llm-cli-gateway 2.6.0 → 2.6.3

package/CHANGELOG.md

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

@@ -761,6 +761,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 }),
     };
@@ -1105,7 +1106,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 +1152,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 +1176,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 +1203,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 +1223,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 +1312,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         stablePrefixTokens,
         stdinPayload,
         cacheControlBlocks,
+        cacheControlTtlSeconds,
         warnings: warnings.length > 0 ? warnings : undefined,
     };
 }
@@ -3383,6 +3405,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 {

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",

package/dist/upstream-contracts.js

@@ -36,8 +36,20 @@ function subcommand(commandPath, summary, risk, flags = [], options = {}) {
         tokenCost: options.tokenCost ?? "small",
         summary,
         conformanceFixtures: options.fixtures ?? [],
+        acknowledgedUpstreamFlags: options.acknowledgedUpstreamFlags ?? [],
     };
 }
+function acknowledgeSubcommandFlags(subcommands, flags) {
+    return Object.fromEntries(Object.entries(subcommands).map(([name, contract]) => [
+        name,
+        {
+            ...contract,
+            acknowledgedUpstreamFlags: Array.from(new Set([...(contract.acknowledgedUpstreamFlags ?? []), ...flags])),
+            children: acknowledgeSubcommandFlags(contract.children ?? {}, flags),
+        },
+    ]));
+}
+const GROK_DEBUG_HELP_FLAGS = ["--debug", "--debug-file"];
 export const UPSTREAM_CLI_CONTRACTS = {
     claude: {
         cli: "claude",
@@ -903,7 +915,7 @@ export const UPSTREAM_CLI_CONTRACTS = {
             watchCategories: ["flags", "permission-modes", "session-resume", "sandbox", "output-formats"],
         },
         helpArgs: [["--help"]],
-        subcommands: {
+        subcommands: acknowledgeSubcommandFlags({
             agent: subcommand(["agent"], "Run Grok agent service helpers.", "executes_agent", [
                 "--agent-profile",
                 "--always-approve",
@@ -935,6 +947,7 @@ export const UPSTREAM_CLI_CONTRACTS = {
                         "--leader-socket",
                         "--no-auto-update",
                         "--no-exit-on-disconnect",
+                        "--relay-on-demand",
                     ], { exposure: "not_exposed" }),
                 },
             }),
@@ -981,11 +994,10 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 "--version",
             ], { exposure: "not_exposed" }),
             version: subcommand(["version"], "Print Grok version information.", "read_only", ["--json", "--leader-socket"], { tier: "diagnostic" }),
-            worktree: subcommand(["worktree"], "Manage Grok worktree sessions.", "writes_local_config", [
-                "--leader-socket",
-            ]),
-        },
+            worktree: subcommand(["worktree"], "Manage Grok worktree sessions.", "writes_local_config", ["--leader-socket"]),
+        }, GROK_DEBUG_HELP_FLAGS),
         maxPositionals: 0,
+        acknowledgedUpstreamFlags: GROK_DEBUG_HELP_FLAGS,
         mcpTools: ["grok_request", "grok_request_async"],
         mcpParameters: [
             "prompt",

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.6.0",
+  "version": "2.6.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.6.0",
+      "version": "2.6.3",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.6.0",
+  "version": "2.6.3",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "MCP server providing unified access to Claude Code, Codex, Gemini, Grok, and Mistral Vibe CLIs with session management, retry logic, async job orchestration, durable job results, and cross-LLM validation.",
   "license": "MIT",