llm-cli-gateway 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -2,7 +2,69 @@
 
 All notable changes to the llm-cli-gateway project.
 
-## Unreleased
+## [2.12.0] - 2026-06-30: Validation receipts, API-provider parity, and a gateway usability pass
+
+### Added
+
+- **Durable, owner-scoped receipts for cross-LLM validation runs.** A terminal validation run (every dispatched provider job terminal, and the judge if one was requested) mints exactly one immutable `validation_receipts` row enveloping the existing `validation-report.v1` structuredContent, with a deterministic `canonical_sha256` over the canonical serialization (recursively sorted object keys, preserved array order, UTF-8; the re-derived `humanReadable` is excluded). Minting is eager (the first time a run is observed terminal, via the `job_result` collection hook and `synthesize_validation`), so a receipt is captured before job rows are evicted; an explicit read is the fallback.
+- **New `validation_receipt` tool.** Retrieves a receipt by `validationId` with own-or-not-found ownership: `minted` | `pending` | `expired_unminted` | `not_found`. `format: "json" | "markdown"` (markdown is a read-time rendering, never stored or hashed). `includeRawResponses` inlines full provider answer text as a read-time-only expansion pulled live per job under the same owner check (never persisted, never hashed).
+- **New `validation-receipt://{validationId}` MCP resource** with the same own-or-not-found owner scoping.
+- **Durable run identity (prerequisite).** `validation_runs` (plus a `validation_run_jobs` reverse index) persists each run's `validationId`, owner principal, and provider/judge job links at kickoff. The report and synthesis status enums gained a terminal `completed` value.
+- The receipt tool, the resource, and the run/receipt tables exist ONLY under an implemented durable backend (today `sqlite`) with a store attached at runtime; under `memory` / `postgres` / `none` no run/receipt row is written and the tool/resource are not registered (the caller still receives a `validationId` at kickoff). Silent loss is impossible by construction.
+- **Grok structured-output and session/worktree parity (Grok 0.2.73).** `grok_request` / `grok_request_async` gained `jsonSchema` (emits `--json-schema`, constrains output to a JSON Schema, implies json output), `forkSession` (emits `--fork-session`, forks a resumed session into a new ID), and `worktreeRef` (emits `--worktree-ref <REF>`; requires `nativeWorktree`, else rejected). Grok `--session-id` remains intentionally unwired (the gateway owns session-id lifecycle and cross-principal isolation).
+- **Antigravity project selection (agy 1.0.13).** `gemini_request` / `gemini_request_async` gained `project` (emits `--project <ID>`) and `newProject` (emits `--new-project`); the two are mutually exclusive (rejected if both set).
+- **API-provider unification: the generic `api_<name>_request` surface reaches CLI-tool parity (Slices 1-4b).** Telemetry parity (per-request usage/cost), schema parity (`promptParts`, `optimizePrompt`, `optimizeResponse`, `forceRefresh`, `sessionId`, `createNewSession`), capability-typed continuity with gateway sessions (`ApiContinuity` = `server-side-id` | `stateless-resend` | `none`), and server-side-id continuation on the generic handler. The legacy standalone `xai-api-provider` module was removed; the grok-api HTTP path now runs through the shared `api-provider` / `api-http` adapter (externally-observable response shape unchanged).
+- **OpenRouter usage accounting.** New optional provider config key `usage_include` opts the OpenAI-compatible adapter into `usage: { include: true }` so token counts and end-to-end `usage.cost` (USD) are returned; off by default so strict OpenAI-compatible servers are unaffected.
+- **Caller-facing skills now ship in the npm package.** The published gateway serves six caller skills (`async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, `public-demo-session`); previously `.agents` was excluded from `package.json` `files`, so every install served zero skills. Operator/maintainer skills (the `provider-*` contract guides, `gateway-restart-surfaces`) stay out of the tarball, and the release tarball guard now scans shipped skills for host-internal leaks.
+
+### Changed
+
+- **Upstream contracts refreshed to the installed provider versions.** Live `--probe-installed` probes were re-run across all six provider CLIs; ACP `targetVersion` pins bumped to claude 2.1.195, codex-cli 0.142.4, agy 1.0.13, grok 0.2.73, and devin 2026.8.18 (mistral vibe 2.17.1 unchanged), kept in sync across `upstream-contracts`, `provider-tool-capabilities`, and the ACP `provider-registry`. Acknowledged newly-advertised flags (claude `--bg`/`--background`); dropped stale acknowledgements (claude `--mcp-debug`, agy `-i`/`--version`); and acknowledged grok's `ssh` subcommand inheriting the global agent flag surface.
+- **`agy update` help-probe drift silenced.** `agy update --help` uses Go's `flag` package (prints "Usage of update:" and exits 2). A new `helpProbeExitTolerant` subcommand-contract marker treats that legitimate non-zero help exit as clean rather than reporting it as drift.
+- **Devin is now visible across discovery.** Devin was a fully registered request tool but omitted from the server instructions and rejected by the `list_models`, `cli_versions`, `cli_upgrade`, and `provider_tool_capabilities` enums; those now include devin (pure widening), and the stale "five providers" describe/description text was refreshed.
+- **Request tool and parameter descriptions sharpened for usability.** Clarified Codex `sandboxMode` (omit = read-only), Gemini `approvalMode`/`outputFormat` (only default/yolo and text work on the agy headless path), `approvalStrategy`/`approvalPolicy` semantics, `idleTimeoutMs` (gateway 10-min idle kill; Claude stream-json only), `jsonSchema` (set `outputFormat:json`), session-resume rules (gw-* fresh-session ids are not resumable; use `resumeLatest`), the generic API params, and the mistral/devin permission defaults.
+
+### Reliability and error guidance
+
+- **Result-health guards against silent success.** A Claude run that exits 0 but reports `is_error:true` (e.g. `error_max_turns`) now carries a `claude_result_error` warning and a `resultIsError` signal (the text is still returned); an exit-0 run with empty assistant output emits an `empty_output` warning. Claude `--output-format json` telemetry (usage/cost) is now parsed (it was previously dropped), and the real Codex session UUID is surfaced as `codexSessionId` so callers can resume/fork without filesystem access.
+- **Actionable error remediation.** `createErrorResponse` now detects auth/login failures and appends per-CLI remediation (`errorCategory: auth_error`), categorizes the 50MB output overflow as `output_overflow`, adds async-retry guidance on wall-clock timeout (124) and an interactive/idle hint on idle timeout (125), enriches Codex failures from the JSONL stream when stderr is empty (with a resume-not-found hint), and adds a fallback hint when a non-zero exit captured no stderr.
+- A whitespace-only prompt is now rejected at the prep boundary instead of being passed to the CLI.
+
+### Fixed
+
+- **Cross-principal read hole on the validation collection tools.** `job_status` / `job_result` now apply the `principalCanAccess` owner check that the `llm_job_*` paths already enforce; a job owned by another principal is reported as not found.
+
+### Deps
+
+- npm-minor-patch group: `smol-toml` 1.6.1 to 1.7.0 (runtime), `pg` 8.21.0 to 8.22.0, plus devDeps `@types/node` to 26.0.1, `@typescript-eslint/{eslint-plugin,parser}` 8.61.1 to 8.62.1, `eslint` 10.5.0 to 10.6.0, `prettier` 3.8.4 to 3.9.3. CI: `zizmor` 1.25.2 to 1.26.1, github-actions group bumps. Dependabot now ignores `body-parser` 2.3.0 (it transitively pulled the Socket-flagged `type-is` 2.1.0 / `content-type` 2.0.0 that the release audit blocks).
+
+### Not yet implemented (reserved)
+
+- Cryptographic signing and hash chaining. The `prev_sha256` / `seq` / `signature` columns are reserved (NULL); the canonical byte definition they will build on is fixed now. Semantic enrichment (`key_points`, `evidence_cited`, `uncertainty_signals`, numeric per-model confidence) is deferred to `validation-receipt.v2` (no extraction source exists today).
+
+## [2.11.1] - 2026-06-22: Provider contract refresh and stable upstream scans
+
+### Changed
+
+- **Upstream contracts refreshed for all providers.** Live `--probe-installed` probes were run across the installed provider CLIs. Synced contract surfaces and bumped ACP `targetVersion` pins:
+  - claude → 2.1.185 (added `--ax-screen-reader`, `--safe-mode` to acknowledged flags; `agents --all` to subcommand contract)
+  - codex → 0.141.0 (aligned `exec resume` / `exec review` / top-level `review` flag lists with current advertised surfaces)
+  - gemini (agy) → 1.0.10
+  - grok → 0.2.60 (474c2bbfc)
+  - mistral (vibe) → 2.17.1
+  - devin → 2026.7.23 (3bd47f77) (added new flags to `acknowledgedUpstreamFlags`)
+- **Mistral upstream scan source stabilized.** The scanner now tracks GitHub's latest-release API for Mistral Vibe instead of the volatile HTML releases page, so `--live --fail-on-critical` no longer trips on release-page chrome/hash churn.
+- **Provider skill docs updated.** All five `.agents/skills/provider-*` files bumped to metadata version 1.2. Descriptions now call out `/subcommand` behaviour changes; added current-version "Tested against" notes and usage examples for the cache levers (Grok compaction, Claude `cacheControl`).
+- **Cache usage documentation expanded with concrete examples.** Added exact parameters, emitted CLI flags, and stream-json payload shapes for Grok `compactionMode`/`compactionDetail` and Claude `promptParts.cacheControl` (including the `assembleClaudeCacheBlocks` NDJSON structure with `cache_control: {type:"ephemeral", ttl:"1h"}`) to:
+  - `docs/personal-mcp/PROVIDER_CACHE_SURFACES.md`
+  - `README.md` (updated Cache-aware operation section and matrix)
+  - `.agents/skills/session-workflow/SKILL.md`
+- Cross-LLM reviews (Claude, Codex, Mistral) on the implementation plan were incorporated: kept provider-specific levers (no new unifying `CacheDirective` abstraction); focused on documentation and discoverability.
+- **Internal caching hygiene.** Promoted the ad-hoc capability cache in `provider-tool-capabilities.ts` to a documented reusable TTL structure (`CAPABILITY_CACHE`, helpers, test accessors) for easier future reuse.
+
+### Tests / CI
+
+- `npm run upstream:contracts`, relevant cache/session/provider-tool tests, and build all green.
 
 ## [2.11.0] - 2026-06-18: API providers, Devin, ACP runtime, and a strip-at-publish internal-MCP boundary
 

package/README.md

@@ -9,9 +9,9 @@
 > _"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, and Mistral (Vibe) CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
+A Model Context Protocol (MCP) gateway for running Claude Code, Codex, Gemini, Grok, Mistral (Vibe), and Devin CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
 
-**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across five provider CLIs.
+**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across six provider CLIs.
 
 **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 +38,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 five provider CLIs through consistent sync and async MCP tools.
+- Runs six provider CLIs 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.
@@ -49,7 +49,7 @@ Or use directly with `npx` from an MCP client:
 
 ## Workflow Assets
 
-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. 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 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.
 
@@ -84,7 +84,7 @@ Current personal-appliance artifacts include:
 - Docker Compose fallback: [docker/personal.compose.yml](docker/personal.compose.yml) + [docker/Dockerfile.personal](docker/Dockerfile.personal) for users who already manage containers.
 - Local setup UI artifact: [setup/ui/index.html](setup/ui/index.html)
 - Provider setup snippets: [setup/providers/](setup/providers/)
-- Cross-validation tools: `validate_with_models`, `second_opinion`, `compare_answers`, `red_team_review`, `consensus_check`, `ask_model`, `synthesize_validation`, `job_status`, and `job_result`.
+- Cross-validation tools: `validate_with_models`, `second_opinion`, `compare_answers`, `red_team_review`, `consensus_check`, `ask_model`, `synthesize_validation`, `job_status`, `job_result`, and `validation_receipt` (plus the `validation-receipt://{validationId}` resource).
 
 ### Install / Upgrade / Uninstall (single binary)
 
@@ -157,7 +157,7 @@ docker compose -f docker/personal.compose.yml run --rm doctor
 
 ### Core Capabilities
 
-- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, Gemini, Grok, and Mistral (Vibe) CLIs
+- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, Gemini, Grok, Mistral (Vibe), and Devin CLIs
 - **Session Management**: Track and resume conversations across all CLIs with persistent storage
 - **Gateway-owned worktrees**: Run any sync or async provider request inside a managed git worktree, with per-session reuse and cleanup
 - **Token Optimization**: Automatic 44% reduction on prompts, 37% on responses (opt-in)
@@ -169,11 +169,11 @@ 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.
+- **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, Mistral Vibe, and Cognition Devin. `doctor --json` includes a compact `provider_capabilities` summary for setup assistants.
 
 ### Cache-aware operation
 
-Every `*_request` and `*_request_async` tool accepts an optional `promptParts` field that structures the prompt for better cache hit rates. The gateway concatenates the parts in canonical order (`system → tools → context → task`) so that the stable prefix bytes precede the volatile task tail unchanged across calls, letting each provider's automatic prompt-caching land on the same content hash each time.
+Every `*_request` and `*_request_async` tool except `devin_request` / `devin_request_async` accepts an optional `promptParts` field that structures the prompt for better cache hit rates (the Devin headless path takes a plain `prompt` only). The gateway concatenates the parts in canonical order (`system → tools → context → task`) so that the stable prefix bytes precede the volatile task tail unchanged across calls, letting each provider's automatic prompt-caching land on the same content hash each time.
 
 ```json
 {
@@ -188,17 +188,47 @@ Every `*_request` and `*_request_async` tool accepts an optional `promptParts` f
 
 `prompt` and `promptParts` are mutually exclusive — pass exactly one.
 
-Per-CLI capability matrix:
+Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for all providers except Devin, which has no `promptParts` surface; explicit levers are provider-specific):
+
+| 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) |
+
+**Claude example (explicit cacheControl)**
+
+```ts
+claude_request({
+  promptParts: {
+    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
+  },
+  outputFormat: "stream-json"
+})
+```
+
+Gateway emits the `stream-json` stdin path with `cache_control: {type:"ephemeral", ttl:"1h"}` on marked blocks only.
+
+**Grok example (compaction)**
+
+```ts
+grok_request({
+  promptParts: { system: "...", context: "...", task: "..." },
+  compactionMode: "segments",
+  compactionDetail: "balanced"
+})
+```
+
+Emits `--compaction-mode segments --compaction-detail balanced`.
 
-| CLI     | Prefix discipline (auto via `promptParts`) | Explicit `cache_control` emission                                            |
-| ------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
-| claude  | yes                                        | yes, opt-in via `promptParts.cacheControl` and `outputFormat: "stream-json"` |
-| codex   | yes                                        | n/a (OpenAI implicit cache, no CLI lever)                                    |
-| gemini  | yes                                        | n/a (implicit prefix cache server-side)                                      |
-| grok    | yes                                        | n/a (no surfaced cache lever)                                                |
-| mistral | yes                                        | n/a (no surfaced cache lever)                                                |
+See `docs/personal-mcp/PROVIDER_CACHE_SURFACES.md` for full surfaces, telemetry differences (e.g. Grok `-p` vs ACP), exact stream-json payload shapes, and cross-LLM review notes.
 
-Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gateway/config.toml`. See `docs/personal-mcp/PROVIDER_CACHE_SURFACES.md` for the per-model minimum cacheable token thresholds and field-name divergences.
+Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gateway/config.toml`.
 
 ### Reliability & Performance
 
@@ -210,7 +240,7 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 ### Security & Quality
 
-- **Comprehensive Testing**: 1,000+ tests covering unit, integration, and regression scenarios with real CLI execution
+- **Comprehensive Testing**: 1,700+ tests covering unit, integration, and regression scenarios with real CLI execution
 - **Input Validation**: Zod schemas prevent injection attacks
 - **No Secret Leakage**: Generic session descriptions only (file permissions 0o600)
 - **No ReDoS**: Bounded regex patterns prevent catastrophic backtracking
@@ -357,6 +387,9 @@ 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).
+
+The same receipt is also exposed as the `validation-receipt://{validationId}` MCP resource (same durable gate and own-or-not-found owner scoping).
 
 The validation report preserves per-provider disagreement. Optional judge synthesis is explicit about which provider produced the judge job.
 
@@ -501,6 +534,8 @@ Execute a Google Antigravity CLI (`agy`) request with session support.
 - `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`
 - `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"`
 - `includeDirs` (string[], optional): Additional workspace directories (passed as `--add-dir`)
+- `project` (string, optional): Select the Antigravity project for this session (`--project <ID>`); mutually exclusive with `newProject`
+- `newProject` (boolean, optional): Create a new Antigravity project for this session (`--new-project`); mutually exclusive with `project`
 - `sandbox` (boolean, optional): Run Antigravity in sandbox mode (`--sandbox`)
 - `outputFormat` (string, optional): `text` only. Antigravity print mode emits text; `json` and `stream-json` are rejected.
 - `mcpServers`, `allowedTools`, `policyFiles`, `adminPolicyFiles`, `attachments` (string[], optional) and `skipTrust` (boolean, optional): **Unsupported by Antigravity CLI** — non-empty values (or `skipTrust: true`) are rejected with an explanatory error. Retained in the schema for caller parity.
@@ -572,6 +607,9 @@ Execute a Grok CLI (xAI) request with session support.
 - `restoreCode` (boolean, optional): Check out the original session commit when resuming
 - `leaderSocket` (string, optional): Custom leader socket path (`--leader-socket`, Grok 0.2.32+; default `~/.grok/leader.sock`) — targets an isolated leader process, e.g. a local/branch Grok build
 - `nativeWorktree` (boolean|string, optional): Grok's own `--worktree` flag (`true` → bare, string → named); distinct from the gateway `worktree` option
+- `worktreeRef` (string, optional): Branch/tag/commit to base the native worktree on (`--worktree-ref`); requires `nativeWorktree`
+- `forkSession` (boolean, optional): Fork the resumed session into a new branch instead of appending to it
+- `jsonSchema` (string|object, optional): JSON Schema (string or object) constraining structured output (`--json-schema`)
 - `worktree` (boolean|object, optional): Run inside a gateway-owned git worktree (slice λ)
 - `promptParts` (object, optional): Cache-aware structured prompt `{ system?, tools?, context?, task }`; mutually exclusive with `prompt`
 - `optimizePrompt` (boolean, optional): Optimize prompt for token efficiency, default: false
@@ -848,9 +886,28 @@ Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but wit
 - `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
 - `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
-##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async`
+##### `devin_request`
+
+Run a Cognition Devin CLI request synchronously (headless print mode, `devin -p`). Auto-defers to a pollable job past the sync deadline when async jobs are enabled.
+
+**Parameters:**
+
+- `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)
+- `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`
+- `resumeLatest` (boolean, optional): Resume the most recent Devin session in cwd (`--continue`)
+- `createNewSession` (boolean, optional): Force a new session
+- `optimizePrompt` / `optimizeResponse` (boolean, optional): Token-efficiency optimisation, default: false
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
+
+##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async` / `devin_request_async`
 
-Start a long-running Claude, Codex, Gemini, Grok, or Mistral request without waiting for completion in the same MCP call.
+Start a long-running Claude, Codex, Gemini, Grok, Mistral, or Devin request without waiting for completion in the same MCP call.
 
 Use this flow when analysis/runtime can exceed client tool-call limits:
 
@@ -909,7 +966,7 @@ Return the gateway's declared provider CLI contracts, optionally probing the ins
 
 **Parameters:**
 
-- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral`)
+- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral|devin`)
 - `probeInstalled` (boolean, optional, default `false`): Run local `--help` probes and compare advertised flags against the declared contract — strongly recommended after any provider CLI upgrade. The probe reports `missingFlags`, `extraFlags`, `acknowledgedExtraFlags` (known upstream-only flags filtered from `extraFlags`), `discoveredFlags`, and stale-marker `warnings`.
 
 #### Session Management Tools
