@nanobpm/agentic 0.1.0 → 0.4.0

package/src/session/acp/client.ts

@@ -0,0 +1,356 @@
+/**
+ * The ACP ingestion backend — ADR 0062, slice 2 (the preferred adapter target).
+ *
+ * {@link AcpSessionClient} connects an ACP-speaking harness (reference:
+ * `opencode acp`; also Claude via `claude-code-acp`, the Gemini lineage) to a
+ * Slice-1 {@link SessionEventSink} — normalising the harness's `session/update`
+ * stream into canonical {@link SessionEvent}s and driving/steering the session
+ * over JSON-RPC. It realises the three ADR 0062 §5 primitives:
+ *
+ *  - `session/update` → **emit**: each notification is classified
+ *    ({@link classifyUpdate}), streamed message chunks are coalesced into whole
+ *    `assistant`/`reasoning`/`user` events, and the `tool_call`/`tool_call_update`
+ *    lifecycle becomes canonical `tool-call`/`tool-result` events.
+ *  - `session/load` → **restore**: replays the harness's prior history (delivered
+ *    as `session/update`s during the load) back into the sink.
+ *  - `agentCapabilities.loadSession` (from `initialize`) → the **durable-resume
+ *    capability probe** the nano-workforce enrolment gate (slice 5) consumes.
+ *
+ * This backend owns event **identity** and **causality** (the `id`/`parentId`
+ * chain) exactly as `events.ts` prescribes — ACP carries neither — while the sink
+ * (a {@link SessionAdapter}) owns ordering and fencing. Keeping those split lets a
+ * `SessionBackend` be passed straight in as the sink with no adapter.
+ */
+import { randomUUID } from "node:crypto";
+import type { SessionEvent } from "../events.ts";
+import { AcpConnection } from "./jsonrpc.ts";
+import { type AcpClassifiedUpdate, classifyUpdate } from "./normalize.ts";
+import {
+  ACP_CLIENT_METHOD,
+  ACP_METHOD,
+  ACP_PROTOCOL_VERSION,
+  type AcpPromptCapabilities,
+  isRecord,
+  parseInitializeResult,
+  parseSessionId,
+} from "./protocol.ts";
+import type { AcpTransport } from "./transport.ts";
+
+/**
+ * The narrow port the ingestion client writes canonical events to. A Slice-1
+ * {@link SessionAdapter} (e.g. a `SessionBackend`) satisfies it structurally, so
+ * the ACP stream can feed the authoritative log directly; a test can pass a
+ * plain collector.
+ */
+export interface SessionEventSink {
+  emit(event: SessionEvent): void;
+}
+
+/** A single ACP content block sent in a prompt. `text` is the baseline shape. */
+export interface AcpTextContentBlock {
+  readonly type: "text";
+  readonly text: string;
+}
+
+/** The prompt payload: a content-block array, or a bare string (wrapped as text). */
+export type AcpPromptInput = string | readonly AcpTextContentBlock[];
+
+/** The durable-resume capability probe read from the `initialize` handshake. */
+export interface AcpCapabilityProbe {
+  /** The protocol version the agent negotiated. */
+  readonly protocolVersion: number;
+  /** The raw `agentCapabilities.loadSession` flag. */
+  readonly loadSession: boolean;
+  /**
+   * The nano-workforce enrolment-gate signal (slice 5): `true` iff the agent can
+   * durably resume via `session/load`. Equal to {@link loadSession} — named for
+   * the gate that consumes it, so the enrolment site reads intent, not wire detail.
+   */
+  readonly durableResume: boolean;
+  /** The agent's advertised prompt-content capabilities. */
+  readonly promptCapabilities: AcpPromptCapabilities;
+  /** The full, unmodified `agentCapabilities` object for consumers that need more. */
+  readonly agentCapabilities: unknown;
+}
+
+/** The result of a completed `session/prompt`, plus the events it produced. */
+export interface AcpPromptResult {
+  /** The agent's stop reason (`end_turn`, `cancelled`, …) when it reports one. */
+  readonly stopReason: string | null;
+  /** The canonical events emitted while this prompt ran, in emission order. */
+  readonly events: readonly SessionEvent[];
+}
+
+/** Parameters shared by `session/new` and `session/load`. */
+export interface AcpSessionParams {
+  /** The session working directory (absolute path). */
+  readonly cwd: string;
+  /** MCP servers to attach; defaults to none. */
+  readonly mcpServers?: readonly unknown[];
+}
+
+export interface AcpSessionClientOptions {
+  /** Injectable event-id generator (deterministic tests). Default `crypto.randomUUID`. */
+  readonly newEventId?: () => string;
+  /** Client name/version reported in `initialize`. */
+  readonly clientInfo?: { readonly name: string; readonly version: string };
+  /**
+   * How to answer an agent's `session/request_permission`. Default: select the
+   * first "allow"-flavoured option the agent offers (or a cancel outcome when
+   * none is), so a driven session is never silently blocked on approval.
+   */
+  readonly onPermissionRequest?: (params: unknown) => unknown;
+}
+
+interface MessageBuffer {
+  readonly role: "assistant" | "reasoning" | "user";
+  readonly messageId: string | null;
+  readonly text: string;
+}
+
+/**
+ * The ACP ingestion client. Bind it to a transport and a sink, `initialize`, then
+ * either `newSession` + `prompt` (drive) or `restore` an existing session id.
+ */
+export class AcpSessionClient {
+  readonly #connection: AcpConnection;
+  readonly #sink: SessionEventSink;
+  readonly #newEventId: () => string;
+  readonly #clientInfo: { name: string; version: string };
+  #lastId: string | null = null;
+  #buffer: MessageBuffer | undefined;
+  #collector: SessionEvent[] | null = null;
+  #sessionId: string | undefined;
+
+  constructor(connection: AcpConnection, sink: SessionEventSink, options: AcpSessionClientOptions = {}) {
+    this.#connection = connection;
+    this.#sink = sink;
+    this.#newEventId = options.newEventId ?? randomUUID;
+    this.#clientInfo = options.clientInfo ?? { name: "nano-agentic", version: "0" };
+    const permit = options.onPermissionRequest ?? defaultPermissionResponse;
+    connection.onNotification(ACP_CLIENT_METHOD.sessionUpdate, (params) => this.#ingest(params));
+    connection.onRequest(ACP_CLIENT_METHOD.requestPermission, (params) => permit(params));
+  }
+
+  /** The active session id (after `newSession`/`restore`), or `undefined`. */
+  get sessionId(): string | undefined {
+    return this.#sessionId;
+  }
+
+  /**
+   * Perform the `initialize` handshake and return the durable-resume capability
+   * probe. Must be called before any `session/*` method.
+   */
+  async initialize(): Promise<AcpCapabilityProbe> {
+    const result = await this.#connection.request(ACP_METHOD.initialize, {
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: this.#clientInfo,
+    });
+    const parsed = parseInitializeResult(result);
+    return {
+      protocolVersion: parsed.protocolVersion,
+      loadSession: parsed.agentCapabilities.loadSession,
+      durableResume: parsed.agentCapabilities.loadSession,
+      promptCapabilities: parsed.agentCapabilities.promptCapabilities,
+      agentCapabilities: parsed.rawAgentCapabilities,
+    };
+  }
+
+  /** Open a fresh session (`session/new`); stores and returns its id. */
+  async newSession(params: AcpSessionParams): Promise<string> {
+    const result = await this.#connection.request(ACP_METHOD.sessionNew, {
+      cwd: params.cwd,
+      mcpServers: params.mcpServers ?? [],
+    });
+    this.#sessionId = parseSessionId(result);
+    return this.#sessionId;
+  }
+
+  /**
+   * **restore** — load an existing session (`session/load`). The agent replays its
+   * prior history as `session/update` notifications, which this client ingests
+   * into the sink; when the load resolves, the pending message is flushed. Returns
+   * the canonical events reconstructed from the replayed history, in order.
+   *
+   * Only valid against an agent whose probe reported `durableResume: true`.
+   */
+  async restore(sessionId: string, params: AcpSessionParams): Promise<readonly SessionEvent[]> {
+    const collected = await this.#collecting(() =>
+      this.#connection.request(ACP_METHOD.sessionLoad, {
+        sessionId,
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+      }),
+    );
+    this.#sessionId = sessionId;
+    return collected.events;
+  }
+
+  /**
+   * **drive** — send a prompt (`session/prompt`) and resolve when the turn ends.
+   * All assistant output arrives as `session/update` notifications and is emitted
+   * to the sink during the call; the final buffered message is flushed on
+   * completion.
+   */
+  async prompt(input: AcpPromptInput): Promise<AcpPromptResult> {
+    if (this.#sessionId === undefined) {
+      throw new Error("prompt requires an active session — call newSession() or restore() first");
+    }
+    const prompt = typeof input === "string" ? [{ type: "text", text: input }] : input;
+    const collected = await this.#collecting(() =>
+      this.#connection.request(ACP_METHOD.sessionPrompt, { sessionId: this.#sessionId, prompt }),
+    );
+    return { stopReason: readStopReason(collected.result), events: collected.events };
+  }
+
+  /** **steer** — request cancellation of the running turn (`session/cancel`, a notification). */
+  cancel(): void {
+    if (this.#sessionId === undefined) return;
+    this.#connection.notify(ACP_METHOD.sessionCancel, { sessionId: this.#sessionId });
+  }
+
+  /** Close the underlying connection and flush any pending buffered message. */
+  close(): void {
+    this.#flushMessage();
+    this.#connection.close();
+  }
+
+  async #collecting(op: () => Promise<unknown>): Promise<{ result: unknown; events: SessionEvent[] }> {
+    const events: SessionEvent[] = [];
+    const previous = this.#collector;
+    this.#collector = events;
+    try {
+      const result = await op();
+      // Every session/update queued before the response has been ingested by now
+      // (ordered transport delivery); flush the final in-flight message.
+      this.#flushMessage();
+      return { result, events };
+    } finally {
+      this.#collector = previous;
+    }
+  }
+
+  #ingest(params: unknown): void {
+    if (!isRecord(params)) return;
+    // session/update carries the target sessionId (ACP). Once this client is driving
+    // a session, ignore updates addressed to a *different* session — a late update
+    // from a previous session, or a misrouted one, must not corrupt this stream.
+    // Guarded on #sessionId being set: during session/load replay the id is not yet
+    // stored, and those updates legitimately belong to the session being restored.
+    const sessionId = params.sessionId;
+    if (this.#sessionId !== undefined && typeof sessionId === "string" && sessionId !== this.#sessionId) {
+      return;
+    }
+    const update = classifyUpdate(params.update);
+    switch (update.kind) {
+      case "message":
+        this.#appendMessage(update);
+        return;
+      case "tool-call": {
+        this.#flushMessage();
+        const { id, parentId } = this.#nextIdentity();
+        this.#push({ type: "tool-call", id, parentId, callId: update.callId, name: update.name, args: update.args });
+        return;
+      }
+      case "tool-result": {
+        this.#flushMessage();
+        const { id, parentId } = this.#nextIdentity();
+        this.#push({ type: "tool-result", id, parentId, callId: update.callId, ok: update.ok, result: update.result });
+        return;
+      }
+      case "ignored":
+        return;
+    }
+  }
+
+  #appendMessage(update: Extract<AcpClassifiedUpdate, { kind: "message" }>): void {
+    const buffer = this.#buffer;
+    if (buffer !== undefined && buffer.role === update.role && sameMessage(buffer.messageId, update.messageId)) {
+      this.#buffer = { role: buffer.role, messageId: buffer.messageId, text: buffer.text + update.text };
+      return;
+    }
+    this.#flushMessage();
+    this.#buffer = { role: update.role, messageId: update.messageId, text: update.text };
+  }
+
+  #flushMessage(): void {
+    const buffer = this.#buffer;
+    if (buffer === undefined) return;
+    this.#buffer = undefined;
+    const { id, parentId } = this.#nextIdentity();
+    switch (buffer.role) {
+      case "assistant":
+        this.#push({ type: "assistant", id, parentId, text: buffer.text });
+        return;
+      case "reasoning":
+        this.#push({ type: "reasoning", id, parentId, text: buffer.text });
+        return;
+      case "user":
+        this.#push({ type: "user", id, parentId, text: buffer.text });
+        return;
+    }
+  }
+
+  #nextIdentity(): { id: string; parentId: string | null } {
+    const id = this.#newEventId();
+    const parentId = this.#lastId;
+    this.#lastId = id;
+    return { id, parentId };
+  }
+
+  #push(event: SessionEvent): void {
+    this.#sink.emit(event);
+    this.#collector?.push(event);
+  }
+}
+
+/**
+ * Two message chunks belong to the same logical message when their `messageId`s
+ * are equal, or when neither carries one (the agent omitted it) — in which case
+ * consecutive same-role chunks coalesce until a role change or a tool boundary.
+ */
+function sameMessage(a: string | null, b: string | null): boolean {
+  if (a === null && b === null) return true;
+  return a === b;
+}
+
+function readStopReason(result: unknown): string | null {
+  if (isRecord(result) && typeof result.stopReason === "string") return result.stopReason;
+  return null;
+}
+
+/**
+ * Select the first option whose kind reads as an approval from a
+ * `session/request_permission` request, so a driven session proceeds without a
+ * human in the loop; cancel when the agent offers no allow option. Full
+ * interactive-permission and client-side `fs`/`terminal` support is out of this
+ * slice's scope (this backend advertises neither capability at `initialize`).
+ */
+function defaultPermissionResponse(params: unknown): unknown {
+  if (isRecord(params) && Array.isArray(params.options)) {
+    for (const option of params.options) {
+      if (!isRecord(option)) continue;
+      const kind = option.kind;
+      if (typeof kind === "string" && kind.startsWith("allow") && typeof option.optionId === "string") {
+        return { outcome: { outcome: "selected", optionId: option.optionId } };
+      }
+    }
+  }
+  // No "allow"-flavoured option (or no options at all): cancel, as documented,
+  // rather than silently selecting an arbitrary — possibly deny — option.
+  return { outcome: { outcome: "cancelled" } };
+}
+
+/**
+ * Open an ACP ingestion client over `transport`, emitting into `sink`. Wraps the
+ * transport in an {@link AcpConnection} and returns the ready client; call
+ * {@link AcpSessionClient.initialize} first.
+ */
+export function openAcpSession(
+  transport: AcpTransport,
+  sink: SessionEventSink,
+  options: AcpSessionClientOptions = {},
+): AcpSessionClient {
+  return new AcpSessionClient(new AcpConnection(transport), sink, options);
+}

