@openparachute/agent 0.1.2 → 0.2.2

package/src/backends/stream-json.ts

@@ -0,0 +1,392 @@
+/**
+ * Parse `claude -p --output-format stream-json --verbose` output.
+ *
+ * VERIFIED against claude 2.1.179 (spike). The output is NDJSON — one JSON object
+ * per line — but the stream also carries lines we must tolerate without breaking:
+ * hook output, `rate_limit_event`s, blank lines, and (at the tail of a still-open
+ * pipe) a partial final line. The parser is therefore DEFENSIVE: it parses what it
+ * can, ignores any line that isn't a JSON object, and never throws.
+ *
+ * The event types we key on (others are passed over):
+ *
+ *   { "type": "system", "subtype": "init", "session_id": "...",
+ *     "apiKeySource": "none", "mcp_servers": [...], ... }
+ *
+ *   { "type": "assistant", "message": { "content": [{ "type": "text",
+ *     "text": "..." }], ... }, "session_id": "..." }
+ *
+ *   { "type": "result", "subtype": "success", "is_error": false,
+ *     "result": "<final reply text>", "session_id": "...",
+ *     "usage": {...}, "total_cost_usd": ... }
+ *
+ * The `result` event is authoritative: its `result` field is the final reply and
+ * its `is_error` / `subtype` decide success. We also capture `session_id` from the
+ * FIRST event that carries one (the `init` event arrives before `result`), so a
+ * turn that fails AFTER establishing a session still yields the id for a resume.
+ *
+ * `apiKeySource: "none"` on the init event is the SUBSCRIPTION-auth signal — the
+ * turn ran on the operator's subscription, not a metered API key (design §1 / the
+ * Billing caveat). We surface it so a caller / test can assert it.
+ *
+ * ── Two reading modes ───────────────────────────────────────────────────────────
+ * {@link parseStreamJson} folds a COMPLETE blob into the final {@link ParsedTurn}
+ * (used wherever the whole stdout is already in hand). {@link parseStreamJsonStream}
+ * reads a byte stream INCREMENTALLY, emitting {@link InterimTurnEvent}s — interim
+ * assistant text + which tool the agent is using — as each line arrives, and
+ * returns the same final {@link ParsedTurn} at the end. The streaming view (design
+ * 2026-06-16-channel-architecture-post-programmatic.md, build item #1) drives the
+ * "watch it work" chat UI off those interim events while the durable final-reply
+ * path is unchanged. Both modes share one per-line fold ({@link foldLine}), so the
+ * final-result semantics are identical whichever mode produced them.
+ */
+
+/** A parsed `claude -p` stream-json turn. */
+export interface ParsedTurn {
+  /** The session id (from the first event carrying one — init, else result). */
+  sessionId?: string;
+  /** The final reply text (the `result` event's `result` field). */
+  reply?: string;
+  /**
+   * The `result` event's success verdict. `true` only when a `result` event with
+   * `subtype: "success"` and `is_error: false` was seen. Absent (undefined) when no
+   * `result` event arrived at all (a crashed / truncated turn).
+   */
+  success?: boolean;
+  /** The `result` event's `subtype` (e.g. "success", "error_max_turns"). */
+  subtype?: string;
+  /** The `result` event's `is_error` flag, verbatim. */
+  isError?: boolean;
+  /** `apiKeySource` from the init event ("none" = subscription auth — design §1). */
+  apiKeySource?: string;
+  /** Usage from the result event (token counts), passed through verbatim. */
+  usage?: { input_tokens?: number; output_tokens?: number; [k: string]: unknown };
+  /** `total_cost_usd` from the result event (equivalent-cost, NOT a charge — §1). */
+  totalCostUsd?: number;
+  /**
+   * Any error message the result event carried (some failures put the message in
+   * the `result` field even with `is_error: true`). Best-effort.
+   */
+  errorMessage?: string;
+}
+
+/**
+ * Hard caps on the live-view payload fields. SSE frames must stay SMALL — a tool's
+ * `input` (a Bash command, a long Write body) or a `tool_result` (a file read, a
+ * grep dump) can be arbitrarily large, so both are bounded here. Truncation appends
+ * the {@link TRUNCATION_MARKER} so the consumer can show "…".
+ *
+ * Operator-visibility note: the turn-events SSE this feeds is `agent:read`-gated —
+ * operator-only, owner-operated. Tool inputs/results are INTENTIONALLY visible to the
+ * operator (it's their own agent doing their own work), so there is no redaction here
+ * beyond size-bounding; the only concern is keeping each frame small.
+ */
+export const MAX_TOOL_INPUT_CHARS = 2000;
+export const MAX_TOOL_RESULT_CHARS = 2000;
+const TRUNCATION_MARKER = "…";
+
+/** Truncate `s` to at most `max` chars, appending the marker when it was cut. */
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max) + TRUNCATION_MARKER : s;
+}
+
+/**
+ * An interim progress event surfaced WHILE a turn runs (the streaming view). The
+ * kinds:
+ *  - `text`        — a chunk of the agent's assistant message (each assistant event's
+ *                    text block; chunk-level, NOT token-level — design §1's "chunk-level
+ *                    is fine"). The chat UI appends these into the live in-progress bubble.
+ *  - `tool`        — the agent invoked a tool; `tool` is its name (e.g. "Read", "Bash",
+ *                    an MCP tool). `input` (optional) is the tool_use block's `input`
+ *                    object JSON-stringified + bounded to {@link MAX_TOOL_INPUT_CHARS},
+ *                    so the UI can render an EXPANDABLE "Read {file}" / "Bash <cmd>" view.
+ *  - `tool_result` — a tool finished; `preview` (optional) is a bounded snippet of its
+ *                    output ({@link MAX_TOOL_RESULT_CHARS}), `ok` the success flag
+ *                    (`is_error: false` → `ok: true`), and `tool` (optional) the name
+ *                    of the tool it came from (correlated via the tool_use_id map).
+ *  - `init`        — the turn established a session; carries the `sessionId`. Lets the UI
+ *                    start a fresh live bubble (and a consumer correlate by session id).
+ *
+ * Deliberately small + serializable so it maps 1:1 onto an SSE frame the chat (and,
+ * later, my-vault-ui) subscribes to. The `input` / `preview` fields are ADDITIVE +
+ * optional: an existing consumer that only reads `kind`/`tool`/`text` keeps working,
+ * and one that doesn't know `tool_result` simply ignores the new kind.
+ */
+export type InterimTurnEvent =
+  | { kind: "init"; sessionId: string }
+  | { kind: "text"; text: string }
+  | { kind: "tool"; tool: string; input?: string }
+  | { kind: "tool_result"; tool?: string; ok?: boolean; preview?: string };
+
+interface SystemInitEvent {
+  type: "system";
+  subtype?: string;
+  session_id?: string;
+  apiKeySource?: string;
+}
+interface ResultEvent {
+  type: "result";
+  subtype?: string;
+  is_error?: boolean;
+  result?: string;
+  session_id?: string;
+  usage?: { input_tokens?: number; output_tokens?: number; [k: string]: unknown };
+  total_cost_usd?: number;
+}
+/** One content block of an assistant message — text or a tool invocation. */
+interface AssistantContentBlock {
+  type?: string;
+  /** Present on a `{ type: "text" }` block — a chunk of the assistant's prose. */
+  text?: string;
+  /** Present on a `{ type: "tool_use" }` block — the invoked tool's name. */
+  name?: string;
+  /** Present on a `{ type: "tool_use" }` block — the tool's input arguments. */
+  input?: unknown;
+  /** Present on a `{ type: "tool_use" }` block — correlates with a later tool_result. */
+  id?: string;
+}
+interface AssistantEvent {
+  type: "assistant";
+  message?: { content?: AssistantContentBlock[] };
+  session_id?: string;
+}
+/**
+ * One content block of a USER-role message — claude emits `tool_result` blocks here,
+ * one per completed `tool_use`. `content` is the result payload (a string, or an array
+ * of `{ type: "text", text }` parts), `tool_use_id` links it back to its tool_use, and
+ * `is_error` is the success flag.
+ */
+interface UserContentBlock {
+  type?: string;
+  tool_use_id?: string;
+  is_error?: boolean;
+  /** The result payload — a plain string, or content parts (`{ type, text }`). */
+  content?: unknown;
+}
+interface UserEvent {
+  type: "user";
+  message?: { content?: UserContentBlock[] };
+  session_id?: string;
+}
+
+/**
+ * Flatten a `tool_result` block's `content` into a plain preview string. claude
+ * emits it either as a bare string or as an array of content parts
+ * (`[{ type: "text", text: "…" }, …]`); join the text parts. Returns undefined when
+ * there's nothing renderable.
+ */
+function previewToolResultContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const parts: string[] = [];
+    for (const part of content) {
+      if (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string") {
+        parts.push((part as { text: string }).text);
+      }
+    }
+    return parts.length > 0 ? parts.join("") : undefined;
+  }
+  return undefined;
+}
+interface AnyEvent {
+  type?: string;
+  session_id?: string;
+  [k: string]: unknown;
+}
+
+/**
+ * Fold ONE already-trimmed, non-empty NDJSON line into the running {@link ParsedTurn}
+ * and, when an `onInterim` sink is given, emit the interim events the line carries
+ * (assistant text chunks, tool_use names + inputs, tool_result previews, the
+ * session-establishing init). Shared by the blob parser and the streaming parser so
+ * both have identical final-result semantics. Never throws: a non-`{` line or a
+ * JSON-parse failure (a truncated partial line, hook plain text, any noise) is
+ * silently ignored.
+ *
+ * `toolNames` (when given) is a per-PARSE `tool_use_id → name` map: a `tool_use`
+ * block records its id→name so a later `tool_result` (which carries only the
+ * `tool_use_id`) can be labeled with the tool it came from. The caller owns it (one
+ * per parse) so it persists across lines.
+ */
+function foldLine(
+  line: string,
+  turn: ParsedTurn,
+  onInterim?: (e: InterimTurnEvent) => void,
+  toolNames?: Map<string, string>,
+): void {
+  // Fast reject: NDJSON events are objects. A non-`{` line (hook plain text, a
+  // partial line that got cut mid-token) can't be one — skip without a try/catch.
+  if (line[0] !== "{") return;
+
+  let obj: AnyEvent;
+  try {
+    obj = JSON.parse(line) as AnyEvent;
+  } catch {
+    // A partial/truncated line, or any non-JSON noise — tolerate it.
+    return;
+  }
+  if (!obj || typeof obj !== "object") return;
+
+  // Capture session_id from the FIRST event that has one (init precedes result),
+  // so a turn that errors after init still yields the id for a resume. The first
+  // sighting also drives the interim `init` event (a single per-turn signal the UI
+  // uses to open a fresh live bubble).
+  if (turn.sessionId === undefined && typeof obj.session_id === "string" && obj.session_id) {
+    turn.sessionId = obj.session_id;
+    onInterim?.({ kind: "init", sessionId: obj.session_id });
+  }
+
+  if (obj.type === "system" && (obj as SystemInitEvent).subtype === "init") {
+    const init = obj as SystemInitEvent;
+    if (typeof init.apiKeySource === "string") turn.apiKeySource = init.apiKeySource;
+    return;
+  }
+
+  // ASSISTANT events carry the interim progress: text chunks + tool_use blocks.
+  // These don't affect the final ParsedTurn (the authoritative reply is the result
+  // event's `result`), but they're what the live view renders. Only emitted when a
+  // sink is wired (the blob parser passes none, so this is a no-op there).
+  if (obj.type === "assistant" && onInterim) {
+    const blocks = (obj as AssistantEvent).message?.content;
+    if (Array.isArray(blocks)) {
+      for (const block of blocks) {
+        if (block.type === "text" && typeof block.text === "string" && block.text.length > 0) {
+          onInterim({ kind: "text", text: block.text });
+        } else if (block.type === "tool_use" && typeof block.name === "string" && block.name.length > 0) {
+          // Record id→name so a later tool_result (which only carries the id) can be
+          // labeled with this tool. Best-effort: a result without a recorded id just
+          // omits the `tool` label.
+          if (toolNames && typeof block.id === "string" && block.id) toolNames.set(block.id, block.name);
+          // Stringify + HARD-bound the input so the UI can render an expandable view
+          // (e.g. the Read path, the Bash command). Omit when there's no input or it
+          // can't be stringified (a circular/exotic value — never throw the parse).
+          let input: string | undefined;
+          if (block.input !== undefined) {
+            try {
+              const json = JSON.stringify(block.input);
+              if (typeof json === "string") input = truncate(json, MAX_TOOL_INPUT_CHARS);
+            } catch {
+              // unstringifiable input — drop the field, keep the tool event
+            }
+          }
+          onInterim(input !== undefined ? { kind: "tool", tool: block.name, input } : { kind: "tool", tool: block.name });
+        }
+      }
+    }
+    return;
+  }
+
+  // USER events carry the tool_result blocks (claude reports each completed tool's
+  // output as a tool_result on a user-role message). Emit a bounded `tool_result`
+  // interim event per block, labeled with the originating tool via the id→name map.
+  // Sink-gated like the assistant path (a no-op for the blob parser).
+  if (obj.type === "user" && onInterim) {
+    const blocks = (obj as UserEvent).message?.content;
+    if (Array.isArray(blocks)) {
+      for (const block of blocks) {
+        if (block.type !== "tool_result") continue;
+        const event: { kind: "tool_result"; tool?: string; ok?: boolean; preview?: string } = { kind: "tool_result" };
+        const name = toolNames && typeof block.tool_use_id === "string" ? toolNames.get(block.tool_use_id) : undefined;
+        if (name !== undefined) event.tool = name;
+        if (typeof block.is_error === "boolean") event.ok = block.is_error === false;
+        const preview = previewToolResultContent(block.content);
+        if (preview !== undefined) event.preview = truncate(preview, MAX_TOOL_RESULT_CHARS);
+        onInterim(event);
+      }
+    }
+    return;
+  }
+
+  if (obj.type === "result") {
+    const r = obj as ResultEvent;
+    turn.subtype = typeof r.subtype === "string" ? r.subtype : undefined;
+    turn.isError = r.is_error === true;
+    turn.success = r.subtype === "success" && r.is_error !== true;
+    if (typeof r.result === "string") {
+      // `result` carries the reply on success; on some failures it carries the
+      // error message. Record it as both; the caller picks per success/isError.
+      turn.reply = r.result;
+      if (turn.isError) turn.errorMessage = r.result;
+    }
+    if (r.usage && typeof r.usage === "object") turn.usage = r.usage;
+    if (typeof r.total_cost_usd === "number") turn.totalCostUsd = r.total_cost_usd;
+    // Don't return early after a result so session_id capture stays robust if
+    // ordering ever surprises us — there's only one result event in practice.
+    return;
+  }
+}
+
+/**
+ * Parse a complete stream-json blob (the full stdout of one `claude -p` turn).
+ * Splits on newlines, JSON-parses each non-blank line, and folds the recognized
+ * events into a {@link ParsedTurn}. Lines that aren't a JSON object (hook text, a
+ * trailing partial line, blanks) are silently skipped — robustness is the point.
+ */
+export function parseStreamJson(stdout: string): ParsedTurn {
+  const turn: ParsedTurn = {};
+  // No sink + no toolNames map: foldLine's interim branches (which build/consult the
+  // map) are all gated on `onInterim`, so the blob path needs neither — final-result
+  // semantics are identical with or without them.
+  for (const rawLine of stdout.split("\n")) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    foldLine(line, turn);
+  }
+  return turn;
+}
+
+/**
+ * Parse a stream-json byte stream INCREMENTALLY, emitting {@link InterimTurnEvent}s
+ * via `onInterim` as each complete line arrives, and resolving to the final
+ * {@link ParsedTurn} when the stream ends. This is the streaming-view path (design
+ * build item #1): the same final result `parseStreamJson` would compute from the
+ * whole blob, PLUS live progress.
+ *
+ * Mechanics: decode incrementally (a `TextDecoder` with `{ stream: true }` so a
+ * multi-byte char split across chunks doesn't corrupt), buffer until a newline,
+ * fold each complete line. The trailing partial line (no terminating newline — a
+ * chunk boundary mid-line, or a truncated final line) is folded ONCE at the end:
+ * `foldLine` tolerates a partial that isn't valid JSON, and a complete-but-
+ * unterminated final result line (the pipe closing without a trailing `\n`) is
+ * still parsed. A null stream (no stdout) yields an empty turn with no events.
+ *
+ * The `onInterim` callback must not throw (the daemon's sink swallows dead-stream
+ * errors); a throw here would abort the drain. Best-effort by contract: this is
+ * ADDITIVE live progress — the durable record is the final ParsedTurn the caller
+ * turns into the outbound note.
+ */
+export async function parseStreamJsonStream(
+  stream: ReadableStream<Uint8Array> | null,
+  onInterim: (e: InterimTurnEvent) => void,
+): Promise<ParsedTurn> {
+  const turn: ParsedTurn = {};
+  if (!stream) return turn;
+
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  // Per-parse tool_use_id → name map, so a tool_result can be labeled with its tool.
+  const toolNames = new Map<string, string>();
+  let buf = "";
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      // Drain every COMPLETE line (terminated by \n). Keep the trailing remainder
+      // (a still-incomplete line) in `buf` for the next chunk.
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) !== -1) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (line) foldLine(line, turn, onInterim, toolNames);
+      }
+    }
+    // Flush any multi-byte tail the decoder is holding, then fold the final
+    // unterminated line (a result line the pipe closed without a trailing \n).
+    buf += decoder.decode();
+    const tail = buf.trim();
+    if (tail) foldLine(tail, turn, onInterim, toolNames);
+  } finally {
+    reader.releaseLock();
+  }
+  return turn;
+}

