@theokit/acp 3.0.2 → 4.0.1-next.0

package/dist/index.d.cts

@@ -7,84 +7,154 @@ import { SDKAgent } from '@theokit/sdk';
  */
 
 /**
- * Factory function shape: receives the ACP session id (UUID) and returns
- * a fresh `SDKAgent` for that session. Per D351, this enforces per-session
- * conversation isolation when consumers want it.
+ * Builds the agent that will serve one ACP session.
+ *
+ * Called once per `session/new`, with a freshly generated UUID, and awaited. Returning a NEW agent
+ * per call is what gives each session its own conversation state (D351); returning the same instance
+ * every time is the shared-state shape described on {@link AgentOrFactory}.
+ *
+ * A throw or rejection here is reported to the host as JSON-RPC `-32603`, message
+ * `agent factory threw: <your message>`, and no session is created.
  *
  * @public
  */
 type AgentFactory = (sessionId: string) => SDKAgent | Promise<SDKAgent>;
 /**
- * Acceptable shapes for `serveAcp({ agent })`:
- *   - `AgentFactory`: per-session isolation (recommended).
- *   - `SDKAgent`: single shared agent — emits one-time stderr warning.
+ * What `serveAcp({ agent })` accepts.
+ *
+ * - {@link AgentFactory} — one agent per session. Recommended.
+ * - `SDKAgent` — one agent for the whole process. Legal, but every ACP session then appends to the
+ *   SAME conversation; `serveAcp` writes a one-time warning through its `log` and carries on.
+ *
+ * Anything else (a plain object, `null`, a string) makes `serveAcp` fail with an
+ * `InvalidAgentError` before a single byte of protocol is read. `serveAcp` is `async`, so that
+ * arrives as a REJECTED PROMISE, never as a synchronous throw — `try { serveAcp(...) } catch` around
+ * the call alone catches nothing. The class is not exported either (see {@link serveAcp}); match on
+ * `err.name`. The duck-test is narrow: an object qualifies only when it has a string `agentId` and a
+ * callable `send`.
  *
  * @public
  */
 type AgentOrFactory = AgentFactory | SDKAgent;
 /**
- * Permission mode controlling how tool calls flow through ACP permission
- * round-trip (D355).
+ * How tool calls are gated before they execute (D355).
+ *
+ * - `"ask"` (default) — every tool call except the ones named in `trustedTools` round-trips through
+ *   the host's `session/request_permission`. A `deny` choice, a cancelled request, a transport
+ *   failure, or `permissionTimeoutMs` elapsing all BLOCK the call.
+ * - `"auto"` — no gating whatsoever: the veto plugin is never installed, so `trustedTools` AND
+ *   `permissionTimeoutMs` are silently ignored in this mode.
+ * - `"deny"` — blocks every tool call without asking the host. `trustedTools` does NOT exempt
+ *   anything here: the deny branch is evaluated before the trusted-tool check.
+ *
+ * `"ask"` and `"deny"` fail closed. When the runtime has no plugin manager to hang the veto on (a
+ * cloud-backed agent, for instance), the prompt is refused with `-32603` rather than executed
+ * ungated — a security control that cannot be installed must not silently degrade to `"auto"`.
  *
  * @public
  */
 type PermissionMode = "ask" | "auto" | "deny";
 /**
- * Capabilities advertised in the ACP `initialize` handshake. Users may
- * override any subset; defaults are loaded internally.
+ * Overrides for the capabilities advertised in the ACP `initialize` handshake.
+ *
+ * `loadSession` and the three `prompt` flags reach the wire; they are the only session-shaped
+ * capabilities `AgentCapabilities` has a slot for at `@agentclientprotocol/sdk@0.22.1`.
+ *
+ * `forkSession` and `listSessions` were removed in #350. The protocol has nowhere to advertise
+ * them — neither name appears in its generated schema — and neither gated anything here:
+ * `session/fork` is refused unconditionally and `session/list` is answered from the in-memory
+ * store regardless. They were accepted, typed, documented, and inert.
  *
  * @public
  */
 interface AcpCapabilities {
+    /** Advertise `session/load`. Default `true`. The handler needs the SDK to be able to resume that id. */
     loadSession?: boolean;
-    forkSession?: boolean;
-    listSessions?: boolean;
+    /** Prompt content the host may send. Anything disabled here is a hint to the host, not a guard. */
     prompt?: {
+        /** Default `false`. Audio blocks are still accepted and counted against `maxPromptBytes`. */
         audio?: boolean;
+        /** Default `true`. */
         embeddedContext?: boolean;
+        /** Default `true`. Images are accepted but only the TEXT blocks of a prompt reach the agent. */
         image?: boolean;
     };
 }
 /**
- * Display info for the agent in the ACP host UI.
+ * Display info for the agent in an ACP host UI.
+ *
+ * Sent as `InitializeResponse.agentInfo` when you supply it (#350 — it was accepted and read by
+ * nothing). Omitted otherwise: defaulting to this package's own metadata would label every agent as
+ * the adapter serving it, and a name that is confidently wrong is worse for a host to display than
+ * one that is absent.
  *
  * @public
  */
 interface AcpAgentInfo {
+    /** Machine-ish identifier, e.g. `"my-bot"`. */
     name: string;
+    /** Human label preferred by a UI over `name`. */
     title?: string;
+    /** Semver of the agent, not of this package. */
     version: string;
 }
 /**
- * Options for `serveAcp()`.
+ * Options for {@link serveAcp}. Every field but `agent` is optional and every default is listed
+ * below — this object is the whole configuration surface, nothing is read from env or disk.
  *
  * @public
  */
 interface AcpServerOptions {
-    /** Single agent OR factory `(sessionId) => SDKAgent`. Required. */
+    /** The agent, or a per-session factory. Required; an unusable value throws before serving. */
     agent: AgentOrFactory;
-    /** Display info advertised in `initialize`. Defaults to package metadata. */
+    /** Name, title and version advertised as `agentInfo` in the `initialize` handshake. */
     info?: AcpAgentInfo;
-    /** Capability overrides for the `initialize` handshake. */
+    /** Handshake capability overrides. Only a subset is honoured — see {@link AcpCapabilities}. */
     capabilities?: AcpCapabilities;
-    /** Permission mode (default `"ask"`). See D355. */
+    /** Default `"ask"`. Read {@link PermissionMode} before choosing: `"auto"` disables the two fields below. */
     permissionDefault?: PermissionMode;
-    /** Timeout (ms) for `requestPermission` round-trip before vetoing (default 60_000). EC-2. */
+    /**
+     * How long to wait for the host to answer `session/request_permission` before BLOCKING the tool
+     * call (fail-closed, EC-2). Default `60_000` ms. Ignored unless `permissionDefault` is `"ask"`.
+     */
     permissionTimeoutMs?: number;
-    /** Tool names that bypass `ask` mode. */
+    /**
+     * Tool names that skip the permission round-trip. Matched by exact tool name.
+     *
+     * Effective in `"ask"` mode ONLY: `"auto"` never installs the plugin, and `"deny"` blocks these
+     * too.
+     */
     trustedTools?: ReadonlyArray<string>;
-    /** Cap on total prompt bytes (default 2 MiB). D360. */
+    /**
+     * Ceiling on the ACCUMULATED size of one prompt, in bytes. Default `2 * 1024 * 1024` (2 MiB), D360.
+     *
+     * Counted per block and summed: UTF-8 bytes for text, base64-DECODED bytes for image and audio,
+     * the URI for a resource link, the JSON form for an embedded resource. Crossing it rejects the
+     * whole prompt with `-32602` — see {@link PromptTooLargeError}.
+     */
     maxPromptBytes?: number;
-    /** Logger — defaults to `process.stderr.write` per D359. */
+    /**
+     * Sink for this package's diagnostics — one line per call, newline NOT included.
+     *
+     * Defaults to a write to `process.stderr` (D359). Never route this to stdout: stdout carries the
+     * JSON-RPC frames.
+     */
     log?: (msg: string) => void;
-    /** Override stdin (test seam). */
+    /** Override the protocol input stream. Defaults to `process.stdin`. Test seam. */
     stdin?: NodeJS.ReadableStream;
-    /** Override stdout (test seam). */
+    /** Override the protocol output stream. Defaults to `process.stdout`. Test seam. */
     stdout?: NodeJS.WritableStream;
 }
 /**
- * Thrown by `extractPrompt` when the decoded prompt exceeds `maxPromptBytes`.
- * Public so callers can `instanceof` it.
+ * Raised when a prompt's accumulated size passes `maxPromptBytes` (D360).
+ *
+ * `size` is the running total AT the block that crossed the limit, not the size of the full prompt:
+ * extraction stops at the first offending block, so blocks after it are never measured.
+ *
+ * Under {@link serveAcp} this never escapes to the caller — it is caught and returned to the ACP
+ * host as JSON-RPC `-32602` carrying `message` verbatim (`prompt exceeds N bytes (got M)`). The
+ * class is exported so that text has a named origin; the extractor that throws it is not part of the
+ * public surface, so there is no supported call site where a consumer can `instanceof` it directly.
  *
  * @public
  */
