llm-cli-gateway 1.4.0 → 1.5.4

package/CHANGELOG.md

@@ -2,7 +2,73 @@
 
 All notable changes to the llm-cli-gateway project.
 
-## Unreleased
+## [1.5.4] - 2026-05-19
+
+### Fixed
+
+- Disable the default shared SQLite flight recorder during Vitest runs so parallel test workers do not race on `~/.llm-cli-gateway/logs.db` in GitHub Actions.
+- Keep the npm publish job under the public mirror's hosted-runner limit by installing without lifecycle scripts/audit, building once, verifying package contents, and leaving the full suite to CI.
+
+## [1.5.3] - 2026-05-19
+
+### Fixed
+
+- Align npm and PyPI release versions at 1.5.3.
+- Publish npm from the build already verified by CI instead of re-running `prepublishOnly` inside `npm publish`, which was causing the release publish step to be cancelled.
+- Add a PyPI tag/version guard so future release jobs fail before upload when `integrations/llm-plugin/pyproject.toml` does not match the release tag.
+
+## [1.5.2] - 2026-05-19
+
+### Fixed
+
+- **CI publish workflows fixed.** Both v1.5.0 and v1.5.1 npm + PyPI publish workflows failed; this release unblocks them:
+  - **`src/__tests__/session-manager.test.ts:437` — "should update lastUsedAt but not createdAt" was a broken test.** It used `setTimeout(...)` without awaiting it: the inner assertions never ran, AND the timer fired after `afterEach` removed the tmpdir, causing `FileSessionManager.updateSessionUsage` → `saveStorage` → `writeFileSync` to throw an unhandled `ENOENT`. Local vitest happened to exit 0 anyway; CI vitest correctly exits 1 on unhandled errors, so `npm test` failed every publish job. The test now `await`s the timer and snapshots `originalLastUsed` as a string (the original code compared against `session.lastUsedAt`, which is a live reference into the storage map and mutates when `updateSessionUsage` runs).
+  - **`.github/workflows/publish.yml` (PyPI) missing `contents: read`.** Declaring `permissions: { id-token: write }` shrinks `GITHUB_TOKEN` to only that scope, so `actions/checkout@v4` couldn't authenticate to fetch the release tag and failed with `fatal: could not read Username for 'https://github.com': terminal prompts disabled`. Permission now explicitly includes `contents: read`.
+
+No package-code changes vs 1.5.0 (functional surface) or 1.5.1 (installer workflow). This patch is the test + workflow correctness fix that lets the npm + PyPI artifacts actually publish.
+
+## [1.5.1] - 2026-05-19
+
+### Changed
+
+- **Desktop installer artifacts now built and uploaded automatically on release.** New `.github/workflows/release-installer.yml` triggers on `release: published`, cross-compiles the Go bootstrapper for 5 OS/arch targets (`darwin/{arm64,amd64}`, `linux/{amd64,arm64}`, `windows/amd64`), packages the Node gateway bundle (`llm-cli-gateway-bundle-<ver>.tar.gz`), generates `SHA256SUMS` + `release-manifest.json` with the repo-relative `RVWR_RELEASE_PUBLIC_BASE`, verifies checksums, and uploads everything as release assets via `gh release upload --clobber`. `workflow_dispatch` is supported so a missed run can be rebuilt for an existing tag. No package-code changes vs 1.5.0; this is purely the build/distribution pipeline that lets users install the desktop integration without git/npm/docker.
+
+## [1.5.0] - 2026-05-19
+
+Lands DAG layers 6-12 — the personal-MCP MVP terminal plus all of Phase 0-3 provider modernisation. Codex round-2 unconditional SHIP across U22-U27 (correlation `517700e1`). 523 tests passing (+184 from 1.4.0).
+
+### Added
+
+- **U19 / U20 — Early LLM-assisted setup validation + automated MVP test harness.** New `doctor.ts`, `http-transport.ts`, `validation-orchestrator.ts`, `validation-report.ts`, `validation-normalizer.ts`, `validation-prompts.ts`, `validation-tools.ts`, `endpoint-exposure.ts`, `auth.ts`, `provider-status.ts`, `provider-login-guidance.ts`, and `gateway-server.ts`. Prompt-pack tightenings driven by real LLM dogfooding (Gemini chat-only + Codex command-capable). 35 new tests across the four matching `__tests__/` files.
+- **U13 / U16 — Release packaging + dogfood readiness.** `installer/build-release.sh` cross-compiles 5 OS/arch targets (linux/{amd64,arm64}, darwin/{amd64,arm64}, windows/amd64) + Node bundle + `SHA256SUMS` + `release-manifest.json`. New `cli_upgrade --uninstall` (idempotent, dry-run by default) and `cli_upgrade --check`. New `Dockerfile.personal` + `docker-compose.personal.yml` for the personal-MCP container path. New `installer/packaging/README.md`. New `package.json` scripts `release:build`, `release:checksums`, `release:docker`. Comprehensive `docs/personal-mcp/{DOGFOODING_RESULTS,RELEASE_READINESS,SINGLE_BINARY_INSTALLER,ENDPOINT_EXPOSURE,PRODUCT_CONTRACT,PROVIDER_SUPPORT_MATRIX,VALIDATION_REPORT_FORMAT}.md` + per-provider `connect-*.md` guides + `setup/assistants/*-install-prompt.md` install-prompt corpus.
+- **U21 — Phase-0 parity fixes.** `SESSION_PROVIDER_VALUES` / `SESSION_PROVIDER_ENUM` now expose the full provider set (grok was previously absent from `session_create`/`session_list`/`session_clear_all` Zod enums despite the storage layer supporting it). `prepareGeminiRequest` emits `["-p", prompt, ...]` instead of a positional prompt, eliminating the dependency on Gemini's TTY/mode-detection heuristics. 6 new tests pin both fixes.
+- **U22 — Mistral Vibe is the fifth supported provider.** New `mistral_request` and `mistral_request_async` MCP tools register alongside the four incumbents and route through the same async job manager, dedup store, flight recorder, approval manager, and validation orchestrator. Five Vibe-specific divergences are documented in `docs/personal-mcp/PROVIDER_MODERNISATION_AUDIT.md`:
+  - **No `--model` flag** — model selection is via the `VIBE_ACTIVE_MODEL` environment variable (default alias: `devstral-medium`); the executor and async job manager forward an `env` override.
+  - **Session-logging is opt-in** in `~/.vibe/config.toml` — `doctor --json` probes `[session_logging] enabled = true` (read-only) and surfaces an actionable `next_actions` entry when the toggle is missing.
+  - **`--agent` enum** replaces Grok's `--always-approve` (`default | plan | accept-edits | auto-approve | chat | explore | lean`); the gateway always emits `--agent` explicitly and defaults to `auto-approve` for programmatic callers.
+  - **`--enabled-tools` allow-list only** — `allowedTools` emits one `--enabled-tools <tool>` per entry; `disallowedTools` is accepted in the schema for caller parity but silently ignored at the CLI boundary (a logged warning records the no-op).
+  - **No self-update** — `cli_upgrade --cli mistral` detects pip / uv / brew via probes and dispatches to `pip install -U vibe-cli`, `uv tool upgrade vibe-cli`, or `brew upgrade mistral-vibe`. Unknown installations return an actionable error rather than running a non-existent `vibe update`.
+
+  Other surfaces extended: `SESSION_PROVIDER_VALUES` now includes `"mistral"`; `list_models`, `cli_versions`, `cli_upgrade`, `approval_list`, `session_create`, `session_list`, and `session_clear_all` accept the fifth provider; new MCP resources `sessions://mistral` and `models://mistral` are registered; `validate_with_models` / `consensus_check` / `red_team_review` can route to Mistral.
+- **U23 — JSON output + token/cost parity across providers.** New `src/codex-json-parser.ts` parses the Codex `--json` JSONL event stream (`thread.started`, `turn.started`/`completed`/`failed`, `item.*`, `error`); lenient against partial streams and garbage preamble. New `src/gemini-json-parser.ts` parses `gemini -o json` output and maps `usageMetadata.{promptTokenCount, candidatesTokenCount, cachedContentTokenCount}`. `extractUsageAndCost` is now a thin per-provider dispatcher returning `{inputTokens, outputTokens, cacheReadTokens?, cacheCreationTokens?, costUsd?}` for every provider that supports JSON; Claude `cache_read_input_tokens` / `cache_creation_input_tokens` are now plumbed through instead of being discarded. `codex_request`, `codex_request_async`, `gemini_request`, and `gemini_request_async` now expose `outputFormat: enum("text","json")` — set to `"json"` and the gateway emits `--json` (Codex) or `-o json` (Gemini) and forwards parsed usage/cost into the flight recorder. Flight-recorder schema gains `cache_read_tokens` and `cache_creation_tokens` columns via idempotent migration (`PRAGMA table_info` → `ALTER TABLE ADD COLUMN`); existing `logs.db` files are upgraded in place. 15 new tests.
+- **U24 — Permission/approval-mode parity across providers.** Claude `permissionMode` enum (`default | acceptEdits | plan | auto | dontAsk | bypassPermissions`) replaces the boolean `dangerouslySkipPermissions` (the boolean still works and now maps to `permissionMode: "bypassPermissions"`; setting both logs a warning, `permissionMode` wins). Gemini `approvalMode` gains `plan`. Codex splits `--full-auto` into `sandboxMode: enum("read-only","workspace-write","danger-full-access")` and `askForApproval: enum("untrusted","on-request","never")`, emitting `--sandbox <mode>` and `--ask-for-approval <mode>` independently; legacy `fullAuto: true` still works and expands to `--sandbox workspace-write --ask-for-approval never` by default, with `useLegacyFullAutoFlag: true` as an explicit escape hatch to emit `--full-auto` directly. Codex resume mode filters all three flags (`--full-auto`, `--sandbox`, `--ask-for-approval`) since `codex exec resume` inherits the session's policy. 26 new tests.
+- **U25 — Claude high-impact features.** `claude_request` / `claude_request_async` schemas gain `agent?: string` (single sub-agent dispatch), `agents?: Record<string, object>` (multi-agent JSON, validated against `CLAUDE_AGENT_DEFINITION_SCHEMA` before emit), `forkSession?: boolean`, `systemPrompt?: string`, `appendSystemPrompt?: string` (mutually exclusive at the schema + tool-callback boundary), `maxBudgetUsd?: number`, `maxTurns?: number`, `effort?: enum("low","medium","high","xhigh","max")`, and `excludeDynamicSystemPromptSections?: boolean`. Each emits the documented `--<flag>` form. 25 new tests in `src/__tests__/claude-handler.test.ts`.
+- **U26 — Codex high-impact features.** `codex_request` / `codex_request_async` gain `outputSchema?: string | object` (object form is materialised to an `0o600` temp file under `os.tmpdir()` and cleaned via the AsyncJobManager `onComplete` contract — see post-review fixes below), `search?: boolean`, `profile?: string`, `configOverrides?: Record<string,string>` (keys validated against `/^[a-zA-Z0-9._]+$/`, values reject `\r`/`\n` via Zod refinement; emitted as repeated `-c key=value`), `ephemeral?: boolean`, `images?: string[]` (each path existence-validated; missing paths fail fast), `ignoreUserConfig?: boolean`, `ignoreRules?: boolean`. New top-level tool `codex_fork_session` wraps `codex fork <UUID> <prompt>` and `codex fork --last <prompt>` (sessionId XOR forkLast via Zod refinement). Codex default model alias is now `gpt-5.5` (the prior `gpt-5.3-codex` alias still resolves). Codex resume filter list extended with `--add-dir`, `-C`, `--output-schema`, and `--search`. 28 new tests across `codex-handler.test.ts` and `codex-fork.test.ts`.
+- **U27 — Gemini high-impact features.** `gemini_request` / `gemini_request_async` gain `sandbox?: boolean` (emits `-s`), `policyFiles?: string[]` and `adminPolicyFiles?: string[]` (each path existence-validated; missing paths fail fast), and `attachments?: string[]` (absolute paths only, validated and prepended to the prompt as `@<abs-path>` tokens before the `-p` pair — U21 ordering invariant preserved). For fresh sessions (`createNewSession: true` or no sessionId), the gateway now emits `--session-id <uuid-v4>` instead of `--resume`, mapping the gateway session 1:1 to Gemini's authoritative store; `gw-*` prefixed IDs are rejected via strict UUID-v4 regex. `doctor --json` probes `./GEMINI.md`, `~/.gemini/GEMINI.md`, and `~/.gemini/settings.json` (parses `mcpServers` and reconciles against the gateway's `--allowed-mcp-server-names` whitelist; surfaces `next_actions` for missing registrations). `provider-status.ts` `geminiAuthStatus()` recognises four auth methods: OAuth file, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, and `GOOGLE_CLOUD_PROJECT` + `GOOGLE_GENAI_USE_VERTEXAI=true`. 41 new tests across `gemini-handler.test.ts`, `provider-status.test.ts`, and the extended `doctor.test.ts`.
+
+### Fixed
+
+Round-1 Codex review found 5 blockers across U22, U23, and U26; round-2 unconditional SHIP. Locked in by `src/__tests__/post-review-fixes.test.ts` (14 tests, no mocks).
+
+- **U22 dedup key now reflects env vars.** `AsyncJobManager.buildRequestKey(cli, args, env)` hashes a `canonicaliseEnvForKey(env)` payload (sorted-keys JSON) via the existing `computeRequestKey(cli, args, extra)` API. Two Mistral requests with the same argv but different `VIBE_ACTIVE_MODEL` no longer collide on dedup. Empty/undefined env collapses to `""` so pre-U22 callers retain the same key shape and previously-stored entries remain hit-able.
+- **U23 JSON parsers are now reachable.** The newly-added Codex JSONL parser and Gemini JSON parser were dead code because `codex_request` / `gemini_request` exposed no `outputFormat` parameter and the gateway never emitted `--json` / `-o json`. Both tool schemas (sync + async) now expose `outputFormat: enum("text","json")`. `prepareCodexRequest` emits `--json`; `prepareGeminiRequest` emits a contiguous `-o json` pair after the U21 `-p` prompt pair. The success paths for `codex_request` and `gemini_request` now run `extractUsageAndCost(cli, stdout, outputFormat)` and forward `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheCreationTokens`, and `costUsd` into the flight recorder.
+- **U26 `outputSchema` temp-file lifecycle now correct on every exit path.** `AsyncJobRecord` gains `onComplete?: () => void` + `onCompleteFired?: boolean` guard. `fireOnComplete(job)` is wired into every site that calls `persistComplete(job)` (8 total: close handler, cancel, idle-timeout, output overflow, dead-process recovery, exited-flag mismatch, process-monitor expiry, persistence-recovery). The dedup path also fires the new request's `onComplete` immediately so a deduped request never leaves its own materialised temp file orphaned. `awaitJobOrDefer` now takes `onComplete` as a trailing arg and guarantees exactly-once consumption across direct-execution, deferred, and `startJobWithDedup`-throws branches. The sync `codex_request` finally no longer runs cleanup (would have deleted the temp file while the deferred CLI process was still reading it); the async `codex_request_async` no longer leaks the temp file on successful start.
+
+### Changed
+
+- Codex default model alias is now `gpt-5.5` (legacy `gpt-5.3-codex` alias preserved).
+- Default `model-registry` fallback chain order updated for new aliases.
+- Skills (`.agents/skills/*` and `skills/*`) extended from four-provider to five-provider lists, with Mistral notes on auto-approve default and session-logging requirement.
 
 ## [1.4.0] - 2026-05-16
 

