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
- Start / Resume
startAttempt/followupAttemptresolve 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.queued→attempt.started→attempt.status.changedupdates.attempt.log.appended,attempt.conversation.appended,attempt.session.recordedfor telemetry/UI.
- Worktree creation calls
createWorktree(..., { projectId, attemptId })which raisesworktree.created.
- Completion
- Runner emits
attempt.completedwith final status. Git auto-commit is delegated viaattempt.autocommit.requested(handled by the git listener). - On abort,
attempt.stoppedfires and the status transitions tostopping/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_pathis explicitly set toNULLso completed Attempts can remain in the database without pointing at a deleted directory on disk.
- Runner emits
- Git Helpers
- Attempt routes proxy to the git service (
commitAtPath, etc.) with metadata so those helpers emitgit.*events automatically.
- Attempt routes proxy to the git service (
- Editor
/attempts/:id/open-editoremitseditor.open.requested/succeeded/failedand returns diagnostics.
Key Entry Points
service.ts: attempt lifecycle logic and event emission, includinglistConversationItemsPaginatedfor paginated message retrieval andresetAttemptfor 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 forattempt.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.