@koda-sl/baker-bridge 0.35.2 → 0.37.0-dev.c223fbd9

package/README.md

@@ -1,6 +1,9 @@
 # @koda-sl/baker-bridge
 
-HTTP server wrapping the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) with WebSocket, SSE streaming, and async endpoints. Designed for running Claude Code as a headless agent with real-time bidirectional communication and Convex callback relay.
+HTTP server wrapping the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk).
+Runs inside a sandbox, persists every chat event directly to Convex, and exposes
+HTTP endpoints for dispatch / abort / answer-question. The dashboard subscribes
+to Convex realtime — there is no chat WebSocket.
 
 ## Installation
 
@@ -33,9 +36,10 @@ await server.start();
 
 | Variable | Description |
 |---|---|
-| `AUTH_TOKEN` | Bearer token for authenticating requests |
-| `BAKER_CONVEX_SITE_URL` | Convex site URL for callback relay (e.g. `https://your-deployment.convex.site`) |
+| `AUTH_TOKEN` | Bearer token for `/message/*` and `/answer-question` |
+| `BAKER_CONVEX_SITE_URL` | Convex site URL for chat persistence (e.g. `https://your-deployment.convex.site`) |
 | `BAKER_API_KEY` | API key for Convex callbacks (`bk_...`) |
+| `INTERNAL_SECRET_KEY` | AES key for encrypting flow `_data.json` config at rest |
 | `ANTHROPIC_API_KEY` | Anthropic API key (required by the Agent SDK) |
 
 All variables are validated at startup via `@t3-oss/env-core` + `zod`.
@@ -45,60 +49,61 @@ All variables are validated at startup via `@t3-oss/env-core` + `zod`.
 | Method | Path | Auth | Description |
 |--------|------|------|-------------|
 | `GET` | `/health` | None | Health check — returns `{ status, projectDir }` |
-| `GET` | `/company` | None | Return COMPANY.md as JSON `{ content, title }` |
-| `GET` | `/brand` | None | Return BRAND.md as JSON `{ content, title }` |
-| `GET` | `/knowledge/:collection/:entry` | None | Return knowledge entry as JSON `{ content, title }` |
+| `GET` | `/commands` | None | List available slash commands (cached 5m) |
+| `GET` | `/company` | None | Return COMPANY.md as `{ content, title }` |
+| `GET` | `/brand` | None | Return BRAND.md as `{ content, title }` |
+| `GET` | `/knowledge/:collection/:entry` | None | Return knowledge entry as `{ content, title }` |
 | `GET` | `/documents/:slug` | None | Serve document binary (pdf, pptx, docx, xlsx) |
 | `GET` | `/flows/:slug` | None | Read flow `_data.json` (decrypted) |
 | `PUT` | `/flows/:slug` | None | Write flow `_data.json` (encrypts at rest) |
-| `GET` | `/ws` | Query param `?token=` | WebSocket — persistent bidirectional chat |
-| `POST` | `/message/async` | Bearer token | Fire-and-forget with Convex callback |
-| `POST` | `/answer-question` | Bearer token | Resolve a pending `AskUserQuestion` tool call |
+| `POST` | `/message/async` | Bearer token | Dispatch a chat turn — fire-and-forget, 202 immediately |
+| `POST` | `/message/abort` | Bearer token | Abort a running query — kills the SDK iterator |
+| `POST` | `/answer-question` | Bearer token | Resolve a pending `AskUserQuestion` |
 
-## WebSocket Protocol
+## Chat flow
 
-Connect to `/ws?token=<AUTH_TOKEN>` for real-time bidirectional communication.
-
-### Client to Server
-
-**Chat message:**
-
-```json
-{
-  "type": "chat",
-  "threadId": "thread_abc123",
-  "content": "Build a landing page for our new product",
-  "attachments": [
-    { "url": "https://...", "contentType": "image/png", "filename": "mockup.png" }
-  ]
-}
 ```
