llm-cli-gateway 2.6.3 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,89 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.8.0] - 2026-06-14: HTTP workspace gating and ACP transport
+
+### Added
+
+- Added ACP gateway extension foundations, including the contract, config and
+  capability surface, and transport core.
+- Added provider CLI release-target evidence for release validation: exact
+  probed Claude Code, Codex, Antigravity (`agy`), Grok, and Mistral Vibe
+  versions plus artifact SHA-256 values.
+- Added Gemini, Grok, and Mistral pricing families and Codex token/cache usage
+  telemetry extraction.
+
+### Changed
+
+- HTTP and tunnel provider execution now uses explicit request transport
+  metadata and requires a registered workspace, default workspace, or session
+  workspace before spawning a provider across sync/async request tools and
+  `codex_fork_session`. Local stdio keeps the prior unrestricted
+  `workingDir`/`addDir` behavior.
+- Replaced the OAuth-only remote workspace guard with transport-based HTTP
+  workspace gating, so bearer, OAuth, auth-disabled, and configured no-auth
+  connector HTTP paths all fail closed before provider spawn.
+- Replaced CodeQL with the OSS SAST workflow using OpenGrep, gosec, and
+  govulncheck.
+
+### Fixed
+
+- Corrected Claude default pricing/cache classification and Grok API pricing
+  bucket handling.
+- Preserved captured async orphan readbacks as completed flight-recorder rows
+  when stdout was captured and no failure was recorded.
+
+### Documentation
+
+- Documented Grok CLI prompt-surface telemetry limitations.
+- Documented ACP gateway extension research, design, and smoke validation.
+
+## [2.7.0] - 2026-06-12: Provider capability inventory
+
+### Added
+
+- Added `provider_tool_capabilities`, a read-only MCP tool that reports the
+  gateway request tools, provider kind, supported controls, feature flags,
+  model info, config-surface hints, local skill discovery, provider-native tool
+  discovery, unsupported/degraded inputs, warnings, and cache metadata for
+  Claude Code, Codex CLI, Gemini/Antigravity (`agy`), Grok CLI, optional
+  `grok_api`, and Mistral Vibe.
+- Added `provider-tools://catalog` and per-provider resources
+  `provider-tools://claude`, `provider-tools://codex`,
+  `provider-tools://gemini`, `provider-tools://grok`,
+  `provider-tools://grok_api`, and `provider-tools://mistral` for clients that
+  prefer resource discovery over tool calls.
+- Added `doctor --json` `provider_capabilities`, a compact setup-assistant
+  summary with schema version, resource URIs, per-provider request tools,
+  supported feature names, unsupported input names, config-surface counts,
+  discovered skill/tool counts, and warnings without raw local paths.
+- Added bounded, redacted local skill/config discovery for provider capability
+  reporting. Grok local/bundled skills can now surface provider-native tools
+  such as Imagine `image_gen`, `image_edit`, `image_to_video`, and
+  `reference_to_video` when present, while keeping execution routed through
+  `grok_request`.
+
+### Changed
+
+- Updated agent skills so LLM agents have provider-specific gateway usage
+  guidance for Claude, Codex, Gemini/Antigravity (`agy`), Grok, and Mistral
+  Vibe, and so orchestration skills check `provider_tool_capabilities` before
+  assuming tool allowlists, MCP-server semantics, sessions, output formats, or
+  provider-native tools.
+- Updated setup assistant guidance and `setup/status.schema.json` so install
+  agents treat `doctor.provider_capabilities` as the compact source of truth
+  for outbound provider capability claims.
+- Documented the intentionally published prod-only `npm-shrinkwrap.json` in
+  README and `socket.yml`, including the release audit and packed-consumer
+  checks that bound the shrinkwrap and shell-spawn Socket alerts.
+
+### Fixed
+
+- Corrected stale internal skill guidance that described Codex continuity as
+  bookkeeping-only, described Gemini allowlists/MCP allowlists as pass-through,
+  omitted Mistral async from async orchestration docs, or encouraged copying
+  Claude tool names into other provider allowlists.
+
 ## [2.6.3] - 2026-06-12: Claude cache-control veracity and Grok 0.2.50
 
 ### Fixed

package/README.md