package/src/session/acp/fake-agent.ts

@@ -0,0 +1,71 @@
+/**
+ * A scriptable in-memory fake ACP agent — test-only (excluded from the build,
+ * like `../test-db.ts`). It plays the *agent* side of the ACP peer over an
+ * {@link AcpTransport} so the client's `initialize`/`session/*` flow and the
+ * `session/update` → canonical `SessionEvent` normalisation can be exercised
+ * end-to-end without spawning a real `opencode acp` process.
+ *
+ * It reuses the production {@link AcpConnection} for its own peer, so the tests
+ * drive the exact JSON-RPC wire the real harness would.
+ */
+import { AcpConnection } from "./jsonrpc.ts";
+import { isRecord } from "./protocol.ts";
+import type { AcpTransport } from "./transport.ts";
+
+export interface FakeAcpAgentScript {
+  /** Advertised `agentCapabilities.loadSession` (the durable-resume probe). Default `false`. */
+  readonly loadSession?: boolean;
+  /** The protocol version the agent negotiates. Default `1`. */
+  readonly protocolVersion?: number;
+  /** `update` objects the agent streams (as `session/update`) while a prompt runs. */
+  readonly promptUpdates?: readonly unknown[];
+  /** The `stopReason` the `session/prompt` resolves with. Default `"end_turn"`. */
+  readonly promptStopReason?: string;
+  /** `update` objects the agent replays (as `session/update`) during `session/load`. */
+  readonly loadUpdates?: readonly unknown[];
+  /** The session id `session/new` hands out. Default `"sess-fake"`. */
+  readonly sessionId?: string;
+}
+
+function sessionIdOf(params: unknown, fallback: string): string {
+  if (isRecord(params) && typeof params.sessionId === "string") {
+    return params.sessionId;
+  }
+  return fallback;
+}
+
+/** Wire a fake agent onto `transport` and return its connection (for `close()`). */
+export function startFakeAcpAgent(transport: AcpTransport, script: FakeAcpAgentScript = {}): AcpConnection {
+  const connection = new AcpConnection(transport);
+  const sessionId = script.sessionId ?? "sess-fake";
+  const loadSession = script.loadSession ?? false;
+
+  connection.onRequest("initialize", () => ({
+    protocolVersion: script.protocolVersion ?? 1,
+    agentCapabilities: {
+      loadSession,
+      promptCapabilities: { image: false, audio: false, embeddedContext: false },
+    },
+    authMethods: [],
+  }));
+
+  connection.onRequest("session/new", () => ({ sessionId }));
+
+  connection.onRequest("session/load", (params) => {
+    const sid = sessionIdOf(params, sessionId);
+    for (const update of script.loadUpdates ?? []) {
+      connection.notify("session/update", { sessionId: sid, update });
+    }
+    return { modes: null, configOptions: null };
+  });
+
+  connection.onRequest("session/prompt", (params) => {
+    const sid = sessionIdOf(params, sessionId);
+    for (const update of script.promptUpdates ?? []) {
+      connection.notify("session/update", { sessionId: sid, update });
+    }
+    return { stopReason: script.promptStopReason ?? "end_turn" };
+  });
+
+  return connection;
+}

