@agent-compose/sdk 0.5.8 → 0.6.0

package/dist/pause/checkpoint.d.ts

@@ -1,5 +1,6 @@
 /**
- * `ctx.checkpoint(name, fn)` — disk-backed memoise across pause-resume.
+ * Disk-backed memoise across pause-resume — the engine behind durable
+ * `ctx.step(name, fn)` (ADR-0012).
  *
  * First call: `fn()` runs, the result is atomically written to
  * `/tmp/wf/state/checkpoints/<name>.json`. On any subsequent invocation
@@ -16,13 +17,29 @@
  * memoisation is in-sandbox only and would silently retry on a sandbox
  * recreation that lost the checkpoint file.
  *
- * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+ * INTERNAL only — there is no public `ctx.checkpoint`. The durable
+ * `ctx.step` wires `scopedMemoize("step<idx>")` and reports a "restored"
+ * sub-step on a cache hit. See ADR-0012.
  */
-/** Read-or-run-and-write helper. `name` is validated by the state-dir
- *  layer (rejects path-escape attempts); `fn` is awaited if it returns
- *  a Promise so sync and async callers compose identically. */
-export declare function checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
-/** Bind user checkpoint names to a runner-owned namespace. The user's
- *  `name` is still validated independently so a scope prefix cannot turn
- *  an empty or path-escaping name into a valid filename. */
-export declare function scopedCheckpoint(scope: string): typeof checkpoint;
+/** Result of a memoise call — `restored` distinguishes a disk hit (fn was
+ *  NOT run, value read from a prior subprocess) from a fresh run (fn ran,
+ *  value just written). The durable `ctx.step` maps `restored` onto the
+ *  duration-0 "restored" sub-step status. */
+export interface MemoizeResult<T> {
+    value: T;
+    restored: boolean;
+}
+/** Read-or-run-and-write helper reporting whether the value was restored
+ *  from disk. `name` is validated by the state-dir layer (rejects
+ *  path-escape attempts); `fn` is awaited if it returns a Promise so sync
+ *  and async callers compose identically.
+ *
+ *  A pause inside `fn` (PauseSignal) propagates BEFORE any write — a
+ *  partially-completed body is never memoised, so the resume re-runs it. */
+export declare function memoize<T>(name: string, fn: () => Promise<T> | T): Promise<MemoizeResult<T>>;
+/** A memoise function bound to a runner-owned scope. */
+export type ScopedMemoize = <T>(name: string, fn: () => Promise<T> | T) => Promise<MemoizeResult<T>>;
+/** Bind memoise names to a runner-owned namespace (e.g. `step<idx>`). The
+ *  caller's `name` is still validated independently so a scope prefix
+ *  cannot turn an empty or path-escaping name into a valid filename. */
+export declare function scopedMemoize(scope: string): ScopedMemoize;

package/dist/pause/manager.d.ts

