@agent-compose/sdk 0.5.1 → 0.5.2

package/src/pause/state-dir.ts

@@ -0,0 +1,262 @@
+/**
+ * Pause state directory — durable per-agent / per-checkpoint / per-pause
+ * blobs the sandbox snapshot carries across pause-resume.
+ *
+ * Layout under `/tmp/wf/state/`:
+ *
+ *   agent-<agentInstanceId>.json     ← agent loop state (iteration, messages, processor cursor)
+ *   runtime-<agentInstanceId>.json   ← runtime-private blob (opaque to the loop)
+ *   checkpoints/<name>.json          ← user `ctx.checkpoint(name, fn)` memoised values
+ *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
+ *
+ * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`
+ * cannot capture partial state. Most read helpers return `null` on missing-file
+ * rather than throwing — callers branch on presence to distinguish "first
+ * run" from "post-resume restore". User checkpoints use an explicit
+ * found/value result because `null` is a valid memoised value.
+ *
+ * The state-dir layout is treated as wire protocol between the SDK
+ * runner (writer) and the SDK on the next subprocess invocation (reader).
+ * Changing a filename or shape is a breaking change to pause resumption
+ * for any in-flight paused workflow. See ADR-0006.
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Root of the pause state-dir. Defaults to `/tmp/wf/state` — the
+ *  canonical location inside the sandbox. Tests and non-`/tmp`-writable
+ *  environments can override via `AGENT_COMPOSE_STATE_DIR`.
+ *
+ *  Read at CALL TIME, not module load. An earlier draft cached it on
+ *  first import, but that turned out to be test-ordering-fragile: once
+ *  any test imported state-dir (directly or transitively via
+ *  agent-loop) the path got locked to whatever env was set at that
+ *  instant, and a later test setting `AGENT_COMPOSE_STATE_DIR` would
+ *  silently write to the cached path instead. Reading the env each
+ *  call costs nothing measurable next to the fsync. */
+export function getStateDir(): string {
+  return process.env.AGENT_COMPOSE_STATE_DIR ?? "/tmp/wf/state";
+}
+
+const checkpointsDir = () => join(getStateDir(), "checkpoints");
+const pausesDir      = () => join(getStateDir(), "pauses");
+
+const agentStatePath   = (agentInstanceId: string) => join(getStateDir(), `agent-${agentInstanceId}.json`);
+const runtimeStatePath = (agentInstanceId: string) => join(getStateDir(), `runtime-${agentInstanceId}.json`);
+const checkpointPath   = (name: string)            => join(checkpointsDir(), `${name}.json`);
+const pausePath        = (pauseId: string)         => join(pausesDir(), `${pauseId}.json`);
+
+/** `name` is interpolated into a filename; reject anything outside a
+ *  conservative slug. Prevents a workflow author from writing
+ *  `ctx.checkpoint("../../etc/passwd", fn)` and escaping the dir.
+ *
+ *  First character must be alphanumeric or `_` so dotfile names (`.foo`)
+ *  and parent-directory tokens (`.`, `..`) are rejected regardless of
+ *  any future change to the `.json` suffix invariant. Empty strings are
+ *  rejected because the first character is required.
+ *
+ *  Allowed: `agent-1`, `expensive_load`, `p.42`, `decision-v2`.
+ *  Rejected: ``, `.`, `..`, `.hidden`, `-leading`, `a/b`, `a\b`. */
+const NAME_RE = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/;
+
+function assertSafeName(label: string, name: string): void {
+  if (!NAME_RE.test(name)) {
+    throw new Error(`${label} name must match ${NAME_RE} (got ${JSON.stringify(name)})`);
+  }
+}
+
+export function assertSafeCheckpointName(name: string): void {
+  assertSafeName("checkpoint", name);
+}
+
+/** Ensure the state-dir and its subdirectories exist. Idempotent —
+ *  re-running is a no-op. Called lazily by every write entry-point so
+ *  callers don't need to remember to call it. */
+async function ensureDirs(): Promise<void> {
+  await fs.mkdir(checkpointsDir(), { recursive: true });
+  await fs.mkdir(pausesDir(),      { recursive: true });
+}
+
+/** Atomic write: temp file in the same directory, fsync to flush
+ *  contents to disk, then rename onto the target. POSIX rename is
+ *  atomic when source and target are on the same filesystem (always
+ *  true here — same dir), so a snapshot in progress sees either the
+ *  pre-write file or the fully-written file, never a partial. */
+async function atomicWriteJSON(path: string, value: unknown): Promise<void> {
+  await ensureDirs();
+  const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
+  const payload = JSON.stringify(value);
+  if (payload === undefined) {
+    throw new Error("pause state values must be JSON-serialisable");
+  }
+  const handle = await fs.open(tmp, "w");
+  try {
+    await handle.writeFile(payload, { encoding: "utf8" });
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await fs.rename(tmp, path);
+}
+
+/** Read + JSON-parse. Returns `null` when the file doesn't exist —
+ *  the absence IS the signal "no state yet".
+ *  Any other error (permission, JSON syntax, partial write) bubbles
+ *  so the runner fails loudly rather than silently re-running. */
+async function readJSON<T = unknown>(path: string): Promise<T | null> {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export type CheckpointRead<T> =
+  | { found: true; value: T }
+  | { found: false };
+
+async function readJSONWithPresence<T = unknown>(path: string): Promise<CheckpointRead<T>> {
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    return { found: true, value: JSON.parse(raw) as T };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { found: false };
+    throw err;
+  }
+}
+
+// ── Agent loop state ────────────────────────────────────────────────────────
+//
+// `agentInstanceId` flows from workflow-author code (`agent({ agentId })`)
+// and from the step-mode derivation in `run-agent.ts`. Both are
+// validated here so a malformed id can't escape the state-dir even
+// through the agent / runtime entry points.
+
+export async function readAgentState<T = unknown>(agentInstanceId: string): Promise<T | null> {
+  assertSafeName("agent", agentInstanceId);
+  return readJSON<T>(agentStatePath(agentInstanceId));
+}
+
+export async function writeAgentState(agentInstanceId: string, state: unknown): Promise<void> {
+  assertSafeName("agent", agentInstanceId);
+  await atomicWriteJSON(agentStatePath(agentInstanceId), state);
+}
+
+// ── Runtime-private blob ────────────────────────────────────────────────────
+
+export async function readRuntimeCheckpoint<T = unknown>(agentInstanceId: string): Promise<T | null> {
+  assertSafeName("runtime", agentInstanceId);
+  return readJSON<T>(runtimeStatePath(agentInstanceId));
+}
+
+export async function writeRuntimeCheckpoint(agentInstanceId: string, blob: unknown): Promise<void> {
+  assertSafeName("runtime", agentInstanceId);
+  await atomicWriteJSON(runtimeStatePath(agentInstanceId), blob);
+}
+
+// ── User checkpoints ────────────────────────────────────────────────────────
+
+export async function readCheckpoint<T = unknown>(name: string): Promise<CheckpointRead<T>> {
+  assertSafeCheckpointName(name);
+  return readJSONWithPresence<T>(checkpointPath(name));
+}
+
+export async function writeCheckpoint(name: string, value: unknown): Promise<void> {
+  assertSafeCheckpointName(name);
+  await atomicWriteJSON(checkpointPath(name), value);
+}
+
+// ── Pause records ───────────────────────────────────────────────────────────
+
+/** The `pauses/<pauseId>.json` file — the only durable handoff between the
+ *  paused subprocess and the resumed one.
+ *
+ *  Written twice in two execution contexts:
+ *  - At pause time the runner writes the placeholder `{ pauseId, request }`
+ *    (no `resolved`). The snapshot captures it.
+ *  - At resume time the engine activity writes the resolution — usually
+ *    merged on top of the placeholder, but snapshotless pauses may only have
+ *    `{ resolved: true, resumePayload, expired }` in a fresh sandbox. Those
+ *    three resolution fields are always present together so the byte shape
+ *    distinguishes a real resume (`expired:false`) from a TTL expiry
+ *    (`expired:true`) from an unresolved placeholder (`resolved` absent).
+ *
+ *  `corePause` reads it on re-entry: `resolved !== true` ⇒ still my own
+ *  placeholder, pause again; `expired` ⇒ apply `onExpiry`; else return
+ *  `resumePayload`. */
+export interface PauseRecord {
+  pauseId:        string;
+  request:        unknown;
+  /** Set true once the engine has written the resolution (resume or expiry). */
+  resolved?:      boolean;
+  /** Value to return from `ctx.pause` on a real resume; null for expiry. */
+  resumePayload?: unknown;
+  /** True when the resolution is a TTL expiry, not a caller-driven resume. */
+  expired?:       boolean;
+}
+
+function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function validatePauseRecord(value: unknown, expectedPauseId: string): PauseRecord {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: expected object`);
+  }
+  const record = value as Record<string, unknown>;
+  if (record.pauseId !== undefined && record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: pauseId mismatch`);
+  }
+
+  if (record.resolved === true) {
+    if (typeof record.expired !== "boolean") {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require boolean expired`);
+    }
+    if (!hasOwn(record, "resumePayload") || record.resumePayload === undefined) {
+      throw new Error(`pause record ${expectedPauseId} is malformed: resolved records require resumePayload`);
+    }
+    return {
+      pauseId: expectedPauseId,
+      request: hasOwn(record, "request") ? record.request : null,
+      ...record,
+    } as unknown as PauseRecord;
+  }
+
+  if (record.pauseId !== expectedPauseId) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require matching pauseId`);
+  }
+  if (!hasOwn(record, "request") || record.request === undefined) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records require request`);
+  }
+  if (record.resolved !== undefined && record.resolved !== false) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: resolved must be true, false, or absent`);
+  }
+  if (hasOwn(record, "expired") || hasOwn(record, "resumePayload")) {
+    throw new Error(`pause record ${expectedPauseId} is malformed: unresolved records must not include resolution fields`);
+  }
+  return record as unknown as PauseRecord;
+}
+
+export async function readPauseRecord(pauseId: string): Promise<PauseRecord | null> {
+  assertSafeName("pause", pauseId);
+  const record = await readJSON<unknown>(pausePath(pauseId));
+  return record === null ? null : validatePauseRecord(record, pauseId);
+}
+
+export async function writePauseRecord(record: PauseRecord): Promise<void> {
+  assertSafeName("pause", record.pauseId);
+  validatePauseRecord(record, record.pauseId);
+  await atomicWriteJSON(pausePath(record.pauseId), record);
+}
+
+/** Wipe the entire state directory. Used by the runner at first-boot
+ *  (no pauseId in env) so a freshly-dispatched run never inherits state
+ *  from a prior dispatch that shared the sandbox snapshot template.
+ *  No-op when the directory doesn't exist. */
+export async function resetStateDir(): Promise<void> {
+  await fs.rm(getStateDir(), { recursive: true, force: true });
+}

