llm-cli-gateway 2.13.2 → 2.14.0-rc.1

package/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [2.14.0-rc.1] - 2026-07-03: full-featured provider integration + security-review hardening
+
+Release candidate. Every non-Cursor provider (Claude, Codex, Gemini, Grok,
+Mistral, Devin) becomes a first-class, provider-definition-driven integration,
+and a security review of the change set is folded in. Cursor stays working via
+the shared generation and is maintenance-only.
+
+### Added
+
+- **Provider definitions as the single source of truth** (`src/provider-definitions.ts`):
+  one `ProviderDefinition` per CLI type drives request schemas, resources,
+  discovery, and capabilities, with compile-time exhaustiveness assertions and a
+  `scripts/provider-surfaces-check.mjs` ratchet wired into `npm run check`.
+- **Runtime provider capability discovery with an on-disk cache**: an injectable
+  probe runner (no shell interpolation of caller input), a cache keyed on
+  discovery checksums with a shape-driven secret scrubber and Zod-validated
+  reads, and a TTL that bounds staleness so an upgraded or moved provider CLI is
+  re-discovered instead of served stale.
+- **Registry-generated `models://` and `sessions://` resources** for every
+  provider (Devin and Cursor now first-class), plus **live model discovery**
+  wired into `models://<provider>` and `list_models` via a memoized resolver
+  with a fire-and-forget startup warm (reads never block on a spawn).
+- **Complete CLI request-field coverage** across providers, guarded by
+  upstream-contract and coverage-closure tests; interactive/admin-only flags are
+  represented as typed capability facts rather than silently dropped.
+- **Discovery-driven native ACP surface**: Grok, Mistral, and Devin route
+  natively over ACP when enabled (no masquerade), with capability-gated session
+  methods and state-mutating session ops gated behind
+  `acp.allow_mutating_session_ops`.
+- **Provider admin tools**: `provider_admin_list` / `provider_admin_run`
+  (read-only) and `provider_admin_mutate` (gated). Availability is
+  discovery-driven; mutating ops require `[admin] allow_mutating_cli_admin_ops`
+  and, for remote callers, `LLM_GATEWAY_CLI_ADMIN=1` plus the `cli:admin` OAuth
+  scope, routed through the approval manager with a fail-closed pre-spawn audit.
+- **Postgres job store** (`PostgresJobStore`): a durable async-job and
+  validation-run/receipt backend over the `pg` pool, driven through a dedicated
+  worker thread (`postgres-job-store-worker.ts`). Selectable via
+  `persistence.backend = "postgres"`; the ephemeral memory backend deliberately
+  does not implement the validation-run surface.
+- **Search-engine discoverability for the docs site**: Google Search Console
+  and Bing IndexNow submission (`npm run search:*`), plus `sitemap.xml`,
+  `robots.txt`, and `llms.txt`, alongside a marketing-site refresh.
+
+### Changed
+
+- **Unified provider output/event normalization**: a real Grok JSON parser, and
+  `stopReason`/error signals threaded across the CLI parsers and the ACP event
+  normalizer. The provider-minted session id and terminal stop reason are
+  preserved through the async job and flight recorder so a deferred job resumes
+  with the real provider session id.
+- **`provider_tool_capabilities`** now reports ACP `runtimeEnabled` from the
+  resolved config (previously hardcoded), with entrypoint/version/mediation
+  derived from the registry.
+- Docs: README provider-capability table, per-provider skills refreshed to the
+  installed CLI versions, ACP documented as sync-only for now, and the
+  `provider-acp://` resource registered on the MCP server.
+
+### Fixed
+
+- Codex and Gemini clean exits that actually carried a failed terminal event
+  now surface a warning instead of being reported as a silent empty success;
+  the ACP transport likewise flags a refusal/cancelled/truncated turn.
+- Codex surfaces the real `turn.failed` reason on a non-zero exit instead of a
+  partial agent message.
+- json-mode output parsers tolerate a stray banner line around the JSON object
+  (telemetry is no longer all-or-nothing), and the Gemini stream replaces rather
+  than doubles a consolidated non-delta final message.
+- Implausible `agy models` label lines are filtered instead of surfacing as
+  bogus models in `models://gemini`.
+
+### Security
+
+- **Remote host-path confinement.** Remote HTTP/OAuth callers can no longer hand
+  a provider CLI an arbitrary host path to read, write, or load code from. The
+  advanced path/plugin fields are rejected for remote callers (local stdio is
+  unaffected): `systemPromptFile`/`appendSystemPromptFile`/`settings`/
+  `pluginDir`/`pluginUrl`/`debugFile` (Claude), string `outputSchema`/`images`/
+  `outputLastMessage` (Codex), `promptFile`/`config`/`agentConfig`/string
+  `exportSession` (Devin), and `promptFile`/`leaderSocket`/`rules`/`agent`
+  (Grok). `workingDir`/`addDir`/`includeDirs` remain workspace-confined.
+- **Read-only provider-admin ops** now require the same remote `cli:admin` gate
+  as the mutating path, so a remote caller cannot enumerate or trigger
+  host-global provider-CLI spawns unprivileged.
+- **ACP permission bridge** never turns a single approval into a standing
+  `allow_always` grant (it selects a one-time allow, else denies).
+- **ACP subprocess reaping**: a graceful termination signal escalates to
+  SIGKILL after a grace window so a provider CLI that ignores SIGTERM is not
+  leaked as a zombie.
+- Job results scrub the provider session id from returned streams for remote
+  callers; ACP error redaction covers Google/GitHub/Slack token shapes;
+  `session_info_update` is handled as a forward-compatible unknown ACP variant.
+- CI/release: the Cloudflare Pages token is fetched from Azure Key Vault via
+  GitHub OIDC federation (no stored secret); the release tooling supports
+  prerelease cuts (a prerelease publishes under a side npm dist-tag, never
+  `latest`); typos and gitleaks allowlists cover a deliberate identifier and
+  secret-fixture test files.
+
 ## [2.13.2] - 2026-07-01: remote HTTP + OAuth connector UX and hardening
 
 ### Added

