@agent-compose/sdk 0.5.8 → 0.6.0

package/src/runtimes/_cli-agent.ts

@@ -24,10 +24,16 @@
  * 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 { defineRuntime } from "../types/runtime.js";
 import { AsyncQueue } from "../agent/async-queue.js";
 import { formatError } from "../utils/errors.js";
+import { ndJsonStream, type Stream } from "@agentclientprotocol/sdk";
+import { runProcessorChain } from "../processors/runner.js";
+import type { ProcessorContext, ToolCall } from "../processors/processor.js";
+import { RequestContext } from "../request-context/request-context.js";
+import { AcpClientPeer, ACP_PROTOCOL_VERSION } from "./_acp-client.js";
+import { isPauseSignal, boundProcessorPause } from "../pause/pause-core.js";
 
 function now(): string { return new Date().toISOString(); }
 
@@ -36,6 +42,47 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/** Internal sentinel yielded by `sendMessageAcp` to signal the version-check
+ *  fallback: the ACP handshake didn't negotiate version 1, so `sendMessage`
+ *  must drive the legacy JSONL path for this (and every later) turn. Not an
+ *  `AgentMessage` — filtered out before anything reaches the loop. */
+const ACP_FALLBACK = Symbol("acp-fallback");
+
+/** 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 const ACP_HANDSHAKE_TIMEOUT_MS = Number(process.env.AC_ACP_HANDSHAKE_TIMEOUT_MS) || 10_000;
+
+/** 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 const ACP_TRANSPORT_READY = true;
+
+/** Race a promise against the handshake deadline. On timeout, rejects with a
+ *  marker error so `sendMessageAcp` falls back to JSONL (same as a handshake
+ *  error). The timer is cleared on settle so it never keeps the process alive. */
+async function withHandshakeTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`ACP handshake timed out after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 /** 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 {
@@ -64,15 +111,87 @@ export interface CliAgentSpec {
   buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string }): 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> };
+}
+
+/** A spawned ACP-mode CLI: the read side of its stdout and a delivery for its
+ *  stdin, wrapped as byte web-streams for `ndJsonStream`. Producing this is a
+ *  below-ACP transport concern (the duplex command primitive) — see
+ *  `spawnAcpProcess`. */
+interface AcpProcess {
+  /** Duplex byte stream: `readable` = subprocess stdout, `writable` = stdin. */
+  stream: Stream;
+  /** Resolves when the subprocess exits (with its exit code). */
+  exited: Promise<{ exitCode: number; stderr: string }>;
+  /** Force-terminate the subprocess and release the stream. */
+  kill(): void;
 }
 
 export class CliAgentRunner implements ModelExecutionContract {
   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(): boolean {
+    return this.spec.acp !== undefined
+      && this.acpTransportReady
+      && typeof this.sandbox.commands.spawnDuplex === "function";
+  }
+
+  /** 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 {
+    return this.acpCapable;
+  }
+  /** 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: "acp" | "jsonl" | undefined;
+  /** 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: { proc: AcpProcess; peer: AcpClientPeer; sessionId: string } | undefined;
+  /** 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: ProcessorContext | undefined;
+  /** 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 = ACP_TRANSPORT_READY;
 
   constructor(
     private readonly sandbox: SandboxProvider,
@@ -83,10 +202,49 @@ export class CliAgentRunner implements ModelExecutionContract {
     this.kind = spec.kind;
   }
 
+  /** 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 {
+    this.acpTransportReady = true;
+  }
+
   get model(): string | undefined {
     return this.configModel ?? this.options.model ?? this.spec.defaultModel;
   }
 
+  /** 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). */
+  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;
+  }
+
+  private buildProcCtx(signal: AbortSignal | undefined, iteration: number | undefined): ProcessorContext {
+    const agentId = this.options.agentId ?? "agent";
+    const iter = iteration ?? 1;
+    return {
+      requestContext: this.options.requestContext ?? RequestContext.fromReserved({
+        teamId: "", runId: "", workflowId: "",
+        factoryId: null, apiKeyScopes: [], parentRunId: null,
+      }),
+      abortSignal: signal ?? new AbortController().signal,
+      retryCount: 0,
+      agentId,
+      iteration: iter,
+      // Wire the pause boundary so a permission-gate processor can raise a
+      // human-approval `ctx.pause` from inside `gateToolCall` (the ACP
+      // `session/request_permission` path). pauseId is keyed on agentId+iteration
+      // so it stays stable across the mid-turn pause/resume.
+      pause: boundProcessorPause(this.options.pause, { agentId, iteration: iter }),
+    };
+  }
+
   private installed = false;
 
   /** Provision the CLI on demand. A no-op once `bin` is on PATH — the steady
@@ -115,8 +273,263 @@ export class CliAgentRunner implements ModelExecutionContract {
     iteration?: number;
     signal?: AbortSignal;
   }): AsyncGenerator<AgentMessage> {
+    // Synthesised init stays runner-side (unchanged loop contract): yield before
+    // any spawn/handshake so `lastSessionId` is set even on an early failure.
     yield { type: "init", sessionId: opts.sessionId ?? "", timestamp: now() };
 
+    // ACP path when the spec declares an `acp` invocation, the live transport is
+    // ready, the provider exposes the duplex-stdin primitive (`acpCapable`), AND
+    // we haven't already fallen back to JSONL for this runner. A provider without
+    // `commands.spawnDuplex` (the server→sandbox vercel/e2b view) goes straight
+    // to JSONL — no wasted handshake. The handshake inside `sendMessageAcp` then
+    // decides per-process: a non-1 negotiated version, a handshake error, OR the
+    // handshake watchdog firing closes the ACP peer and yields `ACP_FALLBACK`
+    // so we drive the legacy JSONL path instead — a pinned-old CLI is never
+    // stranded, and a non-responding CLI can't hang the run.
+    if (this.acpCapable && this.acpDecision !== "jsonl") {
+      let fellBack = false;
+      try {
+        for await (const ev of this.sendMessageAcp(opts)) {
+          if (ev === ACP_FALLBACK) { fellBack = true; break; }
+          yield ev;
+        }
+      } catch (err) {
+        // A PauseSignal re-raised from the permission handler is control flow,
+        // NOT an error — let it propagate past sendMessage so it unwinds to
+        // serveStep and the run_pauses row is written (ADR-0020 Q4 / ADR-0006).
+        // Swallowing it here as `{type:"error"}` is the exact bug the design
+        // warns against.
+        if (isPauseSignal(err)) throw err;
+        yield { type: "error", text: formatError(err), timestamp: now() };
+        return;
+      }
+      if (!fellBack) { this.acpDecision = "acp"; return; }
+      this.acpDecision = "jsonl";
+      // fall through to the legacy path below for THIS turn
+    }
+
+    yield* this.sendMessageJsonl(opts);
+  }
+
+  /**
+   * 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 async teardownAcp(proc: AcpProcess, peer: AcpClientPeer): Promise<void> {
+    peer.close();
+    // EOF on stdin lets a conformant CLI exit on its own; group-kill is the
+    // backstop for one that ignores it. Both are best-effort.
+    try { await proc.stream.writable.close(); } catch { /* already closing/closed */ }
+    proc.kill();
+    proc.exited.catch(() => { /* abandoned process — don't leak an unhandled rejection */ });
+  }
+
+  /**
+   * 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 async ensureAcpSession(opts: {
+    iteration?: number;
+    signal?: AbortSignal;
+  }): Promise<{ proc: AcpProcess; peer: AcpClientPeer; sessionId: string } | null> {
+    if (this.acpSession) return this.acpSession;
+
+    await this.ensureInstalled();
+
+    const acp = this.spec.acp!;
+    const proc = this.spawnAcpProcess(acp, opts.signal);
+    const peer = new AcpClientPeer({
+      stream: proc.stream,
+      gateToolCall: (call, ctx) => this.gateToolCall(call, ctx),
+      // Provider, NOT a frozen value: the peer outlives a single turn, so it
+      // must read the CURRENT turn's gate context (refreshed by sendMessageAcp)
+      // — otherwise a turn>=2 permission->pause computes its pauseId with the
+      // first turn's iteration and the resume can't recompute the same id.
+      procCtx: () => this.currentAcpProcCtx ?? this.buildProcCtx(opts.signal, opts.iteration),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+
+    let negotiated: number;
+    try {
+      // Watchdog the handshake: `peer.initialize()` resolves ONLY when the agent
+      // answers. A CLI that never speaks ACP (or blocks on stdin) would hang
+      // here forever and the JSONL fallback would never be reached, so race a
+      // hard deadline. A timeout is treated identically to a handshake error.
+      ({ protocolVersion: negotiated } = await withHandshakeTimeout(peer.initialize(), ACP_HANDSHAKE_TIMEOUT_MS));
+    } catch {
+      // The process doesn't speak ACP (no valid JSON-RPC response, or it never
+      // answered within the deadline) — tear down and fall back.
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+    if (negotiated !== ACP_PROTOCOL_VERSION) {
+      // A pinned-old CLI negotiating a different wire version: fall back rather
+      // than strand it.
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+
+    // `session/new` is the second handshake round-trip — watchdog it too, so a
+    // CLI that negotiates a version then stalls before opening a session still
+    // falls back rather than hanging. This is the ONLY `session/new` for the
+    // runner's lifetime; every later turn reuses this session id.
+    let sessionId: string;
+    try {
+      sessionId = await withHandshakeTimeout(peer.startSession(this.options.cwd ?? "/"), ACP_HANDSHAKE_TIMEOUT_MS);
+    } catch {
+      await this.teardownAcp(proc, peer);
+      return null;
+    }
+
+    this.acpSession = { proc, peer, sessionId };
+    return this.acpSession;
+  }
+
+  /**
+   * 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 async *sendMessageAcp(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+  }): AsyncGenerator<AgentMessage | typeof ACP_FALLBACK> {
+    // Refresh the per-turn gate context BEFORE prompting. The persistent peer
+    // reads it via its `procCtx` provider, so a permission->pause on THIS turn
+    // binds to THIS turn's iteration → the pauseId recomputes identically on
+    // resume. (Freezing it at peer construction mis-keyed every turn>=2 pause.)
+    this.currentAcpProcCtx = this.buildProcCtx(opts.signal, opts.iteration);
+    const session = await this.ensureAcpSession(opts);
+    if (!session) { yield ACP_FALLBACK; return; }
+    const { proc, peer, sessionId } = session;
+
+    // Prompt-turn watchdog: a turn must make progress within the deadline or we
+    // tear down. Unlike the handshake watchdog this does NOT fall back to JSONL
+    // (we've already committed to ACP for this runner) — it cancels the stalled
+    // turn and surfaces an error. The deadline is reset on every yielded message
+    // so a legitimately long, *streaming* turn is never killed; only a turn that
+    // goes fully silent (the documented Gemini-style hang, ADR-0020 risks) trips
+    // it. `peer.cancel()` sends `session/cancel` AND trips the peer's abort latch
+    // so the in-flight `session/prompt` unblocks deterministically rather than
+    // hanging on a reply a stalled CLI never sends.
+    //
+    // We do NOT close the peer here on a clean turn end: the peer wraps the
+    // persistent connection, reused by the next turn's `session/prompt`. The
+    // persistent process is killed only on the abort signal (wired in
+    // `spawnAcpProcess`) or group-killed below on a stall, and otherwise
+    // reclaimed when the sandbox VM is torn down at run-end.
+    let sawError = false;
+    let stalled = false;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+    const armWatchdog = () => {
+      if (watchdog) clearTimeout(watchdog);
+      watchdog = setTimeout(() => { stalled = true; peer.cancel(); }, ACP_HANDSHAKE_TIMEOUT_MS);
+    };
+    try {
+      armWatchdog();
+      for await (const msg of peer.prompt(opts.prompt)) {
+        armWatchdog();
+        if (msg.type === "error") sawError = true;
+        yield msg;
+      }
+    } finally {
+      if (watchdog) clearTimeout(watchdog);
+    }
+    if (stalled && !sawError) {
+      // A wedged CLI can't continue — group-kill the persistent process, drop
+      // the cached session (a later turn would only re-stall on the dead peer),
+      // and surface the stall as an error.
+      await this.teardownAcp(proc, peer);
+      this.acpSession = undefined;
+      yield { type: "error", text: `${this.spec.kind} prompt turn stalled (no activity for ${ACP_HANDSHAKE_TIMEOUT_MS}ms)`, timestamp: now() };
+      return;
+    }
+
+    if (!sawError) yield { type: "done", sessionId: peer.currentSessionId ?? sessionId, timestamp: now() };
+  }
+
+  /**
+   * 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(
+    acp: { command: string; args: string[]; env?: Record<string, string> },
+    signal: AbortSignal | undefined,
+  ): AcpProcess {
+    const spawnDuplex = this.sandbox.commands.spawnDuplex;
+    if (!spawnDuplex) {
+      // Defensive: the capability check in sendMessage must keep this path off a
+      // provider without duplex. Reaching here is a programming error.
+      throw new Error("spawnAcpProcess called on a provider without commands.spawnDuplex");
+    }
+
+    const cmd = `${acp.command} ${acp.args.map(shellQuote).join(" ")}`.trim();
+    const agentEnv = { ...acp.env };
+    const proc = spawnDuplex.call(this.sandbox.commands, cmd, {
+      ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
+      ...(Object.keys(agentEnv).length > 0 ? { envs: agentEnv } : {}),
+    });
+
+    const kill = () => proc.kill();
+    if (signal) {
+      if (signal.aborted) kill();
+      else signal.addEventListener("abort", kill, { once: true });
+    }
+
+    return { stream: ndJsonStream(proc.stdin, proc.stdout), exited: proc.exited, kill };
+  }
+
+  /**
+   * 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 async *sendMessageJsonl(opts: {
+    prompt: string;
+    sessionId?: string;
+    iteration?: number;
+    signal?: AbortSignal;
+  }): AsyncGenerator<AgentMessage> {
     let sessionId = opts.sessionId;
     let sawError = false;
     try {

package/src/runtimes/claude.ts

@@ -8,6 +8,7 @@ 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";
+import { boundProcessorPause } from "../pause/pause-core.js";
 import { formatError } from "../utils/errors.js";
 
 function now(): string { return new Date().toISOString(); }
@@ -199,12 +200,15 @@ export class ClaudeRunner implements ModelExecutionContract {
         toolInput: (pre.tool_input ?? {}) as Record<string, unknown>,
         toolUseId: toolUseId ?? `${pre.tool_name}-${Date.now()}`,
       };
+      const gateAgentId = this.options.agentId ?? "agent";
+      const gateIteration = opts.iteration ?? 1;
       const gate = await this.gateToolCall(call, {
         requestContext,
         abortSignal: signal ?? opts.signal ?? new AbortController().signal,
         retryCount: 0,
-        agentId: this.options.agentId ?? "agent",
-        iteration: opts.iteration ?? 1,
+        agentId: gateAgentId,
+        iteration: gateIteration,
+        pause: boundProcessorPause(this.options.pause, { agentId: gateAgentId, iteration: gateIteration }),
       });
       if (gate.kind === "allow") return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "allow", updatedInput: gate.call.toolInput } };
       if (gate.kind === "deny") return { hookSpecificOutput: { hookEventName: pre.hook_event_name, permissionDecision: "deny", permissionDecisionReason: gate.reason } };
@@ -249,6 +253,26 @@ export class ClaudeRunner implements ModelExecutionContract {
     }
     const promptForQuery: string | AsyncIterable<SDKUserMessage> = inboxQueue ?? opts.prompt;
 
+    // Bridge the loop's abort signal into the Agent SDK's cancel knob
+    // (`query({ options: { abortController } })`). Without this the `signal` was
+    // accepted but never wired into query(), so a loop abort (cancellation, or a
+    // sibling agent's pause tearing the loop down) let the in-flight query run to
+    // completion — exactly what the loop's abort is supposed to prevent.
+    const queryAbort = new AbortController();
+    const onLoopAbort = () => queryAbort.abort();
+    if (opts.signal) {
+      if (opts.signal.aborted) queryAbort.abort();
+      else opts.signal.addEventListener("abort", onLoopAbort, { once: true });
+    }
+
+    // System-prompt append: the platform manual (agentManual, threaded from
+    // agent()) + any caller-supplied claudeMdContent. The Agent SDK does NOT
+    // auto-load CLAUDE.md from cwd (no settingSources), so without this the
+    // agent never reliably sees the manual — including how to pause.
+    const systemPromptAppend = [this.config.claudeMdContent, this.options.agentManual]
+      .filter((s): s is string => Boolean(s && s.trim()))
+      .join("\n\n");
+
     try {
       let emittedAssistantText = false;
       for await (const message of query({
@@ -262,11 +286,12 @@ export class ClaudeRunner implements ModelExecutionContract {
           thinking: resolveThinking(this.model, this.config.thinking),
           effort: this.config.effort,
           cwd: this.options.cwd,
+          abortController: queryAbort,
           env: { ...process.env, ...(this.config.env ?? {}) },
           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 } } : {}),
+          ...(systemPromptAppend ? { systemPrompt: { type: "preset" as const, preset: "claude_code" as const, append: systemPromptAppend } } : {}),
           // Turn skills ON (and auto-add the `Skill` tool). The agent-env
           // bakes the `/ac:*` skills; without this the Agent SDK leaves
           // them un-enabled and the agent can't invoke them.
@@ -314,6 +339,9 @@ export class ClaudeRunner implements ModelExecutionContract {
       // Belt-and-braces — close on error/abort too so the dangling
       // iterable doesn't leak the inboxStream consumer.
       inboxQueue?.close();
+      // Detach the abort bridge (no-op if it already fired, {once:true}) so a
+      // completed turn doesn't leak a listener on the long-lived loop signal.
+      opts.signal?.removeEventListener("abort", onLoopAbort);
     }
   }
 }

package/src/runtimes/codex.ts

@@ -19,10 +19,30 @@ import { formatError } from "../utils/errors.js";
 
 function now(): string { return new Date().toISOString(); }
 
-const codexSpec: CliAgentSpec = {
+/** Pinned codex-acp adapter version. The README warns "breaking changes
+ *  likely", so we pin exact (not a range) and bump deliberately. `CODEX_PATH`
+ *  overrides the bundled `@openai/codex` the adapter drives underneath. */
+const CODEX_ACP_ADAPTER = "@agentclientprotocol/codex-acp@0.1.0";
+
+/** 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 const codexSpec: CliAgentSpec = {
   kind: "codex",
   authEnv: "CODEX_API_KEY",
   bin: "codex",
+  // ACP-mode invocation (ADR-0020 increment 1). `codex` has no native `--acp`
+  // flag; the adapter (a Rust binary shipped via npm) speaks ACP and drives a
+  // compatible bundled `@openai/codex`. The runner attempts this first and
+  // falls back to the legacy `codex exec --json` JSONL spec below if the
+  // version-1 handshake fails.
+  acp: {
+    command: "npx",
+    args: ["-y", CODEX_ACP_ADAPTER],
+    // CODEX_PATH lets an operator point the adapter at a specific codex binary
+    // (e.g. a sandbox-baked one) instead of the adapter's bundled copy.
+    ...(process.env.CODEX_PATH ? { env: { CODEX_PATH: process.env.CODEX_PATH } } : {}),
+  },
   // Global npm install; symlink onto PATH only if the global bin dir isn't
   // already there (so a non-login `sh -c` can find it).
   install: 'sudo npm install -g @openai/codex && (command -v codex >/dev/null 2>&1 || sudo ln -sf "$(npm prefix -g)/bin/codex" /usr/local/bin/codex)',

package/src/runtimes/vercel.ts

@@ -10,6 +10,7 @@ import { codingTools, type CodingTool } from "../tools/index.js";
 import { runProcessorChain } from "../processors/runner.js";
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
+import { boundProcessorPause } from "../pause/pause-core.js";
 import { formatError } from "../utils/errors.js";
 
 type AiToolSet = Record<string, ReturnType<typeof tool<Record<string, unknown>, string>>>;
@@ -153,12 +154,14 @@ export class VercelRunner implements ModelExecutionContract {
             teamId: "", runId: "", workflowId: "",
             factoryId: null, apiKeyScopes: [], parentRunId: null,
           });
+          const gateAgentId = this.options.agentId ?? "agent";
           const gate = await this.gateToolCall(call, {
             requestContext,
             abortSignal: execOpts.abortSignal ?? signal ?? new AbortController().signal,
             retryCount: 0,
-            agentId: this.options.agentId ?? "agent",
+            agentId: gateAgentId,
             iteration,
+            pause: boundProcessorPause(this.options.pause, { agentId: gateAgentId, iteration }),
           });
           if (gate.kind === "deny") return gate.reason;
           if (gate.kind === "abort") throw new Error(gate.reason);