package/src/pause/wrappers.ts

@@ -0,0 +1,79 @@
+/**
+ * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * closure over `ctx.pause`:
+ *
+ *   - `requestDecision` — pause for a typed human/agent decision (schema required).
+ *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
+ *                         skips the snapshot, returns void.
+ *   - `waitForEvent`    — pause until an event resumes by correlation key.
+ *
+ * Built from a `PauseFn` so the wrapper logic lives in one place and the step
+ * runner just spreads them onto the context next to `pause`.
+ */
+
+import type { z } from "zod";
+import type { StepPauseRequest } from "../step-invocation/types.js";
+import type { PauseRequest } from "./pause-core.js";
+
+/** The public `ctx.pause` callable (always `kind: "custom"`). */
+export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
+
+/** Internal: pause with an explicit wire `kind`. The wrappers stamp
+ *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `custom` and never exposes it. */
+export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
+
+export interface RequestDecisionRequest<T> {
+  reason:   string;
+  payload?: Record<string, unknown>;
+  /** Required — a decision is always validated against a shape. */
+  schema:   z.ZodType<T>;
+  ttlMs?:   number;
+}
+
+export interface WaitForEventRequest<T> {
+  reason:         string;
+  /** Required — the by-key resume route targets this. */
+  correlationKey: string;
+  schema?:        z.ZodType<T>;
+  ttlMs?:         number;
+}
+
+export interface PauseWrappers {
+  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
+  sleep(durationMs: number): Promise<void>;
+  waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+}
+
+export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
+  return {
+    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T> {
+      return pause<T>({
+        reason: req.reason,
+        schema: req.schema,
+        ...(req.payload !== undefined ? { payload: req.payload } : {}),
+        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+      }, "decision");
+    },
+
+    // Resolves on its OWN ttl — there is no external resumer for a sleep, so
+    // onExpiry resolves (not throws) with void. snapshot:false keeps it cheap.
+    sleep(durationMs: number): Promise<void> {
+      return pause<void>({
+        reason:    `sleep ${durationMs}ms`,
+        ttlMs:     durationMs,
+        snapshot:  false,
+        onExpiry:  { mode: "resolve", value: undefined },
+      }, "sleep");
+    },
+
+    waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T> {
+      return pause<T>({
+        reason:         req.reason,
+        correlationKey: req.correlationKey,
+        ...(req.schema !== undefined ? { schema: req.schema } : {}),
+        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+      }, "event");
+    },
+  };
+}

