@nanobpm/agentic 0.1.0 → 0.5.0

package/src/session/acp/protocol.ts

@@ -0,0 +1,178 @@
+/**
+ * The ACP (Agent Client Protocol) wire vocabulary — ADR 0062, slice 2.
+ *
+ * This is the **harness-facing** half of the ACP ingestion backend: the JSON-RPC
+ * method names, the protocol-version constant, and the small set of runtime
+ * guards that turn the untyped JSON a harness sends over the wire into the typed
+ * shapes {@link ./normalize.ts} and {@link ./client.ts} consume. Exactly like
+ * `../events.ts`' `parseSessionEvent`, every guard *builds* a typed value field
+ * by field and fails loudly on a malformed one — it never uses an `as`-cast to
+ * fabricate a shape (AGENTS.md: the `as T` ban applies at every untyped boundary).
+ *
+ * The shapes mirror ACP **protocol version 1** — the version `opencode acp`
+ * speaks and the one ADR 0062 §5 resolves as the preferred harness protocol.
+ * Method names are verified against the canonical schema
+ * (`zed-industries/agent-client-protocol`, `schema/v1/meta.json`) and confirmed
+ * present in the opencode binary: `initialize`, `session/new|load|prompt|cancel`,
+ * `session/update`.
+ */
+
+/** The ACP protocol version this client negotiates (integer, per the spec). */
+export const ACP_PROTOCOL_VERSION = 1;
+
+/** Agent-handled JSON-RPC methods (client → agent requests / notifications). */
+export const ACP_METHOD = {
+  initialize: "initialize",
+  sessionNew: "session/new",
+  sessionLoad: "session/load",
+  sessionPrompt: "session/prompt",
+  /** A notification — no response is expected. */
+  sessionCancel: "session/cancel",
+} as const;
+
+/** Client-handled JSON-RPC methods (agent → client requests / notifications). */
+export const ACP_CLIENT_METHOD = {
+  /** Streamed session activity — a notification the agent pushes to the client. */
+  sessionUpdate: "session/update",
+  /** The agent asks the client to approve a tool call. */
+  requestPermission: "session/request_permission",
+} as const;
+
+/** A JSON object with unknown-typed values — the raw wire shape before guarding. */
+export type JsonRecord = Record<string, unknown>;
+
+/** Narrow an unknown value to a plain (non-array) object. */
+export function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The prompt-content capabilities an agent advertises (`agentCapabilities`
+ * sub-object). All optional booleans, defaulting to `false` when absent.
+ */
+export interface AcpPromptCapabilities {
+  readonly image: boolean;
+  readonly audio: boolean;
+  readonly embeddedContext: boolean;
+}
+
+/**
+ * The subset of `agentCapabilities` this slice reads from the `initialize`
+ * handshake. `loadSession` is the ADR 0062 §5 durable-resume probe; the rest is
+ * retained verbatim in {@link AcpInitializeResult.rawAgentCapabilities} for
+ * consumers that need more.
+ */
+export interface AcpAgentCapabilities {
+  /** Whether the agent supports `session/load` — the durable-resume signal. */
+  readonly loadSession: boolean;
+  readonly promptCapabilities: AcpPromptCapabilities;
+}
+
+/** The negotiated result of an `initialize` handshake, guarded off the wire. */
+export interface AcpInitializeResult {
+  readonly protocolVersion: number;
+  readonly agentCapabilities: AcpAgentCapabilities;
+  /** The full, unmodified `agentCapabilities` object (opaque passthrough). */
+  readonly rawAgentCapabilities: unknown;
+}
+
+function optBool(record: JsonRecord, field: string): boolean {
+  return record[field] === true;
+}
+
+function readPromptCapabilities(value: unknown): AcpPromptCapabilities {
+  if (!isRecord(value)) {
+    return { image: false, audio: false, embeddedContext: false };
+  }
+  return {
+    image: optBool(value, "image"),
+    audio: optBool(value, "audio"),
+    embeddedContext: optBool(value, "embeddedContext"),
+  };
+}
+
+/** Raised when an ACP wire message is not the well-formed shape its method requires. */
+export class AcpProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AcpProtocolError";
+  }
+}
+
+/**
+ * Parse an `initialize` result. The agent MAY answer with a lower
+ * `protocolVersion` than requested (down-negotiation); we surface whatever it
+ * reports and let the caller decide. A missing `agentCapabilities` is treated as
+ * "no capabilities" (every flag `false`) rather than an error, matching the ACP
+ * schema's `x-deserialize-default-on-error` default.
+ */
+export function parseInitializeResult(value: unknown): AcpInitializeResult {
+  if (!isRecord(value)) {
+    throw new AcpProtocolError(`initialize result must be an object, got ${typeof value}`);
+  }
+  const protocolVersion = value.protocolVersion;
+  if (typeof protocolVersion !== "number" || !Number.isInteger(protocolVersion)) {
+    throw new AcpProtocolError(
+      `initialize result "protocolVersion" must be an integer, got ${String(protocolVersion)}`,
+    );
+  }
+  const rawAgentCapabilities = value.agentCapabilities;
+  const caps = isRecord(rawAgentCapabilities) ? rawAgentCapabilities : {};
+  return {
+    protocolVersion,
+    agentCapabilities: {
+      loadSession: optBool(caps, "loadSession"),
+      promptCapabilities: readPromptCapabilities(caps.promptCapabilities),
+    },
+    rawAgentCapabilities,
+  };
+}
+
+/**
+ * Extract the session id from a `session/new` result (`{ sessionId }`).
+ * `session/load` carries the id from the request and returns only session
+ * metadata, so this guards the `session/new` case.
+ */
+export function parseSessionId(value: unknown): string {
+  if (!isRecord(value)) {
+    throw new AcpProtocolError(`session result must be an object, got ${typeof value}`);
+  }
+  const sessionId = value.sessionId;
+  if (typeof sessionId !== "string" || sessionId.length === 0) {
+    throw new AcpProtocolError(`session result "sessionId" must be a non-empty string`);
+  }
+  return sessionId;
+}
+
+/**
+ * Flatten an ACP `ContentBlock` (or an array of them) to plain text — the only
+ * projection the canonical `SessionEvent` model needs from a message/thought
+ * chunk. A `text` block contributes its `text`; a `resource` block with embedded
+ * text contributes that; every other block type (image/audio/resource_link)
+ * contributes nothing. Returns `null` when no text could be recovered so the
+ * caller can distinguish "empty text" from "no textual content at all".
+ */
+export function contentBlockText(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const parts: string[] = [];
+    for (const item of value) {
+      const text = contentBlockText(item);
+      if (text !== null) parts.push(text);
+    }
+    return parts.length > 0 ? parts.join("") : null;
+  }
+  if (!isRecord(value)) return null;
+  const type = value.type;
+  if (type === "text") {
+    return typeof value.text === "string" ? value.text : null;
+  }
+  if (type === "resource") {
+    const resource = value.resource;
+    if (isRecord(resource) && typeof resource.text === "string") {
+      return resource.text;
+    }
+    return null;
+  }
+  return null;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Unit tests for {@link spawnAcpTransport}. These spawn the test runtime's own
+ * `node` (never an external ACP binary), so they stay hermetic and deterministic —
+ * the env-gated real-harness path lives in `integration.test.ts`.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spawnAcpTransport } from "./spawn.ts";
+
+/** A short-lived `node` invocation running the given script. */
+function nodeScript(script: string) {
+  return spawnAcpTransport({ command: process.execPath, args: ["-e", script] });
+}
+
+test("close() suppresses the child's exit as a transport error (normal shutdown, not a fault)", async () => {
+  const errors: Error[] = [];
+  // Stay alive until stdin closes, so the only thing that ends this child is our close().
+  const transport = nodeScript("process.stdin.resume()");
+  transport.onError((error) => errors.push(error));
+  const exited = new Promise<void>((resolve) => transport.child.on("exit", () => resolve()));
+
+  transport.close();
+  await exited;
+  // Give any queued exit handler a turn to run.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(errors, [], "a caller-initiated close() must not surface a spurious exit error");
+});
+
+test("a final message written without a trailing newline is flushed at EOF, not dropped", async () => {
+  const messages: unknown[] = [];
+  // Write one complete JSON message with NO trailing newline, then exit.
+  const transport = nodeScript('process.stdout.write(JSON.stringify({ jsonrpc: "2.0", method: "hello" }))');
+  transport.onError(() => {});
+  const received = new Promise<void>((resolve) => {
+    transport.onMessage((m) => {
+      messages.push(m);
+      resolve();
+    });
+  });
+
+  await received;
+  assert.deepEqual(messages, [{ jsonrpc: "2.0", method: "hello" }], "the unterminated final line is flushed on EOF");
+  transport.close();
+});

