@noetic-tools/types 3.2.0 → 3.2.2

package/dist/types/acp.d.ts

@@ -0,0 +1,525 @@
+/**
+ * Agent Client Protocol (ACP) contract.
+ *
+ * Noetic drives external coding agents — Claude Code, Codex, Gemini CLI, any
+ * ACP-speaking binary — as an **ACP Client**. The agent is a JSON-RPC 2.0 peer
+ * reached over a duplex byte stream, so there is no vendor SDK per agent and no
+ * closed set of supported agents.
+ *
+ * This file is the direct analogue of the `ContextLayer` contract: defined in
+ * the foundation package so both `@noetic-tools/core` (which executes ACP steps)
+ * and `@noetic-tools/acp` (which implements the protocol) depend on it without
+ * forming a cycle. Core calls only the methods declared here — the ACP library's
+ * `ClientSideConnection` never enters core's dependency graph.
+ *
+ * Protocol types are re-used verbatim from `@zed-industries/agent-client-protocol`
+ * (spec version 1) rather than mirrored, so the wire surface cannot drift from
+ * the specification.
+ *
+ * @see https://agentclientprotocol.com/
+ */
+import type * as acp from '@zed-industries/agent-client-protocol';
+import type { TokenUsage } from './common.js';
+import type { Context } from './context.js';
+import type { FsAdapter } from './fs-adapter.js';
+import type { Item } from './items.js';
+import type { ShellAdapter } from './shell-adapter.js';
+/**
+ * The single step kind backing every ACP agent. Unlike the closed harness enum
+ * it replaces, the *agent* is identified by a free-form `agentId` on the
+ * adapter — so adding an agent never touches core or the published JSON Schema.
+ * @public
+ */
+export declare const ACP_AGENT_STEP_KIND = "acp-agent";
+/**
+ * A bidirectional byte stream to an ACP agent — the substrate JSON-RPC frames
+ * ride on.
+ *
+ * This is deliberately *not* built on {@link SubprocessAdapter}: that contract
+ * returns a durable handle (`id`/`status`/`metadata`) with no attached stdio,
+ * and {@link ShellAdapter} is one-shot. ACP needs a long-lived duplex pipe.
+ * @public
+ */
+export interface AcpTransport {
+    /** Frames arriving from the agent. */
+    readonly readable: ReadableStream<Uint8Array>;
+    /** Frames sent to the agent. */
+    readonly writable: WritableStream<Uint8Array>;
+    /** Tear the stream down and release the underlying resource (process, socket, …). */
+    close(): Promise<void>;
+}
+/** @public Options a transport factory receives when a step opens a connection. */
+export interface AcpTransportOptions {
+    /** Working directory the agent process should start in. */
+    cwd: string;
+    /** Environment overrides layered onto the host environment. */
+    env?: Record<string, string | undefined>;
+    /** Aborting this signal closes the transport. */
+    signal?: AbortSignal;
+}
+/**
+ * Opens a transport on demand. Local agents use a stdio transport over a child
+ * process; tests use an in-memory loopback; remote agents can use anything that
+ * yields a duplex byte stream.
+ * @public
+ */
+export type AcpTransportFactory = (opts: AcpTransportOptions) => Promise<AcpTransport>;
+/** @public How a permission request was resolved. */
+export declare const AcpPermissionDecision: {
+    readonly Allow: 'allow';
+    readonly Deny: 'deny';
+    readonly Cancel: 'cancel';
+};
+/** @public Union of permission decisions. */
+export type AcpPermissionDecision = (typeof AcpPermissionDecision)[keyof typeof AcpPermissionDecision];
+/**
+ * The resolved answer to an ACP `session/request_permission` call. The client
+ * translates it into the concrete {@link acp.PermissionOption} the agent
+ * offered — `optionId` pins an exact option when the resolver picked one.
+ * @public
+ */
+export interface AcpPermissionOutcome {
+    decision: AcpPermissionDecision;
+    /** Exact option id to select. When omitted the client picks by `decision`. */
+    optionId?: string;
+    /** Why this decision was made — surfaced on framework events and the steering ledger. */
+    reason?: string;
+}
+/**
+ * Matches a tool call the agent wants to run. An omitted field matches anything;
+ * all present fields must match.
+ * @public
+ */
+export interface AcpPermissionRule {
+    /** ACP tool classification (`read`, `edit`, `execute`, …). */
+    kind?: acp.ToolKind;
+    /** Matches the tool call title — substring (case-insensitive) or pattern. */
+    title?: string | RegExp;
+}
+/**
+ * Declarative permission policy evaluated before the steering pipeline and the
+ * `onPermissionRequest` handler.
+ * @public
+ */
+export interface AcpPermissionPolicy {
+    /**
+     * Decision when no rule matches and no later resolver decides. Defaults to
+     * `'deny'` — an unattended agent must not get blanket approval by omission.
+     */
+    default?: AcpPermissionDecision;
+    /** Rules granting permission. Evaluated before {@link deny}. */
+    allow?: ReadonlyArray<AcpPermissionRule>;
+    /** Rules refusing permission. */
+    deny?: ReadonlyArray<AcpPermissionRule>;
+    /**
+     * Prefer the agent's `allow_always` / `reject_always` options over the
+     * `*_once` variants, so a decision persists for the rest of the session.
+     */
+    persist?: boolean;
+}
+/**
+ * Async escape hatch for decisions a declarative policy cannot express —
+ * human-in-the-loop approval, a remote policy service, an LLM judge.
+ *
+ * Receives the executing {@link Context} because reaching a human almost always
+ * means reaching a channel: `ctx.send` the request out, `ctx.recv` the decision
+ * back. Without it a handler could only answer from what it closed over.
+ * @public
+ */
+export type AcpPermissionHandler = (request: acp.RequestPermissionRequest, ctx: Context, info: AcpPermissionRequestInfo) => Promise<AcpPermissionOutcome>;
+/**
+ * Which agent and step raised a permission request. The protocol request says
+ * what the agent wants to do but not who is asking, and a human answering
+ * needs both to make sense of the prompt.
+ * @public
+ */
+export interface AcpPermissionRequestInfo {
+    /** `agentId` of the adapter whose turn raised the request. */
+    agentId: string;
+    /** Id of the step whose turn raised it. */
+    stepId: string;
+}
+/**
+ * The handler as the protocol client sees it — already bound to the executing
+ * context by the runtime. Keeps `Context` out of the client, which only needs
+ * to ask the question and get an answer.
+ * @public
+ */
+export type AcpBoundPermissionHandler = (request: acp.RequestPermissionRequest) => Promise<AcpPermissionOutcome>;
+/**
+ * The steering tier of permission resolution. Returning `undefined` abstains,
+ * handing the decision to the next tier. The runtime wires this to the same
+ * `beforeToolCall` pipeline that governs first-party tool calls, so one rule set
+ * covers both.
+ * @public
+ */
+export type AcpPermissionSteerer = (request: acp.RequestPermissionRequest) => Promise<AcpPermissionOutcome | undefined>;
+/**
+ * Which ACP client capabilities to advertise during `initialize`. Every flag
+ * defaults to enabled when the host can back it; setting one to `false`
+ * withdraws it, so the agent never attempts the call.
+ * @public
+ */
+export interface AcpClientCapabilityConfig {
+    /** Serve `fs/read_text_file` from the host's {@link FsAdapter}. */
+    readTextFile?: boolean;
+    /** Serve `fs/write_text_file` from the host's {@link FsAdapter}. */
+    writeTextFile?: boolean;
+    /** Serve the `terminal/*` family from the host's {@link ShellAdapter}. */
+    terminal?: boolean;
+    /**
+     * Directories the agent may reach in addition to the session working
+     * directory, which is always allowed. Use for a monorepo sibling, a shared
+     * cache, or a scratch dir outside the workspace.
+     */
+    additionalDirectories?: ReadonlyArray<string>;
+    /**
+     * Lift filesystem confinement entirely, letting the agent read and write any
+     * absolute path the host process can.
+     *
+     * Off by default, and worth leaving off: ACP places boundary enforcement on
+     * the client, and a `permissions` policy does not substitute for it — that
+     * answers `session/request_permission`, which covers the agent's tool calls,
+     * not the `fs/*` methods it invokes on the client directly.
+     */
+    allowAnyPath?: boolean;
+}
+/**
+ * The client methods an agent can invoke on us. Closed by ACP spec version 1,
+ * so a literal union rather than `string`: a typo in a descriptor is a compile
+ * error, and consumers narrowing on `activity.method` get exhaustiveness.
+ * @public
+ */
+export type AcpClientMethod = 'fs/read_text_file' | 'fs/write_text_file' | 'terminal/create' | 'terminal/output' | 'terminal/wait_for_exit' | 'terminal/kill' | 'terminal/release';
+/**
+ * One client-side operation an agent performed — or was refused. Emitted for
+ * every `fs/*` and `terminal/*` call the agent makes.
+ *
+ * This is an *observed* record, not the agent's self-report: `tool_call`
+ * updates say what the agent claims it did, while this says what it actually
+ * asked the client to do, including the calls that were turned down.
+ * @public
+ */
+export interface AcpClientActivity {
+    /** The ACP client method invoked, e.g. `fs/read_text_file`. */
+    method: AcpClientMethod;
+    /** Path involved, for the `fs/*` family and `terminal/create`'s cwd. */
+    path?: string;
+    /** Command line, for `terminal/create`. */
+    command?: string;
+    /** Terminal handle, for the `terminal/*` family. */
+    terminalId?: string;
+    /** False when the call was refused — by a withdrawn capability or confinement. */
+    allowed: boolean;
+    /** Why it was refused. */
+    reason?: string;
+}
+/**
+ * The runtime surface an ACP connection is given to satisfy client-side
+ * requests. Because file reads/writes and terminal commands are served from
+ * Noetic's own adapters, everything the sub-agent touches passes through the
+ * same sandboxing, virtual-filesystem, and audit machinery as first-party steps.
+ * @public
+ */
+export interface AcpClientHost {
+    /** Working directory for the session (resolved from `ctx.cwdState.cwd`). */
+    readonly cwd: string;
+    readonly fs: FsAdapter;
+    readonly shell: ShellAdapter;
+    /** Conversation thread id, for hosts that scope state per thread. */
+    readonly threadId: string;
+    /** Abort signal for the surrounding execution. */
+    readonly signal?: AbortSignal;
+    /**
+     * Capability advertisement overrides. Connection-level: ACP negotiates the
+     * client capability set once during `initialize`, so this cannot change for
+     * the life of a connection.
+     */
+    readonly capabilities?: AcpClientCapabilityConfig;
+    /**
+     * Permission resolution, in the order it is consulted: the declarative
+     * policy, then steering, then the async handler. The protocol client owns the
+     * resolution logic; the host only supplies the inputs.
+     *
+     * These are **per-turn**, and deliberately mutable: a session reused across
+     * several steps must answer with the CURRENT step's policy, not the one that
+     * happened to open the connection. The client reads them at call time, so
+     * the runtime updates them before each turn.
+     */
+    permissions?: AcpPermissionPolicy;
+    steerPermission?: AcpPermissionSteerer;
+    onPermissionRequest?: AcpBoundPermissionHandler;
+    /**
+     * Receive every `session/update` notification for the active session. Also
+     * per-turn — it routes to the running step's event bridge, so a reused
+     * session's output is attributed to the step that actually asked for it.
+     */
+    onSessionUpdate: (notification: acp.SessionNotification) => void;
+    /**
+     * Receive every `fs/*` and `terminal/*` call the agent makes, allowed or
+     * refused. Per-turn like {@link onSessionUpdate}, so activity is attributed
+     * to the step that actually caused it.
+     */
+    onClientActivity?: (activity: AcpClientActivity) => void;
+}
+/**
+ * Why the agent stopped a turn. Derived from `PromptResponse` because the
+ * protocol package inlines the union rather than exporting it by name.
+ * @public
+ */
+export type AcpStopReason = acp.PromptResponse['stopReason'];
+/** @public Input for one `session/prompt` turn. */
+export interface AcpPromptOptions {
+    /**
+     * Prompt content blocks. Validated against the agent's advertised
+     * `promptCapabilities` before sending — the spec requires clients to restrict
+     * content types to what the agent accepts.
+     */
+    content: ReadonlyArray<acp.ContentBlock>;
+    /** Aborting this signal issues `session/cancel` and awaits the `cancelled` stop reason. */
+    signal?: AbortSignal;
+}
+/**
+ * Result of a completed turn. The interpreter appends `items` to the item log,
+ * charges `usage`/`cost`, records `stopReason`, and returns `text` (or parses it
+ * through the step's output schema).
+ * @public
+ */
+export interface AcpTurnResult {
+    /** Why the agent stopped — drives the interpreter's success/error decision. */
+    stopReason: AcpStopReason;
+    /** Noetic Items produced this turn (assistant message, tool calls, tool results). */
+    items: Item[];
+    /** Concatenated assistant text of the turn. */
+    text: string;
+    usage?: TokenUsage;
+    cost?: number;
+    /** Plan entries reported via `plan` updates, latest snapshot wins. */
+    plan?: ReadonlyArray<acp.PlanEntry>;
+    /** Slash commands the agent advertised during the turn. */
+    availableCommands?: ReadonlyArray<acp.AvailableCommand>;
+    /** Mode the session ended the turn in, when the agent reports modes. */
+    currentModeId?: string;
+}
+/** @public Options for creating a session. */
+export interface AcpNewSessionOptions {
+    /** Absolute working directory for the session. */
+    cwd: string;
+    /** MCP servers the agent should connect to, gated by its `mcpCapabilities`. */
+    mcpServers?: ReadonlyArray<acp.McpServer>;
+}
+/** @public Options for resuming a previously created session via `session/load`. */
+export interface AcpLoadSessionOptions extends AcpNewSessionOptions {
+    sessionId: string;
+}
+/**
+ * One ACP session: a conversation with its own history and state, living on the
+ * far side of a connection.
+ * @public
+ */
+export interface AcpSession {
+    readonly sessionId: string;
+    /** Mode state when the agent supports session modes. */
+    readonly modes?: acp.SessionModeState;
+    /** Slash commands currently offered, refreshed by `available_commands_update`. */
+    readonly availableCommands: ReadonlyArray<acp.AvailableCommand>;
+    /** Run one prompt turn to completion. */
+    prompt(opts: AcpPromptOptions): Promise<AcpTurnResult>;
+    /** Send `session/cancel` for an in-flight turn. */
+    cancel(): Promise<void>;
+    /** Switch mode. Throws when the agent advertised no modes. */
+    setMode(modeId: string): Promise<void>;
+    /** Switch model. Throws when the agent advertised no models. */
+    setModel(modelId: string): Promise<void>;
+}
+/**
+ * A negotiated connection to an ACP agent — one `initialize` handshake and one
+ * transport, able to carry several sessions.
+ * @public
+ */
+export interface AcpAgentConnection {
+    /** Everything the agent advertised during `initialize`. */
+    readonly agentCapabilities: acp.AgentCapabilities;
+    /** Authentication methods the agent offers, empty when it needs none. */
+    readonly authMethods: ReadonlyArray<acp.AuthMethod>;
+    /** Protocol version agreed with the agent. */
+    readonly protocolVersion: number;
+    /** Run the `authenticate` flow for one of {@link authMethods}. */
+    authenticate(methodId: string): Promise<void>;
+    /** Create a session (`session/new`). */
+    newSession(opts: AcpNewSessionOptions): Promise<AcpSession>;
+    /**
+     * Resume a session (`session/load`). Throws {@link AcpCapabilityError} when
+     * the agent did not advertise `loadSession`.
+     */
+    loadSession(opts: AcpLoadSessionOptions): Promise<AcpSession>;
+    /** Close the connection and release the transport. */
+    close(): Promise<void>;
+}
+/**
+ * A live connection plus the session running on it. The runtime keeps these
+ * keyed by {@link AcpSessionPolicy.reuse} so a session can span several steps.
+ * @public
+ */
+export interface AcpLiveSession {
+    connection: AcpAgentConnection;
+    session: AcpSession;
+    /**
+     * The host this connection was opened with. The runtime rebinds its
+     * per-turn fields before every turn, so a session shared by several steps
+     * honours each step's own permissions, steering, and event stream.
+     */
+    host: AcpClientHost;
+    /** `agentId` of the adapter that opened this connection, for reuse conflict checks. */
+    agentId: string;
+    /** How long this connection is kept alive; decides who closes it and when. */
+    keepAlive: AcpKeepAlive;
+    /** Working directory the session was created in — fixed for its lifetime. */
+    cwd: string;
+    /** MCP servers attached at creation — also fixed for its lifetime. */
+    mcpServers?: ReadonlyArray<acp.McpServer>;
+}
+/** @public Options handed to {@link AcpAgent.connect}. */
+export interface AcpConnectOptions {
+    /** The runtime surface backing client-side ACP methods. */
+    host: AcpClientHost;
+    signal?: AbortSignal;
+}
+/**
+ * An ACP agent adapter. `@noetic-tools/acp` exports presets (`claudeCode()`,
+ * `codex()`, `gemini()`, `customAcpAgent()`) that return one of these.
+ * @public
+ */
+export interface AcpAgent {
+    /** Spec tag for forward-compatibility. */
+    readonly specificationVersion: 'acp-v1';
+    /**
+     * Stable identifier for the agent (`'claude-code'`, `'codex'`, …). Free-form:
+     * the set of agents is open, and this is only used for registry lookup,
+     * observability, and error messages.
+     */
+    readonly agentId: string;
+    /** Open a transport, run `initialize`, and return the negotiated connection. */
+    connect(opts: AcpConnectOptions): Promise<AcpAgentConnection>;
+}
+/**
+ * Controls how an ACP connection is reused and torn down across steps.
+ * @public
+ */
+/**
+ * How long an ACP connection outlives the step that opened it.
+ *
+ * A connection owns a live agent — usually a child process whose stdio keeps
+ * the event loop alive — so keeping one is never inferred. Every level beyond
+ * the default is something the step asks for explicitly.
+ * @public
+ */
+export declare const AcpKeepAlive: {
+    /** Closed when the step finishes. The default. */
+    readonly Step: 'step';
+    /** Kept for the rest of the root run, then closed by the harness. */
+    readonly Run: 'run';
+    /** Kept until {@link AcpSessionDisposer.closeAcpSessions} is called. Nothing closes it for you. */
+    readonly Harness: 'harness';
+};
+/** @public Union of connection keep-alive scopes. */
+export type AcpKeepAlive = (typeof AcpKeepAlive)[keyof typeof AcpKeepAlive];
+/**
+ * Controls how an ACP connection is shared and how long it is kept alive.
+ * @public
+ */
+export interface AcpSessionPolicy {
+    /**
+     * Share one live connection + session under this id, so later steps take
+     * their turns against the same agent. Requires {@link keepAlive} `'run'` or
+     * `'harness'` — a connection closed at the end of its step has nothing left
+     * to share.
+     */
+    reuse?: string;
+    /**
+     * How long to keep the connection alive. Defaults to `'step'`: the
+     * connection is closed as soon as the step finishes, so nothing is
+     * maintained unless the step says so.
+     *
+     * `'harness'` hands ownership to the caller — the runtime will not close it,
+     * and an undisposed connection keeps the host process from exiting. Call
+     * `harness.closeAcpSessions()` when the work is done.
+     */
+    keepAlive?: AcpKeepAlive;
+    /**
+     * Resume this ACP session id via `session/load` instead of creating a new one.
+     * Requires the agent's `loadSession` capability.
+     */
+    load?: string;
+}
+/**
+ * A snapshot of one live ACP sub-agent — what a UI needs to show it and offer
+ * actions on it, without handing out the connection itself.
+ * @public
+ */
+export interface AcpSessionInfo {
+    /** Opaque handle for this session — pass it back to `getAcpSession`/`cancelAcpSession`. */
+    key: string;
+    /** The `session.reuse` key the step named, when it named one. */
+    reuseKey?: string;
+    /** `agentId` of the adapter driving it. */
+    agentId: string;
+    /** The agent's own session id. */
+    sessionId: string;
+    keepAlive: AcpKeepAlive;
+    /** Current mode, when the agent supports modes. */
+    currentModeId?: string;
+    /** Modes the agent offers, for a mode switcher. */
+    availableModes: ReadonlyArray<acp.SessionMode>;
+    /** Slash commands the agent currently advertises. */
+    availableCommands: ReadonlyArray<acp.AvailableCommand>;
+}
+/**
+ * The disposal surface for connections kept past their run. Implemented by
+ * `AgentHarness`; declared here so callers can hold the capability without
+ * depending on the concrete runtime.
+ * @public
+ */
+export interface AcpSessionDisposer {
+    /** Close every ACP connection this harness still holds. Idempotent. */
+    closeAcpSessions(): Promise<void>;
+}
+/**
+ * Thrown when an ACP agent is asked for a capability it did not advertise
+ * during `initialize` — loading a session, switching mode, sending image
+ * content. Raised before anything reaches the wire.
+ * @public
+ */
+export declare class AcpCapabilityError extends Error {
+    readonly agentId: string;
+    readonly capability: string;
+    constructor(opts: {
+        agentId: string;
+        capability: string;
+        message?: string;
+    });
+}
+/** @public Type guard for {@link AcpCapabilityError}. */
+export declare function isAcpCapabilityError(e: unknown): e is AcpCapabilityError;
+/**
+ * Thrown when a connection cannot be established — the agent binary is missing,
+ * the handshake fails, or authentication is required and unsatisfied.
+ * @public
+ */
+export declare class AcpConnectError extends Error {
+    readonly agentId: string;
+    readonly connectCause?: unknown;
+    constructor(opts: {
+        agentId: string;
+        message: string;
+        cause?: unknown;
+    });
+}
+/** @public Type guard for {@link AcpConnectError}. */
+export declare function isAcpConnectError(e: unknown): e is AcpConnectError;
+/**
+ * The ACP protocol surface, re-exported so consumers get the wire types without
+ * taking a direct dependency on the protocol package.
+ * @public
+ */
+export type { AgentCapabilities as AcpAgentCapabilities, AuthMethod as AcpAuthMethod, AvailableCommand as AcpAvailableCommand, ContentBlock as AcpContentBlock, McpServer as AcpMcpServer, PermissionOption as AcpPermissionOption, PlanEntry as AcpPlanEntry, PromptCapabilities as AcpPromptCapabilities, RequestPermissionRequest as AcpRequestPermissionRequest, SessionMode as AcpSessionMode, SessionModeState as AcpSessionModeState, SessionNotification as AcpSessionNotification, ToolCallContent as AcpToolCallContent, ToolCallStatus as AcpToolCallStatus, ToolKind as AcpToolKind, } from '@zed-industries/agent-client-protocol';