@@ -27,6 +27,7 @@ export interface AgentLoopProgressState {
         reason: string;
         correlationKey: string | null;
         at: number;
+        payload?: Record<string, unknown>;
     } | null;
 }
 export interface SettledAgentLoopResult<TResponse = unknown> {

package/dist/pause/pause-core.d.ts

@@ -88,6 +88,29 @@ export declare class PauseSignal {
  *  `err instanceof PauseSignal` anywhere a signal may have been thrown by a
  *  different SDK instance (the runner catching a bundled workflow's signal). */
 export declare function isPauseSignal(err: unknown): err is PauseSignal;
+/**
+ * The run's pause boundary. The runner (`run-agent` `steerPause`) closes a
+ * `corePause` over the ambient `runId`/`stepIndex`; the agent loop / runtime
+ * supplies the per-iteration `agentScope` so the pauseId stays stable across
+ * the loop's iteration-skipping on resume. Absent outside a workflow step
+ * (local / non-sandbox callers) — see `boundProcessorPause`.
+ */
+export type BoundaryPauseFn = <T = unknown>(req: PauseRequest<T>, agentScope: {
+    agentId: string;
+    iteration: number;
+}) => Promise<T>;
+/**
+ * Build the `ProcessorContext.pause` callable for a given hook scope: binds the
+ * boundary to this hook's `{ agentId, iteration }` so a processor calling
+ * `ctx.pause(req)` gets a deterministic, resume-stable pauseId. When no boundary
+ * is wired (local tests, non-sandbox callers), the returned fn rejects loudly
+ * rather than silently no-op'ing — pause genuinely cannot work without the
+ * runner's snapshot/Temporal machinery.
+ */
+export declare function boundProcessorPause(boundary: BoundaryPauseFn | undefined, scope: {
+    agentId: string;
+    iteration: number;
+}): <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 /** Wipe the ordinal counters. Called by the runner at first-boot alongside
  *  `resetStateDir()`; a fresh module load already starts empty, so this is
  *  belt-and-braces for any in-process reuse. */

package/dist/pause/state-dir.d.ts

@@ -6,7 +6,7 @@
  *
  *   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
+ *   checkpoints/<name>.json          ← durable `ctx.step(name, fn)` memoised values (keyed `step<idx>.<name>`)
  *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
  *
  * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`

package/dist/processors/builtins.d.ts

@@ -3,7 +3,7 @@
  * covers the most common gating needs. More can be authored by users; these
  * exist as load-bearing examples and as defaults for common policies.
  */
-import type { Processor } from "./processor.js";
+import type { Processor, ToolCall } from "./processor.js";
 /**
  * Reject any tool call whose name appears in `names`. The reason is returned
  * to the model as the tool result, so the model can react and try a
@@ -14,6 +14,25 @@ import type { Processor } from "./processor.js";
  * (candidate #1).
  */
 export declare function denyTools(names: readonly string[]): Processor;
+/**
+ * Pause the run for HUMAN APPROVAL before a matching tool executes — the
+ * human-in-the-loop pre-tool gate (ADR-0006 `ctx.pause`). Over an ACP runtime
+ * this is exactly the `session/request_permission` path: the CLI asks to run a
+ * tool, the gate runs here, and `ctx.pause` snapshots the workflow and waits
+ * durably until a reviewer resolves the pause with `{ approved, reason? }`.
+ * Approve → the tool runs; deny → the reason is returned to the model as the
+ * tool result and the loop continues.
+ *
+ *   tools?  — only these tool names require approval (default: EVERY tool call).
+ *   reason? — build the human-facing prompt from the call (default names the tool).
+ *
+ * Dormant on runtimes without pre-tool gating; active on those that wire
+ * `processToolCall` (the ACP CLI runtimes, the Claude pre-tool hook, Vercel).
+ */
+export declare function humanApproval(opts?: {
+    tools?: readonly string[];
+    reason?: (call: ToolCall) => string;
+}): Processor;
 /**
  * Require the calling API key to carry every scope in `required`. Aborts the
  * agent loop with a clear reason if any are missing — defence-in-depth on

package/dist/processors/gate-pause.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gate-pause processor (ADR-0028).
+ *
+ * A pre-tool gate that, when its `policy` flags a tool call as needing human
+ * approval, pauses the run as a SERVER operation (`requestPauseAndAwait`) and
+ * blocks until a human answers — then allows or denies the tool.
+ *
+ * It pauses through the server pause API (`requestPauseAndAwait`), so the pause
+ * is a server operation no `try/catch` can swallow. It does NOT use today's
+ * `ctx.pause`, which still throws `PauseSignal` — exactly the swallowable path
+ * ADR-0028 supersedes for agents. (Routing `ctx.pause` itself through this same
+ * server pause is the natural unification — ADR-0028 open question — at which
+ * point "the pause API" and "ctx.pause" become one thing.) Because it lives in
+ * the shared `gateToolCall` chain, one implementation covers every runtime — the
+ * Claude Agent SDK `PreToolUse` hook and the ACP `session/request_permission`
+ * path both route through it.
+ *
+ * Opt-in: the workflow/agent supplies the `policy` (which may be a heuristic or
+ * an async classifier agent). The connection defaults to the run credential in
+ * the sandbox env; absent it (local / non-sandbox), the gate is a no-op and
+ * tool calls pass through untouched.
+ */
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+export interface GatePauseApproval {
+    /** Human-readable question shown on the approval UI. */
+    reason: string;
+    /** Decision options the human picks from. Defaults to Approve / Deny. */
+    options?: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+/** Decide whether a tool call needs human approval. Return `false` to let it
+ *  through untouched, or an approval request to pause the run until a human
+ *  answers. May be async (e.g. a small classifier agent). */
+export type GatePausePolicy = (call: ToolCall, ctx: ProcessorContext) => (false | GatePauseApproval) | Promise<false | GatePauseApproval>;
+export interface GatePauseConnection {
+    baseUrl: string;
+    token: string;
+    runId: string;
+}
+export declare function createGatePauseProcessor(opts: {
+    policy: GatePausePolicy;
+    /** Override the server connection (defaults to the sandbox run-credential env). */
+    connection?: GatePauseConnection;
+}): Processor;

package/dist/processors/gate-pause.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/processors/index.d.ts

@@ -1,4 +1,6 @@
 export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from "./processor.js";
 export { Verdict } from "./processor.js";
 export { runProcessorChain } from "./runner.js";
-export { denyTools, requireScope, redactPattern, } from "./builtins.js";
+export { denyTools, humanApproval, requireScope, redactPattern, } from "./builtins.js";
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";

package/dist/processors/processor.d.ts

@@ -29,6 +29,7 @@
  */
 import type { AgentMessage } from "../types/protocol.js";
 import type { RequestContext } from "../request-context/request-context.js";
+import type { PauseRequest } from "../pause/pause-core.js";
 /** Proposed tool call. Mirrors the relevant fields of AgentMessageToolUse but
  *  lives as its own type so runtime adapters (candidate #1) can populate it
  *  from their internal call shape without coupling to the agent message protocol. */
@@ -50,6 +51,18 @@ export interface ProcessorContext {
     agentId: string;
     /** Iteration of the agent loop (1-based). */
     iteration: number;
+    /**
+     * Pause the run from inside a processor — the human-approval primitive for a
+     * pre-tool-use gate (ADR-0006 §"reachable from every user code path";
+     * ADR-0020 the ACP `session/request_permission` path). On the fresh pass it
+     * throws `PauseSignal` (internal control flow) so the workflow snapshots and
+     * waits durably; on step re-entry after resolution it returns the resume
+     * payload (validated against `req.schema` if given). The agent loop / runtime
+     * wires it to the run's pause boundary with a deterministic, resume-stable
+     * pauseId (keyed on this hook's agentId + iteration). Calling it outside a
+     * sandboxed workflow step throws — pause requires the runner's pause boundary.
+     */
+    pause<T = unknown>(req: PauseRequest<T>): Promise<T>;
 }
 /**
  * Verdict returned by every processor method.

package/dist/runtimes/_acp-client.d.ts

@@ -0,0 +1,140 @@
+/**
+ * ACP client peer — the JSON-RPC half of a CLI-agent runtime (WS-C / ADR-0020).
+ *
+ * `CliAgentRunner` spawns an agentic CLI in **ACP agent** mode and delegates the
+ * whole wire protocol to this class. We are the ACP *Client*; the CLI is the
+ * *Agent*. `AcpClientPeer` owns:
+ *
+ *   - the `ClientSideConnection` (from `@agentclientprotocol/sdk`) over an
+ *     `ndJsonStream`-framed duplex wired to the subprocess stdio;
+ *   - the SINGLE `session/update` → `AgentMessage` normaliser (replacing every
+ *     per-CLI `mapEvent`) — one place, defensive, never throws on an unknown
+ *     `sessionUpdate` variant (returns `[]`);
+ *   - the `session/request_permission` handler — builds a `ToolCall`, runs it
+ *     through the runner's `gateToolCall` (the shared processor chain), and maps
+ *     the verdict back to a `PermissionOption.optionId`. A `PauseSignal` thrown
+ *     by a processor MUST propagate (recognised via `isPauseSignal`) — never
+ *     swallowed by a JSON-RPC try/catch, or the `run_pauses` row is silently
+ *     lost (ADR-0020 Q4 / ADR-0006);
+ *   - `session/cancel` driven by the `sendMessage` `AbortSignal`.
+ *
+ * We advertise NO `fs` / `terminal` client capabilities: the CLI runs in-sandbox
+ * with direct access to the factory drive, so we never serve file or terminal
+ * ops. We register no handlers for them — the `Client` interface methods are
+ * simply absent, so a (conformant) agent won't request them.
+ *
+ * The wire `protocolVersion` is pinned at integer 1 at `initialize`; the
+ * package version is pinned separately. Version negotiation drives the
+ * capability fallback that lives in `CliAgentRunner` (a non-1 response → the
+ * runner closes this peer and falls back to the legacy JSONL path).
+ */
+import { RequestError, type Stream } from "@agentclientprotocol/sdk";
+import type * as acp from "@agentclientprotocol/sdk";
+import type { AgentMessage } from "../types/protocol.js";
+import type { ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { ToolCallGateResult } from "../types/runtime.js";
+/** The wire protocol version we pin at `initialize`. Bumped only on a breaking
+ *  ACP wire change — never silently. The package version is pinned separately
+ *  in package.json; this integer is the real compatibility gate (ADR-0020). */
+export declare const ACP_PROTOCOL_VERSION = 1;
+/** Collaborators `AcpClientPeer` needs from `CliAgentRunner`, kept as a small
+ *  injected surface so the peer stays transport-agnostic and unit-testable. */
+export interface AcpClientPeerDeps {
+    /** Duplex ACP stream (typically `ndJsonStream(stdinWritable, stdoutReadable)`
+     *  wired to the subprocess). The peer does not own the subprocess — only the
+     *  protocol over this stream. */
+    stream: Stream;
+    /** Run a proposed tool call through the runner's processor chain. Mirrors
+     *  `ClaudeRunner.gateToolCall`. May throw `PauseSignal` (human-approval
+     *  processor) — the peer re-raises it, never swallows it. */
+    gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+    /** PROVIDER for the current turn's processor context (requestContext, abort
+     *  signal, agentId, iteration). A provider — not a frozen value — because the
+     *  peer is long-lived (persistent session) and reused across turns; it must
+     *  read the LIVE turn's context so a permission->pause binds to the right
+     *  iteration. The runner refreshes the backing value before each turn. */
+    procCtx: () => ProcessorContext;
+    /** Turn-scoped abort signal from `sendMessage`. On abort the peer sends
+     *  `session/cancel` for the live session. */
+    signal?: AbortSignal;
+}
+/**
+ * Map ONE ACP `session/update` to zero-or-more `AgentMessage`s. The single
+ * normaliser (ADR-0020) — defensive: any variant a given CLI never emits is
+ * simply absent → `[]`, and an unknown `sessionUpdate` discriminator returns
+ * `[]` rather than throwing (mirrors the legacy `mapEvent` `default: return []`).
+ *
+ * Lifecycle (`init` / `done`) and turn-level errors are synthesised by the
+ * runner / `prompt()` result, NOT here. Per-turn token usage rides the
+ * `session/prompt` result (`PromptResponse.usage`), not `usage_update` — the
+ * `usage_update` session update is a context-window/cost gauge with no per-token
+ * fields, so it maps to nothing (ADR-0020 Q1 verified against the live zod types).
+ */
+export declare function normalizeSessionUpdate(update: acp.SessionUpdate): AgentMessage[];
+export declare class AcpClientPeer {
+    private readonly deps;
+    private readonly conn;
+    /** Messages mapped from inbound `session/update` notifications, drained by the
+     *  active `prompt()` call. REPLACED with a fresh queue at the start of every
+     *  turn: an `AsyncQueue` is single-use (once `close()`d it stays drained), so a
+     *  long-lived peer reused across turns must hand each turn its own queue or the
+     *  second turn's updates would be silently dropped. The inbound `sessionUpdate`
+     *  handler always pushes onto whatever the current queue is. */
+    private updates;
+    /** Live session id (from `session/new` / `session/resume`), needed by
+     *  `session/cancel`. */
+    private sessionId;
+    /** Captured `PauseSignal` thrown out of the permission handler. The JSON-RPC
+     *  layer would otherwise convert the throw into an error response; we instead
+     *  stash it and re-raise it from `prompt()` so it unwinds to `serveStep`. */
+    private pendingPause;
+    private cancelled;
+    /** Trips the in-flight `session/prompt` turn when `cancel()` / `close()` fires.
+     *  The agent is supposed to answer `cancelled` after `session/cancel`, but a
+     *  fully-silent / dead CLI may never resolve the prompt request — so the abort
+     *  latch unblocks `prompt()` deterministically instead of hanging on the
+     *  outstanding JSON-RPC request. `null` between turns. */
+    private abortPrompt;
+    constructor(deps: AcpClientPeerDeps);
+    /**
+     * Negotiate the wire protocol at `initialize`. Pins `protocolVersion` to
+     * integer 1 and advertises NO fs / terminal capabilities. Returns the
+     * version the agent negotiated — `CliAgentRunner` compares it to
+     * `ACP_PROTOCOL_VERSION` to decide ACP-path vs. legacy-JSONL fallback.
+     */
+    initialize(): Promise<{
+        protocolVersion: number;
+    }>;
+    /**
+     * Start a session and return its id (threaded back onto the synthesised
+     * `init` / `done`). Resume is via the CLI's own persisted thread/rollout on
+     * the sandbox FS keyed by this id — not an ACP `session/resume` round-trip;
+     * the re-issued turn on resume continues that thread (ADR-0020 Q4, validated
+     * in the manual live step).
+     */
+    startSession(cwd: string): Promise<string>;
+    /**
+     * Drive one `session/prompt` turn, yielding `AgentMessage`s as the agent
+     * streams `session/update` notifications. Resolves the generator when the
+     * prompt result lands (clean `stopReason`), or yields `{type:"error"}` on a
+     * `refusal` stop reason or a JSON-RPC error. A `cancelled` stop reason ends
+     * the turn with no error. Re-raises any `PauseSignal` captured by the
+     * permission handler so it unwinds past `sendMessage` to `serveStep`.
+     */
+    prompt(text: string): AsyncGenerator<AgentMessage>;
+    /** The live session id, or undefined before `startSession`. Threaded back
+     *  onto the synthesised `init` / `done` by the runner. */
+    get currentSessionId(): string | undefined;
+    /** Send `session/cancel` for the live session (notification, fire-and-forget).
+     *  Idempotent. The pending `session/prompt` is expected to resolve
+     *  `cancelled`; any outstanding `session/request_permission` resolves with
+     *  `outcome:"cancelled"` via the handler's signal check. */
+    cancel(): void;
+    /** Tear down the connection. Trips the abort latch so any in-flight `prompt()`
+     *  turn unblocks, and closes the updates queue. Used both on clean turn end and
+     *  when the runner falls back to the legacy JSONL path after a version
+     *  mismatch. */
+    close(): void;
+    private onRequestPermission;
+}
+export { RequestError };

package/dist/runtimes/_cli-agent.d.ts

@@ -23,9 +23,28 @@
  * (see each spec's `authEnv`); `commands.run` inherits the sandbox env, so
  * values set via `agentc secrets set` are visible to the CLI.
  */
-import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider } from "../index.js";
+import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
+import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
 export declare function shellQuote(value: string): string;
+/** Hard deadline (ms) for the ACP `initialize` handshake AND the prompt turn.
+ *  `peer.initialize()` resolves only when the agent answers; a real CLI that
+ *  never speaks ACP (or blocks on stdin) would otherwise hang forever and the
+ *  JSONL fallback would never be reached. On timeout we tear the peer down and
+ *  route to JSONL exactly like a handshake error. Overridable via the env for
+ *  ops tuning; defaults sane. */
+export declare const ACP_HANDSHAKE_TIMEOUT_MS: number;
+/** Readiness gate for the LIVE ACP attempt. The duplex-stdin transport in
+ *  `spawnAcpProcess` is now real (`commands.spawnDuplex` on the local provider),
+ *  so the agent's `initialize` request bytes are delivered and the handshake can
+ *  actually negotiate. The transport is live; this is `true`.
+ *
+ *  Readiness alone is not sufficient — the runner still requires the live
+ *  provider to expose `commands.spawnDuplex`. A provider without it (the
+ *  server→sandbox vercel/e2b view never spawns the in-VM CLI, so neither
+ *  implements duplex) falls back to JSONL cleanly via the capability check in
+ *  `sendMessage`. */
+export declare const ACP_TRANSPORT_READY = true;
 /** Per-CLI behaviour. The base owns the lifecycle (init/done/error) and the
  *  transport (spawn + JSONL parse); a spec owns the CLI-specific bits. */
 export interface CliAgentSpec {
@@ -59,11 +78,27 @@ export interface CliAgentSpec {
     }): string;
     /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
      *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
-     *  usage (text / thinking / tool_use / tool_result / usage). */
+     *  usage (text / thinking / tool_use / tool_result / usage).
+     *
+     *  LEGACY FALLBACK PATH. Retained for a pinned-old CLI that predates ACP
+     *  support (the `initialize` handshake negotiates a non-1 version → the
+     *  runner closes the ACP peer and drives this JSONL path instead). Removed
+     *  only after the last subprocess CLI is on ACP (ADR-0020 increment 5). */
     mapEvent(parsed: Record<string, unknown>): AgentMessage[];
     /** Pull a session/thread id out of a parsed event so the next turn can
-     *  resume it (codex `thread.started.thread_id`, amp `session_id`). */
+     *  resume it (codex `thread.started.thread_id`, amp `session_id`).
+     *  LEGACY FALLBACK PATH (see `mapEvent`). */
     extractSessionId(parsed: Record<string, unknown>): string | undefined;
+    /** ACP-mode invocation (the Zed `agent_servers` shape). When present, the
+     *  runner spawns the CLI in ACP agent mode and delegates the whole wire
+     *  protocol to `AcpClientPeer`; the legacy `promptPayload`/`buildCommand`/
+     *  `extractSessionId`/`mapEvent` members are used only as the version-mismatch
+     *  fallback. Absent → the spec is JSONL-only (legacy path always). */
+    acp?: {
+        command: string;
+        args: string[];
+        env?: Record<string, string>;
+    };
 }
 export declare class CliAgentRunner implements ModelExecutionContract {
     private readonly sandbox;
@@ -71,8 +106,60 @@ export declare class CliAgentRunner implements ModelExecutionContract {
     private readonly spec;
     private readonly configModel?;
     readonly kind: string;
+    /** Whether the live ACP path will actually run for this runner: the spec
+     *  declares an `acp` invocation, the transport is ready, AND the live provider
+     *  exposes the duplex-stdin primitive ACP needs. A provider without
+     *  `commands.spawnDuplex` (the server→sandbox vercel/e2b view) can't carry the
+     *  JSON-RPC duplex, so the runner falls back to JSONL — and in that state the
+     *  CLI owns its own tool loop with no pre-tool seam. */
+    private get acpCapable();
+    /** ACP-capable specs gate tools through the shared processor chain (the CLI
+     *  no longer owns its own unsupervised tool loop). True ONLY when the ACP path
+     *  will actually run — a JSONL-only spec, an ACP spec while the transport is
+     *  dormant (`acpTransportReady` false), OR a provider that can't spawn a duplex
+     *  leaves the CLI in charge with NO pre-tool seam, so this must report false in
+     *  those states. Otherwise the agent loop would suppress its "processToolCall
+     *  gating is dormant" warning and a registered deny/gate processor would be
+     *  silently un-enforced for the agent. */
+    get supportsToolCallProcessor(): boolean;
+    /** Once the handshake has decided ACP vs. legacy for this runner instance,
+     *  cache it so every later turn skips re-probing. `undefined` = not yet
+     *  decided. */
+    private acpDecision;
+    /** The persistent ACP session, established lazily on the first ACP turn and
+     *  reused across every later turn (a real ACP agent is a LONG-LIVED JSON-RPC
+     *  server — one process, one initialize, one session — driven turn-by-turn via
+     *  `session/prompt`, NOT respawned per turn). `undefined` until the first
+     *  successful handshake; never re-set after a fallback (we switch to JSONL
+     *  for the whole runner instead). */
+    private acpSession;
+    /** The CURRENT turn's processor context. The long-lived ACP peer is built
+     *  once but reused across turns, so it reads the gate context through a
+     *  provider (`procCtx: () => this.currentAcpProcCtx`) rather than a frozen
+     *  value — `sendMessageAcp` refreshes this before each prompt so a
+     *  permission->pause binds to THIS turn's iteration (stable pauseId on
+     *  resume), not the first turn's. */
+    private currentAcpProcCtx;
+    /** Per-instance copy of the live-ACP readiness gate (defaults to the module
+     *  const `ACP_TRANSPORT_READY`). Tests that drive the ACP lifecycle/fallback/
+     *  pause/parity paths flip it on via `enableAcpForTesting()` so they keep
+     *  exercising the real `sendMessageAcp` even while the production default is
+     *  dormant. Not a public API. */
+    private acpTransportReady;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined);
+    /** TEST-ONLY: flip the live-ACP readiness gate on for this runner instance so
+     *  the ACP lifecycle / fallback tests can exercise `sendMessageAcp` while the
+     *  production default (`ACP_TRANSPORT_READY`) stays dormant. Not part of the
+     *  public runtime surface. */
+    enableAcpForTesting(): void;
     get model(): string | undefined;
+    /** Runtime-owned pre-tool gate. Runs the shared processor chain and maps its
+     *  verdict to a `ToolCallGateResult` — identical to `ClaudeRunner.gateToolCall`.
+     *  Invoked by `AcpClientPeer`'s `session/request_permission` handler. A
+     *  processor that throws `PauseSignal` propagates through unchanged (the
+     *  handler re-raises it; never swallowed). */
+    gateToolCall(call: ToolCall, ctx: ProcessorContext): Promise<ToolCallGateResult>;
+    private buildProcCtx;
     private installed;
     /** Provision the CLI on demand. A no-op once `bin` is on PATH — the steady
      *  state under `snapshots: { bootFrom: "reuse" }`, where the first run's
@@ -85,5 +172,70 @@ export declare class CliAgentRunner implements ModelExecutionContract {
         iteration?: number;
         signal?: AbortSignal;
     }): AsyncGenerator<AgentMessage>;
+    /**
+     * Tear down the failed/probed ACP process on a fallback path: group-kill the
+     * subprocess (so the npx-spawned grandchild dies too, not just `sh`) and
+     * `.catch()` its `exited` promise so the abandoned process can't surface an
+     * unhandled rejection once we've stopped awaiting it. A best-effort stdin
+     * close is attempted first — a conformant CLI exits cleanly on EOF — but we
+     * rely on the group-kill for force-termination of one that won't.
+     */
+    private teardownAcp;
+    /**
+     * Establish the persistent ACP session for this runner instance, ONCE,
+     * lazily on the first ACP turn: spawn the long-lived ACP agent process, run
+     * `initialize`, and open the single `session/new`. The result is cached on the
+     * instance and reused by every later turn — a real ACP agent
+     * (`npx @agentclientprotocol/codex-acp`) is a long-lived JSON-RPC server that
+     * does NOT exit after one turn, so respawning per turn would both hang on
+     * `proc.exited` and break multi-turn continuity (each turn would open a fresh
+     * session and lose the thread).
+     *
+     * Returns the cached session, or `null` to signal the version-mismatch /
+     * handshake-error / stall fallback — in which case the failed process has
+     * already been torn down (group-killed + exited-catch) by `teardownAcp`, and
+     * the caller yields `ACP_FALLBACK`. The persistent process is otherwise killed
+     * only on the abort signal (wired in `spawnAcpProcess`) and is reclaimed when
+     * the sandbox VM is torn down at run-end — we never block on its exit.
+     */
+    private ensureAcpSession;
+    /**
+     * ACP transport, ONE turn. On the FIRST turn it lazily establishes the
+     * persistent session (`ensureAcpSession`); every later turn REUSES that same
+     * process + peer + session id — `session/prompt` against the live session, no
+     * respawn, no new session. On a handshake error / version mismatch / session
+     * open failure (first turn only) it yields `ACP_FALLBACK` so `sendMessage`
+     * switches to the JSONL path. Never yields a duplicate `init` (the caller
+     * already did). CRITICALLY: never `await proc.exited` — the ACP agent is a
+     * long-lived server that does not exit after a turn; blocking on its exit
+     * would hang the loop forever.
+     */
+    private sendMessageAcp;
+    /**
+     * Spawn the CLI in ACP agent mode and wrap its stdio as an `ndJsonStream`
+     * duplex.
+     *
+     * The real stdin/stdout duplex comes from `commands.spawnDuplex` — the in-VM
+     * `child_process` pipe (`makeLocalSandboxProvider`). The runner runs INSIDE
+     * the sandbox VM and spawns the CLI via the local provider, so a duplex stdin
+     * is a normal pipe and works identically on Vercel/E2B/local (the
+     * @vercel/sandbox no-stdin limit is the server→sandbox boundary, not this
+     * one). `ndJsonStream(stdin, stdout)` then carries JSON-RPC both ways:
+     * outbound `initialize`/`session/*` request frames down stdin, inbound
+     * `session/update` notifications + results up stdout.
+     *
+     * Caller contract: only invoked when `commands.spawnDuplex` is present (the
+     * capability check in `sendMessage` gates the whole ACP attempt on it), so a
+     * provider without duplex never reaches here — it falls back to JSONL.
+     */
+    private spawnAcpProcess;
+    /**
+     * Legacy JSONL transport (the version-mismatch fallback, ADR-0020 increment
+     * 5 retires it). Unchanged behaviour: write the prompt to a file, run the
+     * one-shot command, line-buffer stdout, `mapEvent` each parsed line, and cap
+     * with the runner-synthesised `done`. Does NOT re-yield `init` (the caller
+     * already did).
+     */
+    private sendMessageJsonl;
 }
 export declare function createCliAgentRuntime(spec: CliAgentSpec, configModel?: string): import("../index.js").AgentRuntime<SandboxProvider>;

package/dist/runtimes/amp.d.ts

@@ -18,6 +18,6 @@ export interface AmpRuntimeConfig {
     /** Amp uses its configured model; reserved for forward-compatibility. */
     model?: string;
 }
-export declare function createAmpRuntime(config?: AmpRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
-declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export declare function createAmpRuntime(config?: AmpRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
 export default _default;

package/dist/runtimes/cli-agent-acp-live.test.d.ts

@@ -0,0 +1,30 @@
+/**
+ * WS-C / ADR-0020 Increment 2 — END-TO-END transport tests for the live ACP
+ * path. Unlike `cli-agent.test.ts` (which drives `AcpClientPeer` over an
+ * in-memory cross-piped `TransformStream` against a fake `AgentSideConnection`
+ * in the SAME process), these spawn a REAL child process — the committed
+ * `__fixtures__/fake-acp-agent.mjs` — through
+ * `makeLocalSandboxProvider().commands.spawnDuplex` and drive a full
+ * `CliAgentRunner.sendMessage` turn against it.
+ *
+ * Why this matters: the in-memory fixtures never exercise stdin *delivery*. The
+ * historical no-duplex-stdin reality (the @vercel/sandbox server→sandbox
+ * boundary) meant a spawned "ACP" process never received the client's
+ * `initialize` frame, so the handshake hung and the runner fell back to JSONL.
+ * Increment 2's `commands.spawnDuplex` on the local provider is a genuine
+ * `child_process` pipe; these tests prove the JSON-RPC duplex round-trips over
+ * real OS pipes — `initialize` / `session/new` / `session/prompt` frames go
+ * DOWN the child's stdin and `session/update` notifications + results come back
+ * UP its stdout — end to end, with no in-memory shortcut.
+ *
+ * Three scenarios, one fake agent (mode selected via `FAKE_ACP_MODE`):
+ *   1. full turn       — init → thinking/text/tool_use/tool_result/plan/usage → done
+ *   2. cancel mid-turn — AbortSignal fires; session/cancel is sent; turn unwinds
+ *   3. deny-gate       — a denyTools-style processor rejects a tool over ACP
+ *                        WITHOUT ctx.pause (gateToolCall deny → reject option)
+ *
+ * The in-memory normaliser/lifecycle/fallback/pause suites in
+ * `cli-agent.test.ts` stay green — they validate the mapping; these validate
+ * the wire.
+ */
+export {};

package/dist/runtimes/cli-agent.test.d.ts

@@ -1,9 +1,25 @@
 /**
- * CliAgentRunner self-provisioning — the runtime installs its CLI on demand
- * (`command -v <bin>` → install if missing), runs the install at most once per
- * runner, and surfaces an install failure as an `error` message rather than
- * blowing up. This is what lets `createCodexRuntime()` work on a bare sandbox
- * with no image baking, and lets `snapshots: { bootFrom: "reuse" }` collapse
- * the install to a one-time cost.
+ * WS-C / ADR-0020 — fixture-based parity + lifecycle tests for the ACP path.
+ *
+ * There is NO live Codex/Amp/Gemini CLI in the test sandbox, so parity is
+ * proven against fixtures rather than a running agent (design doc §Parity-test
+ * strategy). Two equivalent fixture sets live under `__fixtures__/`:
+ *
+ *   - `acp/codex/<case>.ndjson`   — ACP `session/update` notifications (one per
+ *     line), plus, for the usage/error cases, a single `PromptResponse`.
+ *   - `jsonl/codex/<case>.jsonl`  — the EQUIVALENT legacy codex JSONL events the
+ *     current `codexSpec.mapEvent` consumes.
+ *
+ * The parity gate feeds each ACP fixture through the single `normalizeSessionUpdate`
+ * normaliser and the JSONL fixture through `codexSpec.mapEvent`, then asserts the
+ * two `AgentMessage` arrays are EQUAL MODULO `timestamp` (timestamps are
+ * now()-derived; we strip them before comparing). New-kind cases (`plan`,
+ * structured `diffs`) have no legacy counterpart — they assert the normaliser
+ * output against a golden directly.
+ *
+ * The lifecycle / fallback / pause suites drive the REAL `AcpClientPeer` over an
+ * in-memory `ndJsonStream` duplex against a fake `AgentSideConnection`, so the
+ * synthesised init/done ordering, the version-1 handshake fallback, and the
+ * PauseSignal-propagation invariant are exercised end-to-end with no subprocess.
  */
 export {};

package/dist/runtimes/codex.d.ts

@@ -12,10 +12,15 @@
  * Verified against codex-cli 0.124.0: `codex exec --json` + resume-by-thread,
  * with the command_execution / reasoning / agent_message item shapes below.
  */
+import { type CliAgentSpec } from "./_cli-agent.js";
+/** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
+ *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
+ *  of the public runtime surface — `createCodexRuntime` stays the entry point. */
+export declare const codexSpec: CliAgentSpec;
 export interface CodexRuntimeConfig {
     /** Codex model id (`-m`). Omit to use the codex CLI's configured default. */
     model?: string;
 }
-export declare function createCodexRuntime(config?: CodexRuntimeConfig): import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
-declare const _default: import("../index.js").AgentRuntime<import("../sandbox.js").SandboxProvider>;
+export declare function createCodexRuntime(config?: CodexRuntimeConfig): import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
+declare const _default: import("../index.js").AgentRuntime<import("../index.js").SandboxProvider>;
 export default _default;