package/README.md

@@ -9,9 +9,11 @@
 > _"Without consultation, plans are frustrated, but with many counselors they succeed."_
 > — Proverbs 15:22 (LSB)
 
-A Model Context Protocol (MCP) gateway for running Claude Code, Codex, Gemini, Grok, Mistral (Vibe), Devin, and Cursor Agent CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
+**Cross-model review without rebuilding your agent stack.**
 
-**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across registered provider CLIs.
+`llm-cli-gateway` gives any MCP client one local-first gateway for Claude Code, Codex, Gemini/Antigravity, Grok Build, Mistral Vibe, Cognition Devin, Cursor Agent, and configured HTTP API providers, while preserving native CLI sessions, local credentials, durable async jobs, validation receipts, and review workflows.
+
+**Why developers try it:** any connected client can ask other models for a second opinion, run implementation/review loops, collect durable job results, and route API-token LLMs without turning local coding agents into a generic chat proxy.
 
 **Current signals:** CI and security workflows pass on `main`, OpenSSF Scorecard is published, OpenSSF Best Practices is passing, releases use Sigstore signing, and the package is MIT licensed.
 
@@ -38,7 +40,7 @@ Or use directly with `npx` from an MCP client:
 
 `llm-cli-gateway` is a single-user MCP gateway for cross-LLM validation and multi-agent coding workflows. It is more than a thin CLI wrapper:
 
-- Runs registered provider CLIs through consistent sync and async MCP tools.
+- Runs registered provider CLIs and configured HTTP API providers through consistent sync and async MCP tools.
 - Persists long-running jobs, supports restart-safe result collection, deduplication, cancellation, and sync-to-async deferral.
 - Tracks sessions, real CLI resume paths, structured response metadata, and cache telemetry.
 - Supports cache-aware `promptParts`, including explicit Claude `cache_control` when opted in.
@@ -51,7 +53,7 @@ Or use directly with `npx` from an MCP client:
 
 The repo ships agent-ready workflow skills under [`.agents/skills`](.agents/skills) for async orchestration, session continuity, multi-LLM review, implement-review-fix loops, and secure approval-gated dispatch. Six caller-facing skills are bundled in the published npm package: `async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, and `public-demo-session`. Machine-readable DAG-TOML plans live under [`docs/plans`](docs/plans) and [`setup/install-plan.dag.toml`](setup/install-plan.dag.toml) for workflows that need deterministic sequencing and verification gates.
 
-The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI: Claude, Codex, Gemini, Grok, and Mistral Vibe. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
+The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI and API-provider family: Claude, Codex, Gemini/Antigravity, Grok, Mistral Vibe, Devin, Cursor Agent, OpenAI-compatible endpoints, Anthropic Messages, and xAI Responses. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks or token-env checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
 
 ## Trust & Supply Chain
 
@@ -61,7 +63,7 @@ The next documentation focus is provider-specific skill and DAG-TOML pairs for e
 - CI runs build, lint, format, tests, package checks, and npm audit.
 - 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.
+- npm releases use a generated prod-only shrinkwrap and release security audit; the publish token is fetched at runtime from Azure Key Vault through GitHub OIDC to Entra.
 - 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.
 
@@ -190,15 +192,15 @@ Every `*_request` and `*_request_async` tool except `devin_request` / `devin_req
 
 Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for all providers except Devin and Cursor, which have no `promptParts` surface; explicit levers are provider-specific):
 
-| CLI     | Prefix discipline | Explicit lever(s) |
-| ------- | ----------------- | ----------------- |
+| CLI     | Prefix discipline | Explicit lever(s)                                                                                                                      |
+| ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | claude  | yes               | `promptParts.cacheControl` + `outputFormat: "stream-json"` (Anthropic `cache_control` breakpoints on stable blocks; `ttl="1h"` forced) |
-| codex   | yes               | none (OpenAI implicit) |
-| gemini  | yes               | none (implicit server-side) |
-| grok    | yes               | `compactionMode` / `compactionDetail` (context compaction: `summary|transcript|segments`; `segments` writes per-segment markdown) |
-| mistral | yes               | none (implicit) |
-| devin   | no                | plain `prompt` only |
-| cursor  | no                | plain `prompt` only |
+| codex   | yes               | none (OpenAI implicit)                                                                                                                 |
+| gemini  | yes               | none (implicit server-side)                                                                                                            |
+| grok    | yes               | `compactionMode` / `compactionDetail` (context compaction: `summary                                                                    | transcript | segments`; `segments` writes per-segment markdown) |
+| mistral | yes               | none (implicit)                                                                                                                        |
+| devin   | no                | plain `prompt` only                                                                                                                    |
+| cursor  | no                | plain `prompt` only                                                                                                                    |
 
 **Claude example (explicit cacheControl)**
 