@@ -920,7 +977,7 @@ Create a new session for a specific CLI.
 
 **Parameters:**
 
-- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok", "mistral")
+- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok", "mistral", "devin")
 - `description` (string, optional): Description for the session
 - `setAsActive` (boolean, optional): Set as active session, default: true
 
@@ -940,7 +997,7 @@ List all sessions, optionally filtered by CLI.
 
 **Parameters:**
 
-- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok", "mistral")
+- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok", "mistral", "devin")
 
 **Response includes:**
 
@@ -989,7 +1046,7 @@ List available models for each CLI.
 
 **Parameters:**
 
-- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok", "mistral")
+- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok", "mistral", "devin")
 
 **Response includes:**
 
@@ -1037,7 +1094,7 @@ inputs.
 
 **Parameters:**
 
-- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"grok_api"`, or `"mistral"`)
+- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, or `"grok_api"`)
 - `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
@@ -1057,6 +1114,7 @@ Equivalent MCP resources:
 - `provider-tools://grok`
 - `provider-tools://grok_api`
 - `provider-tools://mistral`
+- `provider-tools://devin`
 
 `doctor --json` also emits a compact `provider_capabilities` block with the
 same schema version, per-provider request tool names, supported feature names,
@@ -1070,7 +1128,7 @@ Report installed CLI versions.
 
 **Parameters:**
 
-- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok", "mistral")
+- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok", "mistral", "devin")
 
 ##### `cli_upgrade`
 
@@ -1078,7 +1136,7 @@ Plan or run an upgrade for one CLI.
 
 **Parameters:**
 
-- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok", "mistral")
+- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok", "mistral", "devin")
 - `target` (string, optional): Package tag/version/target, default: `latest`
 - `dryRun` (boolean, optional): Return the upgrade plan without running it, default: `true`
 - `timeoutMs` (number, optional): Upgrade timeout when `dryRun=false`
@@ -1093,6 +1151,7 @@ Plan or run an upgrade for one CLI.
 - Grok latest: `grok update`
 - Grok explicit target: `grok update --version <target>`
 - Mistral (Vibe): dispatches to the detected installer (`pip`/`uv`/`brew`); errors with guidance when none is detected (Vibe ships no self-update command)
+- Devin latest: `devin update` (self-update; explicit version targets are unsupported)
 
 **Example dry run:**
 

package/dist/acp/provider-registry.js

@@ -4,7 +4,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "Mistral Vibe",
         status: "native_smoke_passed",
         supportKind: "native",
-        targetVersion: "vibe 2.14.1",
+        targetVersion: "vibe 2.17.1",
         entrypoint: Object.freeze({ command: "vibe-acp", args: Object.freeze([]) }),
         runtimeEnabledDefault: false,
         shipRuntimePilot: true,