package/src/session/acp/index.ts

@@ -0,0 +1,68 @@
+/**
+ * `@nanobpm/agentic/session/acp` — the ACP ingestion backend (ADR 0062, slice 2).
+ *
+ * The preferred harness-facing backend of the `@nanobpm/agentic/session` contract
+ * (ADR 0062 §5): an Agent Client Protocol (protocol v1) client that connects to an
+ * ACP-speaking harness (`opencode acp`, `claude-code-acp`, the Gemini lineage),
+ * runs the `initialize` handshake to probe `agentCapabilities.loadSession`, and
+ * normalises the `session/update` stream into canonical {@link SessionEvent}s —
+ * driving via `session/prompt`, steering via `session/cancel`, and **restoring**
+ * prior history via `session/load`.
+ *
+ * Exports, in the order a consumer meets them:
+ *  - {@link openAcpSession} / {@link AcpSessionClient} — the ingestion client and
+ *    its capability probe / prompt-result types;
+ *  - {@link classifyUpdate} + {@link ACP_FIDELITY_GAPS} — the pure wire→canonical
+ *    normaliser and the enumerated ADR 0062 §5 fidelity gaps that justify slice 3;
+ *  - the {@link AcpConnection} JSON-RPC peer and the {@link AcpTransport} seam,
+ *    with {@link spawnAcpTransport} (a real harness subprocess) and
+ *    {@link inMemoryTransportPair} (an in-memory peer for tests);
+ *  - the ACP wire vocabulary ({@link ACP_METHOD}, guards) from `protocol.ts`.
+ */
+export {
+  AcpSessionClient,
+  type AcpCapabilityProbe,
+  type AcpPromptInput,
+  type AcpPromptResult,
+  type AcpSessionClientOptions,
+  type AcpSessionParams,
+  type AcpTextContentBlock,
+  openAcpSession,
+  type SessionEventSink,
+} from "./client.ts";
+
+export {
+  ACP_FIDELITY_GAPS,
+  type AcpClassifiedUpdate,
+  type AcpFidelityGap,
+  classifyUpdate,
+} from "./normalize.ts";
+
+export {
+  AcpConnection,
+  type AcpNotificationHandler,
+  type AcpRequestHandler,
+  AcpRpcError,
+} from "./jsonrpc.ts";
+
+export {
+  type AcpTransport,
+  encodeMessageLine,
+  inMemoryTransportPair,
+  NewlineJsonDecoder,
+} from "./transport.ts";
+
+export { type SpawnAcpOptions, type SpawnedAcpTransport, spawnAcpTransport } from "./spawn.ts";
+
+export {
+  ACP_CLIENT_METHOD,
+  ACP_METHOD,
+  ACP_PROTOCOL_VERSION,
+  type AcpAgentCapabilities,
+  type AcpInitializeResult,
+  type AcpPromptCapabilities,
+  AcpProtocolError,
+  contentBlockText,
+  parseInitializeResult,
+  parseSessionId,
+} from "./protocol.ts";

