@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/acp/normalize.js

@@ -0,0 +1,162 @@
+/**
+ * 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.js";
+// 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 = Object.assign(Object.create(null), {
+    agent_message_chunk: "assistant",
+    agent_thought_chunk: "reasoning",
+    user_message_chunk: "user",
+});
+function ignored(sessionUpdate, reason) {
+    return { kind: "ignored", sessionUpdate, reason };
+}
+function optMessageId(update) {
+    const id = update.messageId;
+    return typeof id === "string" ? id : null;
+}
+function classifyChunk(update, sessionUpdate) {
+    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) {
+    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) {
+    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) {
+    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`);
+}
+/**
+ * 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 = [
+    {
+        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.",
+    },
+];

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

@@ -0,0 +1,94 @@
+/**
+ * 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 declare const ACP_PROTOCOL_VERSION = 1;
+/** Agent-handled JSON-RPC methods (client → agent requests / notifications). */
+export declare const ACP_METHOD: {
+    readonly initialize: "initialize";
+    readonly sessionNew: "session/new";
+    readonly sessionLoad: "session/load";
+    readonly sessionPrompt: "session/prompt";
+    /** A notification — no response is expected. */
+    readonly sessionCancel: "session/cancel";
+};
+/** Client-handled JSON-RPC methods (agent → client requests / notifications). */
+export declare const ACP_CLIENT_METHOD: {
+    /** Streamed session activity — a notification the agent pushes to the client. */
+    readonly sessionUpdate: "session/update";
+    /** The agent asks the client to approve a tool call. */
+    readonly requestPermission: "session/request_permission";
+};
+/** 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 declare function isRecord(value: unknown): value is JsonRecord;
+/**
+ * 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;
+}
+/** Raised when an ACP wire message is not the well-formed shape its method requires. */
+export declare class AcpProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function parseInitializeResult(value: unknown): AcpInitializeResult;
+/**
+ * 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 declare function parseSessionId(value: unknown): string;
+/**
+ * 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 declare function contentBlockText(value: unknown): string | null;

package/dist/session/acp/protocol.js

@@ -0,0 +1,136 @@
+/**
+ * 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",
+};
+/** 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",
+};
+/** Narrow an unknown value to a plain (non-array) object. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optBool(record, field) {
+    return record[field] === true;
+}
+function readPromptCapabilities(value) {
+    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) {
+        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) {
+    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) {
+    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) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        const parts = [];
+        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/dist/session/acp/spawn.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 } from "node:child_process";
+import { type AcpTransport } 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 declare function spawnAcpTransport(options: SpawnAcpOptions): SpawnedAcpTransport;

package/dist/session/acp/spawn.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { spawn } from "node:child_process";
+import { encodeMessageLine, NewlineJsonDecoder } from "./transport.js";
+/**
+ * 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) {
+    // 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;
+    let errorHandler;
+    let closed = false;
+    const decoder = new NewlineJsonDecoder((message) => messageHandler?.(message), (error) => errorHandler?.(error));
+    child.stdout.on("data", (chunk) => 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) => options.onStderr?.(chunk));
+    return {
+        child,
+        send(message) {
+            if (closed)
+                return;
+            child.stdin.write(encodeMessageLine(message));
+        },
+        onMessage(handler) {
+            messageHandler = handler;
+        },
+        onError(handler) {
+            errorHandler = handler;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            child.stdin.end();
+            child.kill();
+        },
+    };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 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 declare class NewlineJsonDecoder {
+    #private;
+    constructor(onMessage: (message: unknown) => void, onError: (error: Error) => void);
+    /** Feed a decoded string chunk; emits every complete line it now contains. */
+    push(chunk: string): void;
+    /**
+     * 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;
+}
+/** Serialise a JSON-RPC message as a single ACP wire line (JSON + `\n`). */
+export declare function encodeMessageLine(message: unknown): string;
+/**
+ * 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 declare function inMemoryTransportPair(): {
+    client: AcpTransport;
+    agent: AcpTransport;
+};