@@ -17,7 +17,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "xAI Grok CLI",
         status: "native_smoke_passed",
         supportKind: "native",
-        targetVersion: "grok 0.2.50 (cadf94855)",
+        targetVersion: "grok 0.2.73 (9ff14c43bb)",
         entrypoint: Object.freeze({ command: "grok", args: Object.freeze(["agent", "stdio"]) }),
         runtimeEnabledDefault: false,
         shipRuntimePilot: true,
@@ -30,7 +30,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "OpenAI Codex CLI",
         status: "adapter_mediated_deferred",
         supportKind: "adapter_mediated",
-        targetVersion: "codex-cli 0.139.0",
+        targetVersion: "codex-cli 0.142.4",
         entrypoint: null,
         runtimeEnabledDefault: false,
         shipRuntimePilot: false,
@@ -43,7 +43,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "Anthropic Claude Code",
         status: "adapter_mediated_deferred",
         supportKind: "adapter_mediated",
-        targetVersion: "claude 2.1.175",
+        targetVersion: "claude 2.1.195",
         entrypoint: null,
         runtimeEnabledDefault: false,
         shipRuntimePilot: false,
@@ -56,7 +56,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "Google Antigravity",
         status: "absent_watchlist",
         supportKind: "none",
-        targetVersion: "agy 1.0.7",
+        targetVersion: "agy 1.0.13",
         entrypoint: null,
         runtimeEnabledDefault: false,
         shipRuntimePilot: false,