-
-**Answer a pending question:**
-
-```json
-{
-  "type": "answer",
-  "threadId": "thread_abc123",
-  "toolUseId": "tool_xyz",
-  "answers": { "question_key": "user response" }
-}
+Convex action ──POST /message/async──▶ Bridge AgentSession
+                                          │
+                                          ▼
+                                    SDK query() iterator
+                                          │
+              ┌───────────────────────────┼───────────────────────────┐
+              ▼                           ▼                           ▼
+    /api/chat/stream            /api/chat/event             /api/chat/complete
+    (throttled ~50ms             (assistant events,          (final cost / status)
+     text + tool list,           idempotent on uuid)
+     replaces preview)
+                                          │
+                                          ▼
+                                  Convex (single source
+                                   of truth — UI reads
+                                   via realtime query)
 ```
 
-### Server to Client
-
-The server sends Claude Agent SDK events as they stream:
-
-- `{ type: "assistant", data: ... }` — assistant message chunks
-- `{ type: "tool_use", data: ... }` — tool invocations
-- `{ type: "input_request", toolUseId, questions }` — agent needs user input
-- `{ type: "result", costUsd, isError, errors? }` — turn complete
-
-All non-streaming events are also relayed to Convex via `POST /api/chat/event`.
-
-## Async Endpoint
-
-For server-to-server dispatch where you don't need real-time streaming. Returns `202 Accepted` immediately and processes in the background. Results are delivered via Convex callbacks.
+- **Live preview** is throttled to ~50ms — the bridge buffers text deltas and
+  in-flight tool starts and POSTs them to `/api/chat/stream`. The Convex
+  mutation overwrites `thread.streamingState`. The UI reactively re-renders.
+- **Persisted messages** go to `/api/chat/event` with the SDK's `event.uuid`
+  for idempotent insert. The mutation also clears `streamingState` inline so
+  the UI snaps from preview to persisted text without a flicker.
+- **Stop button** flips the thread to `cancelled` via Convex first (UI is
+  freed immediately) and best-effort POSTs `/message/abort` to kill the SDK.
+- **AskUserQuestion** posts `/api/chat/input-request` and blocks until the
+  dashboard answers via Convex action → bridge `/answer-question`.
+
+## Resilience
+
+- All Convex POSTs retry 3× with exponential backoff (1s, 2s, 4s).
+- Persistent failures of `/api/chat/event` and `/api/chat/complete` are
+  appended to `~/.baker/relay-errors.jsonl` for post-mortem.
+- The SDK iterator is wrapped in a 5 min watchdog: if no event arrives for
+  that long, the run is aborted and the thread is marked errored.
+- The session registry evicts entries idle for >24h to bound memory.
+- A new chat that arrives while a previous one is still running aborts the
+  previous run with a 30s timeout cap — a hung run cannot block the next message.
+
+## Sending dispatch by hand
 
 ```bash
 curl -X POST http://localhost:3000/message/async \
@@ -107,18 +112,19 @@ curl -X POST http://localhost:3000/message/async \
   -d '{"threadId": "thread_abc123", "prompt": "Analyze the campaign performance"}'
 ```
 
-On completion, the bridge calls:
-- `POST /api/chat/event` — each SDK event (excluding stream events)
-- `POST /api/chat/complete` — final callback with `{ threadId, isError, costUsd, errors? }`
-- `POST /api/chat/input-request` — sets the thread to `awaiting_input` when the agent calls `AskUserQuestion`
-- `POST /api/chat/input-resolved` — returns the thread to `streaming` after the user answers
+The bridge processes in the background and writes to Convex; nothing is
+returned in the dispatch response besides 202.
 
 ## Architecture
 