@@ -95,22 +165,90 @@ declare class PromptTooLargeError extends Error {
     constructor(size: number, limit: number);
 }
 
+/**
+ * Normalize `serveAcp({ agent })` into a uniform `AgentFactory` (D351).
+ *
+ * - Function input → passed through as-is. NOT duck-tested: any function is accepted, and a bad
+ *   return value only surfaces when the first session is created.
+ * - SDKAgent-shaped object → wrapped in a factory that returns that same instance for every session,
+ *   plus a one-time warning through `log` (a shared agent defeats per-session isolation).
+ * - Anything else → `InvalidAgentError` thrown synchronously.
+ *
+ * @internal
+ */
+
+/** Thrown when `serveAcp({ agent })` is neither a function nor an object with `agentId` + `send`. */
+declare class InvalidAgentError extends Error {
+    readonly name = "InvalidAgentError";
+}
+
 /**
  * `serveAcp({ agent })` — top-level entry that wires the ACP server.
  *
  * Constructs `AgentSideConnection` from `@agentclientprotocol/sdk@^0.22`,
  * delegates lifecycle methods to `lifecycle.ts`, and drives the prompt
- * translator from `translator.ts`. Per-invocation state (D356).
+ * translator from `translator.ts`. All state (sessions, warnings, defaults) is
+ * per invocation — nothing is module-global, so two `serveAcp` calls on
+ * different stream pairs do not see each other (D356).
  *
  * @public
  */
 
 /**
- * Block on a stdio JSON-RPC ACP server until stdin closes. Returns ONLY
- * after every active session has been disposed (EC-1).
+ * Serve `options.agent` to an ACP host over JSON-RPC on stdio, blocking until the input stream ends.
+ *
+ * ```ts
+ * await serveAcp({ agent: (sessionId) => Agent.create({ agentId: sessionId }) });
+ * ```
+ *
+ * Needs `@agentclientprotocol/sdk` and `@theokit/sdk` installed (peer dependencies). It reads no
+ * environment variable and no config file of its own; every knob is on {@link AcpServerOptions}.
+ * **Do not write to stdout** from the agent or its tools — that stream carries the protocol frames.
+ *
+ * Resolves once `stdin` emits `end` or `close` AND `dispose()` has settled for every live session
+ * (EC-1). A `dispose()` that throws is logged and swallowed, so a bad teardown cannot strand the
+ * process.
+ *
+ * Rejects only when it cannot start: an `InvalidAgentError` when `agent` is neither a function nor
+ * an object with a string `agentId` and a callable `send`. That class is exported, so branch on
+ * `instanceof InvalidAgentError` rather than on `err.name` (#369). Nothing that happens afterwards
+ * rejects this promise — per-request failures go back to
+ * the host as JSON-RPC errors:
+ *
+ * | Condition | Code |
+ * |---|---|
+ * | `cwd` absent or not on disk (`session/new`, `session/load`, `session/fork`) | `-32602` |
+ * | `session/load` for an id already loaded in this process | `-32602` |
+ * | prompt with no text block, or over `maxPromptBytes` | `-32602` |
+ * | `session/fork` whose parent IS loaded here — deferred to v0.2 | `-32602` |
+ * | `session/prompt` or `session/fork` naming a session this process has not loaded | `-32001` |
+ * | `session/load` the SDK cannot resume (wrong host, no shared storage) | `-32001` |
+ * | agent factory threw | `-32603` |
+ * | `permissionDefault` is `"ask"`/`"deny"` and the runtime cannot enforce it | `-32603` |
+ * | run ended in a status ACP has no stop reason for | `-32603` |
+ *
+ * `session/fork` checks the parent BEFORE `cwd`, so a fork naming a parent this process does not
+ * hold answers `-32001` and never reaches either `-32602` row above. Because the session store is
+ * in-memory and per-process, that is the common case after a restart — `session/fork` is refused in
+ * every case, but reading the refusal as "always `-32602`" is wrong.
+ *
+ * A prompt that completes maps the run onto an ACP stop reason: `end_turn`, `cancelled`, `refusal`
+ * (safety), `max_tokens` (context or token cap), `max_turn_requests` (iteration cap).
+ *
+ * Traps worth knowing before you wire a host to this:
+ * - `session/authenticate` always answers success without checking anything (D350) — do not read an
+ *   empty `authMethods` plus a successful authenticate as "the agent authorised me".
+ * - Only the TEXT blocks of a prompt reach the agent. Images, audio and resources are counted
+ *   against `maxPromptBytes`, then dropped.
+ * - `session/cancel` aborts the session's single `AbortController`, and nothing re-arms it. Every
+ *   later prompt on that session is issued with an already-aborted signal, so treat a cancelled
+ *   session as spent and open a new one.
+ * - Of the SDK stream, only assistant text, thinking and tool calls are forwarded; `status`, `task`
+ *   and `object_delta` messages have no ACP equivalent and are dropped silently.
+ * - `serveAcp` does not close `stdout` and does not call `process.exit` — the caller owns the exit.
  *
  * @public
  */
 declare function serveAcp(options: AcpServerOptions): Promise<void>;
 
