Skip to main content

Attempts Module

Purpose

  • Manage the lifecycle of agent attempts (create, resume, stop) against project cards.
  • Persist attempt metadata, logs, and conversation history in SQLite through Drizzle ORM.
  • Coordinate worktree provisioning and teardown while remaining decoupled through the event bus.

Data & Event Flow

  1. Start / Resume
    • startAttempt / followupAttempt resolve project settings, ensure worktree paths, and enqueue the run.
    • The async runner streams structured JSONL from the agent. Each message is persisted and emitted as an event:
      • attempt.queuedattempt.startedattempt.status.changed updates.
      • attempt.log.appended, attempt.conversation.appended, attempt.session.recorded for telemetry/UI.
    • Worktree creation calls createWorktree(..., { projectId, attemptId }) which raises worktree.created.
  2. Completion
    • Runner emits attempt.completed with final status. Git auto-commit is delegated via attempt.autocommit.requested (handled by the git listener).
    • On abort, attempt.stopped fires and the status transitions to stopping/stopped.
    • When a card is moved to Done and its attempt is finished, a tasks listener tears down the attempt worktree and deletes its branch.
    • As part of this cleanup, attempts.worktree_path is explicitly set to NULL so completed Attempts can remain in the database without pointing at a deleted directory on disk.
  3. Git Helpers
    • Attempt routes proxy to the git service (commitAtPath, etc.) with metadata so those helpers emit git.* events automatically.
  4. Editor
    • /attempts/:id/open-editor emits editor.open.requested/succeeded/failed and returns diagnostics.

Key Entry Points

  • service.ts: attempt lifecycle logic and event emission, including listConversationItemsPaginated for paginated message retrieval and resetAttempt for clearing conversation history and logs.
  • routes.ts: HTTP router wiring for attempts, git actions, follow-ups, editor launch, paginated message endpoints, and reset endpoint.
  • attempts.handlers.ts: attempt lifecycle/log handlers (details, stop, logs, follow-ups, automation, reset, and paginated messages).
  • attempts.editor.ts: editor launch handler for /attempts/:id/open-editor.
  • attempts.git.ts: git helpers scoped to attempt worktrees (status, file, commit, push, merge).
  • attempts.pr.ts: pull request helper handlers for attempt branches.
  • autocommit.ts: shared handler invoked by git listener for attempt.autocommit.requested.

Open Tasks

  • Add unit/integration tests covering attempt events (success, failure, stop).
  • Extend stop handling to cancel background processes and surface status in UI.
  • Consider resumable state caching for long-running agents.

title: Server: Attempts module