@@ -208,10 +210,10 @@ claude_request({
     system: "You are a helpful code reviewer.",
     context: "<long stable file dump>",
     task: "Review the diff.",
-    cacheControl: { system: true, context: true }  // task is never marked
+    cacheControl: { system: true, context: true }, // task is never marked
   },
-  outputFormat: "stream-json"
-})
+  outputFormat: "stream-json",
+});
 ```
 
 Gateway emits the `stream-json` stdin path with `cache_control: {type:"ephemeral", ttl:"1h"}` on marked blocks only.
@@ -222,8 +224,8 @@ Gateway emits the `stream-json` stdin path with `cache_control: {type:"ephemeral
 grok_request({
   promptParts: { system: "...", context: "...", task: "..." },
   compactionMode: "segments",
-  compactionDetail: "balanced"
-})
+  compactionDetail: "balanced",
+});
 ```
 
 Emits `--compaction-mode segments --compaction-detail balanced`.
@@ -249,6 +251,26 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 - **Type Safety**: Strict TypeScript with comprehensive error handling
 - **Supply-chain hardening**: a dedicated `.github/workflows/security.yml` runs actionlint, zizmor, shellcheck, typos, osv-scanner, gitleaks, and lychee on every push and PR (see `SECURITY.md` for the threat model)
 
+## Provider capability surface
+
+Every provider is reachable through the same request, session, job, and validation machinery, but the underlying CLIs differ in what they natively expose. The table records what actually shipped per provider; discover the live surface at runtime with `provider_tool_capabilities`, `list_models`, and the `provider-acp://<provider>` / `provider-tools://<provider>` resources.
+
+| Provider | CLI request tools | Native ACP | Live model discovery | Admin surface |
+| --- | --- | --- | --- | --- |
+| Claude Code (`claude`) | `claude_request` / `_async` | None (CLI-first; no ACP entrypoint at claude 2.1.198) | model aliases, reasoning-effort levels, fallback model | read-only via `provider_admin_list` / `provider_admin_run` |
+| OpenAI Codex (`codex`) | `codex_request` / `_async`, `codex_fork_session` | None (codex-cli 0.142.4 advertises mcp-server / app-server transports, not native ACP) | `codex debug models` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Gemini / Antigravity (`gemini`, `agy`) | `gemini_request` / `_async` | None (agy 1.0.14 exposes no ACP entrypoint; legacy Gemini CLI ACP evidence does not transfer) | `agy models` | read-only via `provider_admin_list` / `provider_admin_run` |
+| xAI Grok (`grok`) | `grok_request` (sync `transport: "acp"`) / `_async` | Native via `grok agent stdio` | `grok models` + `~/.grok/config.toml` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Mistral Vibe (`mistral`) | `mistral_request` (sync `transport: "acp"`) / `_async` | Native via `vibe-acp` | Vibe config plus the `VIBE_ACTIVE_MODEL` active model and agent profiles | read-only via `provider_admin_list` / `provider_admin_run` |
+| Cognition Devin (`devin`) | `devin_request` (sync `transport: "acp"`, `agentType: summarizer\|review`) / `_async` | Native via `devin acp` | `--model` / `DEVIN_MODEL` | read-only via `provider_admin_list` / `provider_admin_run` |
+| Cursor Agent (`cursor`) | `cursor_request` (sync `transport: "acp"`) / `_async` | Native via `cursor-agent acp` (companion-owned) | model aliases | read-only via `provider_admin_list` / `provider_admin_run` |
+
+- **Native ACP** is reported honestly. `grok`, `mistral`, `devin`, and `cursor` expose a native ACP entrypoint, so `provider-acp://<provider>` carries the negotiated `initialize` capability set and the derived session-method availability, and the sync `*_request` accepts `transport: "acp"` (fails closed unless `[acp]` and the provider's `runtime_enabled` gate are set). ACP routing is sync-only: the `*_request_async` variants always run the CLI transport and do not accept `transport: "acp"` (nor Devin's `agentType`); async ACP parity is a later phase. `claude`, `codex`, and `gemini` have no native ACP entrypoint at their target CLI versions; their `provider-acp://` records report `native: false` with no methods and no adapter-as-native masquerade, and they expose no `transport: "acp"` selector.
+- **Resources** are generated from the provider registry for every CLI provider: `models://<provider>`, `sessions://<provider>`, `provider-acp://<provider>`, `provider-tools://<provider>`, and `provider-subcommands://<provider>`.
+- **Model discovery** is live and account-aware: the discovery listed above reaches `models://<provider>` and `list_models`, degrading to static registry facts when a live probe is unavailable (a resource read never spawns a CLI).
+- **Admin surfaces** are discovery-driven and output-redacted. `provider_admin_list` and `provider_admin_run` are read-only for every provider. State-mutating admin operations are exposed only through `provider_admin_mutate`, gated behind `[admin] allow_mutating_cli_admin_ops`, the remote `cli:admin` scope, an approval gate, and an audit record. Mutating ACP session operations are likewise gated behind `[acp] allow_mutating_session_ops`.
+- **Validation** commands work across every provider: `validate_with_models`, `second_opinion`, `compare_answers`, `red_team_review`, `consensus_check`, `ask_model`, and `synthesize_validation`, with durable signed receipts via `validation_receipt` and the `validation-receipt://{validationId}` resource.
+
 ## Prerequisites
 
 **Node.js >= 24.4.0** is required (`engines.node` in `package.json`). The gateway uses Node's built-in `node:sqlite` module for persistence — there is no native binding to compile and no install scripts run. The 24.4 floor is where `allowBareNamedParameters` defaults to `true`, which the persistence layer relies on.
