Codewalkers/docs/agent.md

Agent Module

src/agent/ — Agent lifecycle management, output parsing, multi-provider support, and account failover.

File Inventory

File	Purpose
types.ts	Core types: AgentInfo, AgentManager interface, SpawnOptions, StreamEvent
manager.ts	MultiProviderAgentManager — main orchestrator class
process-manager.ts	AgentProcessManager — worktree creation, command building, detached spawn
output-handler.ts	OutputHandler — JSONL stream parsing, completion detection, proposal creation
file-tailer.ts	FileTailer — watches output files, emits line events
file-io.ts	Input/output file I/O: frontmatter writing, signal.json reading, tiptap conversion
markdown-to-tiptap.ts	Markdown to Tiptap JSON conversion using MarkdownManager
index.ts	Public exports, ClaudeAgentManager deprecated alias

Sub-modules

Directory	Purpose
providers/	Provider registry, presets (7 providers), config types
providers/parsers/	Provider-specific output parsers (Claude JSONL, generic line)
accounts/	Account discovery, config dir setup, credential management, usage API
credentials/	AccountCredentialManager — credential injection per account
lifecycle/	LifecycleController — retry policy, signal recovery, missing signal instructions
prompts/	Mode-specific prompt builders (execute, discuss, breakdown, decompose, refine)

Key Flows

Spawning an Agent

1. tRPC procedure calls agentManager.spawn(options)
2. Manager generates alias (adjective-animal), creates DB record
3. AgentProcessManager.createWorktree() — creates git worktree at .cw-worktrees/agent/<alias>/
4. file-io.writeInputFiles() — writes .cw/input/ with initiative, pages, phase, task as frontmatter
5. Provider config builds spawn command via buildSpawnCommand()
6. spawnDetached() — launches detached child process with file output redirection
7. FileTailer watches output file, fires onEvent and onRawContent callbacks
8. OutputHandler.handleStreamEvent() processes each JSONL line
9. DB record updated with PID, output file path, session ID
10. agent:spawned event emitted

Completion Detection

1. FileTailer detects process exit
2. OutputHandler.handleCompletion() triggered
3. Primary path: Reads .cw/output/signal.json from agent worktree
4. Signal contains { status: "done"|"questions"|"error", result?, questions?, error? }
5. Agent DB status updated accordingly (idle, waiting_for_input, crashed)
6. For done: proposals created from structured output; agent:stopped emitted
7. For questions: parsed and stored as pendingQuestions; agent:waiting emitted
8. Fallback: If signal.json missing, lifecycle controller retries with instruction injection

Account Failover

1. On usage-limit error, markAccountExhausted(id, until) called
2. findNextAvailable(provider) returns least-recently-used non-exhausted account
3. Agent re-spawned with new account's credentials
4. agent:account_switched event emitted

Resume Flow

1. tRPC resumeAgent called with answers: Record<string, string>
2. Manager looks up agent's session ID and provider config
3. buildResumeCommand() creates resume command with session flag
4. formatAnswersAsPrompt(answers) converts answers to prompt text
5. New detached process spawned, same worktree, incremented session number

Provider Configuration

Providers defined in providers/presets.ts:

Provider	Command	Resume	Prompt Mode
claude	claude	--resume <id>	native (-p)
claude-code	claude	--resume <id>	native
codex	codex	none	flag (--prompt)
aider	aider	none	flag (--message)
cline	cline	none	flag
continue	continue	none	flag
cursor-agent	cursor	none	flag

Each provider config specifies: command, args, resumeStyle, promptMode, structuredOutput, sessionId extraction, nonInteractive options.

Output Parsing

The OutputHandler processes JSONL streams from Claude CLI:

• text_delta events → accumulated as text output, emitted via agent:output
• init event → session ID extracted
• result event → final result with structured data
• Signal file (signal.json) → authoritative completion status

For providers without structured output, the generic line parser accumulates raw text.

Credential Management

AccountCredentialManager in credentials/ handles OAuth token lifecycle:

• read() — extracts claudeAiOauth from .credentials.json. Only accessToken is required; refreshToken and expiresAt may be null (setup tokens).
• isExpired() — returns false when expiresAt is null (setup tokens never "expire" from our perspective).
• ensureValid() — if expired and refreshToken exists, refreshes. If expired with no refreshToken, returns invalid with error.

Setup Tokens

Setup tokens (from claude setup-token) are long-lived OAuth access tokens with no refresh token or expiry. Register via:

cw account add --token <token> --email user@example.com

Stored as credentials: {"claudeAiOauth":{"accessToken":"<token>"}} and configJson: {"hasCompletedOnboarding":true}.

Log Chunks

Agent output is persisted to agent_log_chunks table:

• onRawContent callback fires for every output chunk
• Fire-and-forget DB insert (no FK to agents — survives deletion)
• Session tracking: spawn=1, resume=previousMax+1
• Read path concatenates all sessions for full output history