-- **One session per thread** — `getOrCreateSession(threadId)` ensures all messages on the same thread share an `AgentSession`, whether they arrive via WebSocket or the async endpoint.
-- **Multi-turn via resume** — the first message creates a fresh `query()`. Subsequent messages resume with the `sessionId` so conversation context carries over.
-- **Attachment handling** — file URLs are downloaded to `/tmp/attachments` and appended to the prompt so the agent can use its `Read` tool to view them.
-- **Convex relay** — all SDK events (except `stream_event`) are posted to the Convex backend with exponential backoff retry (3 attempts).
+- **One session per thread** — `getOrCreateSession(threadId)` ensures every
+  message on the same thread shares an `AgentSession`. Multi-turn context is
+  preserved across bridge restarts via `~/.baker/sessions/<threadId>.json`.
+- **Run-token cancellation** — each call to `sendAndStream` mints a Symbol; if
+  the symbol changes (abort, replace) the run cleans up and exits without
+  writing further. No globally-mutable abort flag.
+- **Single-writer to Convex** — there is no parallel WebSocket. Convex is the
+  only place the UI reads state from, eliminating dual-write races.
 
 ## Development
 
@@ -139,56 +145,30 @@ pnpm --filter @koda-sl/baker-bridge unlink:local  # Remove link, restore registr
 
 ### Auto-publish (CI)
 
-Pushing to `main` with changes in `packages/bridge/` triggers the GitHub Actions workflow, which publishes to npm with the `latest` tag by default. To publish a pre-release, use the workflow dispatch with `npm_tag: next`.
+Pushing to `main` with changes in `packages/bridge/` triggers the GitHub Actions
+workflow, which publishes to npm with the `latest` tag by default. To publish a
+pre-release, use the workflow dispatch with `npm_tag: next`.
 
 ### Manual publish
 
 From the monorepo root:
 
 ```bash
-# Publish as @latest (production)
-./scripts/publish-package.sh bridge
-
-# Publish as @next (pre-release)
-./scripts/publish-package.sh bridge next
+./scripts/publish-package.sh bridge          # @latest
+./scripts/publish-package.sh bridge next     # @next pre-release
 ```
 
-The script checks for duplicate versions, builds, and publishes. Bump the version in `package.json` before publishing.
+Bump `version` in `package.json` (and the `VERSION` const in `src/cli.ts`)
+before publishing.
 
 ### Testing a pre-release in sandboxes
 
-When you publish a `@next` version, sandboxes won't use it automatically — they use the version baked into the template. To override:
-
 ```bash
-# Point sandboxes to the pre-release version
 npx convex env set BAKER_BRIDGE_VERSION <version>
-```
-
-The sandbox startup (`nodeActions.ts`) checks this env var and runs `npm install -g @koda-sl/baker-bridge@<version>` before starting. This is optional — when unset, the default template version is used.
-
-After testing, always clean up to avoid running pre-release in production:
-
-```bash
+# … test …
 npx convex env remove BAKER_BRIDGE_VERSION
 ```
 
-## Debugging relay failures
-
-When `postToConvex` exhausts all retries, the error is appended to `~/.baker/relay-errors.jsonl` on the sandbox filesystem. Each line is a JSON object:
-
-```jsonl
-{"timestamp":"2026-04-24T15:19:55.123Z","path":"/api/chat/complete","threadId":"abc123","status":502,"responseBody":"Bad Gateway"}
-{"timestamp":"2026-04-24T15:20:01.456Z","path":"/api/chat/event","threadId":"abc123","error":"fetch failed"}
-```
-
-To inspect on a running sandbox:
-
-```bash
-cat ~/.baker/relay-errors.jsonl
-```
-
-If a thread is stuck in `"streaming"`, this file tells you whether the bridge failed to reach Convex (and why — auth, network, HTTP status).
-
 ## Requirements
 
 - Node.js 18+

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 declare const args: string[];
 declare const command: string;
-declare const VERSION = "0.34.0";
+declare const VERSION = "0.37.0";
 declare function printUsage(): void;
 declare function main(): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -2,7 +2,7 @@
 "use strict";
 const args = process.argv.slice(2);
 const command = args[0];