-export { type AcpAgentInfo, type AcpCapabilities, type AcpServerOptions, type AgentFactory, type AgentOrFactory, type PermissionMode, PromptTooLargeError, serveAcp };
+export { type AcpAgentInfo, type AcpCapabilities, type AcpServerOptions, type AgentFactory, type AgentOrFactory, InvalidAgentError, type PermissionMode, PromptTooLargeError, serveAcp };

package/dist/index.d.ts

@@ -7,84 +7,154 @@ import { SDKAgent } from '@theokit/sdk';
  */
 
 /**
- * Factory function shape: receives the ACP session id (UUID) and returns
- * a fresh `SDKAgent` for that session. Per D351, this enforces per-session
- * conversation isolation when consumers want it.
+ * Builds the agent that will serve one ACP session.
+ *
+ * Called once per `session/new`, with a freshly generated UUID, and awaited. Returning a NEW agent
+ * per call is what gives each session its own conversation state (D351); returning the same instance
+ * every time is the shared-state shape described on {@link AgentOrFactory}.
+ *
+ * A throw or rejection here is reported to the host as JSON-RPC `-32603`, message
+ * `agent factory threw: <your message>`, and no session is created.
  *
  * @public
  */
 type AgentFactory = (sessionId: string) => SDKAgent | Promise<SDKAgent>;
 /**
- * Acceptable shapes for `serveAcp({ agent })`:
- *   - `AgentFactory`: per-session isolation (recommended).
- *   - `SDKAgent`: single shared agent — emits one-time stderr warning.
+ * What `serveAcp({ agent })` accepts.
+ *
+ * - {@link AgentFactory} — one agent per session. Recommended.
+ * - `SDKAgent` — one agent for the whole process. Legal, but every ACP session then appends to the
+ *   SAME conversation; `serveAcp` writes a one-time warning through its `log` and carries on.
+ *
+ * Anything else (a plain object, `null`, a string) makes `serveAcp` fail with an
+ * `InvalidAgentError` before a single byte of protocol is read. `serveAcp` is `async`, so that
+ * arrives as a REJECTED PROMISE, never as a synchronous throw — `try { serveAcp(...) } catch` around
+ * the call alone catches nothing. The class is not exported either (see {@link serveAcp}); match on
+ * `err.name`. The duck-test is narrow: an object qualifies only when it has a string `agentId` and a
+ * callable `send`.
  *
  * @public
  */
 type AgentOrFactory = AgentFactory | SDKAgent;
 /**
- * Permission mode controlling how tool calls flow through ACP permission
- * round-trip (D355).
+ * How tool calls are gated before they execute (D355).
+ *
+ * - `"ask"` (default) — every tool call except the ones named in `trustedTools` round-trips through
+ *   the host's `session/request_permission`. A `deny` choice, a cancelled request, a transport
+ *   failure, or `permissionTimeoutMs` elapsing all BLOCK the call.
+ * - `"auto"` — no gating whatsoever: the veto plugin is never installed, so `trustedTools` AND
+ *   `permissionTimeoutMs` are silently ignored in this mode.
+ * - `"deny"` — blocks every tool call without asking the host. `trustedTools` does NOT exempt
+ *   anything here: the deny branch is evaluated before the trusted-tool check.
+ *
+ * `"ask"` and `"deny"` fail closed. When the runtime has no plugin manager to hang the veto on (a
+ * cloud-backed agent, for instance), the prompt is refused with `-32603` rather than executed
+ * ungated — a security control that cannot be installed must not silently degrade to `"auto"`.
  *
  * @public
  */
 type PermissionMode = "ask" | "auto" | "deny";
 /**
- * Capabilities advertised in the ACP `initialize` handshake. Users may
- * override any subset; defaults are loaded internally.
+ * Overrides for the capabilities advertised in the ACP `initialize` handshake.
+ *
+ * `loadSession` and the three `prompt` flags reach the wire; they are the only session-shaped
+ * capabilities `AgentCapabilities` has a slot for at `@agentclientprotocol/sdk@0.22.1`.
+ *
+ * `forkSession` and `listSessions` were removed in #350. The protocol has nowhere to advertise
+ * them — neither name appears in its generated schema — and neither gated anything here:
+ * `session/fork` is refused unconditionally and `session/list` is answered from the in-memory
+ * store regardless. They were accepted, typed, documented, and inert.
  *
  * @public
  */
 interface AcpCapabilities {
+    /** Advertise `session/load`. Default `true`. The handler needs the SDK to be able to resume that id. */
     loadSession?: boolean;
-    forkSession?: boolean;
-    listSessions?: boolean;
+    /** Prompt content the host may send. Anything disabled here is a hint to the host, not a guard. */
     prompt?: {
+        /** Default `false`. Audio blocks are still accepted and counted against `maxPromptBytes`. */
         audio?: boolean;
+        /** Default `true`. */
         embeddedContext?: boolean;
+        /** Default `true`. Images are accepted but only the TEXT blocks of a prompt reach the agent. */
         image?: boolean;
     };
 }
 /**
- * Display info for the agent in the ACP host UI.
+ * Display info for the agent in an ACP host UI.
+ *
+ * Sent as `InitializeResponse.agentInfo` when you supply it (#350 — it was accepted and read by
+ * nothing). Omitted otherwise: defaulting to this package's own metadata would label every agent as
+ * the adapter serving it, and a name that is confidently wrong is worse for a host to display than
+ * one that is absent.
  *
  * @public
  */
 interface AcpAgentInfo {
+    /** Machine-ish identifier, e.g. `"my-bot"`. */
     name: string;
+    /** Human label preferred by a UI over `name`. */
     title?: string;
+    /** Semver of the agent, not of this package. */
     version: string;
 }
 /**
- * Options for `serveAcp()`.
+ * Options for {@link serveAcp}. Every field but `agent` is optional and every default is listed
+ * below — this object is the whole configuration surface, nothing is read from env or disk.
  *
  * @public
  */
 interface AcpServerOptions {
-    /** Single agent OR factory `(sessionId) => SDKAgent`. Required. */
+    /** The agent, or a per-session factory. Required; an unusable value throws before serving. */
     agent: AgentOrFactory;
-    /** Display info advertised in `initialize`. Defaults to package metadata. */
+    /** Name, title and version advertised as `agentInfo` in the `initialize` handshake. */
     info?: AcpAgentInfo;
-    /** Capability overrides for the `initialize` handshake. */
+    /** Handshake capability overrides. Only a subset is honoured — see {@link AcpCapabilities}. */
     capabilities?: AcpCapabilities;
-    /** Permission mode (default `"ask"`). See D355. */
+    /** Default `"ask"`. Read {@link PermissionMode} before choosing: `"auto"` disables the two fields below. */
     permissionDefault?: PermissionMode;
-    /** Timeout (ms) for `requestPermission` round-trip before vetoing (default 60_000). EC-2. */
+    /**
+     * How long to wait for the host to answer `session/request_permission` before BLOCKING the tool
+     * call (fail-closed, EC-2). Default `60_000` ms. Ignored unless `permissionDefault` is `"ask"`.
+     */
     permissionTimeoutMs?: number;
-    /** Tool names that bypass `ask` mode. */
+    /**
+     * Tool names that skip the permission round-trip. Matched by exact tool name.
+     *
+     * Effective in `"ask"` mode ONLY: `"auto"` never installs the plugin, and `"deny"` blocks these
+     * too.
+     */
     trustedTools?: ReadonlyArray<string>;
-    /** Cap on total prompt bytes (default 2 MiB). D360. */
+    /**
+     * Ceiling on the ACCUMULATED size of one prompt, in bytes. Default `2 * 1024 * 1024` (2 MiB), D360.
+     *
+     * Counted per block and summed: UTF-8 bytes for text, base64-DECODED bytes for image and audio,
+     * the URI for a resource link, the JSON form for an embedded resource. Crossing it rejects the
+     * whole prompt with `-32602` — see {@link PromptTooLargeError}.
+     */
     maxPromptBytes?: number;
-    /** Logger — defaults to `process.stderr.write` per D359. */
+    /**
+     * Sink for this package's diagnostics — one line per call, newline NOT included.
+     *
+     * Defaults to a write to `process.stderr` (D359). Never route this to stdout: stdout carries the
+     * JSON-RPC frames.
+     */
     log?: (msg: string) => void;
-    /** Override stdin (test seam). */
+    /** Override the protocol input stream. Defaults to `process.stdin`. Test seam. */
     stdin?: NodeJS.ReadableStream;
-    /** Override stdout (test seam). */
+    /** Override the protocol output stream. Defaults to `process.stdout`. Test seam. */
     stdout?: NodeJS.WritableStream;
 }
 /**
- * Thrown by `extractPrompt` when the decoded prompt exceeds `maxPromptBytes`.
- * Public so callers can `instanceof` it.
+ * Raised when a prompt's accumulated size passes `maxPromptBytes` (D360).
+ *
+ * `size` is the running total AT the block that crossed the limit, not the size of the full prompt:
+ * extraction stops at the first offending block, so blocks after it are never measured.
+ *
+ * Under {@link serveAcp} this never escapes to the caller — it is caught and returned to the ACP
+ * host as JSON-RPC `-32602` carrying `message` verbatim (`prompt exceeds N bytes (got M)`). The
+ * class is exported so that text has a named origin; the extractor that throws it is not part of the
+ * public surface, so there is no supported call site where a consumer can `instanceof` it directly.
  *
  * @public
  */
