@nanobpm/agentic 0.1.0 → 0.5.0

package/dist/session/acp/client.js

@@ -0,0 +1,254 @@
+/**
+ * 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 { AcpConnection } from "./jsonrpc.js";
+import { classifyUpdate } from "./normalize.js";
+import { ACP_CLIENT_METHOD, ACP_METHOD, ACP_PROTOCOL_VERSION, isRecord, parseInitializeResult, parseSessionId, } from "./protocol.js";
+/**
+ * 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 {
+    #connection;
+    #sink;
+    #newEventId;
+    #clientInfo;
+    #lastId = null;
+    #buffer;
+    #collector = null;
+    #sessionId;
+    constructor(connection, sink, options = {}) {
+        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() {
+        return this.#sessionId;
+    }
+    /**
+     * Perform the `initialize` handshake and return the durable-resume capability
+     * probe. Must be called before any `session/*` method.
+     */
+    async initialize() {
+        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) {
+        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, params) {
+        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) {
+        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() {
+        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() {
+        this.#flushMessage();
+        this.#connection.close();
+    }
+    async #collecting(op) {
+        const events = [];
+        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) {
+        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) {
+        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() {
+        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() {
+        const id = this.#newEventId();
+        const parentId = this.#lastId;
+        this.#lastId = id;
+        return { id, parentId };
+    }
+    #push(event) {
+        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, b) {
+    if (a === null && b === null)
+        return true;
+    return a === b;
+}
+function readStopReason(result) {
+    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) {
+    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, sink, options = {}) {
+    return new AcpSessionClient(new AcpConnection(transport), sink, options);
+}

package/dist/session/acp/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@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/dist/session/acp/index.js

@@ -0,0 +1,27 @@
+/**
+ * `@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, openAcpSession, } from "./client.js";
+export { ACP_FIDELITY_GAPS, classifyUpdate, } from "./normalize.js";
+export { AcpConnection, AcpRpcError, } from "./jsonrpc.js";
+export { encodeMessageLine, inMemoryTransportPair, NewlineJsonDecoder, } from "./transport.js";
+export { spawnAcpTransport } from "./spawn.js";
+export { ACP_CLIENT_METHOD, ACP_METHOD, ACP_PROTOCOL_VERSION, AcpProtocolError, contentBlockText, parseInitializeResult, parseSessionId, } from "./protocol.js";

package/dist/session/acp/jsonrpc.d.ts

@@ -0,0 +1,25 @@
+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 declare class AcpRpcError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare class AcpConnection {
+    #private;
+    constructor(transport: AcpTransport);
+    /** Send a request and resolve with its `result` (or reject with its `error`). */
+    request(method: string, params?: unknown): Promise<unknown>;
+    /** Send a fire-and-forget notification (no id, no response). */
+    notify(method: string, params?: unknown): void;
+    /** Register the handler for an inbound notification `method` (last wins). */
+    onNotification(method: string, handler: AcpNotificationHandler): void;
+    /** Register the handler for an inbound request `method` (last wins). */
+    onRequest(method: string, handler: AcpRequestHandler): void;
+    /** Close the connection, rejecting every in-flight request. */
+    close(): void;
+}

package/dist/session/acp/jsonrpc.js

@@ -0,0 +1,148 @@
+/**
+ * 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.js";
+/** A JSON-RPC error returned by, or raised toward, the peer. */
+export class AcpRpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "AcpRpcError";
+        this.code = code;
+        this.data = data;
+    }
+}
+const METHOD_NOT_FOUND = -32601;
+const INTERNAL_ERROR = -32603;
+export class AcpConnection {
+    #transport;
+    #pending = new Map();
+    #notificationHandlers = new Map();
+    #requestHandlers = new Map();
+    #nextId = 1;
+    #closed = false;
+    constructor(transport) {
+        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, params) {
+        if (this.#closed) {
+            return Promise.reject(new Error(`ACP connection is closed; cannot call ${method}`));
+        }
+        const id = this.#nextId++;
+        return new Promise((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, params) {
+        if (this.#closed)
+            return;
+        this.#transport.send({ jsonrpc: "2.0", method, params });
+    }
+    /** Register the handler for an inbound notification `method` (last wins). */
+    onNotification(method, handler) {
+        this.#notificationHandlers.set(method, handler);
+    }
+    /** Register the handler for an inbound request `method` (last wins). */
+    onRequest(method, handler) {
+        this.#requestHandlers.set(method, handler);
+    }
+    /** Close the connection, rejecting every in-flight request. */
+    close() {
+        if (this.#closed)
+            return;
+        this.#failAll(new Error("ACP connection closed"));
+        this.#closed = true;
+        this.#transport.close();
+    }
+    #dispatch(message) {
+        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) {
+        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, params) {
+        const handler = this.#notificationHandlers.get(method);
+        if (handler !== undefined)
+            handler(params);
+    }
+    #handleInboundRequest(method, id, params) {
+        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) => this.#transport.send({ jsonrpc: "2.0", id, error: errorPayload(reason) }));
+    }
+    #failAll(error) {
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+    }
+}
+function toRpcError(error) {
+    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) {
+    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/dist/session/acp/normalize.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare function classifyUpdate(value: unknown): AcpClassifiedUpdate;
+/** 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 declare const ACP_FIDELITY_GAPS: readonly AcpFidelityGap[];