@@ -45,7 +45,7 @@ Or use directly with `npx` from an MCP client:
 - Can run requests inside gateway-managed git worktrees for isolated multi-agent review and implementation loops.
 - Ships personal-appliance setup surfaces: HTTP transport with bearer-token auth, `doctor --json`, setup UI artifacts, provider setup snippets, Docker fallback, and checked release bundles.
 - Remote web connectors use MCP OAuth discovery and authorization-code setup with static client or shared-secret gates. Client secrets are generated locally, stored only as hashes, and printed only by explicit copy-once commands.
-- Provider CLI requests can select registered workspaces by alias via `workspace`; remote requests should use aliases, not arbitrary filesystem paths. New local folder/Git workspaces can be created only under configured allowed roots.
+- Provider CLI requests can select registered workspaces by alias via `workspace`; every HTTP/tunnel request must use a registered alias, session workspace, or `[workspaces].default` before provider execution. Local unrestricted filesystem access is the stdio transport.
 
 ## Workflow Assets
 
@@ -62,6 +62,8 @@ The next documentation focus is provider-specific skill and DAG-TOML pairs for e
 - Security CI runs actionlint, zizmor, shellcheck, typos, osv-scanner, gitleaks, and lychee.
 - GitHub release installer artifacts are checksummed and signed with Sigstore keyless signing.
 - npm releases use provenance through OIDC trusted publishing.
+- The npm package intentionally ships a generated, prod-only `npm-shrinkwrap.json` so registry installs resolve the audited release tree. Release gates regenerate it from `package-lock.json`, compare for parity, and run a registry-fidelity consumer install before publishing.
+- Socket behavioural alerts are documented in [`socket.yml`](./socket.yml) and under "Security Considerations" below. `shellAccess` and `shrinkwrap` are reviewed package capabilities/configuration for this CLI appliance, not hidden install behaviour.
 
 ## Personal MCP Appliance
 
@@ -167,6 +169,7 @@ docker compose -f docker/personal.compose.yml run --rm doctor
 - **SQLite Flight Recorder**: Every request/response logged to `~/.llm-cli-gateway/logs.db` with correlation IDs, token usage, duration, retry counts, and circuit breaker state. Browse with [Datasette](https://datasette.io/): `datasette ~/.llm-cli-gateway/logs.db`
 - **Structured Metadata**: Tool responses include machine-readable `structuredContent` (model, cli, correlationId, sessionId, durationMs, token counts)
 - **Cache observability resources**: `cache-state://global`, `cache-state://session/{id}`, and `cache-state://prefix/{hash}` MCP resources return aggregate cache hit/miss/savings — tokens and hashes only, no prompt text. `session_get` includes a `cacheState` block when the session has prior requests.
+- **Provider capability inventory**: `provider_tool_capabilities` and `provider-tools://catalog` expose the gateway request fields, supported/degraded provider controls, local skill/tool discovery, and safe config-surface hints for Claude Code, Codex CLI, Gemini/Antigravity, Grok CLI/API, and Mistral Vibe. `doctor --json` includes a compact `provider_capabilities` summary for setup assistants.
 
 ### Cache-aware operation
 
@@ -334,6 +337,8 @@ For clients that already support local stdio MCP servers, add a configuration li
 }
 ```
 
+Stdio is the recommended path for unrestricted machine-local development access. HTTP MCP, including localhost HTTP and tunneled HTTPS, is treated as remote-capable for provider execution: provider tools must resolve a registered workspace alias, a session workspace, or `[workspaces].default` before spawning a CLI. Remote clients should pass relative `workingDir`, `addDir`, and include-directory values inside the selected workspace; disabling auth or using a no-auth connector path is not a filesystem bypass.
+
 This generic stdio example is not provider-support verification for the Personal MCP Appliance. Client-specific setup guides for ChatGPT, Claude web, Claude Desktop, Codex, Gemini CLI, Gemini web, and Grok remain gated by the provider-support matrix in [docs/personal-mcp/PRODUCT_CONTRACT.md](docs/personal-mcp/PRODUCT_CONTRACT.md).
 
 ### Available Tools
@@ -396,6 +401,8 @@ Execute a Claude Code request with optional session management.
 - `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
