@agent-compose/sdk 0.5.8 → 0.6.0

package/src/runtimes/_acp-client.ts

@@ -0,0 +1,516 @@
+/**
+ * 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 {
+  ClientSideConnection,
+  RequestError,
+  type Agent,
+  type Client,
+  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";
+import { AsyncQueue } from "../agent/async-queue.js";
+import { isPauseSignal } from "../pause/pause-core.js";
+import { formatError } from "../utils/errors.js";
+
+function now(): string { return new Date().toISOString(); }
+
+/** 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 const ACP_PROTOCOL_VERSION = 1;
+
+/** Permission option ids we answer `session/request_permission` with. The agent
+ *  presents its own `options`; we pick the one whose `kind` matches our verdict.
+ *  When no matching option is offered we fall back to these (a conformant agent
+ *  always offers an allow + a reject option). */
+const OPTION_KIND_FOR_VERDICT = {
+  allow: ["allow_once", "allow_always"],
+  deny: ["reject_once", "reject_always"],
+} as const;
+
+/** 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;
+}
+
+// ── The single session/update → AgentMessage normaliser ───────────────────────
+
+/** Pull readable text out of an ACP `ContentBlock` (text blocks only; image /
+ *  audio / resource produce no text). */
+function contentBlockText(block: acp.ContentBlock | undefined): string {
+  if (!block) return "";
+  return block.type === "text" ? block.text : "";
+}
+
+/** Render a tool call's `content[]` (content / diff / terminal blocks) to a
+ *  readable string for the MVP renderer, and collect structured `diffs`.
+ *  `terminal` blocks become a reference line (we never resolve `terminalId` —
+ *  no terminal capability advertised). */
+function renderToolContent(
+  content: acp.ToolCallContent[] | null | undefined,
+): { output: string; diffs: { path: string; oldText: string | null; newText: string }[] } {
+  const parts: string[] = [];
+  const diffs: { path: string; oldText: string | null; newText: string }[] = [];
+  for (const block of content ?? []) {
+    if (block.type === "content") {
+      parts.push(contentBlockText(block.content));
+    } else if (block.type === "diff") {
+      diffs.push({ path: block.path, oldText: block.oldText ?? null, newText: block.newText });
+      const header = block.oldText == null ? `--- (new file)\n+++ ${block.path}` : `--- ${block.path}\n+++ ${block.path}`;
+      parts.push(`${header}\n${block.newText}`);
+    } else if (block.type === "terminal") {
+      parts.push(`[terminal ${block.terminalId}]`);
+    }
+  }
+  return { output: parts.filter((p) => p !== "").join("\n"), diffs };
+}
+
+function mapLocations(
+  locations: acp.ToolCallLocation[] | null | undefined,
+): { path: string; line?: number }[] | undefined {
+  if (!locations || locations.length === 0) return undefined;
+  return locations.map((l) => (l.line != null ? { path: l.path, line: l.line } : { path: l.path }));
+}
+
+/** Build the `tool_result` for a terminal (`completed` / `failed`) tool call.
+ *  Shared by the `tool_call_update` branch (the streaming, two-message shape)
+ *  AND the `tool_call` start branch (a fast/sync tool that arrives already
+ *  terminal with content/locations and no follow-up `tool_call_update`) — both
+ *  must render diffs/locations/output identically (ADR-0020 Q3). */
+function terminalToolResult(args: {
+  toolCallId: string;
+  status: "completed" | "failed";
+  content: acp.ToolCallContent[] | null | undefined;
+  locations: acp.ToolCallLocation[] | null | undefined;
+  timestamp: string;
+}): AgentMessage {
+  const { output, diffs } = renderToolContent(args.content);
+  const locations = mapLocations(args.locations);
+  return {
+    type: "tool_result",
+    toolUseId: args.toolCallId,
+    output,
+    isError: args.status === "failed",
+    timestamp: args.timestamp,
+    ...(diffs.length > 0 ? { diffs } : {}),
+    ...(locations ? { locations } : {}),
+  };
+}
+
+/**
+ * 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 function normalizeSessionUpdate(update: acp.SessionUpdate): AgentMessage[] {
+  const ts = now();
+  switch (update.sessionUpdate) {
+    case "agent_message_chunk":
+      return [{ type: "text", text: contentBlockText(update.content), timestamp: ts }];
+
+    case "agent_thought_chunk":
+      return [{ type: "thinking", text: contentBlockText(update.content), timestamp: ts }];
+
+    case "tool_call": {
+      // Always emit the tool_use. A `tool_call` start is the symmetric partner
+      // of the legacy codex `item.started` → tool_use mapping.
+      const messages: AgentMessage[] = [{
+        type: "tool_use",
+        toolName: update.title || update.kind || "tool",
+        toolInput: (update.rawInput ?? {}) as Record<string, unknown>,
+        toolUseId: update.toolCallId,
+        timestamp: ts,
+      }];
+      // ACP permits a `tool_call` to arrive ALREADY terminal (a fast/sync tool:
+      // status completed|failed carrying content/locations/rawOutput, with NO
+      // follow-up `tool_call_update`). The legacy codex path always produces a
+      // tool_result, so the ACP path must too — emit the same tool_result the
+      // `tool_call_update` terminal branch produces (ADR-0020 Q3).
+      if (update.status === "completed" || update.status === "failed") {
+        messages.push(terminalToolResult({
+          toolCallId: update.toolCallId,
+          status: update.status,
+          content: update.content,
+          locations: update.locations,
+          timestamp: ts,
+        }));
+      }
+      return messages;
+    }
+
+    case "tool_call_update": {
+      // Only terminal statuses produce a tool_result. pending / in_progress are
+      // progress-only deltas merged by toolCallId downstream → no message.
+      if (update.status !== "completed" && update.status !== "failed") return [];
+      return [terminalToolResult({
+        toolCallId: update.toolCallId,
+        status: update.status,
+        content: update.content,
+        locations: update.locations,
+        timestamp: ts,
+      })];
+    }
+
+    case "plan":
+      return [{
+        type: "plan",
+        // Each `plan` notification carries the ENTIRE entries array (the agent
+        // replaces the whole plan each time); pass it through verbatim. ACP
+        // PlanEntryStatus is exactly pending | in_progress | completed.
+        entries: update.entries.map((e) => ({ content: e.content, priority: e.priority, status: e.status })),
+        timestamp: ts,
+      }];
+
+    // Echoed user input (only during session/load replay — not our stream),
+    // slash-command palette, mode switches, context-window gauge, and the
+    // experimental plan_update / plan_removed / config / session-info updates
+    // are not part of our contract → no message.
+    case "user_message_chunk":
+    case "available_commands_update":
+    case "current_mode_update":
+    case "usage_update":
+    case "plan_update":
+    case "plan_removed":
+    case "config_option_update":
+    case "session_info_update":
+      return [];
+
+    default:
+      // Unknown / future variant — never throw; the contract is defensive.
+      return [];
+  }
+}
+
+// ── The peer ──────────────────────────────────────────────────────────────────
+
+export class AcpClientPeer {
+  private readonly conn: ClientSideConnection;
+  /** 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 = new AsyncQueue<AgentMessage>();
+  /** Live session id (from `session/new` / `session/resume`), needed by
+   *  `session/cancel`. */
+  private sessionId: string | undefined;
+  /** 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: unknown = null;
+  private cancelled = false;
+  /** 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: (() => void) | null = null;
+
+  constructor(private readonly deps: AcpClientPeerDeps) {
+    // The client handler. Methods we DON'T define (writeTextFile / readTextFile)
+    // and the terminal methods are simply absent — we advertise no fs/terminal
+    // capability, so a conformant agent never calls them; if one does the SDK
+    // answers method-not-found.
+    const handler: Client = {
+      sessionUpdate: (params: acp.SessionNotification): void => {
+        // Push mapped messages onto the queue. Tolerate updates that race in
+        // after cancel (the agent may flush a few before unwinding) — the
+        // normaliser handles them the same way.
+        for (const msg of normalizeSessionUpdate(params.update)) this.updates.push(msg);
+      },
+      requestPermission: (params: acp.RequestPermissionRequest) => this.onRequestPermission(params),
+    };
+    this.conn = new ClientSideConnection((_agent: Agent) => handler, this.deps.stream);
+
+    // Wire cancel: on abort, send session/cancel for the live session.
+    if (this.deps.signal) {
+      if (this.deps.signal.aborted) this.cancel();
+      else this.deps.signal.addEventListener("abort", () => this.cancel(), { once: true });
+    }
+  }
+
+  /**
+   * 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.
+   */
+  async initialize(): Promise<{ protocolVersion: number }> {
+    const res = await this.conn.initialize({
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+      },
+    });
+    return { protocolVersion: res.protocolVersion };
+  }
+
+  /**
+   * 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).
+   */
+  async startSession(cwd: string): Promise<string> {
+    const res = await this.conn.newSession({ cwd, mcpServers: [] });
+    this.sessionId = res.sessionId;
+    return res.sessionId;
+  }
+
+  /**
+   * 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`.
+   */
+  async *prompt(text: string): AsyncGenerator<AgentMessage> {
+    if (!this.sessionId) throw new Error("AcpClientPeer.prompt called before startSession");
+
+    // Fresh updates queue for THIS turn. The peer is long-lived and reused
+    // across turns (one persistent ACP process / session), but an `AsyncQueue`
+    // is single-use — once closed it stays drained — so the previous turn's
+    // queue can't carry this turn's `session/update`s. Swap in a new one and
+    // bind a local alias the closures below capture, so closing "the turn's
+    // queue" always means this turn's, never a later turn's.
+    const updates = new AsyncQueue<AgentMessage>();
+    this.updates = updates;
+
+    // Abort latch: `cancel()` / `close()` trips this to unblock the turn even if
+    // the agent never resolves the outstanding `session/prompt` request (a dead
+    // or fully-silent CLI). Resolving it closes the updates queue (ending the
+    // for-await) and races the prompt result so the await below can't hang.
+    const aborted = new Promise<void>((resolve) => {
+      this.abortPrompt = () => { resolve(); updates.close(); };
+    });
+    // If cancel already fired before the prompt started (abort-before-prompt
+    // race), trip immediately.
+    if (this.cancelled) this.abortPrompt!();
+
+    // Kick off the prompt; do NOT await yet — drain updates while it runs, then
+    // close the queue when the turn resolves so the for-await below terminates.
+    const promptPromise = this.conn
+      .prompt({ sessionId: this.sessionId, prompt: [{ type: "text", text }] })
+      .then(
+        (res) => { updates.close(); return { ok: true as const, res }; },
+        (err) => { updates.close(); return { ok: false as const, err }; },
+      );
+
+    for await (const msg of updates) {
+      yield msg;
+    }
+
+    // A processor inside the permission handler asked for a human decision:
+    // re-raise so the pause unwinds to serveStep (ADR-0020 Q4). The outstanding
+    // session/prompt is abandoned as the subprocess exits; on resume the loop
+    // re-issues the turn against the persisted session.
+    if (this.pendingPause !== null) {
+      const pause = this.pendingPause;
+      this.pendingPause = null;
+      this.abortPrompt = null;
+      throw pause;
+    }
+
+    // The turn ended either because the prompt resolved (its `.then` closed the
+    // queue) or because the abort latch tripped. Race them so an aborted turn
+    // returns cleanly instead of awaiting a JSON-RPC reply the agent may never
+    // send. `cancelled` → no error, like a clean cancel stop reason.
+    const settled = await Promise.race([
+      promptPromise.then((o) => ({ kind: "prompt" as const, o })),
+      aborted.then(() => ({ kind: "aborted" as const })),
+    ]);
+    this.abortPrompt = null;
+    if (settled.kind === "aborted") return;
+
+    const outcome = settled.o;
+    if (!outcome.ok) {
+      yield { type: "error", text: formatError(outcome.err), timestamp: now() };
+      return;
+    }
+    const stopReason = outcome.res.stopReason;
+    if (stopReason === "refusal") {
+      yield { type: "error", text: "agent refused the request", timestamp: now() };
+      return;
+    }
+    // end_turn / max_tokens / max_turn_requests → clean end (the runner
+    // synthesises `done`). cancelled → end the turn with no error.
+
+    // Per-turn token usage rides the prompt result, not usage_update (Q1).
+    const usage = outcome.res.usage;
+    if (usage) {
+      yield {
+        type: "usage",
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadTokens: usage.cachedReadTokens ?? 0,
+        cacheCreationTokens: usage.cachedWriteTokens ?? 0,
+        durationMs: 0,
+        numTurns: 1,
+        timestamp: now(),
+      };
+    }
+  }
+
+  /** The live session id, or undefined before `startSession`. Threaded back
+   *  onto the synthesised `init` / `done` by the runner. */
+  get currentSessionId(): string | undefined {
+    return this.sessionId;
+  }
+
+  /** 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 {
+    if (this.cancelled) { this.abortPrompt?.(); return; }
+    this.cancelled = true;
+    // Send session/cancel when we have a live session; with or without one, trip
+    // the abort latch so an in-flight `prompt()` unblocks deterministically
+    // rather than waiting on a reply a cancelled/dead agent may never send.
+    if (this.sessionId) {
+      void this.conn.cancel({ sessionId: this.sessionId }).catch(() => { /* connection may already be closing */ });
+    }
+    this.abortPrompt?.();
+  }
+
+  /** 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 {
+    // Trip the in-flight turn (closes the updates queue too) so `prompt()`'s
+    // `await` can't hang on an outstanding `session/prompt` request.
+    this.abortPrompt?.();
+    this.updates.close();
+    // ClientSideConnection has no explicit close(); ending the stream closes it.
+    // Closing the writable is the caller's job (it owns the subprocess), so we
+    // only drain our queue here. The connection's `signal` aborts when the
+    // stream ends.
+  }
+
+  // ── Permission → gate → PermissionOption ────────────────────────────────────
+
+  // Permission → pause, wired end-to-end (WS-C increment 2b). An ACP
+  // `session/request_permission` runs the shared processor chain via
+  // `gateToolCall`; a human-approval processor (`humanApproval` / any processor
+  // calling `ctx.pause`) raises a `PauseSignal` here. This handler propagates it
+  // unswallowed — stashed in `pendingPause` and re-raised from `prompt()` so it
+  // unwinds to serveStep and the `run_pauses` row is written (ADR-0020 Q4 /
+  // ADR-0006). `ProcessorContext.pause` (processors/processor.ts), wired by the
+  // runtime's `buildProcCtx`, is the source. A gate can now allow / deny / abort
+  // / PAUSE.
+  private async onRequestPermission(
+    params: acp.RequestPermissionRequest,
+  ): Promise<acp.RequestPermissionResponse> {
+    // If the turn was cancelled, the protocol REQUIRES we answer cancelled.
+    if (this.cancelled || this.deps.signal?.aborted) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+
+    const tc = params.toolCall;
+    const call: ToolCall = {
+      toolName: tc.title || tc.kind || "tool",
+      toolInput: (tc.rawInput ?? {}) as Record<string, unknown>,
+      toolUseId: tc.toolCallId,
+    };
+
+    let verdict: ToolCallGateResult;
+    try {
+      // CRITICAL: do NOT wrap this in a catch that swallows everything. A
+      // processor requesting human approval throws `PauseSignal`, which is
+      // control flow, not an error — it must escape to `prompt()` and unwind to
+      // serveStep so the run_pauses row is written (ADR-0020 Q4 / ADR-0006).
+      verdict = await this.deps.gateToolCall(call, this.deps.procCtx());
+    } catch (err) {
+      if (isPauseSignal(err)) {
+        // Stash the signal for `prompt()` to re-raise, and answer the still-
+        // pending request as cancelled so the agent unwinds its turn while the
+        // subprocess is torn down by the pause.
+        this.pendingPause = err;
+        this.cancel();
+        return { outcome: { outcome: "cancelled" } };
+      }
+      throw err; // genuine error → JSON-RPC error response
+    }
+
+    if (verdict.kind === "abort") {
+      this.cancel();
+      return { outcome: { outcome: "cancelled" } };
+    }
+
+    const wantedKinds =
+      verdict.kind === "allow" ? OPTION_KIND_FOR_VERDICT.allow : OPTION_KIND_FOR_VERDICT.deny;
+    const option =
+      params.options.find((o) => (wantedKinds as readonly string[]).includes(o.kind)) ?? params.options[0];
+    if (!option) {
+      // No options offered at all — a non-conformant agent. Cancel rather than
+      // guess.
+      return { outcome: { outcome: "cancelled" } };
+    }
+    return { outcome: { outcome: "selected", optionId: option.optionId } };
+  }
+}
+
+// Re-export RequestError so callers building/handling JSON-RPC errors don't
+// reach into the SDK directly.
+export { RequestError };