@@ -389,7 +411,7 @@ The personal-appliance surface exposes simplified validation tools for non-devel
 - `synthesize_validation`: run an explicit judge model after provider results have been collected.
 - `list_available_models`: list the models each provider CLI exposes through the simplified surface.
 - `job_status` and `job_result`: poll and collect validation job outputs.
-- `validation_receipt`: retrieve the immutable receipt of a terminal cross-LLM validation run by `validationId` (returns `minted | pending | expired_unminted | not_found`, own-or-not-found). `format: "markdown"` renders a human-readable report; `includeRawResponses` inlines provider answer text. Registered only under the durable persistence gate (`backend = "sqlite"` with an attached validation-run store).
+- `validation_receipt`: retrieve the immutable receipt of a terminal cross-LLM validation run by `validationId` (returns `minted | pending | expired_unminted | not_found`, own-or-not-found). `format: "markdown"` renders a human-readable report; `includeRawResponses` inlines provider answer text. Registered only when the attached job store provides the durable validation-run store capability (`sqlite` and `postgres`).
 
 The same receipt is also exposed as the `validation-receipt://{validationId}` MCP resource (same durable gate and own-or-not-found owner scoping).
 
@@ -574,6 +596,7 @@ Execute a Grok CLI (xAI) request with session support.
 
 - `prompt` (string, optional*): The prompt to send (1-100,000 chars). *Exactly one of `prompt` or `promptParts` is required (mutually exclusive)
 - `model` (string, optional): Model name or alias (e.g. `grok-build`, `latest`)
+- `transport` (string, optional): `"cli"` (default) runs the Grok CLI; `"acp"` routes through Grok's native `grok agent stdio` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `grok_request_async` always runs the CLI transport and does not accept `transport`
 - `outputFormat` (string, optional): `"plain"` (default), `"json"`, or `"streaming-json"`
 - `sessionId` (string, optional): Session ID to resume (`--resume <id>`)
 - `resumeLatest` (boolean, optional): Resume the most recent session in the current cwd (`--continue`)