package/src/session/acp/spawn.ts

@@ -0,0 +1,91 @@
+/**
+ * Spawn an `opencode acp` (or any ACP-speaking) harness as a subprocess and adapt
+ * its stdio to the {@link AcpTransport} port — ADR 0062, slice 2.
+ *
+ * This is the **only** module in the ACP backend that touches `node:child_process`:
+ * the JSON-RPC peer and client speak solely to the transport port, so the whole
+ * ingestion stack is exercisable in-memory (see `inMemoryTransportPair`) without a
+ * live process. `initialize` still runs against a real `opencode acp` in the
+ * env-gated integration test.
+ */
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { type AcpTransport, encodeMessageLine, NewlineJsonDecoder } from "./transport.ts";
+
+export interface SpawnAcpOptions {
+  /** The harness executable (e.g. `"opencode"`). */
+  readonly command: string;
+  /** Its arguments (e.g. `["acp"]`). */
+  readonly args?: readonly string[];
+  /** Working directory for the harness process. */
+  readonly cwd?: string;
+  /** Extra environment for the harness (merged over `process.env`). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Where to route the harness's stderr diagnostics. Default: drained and discarded. */
+  readonly onStderr?: (chunk: string) => void;
+}
+
+/** An {@link AcpTransport} bound to a spawned harness, exposing the child handle. */
+export interface SpawnedAcpTransport extends AcpTransport {
+  /** The underlying child process (for lifecycle assertions / signals). */
+  readonly child: ChildProcessWithoutNullStreams;
+}
+
+/**
+ * Spawn the harness and return a transport over its stdin/stdout with ACP's
+ * newline-delimited JSON framing. The child's stderr is protocol-irrelevant
+ * (diagnostics only): it is always piped and routed to `onStderr` when provided,
+ * otherwise drained and discarded (never inherited by the parent's stderr).
+ */
+export function spawnAcpTransport(options: SpawnAcpOptions): SpawnedAcpTransport {
+  // Omitting `stdio` defaults every stream to "pipe", which is both what ACP's
+  // stdio transport needs and what makes the streams statically non-null
+  // (ChildProcessWithoutNullStreams). The child's stderr is protocol-irrelevant
+  // (diagnostics only) — routed to `onStderr`, or drained to avoid backpressure.
+  const child = spawn(options.command, [...(options.args ?? [])], {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+  });
+  child.stdout.setEncoding("utf8");
+
+  let messageHandler: ((message: unknown) => void) | undefined;
+  let errorHandler: ((error: Error) => void) | undefined;
+  let closed = false;
+  const decoder = new NewlineJsonDecoder(
+    (message) => messageHandler?.(message),
+    (error) => errorHandler?.(error),
+  );
+
+  child.stdout.on("data", (chunk: string) => decoder.push(chunk));
+  // On EOF, flush any final message the harness wrote without a trailing newline
+  // rather than dropping it.
+  child.stdout.on("end", () => decoder.flush());
+  child.on("error", (error) => errorHandler?.(error));
+  child.on("exit", (code, signal) => {
+    // A caller-initiated close() kills the child and triggers this exit; that is a
+    // normal shutdown, not a transport error, so do not surface a spurious error.
+    if (closed) return;
+    errorHandler?.(new Error(`ACP harness exited (code=${String(code)}, signal=${String(signal)})`));
+  });
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => options.onStderr?.(chunk));
+
+  return {
+    child,
+    send(message: unknown): void {
+      if (closed) return;
+      child.stdin.write(encodeMessageLine(message));
+    },
+    onMessage(handler: (message: unknown) => void): void {
+      messageHandler = handler;
+    },
+    onError(handler: (error: Error) => void): void {
+      errorHandler = handler;
+    },
+    close(): void {
+      if (closed) return;
+      closed = true;
+      child.stdin.end();
+      child.kill();
+    },
+  };
+}

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

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { encodeMessageLine, inMemoryTransportPair, NewlineJsonDecoder } from "./transport.ts";
+
+test("NewlineJsonDecoder emits one message per complete line and ignores blanks", () => {
+  const messages: unknown[] = [];
+  const decoder = new NewlineJsonDecoder(
+    (m) => messages.push(m),
+    (e) => {
+      throw e;
+    },
+  );
+  decoder.push('{"a":1}\n\n{"b":2}\n');
+  assert.deepEqual(messages, [{ a: 1 }, { b: 2 }]);
+});
+
+test("NewlineJsonDecoder buffers a line split across chunks", () => {
+  const messages: unknown[] = [];
+  const decoder = new NewlineJsonDecoder(
+    (m) => messages.push(m),
+    (e) => {
+      throw e;
+    },
+  );
+  decoder.push('{"partial":');
+  assert.deepEqual(messages, [], "no complete line yet");
+  decoder.push('true}\n');
+  assert.deepEqual(messages, [{ partial: true }]);
+});
+
+test("NewlineJsonDecoder routes an unparseable line to onError without aborting", () => {
+  const messages: unknown[] = [];
+  const errors: Error[] = [];
+  const decoder = new NewlineJsonDecoder(
+    (m) => messages.push(m),
+    (e) => errors.push(e),
+  );
+  decoder.push("not json\n{\"ok\":1}\n");
+  assert.equal(errors.length, 1);
+  assert.deepEqual(messages, [{ ok: 1 }], "the stream continues past the bad line");
+});
+
+test("NewlineJsonDecoder.flush delivers a final unterminated line at EOF instead of dropping it", () => {
+  const messages: unknown[] = [];
+  const decoder = new NewlineJsonDecoder(
+    (m) => messages.push(m),
+    (e) => {
+      throw e;
+    },
+  );
+  // The second message has no trailing newline — as if the pipe hit EOF mid-line.
+  decoder.push('{"a":1}\n{"b":2}');
+  assert.deepEqual(messages, [{ a: 1 }], "push emits only the newline-terminated line");
+  decoder.flush();
+  assert.deepEqual(messages, [{ a: 1 }, { b: 2 }], "flush emits the buffered final line at EOF");
+  decoder.flush();
+  assert.deepEqual(messages, [{ a: 1 }, { b: 2 }], "flush is idempotent — the buffer is cleared");
+});
+
+test("encodeMessageLine produces exactly one newline-terminated JSON line", () => {
+  const line = encodeMessageLine({ jsonrpc: "2.0", id: 1 });
+  assert.equal(line, '{"jsonrpc":"2.0","id":1}\n');
+});
+
+test("encodeMessageLine throws on a non-JSON-serialisable message instead of emitting a bad wire line", () => {
+  // `JSON.stringify(undefined)` returns `undefined`; a naive template would emit
+  // the literal line "undefined\n", which always fails JSON.parse on the peer.
+  assert.throws(() => encodeMessageLine(undefined), /non-JSON-serialisable/);
+});
+
+test("inMemoryTransportPair delivers what one side sends to the other, asynchronously", async () => {
+  const { client, agent } = inMemoryTransportPair();
+  const received: unknown[] = [];
+  agent.onMessage((m) => received.push(m));
+  agent.onError((e) => {
+    throw e;
+  });
+  client.send({ hello: "agent" });
+  assert.deepEqual(received, [], "delivery is deferred to a microtask, never synchronous");
+  await Promise.resolve();
+  assert.deepEqual(received, [{ hello: "agent" }]);
+});

