# Claude Agent SDK backend + clean-room PostgresSessionStore (#9)

**Status:** in progress (started 2026-06-01)
**Source:** `boocode_code_review_v2.md` §1 #9, §5h/§5i (happy + SDK `.d.ts`). Decision §6.2: lean SDK.
**SDK:** `@anthropic-ai/claude-agent-sdk@0.3.159` (installed, Commercial Terms — runtime dep OK, code
reference-only; the store is **clean-room** from the real interface, not vendored).

Replace BooCoder's one-shot PTY claude dispatch with a warm, resumable Claude-SDK backend. Two parts:
the clean-room session store (fully testable here) and the backend + wiring (live pump needs a host
smoke against real `claude`).

## Ground-truth SDK API (from the installed `sdk.d.ts`)
- `query({ prompt: string | AsyncIterable<SDKUserMessage>, options?: Options }): Query` where
  `Query extends AsyncGenerator<SDKMessage, void>`.
- `Options`: `sessionStore?: SessionStore`, `resume?: string`, `model?`, `cwd?`,
  `pathToClaudeCodeExecutable?`, `canUseTool?`, `permissionMode?`, `env?`, `allowedTools?`.
- `SessionStore = { append(key, entries): Promise<void>; load(key): Promise<SessionStoreEntry[]|null>;
  listSessions?(projectKey): Promise<{sessionId,mtime}[]>; delete?(key): Promise<void>;
  listSubkeys?({projectKey,sessionId}): Promise<string[]> }`.
- `SessionKey = { projectKey: string; sessionId: string; subpath?: string }` (undefined subpath = main
  transcript; empty string invalid — store maps undefined→'' internally).
- `SessionStoreEntry = { type: string; uuid?: string; timestamp?: string; [k]: unknown }` (opaque JSONL).
- Messages: `SDKSystemMessage{subtype:'init'}` carries `session_id` (+ model/tools); `SDKResultMessage`
  (success/error) ends a turn with `result`, `usage`, `total_cost_usd`; `SDKPartialAssistantMessage` /
  `SDKAssistantMessage` carry text/thinking/tool blocks.

## Part 1 — Clean-room PostgresSessionStore (testable now)
- Schema (`apps/coder/src/schema.sql`): a generic append-only entry table
  `claude_session_entries(id BIGSERIAL PK, project_key TEXT, session_id TEXT, subpath TEXT DEFAULT '',
  entry JSONB, created_at TIMESTAMPTZ DEFAULT clock_timestamp())` + index `(project_key, session_id,
  subpath, id)`. (The store is generic per the SDK's key; the chat↔session ownership lives in
  `agent_sessions`, not here.)
- `apps/coder/src/services/backends/claude-session-store.ts`: `PostgresSessionStore` implementing the
  real `SessionStore` type over `Sql`. `append` = ordered multi-INSERT (id = order); `load` = SELECT
  ORDER BY id → array or null; `listSessions` = group main-transcript rows, mtime = max(created_at) ms;
  `delete` = scoped delete (subpath given → that subpath; omitted → whole session); `listSubkeys` =
  DISTINCT non-'' subpaths. Pure SQL, no SDK import needed beyond the `SessionStore` type.
- Tests `__tests__/claude-session-store.test.ts` (DB-opt-in, mirror `checkpoints.test.ts`): append→load
  round-trip + order, null on unseen key, subpath isolation (main vs subagent), listSessions mtime,
  delete scoping, listSubkeys.

## Part 2 — ClaudeSdkBackend + wiring (live pump needs host smoke)
- `agent_sessions.backend` CHECK adds `'claude_sdk'`.
- `apps/coder/src/services/backends/claude-sdk.ts`: a `ClaudeSdkBackend` implementing `AgentBackend`
  (mirror `warm-acp.ts`/`opencode-server.ts`). `ensureSession` resolves the resume id from
  `agent_sessions(chat_id,'claude').agent_session_id`; `prompt` drives one persistent `query()` in
  streaming-input mode (a pushable `AsyncIterable<SDKUserMessage>` fed per turn) with
  `{ sessionStore, resume, model, cwd: worktreePath, pathToClaudeCodeExecutable: installPath }`,
  reads the `AsyncGenerator<SDKMessage>` until `result`, captures `session_id` from the `init` message
  and persists it to `agent_sessions`. A pure `mapSdkMessage(msg): AgentEvent[]` (unit-tested) maps
  partial/assistant/tool/thinking → the existing `AgentEvent` union; `result.usage`/`total_cost_usd`
  accumulate onto `agent_sessions` (like opencode U.6). `isBusy`/`closeSession`/crash mirror the ACP
  backend.
- Routing: add `claude` to the warm path (`warm-acp-routing.ts` or a sibling `shouldUseClaudeSdk`),
  with the existing PTY `runExternalAgent` kept as the **fallback** (session-less creators + if the SDK
  backend fails to start). Provider registry: claude stays selectable; transport reflects the SDK path.
- Frames + persistence identical to the warm-ACP path (`persistExternalAgentTurn`, broker frames).

## Verify
- Part 1: `pnpm -C apps/coder test` + DB-opt-in store tests against dev postgres; build clean.
- Part 2: `pnpm -C apps/coder build` + `npx tsc -p apps/coder/tsconfig.json --noEmit` (typechecks
  against the REAL SDK types) + pure-mapper unit tests. **Live pump + resume across turns: host smoke
  against real `claude` (auth required) — cannot run from the dev container.**

## Open flags
- SDK peer-deps want `zod@^4`; workspace is `zod@3.25.76` (installed with a warning) — watch at runtime.
- `pathToClaudeCodeExecutable` from `available_agents.install_path`; the SDK spawns the same `claude`
  binary the PTY path uses. ANTHROPIC auth/env must reach the child (host concern).