llm-cli-gateway 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to the llm-cli-gateway project.
 
 ## Unreleased
 
+## [2.7.0] - 2026-06-12: Provider capability inventory
+
+### Added
+
+- Added `provider_tool_capabilities`, a read-only MCP tool that reports the
+  gateway request tools, provider kind, supported controls, feature flags,
+  model info, config-surface hints, local skill discovery, provider-native tool
+  discovery, unsupported/degraded inputs, warnings, and cache metadata for
+  Claude Code, Codex CLI, Gemini/Antigravity (`agy`), Grok CLI, optional
+  `grok_api`, and Mistral Vibe.
+- Added `provider-tools://catalog` and per-provider resources
+  `provider-tools://claude`, `provider-tools://codex`,
+  `provider-tools://gemini`, `provider-tools://grok`,
+  `provider-tools://grok_api`, and `provider-tools://mistral` for clients that
+  prefer resource discovery over tool calls.
+- Added `doctor --json` `provider_capabilities`, a compact setup-assistant
+  summary with schema version, resource URIs, per-provider request tools,
+  supported feature names, unsupported input names, config-surface counts,
+  discovered skill/tool counts, and warnings without raw local paths.
+- Added bounded, redacted local skill/config discovery for provider capability
+  reporting. Grok local/bundled skills can now surface provider-native tools
+  such as Imagine `image_gen`, `image_edit`, `image_to_video`, and
+  `reference_to_video` when present, while keeping execution routed through
+  `grok_request`.
+
+### Changed
+
+- Updated agent skills so LLM agents have provider-specific gateway usage
+  guidance for Claude, Codex, Gemini/Antigravity (`agy`), Grok, and Mistral
+  Vibe, and so orchestration skills check `provider_tool_capabilities` before
+  assuming tool allowlists, MCP-server semantics, sessions, output formats, or
+  provider-native tools.
+- Updated setup assistant guidance and `setup/status.schema.json` so install
+  agents treat `doctor.provider_capabilities` as the compact source of truth
+  for outbound provider capability claims.
+- Documented the intentionally published prod-only `npm-shrinkwrap.json` in
+  README and `socket.yml`, including the release audit and packed-consumer
+  checks that bound the shrinkwrap and shell-spawn Socket alerts.
+
+### Fixed
+
+- Corrected stale internal skill guidance that described Codex continuity as
+  bookkeeping-only, described Gemini allowlists/MCP allowlists as pass-through,
+  omitted Mistral async from async orchestration docs, or encouraged copying
+  Claude tool names into other provider allowlists.
+
+## [2.6.3] - 2026-06-12: Claude cache-control veracity and Grok 0.2.50
+
+### Fixed
+
+- Claude `promptParts` cache-control stream-json payloads now preserve the
+  exact assembled prompt bytes: concatenating emitted Claude content blocks
+  matches `assemble(parts).text`, including stable-part separators.
+- Empty or omitted stable-part `cacheControl` markers are now treated as a
+  no-op: they do not force the Claude stdin cache-control path, do not suppress
+  opt-in auto-emission, and return a `cache_control_noop` warning.
+- Flight-recorder rows now persist the actual emitted
+  `cache_control_ttl_seconds`, and cache-state TTL reporting prefers that row
+  value while retaining a 1-hour compatibility fallback for legacy
+  `cache_control_blocks` rows.
+- Provider cache docs now describe the verified Claude stream-json
+  `cache_control` path and the remaining hidden-request limits accurately,
+  including async flight-recorder metadata and slice κ TTL handoff.
+
+### Upstream provider maintenance
+
+- Grok Build stable `0.2.50` contract refresh: `--debug` and `--debug-file`
+  are acknowledged as upstream-only help/probe flags at top level and across
+  subcommands without becoming gateway argv allowlist flags.
+- Declared `grok agent leader --relay-on-demand` on the non-exposed agent
+  leader subcommand, refreshed `docs/upstream/snapshots/grok.json`, and added
+  the 2026-06-12 Grok upstream scan report.
+
 ## [2.6.0] - 2026-06-12: Gemini provider on Google Antigravity CLI
 
 ### Changed

package/README.md

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

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