package/dist/types/acp.js

@@ -0,0 +1,101 @@
+/**
+ * Agent Client Protocol (ACP) contract.
+ *
+ * Noetic drives external coding agents — Claude Code, Codex, Gemini CLI, any
+ * ACP-speaking binary — as an **ACP Client**. The agent is a JSON-RPC 2.0 peer
+ * reached over a duplex byte stream, so there is no vendor SDK per agent and no
+ * closed set of supported agents.
+ *
+ * This file is the direct analogue of the `ContextLayer` contract: defined in
+ * the foundation package so both `@noetic-tools/core` (which executes ACP steps)
+ * and `@noetic-tools/acp` (which implements the protocol) depend on it without
+ * forming a cycle. Core calls only the methods declared here — the ACP library's
+ * `ClientSideConnection` never enters core's dependency graph.
+ *
+ * Protocol types are re-used verbatim from `@zed-industries/agent-client-protocol`
+ * (spec version 1) rather than mirrored, so the wire surface cannot drift from
+ * the specification.
+ *
+ * @see https://agentclientprotocol.com/
+ */
+//#region Step-kind discriminator
+/**
+ * The single step kind backing every ACP agent. Unlike the closed harness enum
+ * it replaces, the *agent* is identified by a free-form `agentId` on the
+ * adapter — so adding an agent never touches core or the published JSON Schema.
+ * @public
+ */
+export const ACP_AGENT_STEP_KIND = 'acp-agent';
+//#endregion
+//#region Permissions
+/** @public How a permission request was resolved. */
+export const AcpPermissionDecision = {
+    Allow: 'allow',
+    Deny: 'deny',
+    Cancel: 'cancel',
+};
+//#endregion
+//#region Session policy
+/**
+ * Controls how an ACP connection is reused and torn down across steps.
+ * @public
+ */
+/**
+ * How long an ACP connection outlives the step that opened it.
+ *
+ * A connection owns a live agent — usually a child process whose stdio keeps
+ * the event loop alive — so keeping one is never inferred. Every level beyond
+ * the default is something the step asks for explicitly.
+ * @public
+ */
+export const AcpKeepAlive = {
+    /** Closed when the step finishes. The default. */
+    Step: 'step',
+    /** Kept for the rest of the root run, then closed by the harness. */
+    Run: 'run',
+    /** Kept until {@link AcpSessionDisposer.closeAcpSessions} is called. Nothing closes it for you. */
+    Harness: 'harness',
+};
+//#endregion
+//#region Errors
+/**
+ * Thrown when an ACP agent is asked for a capability it did not advertise
+ * during `initialize` — loading a session, switching mode, sending image
+ * content. Raised before anything reaches the wire.
+ * @public
+ */
+export class AcpCapabilityError extends Error {
+    agentId;
+    capability;
+    constructor(opts) {
+        super(opts.message ??
+            `ACP agent '${opts.agentId}' did not advertise the '${opts.capability}' capability.`);
+        this.name = 'AcpCapabilityError';
+        this.agentId = opts.agentId;
+        this.capability = opts.capability;
+    }
+}
+/** @public Type guard for {@link AcpCapabilityError}. */
+export function isAcpCapabilityError(e) {
+    return e instanceof AcpCapabilityError;
+}
+/**
+ * Thrown when a connection cannot be established — the agent binary is missing,
+ * the handshake fails, or authentication is required and unsatisfied.
+ * @public
+ */
+export class AcpConnectError extends Error {
+    agentId;
+    connectCause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'AcpConnectError';
+        this.agentId = opts.agentId;
+        this.connectCause = opts.cause;
+    }
+}
+/** @public Type guard for {@link AcpConnectError}. */
+export function isAcpConnectError(e) {
+    return e instanceof AcpConnectError;
+}
+//#endregion

package/dist/types/common.d.ts

@@ -54,6 +54,12 @@ export interface TokenUsage {
     input: number;
     output: number;
     total: number;
+    /**
+     * Prompt tokens served from the provider's cache, summed across every model
+     * call on this execution. `undefined` — not `0` — while no call has reported a
+     * cache figure, preserving the `RoundUsage` distinction between "nothing was
+     * cached" and "this provider says nothing about caching".
+     */
     cached?: number;
 }
 /**
@@ -78,6 +84,12 @@ export interface StepMeta {
     usage?: RoundUsage;
     cost?: number;
     responseItems?: ReadonlyArray<Item>;
+    /**
+     * Why an ACP agent stopped its turn. Set only by `acp-agent` steps, and the
+     * only way a caller can tell a truncated turn (`max_tokens`,
+     * `max_turn_requests`) from a complete one — both return normally.
+     */
+    acpStopReason?: string;
 }
 /** @public Structured response returned by a model adapter after an LLM call. */
 export interface LLMResponse {