package/src/request-context/request-context.ts

@@ -39,6 +39,8 @@
  * is per-run by design (cross-run state must be explicit via `input`).
  */
 
+import { z } from "zod";
+
 /** Reserved key namespace prefix — anything starting with this is platform-owned. */
 export const AC_RESERVED_PREFIX = "ac__";
 
@@ -99,6 +101,18 @@ export interface RequestContextWire {
   user: Record<string, unknown>;
 }
 
+export const RequestContextWireSchema = z.object({
+  reserved: z.object({
+    teamId:       z.string(),
+    runId:        z.string(),
+    workflowId:   z.string(),
+    factoryId:    z.string().nullable(),
+    apiKeyScopes: z.array(z.string()).readonly(),
+    parentRunId:  z.string().nullable(),
+  }),
+  user: z.record(z.string(), z.unknown()),
+}) satisfies z.ZodType<RequestContextWire>;
+
 /** Thrown when a caller tries to `set` or `delete` a reserved key downstream. */
 export class ReservedKeyError extends Error {
   readonly key: string;
@@ -185,9 +199,10 @@ export class RequestContext<U extends Record<string, unknown> = Record<string, u
    * its own `AbortSignal` separately via `withAbortSignal()`.
    */
   static deserialise(wire: RequestContextWire): RequestContext {
+    const parsed = RequestContextWireSchema.parse(wire);
     const ctx = new RequestContext(
-      { ...wire.reserved, abortSignal: undefined },
-      new Map(Object.entries(wire.user)),
+      { ...parsed.reserved, abortSignal: undefined },
+      new Map(Object.entries(parsed.user)),
     );
     return ctx;
   }

package/src/runtimes/claude.ts

@@ -1,9 +1,10 @@
 /** Claude Agent SDK runtime — replaces the old Claude CLI subprocess runtime. */
 
-import { query, type HookCallback, type PreToolUseHookInput, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
+import { query, type HookCallback, type PreToolUseHookInput, type SDKUserMessage, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { DEFAULT_CLAUDE_MODEL } from "../agent/agent-loop.js";
+import { AsyncQueue } from "../agent/async-queue.js";
 import { runProcessorChain } from "../processors/runner.js";
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -26,6 +27,12 @@ function translateMessage(message: Record<string, unknown>): AgentMessage[] {
       const b = block as Record<string, unknown>;
       if (b.type === "text") msgs.push({ type: "text", text: String(b.text ?? ""), timestamp: ts });
       if (b.type === "thinking") msgs.push({ type: "thinking", text: String(b.thinking ?? ""), timestamp: ts });
+      // `redacted_thinking` is the encrypted-thinking variant emitted by
+      // reasoning models that don't expose chain-of-thought (the content
+      // is an opaque encrypted blob, not human-readable text). Surface
+      // it as a placeholder so the Agent tab's thinking badge isn't
+      // visually empty for those models.
+      if (b.type === "redacted_thinking") msgs.push({ type: "thinking", text: "(redacted)", timestamp: ts });
       if (b.type === "tool_use") msgs.push({ type: "tool_use", toolName: String(b.name ?? ""), toolInput: (b.input ?? {}) as Record<string, unknown>, toolUseId: String(b.id ?? ""), timestamp: ts });
     }
     return msgs;
@@ -82,24 +89,63 @@ export interface ClaudeRuntimeConfig {
   effort?: "low" | "medium" | "high" | "xhigh" | "max";
 }
 
+/** Canonical install path for Claude Code inside a Vercel sandbox.
+ *  Our `agent-env` setup copies the native binary here as a real file
+ *  (not a symlink) so it survives snapshotting. The Anthropic installer
+ *  drops a symlink at `~/.local/bin/claude` pointing into user-home,
+ *  which Vercel sandbox snapshots don't preserve reliably — pinning
+ *  `/usr/local/bin/claude` instead bypasses both PATH-priority issues
+ *  (`~/.local/bin` comes earlier than `/usr/local/bin`) and the
+ *  broken-symlink-after-restore problem. Callers can override via
+ *  `pathToClaudeCodeExecutable` or `CLAUDE_CODE_EXECUTABLE`. */
+const DEFAULT_CLAUDE_PATH = "/usr/local/bin/claude";
+
 export class ClaudeRunner implements ModelExecutionContract {
   supportsToolCallProcessor = true;
+  readonly kind = "claude";
+
+  // ADR-0006 pause-resume hooks intentionally omitted.
+  //
+  // The Claude Agent SDK keeps the conversation SERVER-SIDE at
+  // Anthropic, addressed by `session_id`. Each `sendMessage` call
+  // passes `resume: sessionId` and Anthropic rehydrates the prior
+  // transcript; `ClaudeRunner` holds no instance state across calls.
+  //
+  // `sessionId` itself lives in the agent loop (see
+  // agent-loop.ts :: `lastSessionId`) and is part of the loop's own
+  // state file — restored automatically on pause-resume. So the loop
+  // gets everything it needs without any per-runtime blob; defining
+  // `captureCheckpoint`/`restoreCheckpoint` here would just be empty.
+  //
+  // Caveat: Anthropic's server-side session retention is bounded by
+  // their TTL (not ours). For workflow pauses inside that window
+  // (default workflowRunTimeout is 7 days) the resume succeeds; a
+  // 30-day pause may get session-not-found from `resume:` and would
+  // need a fallback to client-managed messages. Documented limitation.
 
   constructor(
-    // Claude Agent SDK executes in this process. In dispatched workflows this
-    // process is already the runner sandbox, so there is no remote provider hop.
     _sandbox: SandboxProvider,
     private readonly options: RuntimeOptions = {},
     private readonly config: ClaudeRuntimeConfig = {},
   ) {}
 
+  get model(): string {
+    return this.config.model ?? this.options.model ?? DEFAULT_CLAUDE_MODEL;
+  }
+
   async gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult> {
     const verdict = await runProcessorChain(this.options.processors ?? [], p => p.processToolCall, call, ctx);
     if (verdict.kind === "continue") return { kind: "allow", call: verdict.value };
     return verdict;
   }
 
-  async *sendMessage(opts: { prompt: string; sessionId?: string; iteration?: number; signal?: AbortSignal }): AsyncGenerator<AgentMessage> {
+  async *sendMessage(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+    inboxStream?: AsyncIterable<{ text: string; senderName?: string | null }>;
+  }): AsyncGenerator<AgentMessage> {
     const requestContext = this.options.requestContext ?? RequestContext.fromReserved({
       teamId: "", runId: "", workflowId: "",
       factoryId: null, apiKeyScopes: [], parentRunId: null,
@@ -124,10 +170,48 @@ export class ClaudeRunner implements ModelExecutionContract {
       return { continue: false, systemMessage: gate.reason };
     };
 
+    // Streaming-input mode (Claude Agent SDK):
+    //   When the caller passes `inboxStream`, we build a pushable
+    //   AsyncIterable<SDKUserMessage> queue. The initial prompt is
+    //   pushed as the first user turn; inbox messages arriving while
+    //   the assistant is mid-turn are pushed as additional user turns
+    //   and the SDK delivers them at the next safe boundary.
+    //
+    //   Without an inboxStream we keep the simple string-prompt path —
+    //   no queue, same behaviour as before. This keeps non-interactive
+    //   workflows (memory extractor, etc.) on the original code path.
+    //
+    //   The queue is closed when the SDK's `result` message indicates
+    //   the iteration's assistant turns are done; without close() the
+    //   iterable would block forever waiting for more user input.
+    const inboxQueue = opts.inboxStream ? new AsyncQueue<SDKUserMessage>() : null;
+    if (inboxQueue) {
+      inboxQueue.push({
+        type: "user",
+        message: { role: "user", content: opts.prompt },
+        parent_tool_use_id: null,
+      });
+      // Drain the inbox iterable into the queue. Runs in parallel
+      // with the assistant; pushes user turns as they arrive.
+      void (async () => {
+        try {
+          for await (const ev of opts.inboxStream!) {
+            const tag = ev.senderName ? `[message from ${ev.senderName}]\n` : "[user message]\n";
+            inboxQueue.push({
+              type: "user",
+              message: { role: "user", content: tag + ev.text },
+              parent_tool_use_id: null,
+            });
+          }
+        } catch { /* iterable ended or aborted */ }
+      })();
+    }
+    const promptForQuery: string | AsyncIterable<SDKUserMessage> = inboxQueue ?? opts.prompt;
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
-        prompt: opts.prompt,
+        prompt: promptForQuery,
         options: {
           tools: this.options.allowedTools,
           allowedTools: this.options.allowedTools,
@@ -138,7 +222,9 @@ export class ClaudeRunner implements ModelExecutionContract {
           effort: this.config.effort,
           cwd: this.options.cwd,
           env: { ...process.env, ...(this.config.env ?? {}) },
-          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable ?? process.env.CLAUDE_CODE_EXECUTABLE ?? "claude",
+          pathToClaudeCodeExecutable: this.config.pathToClaudeCodeExecutable
+            ?? process.env.CLAUDE_CODE_EXECUTABLE
+            ?? DEFAULT_CLAUDE_PATH,
           ...(this.config.claudeMdContent ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: this.config.claudeMdContent } } : {}),
           resume: opts.sessionId,
           mcpServers: this.config.mcpServers,
@@ -158,9 +244,18 @@ export class ClaudeRunner implements ModelExecutionContract {
           if (msg.type === "text" && raw.type === "assistant") emittedAssistantText = true;
           yield msg;
         }
+        // End-of-iteration signal: SDK emits a `result` message after the
+        // assistant's turn completes. Close the queue so the AsyncIterable
+        // drains and query() returns. Without this, the iterable would
+        // block forever waiting for the next user turn that never comes.
+        if (raw.type === "result" && inboxQueue) inboxQueue.close();
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now() };
+    } finally {
+      // Belt-and-braces — close on error/abort too so the dangling
+      // iterable doesn't leak the inboxStream consumer.
+      inboxQueue?.close();
     }
   }
 }

package/src/runtimes/openai-desktop.ts

@@ -21,9 +21,20 @@ export interface OpenAIDesktopRunnerOptions extends RuntimeOptions {
 }
 
 export class OpenAIDesktopRunner implements ModelExecutionContract {
+  readonly kind = "openai-desktop";
+  readonly model = "computer-use-preview";
   private openai: OpenAI;
   private label: string;
 
+  // ADR-0006 pause-resume hooks intentionally omitted.
+  //
+  // The computer-use-preview model treats every `sendMessage` as a
+  // fresh conversation seeded with the current desktop screenshot —
+  // the `messages` array and `previousResponseId` are scoped to ONE
+  // call, never carried across. The desktop screenshot IS the state,
+  // and the sandbox snapshot already captures that on the filesystem.
+  // No runtime-private blob needed.
+
   constructor(
     private sandbox: DesktopSandboxProvider,
     opts: OpenAIDesktopRunnerOptions,

package/src/runtimes/vercel.ts

@@ -88,6 +88,32 @@ export class VercelRunner implements ModelExecutionContract {
     return verdict;
   }
 
+  /** ADR-0006 pause-resume hooks. The Vercel AI SDK holds the running
+   *  conversation client-side in `this.messages` — every `streamText`
+   *  call passes the full array as `messages` and reconstructs it from
+   *  `response.messages` after completion. A pause-induced subprocess
+   *  exit loses the array; the new subprocess constructs a fresh
+   *  `VercelRunner` with `this.messages = []` and the next sendMessage
+   *  would see only the current iteration's prompt — conversation
+   *  history broken. The agent loop calls these at every iteration
+   *  boundary so the messages array round-trips through the sandbox
+   *  snapshot. */
+  captureCheckpoint(): unknown {
+    return { messages: [...this.messages] };
+  }
+
+  restoreCheckpoint(blob: unknown): void {
+    if (!blob || typeof blob !== "object") {
+      throw new Error("Vercel runtime checkpoint is invalid: expected an object with messages[]");
+    }
+    const incoming = (blob as { messages?: unknown }).messages;
+    if (!Array.isArray(incoming)) {
+      throw new Error("Vercel runtime checkpoint is invalid: expected messages[]");
+    }
+    this.messages.length = 0;
+    this.messages.push(...incoming);
+  }
+
   private buildTools(iteration: number, signal?: AbortSignal): AiToolSet {
     const set: AiToolSet = {};
     for (const t of this.tools) {