package/src/session/acp/integration.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Integration test against a *real* ACP harness — ADR 0062, slice 2 acceptance.
+ *
+ * Skipped by default: it only runs when `ACP_OPENCODE_CMD` names a real
+ * ACP-speaking binary (e.g. `ACP_OPENCODE_CMD=opencode ACP_OPENCODE_ARGS=acp`),
+ * so CI stays hermetic while the acceptance path ("against a real `opencode acp`
+ * process: `initialize` reports `loadSession`") remains exercisable on demand.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { AcpSessionClient } from "./client.ts";
+import { AcpConnection } from "./jsonrpc.ts";
+import { spawnAcpTransport } from "./spawn.ts";
+
+const command = process.env.ACP_OPENCODE_CMD;
+const args = process.env.ACP_OPENCODE_ARGS
+  ? process.env.ACP_OPENCODE_ARGS.trim().split(/\s+/).filter(Boolean)
+  : ["acp"];
+
+test(
+  "initialize against a real ACP harness reports its loadSession capability",
+  { skip: command ? false : "set ACP_OPENCODE_CMD to run the real-harness integration test" },
+  async () => {
+    assert.ok(command);
+    const transport = spawnAcpTransport({ command, args, cwd: process.cwd() });
+    const client = new AcpSessionClient(new AcpConnection(transport), { emit: () => {} });
+    try {
+      const probe = await client.initialize();
+      assert.equal(typeof probe.loadSession, "boolean");
+      assert.equal(probe.durableResume, probe.loadSession);
+      assert.ok(Number.isInteger(probe.protocolVersion));
+    } finally {
+      client.close();
+      transport.close();
+    }
+  },
+);

package/src/session/acp/jsonrpc.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { AcpConnection, AcpRpcError } from "./jsonrpc.ts";
+import { inMemoryTransportPair } from "./transport.ts";
+
+test("a request resolves with the peer's result", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const clientConn = new AcpConnection(client);
+  const agentConn = new AcpConnection(agent);
+  agentConn.onRequest("ping", (params) => ({ echoed: params }));
+
+  const result = await clientConn.request("ping", { n: 1 });
+  assert.deepEqual(result, { echoed: { n: 1 } });
+});
+
+test("a request rejects with an AcpRpcError when the peer returns an error", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const clientConn = new AcpConnection(client);
+  const agentConn = new AcpConnection(agent);
+  agentConn.onRequest("boom", () => {
+    throw new AcpRpcError(-32000, "kaboom", { extra: true });
+  });
+
+  await assert.rejects(
+    () => clientConn.request("boom"),
+    (error: unknown) => {
+      assert.ok(error instanceof AcpRpcError);
+      assert.equal(error.code, -32000);
+      assert.equal(error.message, "kaboom");
+      assert.deepEqual(error.data, { extra: true });
+      return true;
+    },
+  );
+});
+
+test("an unhandled inbound request is answered with method-not-found", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const clientConn = new AcpConnection(client);
+  // The agent side registers no handler for "unknown/method".
+  new AcpConnection(agent);
+
+  await assert.rejects(
+    () => clientConn.request("unknown/method"),
+    (error: unknown) => {
+      assert.ok(error instanceof AcpRpcError);
+      assert.equal(error.code, -32601);
+      return true;
+    },
+  );
+});
+
+test("notifications are dispatched to the registered handler and expect no response", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const clientConn = new AcpConnection(client);
+  const agentConn = new AcpConnection(agent);
+  const received: unknown[] = [];
+  agentConn.onNotification("event", (params) => received.push(params));
+
+  clientConn.notify("event", { tick: 1 });
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.deepEqual(received, [{ tick: 1 }]);
+});
+
+test("closing a connection rejects every in-flight request", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const clientConn = new AcpConnection(client);
+  const agentConn = new AcpConnection(agent);
+  // A handler that never resolves, so the request stays in flight until close.
+  agentConn.onRequest("hang", () => new Promise(() => {}));
+
+  const pending = clientConn.request("hang");
+  clientConn.close();
+  await assert.rejects(() => pending, /closed/);
+});