llm-cli-gateway 2.11.1 → 2.12.0

package/.agents/skills/public-demo-session/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: public-demo-session
+description: Prepare and drive clean public llm-cli-gateway demo sessions for recordings, README demos, screenshots, or transcripts. Use when the user needs a redacted path, compact Codex output, direct provider calls, or a demo-safe Codex environment.
+metadata:
+  author: verivus-oss
+  version: "1.0"
+---
+
+# Public Demo Session
+
+Use this skill when the goal is a public recording, README demo, screenshot, or clean transcript. The priority is a short, reliable demo surface, not exhaustive orchestration.
+
+## Goals
+
+- Show only a public-safe workspace path such as `/llm-cli-gateway`.
+- Keep the llm-cli-gateway MCP server and workspace skills available.
+- Prefer direct, synchronous provider calls that return compact text.
+- Avoid validation wrappers, async polling, nested Codex, and repeated stuck-job polling unless the user explicitly asks for those features.
+
+## Path Hygiene
+
+Do not start Codex directly from an internal checkout path for public demos. A symlink may still leak a resolved path in some tools. Prefer a bind-mounted public path:
+
+```bash
+bwrap \
+  --bind "$REAL_REPO" /llm-cli-gateway \
+  --chdir /llm-cli-gateway \
+  --setenv CODEX_HOME "$DEMO_CODEX_HOME" \
+  codex --dangerously-bypass-approvals-and-sandbox
+```
+
+If the host needs Codex HTTPS/WebSocket support inside the mount namespace, bind the host CA backing store too. On this host `/etc/ssl/certs` depends on `/var/lib/ca-certificates`.
+
+The demo `CODEX_HOME` should have a minimal `config.toml` with:
+
+```toml
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+project_doc_max_bytes = 0
+
+[projects."/llm-cli-gateway"]
+trust_level = "trusted"
+
+[mcp_servers.llm-gateway]
+command = "node"
+args = ["/llm-cli-gateway/dist/index.js"]
+```
+
+Keep the demo home separate from the normal Codex home. Symlink `auth.json` from the normal Codex home if needed, but do not copy private history or sessions.
+
+## Demo Dispatch Defaults
+
+For simple “ask the other LLMs” demo prompts, use direct provider tools:
+
+```js
+claude_request({prompt: "...", outputFormat: "text"})
+gemini_request({prompt: "...", outputFormat: "text", skipTrust: true})
+mistral_request({prompt: "...", outputFormat: "text", trust: true})
+```
+
+Provider-specific notes:
+
+- Do not pass `maxTurns` to `claude_request` unless the current schema explicitly supports it.
+- Pass `skipTrust:true` to Gemini when the demo workspace trust prompt would interrupt the recording.
+- Pass `trust:true` to Mistral/Vibe for the same reason.
+- Avoid `grok_request` in demos unless the user explicitly names Grok and the local Grok CLI has been checked in this environment.
+- Avoid `codex_request` from inside a Codex demo unless the user explicitly asks for nested Codex.
+
+## Avoid In Demo Mode
+
+Do not use these by default for a public demo prompt:
+
+- `ask_model`
+- `validate_with_models`
+- `compare_answers`
+- `consensus_check`
+- `second_opinion`
+- `red_team_review`
+- `synthesize_validation`
+- `*_request_async`
+- `llm_job_status`, `llm_job_result`, `llm_job_cancel`
+- web search, unless the user explicitly asks for live verification
+
+If a provider fails, state that briefly and continue with useful returned outputs. Do not turn a short demo into a recovery workflow.
+
+## Quick Verification
+
+Before recording:
+
+```bash
+codex doctor --summary --no-color
+```
+
+Expected: MCP server present, WebSocket connected, provider endpoints reachable, and `0 warn · 0 fail`.
+
+Confirm the opening screen shows:
+
+```text
+directory: /llm-cli-gateway
+```