package/src/backends/types.ts

@@ -0,0 +1,223 @@
+/**
+ * The `AgentBackend` seam (design 2026-06-16-pluggable-agent-backend.md).
+ *
+ * A channel agent is "driven" in one of two ways, and the way is a swappable
+ * choice behind ONE interface:
+ *
+ *   - **Interactive** (today's path): an idle interactive `claude` in a tmux pane,
+ *     fed inbound messages by pushing onto a subscribed MCP "development channel."
+ *     `start` = the tmux spawn (`spawnAgent`); `deliver` = a push onto the MCP GET
+ *     stream. This backend carries the whole deaf-on-restart fragility class
+ *     (no-loss high-water-mark + backlog replay #67, per-session restart #68, the
+ *     dev-channels consent-gate auto-confirm #70/#71).
+ *
+ *   - **Programmatic** (this seam's first new implementor — `ProgrammaticBackend`):
+ *     run ONE sandboxed `claude -p` turn per inbound message and capture the reply.
+ *     There is no idle session, so there is nothing to go deaf, nothing to
+ *     reconnect, no backlog to replay, no TUI gate to answer. `deliver` is a direct
+ *     turn into a fresh `claude -p` invocation that resumes the channel's prior
+ *     conversation (`--resume <session_id>`). The daemon turns the returned reply
+ *     into an outbound `#agent/message/outbound` note (the wiring follow-up).
+ *
+ * Everything ABOVE this seam is backend-agnostic: the vault message transport
+ * (`#agent/message/{inbound,outbound}`), the chat UI, the sandbox/isolation
+ * envelope, and the per-channel env/credential injection. Only the
+ * "drive-the-agent" layer differs.
+ *
+ * ── The asymmetric delivery guarantee (design's load-bearing caveat) ────────────
+ * The interactive `deliver` (push onto the MCP GET stream) can SILENTLY fail if
+ * the session is deaf — it is `void` there only because the #67 high-water-mark +
+ * backlog replay catches the gap out-of-band. The programmatic `deliver` is a
+ * direct turn into a fresh invocation, so failure is observable INLINE. To stop the
+ * interactive side's silent-loss footgun leaking into the programmatic contract,
+ * `deliver` returns a {@link DeliverResult} discriminated union — the programmatic
+ * backend reports `{ ok: false, error }` rather than swallowing a failure, and a
+ * future interactive retrofit reports `{ ok: true }` once the push is enqueued
+ * (its real durability staying in the #67 machinery, as today).
+ *
+ * NOTE: this PR defines the contract and ships the PROGRAMMATIC implementor only.
+ * The interactive spawn (`spawnAgent`) is NOT refactored to implement this
+ * interface here — that retrofit is the wiring follow-up. The shape is deliberately
+ * chosen to fit both: `start(spec)` maps to either the tmux spawn or "open a
+ * programmatic session," and `deliver(handle, message)` maps to either a push or a
+ * `claude -p` turn.
+ */
+
+import type { AgentSpec } from "../sandbox/types.ts";
+import type { InterimTurnEvent } from "./stream-json.ts";
+import type { InboundAttachment } from "../transport.ts";
+
+export type { InboundAttachment } from "../transport.ts";
+
+export type { InterimTurnEvent } from "./stream-json.ts";
+
+/**
+ * A sink for interim turn progress (the streaming view, design
+ * 2026-06-16-channel-architecture-post-programmatic.md build item #1). The backend
+ * calls this as a turn runs — assistant text chunks, which tool the agent is using,
+ * the session-establishing init — so the daemon can push live progress to the chat
+ * UI WHILE the turn is in flight. It is ADDITIVE: the durable record is still the
+ * final {@link DeliverResult} the backend returns. Optional on `deliver` — a backend
+ * that can't stream (or a caller that doesn't want live progress) omits it and the
+ * turn behaves exactly as before. MUST NOT throw (a throw would abort the drain);
+ * the daemon's implementation swallows dead-stream errors.
+ */
+export type InterimSink = (event: InterimTurnEvent) => void;
+
+/**
+ * The Claude session UUID for ONE turn, RESOLVED BY THE CALLER (the registry) and
+ * handed to the backend. The daemon owns the session UUID — it lives on the durable
+ * `#agent/thread` note (`metadata.session`), NOT in a backend-private store — so the
+ * caller decides, per turn, whether to CONTINUE a prior conversation or CREATE a new
+ * one, and the backend just runs the turn it's handed:
+ *  - `resume: true`  → `claude --resume <id> -p "…"` — continue a prior conversation
+ *    (single-threaded turn 2+: the thread note already carries a session).
+ *  - `resume: false` → `claude --session-id <id> -p "…"` — CREATE a session with this
+ *    uuid (single-threaded first turn, or every multi-threaded fresh-per-fire turn).
+ * `id` MUST be a valid UUID (the caller mints it via `crypto.randomUUID()` when there
+ * is no prior session to resume).
+ */
+export interface TurnSession {
+  /** The Claude session UUID for this turn. */
+  id: string;
+  /** true → --resume <id> (continue a prior conversation); false → --session-id <id> (create a new one). */
+  resume: boolean;
+}
+
+/**
+ * An opaque handle to a started agent, returned by {@link AgentBackend.start} and
+ * passed back to `deliver`/`stop`/`status`. The only field the seam itself depends
+ * on is `channel` (the wake channel a turn/push targets) + the backend's own
+ * `backend` tag; a backend may carry additional private fields it needs.
+ */
+export interface AgentHandle {
+  /** Which backend produced this handle (so a multiplexer can route correctly). */
+  backend: string;
+  /** The wake channel this agent serves (the first channel of its spec). */
+  channel: string;
+  /** The agent's slug name (the spec name). */
+  name: string;
+  /**
+   * The spec the agent was started from. The programmatic backend reproduces each
+   * turn (its mint scope + sandbox policy) from this; a backend that keeps a
+   * resident process (interactive) need not read it. Optional so the seam doesn't
+   * force every backend to round-trip the whole spec on its handle.
+   */
+  spec?: AgentSpec;
+}
+
+/**
+ * Token usage for one turn, surfaced for observability (cost/quota awareness — the
+ * programmatic backend draws on the operator's subscription quota, a real capacity
+ * limit per the design). Shape mirrors what `claude -p`'s `result` event reports;
+ * fields are optional because a backend may not have them.
+ */
+export interface DeliverUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  /**
+   * The `result` event's `total_cost_usd` — an EQUIVALENT-cost figure on the
+   * subscription path (NOT a charge; the turn draws on the subscription, design §1
+   * of the pluggable-backend doc). Surfaced for observability only.
+   */
+  totalCostUsd?: number;
+}
+
+/**
+ * The result of delivering one message — a discriminated union so a failure is
+ * always observable inline (never a silent drop). On success the daemon turns
+ * `reply` into an outbound `#agent/message/outbound` note (the wiring follow-up).
+ */
+export type DeliverResult =
+  | {
+      ok: true;
+      /** The agent's reply text (the `result` event's `result` field). */
+      reply: string;
+      /**
+       * The session id this turn ran under — captured + persisted so the NEXT turn
+       * resumes the same conversation (`--resume <sessionId>`). Absent if the turn
+       * produced no id (degenerate output).
+       */
+      sessionId?: string;
+      /** Optional token/cost usage for observability. */
+      usage?: DeliverUsage;
+    }
+  | {
+      ok: false;
+      /** A human-readable failure reason (does NOT throw — failure is a value). */
+      error: string;
+      /**
+       * The session id, if one was captured before the failure — so a follow-up
+       * turn can still resume (a turn can fail AFTER establishing a session).
+       */
+      sessionId?: string;
+    };
+
+/** The live/health status of a started agent (for `/health`). */
+export interface AgentStatus {
+  live: boolean;
+}
+
+/**
+ * The pluggable agent-driving seam. A channel chooses a backend; the daemon calls
+ * this interface and stays strategy-agnostic.
+ */
+export interface AgentBackend {
+  /** A stable identifier for the backend kind (e.g. "programmatic", "interactive"). */
+  readonly kind: string;
+
+  /**
+   * Bring an agent up for a channel from its spec. For the programmatic backend
+   * this is lightweight (there is no resident process to launch — and no session to
+   * pre-establish: the session uuid is resolved per turn by the caller and lives on
+   * the durable `#agent/thread` note); for the interactive backend it is the tmux
+   * spawn. Returns an opaque handle the other methods take.
+   */
+  start(spec: AgentSpec): Promise<AgentHandle>;
+
+  /**
+   * Hand the agent one inbound message and get its reply. Returns a
+   * {@link DeliverResult} — a failure is a value (`{ ok: false, error }`), NEVER a
+   * throw, so the caller always learns the outcome inline (the asymmetric-guarantee
+   * fix). The daemon serializes deliveries per channel (one turn at a time).
+   *
+   * `session` is the {@link TurnSession} the CALLER resolved for this turn — the
+   * daemon owns the session UUID (it lives on the durable `#agent/thread` note, not a
+   * backend store), so the caller decides resume-existing (`resume: true` →
+   * `--resume <id>`) vs create-new (`resume: false` → `--session-id <id>`). The
+   * backend just runs the turn with that uuid; it no longer reads or writes any
+   * session store. The captured/echoed id still comes back on the
+   * {@link DeliverResult} (`sessionId`) so the caller can persist it onto the note.
+   *
+   * `onInterim` (optional) is the streaming-view sink: the backend calls it with
+   * interim progress (assistant text chunks + tool_use) AS the turn runs, so the
+   * daemon can render "watch it work" live in the chat UI. ADDITIVE — when omitted,
+   * the turn behaves exactly as before; the final {@link DeliverResult} is the
+   * durable record either way. (Only the programmatic backend streams today; an
+   * interactive retrofit may ignore it.)
+   *
+   * `attachments` (optional, Phase 1) are files attached to the inbound message. The
+   * programmatic backend stages each into the agent's PRIVATE session workspace (under
+   * a safe basename) before the turn and appends a workspace-relative pointer to the
+   * prompt, so the `claude -p` turn can `Read` them. ADDITIVE — absent/empty → no
+   * staging, the turn behaves exactly as before.
+   */
+  deliver(
+    handle: AgentHandle,
+    message: string,
+    session: TurnSession,
+    onInterim?: InterimSink,
+    attachments?: InboundAttachment[],
+  ): Promise<DeliverResult>;
+
+  /**
+   * Tear the agent down. For the programmatic backend this is a NO-OP — there is no
+   * resident process to kill and no session store to clear (the session lives on the
+   * durable `#agent/thread` note), so stop does NOT reset conversation continuity; the
+   * interactive backend kills the tmux session.
+   */
+  stop(handle: AgentHandle): Promise<void>;
+
+  /** Report whether the agent is live (for `/health`). */
+  status(handle: AgentHandle): Promise<AgentStatus>;
+}