@@ -69,7 +69,7 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         displayName: "Cognition Devin CLI",
         status: "native_smoke_passed",
         supportKind: "native",
-        targetVersion: "devin 2026.5.26-8 (1a388fa9)",
+        targetVersion: "devin 2026.8.18 (16737566)",
         entrypoint: Object.freeze({ command: "devin", args: Object.freeze(["acp"]) }),
         runtimeEnabledDefault: false,
         shipRuntimePilot: true,

package/dist/api-provider.d.ts

@@ -2,6 +2,7 @@ import type { URL } from "node:url";
 import type { Logger } from "./logger.js";
 import { ApiHttpError } from "./api-http.js";
 export type ApiProviderKind = "openai-compatible" | "anthropic" | "xai-responses";
+export type ApiContinuity = "server-side-id" | "stateless-resend" | "none";
 export interface ApiChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
@@ -17,6 +18,7 @@ export interface ApiRequest {
     reasoningEffort?: "none" | "low" | "medium" | "high";
     timeoutMs?: number;
     previousResponseId?: string;
+    usageInclude?: boolean;
 }
 export interface ApiUsage {
     inputTokens?: number;
@@ -32,10 +34,12 @@ export interface ApiResult {
     raw: unknown;
     httpStatus: number;
     responseId?: string | null;
+    status?: string | null;
 }
 export interface ApiProvider {
     readonly name: string;
     readonly kind: ApiProviderKind;
+    readonly continuity: ApiContinuity;
     endpointUrl(baseUrl: string): URL;
     buildBody(req: ApiRequest): Record<string, unknown>;
     parseResult(httpStatus: number, body: string): ApiResult;
@@ -45,6 +49,7 @@ export interface ApiProvider {
 export declare class OpenAiCompatibleProvider implements ApiProvider {
     readonly name: string;
     readonly kind: "openai-compatible";
+    readonly continuity: "stateless-resend";
     constructor(name: string);
     endpointUrl(baseUrl: string): URL;
     buildBody(req: ApiRequest): Record<string, unknown>;
@@ -57,6 +62,7 @@ export declare class AnthropicProvider implements ApiProvider {
     readonly name: string;
     private readonly anthropicVersion;
     readonly kind: "anthropic";
+    readonly continuity: "stateless-resend";
     constructor(name: string, anthropicVersion?: string);
     endpointUrl(baseUrl: string): URL;
     buildBody(req: ApiRequest): Record<string, unknown>;
@@ -67,6 +73,7 @@ export declare class AnthropicProvider implements ApiProvider {
 export declare class XaiResponsesProvider implements ApiProvider {
     readonly name: string;
     readonly kind: "xai-responses";
+    readonly continuity: "server-side-id";
     constructor(name: string);
     endpointUrl(baseUrl: string): URL;
     buildBody(req: ApiRequest): Record<string, unknown>;

package/dist/api-provider.js

@@ -15,6 +15,7 @@ function firstNumber(...candidates) {
 export class OpenAiCompatibleProvider {
     name;
     kind = "openai-compatible";
+    continuity = "stateless-resend";
     constructor(name) {
         this.name = name;
     }
@@ -32,6 +33,8 @@ export class OpenAiCompatibleProvider {
             body.temperature = req.temperature;
         if (req.topP !== undefined)
             body.top_p = req.topP;
+        if (req.usageInclude)
+            body.usage = { include: true };
         return body;
     }
     parseResult(httpStatus, body) {
@@ -46,6 +49,7 @@ export class OpenAiCompatibleProvider {
                 inputTokens: firstNumber(usage.prompt_tokens, usage.input_tokens),
                 outputTokens: firstNumber(usage.completion_tokens, usage.output_tokens),
                 cacheReadTokens: firstNumber(usage?.prompt_tokens_details?.cached_tokens),
+                costUsd: firstNumber(usage.cost),
                 raw: usage,
             },
             raw: parsed,
@@ -65,6 +69,7 @@ export class AnthropicProvider {
     name;
     anthropicVersion;
     kind = "anthropic";
+    continuity = "stateless-resend";
     constructor(name, anthropicVersion = DEFAULT_ANTHROPIC_VERSION) {
         this.name = name;
         this.anthropicVersion = anthropicVersion;
@@ -152,6 +157,7 @@ function extractXaiResponseText(parsed) {
 export class XaiResponsesProvider {
     name;
     kind = "xai-responses";
+    continuity = "server-side-id";
     constructor(name) {
         this.name = name;
     }
@@ -186,6 +192,7 @@ export class XaiResponsesProvider {
         const usage = parsed?.usage ?? {};
         return {
             responseId: typeof parsed?.id === "string" ? parsed.id : null,
+            status: typeof parsed?.status === "string" ? parsed.status : null,
             model: typeof parsed?.model === "string" ? parsed.model : "unknown",
             text: extractXaiResponseText(parsed),
             usage: {

package/dist/api-request.js

@@ -47,5 +47,6 @@ export function prepareApiRequest(runtime, params) {
         reasoningEffort: params.reasoningEffort,
         timeoutMs: params.timeoutMs,
         previousResponseId: params.previousResponseId,
+        usageInclude: runtime.usageInclude,
     };
 }

package/dist/async-job-manager.d.ts

@@ -2,7 +2,10 @@ import type { Logger } from "./logger.js";
 import { type JobHealth } from "./process-monitor.js";
 import { JobStore } from "./job-store.js";
 import { type FlightRecorderLike } from "./flight-recorder.js";
-import { type ApiProvider, type ApiRequest } from "./api-provider.js";
+import type { ValidationRunStore } from "./job-store.js";
+import { type ApiProvider, type ApiRequest, type ApiUsage } from "./api-provider.js";
+export declare function extractApiHttpStatus(error: unknown): number | null;
+export declare function extractApiErrorBody(error: unknown): string | undefined;
 export type LlmCli = "claude" | "codex" | "gemini" | "grok" | "mistral" | "devin";
 export type JobProvider = LlmCli | (string & {});
 export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
@@ -41,6 +44,11 @@ export interface AsyncJobResult extends AsyncJobSnapshot {
     stderr: string;
     stdoutTruncated: boolean;
     stderrTruncated: boolean;
+    apiUsage?: ApiUsage;
+    httpStatus?: number | null;
+    responseId?: string | null;
+    model?: string;
+    errorBody?: string;
 }
 export interface StartJobOptions {
     cwd?: string;
@@ -72,6 +80,7 @@ export declare class AsyncJobManager {
     private buildOrphanFlightResult;
     checkStalledJobs(now?: number): void;
     hasStore(): boolean;
+    getValidationRunStore(): ValidationRunStore | null;
     private emitMetrics;
     private evictCompletedJobs;
     private buildRequestKey;
@@ -91,6 +100,7 @@ export declare class AsyncJobManager {
     private fireOnComplete;
     private writeFlightComplete;
     private safeExtractUsage;
+    private httpUsage;
     armFlightCompleteForDeferral(jobId: string): void;
     private safeStoreCall;
     private maybeFlushOutput;