@nanobpm/agentic 0.1.0 → 0.5.0

package/src/session/acp/jsonrpc.ts

@@ -0,0 +1,171 @@
+/**
+ * A minimal JSON-RPC 2.0 peer for ACP — ADR 0062, slice 2.
+ *
+ * ACP is symmetric: the client sends requests/notifications to the agent
+ * (`initialize`, `session/*`) and the agent sends requests/notifications back to
+ * the client (`session/update`, `session/request_permission`). {@link AcpConnection}
+ * is the bidirectional peer over an {@link AcpTransport}: it correlates responses
+ * to outbound requests by id, dispatches inbound notifications and requests to
+ * registered handlers, and answers an unhandled inbound request with a
+ * JSON-RPC "method not found" instead of hanging the agent.
+ *
+ * It is intentionally tiny and dependency-free — the repo has no JSON-RPC library
+ * and this is the only surface that needs one, so a focused peer beats pulling a
+ * general framework (and avoids a drift surface).
+ */
+import { isRecord } from "./protocol.ts";
+import type { AcpTransport } from "./transport.ts";
+
+/** A handler for an inbound agent→client request; its resolved value is the result. */
+export type AcpRequestHandler = (params: unknown) => unknown | Promise<unknown>;
+
+/** A handler for an inbound agent→client notification (no response). */
+export type AcpNotificationHandler = (params: unknown) => void;
+
+/** A JSON-RPC error returned by, or raised toward, the peer. */
+export class AcpRpcError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "AcpRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+}
+
+export class AcpConnection {
+  readonly #transport: AcpTransport;
+  readonly #pending = new Map<number, Pending>();
+  readonly #notificationHandlers = new Map<string, AcpNotificationHandler>();
+  readonly #requestHandlers = new Map<string, AcpRequestHandler>();
+  #nextId = 1;
+  #closed = false;
+
+  constructor(transport: AcpTransport) {
+    this.#transport = transport;
+    transport.onMessage((message) => this.#dispatch(message));
+    transport.onError((error) => this.#failAll(error));
+  }
+
+  /** Send a request and resolve with its `result` (or reject with its `error`). */
+  request(method: string, params?: unknown): Promise<unknown> {
+    if (this.#closed) {
+      return Promise.reject(new Error(`ACP connection is closed; cannot call ${method}`));
+    }
+    const id = this.#nextId++;
+    return new Promise<unknown>((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#transport.send({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  /** Send a fire-and-forget notification (no id, no response). */
+  notify(method: string, params?: unknown): void {
+    if (this.#closed) return;
+    this.#transport.send({ jsonrpc: "2.0", method, params });
+  }
+
+  /** Register the handler for an inbound notification `method` (last wins). */
+  onNotification(method: string, handler: AcpNotificationHandler): void {
+    this.#notificationHandlers.set(method, handler);
+  }
+
+  /** Register the handler for an inbound request `method` (last wins). */
+  onRequest(method: string, handler: AcpRequestHandler): void {
+    this.#requestHandlers.set(method, handler);
+  }
+
+  /** Close the connection, rejecting every in-flight request. */
+  close(): void {
+    if (this.#closed) return;
+    this.#failAll(new Error("ACP connection closed"));
+    this.#closed = true;
+    this.#transport.close();
+  }
+
+  #dispatch(message: unknown): void {
+    if (!isRecord(message)) return;
+    const hasId = "id" in message && (typeof message.id === "number" || typeof message.id === "string");
+    const isResponse = hasId && ("result" in message || "error" in message);
+    if (isResponse) {
+      this.#handleResponse(message);
+      return;
+    }
+    if (typeof message.method === "string") {
+      if (hasId) {
+        this.#handleInboundRequest(message.method, message.id, message.params);
+      } else {
+        this.#handleInboundNotification(message.method, message.params);
+      }
+    }
+  }
+
+  #handleResponse(message: Record<string, unknown>): void {
+    const id = message.id;
+    if (typeof id !== "number") return; // we only ever issue numeric ids
+    const pending = this.#pending.get(id);
+    if (pending === undefined) return;
+    this.#pending.delete(id);
+    if ("error" in message && message.error !== undefined && message.error !== null) {
+      pending.reject(toRpcError(message.error));
+      return;
+    }
+    pending.resolve("result" in message ? message.result : undefined);
+  }
+
+  #handleInboundNotification(method: string, params: unknown): void {
+    const handler = this.#notificationHandlers.get(method);
+    if (handler !== undefined) handler(params);
+  }
+
+  #handleInboundRequest(method: string, id: unknown, params: unknown): void {
+    const handler = this.#requestHandlers.get(method);
+    if (handler === undefined) {
+      this.#transport.send({
+        jsonrpc: "2.0",
+        id,
+        error: { code: METHOD_NOT_FOUND, message: `method not found: ${method}` },
+      });
+      return;
+    }
+    Promise.resolve()
+      .then(() => handler(params))
+      .then(
+        (result) => this.#transport.send({ jsonrpc: "2.0", id, result: result ?? null }),
+        (reason: unknown) => this.#transport.send({ jsonrpc: "2.0", id, error: errorPayload(reason) }),
+      );
+  }
+
+  #failAll(error: Error): void {
+    for (const pending of this.#pending.values()) pending.reject(error);
+    this.#pending.clear();
+  }
+}
+
+function toRpcError(error: unknown): AcpRpcError {
+  if (isRecord(error)) {
+    const code = typeof error.code === "number" ? error.code : INTERNAL_ERROR;
+    const message = typeof error.message === "string" ? error.message : "ACP request failed";
+    return new AcpRpcError(code, message, error.data);
+  }
+  return new AcpRpcError(INTERNAL_ERROR, "ACP request failed with a non-object error");
+}
+
+function errorPayload(reason: unknown): { code: number; message: string; data?: unknown } {
+  if (reason instanceof AcpRpcError) {
+    return { code: reason.code, message: reason.message, data: reason.data };
+  }
+  if (reason instanceof Error) {
+    return { code: INTERNAL_ERROR, message: reason.message };
+  }
+  return { code: INTERNAL_ERROR, message: String(reason) };
+}

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

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { ACP_FIDELITY_GAPS, type AcpClassifiedUpdate, classifyUpdate } from "./normalize.ts";
+
+function textChunk(sessionUpdate: string, text: string, extra: Record<string, unknown> = {}): unknown {
+  return { sessionUpdate, content: { type: "text", text }, ...extra };
+}
+
+test("agent_message_chunk → an assistant message", () => {
+  const result = classifyUpdate(textChunk("agent_message_chunk", "hello"));
+  assert.deepEqual(result, { kind: "message", role: "assistant", messageId: null, text: "hello" });
+});
+
+test("agent_thought_chunk → a reasoning message", () => {
+  const result = classifyUpdate(textChunk("agent_thought_chunk", "thinking", { messageId: "m1" }));
+  assert.deepEqual(result, { kind: "message", role: "reasoning", messageId: "m1", text: "thinking" });
+});
+
+test("user_message_chunk → a user message", () => {
+  const result = classifyUpdate(textChunk("user_message_chunk", "hi"));
+  assert.deepEqual(result, { kind: "message", role: "user", messageId: null, text: "hi" });
+});
+
+test("a chunk with an array of content blocks concatenates their text", () => {
+  const update = {
+    sessionUpdate: "agent_message_chunk",
+    content: [
+      { type: "text", text: "a" },
+      { type: "image", data: "…", mimeType: "image/png" },
+      { type: "text", text: "b" },
+    ],
+  };
+  assert.deepEqual(classifyUpdate(update), { kind: "message", role: "assistant", messageId: null, text: "ab" });
+});
+
+test("a chunk with no textual content is ignored (a fidelity gap, not data)", () => {
+  const update = { sessionUpdate: "agent_message_chunk", content: { type: "image", data: "…", mimeType: "image/png" } };
+  const result = classifyUpdate(update);
+  assert.equal(result.kind, "ignored");
+});
+
+test("tool_call → a tool-call using title as the name and rawInput as args", () => {
+  const update = {
+    sessionUpdate: "tool_call",
+    toolCallId: "call-1",
+    title: "Read config",
+    kind: "read",
+    status: "pending",
+    rawInput: { path: "/etc/app.conf" },
+  };
+  assert.deepEqual(classifyUpdate(update), {
+    kind: "tool-call",
+    callId: "call-1",
+    name: "Read config",
+    args: { path: "/etc/app.conf" },
+  });
+});
+
+test("tool_call without a title falls back to the call id for the name", () => {
+  const result = classifyUpdate({ sessionUpdate: "tool_call", toolCallId: "call-2" });
+  assert.deepEqual(result, { kind: "tool-call", callId: "call-2", name: "call-2", args: null });
+});
+
+test("tool_call without rawInput yields JSON-serialisable args (null, not dropped undefined)", () => {
+  const result = classifyUpdate({ sessionUpdate: "tool_call", toolCallId: "call-3" });
+  assert.equal(result.kind, "tool-call");
+  // `ToolCallEvent.args` is documented as a JSON-serialisable value; `undefined`
+  // is silently dropped by JSON.stringify, so the key must survive a round-trip.
+  const roundTripped = JSON.parse(JSON.stringify(result));
+  assert.ok("args" in roundTripped, "args key must survive JSON serialisation");
+  assert.equal(roundTripped.args, null);
+});
+
+test("tool_call_update completed → a successful tool-result carrying rawOutput", () => {
+  const update = { sessionUpdate: "tool_call_update", toolCallId: "call-1", status: "completed", rawOutput: { ok: 1 } };
+  assert.deepEqual(classifyUpdate(update), { kind: "tool-result", callId: "call-1", ok: true, result: { ok: 1 } });
+});
+
+test("tool_call_update failed → a failed tool-result falling back to content", () => {
+  const update = {
+    sessionUpdate: "tool_call_update",
+    toolCallId: "call-1",
+    status: "failed",
+    content: [{ type: "content", content: { type: "text", text: "boom" } }],
+  };
+  const result = classifyUpdate(update);
+  assert.equal(result.kind, "tool-result");
+  assert.equal(result.kind === "tool-result" && result.ok, false);
+});
+
+test("an intermediate tool_call_update (in_progress) is ignored", () => {
+  const result = classifyUpdate({ sessionUpdate: "tool_call_update", toolCallId: "call-1", status: "in_progress" });
+  assert.equal(result.kind, "ignored");
+});
+
+test("inherited Object.prototype keys are not treated as chunk types (no prototype pollution)", () => {
+  // `sessionUpdate in CHUNK_ROLE` must be an own-property check: a wire value like
+  // "toString"/"constructor"/"hasOwnProperty" is an inherited Object.prototype key,
+  // not an ACP chunk type, and must never classify a chunk with a bogus role.
+  for (const proto of ["toString", "constructor", "hasOwnProperty", "valueOf", "__proto__"]) {
+    const result = classifyUpdate({ sessionUpdate: proto, content: { type: "text", text: "x" } });
+    assert.equal(result.kind, "ignored", `"${proto}" must be ignored, not classified as a chunk`);
+  }
+});
+
+test("non-canonical updates (plan, unknown, malformed) are ignored without throwing", () => {
+  for (const value of [
+    { sessionUpdate: "plan", plan: { entries: [] } },
+    { sessionUpdate: "available_commands_update", availableCommands: [] },
+    { sessionUpdate: "usage_update", used: 10, size: 100 },
+    { notAnUpdate: true },
+    "nonsense",
+    null,
+    42,
+  ]) {
+    assert.equal(classifyUpdate(value).kind, "ignored");
+  }
+});
+
+test("the classifier only ever produces the five canonical event kinds", () => {
+  const corpus: unknown[] = [
+    textChunk("agent_message_chunk", "x"),
+    textChunk("agent_thought_chunk", "y"),
+    textChunk("user_message_chunk", "z"),
+    { sessionUpdate: "tool_call", toolCallId: "c", title: "t" },
+    { sessionUpdate: "tool_call_update", toolCallId: "c", status: "completed" },
+    { sessionUpdate: "plan" },
+  ];
+  const producedTypes = new Set<string>();
+  for (const value of corpus) {
+    const result: AcpClassifiedUpdate = classifyUpdate(value);
+    if (result.kind === "message") producedTypes.add(result.role);
+    else producedTypes.add(result.kind);
+  }
+  producedTypes.delete("ignored");
+  assert.deepEqual(
+    [...producedTypes].sort(),
+    ["assistant", "reasoning", "tool-call", "tool-result", "user"],
+    "ACP can only reconstruct message/tool events; everything else is a documented gap",
+  );
+});
+
+test("ACP_FIDELITY_GAPS documents the canonical concepts ACP cannot reconstruct", () => {
+  assert.ok(ACP_FIDELITY_GAPS.length > 0);
+  const blob = ACP_FIDELITY_GAPS.map((gap) => `${gap.concept} ${gap.detail}`).join(" ").toLowerCase();
+  // The canonical event types ACP has no source for must each be accounted for.
+  for (const missing of ["usage", "compaction", "turn", "continuation", "model"]) {
+    assert.ok(blob.includes(missing), `fidelity gaps should mention "${missing}"`);
+  }
+});

package/src/session/acp/normalize.ts

@@ -0,0 +1,204 @@
+/**
+ * The ACP → canonical `SessionEvent` normaliser — ADR 0062, slice 2.
+ *
+ * A **pure, per-notification classifier**: it maps one ACP `session/update`
+ * payload (the `update` object, discriminated by `sessionUpdate`) to a single
+ * {@link AcpClassifiedUpdate}. It is deliberately free of any I/O, causal-chain,
+ * or coalescing concern — those belong to {@link ./client.ts}, which owns event
+ * identity (`id`/`parentId`) and buffers streamed chunks into whole messages.
+ * Keeping the wire→model mapping a pure function is what makes the ingestion
+ * fidelity testable in isolation (see `normalize.test.ts`).
+ *
+ * ## What maps, and what does not (ADR 0062 §5 fidelity note)
+ *
+ * The three primitives the world half needs all live in one ACP notification
+ * stream:
+ *
+ *  - `agent_message_chunk` / `agent_thought_chunk` / `user_message_chunk` →
+ *    canonical `assistant` / `reasoning` / `user` message text.
+ *  - `tool_call` → a canonical `tool-call` (the request).
+ *  - `tool_call_update` at a **terminal** status (`completed`/`failed`) → a
+ *    canonical `tool-result`; the tool-call lifecycle is exactly the
+ *    checkpoint/effect boundary the world half (slice 4) consumes.
+ *
+ * Everything else ACP streams — `plan`, `available_commands_update`,
+ * `current_mode_update`, `config_option_update`, `session_info_update`, and the
+ * intermediate `tool_call_update`s (status `pending`/`in_progress`) — is
+ * classified `ignored`: not a canonical mind event, retained only as a reason
+ * string for observability.
+ *
+ * The **gaps** (why slice 3's native normaliser must exist) are enumerated as a
+ * first-class, testable artifact in {@link ACP_FIDELITY_GAPS} — do not let that
+ * list drift from this mapping.
+ */
+import { contentBlockText, isRecord } from "./protocol.ts";
+
+/**
+ * The outcome of classifying one ACP `session/update`. A `message` still needs
+ * its chunks coalesced by the client; a `tool-call`/`tool-result` is a complete
+ * canonical event body; an `ignored` update carries no canonical meaning.
+ */
+export type AcpClassifiedUpdate =
+  | {
+      readonly kind: "message";
+      readonly role: "assistant" | "reasoning" | "user";
+      /** Groups streamed chunks into one message; `null` when the agent omits it. */
+      readonly messageId: string | null;
+      readonly text: string;
+    }
+  | { readonly kind: "tool-call"; readonly callId: string; readonly name: string; readonly args: unknown }
+  | { readonly kind: "tool-result"; readonly callId: string; readonly ok: boolean; readonly result: unknown }
+  | { readonly kind: "ignored"; readonly sessionUpdate: string; readonly reason: string };
+
+// A null-prototype map so `sessionUpdate in CHUNK_ROLE` and `CHUNK_ROLE[sessionUpdate]`
+// only ever see the three explicit chunk types — a wire `sessionUpdate` like
+// "toString" or "constructor" must not match an inherited Object.prototype key and
+// classify a chunk with a bogus (function-valued) role.
+const CHUNK_ROLE: Readonly<Record<string, "assistant" | "reasoning" | "user">> = Object.assign(
+  Object.create(null),
+  {
+    agent_message_chunk: "assistant",
+    agent_thought_chunk: "reasoning",
+    user_message_chunk: "user",
+  },
+);
+
+function ignored(sessionUpdate: string, reason: string): AcpClassifiedUpdate {
+  return { kind: "ignored", sessionUpdate, reason };
+}
+
+function optMessageId(update: Record<string, unknown>): string | null {
+  const id = update.messageId;
+  return typeof id === "string" ? id : null;
+}
+
+function classifyChunk(update: Record<string, unknown>, sessionUpdate: string): AcpClassifiedUpdate {
+  const role = CHUNK_ROLE[sessionUpdate];
+  const text = contentBlockText(update.content);
+  if (text === null) {
+    // A non-text content block (image/audio/resource_link) carries nothing the
+    // canonical text model can represent — an intentional fidelity gap, not data.
+    return ignored(sessionUpdate, `${role} chunk had no textual content`);
+  }
+  return { kind: "message", role, messageId: optMessageId(update), text };
+}
+
+function classifyToolCall(update: Record<string, unknown>): AcpClassifiedUpdate {
+  const callId = update.toolCallId;
+  if (typeof callId !== "string" || callId.length === 0) {
+    return ignored("tool_call", `tool_call missing a string "toolCallId"`);
+  }
+  // ACP has no machine tool *name* distinct from the human-readable `title`
+  // (ADR 0062 §5 gap); `title` is the best available identifier, falling back to
+  // the call id when even that is absent.
+  const title = update.title;
+  const name = typeof title === "string" && title.length > 0 ? title : callId;
+  // The call arguments live in `rawInput` (an opaque JSON value) when the agent
+  // exposes them; otherwise there is nothing structured to record. Fall back to
+  // `null` (never `undefined`), mirroring the tool-result `rawOutput` path: the
+  // canonical `ToolCallEvent.args` is a JSON-serialisable value, and `undefined`
+  // is dropped by `JSON.stringify`, which would violate that shape on persist/replay.
+  const args = "rawInput" in update && update.rawInput !== undefined ? update.rawInput : null;
+  return { kind: "tool-call", callId, name, args };
+}
+
+function classifyToolCallUpdate(update: Record<string, unknown>): AcpClassifiedUpdate {
+  const callId = update.toolCallId;
+  if (typeof callId !== "string" || callId.length === 0) {
+    return ignored("tool_call_update", `tool_call_update missing a string "toolCallId"`);
+  }
+  const status = update.status;
+  if (status !== "completed" && status !== "failed") {
+    // pending / in_progress / unknown / status-less patch — an intermediate
+    // lifecycle beat, not yet a canonical result.
+    return ignored("tool_call_update", `tool_call_update status "${String(status)}" is not terminal`);
+  }
+  // Prefer the structured `rawOutput`; fall back to the display `content` array.
+  const result = "rawOutput" in update ? update.rawOutput : (update.content ?? null);
+  return { kind: "tool-result", callId, ok: status === "completed", result };
+}
+
+/**
+ * Classify one ACP `update` object (the `params.update` of a `session/update`
+ * notification). Pure and total — every input yields a classification, malformed
+ * or unknown ones landing in `ignored` with a diagnostic reason rather than
+ * throwing, so a single odd notification can never abort an ingestion stream.
+ */
+export function classifyUpdate(value: unknown): AcpClassifiedUpdate {
+  if (!isRecord(value)) {
+    return ignored("<none>", `update must be an object, got ${typeof value}`);
+  }
+  const sessionUpdate = value.sessionUpdate;
+  if (typeof sessionUpdate !== "string") {
+    return ignored("<none>", `update "sessionUpdate" must be a string, got ${typeof sessionUpdate}`);
+  }
+  if (sessionUpdate in CHUNK_ROLE) {
+    return classifyChunk(value, sessionUpdate);
+  }
+  if (sessionUpdate === "tool_call") {
+    return classifyToolCall(value);
+  }
+  if (sessionUpdate === "tool_call_update") {
+    return classifyToolCallUpdate(value);
+  }
+  return ignored(sessionUpdate, `${sessionUpdate} is not a canonical mind event`);
+}
+
+/** One place where ACP is thinner than a native transcript (ADR 0062 §5). */
+export interface AcpFidelityGap {
+  /** The canonical concept that cannot be fully reconstructed from ACP alone. */
+  readonly concept: string;
+  /** Why ACP cannot carry it, and what a native transcript (slice 3) preserves. */
+  readonly detail: string;
+}
+
+/**
+ * The enumerated resume-fidelity gaps in the ACP backend — the documented reason
+ * (ADR 0062 §5) the slice 3 native normaliser exists as a fallback path. This is
+ * a derived source of truth: `normalize.test.ts` asserts the mapping above only
+ * ever emits `assistant`/`reasoning`/`user`/`tool-call`/`tool-result`, so any
+ * canonical event ACP *cannot* produce is accounted for here.
+ */
+export const ACP_FIDELITY_GAPS: readonly AcpFidelityGap[] = [
+  {
+    concept: "usage / token accounting (UsageEvent)",
+    detail:
+      "ACP's usage_update reports context-window occupancy ({ used, size, cost }), " +
+      "not per-turn input/output token counts. It cannot reconstruct a canonical " +
+      "UsageEvent's inputTokens/outputTokens, so usage is dropped rather than " +
+      "mis-attributed; a native transcript carries the real accounting.",
+  },
+  {
+    concept: "reasoning continuation (ReasoningEvent.providerContinuation)",
+    detail:
+      "ACP streams agent_thought_chunk text only. It has no field for a provider's " +
+      "opaque encrypted reasoning-continuation blob, so a resumed incarnation cannot " +
+      "resume the model's chain-of-thought exactly from an ACP transcript alone.",
+  },
+  {
+    concept: "model identity (UsageEvent.model)",
+    detail:
+      "ACP does not attribute a session/update to a specific provider model id, so " +
+      "the model a turn ran on is not recoverable from the ACP stream.",
+  },
+  {
+    concept: "tool name vs. title (ToolCallEvent.name)",
+    detail:
+      "ACP's tool_call exposes a human-readable `title` and a `kind` category but no " +
+      "stable machine tool name; the normaliser records `title` as the name, which is " +
+      "a display string, not a canonical tool identifier.",
+  },
+  {
+    concept: "compaction / truncation boundaries (CompactionEvent)",
+    detail:
+      "ACP has no notification for a context compaction or truncation, so a replayed " +
+      "ACP history cannot mark the offset ranges a native transcript folds into a summary.",
+  },
+  {
+    concept: "explicit turn boundaries (TurnStartEvent / TurnEndEvent)",
+    detail:
+      "ACP models a prompt's end via a state/stopReason on the session/prompt response, " +
+      "not as numbered turn-start/turn-end markers in the update stream, so canonical " +
+      "turn indices are not reconstructable from session/update notifications alone.",
+  },
+];