package/.agents/skills/secure-orchestration/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: secure-orchestration
+description: Security-conscious LLM orchestration with approval gates across Claude, Codex, Gemini, Grok, and Mistral. Use for high-risk operations, permissions, auditing.
+metadata:
+  author: verivus-oss
+  version: "1.6"
+---
+
+# Secure Orchestration
+
+Approval gate scores request risk, enforces policy thresholds. Applies uniformly to Claude, Codex, Gemini, Grok (xAI), and Mistral Vibe dispatches. Use when security matters — production codebases, sensitive data, autonomous operations.
+
+> **Mistral Vibe note**: the gateway always emits `--agent <mode>` explicitly and defaults the programmatic mode to `auto-approve`. Set `permissionMode:"plan"` (or `chat`/`explore`) when you want stricter behaviour. Current Vibe defaults session logging on; `doctor --json` surfaces explicit `[session_logging] enabled = false` as a `next_actions` entry.
+
+## Dispatch Defaults
+
+Apply these on every dispatch unless the caller has explicitly overridden a rule in the current turn:
+
+1. **Omit `model`** — let the gateway use its configured default per CLI. Nominating a model risks deprecated IDs (`o3`, `o3-pro`, `gpt-4o`, …) and capability mismatches.
+2. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). It runs the scored gateway gate first; Claude then uses `bypassPermissions`, Gemini uses `yolo`, and Codex still needs `fullAuto:true` for autonomous file/shell work. **The `mcp_managed` auto-flip itself is not scored as raw bypass; only caller-supplied raw bypass flags incur the +3 permission-bypass penalty below.** Raw `dangerouslySkipPermissions` / `dangerouslyBypassApprovalsAndSandbox` / caller-set `approvalMode:"yolo"` remain prohibited in production because they bypass the gateway gate entirely.
+3. **No wallclock timeout; poll every 60 s** — good security reviews take minutes to tens of minutes. `idleTimeoutMs` (no-output safeguard) remains a valid security control and is separate from wallclock timeout.
+4. **Iterate until unconditional APPROVED** (review dispatches only) — end every review prompt with "End with APPROVED or NOT APPROVED with findings." Loop: dispatch → parse verdict → on `NOT APPROVED` or conditional approval, dispatch fixes + re-review → repeat until unconditional APPROVED. Escalate after 3 rounds. This rule does **not** apply to pure implementation or non-review analysis dispatches.
+
+## Risk Scoring
+
+| Factor | Points | Trigger |
+|--------|--------|---------|
+| Permission bypass | +3 | Raw caller-supplied bypass: `dangerouslySkipPermissions:true`, `dangerouslyBypassApprovalsAndSandbox:true`, or caller-set Gemini `approvalMode:"yolo"`. The `approvalStrategy:"mcp_managed"` auto-flip is **not** scored here. |
+| Sensitive keywords | +3 | `delete`, `destroy`, `wipe`, `exfiltrate`, `credential`, `token`, `password`, `secret` |
+| Full auto | +2 | `fullAuto:true` (Codex) |
+| Bypass + full-auto | +2 | Both requested together |
+| Weighted MCP server | varies | Per-server approval weights from the host's MCP registry (e.g. a web-search server) add to the score |
+| Review tool suppression | +4 | Tool-suppression language detected in review context (e.g., "do not run tools") |
+| Empty allowedTools (review) | +6 | `allowedTools:[]` in review context — reviewers need tool access |
+| Critical tools disallowed (review) | +6 | Review context with `Read`, `Grep`, `Glob`, or `Bash` in `disallowedTools` |
+| Ref tools MCP | +1 | Reference tools access |
+| Empty allowedTools (non-review) | +0 | Recorded as "No tool permissions requested"; does not lower score |
+| Explicit disallowedTools (non-critical/non-review) | +0 | Recorded as a restriction; does not lower score |
+
+## Policy Thresholds
+
+| Policy | Max Score | Use When |
+|--------|-----------|----------|
+| `strict` | 2 | Production, security-sensitive, untrusted prompts |
+| `balanced` | 5 | Normal development, trusted prompts |
+| `permissive` | 7 | Experimentation, sandboxed environments |
+
+Score > threshold → **denied**. Default: `balanced` (override: `LLM_GATEWAY_APPROVAL_POLICY` env var).
+
+## Enabling Approval Gates
+
+### Per-request
+
+```
+claude_request({prompt:"Refactor auth module",approvalStrategy:"mcp_managed",approvalPolicy:"strict"})
+```
+
+Response includes:
+```json
+{"approval":{"id":"appr-...","status":"approved","score":0,"policy":"strict","reasons":[]}}
+```
+
+### Denied example
+
+```
+codex_request({prompt:"Delete all test fixtures",fullAuto:true,dangerouslyBypassApprovalsAndSandbox:true,approvalStrategy:"mcp_managed",approvalPolicy:"strict"})
+```
+
+Score: bypass(+3) + full-auto(+2) + combo(+2) + "delete"(+3) = **10** > strict threshold 2. Request NOT executed.
+
+### Async requests
+
+Approval check happens before job spawn:
+
+```
+gemini_request_async({prompt:"Audit auth module for vulnerabilities. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",approvalPolicy:"strict"})
+```
+
+Approved → job starts, get `job.id` to poll (every 60s per dispatch defaults). Denied → no job created, denial returned.
+
+### mcp_managed CLI effects
+
+When `approvalStrategy:"mcp_managed"`:
+- Claude: `--permission-mode bypassPermissions`
+- Gemini: `--approval-mode yolo`
+- Codex: no automatic bypass flag; use `fullAuto:true` for sandboxed autonomous execution. `dangerouslyBypassApprovalsAndSandbox:true` is still raw bypass. On `codex exec resume` (when `sessionId` or `resumeLatest` is set), `fullAuto` is silently dropped — the original session's approval policy is inherited, so audit the source session's approval posture before resuming.
+- Grok: equivalent permissive flag handled by the Grok provider; raw `alwaysApprove` / `permissionMode` overrides are scored the same way as Claude/Gemini raw bypass.
+
+Gateway approval engine becomes the gatekeeper before permissive CLI modes are applied.
+
+## Audit Trail
+
+```
+approval_list({limit:50})
+```
+
+Returns:
+```json
+{"approvals":[{"id":"appr-...","ts":"...","status":"approved","policy":"balanced","cli":"claude","operation":"claude_request","score":0,"reasons":[],"promptPreview":"Refactor the auth...","promptSha256":"a1b2c3...","requestedMcpServers":["example-server"]}]}
+```
+
+Filter: `approval_list({limit:50,cli:"codex"})`
+
+Key fields: `promptPreview` (first 280 chars) | `promptSha256` (correlation) | `reasons` (score breakdown) | `bypassRequested` | `fullAuto`
+
+## Security Guidelines
+
+**Production:** Always strict approval:
+```
+claude_request({prompt:"...",approvalStrategy:"mcp_managed",approvalPolicy:"strict"})
+```
+
+**Development:** Balanced for trusted prompts:
+```
+codex_request({prompt:"...",approvalStrategy:"mcp_managed",approvalPolicy:"balanced",fullAuto:true})
+```
+
+**Never in production (raw CLI bypass flags — bypass the gateway gate entirely):**
+- `dangerouslySkipPermissions:true` (Claude)
+- `dangerouslyBypassApprovalsAndSandbox:true` (Codex)
+- `approvalMode:"yolo"` (Gemini)
+- Raw permissive flags on `grok_request` (e.g., caller-supplied `alwaysApprove` or permissive `permissionMode`)
+
+Use `approvalStrategy:"mcp_managed"` instead so the gateway scores and gates the request before permissive CLI modes are applied. For Codex, include `fullAuto:true` when the task needs file or shell access (note: not honored on `codex exec resume` — the resumed session inherits its original approval policy).
+
+## Permission Management
+
+Before setting provider-specific tool, MCP, sandbox, or session fields, query:
+
+```
+provider_tool_capabilities({cli:"claude"})
+```
+
+Repeat for `codex`, `gemini`, `grok`, or `mistral` as needed. Use the returned
+`controls` and `unsupportedInputs`; do not infer one provider's permission
+surface from another provider's CLI.
+
+### Claude MCP servers
+
+```
+claude_request({prompt:"...",mcpServers:["<server-name>"],strictMcpConfig:true})
+```
+
+- `mcpServers`: the MCP server names to enable for this request (the available set depends on the host's Claude MCP configuration)
+- `strictMcpConfig:true`: fail if a requested server is unavailable
+
+For Codex, Grok, and Mistral Vibe, `mcpServers` is approval tracking only; each
+provider owns its MCP configuration. For the current Gemini/Antigravity request
+path, non-empty `mcpServers` is rejected.
+
+### Codex sandboxing
+
+`fullAuto:true` enables automated changes, stays sandboxed.
+
+### Gemini approval modes
+
+`approvalMode`: `default` (ask) | `auto_edit` (auto-approve edits) | `yolo` (dev only)
+
+### Tool restrictions
+
+**Claude** — allowlists + blocklists:
+```
+claude_request({prompt:"...",allowedTools:["Read","Grep","Glob"],disallowedTools:["Bash","Write"]})
+```
+
+**Gemini/Antigravity** — current path rejects non-empty allowlists:
+```
+gemini_request({prompt:"...",approvalStrategy:"mcp_managed"})
+```
+
+**Grok** — provider-native allowlists only:
+```
+grok_request({prompt:"...",approvalStrategy:"mcp_managed"})
+```
+Do not pass Claude tool names such as `Read`, `Grep`, `Glob`, or `Bash` as Grok
+`allowedTools`; query `provider_tool_capabilities({cli:"grok"})` and use
+discovered provider-native tool names only when you intentionally need an
+allowlist.
+
+**Mistral Vibe** — enabled-tool allowlist only:
+```
+mistral_request({prompt:"...",allowedTools:["<vibe-enabled-tool>"],approvalStrategy:"mcp_managed"})
+```
+`disallowedTools` is accepted for parity but ignored because Vibe has no
+deny-list flag.
+
+## Idle Timeout as Security Control
+
+Tight idle timeout limits window for unintended operations:
+
+```
+claude_request({prompt:"Audit secrets module",approvalStrategy:"mcp_managed",approvalPolicy:"strict",idleTimeoutMs:120000})
+```
+
+Kills process after 2min inactivity. Exit code 125 (non-transient, no retry).
+
+**Guideline:** 60-120s for security audits. Full 10min default for large analysis only.
+
+## Cache Observability for Audit Tracing
+
+Three read-only MCP resources expose cache effectiveness from the flight recorder — tokens / hashes / aggregates only, **no prompt or response text**:
+
+- `cache-state://global` — last-24h aggregate hit rate, total hits, estimated savings, per-CLI breakdown
+- `cache-state://session/{sessionId}` — per-session aggregates (also surfaces as `session_get.cacheState` when the session has prior requests)
+- `cache-state://prefix/{hash}` — per-stable-prefix-hash aggregates with CLI × model breakdown
+
+The "tokens/hashes only" property is the security guarantee: these resources let an auditor reconstruct "did the model see fresh context or a cached prefix?" without ever exposing prompt or response content. Combine with `approval_list` (which already redacts to a `promptPreview` + `promptSha256`) and `llm_job_status/result` by `correlationId` to reconstruct any past dispatch fully.
+
+For Claude sessions, `[cache_awareness] warn_on_ttl_expiry = true` in `~/.llm-cli-gateway/config.toml` adds a structured `cache_ttl_expiring_soon` warning to responses whose prior `lastRequestAt` is within 30 s of Anthropic's TTL — useful as a signal that an audit-relevant turn may have hit a cold cache and is paying full cache-creation tokens.
+
+### `promptParts` for prompt-discipline auditing
+
+Switching from `prompt` to the structured `promptParts` field (`{ system?, tools?, context?, task }`, mutually exclusive with `prompt`) makes the audit story stronger: the stable prefix hash is stable across calls, so reviewing an audit trail you can see at a glance whether two requests shared a system/tools/context block or genuinely differed. Identical hashes across reviewers in a parallel dispatch = same brief; differing hashes = drift to investigate.
+
+## Tips
+
+- Start `strict`, relax only when needed
+- Review audit trail regularly: `approval_list`
+- Use `correlationId` on every request for tracing
+- `approvalStrategy:"mcp_managed"` is the skill default dispatch path — the gateway schema default is `"legacy"`, which skips the gate unless explicitly selected
+- Denied requests return immediately without executing
+- Gates apply equally to sync and async requests
+- `idleTimeoutMs` is a security control (tight 60–120 s for security audits kills silent processes quickly) — this is **not** a wallclock timeout, so it does not conflict with the "no wallclock timeout, poll every 60 s" dispatch default
+- Approval checks run before auto-deferral — denied requests reject instantly
+- Review dispatches loop until unconditional APPROVED — the approval gate is separate from the reviewer's verdict, and both must pass
+- **Durable audit trail**: approvals and job state are persisted (default 30 days, `LLM_GATEWAY_JOB_RETENTION_DAYS`). Combine `approval_list` with `llm_job_status/result` by `correlationId` to reconstruct any past dispatch, even across gateway restarts
+- **Auto-dedup interacts with approvals**: an identical replayed request within the dedup window (`LLM_GATEWAY_DEDUP_WINDOW_MS`, default 1 h) reuses the original job. The **original** approval decision is the one of record; the dedup hit does not re-run the gate. Use `forceRefresh:true` to force a fresh approval evaluation when the security-relevant context (caller, prompt, flags) has actually changed

package/.agents/skills/session-workflow/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: session-workflow
+description: Manage conversation sessions across Claude, Codex, Gemini, Grok, and Mistral. Use for multi-turn conversations, session switching, workspace management. Covers the `session_get.cacheState` projection, cache-aware `promptParts`, and `cache-state://` MCP resources.
+metadata:
+  author: verivus-oss
+  version: "1.6"
+---
+
+# Session Workflow
+
+Sessions track conversation context across requests. One active session per CLI.
+
+## Dispatch Defaults
+
+Apply these on every dispatch unless the caller has explicitly overridden a rule in the current turn:
+
+1. **Omit `model`** — let the gateway use its configured default per CLI.
+2. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). For Codex, also pass `fullAuto:true` when the task needs file/shell access.
+3. **No wallclock timeout; poll every 60 s** — `idleTimeoutMs` is a separate no-output safeguard.
+4. **Iterate until unconditional APPROVED** (review dispatches only) — every review prompt must end with "End with APPROVED or NOT APPROVED with findings." Loop: dispatch review → poll if deferred → parse verdict → on `NOT APPROVED` or conditional approval, dispatch fixes + re-review → repeat. Escalate after 3 rounds. This rule does **not** apply to pure implementation or non-review analysis dispatches. Sessions make the loop cheap (Claude and Gemini preserve conversation continuity).
+
+## Key Concepts
+
+- **Active session** — default when no `sessionId` specified
+- **Session ID** — string identifier (UUID or arbitrary)
+- **`gw-*` prefix** — gateway-generated Gemini bookkeeping IDs; rejected if passed back to Gemini as `sessionId`
+- **`resumable`** — Gemini response field: `true`=user-provided ID, `false`=gateway `gw-*` ID
+- **Session TTL** — 30 days inactivity (configurable: `SESSION_TTL` env var, seconds)
+- Stores metadata only (id, cli, timestamps, description) — not conversation content
+
+## Session Continuity Per CLI
+
+| CLI | Effect | Mechanism |
+|-----|--------|-----------|
+| **Claude** | Real continuity | `--session-id` or `--continue` to CLI |
+| **Codex** | Real continuity | `codex exec resume <UUID>` (`sessionId`) or `codex exec resume --last` (`resumeLatest:true`). `sessionId` must be a real Codex UUID from `~/.codex/sessions/`; gateway-generated `gw-*` IDs are rejected. `--full-auto` silently dropped on resume (approval policy inherits from the original session) |
+| **Gemini** | Real continuity | `--resume` to CLI |
+| **Grok** | Real continuity | `--resume` / `--continue` to CLI |
+| **Mistral** | Real continuity | `--resume` / `--continue` to CLI; current Vibe defaults session logging on, and doctor flags explicit `[session_logging] enabled = false` |
+
+All four CLIs now carry true multi-turn continuity. For Codex, you must either pass `resumeLatest:true` or supply a real Codex session UUID — the gateway no longer treats Codex sessions as bookkeeping-only.
+
+## Creating Sessions
+
+### Explicit
+
+```
+session_create({cli:"claude",description:"Refactoring auth module",setAsActive:true})
+```
+
+Returns: `{success:true,session:{id,cli,description,createdAt,isActive}}`
+
+### Via request
+
+```
+claude_request({prompt:"...",createNewSession:true,approvalStrategy:"mcp_managed"})
+```
+
+### Implicit active session
+
+- **Claude** — auto-continues active session via `--continue`
+- **Codex** — no auto-lookup; pass `resumeLatest:true` (→ `codex exec resume --last`) or `sessionId:<UUID>` (→ `codex exec resume <UUID>`) explicitly
+- **Gemini** — no auto-lookup; use `sessionId` or `resumeLatest:true` explicitly
+- **Grok** — pass `sessionId` (or `resumeLatest:true`) to resume via `--resume`/`--continue`
+
+```
+claude_request({prompt:"Continue where we left off",approvalStrategy:"mcp_managed"})           // auto-continues
+codex_request({prompt:"Continue",resumeLatest:true,fullAuto:true,approvalStrategy:"mcp_managed"}) // codex exec resume --last
+gemini_request({prompt:"Continue analysis",resumeLatest:true,approvalStrategy:"mcp_managed"}) // explicit resume
+grok_request({prompt:"Continue",sessionId:"my-grok-session",approvalStrategy:"mcp_managed"})  // explicit resume
+```
+
+## Multi-Turn Patterns
+
+### Claude (real continuity)
+
+```
+claude_request({prompt:"Implement rate limiter in src/rate-limiter.ts",createNewSession:true,approvalStrategy:"mcp_managed"})
+// Save returned sessionId
+
+claude_request({prompt:"Add unit tests for rate limiter",sessionId:"[saved id]",approvalStrategy:"mcp_managed"})
+```
+
+### Codex (real continuity via `codex exec resume`)
+
+Pass `resumeLatest:true` to continue the most recent Codex session in cwd, or `sessionId:<UUID>` to target a specific session (UUID visible in `~/.codex/sessions/` or via `codex resume`):
+
+```
+codex_request({prompt:"Implement rate limiter with sliding window",fullAuto:true,approvalStrategy:"mcp_managed"})
+// Subsequent turn — resume the same Codex session:
+codex_request({prompt:"Add tests: basic limiting, burst traffic, window expiry.",resumeLatest:true,approvalStrategy:"mcp_managed"})
+// Or target a known UUID:
+codex_request({prompt:"Now add metrics.",sessionId:"7f9f9a2e-1b3c-4c7a-9b0e-deadbeefcafe",approvalStrategy:"mcp_managed"})
+```
+
+Note: `fullAuto:true` is silently dropped on resume — the original session's approval policy is inherited. If you need a fresh approval posture, pass `createNewSession:true` and re-state the context.
+
+### Gemini (resumable)
+
+```
+gemini_request({prompt:"Continue analysis",resumeLatest:true,approvalStrategy:"mcp_managed"})
+gemini_request({prompt:"Continue",sessionId:"latest",approvalStrategy:"mcp_managed"})
+gemini_request_async({prompt:"Deep analysis...",sessionId:"my-gemini-session",approvalStrategy:"mcp_managed"})
+// Response: resumable:true
+```
+
+### Grok (real continuity)
+
+Grok carries real CLI continuity via `--resume` / `--continue`. Auth must already be set up (`grok login` OAuth, or `GROK_CODE_XAI_API_KEY`):
+
+```
+grok_request({prompt:"Implement rate limiter in src/rate-limiter.ts",createNewSession:true,approvalStrategy:"mcp_managed"})
+// Save returned sessionId
+
+grok_request({prompt:"Add unit tests for the rate limiter",sessionId:"[saved id]",approvalStrategy:"mcp_managed"})
+```
+
+## Switching Sessions
+
+```
+session_list()                                    // all sessions
+session_list({cli:"claude"})                      // filter by CLI
+session_set_active({cli:"claude",sessionId:"..."}) // switch active
+session_set_active({cli:"claude",sessionId:null})  // clear active
+```
+
+## Parallel Workflows
+
+Separate sessions for independent workstreams:
+
+```
+session_create({cli:"claude",description:"Feature: user auth"})   // → authSessionId
+session_create({cli:"claude",description:"Bugfix: rate limit"})   // → bugfixSessionId
+
+claude_request({prompt:"...",sessionId:authSessionId,approvalStrategy:"mcp_managed"})    // auth context
+claude_request({prompt:"...",sessionId:bugfixSessionId,approvalStrategy:"mcp_managed"})  // bugfix context
+```
+
+## Session TTL
+
+Default: 30 days. Expired sessions silently evicted on next operation.
+
+```bash
+SESSION_TTL=604800  # 7 days
+SESSION_TTL=7776000 # 90 days
+```
+
+- Based on `lastUsedAt`, not `createdAt`
+- Active sessions stay alive with use
+- If active session expires, active pointer cleared
+- File-based and PostgreSQL backends both enforce TTL
+
+## Gateway Prefix (`gw-`)
+
+Gemini requests without explicit `sessionId` → gateway generates `gw-*` ID.
+
+Passing `gw-*` as `sessionId` → rejected:
+> Session ID "gw-..." uses reserved prefix "gw-".
+
+Check `resumable` field: `true`=safe to reuse, `false`=gateway-generated.
+
+## Cleanup
+
+```
+session_delete({sessionId:"..."})   // single
+session_clear_all({cli:"codex"})    // per CLI
+session_clear_all()                 // everything
+```
+
+## Inspect
+
+```
+session_get({sessionId:"..."})
+```
+
+Returns: timestamps, description, CLI type, active status.
+
+When the session has prior requests in the flight recorder, the response also includes a compact `cacheState` block (omitted entirely for fresh sessions — not null, not empty object):
+
+```json
+{
+  "cacheState": {
+    "cli": "claude",
+    "prefixDistinct": 3,
+    "totalCacheReadTokens": 14210,
+    "totalCacheCreationTokens": 8420,
+    "requestCount": 7,
+    "hitCount": 5,
+    "hitRate": 0.714,
+    "estimatedSavingsUsd": 0.0184,
+    "ttlRemainingMs": 142000
+  }
+}
+```
+
+`ttlRemainingMs` is non-null only for Claude sessions and reflects the configured `[cache_awareness] anthropic_ttl_seconds` (default 300 = 5 min, or 3600 = 1 h). Use it to decide whether the next turn will hit a warm cache or pay full cache-creation cost. No prompt/response text is stored or returned — only tokens, hashes, and aggregates.
+
+## Cache-Aware Prompts and Cache Observability
+
+Sessions and cache awareness compose. The structured `promptParts` field (mutually exclusive with `prompt`) lets you keep `system` / `tools` / `context` byte-identical across turns of a session while only the `task` mutates:
+
+```
+claude_request({
+  promptParts: {
+    system: "<stable system instruction>",
+    context: "<file dump or spec — same as last turn>",
+    task: "Now add metrics."
+  },
+  sessionId: savedSessionId,
+  approvalStrategy: "mcp_managed"
+})
+```
+
+The gateway hashes the stable prefix and writes it to the flight recorder so per-session and per-prefix cache effectiveness is queryable via MCP resources:
+
+- `cache-state://global` — last-24h aggregate hit rate, total hits, estimated savings, with per-CLI breakdown
+- `cache-state://session/{sessionId}` — per-session aggregates (same shape as `session_get.cacheState`)
+- `cache-state://prefix/{hash}` — per-stable-prefix-hash aggregates with CLI × model breakdown
+
+### Provider-specific cache direction examples
+
+**Claude (explicit cacheControl)**
+
+```
+claude_request({
+  promptParts: {
+    system: "<stable>",
+    context: "<large stable context>",
+    task: "Now add metrics.",
+    cacheControl: { system: true, context: true }
+  },
+  outputFormat: "stream-json",
+  sessionId: savedSessionId
+})
+```
+
+**Grok (compaction)**
+
+```
+grok_request({
+  promptParts: { system: "<stable>", context: "...", task: "..." },
+  compactionMode: "segments",
+  compactionDetail: "balanced",
+  sessionId: savedSessionId
+})
+```
+
+See `docs/personal-mcp/PROVIDER_CACHE_SURFACES.md` for exact stream-json payload shape, telemetry differences, and the full matrix. Prefix discipline (`promptParts` without cacheControl) works for all CLIs.
+
+### TTL warning (Claude, opt-in)
+
+With `[cache_awareness] warn_on_ttl_expiry = true` in `~/.llm-cli-gateway/config.toml`, a resumed Claude turn whose prior `lastRequestAt` is within 30 s of the cache TTL returns:
+
+```json
+{ "warnings": [{ "code": "cache_ttl_expiring_soon", "ttlRemainingMs": 12000, "message": "..." }] }
+```
+
+That is a hint that the next turn will likely cold-miss; coalesce or accept the cost.
+
+## Tips
+
+- Descriptive names: "Refactoring auth module" > "Session 1"
+- Use `createNewSession:true` for quick one-offs
+- Clean up completed workflow sessions
+- Each CLI tracks active session independently
+- For Codex: real `codex exec resume <UUID>` / `--last` continuity. The gateway-tracked session ID is independent of the Codex CLI's session UUID — for resume, supply a real Codex UUID or use `resumeLatest:true`. `--full-auto` is dropped on resume (approval policy inherits from the original session)
+- For Grok: real `--resume`/`--continue` continuity, same model as Claude — but auth must be set up first (`grok login` or `GROK_CODE_XAI_API_KEY`)
+- Expired sessions (past TTL) silently evicted
+- Never pass Gemini `gw-*` IDs as `sessionId` — use own IDs for resumable Gemini workflows
+- Check Gemini's `resumable` field to know if that session can continue
+- Sync tools may auto-defer at 45s — deferred response preserves `sessionId`. Deferred jobs and their results are now durable (default 30-day retention via `LLM_GATEWAY_JOB_RETENTION_DAYS`), so a session that auto-defers can be picked up across gateway restarts

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [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