package/src/session/acp/transport.ts

@@ -0,0 +1,155 @@
+/**
+ * The ACP transport seam — ADR 0062, slice 2.
+ *
+ * ACP frames JSON-RPC 2.0 as **newline-delimited JSON over stdio** (one complete
+ * message per line, UTF-8, no `Content-Length` headers — that is LSP/MCP framing,
+ * not ACP). {@link AcpConnection} speaks only to this narrow {@link AcpTransport}
+ * port, so the JSON-RPC peer never knows whether it is wired to a spawned
+ * `opencode acp` subprocess ({@link ./spawn.ts}) or, in a test, to an in-memory
+ * fake agent ({@link inMemoryTransportPair}). Transport is a seam, never
+ * re-implemented per backend (AGENTS.md: no drift surfaces).
+ */
+
+/**
+ * A bidirectional stream of already-parsed JSON-RPC messages. Implementations own
+ * the newline framing and `JSON.parse`/`stringify` at the byte boundary; the peer
+ * above works purely in terms of JSON values.
+ */
+export interface AcpTransport {
+  /** Serialise and write one JSON-RPC message toward the peer. */
+  send(message: unknown): void;
+  /**
+   * Register the handler for inbound messages. Called once by the connection on
+   * construction. A malformed line is surfaced via {@link onError} rather than
+   * delivered here.
+   */
+  onMessage(handler: (message: unknown) => void): void;
+  /** Register a handler for transport-level errors (e.g. an unparseable line). */
+  onError(handler: (error: Error) => void): void;
+  /** Close the transport and release its underlying resource. Idempotent. */
+  close(): void;
+}
+
+/**
+ * Split a byte stream into complete newline-delimited JSON messages. Handles
+ * chunk boundaries that fall mid-line (buffering the remainder) and ignores
+ * blank lines. Each decoded value is handed to `onMessage`; a line that fails to
+ * parse goes to `onError` and does not abort the stream.
+ */
+export class NewlineJsonDecoder {
+  #buffer = "";
+  readonly #onMessage: (message: unknown) => void;
+  readonly #onError: (error: Error) => void;
+
+  constructor(onMessage: (message: unknown) => void, onError: (error: Error) => void) {
+    this.#onMessage = onMessage;
+    this.#onError = onError;
+  }
+
+  /** Feed a decoded string chunk; emits every complete line it now contains. */
+  push(chunk: string): void {
+    this.#buffer += chunk;
+    let newlineIndex = this.#buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = this.#buffer.slice(0, newlineIndex).trim();
+      this.#buffer = this.#buffer.slice(newlineIndex + 1);
+      if (line.length > 0) this.#deliver(line);
+      newlineIndex = this.#buffer.indexOf("\n");
+    }
+  }
+
+  /**
+   * Deliver any final buffered line at stream end (EOF without a trailing
+   * newline). A compliant peer newline-terminates every message, but on abrupt
+   * process/pipe EOF a complete final message can sit unterminated in the buffer;
+   * flushing it surfaces the message (or a parse error) instead of silently
+   * dropping it. Idempotent: it clears the buffer, so a second call is a no-op.
+   */
+  flush(): void {
+    const line = this.#buffer.trim();
+    this.#buffer = "";
+    if (line.length > 0) this.#deliver(line);
+  }
+
+  #deliver(line: string): void {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch (cause) {
+      this.#onError(new Error(`ACP transport received a non-JSON line: ${line.slice(0, 200)}`, { cause }));
+      return;
+    }
+    this.#onMessage(parsed);
+  }
+}
+
+/** Serialise a JSON-RPC message as a single ACP wire line (JSON + `\n`). */
+export function encodeMessageLine(message: unknown): string {
+  const json = JSON.stringify(message);
+  // `JSON.stringify(undefined)` (and other non-serialisable inputs) returns
+  // `undefined`, which would emit the literal line "undefined\n" and always fail
+  // `JSON.parse` on the peer. Fail loudly at the sender instead of on the wire.
+  if (json === undefined) {
+    throw new Error("ACP transport cannot encode a non-JSON-serialisable message");
+  }
+  return `${json}\n`;
+}
+
+/**
+ * A pair of transports wired directly to each other in memory: what one `send`s
+ * the other receives (after a `queueMicrotask` hop, so delivery is asynchronous
+ * like a real pipe and never re-enters the sender synchronously). The reference
+ * substrate for driving a fake agent in tests without spawning a process.
+ */
+export function inMemoryTransportPair(): { client: AcpTransport; agent: AcpTransport } {
+  const client = new InMemoryTransport();
+  const agent = new InMemoryTransport();
+  client.connect(agent);
+  agent.connect(client);
+  return { client, agent };
+}
+
+class InMemoryTransport implements AcpTransport {
+  #peer: InMemoryTransport | undefined;
+  #onMessage: ((message: unknown) => void) | undefined;
+  #onError: ((error: Error) => void) | undefined;
+  #closed = false;
+
+  connect(peer: InMemoryTransport): void {
+    this.#peer = peer;
+  }
+
+  send(message: unknown): void {
+    if (this.#closed) return;
+    // Round-trip through the wire encoding so an in-memory test exercises the same
+    // JSON serialisation a real pipe would.
+    const line = encodeMessageLine(message);
+    const peer = this.#peer;
+    queueMicrotask(() => peer?.receive(line));
+  }
+
+  receive(line: string): void {
+    if (this.#closed) return;
+    const handler = this.#onMessage;
+    if (handler === undefined) return;
+    const onError =
+      this.#onError ??
+      ((error: Error) => {
+        throw error;
+      });
+    const decoder = new NewlineJsonDecoder(handler, onError);
+    decoder.push(line);
+  }
+
+  onMessage(handler: (message: unknown) => void): void {
+    this.#onMessage = handler;
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.#onError = handler;
+  }
+
+  close(): void {
+    this.#closed = true;
+  }
+}