package/README.md

@@ -5,6 +5,54 @@
 
 A Model Context Protocol (MCP) server providing unified access to Claude Code, Codex, Gemini, and Grok CLIs with session management, retry logic, and async job orchestration.
 
+## Personal MCP Appliance MVP
+
+`llm-cli-gateway` is being packaged as a single-user personal MCP appliance for cross-LLM validation. The intended workflow is: connect one MCP endpoint, ask any client for cross-LLM validation.
+
+The product contract is documented in [docs/personal-mcp/PRODUCT_CONTRACT.md](docs/personal-mcp/PRODUCT_CONTRACT.md). It defines the single-user scope, security posture, target support matrix, and provider-support verification gates. Public setup guides must not claim ChatGPT, Claude web, Claude Desktop, Codex, Gemini CLI, Gemini web, or Grok inbound support until the corresponding provider/client path has been verified.
+
+This project does not provide hosted multi-tenant credential custody. Provider credentials stay on the user's machine or user-owned deployment volume.
+
+MVP release readiness is tracked in [docs/personal-mcp/RELEASE_READINESS.md](docs/personal-mcp/RELEASE_READINESS.md). Dogfooding evidence (which target LLMs guided setup, what unsafe suggestions were captured, which findings are deferred to post-MVP work) is in [docs/personal-mcp/DOGFOODING_RESULTS.md](docs/personal-mcp/DOGFOODING_RESULTS.md).
+
+Current personal-appliance artifacts include:
+
+- Streamable HTTP startup: `LLM_GATEWAY_AUTH_TOKEN=<token> npm run start:http`
+- Machine-readable diagnostics: `npm run doctor`
+- Go bootstrapper scaffold: `installer/` with `setup`, `doctor --json`, `start`, `stop`, `status`, `repair`, `upgrade`, `uninstall`, `print-client-config`, and verified bundle download commands.
+- Release packaging: `npm run release:build` produces cross-platform binaries plus a checksummed Node bundle under `installer/dist/`; see [installer/packaging/README.md](installer/packaging/README.md).
+- Docker Compose fallback: [docker-compose.personal.yml](docker-compose.personal.yml) + [Dockerfile.personal](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`.
+
+### Install / Upgrade / Uninstall (single binary)
+
+```bash
+# After downloading the binary that matches your OS/arch from a release:
+sha256sum --check SHA256SUMS            # verify before run (or `shasum -a 256 --check` on macOS)
+chmod +x llm-cli-gateway-<ver>-<os>-<arch>
+./llm-cli-gateway-<ver>-<os>-<arch> setup
+./llm-cli-gateway-<ver>-<os>-<arch> install-bundle    # uses RVWR_GATEWAY_BUNDLE_URL/_SHA256
+./llm-cli-gateway-<ver>-<os>-<arch> start
+./llm-cli-gateway-<ver>-<os>-<arch> doctor
+
+# Upgrade: replace the binary, set the new bundle env vars, run upgrade.
+./llm-cli-gateway-<new>-<os>-<arch> upgrade
+
+# Uninstall: dry-run first, then run with --yes.
+./llm-cli-gateway-<ver>-<os>-<arch> uninstall
+./llm-cli-gateway-<ver>-<os>-<arch> uninstall --yes
+```
+
+Docker fallback:
+
+```bash
+LLM_GATEWAY_AUTH_TOKEN=$(openssl rand -hex 32) \
+  docker compose -f docker-compose.personal.yml up -d
+docker compose -f docker-compose.personal.yml run --rm doctor
+```
+
 ## Features
 
 ### Core Capabilities
@@ -63,6 +111,36 @@ grok login   # OAuth flow, or set GROK_CODE_XAI_API_KEY
 # Docs: https://docs.x.ai/build/cli
 ```
 
+### Mistral Vibe CLI
+```bash
+# Pick one — the gateway's cli_upgrade auto-detects which one you used.
+pip install vibe-cli
+uv tool install vibe-cli
+brew install mistral-vibe
+
+vibe auth login
+# Required for `mistral_request --resume` / `--continue` to persist sessions:
+vibe config set session_logging.enabled true   # or edit ~/.vibe/config.toml
+```
+
+Vibe-specific notes:
+
+- **Model selection is via the `VIBE_ACTIVE_MODEL` environment variable** —
+  Vibe has no `--model` flag. The gateway resolves the requested model alias
+  (default: `devstral-medium`) and injects it as `VIBE_ACTIVE_MODEL` when
+  spawning `vibe`.
+- **`permissionMode` accepts** `default | plan | accept-edits | auto-approve |
+  chat | explore | lean` and emits `--agent <mode>`. The gateway's
+  programmatic-mode default is `auto-approve`; pick a stricter mode
+  explicitly if you need approval gates.
+- **`allowedTools` is allow-list only** — the gateway emits one
+  `--enabled-tools <tool>` flag per entry. `disallowedTools` is accepted in
+  the schema for caller-side parity but is silently ignored at the CLI
+  boundary (a `logger.info` warning records the no-op).
+- **No self-update**: `cli_upgrade --cli mistral` detects whether you used
+  pip / uv / brew and dispatches the matching upgrade command. Running
+  `vibe update` is not a thing.
+
 ## Installation
 
 ### As an MCP server (npm)
@@ -94,7 +172,7 @@ npm run build
 
 ### As an MCP Server
 
-Add to your MCP client configuration (e.g., Claude Desktop):
+For clients that already support local stdio MCP servers, add a configuration like:
 
 ```json
 {
@@ -107,8 +185,24 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 }
 ```
 
+This generic stdio example is not provider-support verification for the Personal MCP Appliance MVP. 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
 
+#### Cross-LLM Validation Tools
+
+The personal-appliance surface exposes simplified validation tools for non-developer clients. These tools start provider CLI jobs through the durable async job manager and return normalized provider status plus raw job references.
+
+- `validate_with_models`: ask two or more providers to independently validate a question.
+- `second_opinion`: ask one provider to review an answer.
+- `red_team_review`: challenge a plan, answer, or document for risks and failure modes.
+- `consensus_check`: check whether providers agree with a claim.
+- `ask_model`: ask one provider through the simplified surface.
+- `synthesize_validation`: run an explicit judge model after provider results have been collected.
+- `job_status` and `job_result`: poll and collect validation job outputs.
+
+The validation report preserves per-provider disagreement. Optional judge synthesis is explicit about which provider produced the judge job.
+
 #### LLM Request Tools
 
 ##### `claude_request`
@@ -258,8 +352,17 @@ Environment variables:
 - `LLM_GATEWAY_DEDUP_WINDOW_MS` — how recent an existing job must be to dedup against. Default `3600000` (1 hour). Set `0` to disable dedup.
 - `LLM_GATEWAY_JOBS_DB` — override the sqlite path. Defaults to the value of `LLM_GATEWAY_LOGS_DB`, then `~/.llm-cli-gateway/logs.db`. Set to `none` to disable durability entirely (in-memory only).
 
-##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async`
-Start a long-running Claude, Codex, Gemini, or Grok request without waiting for completion in the same MCP call.
+##### `mistral_request`
+Run a Mistral Vibe agentic coding request. Like `grok_request` in shape, but with Vibe's specific surface:
+
+- `model` (string, optional): Resolved alias (e.g. `devstral-medium`, `devstral-large`, `latest`). The resolved value is injected via the `VIBE_ACTIVE_MODEL` environment variable — Vibe has no `--model` flag.
+- `permissionMode`: `default | plan | accept-edits | auto-approve | chat | explore | lean` — emitted as `--agent <mode>`. 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.
+- `sessionId` / `resumeLatest` / `createNewSession`: standard session controls. Continuity requires `[session_logging] enabled = true` in `~/.vibe/config.toml` — `doctor --json` surfaces an actionable next-action when the toggle is missing.
+
+##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async`
+Start a long-running Claude, Codex, Gemini, Grok, or Mistral request without waiting for completion in the same MCP call.
 
 Use this flow when analysis/runtime can exceed client tool-call limits:
 1. Start job with `*_request_async`
@@ -297,7 +400,7 @@ Approval records are persisted to `~/.llm-cli-gateway/approvals.jsonl`.
 Create a new session for a specific CLI.
 
 **Parameters:**
-- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok")
+- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok", "mistral")
 - `description` (string, optional): Description for the session
 - `setAsActive` (boolean, optional): Set as active session, default: true
 
@@ -314,7 +417,7 @@ Create a new session for a specific CLI.
 List all sessions, optionally filtered by CLI.
 
 **Parameters:**
-- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok")
+- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok", "mistral")
 
 **Response includes:**
 - Total session count
@@ -352,7 +455,7 @@ Clear all sessions, optionally for a specific CLI.
 List available models for each CLI.
 
 **Parameters:**
-- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok")
+- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok", "mistral")
 
 **Response includes:**
 - Model names and descriptions
@@ -394,13 +497,13 @@ LLM_GATEWAY_DISABLE_MODEL_DISCOVERY=1
 Report installed CLI versions.
 
 **Parameters:**
-- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok")
+- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok", "mistral")
 
 ##### `cli_upgrade`
 Plan or run an upgrade for one CLI.
 
 **Parameters:**
-- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok")
+- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok", "mistral")
 - `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`

package/dist/approval-manager.d.ts

@@ -2,7 +2,7 @@ import type { Logger } from "./logger.js";
 import type { ReviewIntegrityResult } from "./review-integrity.js";
 export type ApprovalPolicy = "strict" | "balanced" | "permissive";
 export type ApprovalStrategy = "legacy" | "mcp_managed";
-export type ApprovalCli = "claude" | "codex" | "gemini" | "grok";
+export type ApprovalCli = "claude" | "codex" | "gemini" | "grok" | "mistral";
 export type ApprovalStatus = "approved" | "denied";
 export interface ApprovalRequest {
     cli: ApprovalCli;

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

@@ -1,7 +1,7 @@
 import type { Logger } from "./logger.js";
 import { type JobHealth } from "./process-monitor.js";
 import { JobStore } from "./job-store.js";
-export type LlmCli = "claude" | "codex" | "gemini" | "grok";
+export type LlmCli = "claude" | "codex" | "gemini" | "grok" | "mistral";
 export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
 export interface AsyncJobSnapshot {
     id: string;
@@ -29,6 +29,22 @@ export interface StartJobOptions {
     outputFormat?: string;
     /** Bypass dedup and force a fresh CLI run even if a recent matching job exists. */
     forceRefresh?: boolean;
+    /**
+     * Extra environment variables to inject when spawning the child CLI.
+     * Used by Mistral Vibe to pass `VIBE_ACTIVE_MODEL` (Vibe has no `--model` flag).
+     *
+     * IMPORTANT: env vars participate in the dedup key (canonicalised by sorted
+     * keys + JSON-stringified). Two requests that differ only in env (e.g. two
+     * Mistral requests with the same prompt but different VIBE_ACTIVE_MODEL)
+     * therefore do NOT collide on dedup.
+     */
+    env?: Record<string, string>;
+    /**
+     * Optional hook fired exactly once when the job reaches a terminal state.
+     * Used by callers that own per-request resources (outputSchema temp files,
+     * etc.) that must persist for the lifetime of the spawned CLI process.
+     */
+    onComplete?: () => void;
 }
 export interface StartJobOutcome {
     snapshot: AsyncJobSnapshot;
@@ -50,8 +66,13 @@ export declare class AsyncJobManager {
     /**
      * Compute the dedup key for a job. Stable across re-issues of the same request,
      * which is exactly what allows agents to safely retry without restarting the run.
+     *
+     * U22 fix: env vars participate in the key via a deterministic canonicalisation
+     * (sorted keys → JSON-stringified). This prevents two Mistral requests with the
+     * same argv but different `VIBE_ACTIVE_MODEL` from deduping onto each other.
      */
     private buildRequestKey;
+    private fireOnComplete;
     private safeStoreCall;
     /**
      * Flush in-memory stdout/stderr to the durable store if anything changed
@@ -71,7 +92,7 @@ export declare class AsyncJobManager {
      * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
      * optional param for the dedup-aware path.
      */
-    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean): AsyncJobSnapshot;
+    startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean, env?: Record<string, string>, onComplete?: () => void): AsyncJobSnapshot;
     /**
      * Start a job, with optional dedup against recent identical requests.
      * Returns `{ snapshot, deduped }` so callers can log/report the short-circuit.
@@ -82,6 +103,7 @@ export declare class AsyncJobManager {
      */
     startJobWithDedup(cli: LlmCli, args: string[], correlationId: string, opts?: StartJobOptions): StartJobOutcome;
     getJobSnapshot(jobId: string): AsyncJobSnapshot | null;
+    getJobSnapshots(jobIds: string[]): Record<string, AsyncJobSnapshot | null>;
     getJobResult(jobId: string, maxChars?: number): AsyncJobResult | null;
     cancelJob(jobId: string): {
         canceled: boolean;

package/dist/async-job-manager.js

@@ -8,6 +8,22 @@ const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
 const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour in-memory retention; durable store has its own (longer) retention
 const EVICTION_INTERVAL_MS = 5 * 60 * 1000; // Check every 5 minutes
 const OUTPUT_FLUSH_INTERVAL_MS = 1000; // Throttle DB writes for streaming stdout/stderr
+/**
+ * U22 fix: deterministic canonicalisation of an env-var map for the dedup key.
+ * Returns "" when env is undefined or empty (preserves dedup key continuity for
+ * pre-U22 callers that pass no env).
+ */
+function canonicaliseEnvForKey(env) {
+    if (!env)
+        return "";
+    const entries = Object.entries(env)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => [k, String(v)]);
+    if (entries.length === 0)
+        return "";
+    entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return JSON.stringify(entries);
+}
 function truncateText(value, maxChars) {
     if (value.length <= maxChars) {
         return { text: value, truncated: false };
@@ -82,6 +98,7 @@ export class AsyncJobManager {
                         this.logger.error(`Job ${id} process ${job.process.pid} no longer exists, marking as failed`);
                         this.emitMetrics(job);
                         this.persistComplete(job);
+                        this.fireOnComplete(job);
                     }
                     // EPERM: process exists but we can't signal it — ignore
                 }
@@ -96,6 +113,7 @@ export class AsyncJobManager {
                 this.logger.error(`Job ${id} has exited flag but was still in running state, marking as failed`);
                 this.emitMetrics(job);
                 this.persistComplete(job);
+                this.fireOnComplete(job);
             }
         }
         for (const [id, job] of this.jobs) {
@@ -126,9 +144,26 @@ export class AsyncJobManager {
     /**
      * Compute the dedup key for a job. Stable across re-issues of the same request,
      * which is exactly what allows agents to safely retry without restarting the run.
+     *
+     * U22 fix: env vars participate in the key via a deterministic canonicalisation
+     * (sorted keys → JSON-stringified). This prevents two Mistral requests with the
+     * same argv but different `VIBE_ACTIVE_MODEL` from deduping onto each other.
      */
-    buildRequestKey(cli, args) {
-        return computeRequestKey(cli, args);
+    buildRequestKey(cli, args, env) {
+        return computeRequestKey(cli, args, canonicaliseEnvForKey(env));
+    }
+    fireOnComplete(job) {
+        if (job.onCompleteFired)
+            return;
+        if (!job.onComplete)
+            return;
+        job.onCompleteFired = true;
+        try {
+            job.onComplete();
+        }
+        catch (err) {
+            this.logger.error(`Job ${job.id} onComplete hook threw`, err);
+        }
     }
     safeStoreCall(label, fn) {
         if (!this.store)
@@ -234,12 +269,14 @@ export class AsyncJobManager {
      * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
      * optional param for the dedup-aware path.
      */
-    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat, forceRefresh) {
+    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat, forceRefresh, env, onComplete) {
         return this.startJobWithDedup(cli, args, correlationId, {
             cwd,
             idleTimeoutMs,
             outputFormat,
             forceRefresh,
+            env,
+            onComplete,
         }).snapshot;
     }
     /**
@@ -251,8 +288,8 @@ export class AsyncJobManager {
      * is returned without spawning a new process. forceRefresh skips dedup entirely.
      */
     startJobWithDedup(cli, args, correlationId, opts = {}) {
-        const { cwd, idleTimeoutMs, outputFormat, forceRefresh } = opts;
-        const requestKey = this.buildRequestKey(cli, args);
+        const { cwd, idleTimeoutMs, outputFormat, forceRefresh, env: extraEnv, onComplete } = opts;
+        const requestKey = this.buildRequestKey(cli, args, extraEnv);
         if (!forceRefresh && this.store) {
             try {
                 const existing = this.store.findByRequestKey(requestKey);
@@ -268,6 +305,19 @@ export class AsyncJobManager {
                             originalCorrelationId: record.correlationId,
                             status: record.status,
                         });
+                        // U26 fix: the caller's per-request resources (e.g. outputSchema temp
+                        // file) are NOT consumed by the deduped job, which reuses its own
+                        // original resources. Release the new request's cleanup immediately
+                        // to avoid an orphaned temp file. The original job's onComplete (if
+                        // any) remains attached to that original job record.
+                        if (onComplete) {
+                            try {
+                                onComplete();
+                            }
+                            catch (err) {
+                                this.logger.error("dedup onComplete cleanup threw", err);
+                            }
+                        }
                         return {
                             snapshot: this.snapshot(record),
                             deduped: true,
@@ -282,11 +332,14 @@ export class AsyncJobManager {
         }
         const id = randomUUID();
         const startedAt = new Date().toISOString();
-        const child = spawn(cli, args, {
+        // Mistral Vibe ships as the `vibe` binary; the gateway uses `mistral` as the
+        // provider key but spawns `vibe` on the shell.
+        const command = cli === "mistral" ? "vibe" : cli;
+        const child = spawn(command, args, {
             cwd,
             detached: true,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, PATH: getExtendedPath() },
+            env: { ...process.env, PATH: getExtendedPath(), ...(extraEnv ?? {}) },
         });
         if (child.pid)
             registerProcessGroup(child.pid);
@@ -320,6 +373,8 @@ export class AsyncJobManager {
             metricsRecorded: false,
             outputFormat,
             cleanupGroup,
+            onComplete,
+            onCompleteFired: false,
             outputDirty: false,
             lastOutputFlushAt: Date.now(),
         };
@@ -356,6 +411,7 @@ export class AsyncJobManager {
                 });
                 this.emitMetrics(job);
                 this.persistComplete(job);
+                this.fireOnComplete(job);
                 setTimeout(() => {
                     if (!job.exited && job.process)
                         killProcessGroup(job.process, "SIGKILL");
@@ -386,6 +442,7 @@ export class AsyncJobManager {
                 this.logger.error(`Job ${id} error: ${error.message}`, { correlationId });
                 this.emitMetrics(job);
                 this.persistComplete(job);
+                this.fireOnComplete(job);
             }
         });
         child.on("close", (code) => {
@@ -402,6 +459,7 @@ export class AsyncJobManager {
                 }
                 // Ensure terminal state reaches the durable store (idle-timeout/output-overflow already persisted).
                 this.persistComplete(job);
+                this.fireOnComplete(job);
                 return;
             }
             job.exitCode = code ?? 0;
@@ -417,6 +475,7 @@ export class AsyncJobManager {
             }
             this.emitMetrics(job);
             this.persistComplete(job);
+            this.fireOnComplete(job);
         });
         return { snapshot: this.snapshot(job), deduped: false };
     }
@@ -429,6 +488,9 @@ export class AsyncJobManager {
         }
         return this.snapshot(job);
     }
+    getJobSnapshots(jobIds) {
+        return Object.fromEntries(jobIds.map(jobId => [jobId, this.getJobSnapshot(jobId)]));
+    }
     getJobResult(jobId, maxChars = 200000) {
         let job = this.jobs.get(jobId);
         if (!job) {
@@ -468,6 +530,7 @@ export class AsyncJobManager {
         killProcessGroup(job.process, "SIGTERM");
         this.logger.info(`Job ${jobId} canceled`, { correlationId: job.correlationId });
         this.persistComplete(job);
+        this.fireOnComplete(job);
         setTimeout(() => {
             if (!job.exited && job.process)
                 killProcessGroup(job.process, "SIGKILL");
@@ -539,6 +602,7 @@ export class AsyncJobManager {
                 });
                 this.emitMetrics(job);
                 this.persistComplete(job);
+                this.fireOnComplete(job);
                 setTimeout(() => {
                     if (!job.exited && job.process)
                         killProcessGroup(job.process, "SIGKILL");

package/dist/auth.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export interface AuthConfig {
+    required: boolean;
+    tokenConfigured: boolean;
+    source: "env" | "disabled";
+}
+export interface AuthResult {
+    ok: boolean;
+    status?: number;
+    message?: string;
+}
+export declare function loadAuthConfig(env?: NodeJS.ProcessEnv): AuthConfig;
+export declare function getRequiredBearerToken(env?: NodeJS.ProcessEnv): string | null;
+export declare function authorizeBearerRequest(req: IncomingMessage, token?: string | null): AuthResult;
+export declare function writeAuthFailure(res: ServerResponse, result: AuthResult): void;

package/dist/auth.js

@@ -0,0 +1,46 @@
+const AUTH_SCHEME = "Bearer ";
+export function loadAuthConfig(env = process.env) {
+    const token = env.LLM_GATEWAY_AUTH_TOKEN;
+    const disabled = env.LLM_GATEWAY_AUTH_DISABLED === "1";
+    return {
+        required: !disabled,
+        tokenConfigured: Boolean(token),
+        source: disabled ? "disabled" : "env",
+    };
+}
+export function getRequiredBearerToken(env = process.env) {
+    const config = loadAuthConfig(env);
+    if (!config.required)
+        return null;
+    return env.LLM_GATEWAY_AUTH_TOKEN || null;
+}
+export function authorizeBearerRequest(req, token = getRequiredBearerToken()) {
+    if (!loadAuthConfig().required) {
+        return { ok: true };
+    }
+    if (!token) {
+        return {
+            ok: false,
+            status: 503,
+            message: "HTTP transport requires LLM_GATEWAY_AUTH_TOKEN",
+        };
+    }
+    const header = req.headers.authorization;
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value || !value.startsWith(AUTH_SCHEME)) {
+        return { ok: false, status: 401, message: "Unauthorized" };
+    }
+    const supplied = value.slice(AUTH_SCHEME.length);
+    if (supplied !== token) {
+        return { ok: false, status: 401, message: "Unauthorized" };
+    }
+    return { ok: true };
+}
+export function writeAuthFailure(res, result) {
+    const status = result.status ?? 401;
+    res.writeHead(status, {
+        "content-type": "application/json",
+        "www-authenticate": 'Bearer realm="llm-cli-gateway"',
+    });
+    res.end(JSON.stringify({ error: result.message || "Unauthorized" }));
+}