+Workspace boundary: stdio callers may use machine-local paths directly. HTTP/tunnel callers must pass `workspace` or rely on a configured default/session workspace; path fields are then validated relative to that workspace. `[workspaces].allow_unregistered_working_dir` is a stdio/local legacy setting and does not allow arbitrary HTTP working directories or additional directories.
+
 **Response extras:**
 
 - `approval`: Approval decision record when `approvalStrategy="mcp_managed"`
@@ -1019,6 +1026,42 @@ GEMINI_HISTORY_ROOT=/path/to/.gemini/tmp
 LLM_GATEWAY_DISABLE_MODEL_DISCOVERY=1
 ```
 
+##### `provider_tool_capabilities`
+
+Report the provider tool and feature capability catalog. Use this before
+orchestrating provider-specific requests so callers can distinguish supported
+controls, provider-owned configuration, ignored parity fields, and unsupported
+inputs.
+
+**Parameters:**
+
+- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"grok_api"`, or `"mistral"`)
+- `includeSkills` (boolean, default `true`): Include bounded local skill discovery
+- `includeProviderTools` (boolean, default `true`): Include provider-native tools extracted from discovered skills
+- `includeUnsupported` (boolean, default `true`): Include explicit unsupported/degraded input records
+- `includePaths` (boolean, default `false`): Include raw local filesystem paths in discovery output
+- `refresh` (boolean, default `false`): Bypass the short-lived capability cache
+
+The response schema is `provider-tool-capabilities.v2`. Capability discovery is
+read-only and bounded; raw local paths are redacted unless `includePaths` is
+explicitly true, and secret-bearing auth files are not read.
+
+Equivalent MCP resources:
+
+- `provider-tools://catalog`: full provider catalog
+- `provider-tools://claude`
+- `provider-tools://codex`
+- `provider-tools://gemini`
+- `provider-tools://grok`
+- `provider-tools://grok_api`
+- `provider-tools://mistral`
+
+`doctor --json` also emits a compact `provider_capabilities` block with the
+same schema version, per-provider request tool names, supported feature names,
+unsupported input names, config-surface counts, discovery counts, and resource
+URIs. This block is intended for setup assistants that need a concise capability
+summary without local skill bodies or raw paths.
+
 ##### `cli_versions`
 
 Report installed CLI versions.
@@ -1299,15 +1342,18 @@ The gateway supports concurrent requests across different CLIs. Each request spa
 
 ### Socket alerts — context for reviewers
 
-If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/package/llm-cli-gateway) or a similar supply-chain scanner, you'll see behavioural alerts and some dependency-ownership alerts. They are accurate descriptions of what the package does and what it depends on. The reviewed `shellAccess` capability is configured in `socket.yml` for repository/PR policy surfaces, but Socket's public package page may still display it for the published npm artifact; the rationale remains documented here and in the package.
+If you're vetting `llm-cli-gateway` through [Socket](https://socket.dev/npm/package/llm-cli-gateway) or a similar supply-chain scanner, you'll see behavioural alerts and some dependency-ownership alerts. They are accurate descriptions of what the package does and what it depends on. The reviewed `shellAccess` and `shrinkwrap` entries are configured in `socket.yml` for repository/PR policy surfaces, but Socket's public package page may still display them for the published npm artifact; the rationale remains documented here and in the package.
+
+The currently flagged surfaces are not new in 2.6.x: the 2.3.0, 2.4.0, 2.5.0, and 2.6.3 npm tarballs all include `npm-shrinkwrap.json`, and all include the same `dist/executor.js` child-process spawn surface used to run provider CLIs. The `socket.yml` policy for 2.4.0, 2.5.0, 2.6.0, and 2.6.3 is materially the same for `shellAccess`; this README now adds the missing shrinkwrap disclosure as well.
 