@@ -95,22 +165,90 @@ declare class PromptTooLargeError extends Error {
     constructor(size: number, limit: number);
 }
 
+/**
+ * Normalize `serveAcp({ agent })` into a uniform `AgentFactory` (D351).
+ *
+ * - Function input → passed through as-is. NOT duck-tested: any function is accepted, and a bad
+ *   return value only surfaces when the first session is created.
+ * - SDKAgent-shaped object → wrapped in a factory that returns that same instance for every session,
+ *   plus a one-time warning through `log` (a shared agent defeats per-session isolation).
+ * - Anything else → `InvalidAgentError` thrown synchronously.
+ *
+ * @internal
+ */
+
+/** Thrown when `serveAcp({ agent })` is neither a function nor an object with `agentId` + `send`. */
+declare class InvalidAgentError extends Error {
+    readonly name = "InvalidAgentError";
+}
+
 /**
  * `serveAcp({ agent })` — top-level entry that wires the ACP server.
  *
  * Constructs `AgentSideConnection` from `@agentclientprotocol/sdk@^0.22`,
  * delegates lifecycle methods to `lifecycle.ts`, and drives the prompt
- * translator from `translator.ts`. Per-invocation state (D356).
+ * translator from `translator.ts`. All state (sessions, warnings, defaults) is
+ * per invocation — nothing is module-global, so two `serveAcp` calls on
+ * different stream pairs do not see each other (D356).
  *
  * @public
  */
 
 /**
- * Block on a stdio JSON-RPC ACP server until stdin closes. Returns ONLY
- * after every active session has been disposed (EC-1).
+ * Serve `options.agent` to an ACP host over JSON-RPC on stdio, blocking until the input stream ends.
+ *
+ * ```ts
+ * await serveAcp({ agent: (sessionId) => Agent.create({ agentId: sessionId }) });
+ * ```
+ *
+ * Needs `@agentclientprotocol/sdk` and `@theokit/sdk` installed (peer dependencies). It reads no
+ * environment variable and no config file of its own; every knob is on {@link AcpServerOptions}.
+ * **Do not write to stdout** from the agent or its tools — that stream carries the protocol frames.
+ *
+ * Resolves once `stdin` emits `end` or `close` AND `dispose()` has settled for every live session
+ * (EC-1). A `dispose()` that throws is logged and swallowed, so a bad teardown cannot strand the
+ * process.
+ *
+ * Rejects only when it cannot start: an `InvalidAgentError` when `agent` is neither a function nor
+ * an object with a string `agentId` and a callable `send`. That class is exported, so branch on
+ * `instanceof InvalidAgentError` rather than on `err.name` (#369). Nothing that happens afterwards
+ * rejects this promise — per-request failures go back to
+ * the host as JSON-RPC errors:
+ *
+ * | Condition | Code |
+ * |---|---|
+ * | `cwd` absent or not on disk (`session/new`, `session/load`, `session/fork`) | `-32602` |
+ * | `session/load` for an id already loaded in this process | `-32602` |
+ * | prompt with no text block, or over `maxPromptBytes` | `-32602` |
+ * | `session/fork` whose parent IS loaded here — deferred to v0.2 | `-32602` |
+ * | `session/prompt` or `session/fork` naming a session this process has not loaded | `-32001` |
+ * | `session/load` the SDK cannot resume (wrong host, no shared storage) | `-32001` |
+ * | agent factory threw | `-32603` |
+ * | `permissionDefault` is `"ask"`/`"deny"` and the runtime cannot enforce it | `-32603` |
+ * | run ended in a status ACP has no stop reason for | `-32603` |
+ *
+ * `session/fork` checks the parent BEFORE `cwd`, so a fork naming a parent this process does not
+ * hold answers `-32001` and never reaches either `-32602` row above. Because the session store is
+ * in-memory and per-process, that is the common case after a restart — `session/fork` is refused in
+ * every case, but reading the refusal as "always `-32602`" is wrong.
+ *
+ * A prompt that completes maps the run onto an ACP stop reason: `end_turn`, `cancelled`, `refusal`
+ * (safety), `max_tokens` (context or token cap), `max_turn_requests` (iteration cap).
+ *
+ * Traps worth knowing before you wire a host to this:
+ * - `session/authenticate` always answers success without checking anything (D350) — do not read an
+ *   empty `authMethods` plus a successful authenticate as "the agent authorised me".
+ * - Only the TEXT blocks of a prompt reach the agent. Images, audio and resources are counted
+ *   against `maxPromptBytes`, then dropped.
+ * - `session/cancel` aborts the session's single `AbortController`, and nothing re-arms it. Every
+ *   later prompt on that session is issued with an already-aborted signal, so treat a cancelled
+ *   session as spent and open a new one.
+ * - Of the SDK stream, only assistant text, thinking and tool calls are forwarded; `status`, `task`
+ *   and `object_delta` messages have no ACP equivalent and are dropped silently.
+ * - `serveAcp` does not close `stdout` and does not call `process.exit` — the caller owns the exit.
  *
  * @public
  */
 declare function serveAcp(options: AcpServerOptions): Promise<void>;
 
-export { type AcpAgentInfo, type AcpCapabilities, type AcpServerOptions, type AgentFactory, type AgentOrFactory, type PermissionMode, PromptTooLargeError, serveAcp };
+export { type AcpAgentInfo, type AcpCapabilities, type AcpServerOptions, type AgentFactory, type AgentOrFactory, InvalidAgentError, type PermissionMode, PromptTooLargeError, serveAcp };