@@ -647,7 +670,7 @@ The job-store backend is configured by `~/.llm-cli-gateway/config.toml` (overrid
 [persistence]
 backend = "sqlite"                          # "sqlite" | "memory" | "postgres" | "none"
 path = "~/.llm-cli-gateway/logs.db"         # for sqlite
-# dsn = "postgresql://user:pw@host/db"      # for postgres (interface only — impl not yet shipped)
+# dsn = "postgresql://user:pw@host/db"      # for postgres
 retentionDays = 30
 dedupWindowMs = 3600000
 acknowledgeEphemeral = false                # required to enable async tools with memory backend
@@ -656,8 +679,8 @@ acknowledgeEphemeral = false                # required to enable async tools wit
 Backends:
 
 - **`sqlite`** (default) — durable, file-backed. Safe for single-instance deployments.
+- **`postgres`** — durable PostgreSQL-backed async job, dedup, orphan recovery, HTTP job, and validation receipt storage. Use this for multi-instance or service deployments. Requires the optional peer dependency `pg` to be installed alongside the gateway.
 - **`memory`** — in-process Map. Lost on gateway exit. Requires `acknowledgeEphemeral = true` to be loaded. Suitable for tests and ephemeral CI gateways.
-- **`postgres`** — interface only, implementation not yet shipped. Selecting this backend throws at startup.
 - **`none`** — no store. **`*_request_async`, `llm_job_status`, `llm_job_result`, and `llm_job_cancel` are NOT registered on the gateway.** This is a structural invariant: agents that try to call async tools against a gateway with `backend = "none"` get a clean "tool not found" at connect time instead of silent in-memory loss after the 1-hour TTL. Use `llm_process_health` to inspect the resolved persistence state programmatically.
 
 Legacy environment variables (deprecated; emit a warning at startup):
@@ -922,6 +945,7 @@ consumes       = ["OUT:mcp-reconnected"]
 Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but with Vibe's specific surface:
 
 - `model` (string, optional): Vibe model alias (for example `mistral-medium-3.5` or `latest`). The resolved value is injected via the `VIBE_ACTIVE_MODEL` environment variable; omit it to let the gateway discover Vibe config and avoid stale hardcoded defaults.
+- `transport` (string, optional): `"cli"` (default) runs the Vibe CLI; `"acp"` routes through Vibe's native `vibe-acp` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `mistral_request_async` always runs the CLI transport and does not accept `transport`
 - `permissionMode`: the Vibe `--agent` name — builtins `default | plan | accept-edits | auto-approve`, or any install-gated/custom agent. Emitted as `--agent <name>`. Defaults to `auto-approve` in programmatic mode.
 - `allowedTools` (string[], optional): One `--enabled-tools <tool>` flag per entry (allow-list only).
 - `disallowedTools` (string[], optional): Accepted for parity with the other providers; ignored at the CLI boundary with a logged warning.
@@ -951,7 +975,8 @@ Run a Cognition Devin CLI request synchronously (headless print mode, `devin -p`
 
 - `prompt` (string, optional*): Prompt text for Devin CLI (1-100,000 chars). Required in practice; `promptFile` is additive
 - `model` (string, optional): Model name or alias (e.g. `opus`, `latest`)
-- `transport` (string, optional): `"cli"` (default) runs the Devin CLI; `"acp"` routes through `devin acp` when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise)
+- `transport` (string, optional): `"cli"` (default) runs the Devin CLI; `"acp"` routes through Devin's native `devin acp` transport when `[acp].enabled` and the provider's `runtime_enabled` are set (fails closed otherwise). Sync-only: `devin_request_async` always runs the CLI transport and accepts neither `transport` nor `agentType`
+- `agentType` (string, optional): ACP agent variant for `transport: "acp"` (`devin acp --agent-type`): `"summarizer"` (no tools, text summary) or `"review"` (read-only plus shell code-review); ignored for the CLI transport
 - `permissionMode` (string, optional): Devin CLI permission mode (`--permission-mode`): `auto` (auto-approves read-only tools), `smart` (also auto-runs actions a fast model judges safe), `dangerous` (auto-approves all). Omit to use Devin's headless default
 - `promptFile` (string, optional): Load the initial prompt from a file (`--prompt-file`)
 - `sessionId` (string, optional): Devin session ID to resume (`--resume <id>`). The `gw-*` id minted for a brand-new session is not resumable via `sessionId`; continue with `resumeLatest: true`
@@ -972,7 +997,7 @@ Run a Cursor Agent CLI request synchronously. Defaults to headless print mode (`
 - `model` (string, optional): Model name or alias (for example `gpt-5`, `sonnet-4-thinking`, or `latest`)
 - `mode` (string, optional): Cursor mode, `"plan"` or `"ask"` (`--mode`)
 - `outputFormat` (string, optional): `"text"` (default), `"json"`, or `"stream-json"`
-- `transport` (string, optional): `"cli"` (default) or `"acp"`; ACP fails closed unless enabled in gateway config and rejects unsupported Cursor CLI-only controls instead of dropping them
+- `transport` (string, optional): `"cli"` (default) or `"acp"`; ACP fails closed unless enabled in gateway config and rejects unsupported Cursor CLI-only controls instead of dropping them. Sync-only: `cursor_request_async` always runs the CLI transport and does not accept `transport`
 - `force` (boolean, optional): Emit `--force` for non-interactive operation
 - `autoReview` (boolean, optional): Emit `--auto-review`
 - `sandbox` (string, optional): `"enabled"` or `"disabled"` (`--sandbox`)
@@ -1317,7 +1342,7 @@ The API key value is never emitted on any of these surfaces (only the env var na
 
 ### Security note
 
-The resolved API key is excluded from `payloadJson`, the dedup key, logs, and the flight recorder. However, the **request prompt is persisted in plaintext** in the async job store (the SQLite file at `[persistence].path`, default `~/.llm-cli-gateway/logs.db`) and is not covered by secret redaction. This mirrors the CLI tools, whose prompt is persisted in `argsJson` whenever it is passed as a command argument (a few CLI paths instead stream the prompt over stdin and so do not persist it). Treat the job store as sensitive at rest. See [Security Considerations](#security-considerations).
+The resolved API key is excluded from `payloadJson`, the dedup key, logs, and the flight recorder. However, the **request prompt is persisted in plaintext** in the async job store (SQLite at `[persistence].path`, default `~/.llm-cli-gateway/logs.db`, or Postgres rows under `backend = "postgres"`) and is not covered by secret redaction. This mirrors the CLI tools, whose prompt is persisted in `argsJson` whenever it is passed as a command argument (a few CLI paths instead stream the prompt over stdin and so do not persist it). Treat the job store as sensitive at rest. See [Security Considerations](#security-considerations).
 
 ## Session Management
 
@@ -1384,9 +1409,11 @@ await callTool("session_delete", {
   - **Gemini (Antigravity)** → `default` / prompted, i.e. **no** `--dangerously-skip-permissions` (the `agy` CLI has no accept-edits middle rung, so the safe default is prompted execution; without the opt-in, Gemini cannot auto-approve mutating tools under `mcp_managed`)
 
   Set to `1`/`true` to let the operator opt back in: this permits bypass requests through the approval gate **and** restores each provider's full auto-approve mode under `mcp_managed` (Claude `bypassPermissions`, Grok `--always-approve`, Mistral `--agent auto-approve`, Gemini `--dangerously-skip-permissions`). Sandboxed auto modes (e.g. codex `--sandbox workspace-write`) are unaffected.
+
   ```bash
   LLM_GATEWAY_APPROVAL_ALLOW_BYPASS=1 node dist/index.js
   ```
+
 - `LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER`: Name of an HTTP header carrying the authenticated user identity asserted by a **trusted front door** (any identity-aware reverse proxy / IdP). When set, the gateway adopts that header value as the request's ownership principal — but **only** for requests authenticated with the gateway's own static bearer token (i.e. the trusted upstream proxy), never from an arbitrary remote client. Off by default; IdP-agnostic. Lets a proxy-fronted multi-user deployment carry per-user identity into the gateway.
   ```bash
   LLM_GATEWAY_TRUSTED_PRINCIPAL_HEADER=x-gateway-principal node dist/index.js
@@ -1575,11 +1602,11 @@ The gateway supports concurrent requests across different CLIs. Each request spa
 
 - **Input Validation**: All prompts are validated (min 1 char, max 100k chars)
 - **API-provider keys**: For `[providers.<name>]` HTTP providers, the gateway reads the key from the named environment variable at request time only. The resolved key is excluded from the persisted `payloadJson`, the dedup key, logs, and the flight recorder, and is never surfaced on the discovery/diagnostic surfaces (which report only the env var name and a presence boolean). `base_url` userinfo is redacted on the diagnostic surfaces. See [API providers (HTTP)](#api-providers-http).
-- **Prompt persistence at rest**: Async job rows store the request **prompt in plaintext** (HTTP `payloadJson`, and CLI `argsJson` whenever the prompt is passed as a command argument rather than streamed over stdin); this is not covered by secret redaction. The SQLite job-store file (default `~/.llm-cli-gateway/logs.db`, configurable via `[persistence].path`) is `chmod`ed to `0o600` on non-Windows hosts; treat it as sensitive and scope/rotate it like any prompt log. Set `[persistence].backend = "none"` to disable the async job store entirely (the `*_request_async` / `llm_job_*` tools are then not registered).
+- **Prompt persistence at rest**: Async job rows store the request **prompt in plaintext** (HTTP `payloadJson`, and CLI `argsJson` whenever the prompt is passed as a command argument rather than streamed over stdin); this is not covered by secret redaction. The SQLite job-store file (default `~/.llm-cli-gateway/logs.db`, configurable via `[persistence].path`) is `chmod`ed to `0o600` on non-Windows hosts; the Postgres backend stores the same fields in database rows. Treat either backend as sensitive and scope/rotate it like any prompt log. Set `[persistence].backend = "none"` to disable the async job store entirely (the `*_request_async` / `llm_job_*` tools are then not registered).
 - **Command Execution**: Uses `spawn` with separate arguments (not shell execution)
 - **No Eval**: No dynamic code evaluation in our source (see "Socket alerts" below for the transitive `ajv` codegen case)
 - **Sandboxing**: Consider running in containers for production use
-- **Provenance**: Releases are published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via OIDC trusted publishing from GitHub Actions
+- **npm publish control**: npm releases are gated by the generated prod-only shrinkwrap, release security audit, packed-consumer checks, and a publish token fetched at runtime from Azure Key Vault through GitHub OIDC to Entra
 - **Release signing**: GitHub release installer artifacts are signed with Sigstore keyless signing; verify `SHA256SUMS.sigstore.json` before trusting the checksum file
 
 ### Socket alerts — context for reviewers

package/dist/acp/client.d.ts

@@ -1,6 +1,6 @@
 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 CloseSessionResponse, type ContentBlock, type DeleteSessionResponse, type InitializeResponse, type ListSessionsResponse, type ReadTextFileRequest, type ReadTextFileResponse, type RequestPermissionRequest, type RequestPermissionResponse, type SessionLoadResponse, type SessionNewResponse, type SessionPromptResponse, type SessionResumeResponse, type SessionUpdateNotification, type SetSessionConfigOptionResponse, type SetSessionModeResponse, 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;
@@ -25,6 +25,7 @@ export interface AcpClientOptions {
     readonly logger?: Logger;
     readonly protocolVersion?: number;
     readonly timeouts?: AcpClientTimeouts;
+    readonly allowMutatingSessionOps?: boolean;
 }
 export interface AcpClientTimeouts {
     readonly initializeMs?: number;
@@ -48,6 +49,18 @@ export interface PromptParams {
     readonly sessionId: string;
     readonly prompt: ReadonlyArray<ContentBlock>;
 }
+export interface ResumeSessionParams extends NewSessionParams {
+    readonly sessionId: string;
+}
+export interface SetSessionModeParams {
+    readonly sessionId: string;
+    readonly modeId: string;
+}
+export interface SetSessionConfigOptionParams {
+    readonly sessionId: string;
+    readonly configId: string;
+    readonly value: string;
+}
 export declare class AcpClient {
     private readonly transport;
     private readonly provider;
@@ -56,16 +69,31 @@ export declare class AcpClient {
     private readonly logger;
     private readonly protocolVersion;
     private readonly timeouts;
+    private readonly allowMutatingSessionOps;
     private initialized;
     private initializeResult;
+    private methodAvailability;
+    private static readonly MUTATING_METHODS;
     constructor(options: AcpClientOptions);
     get isInitialized(): boolean;
     get agentInfo(): InitializeResponse | null;
+    get availableMethods(): ReadonlySet<string>;
+    supportsMethod(method: string): boolean;
     initialize(options?: InitializeOptions): Promise<InitializeResponse>;
     newSession(params: NewSessionParams): Promise<SessionNewResponse>;
     loadSession(params: LoadSessionParams): Promise<SessionLoadResponse>;
     prompt(params: PromptParams): Promise<SessionPromptResponse>;
     cancel(sessionId: string): void;
+    resumeSession(params: ResumeSessionParams): Promise<SessionResumeResponse>;
+    listSessions(params?: {
+        cursor?: string;
+    }): Promise<ListSessionsResponse>;
+    closeSession(sessionId: string): Promise<CloseSessionResponse>;
+    deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
+    setSessionMode(params: SetSessionModeParams): Promise<SetSessionModeResponse>;
+    setSessionConfigOption(params: SetSessionConfigOptionParams): Promise<SetSessionConfigOptionResponse>;
+    private augmentSessionMethods;
+    private assertMethodAvailable;
     private send;
     private normalizeError;
     private assertInitialized;

package/dist/acp/client.js

@@ -1,5 +1,5 @@
-import { AcpProtocolError, isAcpError } from "./errors.js";
-import { parseInitializeResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionUpdateNotification, parseWriteTextFileRequest, } from "./types.js";
+import { AcpMethodUnsupportedError, AcpMutatingDisabledError, AcpProtocolError, isAcpError, } from "./errors.js";
+import { deriveAcpMethodAvailability, parseCloseSessionResponse, parseDeleteSessionResponse, parseInitializeResponse, parseListSessionsResponse, parseReadTextFileRequest, parseRequestPermissionRequest, parseSessionLoadResponse, parseSessionNewResponse, parseSessionPromptResponse, parseSessionResumeResponse, parseSessionUpdateNotification, parseSetSessionConfigOptionResponse, parseSetSessionModeResponse, parseWriteTextFileRequest, sessionResponseMethods, } from "./types.js";
 import { noopLogger } from "../logger.js";
 export const DEFAULT_ACP_PROTOCOL_VERSION = 1;
 export class AcpClient {
@@ -10,8 +10,15 @@ export class AcpClient {
     logger;
     protocolVersion;
     timeouts;
+    allowMutatingSessionOps;
     initialized = false;
     initializeResult = null;
+    methodAvailability = new Set();
+    static MUTATING_METHODS = new Set([
+        "session/delete",
+        "session/set_mode",
+        "session/set_config_option",
+    ]);
     constructor(options) {
         this.transport = options.transport;
         this.provider = options.provider;
@@ -20,6 +27,7 @@ export class AcpClient {
         this.logger = options.logger ?? noopLogger;
         this.protocolVersion = options.protocolVersion ?? DEFAULT_ACP_PROTOCOL_VERSION;
         this.timeouts = options.timeouts ?? {};
+        this.allowMutatingSessionOps = options.allowMutatingSessionOps ?? false;
     }
     get isInitialized() {
         return this.initialized;
@@ -27,6 +35,12 @@ export class AcpClient {
     get agentInfo() {
         return this.initializeResult;
     }
+    get availableMethods() {
+        return new Set(this.methodAvailability);
+    }
+    supportsMethod(method) {
+        return this.methodAvailability.has(method);
+    }
     async initialize(options = {}) {
         if (this.initialized && this.initializeResult) {
             return this.initializeResult;
@@ -45,12 +59,15 @@ export class AcpClient {
         const result = parseInitializeResponse(raw, this.provider);
         this.initialized = true;
         this.initializeResult = result;
+        this.methodAvailability = new Set(deriveAcpMethodAvailability(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);
+        const response = parseSessionNewResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
     }
     async loadSession(params) {
         this.assertInitialized("session/load");
@@ -59,7 +76,9 @@ export class AcpClient {
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
         }, this.timeouts.sessionLoadMs);
-        return parseSessionLoadResponse(raw, this.provider);
+        const response = parseSessionLoadResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
     }
     async prompt(params) {
         this.assertInitialized("session/prompt");
@@ -69,6 +88,61 @@ export class AcpClient {
     cancel(sessionId) {
         this.transport.notify("session/cancel", { sessionId });
     }
+    async resumeSession(params) {
+        this.assertMethodAvailable("session/resume");
+        const raw = await this.send("session/resume", { sessionId: params.sessionId, cwd: params.cwd, mcpServers: params.mcpServers ?? [] }, this.timeouts.sessionLoadMs);
+        const response = parseSessionResumeResponse(raw, this.provider);
+        this.augmentSessionMethods(response);
+        return response;
+    }
+    async listSessions(params = {}) {
+        this.assertMethodAvailable("session/list");
+        const raw = await this.send("session/list", { cursor: params.cursor });
+        return parseListSessionsResponse(raw, this.provider);
+    }
+    async closeSession(sessionId) {
+        this.assertMethodAvailable("session/close");
+        const raw = await this.send("session/close", { sessionId });
+        return parseCloseSessionResponse(raw, this.provider);
+    }
+    async deleteSession(sessionId) {
+        this.assertMethodAvailable("session/delete");
+        const raw = await this.send("session/delete", { sessionId });
+        return parseDeleteSessionResponse(raw, this.provider);
+    }
+    async setSessionMode(params) {
+        this.assertMethodAvailable("session/set_mode");
+        const raw = await this.send("session/set_mode", {
+            sessionId: params.sessionId,
+            modeId: params.modeId,
+        });
+        return parseSetSessionModeResponse(raw, this.provider);
+    }
+    async setSessionConfigOption(params) {
+        this.assertMethodAvailable("session/set_config_option");
+        const raw = await this.send("session/set_config_option", {
+            sessionId: params.sessionId,
+            configId: params.configId,
+            value: params.value,
+        });
+        return parseSetSessionConfigOptionResponse(raw, this.provider);
+    }
+    augmentSessionMethods(response) {
+        for (const method of sessionResponseMethods(response)) {
+            this.methodAvailability.add(method);
+        }
+    }
+    assertMethodAvailable(method) {
+        this.assertInitialized(method);
+        if (!this.methodAvailability.has(method)) {
+            throw new AcpMethodUnsupportedError(this.provider, method, {
+                reason: "capability_not_advertised",
+            });
+        }
+        if (AcpClient.MUTATING_METHODS.has(method) && !this.allowMutatingSessionOps) {
+            throw new AcpMutatingDisabledError(this.provider, method, { reason: "config_gate_off" });
+        }
+    }
     async send(method, params, timeoutMs) {
         try {
             return await this.transport.request(method, params, timeoutMs);

package/dist/acp/errors.d.ts

@@ -1,5 +1,5 @@
 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 type AcpErrorKind = "acp_disabled" | "provider_acp_disabled" | "provider_acp_unsupported" | "provider_runtime_disabled" | "provider_unavailable" | "method_unsupported" | "mutating_disabled" | "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;
@@ -32,6 +32,14 @@ export declare class ProviderRuntimeDisabledError extends AcpError {
 export declare class ProviderUnavailableError extends AcpError {
     constructor(provider: CliType, reason: string, debug?: AcpErrorDebug);
 }
+export declare class AcpMethodUnsupportedError extends AcpError {
+    readonly method: string;
+    constructor(provider: CliType, method: string, debug?: AcpErrorDebug);
+}
+export declare class AcpMutatingDisabledError extends AcpError {
+    readonly method: string;
+    constructor(provider: CliType, method: string, debug?: AcpErrorDebug);
+}
 export declare class AcpProtocolError extends AcpError {
     readonly code?: number;
     constructor(userMessage: string, options?: {

package/dist/acp/errors.js

@@ -2,6 +2,9 @@ export function redactAcpMessage(input) {
     let out = redactJsonLikeBodies(input);
     out = out.replace(/\b(bearer|token|api[_-]?key|secret)\b\s*[:=]?\s*\S+/gi, "$1 <redacted>");
     out = out.replace(/\b(sk|xai|gsk|key)-[A-Za-z0-9_-]{8,}\b/gi, "<redacted-token>");
+    out = out.replace(/\bAIza[A-Za-z0-9_-]{10,}/g, "<redacted-token>");
+    out = out.replace(/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, "<redacted-token>");
+    out = out.replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gi, "<redacted-token>");
     out = out.replace(/(^|[^A-Za-z0-9._~\\/-])[A-Za-z]:\\[^\s"')\]}>]*/g, "$1<redacted-path>");
     out = out.replace(/(^|[^A-Za-z0-9._~\\/-])\\\\[^\s"')\]}>]+/g, "$1<redacted-path>");
     out = out.replace(/(^|[^A-Za-z0-9._~/-])~\/[^\s"')\]}>]+/g, "$1<redacted-path>");
@@ -150,6 +153,22 @@ export class ProviderUnavailableError extends AcpError {
         this.name = "ProviderUnavailableError";
     }
 }
+export class AcpMethodUnsupportedError extends AcpError {
+    method;
+    constructor(provider, method, debug) {
+        super("method_unsupported", `ACP method ${method} is not advertised by provider ${provider}'s capability set; the agent did not declare support for it.`, { provider, debug: { method, ...(debug ?? {}) } });
+        this.name = "AcpMethodUnsupportedError";
+        this.method = method;
+    }
+}
+export class AcpMutatingDisabledError extends AcpError {
+    method;
+    constructor(provider, method, debug) {
+        super("mutating_disabled", `ACP mutating session op ${method} is disabled. Set allow_mutating_session_ops=true under [acp] to permit state-mutating ACP admin ops.`, { provider, debug: { method, ...(debug ?? {}) } });
+        this.name = "AcpMutatingDisabledError";
+        this.method = method;
+    }
+}
 export class AcpProtocolError extends AcpError {
     code;
     constructor(userMessage, options) {

package/dist/acp/event-normalizer.d.ts

@@ -29,6 +29,12 @@ export type AcpProgressEvent = {
     readonly kind: "usage";
     readonly size: number;
     readonly used: number;
+} | {
+    readonly kind: "session_complete";
+    readonly stopReason: string;
+} | {
+    readonly kind: "error";
+    readonly message: string;
 } | {
     readonly kind: "other";
     readonly sessionUpdate: string;
@@ -37,6 +43,12 @@ export declare function summarizeContentBlock(block: ContentBlock): string;
 export declare function normalizeSessionUpdate(notification: SessionUpdateNotification): AcpProgressEvent;
 export declare class AcpEventNormalizer {
     private text;
+    private stopReasonValue;
+    private errorValue;
     handle(notification: SessionUpdateNotification): AcpProgressEvent;
+    completeWith(stopReason: string): AcpProgressEvent;
+    error(message: string): AcpProgressEvent;
     get finalText(): string;
+    get stopReason(): string | undefined;
+    get errorMessage(): string | undefined;
 }