@@ -11,6 +11,7 @@ export interface AsyncJobFlightRecorderEntry {
     stablePrefixHash?: string;
     stablePrefixTokens?: number;
     cacheControlBlocks?: number;
+    cacheControlTtlSeconds?: number;
 }
 export type AsyncJobUsageExtractor = (stdout: string) => {
     inputTokens?: number;

package/dist/async-job-manager.js

@@ -515,6 +515,7 @@ export class AsyncJobManager {
                     stablePrefixHash: flightRecorderEntry.stablePrefixHash,
                     stablePrefixTokens: flightRecorderEntry.stablePrefixTokens,
                     cacheControlBlocks: flightRecorderEntry.cacheControlBlocks,
+                    cacheControlTtlSeconds: flightRecorderEntry.cacheControlTtlSeconds,
                 });
             }
             catch (err) {

package/dist/cache-stats.d.ts

@@ -12,6 +12,8 @@ export interface SessionCacheStats {
     lastRequestAt: string | null;
     estimatedSavingsUsd: number;
     ttlRemainingMs: number | null;
+    latestCacheControlBlocks?: number | null;
+    latestCacheControlTtlSeconds?: number | null;
 }
 export interface PrefixCacheStats {
     stablePrefixHash: string;

package/dist/cache-stats.js

@@ -10,7 +10,9 @@ export function computeSessionCacheStats(db, sessionId) {
             COALESCE(cache_read_tokens, 0) AS cache_read_tokens,
             COALESCE(cache_creation_tokens, 0) AS cache_creation_tokens,
             stable_prefix_hash,
-            datetime_utc
+            datetime_utc,
+            cache_control_blocks,
+            cache_control_ttl_seconds
      FROM requests
      WHERE session_id = ?
      ORDER BY datetime_utc DESC`, sessionId);
@@ -51,6 +53,8 @@ export function computeSessionCacheStats(db, sessionId) {
         lastRequestAt: lastAt,
         estimatedSavingsUsd,
         ttlRemainingMs: null,
+        latestCacheControlBlocks: rows.length > 0 ? (rows[0].cache_control_blocks ?? null) : null,
+        latestCacheControlTtlSeconds: rows.length > 0 ? (rows[0].cache_control_ttl_seconds ?? null) : null,
     };
 }
 export function computeTtlRemaining(stats, cli, ttlPolicy) {
@@ -63,7 +67,14 @@ export function computeTtlRemaining(stats, cli, ttlPolicy) {
     if (!Number.isFinite(lastWriteMs))
         return null;
     const elapsedMs = nowMs - lastWriteMs;
-    const ttlMs = ttlPolicy.anthropicTtlSeconds * 1000;
+    const isExplicit = typeof stats.latestCacheControlBlocks === "number" && stats.latestCacheControlBlocks > 0;
+    const recordedTtlSeconds = typeof stats.latestCacheControlTtlSeconds === "number" &&
+        Number.isFinite(stats.latestCacheControlTtlSeconds) &&
+        stats.latestCacheControlTtlSeconds > 0
+        ? stats.latestCacheControlTtlSeconds
+        : null;
+    const ttlSeconds = recordedTtlSeconds ?? (isExplicit ? 3600 : ttlPolicy.anthropicTtlSeconds);
+    const ttlMs = ttlSeconds * 1000;
     return Math.max(0, ttlMs - elapsedMs);
 }
 export function computePrefixCacheStats(db, stablePrefixHash) {
@@ -128,7 +139,8 @@ export function computeGlobalCacheStats(db, opts = {}) {
               COALESCE(cache_creation_tokens, 0) AS cache_creation_tokens,
               stable_prefix_hash,
               datetime_utc,
-              cache_control_blocks
+              cache_control_blocks,
+              cache_control_ttl_seconds
        FROM requests
        WHERE datetime_utc >= ?`
         : `SELECT cli, model,
@@ -136,7 +148,8 @@ export function computeGlobalCacheStats(db, opts = {}) {
               COALESCE(cache_creation_tokens, 0) AS cache_creation_tokens,
               stable_prefix_hash,
               datetime_utc,
-              cache_control_blocks
+              cache_control_blocks,
+              cache_control_ttl_seconds
        FROM requests`;
     const rows = sinceIso ? db.queryRequests(sql, sinceIso) : db.queryRequests(sql);
     const perCliMap = new Map();

package/dist/doctor.d.ts

@@ -2,6 +2,7 @@ import { type EndpointExposureReport } from "./endpoint-exposure.js";
 import { type ProviderLoginStatus } from "./provider-status.js";
 import type { FlightRecorderQuery } from "./flight-recorder.js";
 import { type CacheAwarenessConfig } from "./config.js";
+import { type ProviderCapabilityId, type ProviderKind } from "./provider-tool-capabilities.js";
 export type CliType = "claude" | "codex" | "gemini" | "grok" | "mistral";
 export interface CacheAwarenessReport {
     enabled_features: Array<"anthropic_cache_control" | "ttl_warnings">;
@@ -17,6 +18,26 @@ export interface CacheAwarenessReport {
         total_cache_read_tokens: number;
     }>>;
 }
+export interface ProviderCapabilitySummaryReport {
+    schema_version: "provider-tool-capabilities.v2";
+    tool: "provider_tool_capabilities";
+    resources: {
+        catalog: "provider-tools://catalog";
+        providers: Record<ProviderCapabilityId, string>;
+    };
+    cache_ttl_ms: number;
+    providers: Record<ProviderCapabilityId, {
+        provider_kind: ProviderKind;
+        cli_available: boolean;
+        gateway_request_tools: string[];
+        supported_features: string[];
+        unsupported_inputs: string[];
+        config_surface_count: number;
+        discovered_skill_count: number;
+        discovered_provider_tool_count: number;
+        warnings: string[];
+    }>;
+}
 export interface VibeSessionLoggingStatus {
     config_path: string;
     config_present: boolean;
@@ -116,6 +137,7 @@ export interface DoctorReport {
         vibe_session_logging: VibeSessionLoggingStatus;
     };
     cache_awareness: CacheAwarenessReport;
+    provider_capabilities: ProviderCapabilitySummaryReport;
     upstream: {
         note: string;
         recommendation: string;

package/dist/doctor.js

@@ -11,6 +11,7 @@ import { loadWorkspaceRegistry } from "./workspace-registry.js";
 import { computeGlobalCacheStats } from "./cache-stats.js";
 import { FlightRecorder, resolveFlightRecorderDbPath } from "./flight-recorder.js";
 import { buildUpstreamContractReport } from "./upstream-contracts.js";
+import { getProviderToolCapabilities, providerCapabilityIds, } from "./provider-tool-capabilities.js";
 export function checkVibeSessionLogging(home = homedir()) {
     const configPath = join(home, ".vibe", "config.toml");
     if (!existsSync(configPath)) {
@@ -226,6 +227,49 @@ function buildCacheAwarenessReport(opts) {
         per_cli: perCli,
     };
 }
+function buildProviderCapabilitySummary(providerStatuses) {
+    const capabilities = getProviderToolCapabilities({
+        includeSkills: true,
+        includeProviderTools: true,
+        includeUnsupported: true,
+        includePaths: false,
+    });
+    const providers = Object.fromEntries(providerCapabilityIds().map(provider => {
+        const capability = capabilities[provider];
+        if (!capability) {
+            throw new Error(`Missing provider capability record for ${provider}`);
+        }
+        const cliAvailable = provider === "grok_api"
+            ? capability.gatewayRequestTools.includes("grok_api_request")
+            : providerStatuses[provider].installed;
+        return [
+            provider,
+            {
+                provider_kind: capability.providerKind,
+                cli_available: cliAvailable,
+                gateway_request_tools: capability.gatewayRequestTools,
+                supported_features: Object.entries(capability.features)
+                    .filter(([, feature]) => feature.supported)
+                    .map(([name]) => name),
+                unsupported_inputs: capability.unsupportedInputs.map(input => input.input),
+                config_surface_count: capability.configSurfaces.length,
+                discovered_skill_count: capability.discoveredSkills.length,
+                discovered_provider_tool_count: capability.discoveredProviderTools.length,
+                warnings: capability.warnings,
+            },
+        ];
+    }));
+    return {
+        schema_version: "provider-tool-capabilities.v2",
+        tool: "provider_tool_capabilities",
+        resources: {
+            catalog: "provider-tools://catalog",
+            providers: Object.fromEntries(providerCapabilityIds().map(provider => [provider, `provider-tools://${provider}`])),
+        },
+        cache_ttl_ms: 60_000,
+        providers,
+    };
+}
 export function createDoctorReport(envOrOptions = process.env) {
     const opts = isCreateDoctorReportOptions(envOrOptions)
         ? envOrOptions
@@ -316,6 +360,7 @@ export function createDoctorReport(envOrOptions = process.env) {
         endpoint_exposure: endpointExposure,
         client_config: clientConfigStatus(),
         cache_awareness: buildCacheAwarenessReport(opts),
+        provider_capabilities: buildProviderCapabilitySummary(providerStatuses),
         upstream,
         next_actions: [],
     };

package/dist/flight-recorder.d.ts

@@ -10,6 +10,7 @@ export interface FlightLogStart {
     stablePrefixHash?: string;
     stablePrefixTokens?: number;
     cacheControlBlocks?: number;
+    cacheControlTtlSeconds?: number;
 }
 export interface FlightLogResult {
     response: string;

package/dist/flight-recorder.js

@@ -31,6 +31,13 @@ function ensureCacheControlBlocksColumn(db) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_control_blocks INTEGER");
     }
 }
+function ensureCacheControlTtlSecondsColumn(db) {
+    const rows = db.prepare("PRAGMA table_info(requests)").all();
+    const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
+    if (!names.has("cache_control_ttl_seconds")) {
+        db.exec("ALTER TABLE requests ADD COLUMN cache_control_ttl_seconds INTEGER");
+    }
+}
 export function resolveFlightRecorderDbPath() {
     const configured = process.env.LLM_GATEWAY_LOGS_DB;
     if (configured !== undefined) {
@@ -144,6 +151,10 @@ export class FlightRecorder {
         this.db
             .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(4, ?)")
             .run(new Date().toISOString());
+        ensureCacheControlTtlSecondsColumn(this.db);
+        this.db
+            .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(5, ?)")
+            .run(new Date().toISOString());
         if (process.platform !== "win32") {
             try {
                 chmodSync(dbPath, 0o600);
@@ -154,10 +165,10 @@ export class FlightRecorder {
         const insertRequest = this.db.prepare(`
       INSERT INTO requests (id, cli, model, prompt, system, session_id, datetime_utc,
                             stable_prefix_hash, stable_prefix_tokens,
-                            cache_control_blocks)
+                            cache_control_blocks, cache_control_ttl_seconds)
       VALUES (@id, @cli, @model, @prompt, @system, @session_id, @datetime_utc,
               @stable_prefix_hash, @stable_prefix_tokens,
-              @cache_control_blocks)
+              @cache_control_blocks, @cache_control_ttl_seconds)
     `);
         const insertMetadata = this.db.prepare(`
       INSERT INTO gateway_metadata (request_id, async_job_id, status)
@@ -175,6 +186,7 @@ export class FlightRecorder {
                 stable_prefix_hash: entry.stablePrefixHash ?? null,
                 stable_prefix_tokens: entry.stablePrefixTokens ?? null,
                 cache_control_blocks: entry.cacheControlBlocks ?? null,
+                cache_control_ttl_seconds: entry.cacheControlTtlSeconds ?? null,
             });
             insertMetadata.run({
                 request_id: entry.correlationId,

package/dist/index.d.ts

@@ -134,6 +134,7 @@ interface CliRequestPrep {
     stablePrefixTokens: number | null;
     stdinPayload?: string;
     cacheControlBlocks?: number;
+    cacheControlTtlSeconds?: number;
     warnings?: WarningEntry[];
 }
 export declare function prepareClaudeRequest(params: {

package/dist/index.js

@@ -22,6 +22,7 @@ import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvid
 import { createXaiResponse, XaiApiError, } from "./xai-api-provider.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
+import { getProviderToolCapabilities } from "./provider-tool-capabilities.js";
 import { AsyncJobManager, } from "./async-job-manager.js";
 import { createJobStore } from "./job-store.js";
 import { ApprovalManager } from "./approval-manager.js";
@@ -761,6 +762,7 @@ function buildAsyncFlightRecorderHandoff(cliName, prep, sessionId, outputFormat)
             stablePrefixHash: prep.stablePrefixHash ?? undefined,
             stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
             cacheControlBlocks: prep.cacheControlBlocks,
+            cacheControlTtlSeconds: prep.cacheControlTtlSeconds,
         },
         extractUsage: (stdout) => extractUsageAndCost(cli, stdout, fmt, { sessionId: sid, home }),
     };
@@ -1048,6 +1050,27 @@ function registerBaseResources(server, runtime) {
         const contents = await runtime.resourceProvider.readResource(uri.href);
         return { contents: contents ? [contents] : [] };
     });
+    server.registerResource("provider-tools-catalog", "provider-tools://catalog", {
+        title: "Provider Tool Capabilities Catalog",
+        description: "Read-only catalog of gateway tool controls and discovered provider skills",
+        mimeType: "application/json",
+    }, async (uri) => {
+        runtime.logger.debug("Reading provider-tools://catalog resource");
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
+    server.registerResource("provider-tools", new ResourceTemplate("provider-tools://{provider}", { list: undefined }), {
+        title: "Provider Tool Capabilities",
+        description: "Read-only gateway tool controls and discovered local skills for one provider CLI",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const provider = Array.isArray(variables.provider)
+            ? variables.provider[0]
+            : variables.provider;
+        runtime.logger.debug(`Reading provider-tools://${provider}`);
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
 }
 function resolvePromptOrPartsForPrep(args) {
     const hasPrompt = typeof args.prompt === "string" && args.prompt.length > 0;
@@ -1105,7 +1128,18 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
     const ccEarly = params.promptParts?.cacheControl;
     const cacheControlRequestedEarly = !!(ccEarly &&
         (ccEarly.system || ccEarly.tools || ccEarly.context));
-    if (params.optimizePrompt && cacheControlRequestedEarly) {
+    const explicitCacheControlBlockCount = params.promptParts && ccEarly
+        ? (ccEarly.system && params.promptParts.system && params.promptParts.system.length > 0
+            ? 1
+            : 0) +
+            (ccEarly.tools && params.promptParts.tools && params.promptParts.tools.length > 0 ? 1 : 0) +
+            (ccEarly.context && params.promptParts.context && params.promptParts.context.length > 0
+                ? 1
+                : 0)
+        : 0;
+    const effectiveExplicitCacheControl = explicitCacheControlBlockCount > 0;
+    const cacheControlNoop = cacheControlRequestedEarly && !effectiveExplicitCacheControl;
+    if (params.optimizePrompt && effectiveExplicitCacheControl) {
         return createErrorResponse(params.operation, 1, "", corrId, new Error("optimizePrompt is incompatible with promptParts.cacheControl (slice κ): optimization rewrites the assembled prompt text the flight recorder logs, while the cache_control payload is built from raw promptParts; the two would desync and break Anthropic prefix-cache reuse. Disable optimizePrompt when opting into cacheControl."));
     }
     let effectivePrompt = assembledPrompt;
@@ -1140,7 +1174,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         }
     }
     let autoEmittedCacheControlBlock = null;
-    if (!cacheControlRequestedEarly &&
+    if (!effectiveExplicitCacheControl &&
         runtime.cacheAwareness.emitAnthropicCacheControl &&
         !params.optimizePrompt &&
         params.outputFormat === "stream-json" &&
@@ -1164,7 +1198,14 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         }
     }
     const warnings = [];
-    if (!cacheControlRequestedEarly &&
+    if (cacheControlNoop) {
+        warnings.push({
+            code: "cache_control_noop",
+            message: "promptParts.cacheControl only marked empty or omitted stable parts; no cache_control breakpoint will be emitted from the explicit marker.",
+            reason: "cacheControl marker did not match a non-empty stable block",
+        });
+    }
+    if (!effectiveExplicitCacheControl &&
         autoEmittedCacheControlBlock === null &&
         params.promptParts &&
         stablePrefixTokens !== null) {
@@ -1184,9 +1225,10 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
             });
         }
     }
-    const cacheControlRequested = cacheControlRequestedEarly || autoEmittedCacheControlBlock !== null;
+    const cacheControlRequested = effectiveExplicitCacheControl || autoEmittedCacheControlBlock !== null;
     let stdinPayload;
     let cacheControlBlocks;
+    let cacheControlTtlSeconds;
     if (cacheControlRequested) {
         if (params.outputFormat !== "stream-json") {
             return createErrorResponse(params.operation, 1, "", corrId, new Error("promptParts.cacheControl requires outputFormat: 'stream-json' (slice κ pipes the cache_control blocks over --input-format stream-json; text/json output formats cannot carry the required NDJSON usage events)."));
@@ -1203,6 +1245,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         const built = assembleClaudeCacheBlocks(effectiveParts);
         stdinPayload = `${JSON.stringify(built.payload)}\n`;
         cacheControlBlocks = built.markedBlockCount;
+        cacheControlTtlSeconds = built.markedBlockCount > 0 ? 3600 : undefined;
     }
     const args = cacheControlRequested
         ? [
@@ -1291,6 +1334,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         stablePrefixTokens,
         stdinPayload,
         cacheControlBlocks,
+        cacheControlTtlSeconds,
         warnings: warnings.length > 0 ? warnings : undefined,
     };
 }
@@ -3383,6 +3427,7 @@ export function createGatewayServer(deps = {}) {
             stablePrefixHash: prep.stablePrefixHash ?? undefined,
             stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
             cacheControlBlocks: prep.cacheControlBlocks,
+            cacheControlTtlSeconds: prep.cacheControlTtlSeconds,
         }, runtime);
         logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prep.effectivePrompt.length}, sessionId=${effectiveSessionId}, cacheControlBlocks=${prep.cacheControlBlocks ?? 0}`);
         try {
@@ -5392,6 +5437,44 @@ export function createGatewayServer(deps = {}) {
         const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
+    server.tool("provider_tool_capabilities", "Report provider tool/feature capabilities and discovered local skill/tool integrations for claude|codex|gemini|grok|grok_api|mistral.", {
+        cli: z
+            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "grok_api", "mistral"]).optional())
+            .describe("Provider filter (claude|codex|gemini|grok|grok_api|mistral)"),
+        includeSkills: z
+            .boolean()
+            .default(true)
+            .describe("Include bounded local skill discovery results"),
+        includeProviderTools: z
+            .boolean()
+            .default(true)
+            .describe("Include provider-native tools extracted from local skills"),
+        includeUnsupported: z
+            .boolean()
+            .default(true)
+            .describe("Include explicit unsupported/degraded input records"),
+        includePaths: z
+            .boolean()
+            .default(false)
+            .describe("Include raw local filesystem paths in discovery output"),
+        refresh: z.boolean().default(false).describe("Bypass the short-lived capability cache"),
+    }, {
+        title: "Provider tool capabilities",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ cli, includeSkills, includeProviderTools, includeUnsupported, includePaths, refresh, }) => {
+        const capabilities = getProviderToolCapabilities({
+            cli,
+            includeSkills,
+            includeProviderTools,
+            includeUnsupported,
+            includePaths,
+            refresh,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(capabilities, null, 2) }] };
+    });
     server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all five providers or one.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral"]).optional())

package/dist/prompt-parts.js

@@ -60,14 +60,17 @@ export function assembleClaudeCacheBlocks(parts) {
     for (const [name, value] of stableEntries) {
         if (value === undefined || value.length === 0)
             continue;
-        const block = { type: "text", text: value };
+        const block = {
+            type: "text",
+            text: blocks.length > 0 ? `${SEPARATOR}${value}` : value,
+        };
         if (cc[name]) {
             block.cache_control = { type: "ephemeral", ttl: "1h" };
             markedBlockCount += 1;
         }
         blocks.push(block);
     }
-    blocks.push({ type: "text", text: parts.task });
+    blocks.push({ type: "text", text: blocks.length > 0 ? `${SEPARATOR}${parts.task}` : parts.task });
     return {
         payload: {
             type: "user",