-| Alert                            | Where                                                                                                                                                                                            | Why it's bounded                                                                                                                                                                                                                                                                                                                                             |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Network access**               | `src/http-transport.ts` opens an HTTP MCP transport when started via `npm run start:http`. `src/endpoint-exposure.ts` issues a HEAD probe to verify configured public/tunnel URLs. Socket also flagged `dist/upstream-contracts.js` in v1.17.2 from descriptive text, not a network call. | The transport binds to `127.0.0.1` by default and requires `LLM_GATEWAY_AUTH_TOKEN` to be set. The default stdio MCP entry point (`npm start`) opens no sockets. `src/upstream-contracts.ts` stores provider CLI metadata and imports no HTTP client APIs.                                                                                                  |
-| **Shell access**                 | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                    | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `agy`, `grok`, `vibe`).                                                                                                         |
-| **Uses eval**                    | None in our source. Transitive: `@modelcontextprotocol/sdk` → `ajv@8` uses `new Function(...)` in `ajv/dist/compile/index.js` to compile JSON Schema validators.                                 | This is ajv's standard codegen path. Only known schemas (defined in our source and the MCP SDK) flow into it; no caller-supplied data ever reaches the compiled function body.                                                                                                                                                                               |
-| **SQLite adapter isolation**     | Persistence uses Node's built-in `node:sqlite` module (no native binding, no install scripts) through a single adapter, `src/sqlite-driver.ts`.                                                  | `node:sqlite` is touched by exactly one production module (the adapter); every other module talks to SQLite through its typed surface. We never call any `db.pragma()` helper (it does not exist on `node:sqlite`); SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements. `npm run security:audit` fails the release if production code references `node:sqlite` outside the adapter or reintroduces a `.pragma()` call.                                                            |
-| **Dependency ownership**         | A handful of small transitive packages (e.g. `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics.                                  | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. As of 2.0.0 the prod graph carries no native module (`better-sqlite3` moved to devDependencies; `node:sqlite` is built into Node), eliminating the entire `prebuild-install`/`tar-fs`/`tar-stream` install-time chain. Our earlier direct dependency on `toml@3.0.0` was replaced with `smol-toml`.        |
+| Alert                        | Where                                                                                                                                                                                                                                                                                     | Why it's bounded                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Network access**           | `src/http-transport.ts` opens an HTTP MCP transport when started via `npm run start:http`. `src/endpoint-exposure.ts` issues a HEAD probe to verify configured public/tunnel URLs. Socket also flagged `dist/upstream-contracts.js` in v1.17.2 from descriptive text, not a network call. | The transport binds to `127.0.0.1` by default and requires `LLM_GATEWAY_AUTH_TOKEN` to be set. The default stdio MCP entry point (`npm start`) opens no sockets. `src/upstream-contracts.ts` stores provider CLI metadata and imports no HTTP client APIs.                                                                                                                                                                                                                             |
+| **Shell access**             | `src/executor.ts` uses `child_process.spawn(cmd, args, …)` to invoke the underlying LLM CLIs.                                                                                                                                                                                             | `spawn` is called with an argument array and **never** `shell: true`, so there is no shell interpolation path for caller input. The command name is restricted to an allow-list of known CLI binaries (`claude`, `codex`, `agy`, `grok`, `vibe`).                                                                                                                                                                                                                                      |
+| **Published shrinkwrap**     | The npm artifact includes `npm-shrinkwrap.json`; `package.json#files` includes it and `scripts/make-prod-shrinkwrap.mjs` generates it from `package-lock.json`.                                                                                                                           | This is a CLI/application package. npm documents the shrinkwrap use case for applications, daemons, and command-line tools published through the registry. Our shrinkwrap is a prod-only projection, not a committed full dev lockfile: `scripts/release-security-audit.sh` verifies parity with the audited lockfile, and `scripts/verify-registry-install.sh` proves fresh registry consumers receive no `better-sqlite3`/`prebuild-install`/`tar-fs`/`tar-stream` production chain. |
+| **Uses eval**                | None in our source. Transitive: `@modelcontextprotocol/sdk` → `ajv@8` uses `new Function(...)` in `ajv/dist/compile/index.js` to compile JSON Schema validators.                                                                                                                          | This is ajv's standard codegen path. Only known schemas (defined in our source and the MCP SDK) flow into it; no caller-supplied data ever reaches the compiled function body.                                                                                                                                                                                                                                                                                                         |
+| **SQLite adapter isolation** | Persistence uses Node's built-in `node:sqlite` module (no native binding, no install scripts) through a single adapter, `src/sqlite-driver.ts`.                                                                                                                                           | `node:sqlite` is touched by exactly one production module (the adapter); every other module talks to SQLite through its typed surface. We never call any `db.pragma()` helper (it does not exist on `node:sqlite`); SQLite setup uses fixed literal `db.exec("PRAGMA ...")` statements. `npm run security:audit` fails the release if production code references `node:sqlite` outside the adapter or reintroduces a `.pragma()` call.                                                 |
+| **Dependency ownership**     | A handful of small transitive packages (e.g. `media-typer` via `@modelcontextprotocol/sdk`) trip Socket's "unstable ownership" or "obfuscated code" heuristics.                                                                                                                           | These are pinned, well-known micro-deps in the Node ecosystem with no known issues. We pin direct override versions of `content-type` and `type-is` in `package.json#overrides`. As of 2.0.0 the prod graph carries no native module (`better-sqlite3` moved to devDependencies; `node:sqlite` is built into Node), eliminating the entire `prebuild-install`/`tar-fs`/`tar-stream` install-time chain. Our earlier direct dependency on `toml@3.0.0` was replaced with `smol-toml`.   |
 
 See [`socket.yml`](./socket.yml) for the same context in machine-readable form.
 

package/dist/acp/client.d.ts

@@ -0,0 +1,78 @@
+import { AcpError } from "./errors.js";
+import type { JsonRpcStdioTransport, JsonRpcId } from "./json-rpc-stdio.js";
+import { type ContentBlock, type InitializeResponse, type ReadTextFileRequest, type ReadTextFileResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionLoadResponse, type SessionNewResponse, type SessionPromptResponse, type SessionUpdateNotification, type WriteTextFileRequest, type WriteTextFileResponse } from "./types.js";
+import type { Logger } from "../logger.js";
+import type { CliType } from "../session-manager.js";
+export declare const DEFAULT_ACP_PROTOCOL_VERSION = 1;
+export interface HostServices {
+    readTextFile?(request: ReadTextFileRequest, context: HostCallbackContext): Promise<ReadTextFileResponse>;
+    writeTextFile?(request: WriteTextFileRequest, context: HostCallbackContext): Promise<WriteTextFileResponse>;
+    requestPermission?(request: RequestPermissionRequest, context: HostCallbackContext): Promise<RequestPermissionResponse>;
+}
+export interface HostCallbackContext {
+    readonly provider: CliType;
+    readonly method: string;
+}
+export interface AcpClientCallbacks {
+    readonly onSessionUpdate?: (update: SessionUpdateNotification) => void;
+    readonly onProcessExit?: (error: AcpError) => void;
+}
+export interface AcpClientOptions {
+    readonly transport: JsonRpcStdioTransport;
+    readonly provider: CliType;
+    readonly hostServices: HostServices;
+    readonly callbacks?: AcpClientCallbacks;
+    readonly logger?: Logger;
+    readonly protocolVersion?: number;
+    readonly timeouts?: AcpClientTimeouts;
+}
+export interface AcpClientTimeouts {
+    readonly initializeMs?: number;
+    readonly sessionNewMs?: number;
+    readonly sessionLoadMs?: number;
+    readonly promptMs?: number;
+}
+export interface InitializeOptions {
+    readonly readTextFile?: boolean;
+    readonly writeTextFile?: boolean;
+    readonly terminal?: boolean;
+}
+export interface NewSessionParams {
+    readonly cwd: string;
+    readonly mcpServers?: ReadonlyArray<Record<string, unknown>>;
+}
+export interface LoadSessionParams extends NewSessionParams {
+    readonly sessionId: string;
+}
+export interface PromptParams {
+    readonly sessionId: string;
+    readonly prompt: ReadonlyArray<ContentBlock>;
+}
+export declare class AcpClient {
+    private readonly transport;
+    private readonly provider;
+    private readonly hostServices;
+    private readonly callbacks?;
+    private readonly logger;
+    private readonly protocolVersion;
+    private readonly timeouts;
+    private initialized;
+    private initializeResult;
+    constructor(options: AcpClientOptions);
+    get isInitialized(): boolean;
+    get agentInfo(): InitializeResponse | null;
+    initialize(options?: InitializeOptions): Promise<InitializeResponse>;
+    newSession(params: NewSessionParams): Promise<SessionNewResponse>;
+    loadSession(params: LoadSessionParams): Promise<SessionLoadResponse>;
+    prompt(params: PromptParams): Promise<SessionPromptResponse>;
+    cancel(sessionId: string): void;
+    private send;
+    private normalizeError;
+    private assertInitialized;
+    handleNotification(method: string, params: unknown): void;
+    private handleSessionUpdate;
+    handleRequest(id: JsonRpcId, method: string, params: unknown): void;
+    private dispatchRequest;
+    private requireHandler;
+    notifyProcessExit(error: AcpError): void;
+}

package/dist/acp/client.js

@@ -0,0 +1,201 @@
+import { AcpProtocolError, isAcpError } from "./errors.js";
+import { parseInitializeResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionUpdateNotification, parseWriteTextFileRequest, } from "./types.js";
+import { noopLogger } from "../logger.js";
+export const DEFAULT_ACP_PROTOCOL_VERSION = 1;
+export class AcpClient {
+    transport;
+    provider;
+    hostServices;
+    callbacks;
+    logger;
+    protocolVersion;
+    timeouts;
+    initialized = false;
+    initializeResult = null;
+    constructor(options) {
+        this.transport = options.transport;
+        this.provider = options.provider;
+        this.hostServices = options.hostServices;
+        this.callbacks = options.callbacks;
+        this.logger = options.logger ?? noopLogger;
+        this.protocolVersion = options.protocolVersion ?? DEFAULT_ACP_PROTOCOL_VERSION;
+        this.timeouts = options.timeouts ?? {};
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    get agentInfo() {
+        return this.initializeResult;
+    }
+    async initialize(options = {}) {
+        if (this.initialized && this.initializeResult) {
+            return this.initializeResult;
+        }
+        const params = {
+            protocolVersion: this.protocolVersion,
+            clientCapabilities: {
+                fs: {
+                    readTextFile: options.readTextFile ?? false,
+                    writeTextFile: options.writeTextFile ?? false,
+                },
+                terminal: options.terminal ?? false,
+            },
+        };
+        const raw = await this.send("initialize", params, this.timeouts.initializeMs);
+        const result = parseInitializeResponse(raw, this.provider);
+        this.initialized = true;
+        this.initializeResult = result;
+        return result;
+    }
+    async newSession(params) {
+        this.assertInitialized("session/new");
+        const raw = await this.send("session/new", { cwd: params.cwd, mcpServers: params.mcpServers ?? [] }, this.timeouts.sessionNewMs);
+        return parseSessionNewResponse(raw, this.provider);
+    }
+    async loadSession(params) {
+        this.assertInitialized("session/load");
+        const raw = await this.send("session/load", {
+            sessionId: params.sessionId,
+            cwd: params.cwd,
+            mcpServers: params.mcpServers ?? [],
+        }, this.timeouts.sessionLoadMs);
+        return parseSessionLoadResponse(raw, this.provider);
+    }
+    async prompt(params) {
+        this.assertInitialized("session/prompt");
+        const raw = await this.send("session/prompt", { sessionId: params.sessionId, prompt: params.prompt }, this.timeouts.promptMs);
+        return parseSessionPromptResponse(raw, this.provider);
+    }
+    cancel(sessionId) {
+        this.transport.notify("session/cancel", { sessionId });
+    }
+    async send(method, params, timeoutMs) {
+        try {
+            return await this.transport.request(method, params, timeoutMs);
+        }
+        catch (err) {
+            throw this.normalizeError(method, err);
+        }
+    }
+    normalizeError(method, err) {
+        if (isAcpError(err)) {
+            return err;
+        }
+        return new AcpProtocolError(`ACP request ${method} failed unexpectedly.`, {
+            provider: this.provider,
+            debug: { method, errorClass: err instanceof Error ? err.name : "unknown" },
+        });
+    }
+    assertInitialized(method) {
+        if (!this.initialized) {
+            throw new AcpProtocolError(`ACP ${method} requires initialize to complete first.`, {
+                provider: this.provider,
+                debug: { method, reason: "not_initialized" },
+            });
+        }
+    }
+    handleNotification(method, params) {
+        if (method === "session/update") {
+            this.handleSessionUpdate(params);
+            return;
+        }
+        this.logger.debug("acp.client.unknown_notification", {
+            provider: this.provider,
+            method,
+        });
+    }
+    handleSessionUpdate(params) {
+        let parsed;
+        try {
+            parsed = parseSessionUpdateNotification(params, this.provider);
+        }
+        catch (err) {
+            this.logger.error("acp.client.session_update.parse_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+            return;
+        }
+        try {
+            this.callbacks?.onSessionUpdate?.(parsed);
+        }
+        catch (err) {
+            this.logger.error("acp.client.session_update.handler_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    handleRequest(id, method, params) {
+        void this.dispatchRequest(id, method, params);
+    }
+    async dispatchRequest(id, method, params) {
+        const context = { provider: this.provider, method };
+        try {
+            switch (method) {
+                case "fs/read_text_file": {
+                    const request = parseReadTextFileRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.readTextFile, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                case "fs/write_text_file": {
+                    const request = parseWriteTextFileRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.writeTextFile, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                case "session/request_permission": {
+                    const request = parseRequestPermissionRequest(params, this.provider);
+                    const result = await this.requireHandler(this.hostServices.requestPermission, method)(request, context);
+                    this.transport.respond(id, result);
+                    return;
+                }
+                default: {
+                    this.logger.debug("acp.client.unknown_host_request", {
+                        provider: this.provider,
+                        method,
+                    });
+                    this.transport.respondError(id, {
+                        code: -32601,
+                        message: "Method not found",
+                    });
+                    return;
+                }
+            }
+        }
+        catch (err) {
+            const acpError = isAcpError(err) ? err : this.normalizeError(method, err);
+            this.logger.error("acp.client.host_request.failed", {
+                provider: this.provider,
+                method,
+                errorClass: acpError.name,
+                kind: acpError.kind,
+            });
+            this.transport.respondError(id, {
+                code: -32000,
+                message: acpError.userMessage,
+            });
+        }
+    }
+    requireHandler(handler, method) {
+        if (!handler) {
+            throw new AcpProtocolError(`Host does not support ACP ${method}.`, {
+                provider: this.provider,
+                debug: { method, reason: "unsupported_host_method" },
+            });
+        }
+        return handler.bind(this.hostServices);
+    }
+    notifyProcessExit(error) {
+        try {
+            this.callbacks?.onProcessExit?.(error);
+        }
+        catch (err) {
+            this.logger.error("acp.client.process_exit.handler_error", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+}

package/dist/acp/errors.d.ts

@@ -0,0 +1,63 @@
+import type { CliType } from "../session-manager.js";
+export type AcpErrorKind = "acp_disabled" | "provider_acp_disabled" | "provider_acp_unsupported" | "provider_runtime_disabled" | "provider_unavailable" | "protocol" | "timeout" | "permission_denied" | "process_exit";
+export declare function redactAcpMessage(input: string): string;
+export declare function redactAcpDebug(value: unknown): unknown;
+export declare function redactAcpCause(cause: unknown): unknown;
+export interface AcpErrorDebug {
+    readonly [key: string]: unknown;
+}
+export declare class AcpError extends Error {
+    readonly kind: AcpErrorKind;
+    readonly provider?: CliType;
+    readonly debug: AcpErrorDebug;
+    constructor(kind: AcpErrorKind, userMessage: string, options?: {
+        provider?: CliType;
+        debug?: AcpErrorDebug;
+        cause?: unknown;
+    });
+    get userMessage(): string;
+}
+export declare class AcpDisabledError extends AcpError {
+    constructor(debug?: AcpErrorDebug);
+}
+export declare class ProviderAcpDisabledError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderAcpUnsupportedError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderRuntimeDisabledError extends AcpError {
+    constructor(provider: CliType, debug?: AcpErrorDebug);
+}
+export declare class ProviderUnavailableError extends AcpError {
+    constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
+}
+export declare class AcpProtocolError extends AcpError {
+    readonly code?: number;
+    constructor(userMessage: string, options?: {
+        provider?: CliType;
+        code?: number;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare class AcpTimeoutError extends AcpError {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number, options?: {
+        provider?: CliType;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare class AcpPermissionDeniedError extends AcpError {
+    constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
+}
+export declare class AcpProcessExitError extends AcpError {
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    constructor(provider: CliType, options?: {
+        exitCode?: number | null;
+        signal?: string | null;
+        debug?: AcpErrorDebug;
+    });
+}
+export declare function isAcpError(value: unknown): value is AcpError;