-const VERSION = "0.34.0";
+const VERSION = "0.37.0";
 function printUsage() {
     console.error("Usage: baker-bridge <command>");
     console.error("");

package/dist/hono/agent.d.ts

@@ -1,28 +1,37 @@
-import type { SDKMessage, SlashCommand } from "@anthropic-ai/claude-agent-sdk";
+import type { SlashCommand } from "@anthropic-ai/claude-agent-sdk";
 import type { ChatAttachment } from "./types.ts";
-interface StreamCallbacks {
-    onMessage: (msg: SDKMessage) => void;
-    onInputRequest: (toolUseId: string, questions: unknown) => void;
-    onComplete: (costUsd: number, isError: boolean, errors?: string[], model?: string) => void;
-    onModelSelected?: (model: string) => void;
-    onRouterSample?: (model: string, messages: Array<{
-        role: string;
-        content: string;
-    }>) => void;
-}
 declare class AgentSession {
     readonly threadId: string;
     private sessionId;
     private pendingQuestions;
     private handlerCtx;
     private options;
+    /** Identity token for the currently-running stream. abort() nulls this; if a
+     *  later check sees a different value, the run knows it was abandoned. This
+     *  replaces a global `aborted` flag whose reset-on-entry was racy. */
+    private activeRun;
+    private activeAbort;
+    private streamingPromise;
+    private replacingStream;
+    private currentTurnTools;
+    private model;
+    lastUsedAt: number;
     constructor(threadId: string);
-    /** Restore a previously persisted session ID (e.g. loaded from disk after restart). */
+    /** Cancel any in-flight run. The next status check inside runStream will trip. */
+    abort(): void;
     setSessionId(id: string): void;
-    sendAndStream(content: string, callbacks: StreamCallbacks, attachments?: ChatAttachment[]): Promise<void>;
     resolveQuestion(toolUseId: string, answers: Record<string, string>): boolean;
+    sendAndStream(content: string, attachments?: ChatAttachment[]): Promise<void>;
+    private runStream;
+    private handleStreamEvent;
+    private handleContentBlockStart;
+    private handleMessage;
+    private preparePrompt;
+    private completeWithCancel;
+    private completeWithError;
 }
-export declare function getSlashCommands(): Promise<SlashCommand[]>;
 export declare function getOrCreateSession(threadId: string): Promise<AgentSession>;
+export declare function abortSession(threadId: string): boolean;
+export declare function getSlashCommands(): Promise<SlashCommand[]>;
 export {};
 //# sourceMappingURL=agent.d.ts.map

package/dist/hono/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/hono/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,UAAU,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAMxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAcjD,UAAU,eAAe;IACvB,SAAS,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAChE,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3F,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAC;CAC9F;AAUD,cAAM,YAAY;IAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,gBAAgB,CAAsC;IAC9D,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,OAAO,CAAU;gBAEb,QAAQ,EAAE,MAAM;IAM5B,uFAAuF;IACvF,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqD/G,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;CAS7E;AAyHD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAuBhE;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAahF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/hono/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAgBxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAuCjD,cAAM,YAAY;IAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,gBAAgB,CAAsC;IAC9D,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,OAAO,CAAU;IAEzB;;0EAEsE;IACtE,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,KAAK,CAAqB;IAClC,UAAU,EAAE,MAAM,CAAc;gBAEpB,QAAQ,EAAE,MAAM;IAM5B,kFAAkF;IAClF,KAAK,IAAI,IAAI;IAkBb,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI9B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO;IAUtE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YA8BrE,SAAS;IAgFvB,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,uBAAuB;YAiBjB,aAAa;YAiBb,aAAa;YAoBb,kBAAkB;YAYlB,iBAAiB;CAehC;AAqFD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAahF;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOtD;AAWD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAuBhE"}