llm-cli-gateway 1.5.34 → 1.6.0

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { randomUUID } from "crypto";
 import { existsSync, readFileSync, readdirSync, renameSync, unlinkSync } from "fs";
@@ -14,7 +14,7 @@ import { createSessionManager } from "./session-manager.js";
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, } from "./config.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { AsyncJobManager } from "./async-job-manager.js";
@@ -24,6 +24,8 @@ import { checkReviewIntegrity } from "./review-integrity.js";
 import { buildClaudeMcpConfig, CLAUDE_MCP_SERVER_NAMES, } from "./claude-mcp-config.js";
 import { resolveGrokSessionArgs, resolveMistralSessionArgs, resolveCodexSessionArgs, sanitizeCliArgValues, prepareMistralRequest as buildMistralCliInvocation, MISTRAL_AGENT_MODES, GATEWAY_SESSION_PREFIX, resolveClaudePermissionFlags, resolveCodexSandboxFlags, CLAUDE_PERMISSION_MODES, GEMINI_APPROVAL_MODES, CODEX_SANDBOX_MODES, CODEX_ASK_FOR_APPROVAL_MODES, CLAUDE_EFFORT_LEVELS, prepareClaudeHighImpactFlags, validateClaudeAgentsMap, prepareCodexHighImpactFlags, prepareCodexForkRequest, CODEX_CONFIG_OVERRIDES_SCHEMA, prepareGeminiHighImpactFlags, prependGeminiAttachments, resolveGeminiSessionPlan, GEMINI_HIGH_IMPACT_PARAMS_SCHEMA, } from "./request-helpers.js";
 import { createFlightRecorder } from "./flight-recorder.js";
+import { resolvePromptInput, PromptPartsSchema } from "./prompt-parts.js";
+import { computeSessionCacheStats, computeTtlRemaining } from "./cache-stats.js";
 import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 import { startHttpGateway } from "./http-transport.js";
 import { printDoctorJson } from "./doctor.js";
@@ -108,6 +110,22 @@ const SYNC_DEADLINE_MS = (() => {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const SKILLS_DIR = join(__dirname, "..", ".agents", "skills");
+function packageVersion() {
+    const candidates = [
+        join(__dirname, "..", "package.json"),
+        join(__dirname, "..", "..", "package.json"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+            return parsed.version || "unknown";
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return "unknown";
+}
 function loadSkills() {
     const skills = [];
     try {
@@ -158,29 +176,56 @@ let sessionManager;
 let db = null;
 const performanceMetrics = new PerformanceMetrics();
 let resourceProvider;
-const flightRecorder = createFlightRecorder(logger);
+let flightRecorder = null;
 // Resolved persistence config — single source of truth for the async-job backend.
 // Driven by ~/.llm-cli-gateway/config.toml (+ deprecated env-var overrides).
 // When backend = "none", the JobStore is null AND *_request_async tools are not
 // registered (see createGatewayServer), making silent in-memory loss
 // structurally impossible.
-const persistenceConfig = loadPersistenceConfig(logger);
-const jobStore = (() => {
+let persistenceConfig = null;
+let cacheAwarenessConfig = null;
+let jobStore = null;
+let jobStoreInitialized = false;
+let asyncJobManager = null;
+let approvalManager = null;
+function getFlightRecorder(runtimeLogger = logger) {
+    flightRecorder ??= createFlightRecorder(runtimeLogger);
+    return flightRecorder;
+}
+function getPersistenceConfig(runtimeLogger = logger) {
+    persistenceConfig ??= loadPersistenceConfig(runtimeLogger);
+    return persistenceConfig;
+}
+function getCacheAwarenessConfig(runtimeLogger = logger) {
+    cacheAwarenessConfig ??= loadCacheAwarenessConfig(runtimeLogger);
+    return cacheAwarenessConfig;
+}
+function getJobStore(runtimeLogger = logger) {
+    if (jobStoreInitialized)
+        return jobStore;
+    jobStoreInitialized = true;
     try {
-        return createJobStore(persistenceConfig, logger);
+        jobStore = createJobStore(getPersistenceConfig(runtimeLogger), runtimeLogger);
     }
     catch (err) {
-        logger.error("Failed to open durable job store; async tools will be unavailable", err);
-        return null;
+        runtimeLogger.error("Failed to open durable job store; async tools will be unavailable", err);
+        jobStore = null;
     }
-})();
-function newAsyncJobManager(metrics, runtimeLogger, store = jobStore) {
+    return jobStore;
+}
+function newAsyncJobManager(metrics, runtimeLogger, store = getJobStore(runtimeLogger)) {
     return new AsyncJobManager(runtimeLogger, (cli, durationMs, success) => {
         metrics.recordRequest(cli, durationMs, success);
     }, store);
 }
-const asyncJobManager = newAsyncJobManager(performanceMetrics, logger);
-const approvalManager = new ApprovalManager(undefined, logger);
+function getAsyncJobManager(runtimeLogger = logger) {
+    asyncJobManager ??= newAsyncJobManager(performanceMetrics, runtimeLogger);
+    return asyncJobManager;
+}
+function getApprovalManager(runtimeLogger = logger) {
+    approvalManager ??= new ApprovalManager(undefined, runtimeLogger);
+    return approvalManager;
+}
 const MCP_SERVER_ENUM = z.enum(CLAUDE_MCP_SERVER_NAMES);
 // U22: Session-provider enum extended to five providers. The storage layer's
 // CLI_TYPES already includes "mistral"; the MCP-tool layer mirrors that here so
@@ -199,22 +244,26 @@ function resolveGatewayServerRuntime(deps = {}, options = {}) {
             ? // Factory-created test/HTTP session servers must not mark another instance's
                 // durable jobs orphaned. Stdio startup injects the process-global manager.
                 newAsyncJobManager(runtimePerformanceMetrics, runtimeLogger, null)
-            : asyncJobManager);
+            : getAsyncJobManager(runtimeLogger));
     const runtimeApprovalManager = deps.approvalManager ??
-        (options.isolateState ? new ApprovalManager(undefined, runtimeLogger) : approvalManager);
+        (options.isolateState
+            ? new ApprovalManager(undefined, runtimeLogger)
+            : getApprovalManager(runtimeLogger));
+    const runtimeFlightRecorder = deps.flightRecorder ?? getFlightRecorder(runtimeLogger);
     return {
         sessionManager: runtimeSessionManager,
         resourceProvider: deps.resourceProvider ??
             (options.isolateState
-                ? new ResourceProvider(runtimeSessionManager, runtimePerformanceMetrics)
+                ? new ResourceProvider(runtimeSessionManager, runtimePerformanceMetrics, runtimeFlightRecorder, deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger))
                 : resourceProvider),
         db: "db" in deps ? (deps.db ?? null) : db,
         performanceMetrics: runtimePerformanceMetrics,
         asyncJobManager: runtimeAsyncJobManager,
         approvalManager: runtimeApprovalManager,
-        flightRecorder: deps.flightRecorder ?? flightRecorder,
+        flightRecorder: runtimeFlightRecorder,
         logger: runtimeLogger,
-        persistence: deps.persistence ?? persistenceConfig,
+        persistence: deps.persistence ?? getPersistenceConfig(runtimeLogger),
+        cacheAwareness: deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger),
     };
 }
 // Per-CLI idle timeouts: kill process if no stdout/stderr activity for this duration.
@@ -664,14 +713,118 @@ function registerBaseResources(server, runtime) {
         const contents = await runtime.resourceProvider.readResource(uri.href);
         return { contents: contents ? [contents] : [] };
     });
+    // Cache-state resources (slice 2). Static URI for global, templated for
+    // session/{id} and prefix/{hash}. All three return tokens/hashes/aggregates
+    // ONLY — never raw prompt or response text. The structural guarantee is in
+    // the SessionCacheStats / PrefixCacheStats / GlobalCacheStats types
+    // themselves: those shapes have no prompt/response/system/task fields.
+    server.registerResource("cache-state-global", "cache_state://global", {
+        title: "💾 Cache State (Global)",
+        description: "Aggregate cache hit/miss/savings across all CLIs in the flight recorder. Tokens/hashes only — no prompt text.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        runtime.logger.debug("Reading cache_state://global resource");
+        const stats = runtime.resourceProvider.readCacheStateGlobal({
+            lastNHours: 24,
+        });
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(stats, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerResource("cache-state-session", new ResourceTemplate("cache_state://session/{sessionId}", { list: undefined }), {
+        title: "💾 Cache State (Session)",
+        description: "Per-session cache hit/miss/savings. Tokens/hashes only — no prompt text.",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const sessionId = Array.isArray(variables.sessionId)
+            ? variables.sessionId[0]
+            : variables.sessionId;
+        runtime.logger.debug(`Reading cache_state://session/${sessionId}`);
+        const stats = runtime.resourceProvider.readCacheStateSession(String(sessionId));
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(stats, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerResource("cache-state-prefix", new ResourceTemplate("cache_state://prefix/{hash}", { list: undefined }), {
+        title: "💾 Cache State (Prefix)",
+        description: "Per-stable-prefix-hash cache hit/miss/savings, with CLI breakdown. Tokens/hashes only — no prompt text.",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const hash = Array.isArray(variables.hash) ? variables.hash[0] : variables.hash;
+        runtime.logger.debug(`Reading cache_state://prefix/${hash}`);
+        const stats = runtime.resourceProvider.readCacheStateForPrefix(String(hash));
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(stats, null, 2),
+                },
+            ],
+        };
+    });
+}
+/**
+ * Slice 1: validate the prompt / promptParts mutex at the prep boundary and
+ * return either an error response or the resolved input. The exact error
+ * messages are part of the public contract — tests assert them verbatim.
+ */
+function resolvePromptOrPartsForPrep(args) {
+    const hasPrompt = typeof args.prompt === "string" && args.prompt.length > 0;
+    const hasParts = args.promptParts !== undefined;
+    if (hasPrompt && hasParts) {
+        return {
+            ok: false,
+            error: createErrorResponse(args.operation, 1, "", args.correlationId, new Error("provide exactly one of `prompt` or `promptParts`")),
+        };
+    }
+    if (!hasPrompt && !hasParts) {
+        return {
+            ok: false,
+            error: createErrorResponse(args.operation, 1, "", args.correlationId, new Error("one of `prompt` or `promptParts` is required")),
+        };
+    }
+    const resolved = resolvePromptInput({
+        prompt: args.prompt,
+        promptParts: args.promptParts,
+    });
+    return {
+        ok: true,
+        assembledPrompt: resolved.assembledPrompt,
+        stablePrefixHash: resolved.stablePrefixHash,
+        stablePrefixTokens: resolved.stablePrefixTokens,
+    };
 }
 export function prepareClaudeRequest(params, runtime = resolveGatewayServerRuntime()) {
     const corrId = params.correlationId || randomUUID();
     const cliInfo = getCliInfo();
     const resolvedModel = resolveModelAlias("claude", params.model, cliInfo);
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: params.operation,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const assembledPrompt = inputResolution.assembledPrompt;
+    const stablePrefixHash = inputResolution.stablePrefixHash;
+    const stablePrefixTokens = inputResolution.stablePrefixTokens;
     // Review integrity check on raw prompt (before optimization)
     const reviewIntegrity = checkReviewIntegrity({
-        prompt: params.prompt,
+        prompt: assembledPrompt,
         allowedTools: params.allowedTools,
         disallowedTools: params.disallowedTools,
     });
@@ -682,7 +835,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
             score: reviewIntegrity.totalScore,
         });
     }
-    let effectivePrompt = params.prompt;
+    let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
         logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
@@ -699,7 +852,7 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         approvalDecision = runtime.approvalManager.decide({
             cli: "claude",
             operation: params.operation,
-            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            prompt: assembledPrompt, // Use raw assembled prompt for review-context detection, not optimized
             bypassRequested: params.dangerouslySkipPermissions,
             fullAuto: false,
             requestedMcpServers,
@@ -778,14 +931,27 @@ export function prepareClaudeRequest(params, runtime = resolveGatewayServerRunti
         approvalDecision,
         reviewIntegrity,
         args,
+        stablePrefixHash,
+        stablePrefixTokens,
     };
 }
 export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntime()) {
     const corrId = params.correlationId || randomUUID();
     const cliInfo = getCliInfo();
     const resolvedModel = resolveModelAlias("codex", params.model, cliInfo);
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: params.operation,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const assembledPrompt = inputResolution.assembledPrompt;
+    const stablePrefixHash = inputResolution.stablePrefixHash;
+    const stablePrefixTokens = inputResolution.stablePrefixTokens;
     // Review integrity check on raw prompt (before optimization)
-    const reviewIntegrity = checkReviewIntegrity({ prompt: params.prompt });
+    const reviewIntegrity = checkReviewIntegrity({ prompt: assembledPrompt });
     if (reviewIntegrity.violations.length > 0) {
         runtime.logger.info(`[${corrId}] Review integrity violations detected: ${reviewIntegrity.violations.map(v => v.type).join(", ")}`, {
             cli: "codex",
@@ -793,7 +959,7 @@ export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntim
             score: reviewIntegrity.totalScore,
         });
     }
-    let effectivePrompt = params.prompt;
+    let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
         logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
@@ -805,7 +971,7 @@ export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntim
         approvalDecision = runtime.approvalManager.decide({
             cli: "codex",
             operation: params.operation,
-            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            prompt: assembledPrompt, // Use raw assembled prompt for review-context detection, not optimized
             bypassRequested: params.dangerouslyBypassApprovalsAndSandbox,
             fullAuto: params.fullAuto,
             requestedMcpServers,
@@ -920,15 +1086,28 @@ export function prepareCodexRequest(params, runtime = resolveGatewayServerRuntim
         reviewIntegrity,
         args,
         cleanup: highImpactCleanup,
+        stablePrefixHash,
+        stablePrefixTokens,
     };
 }
 export function prepareGeminiRequest(params, runtime = resolveGatewayServerRuntime()) {
     const corrId = params.correlationId || randomUUID();
     const cliInfo = getCliInfo();
     const resolvedModel = resolveModelAlias("gemini", params.model, cliInfo);
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: params.operation,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const assembledPrompt = inputResolution.assembledPrompt;
+    const stablePrefixHash = inputResolution.stablePrefixHash;
+    const stablePrefixTokens = inputResolution.stablePrefixTokens;
     // Review integrity check on raw prompt (before optimization)
     const reviewIntegrity = checkReviewIntegrity({
-        prompt: params.prompt,
+        prompt: assembledPrompt,
         allowedTools: params.allowedTools,
     });
     if (reviewIntegrity.violations.length > 0) {
@@ -938,7 +1117,7 @@ export function prepareGeminiRequest(params, runtime = resolveGatewayServerRunti
             score: reviewIntegrity.totalScore,
         });
     }
-    let effectivePrompt = params.prompt;
+    let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
         logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
@@ -950,7 +1129,7 @@ export function prepareGeminiRequest(params, runtime = resolveGatewayServerRunti
         approvalDecision = runtime.approvalManager.decide({
             cli: "gemini",
             operation: params.operation,
-            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            prompt: assembledPrompt, // Use raw assembled prompt for review-context detection, not optimized
             bypassRequested: params.approvalMode === "yolo",
             fullAuto: false,
             requestedMcpServers,
@@ -1020,15 +1199,28 @@ export function prepareGeminiRequest(params, runtime = resolveGatewayServerRunti
         approvalDecision,
         reviewIntegrity,
         args,
+        stablePrefixHash,
+        stablePrefixTokens,
     };
 }
 function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime()) {
     const corrId = params.correlationId || randomUUID();
     const cliInfo = getCliInfo();
     const resolvedModel = resolveModelAlias("grok", params.model, cliInfo);
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: params.operation,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const assembledPrompt = inputResolution.assembledPrompt;
+    const stablePrefixHash = inputResolution.stablePrefixHash;
+    const stablePrefixTokens = inputResolution.stablePrefixTokens;
     // Review integrity check on raw prompt (before optimization)
     const reviewIntegrity = checkReviewIntegrity({
-        prompt: params.prompt,
+        prompt: assembledPrompt,
         allowedTools: params.allowedTools,
         disallowedTools: params.disallowedTools,
     });
@@ -1039,7 +1231,7 @@ function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime()) {
             score: reviewIntegrity.totalScore,
         });
     }
-    let effectivePrompt = params.prompt;
+    let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
         logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
@@ -1051,7 +1243,7 @@ function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime()) {
         approvalDecision = runtime.approvalManager.decide({
             cli: "grok",
             operation: params.operation,
-            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            prompt: assembledPrompt, // Use raw assembled prompt for review-context detection, not optimized
             bypassRequested: Boolean(params.alwaysApprove) || params.permissionMode === "bypassPermissions",
             fullAuto: false,
             requestedMcpServers,
@@ -1095,14 +1287,27 @@ function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime()) {
         approvalDecision,
         reviewIntegrity,
         args,
+        stablePrefixHash,
+        stablePrefixTokens,
     };
 }
 export function prepareMistralRequest(params, runtime = resolveGatewayServerRuntime()) {
     const corrId = params.correlationId || randomUUID();
     const cliInfo = getCliInfo();
     const resolvedModel = resolveModelAlias("mistral", params.model, cliInfo);
-    const reviewIntegrity = checkReviewIntegrity({
+    const inputResolution = resolvePromptOrPartsForPrep({
         prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: params.operation,
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const assembledPrompt = inputResolution.assembledPrompt;
+    const stablePrefixHash = inputResolution.stablePrefixHash;
+    const stablePrefixTokens = inputResolution.stablePrefixTokens;
+    const reviewIntegrity = checkReviewIntegrity({
+        prompt: assembledPrompt,
         allowedTools: params.allowedTools,
         disallowedTools: params.disallowedTools,
     });
@@ -1113,7 +1318,7 @@ export function prepareMistralRequest(params, runtime = resolveGatewayServerRunt
             score: reviewIntegrity.totalScore,
         });
     }
-    let effectivePrompt = params.prompt;
+    let effectivePrompt = assembledPrompt;
     if (params.optimizePrompt) {
         const optimized = optimizePromptText(effectivePrompt);
         logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
@@ -1125,7 +1330,7 @@ export function prepareMistralRequest(params, runtime = resolveGatewayServerRunt
         approvalDecision = runtime.approvalManager.decide({
             cli: "mistral",
             operation: params.operation,
-            prompt: params.prompt,
+            prompt: assembledPrompt,
             bypassRequested: params.permissionMode === "auto-approve",
             fullAuto: false,
             requestedMcpServers,
@@ -1170,6 +1375,8 @@ export function prepareMistralRequest(params, runtime = resolveGatewayServerRunt
         reviewIntegrity,
         args: prep.args,
         mistralEnv: prep.env,
+        stablePrefixHash,
+        stablePrefixTokens,
     };
 }
 function isMistralModelSelectionFailure(stderr) {
@@ -1185,7 +1392,7 @@ function selectMistralRecoveryModel(failedModel) {
     ].filter((model) => Boolean(model && model !== failedModel));
     return candidates.find(model => model !== "local");
 }
-function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat) {
+function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat, warnings) {
     let finalStdout = stdout;
     // Skip response optimization for JSON output to prevent corrupting structured data
     if (optimizeResponse && outputFormat !== "json") {
@@ -1234,8 +1441,41 @@ function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep
     if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
         response.reviewIntegrity = prep.reviewIntegrity;
     }
+    if (warnings && warnings.length > 0) {
+        response.warnings = warnings;
+    }
     return response;
 }
+/**
+ * Slice 3 helper: compute the cache_ttl_expiring_soon warning for a
+ * claude session, if the feature is enabled, the session has prior cache
+ * writes, and ttlRemainingMs is below the threshold (30s by default).
+ * Returns null when no warning applies.
+ */
+function maybeBuildCacheTtlWarning(args) {
+    if (args.cli !== "claude")
+        return null;
+    if (!args.sessionId)
+        return null;
+    if (!args.runtime.cacheAwareness?.warnOnTtlExpiry)
+        return null;
+    const stats = computeSessionCacheStats(args.runtime.flightRecorder, args.sessionId);
+    if (stats.requestCount === 0 || !stats.lastRequestAt)
+        return null;
+    const ttl = computeTtlRemaining(stats, args.cli, {
+        anthropicTtlSeconds: args.runtime.cacheAwareness.anthropicTtlSeconds,
+    });
+    if (ttl === null)
+        return null;
+    const threshold = args.thresholdMs ?? 30_000;
+    if (ttl >= threshold)
+        return null;
+    return {
+        code: "cache_ttl_expiring_soon",
+        ttlRemainingMs: ttl,
+        message: `Anthropic cache breakpoint for session ${args.sessionId} expires in ${ttl}ms (< ${threshold}ms). Subsequent requests may miss the cache.`,
+    };
+}
 function resolveHandlerRuntime(deps) {
     if (deps.runtime)
         return deps.runtime;
@@ -1259,6 +1499,7 @@ export async function handleGeminiRequest(deps, params) {
     const startTime = Date.now();
     const prep = prepareGeminiRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         approvalMode: params.approvalMode,
         approvalStrategy: params.approvalStrategy,
@@ -1284,10 +1525,12 @@ export async function handleGeminiRequest(deps, params) {
         correlationId: corrId,
         cli: "gemini",
         model: prep.resolvedModel || "default",
-        prompt: params.prompt,
+        prompt: prep.effectivePrompt,
         sessionId: params.sessionId,
+        stablePrefixHash: prep.stablePrefixHash ?? undefined,
+        stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
     }, runtime);
-    deps.logger.info(`[${corrId}] gemini_request invoked with model=${prep.resolvedModel || "default"}, approvalMode=${params.approvalMode}, prompt length=${params.prompt.length}`);
+    deps.logger.info(`[${corrId}] gemini_request invoked with model=${prep.resolvedModel || "default"}, approvalMode=${params.approvalMode}, prompt length=${prep.effectivePrompt.length}`);
     try {
         // Gemini CLI 0.43 supports `--resume`, but not a supported fresh
         // `--session-id` flag. Fresh sessions emit no session flag.
@@ -1383,6 +1626,7 @@ export async function handleGeminiRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
     const prep = prepareGeminiRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         approvalMode: params.approvalMode,
         approvalStrategy: params.approvalStrategy,
@@ -1462,6 +1706,7 @@ export async function handleGrokRequest(deps, params) {
     const startTime = Date.now();
     const prep = prepareGrokRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         outputFormat: params.outputFormat,
         alwaysApprove: params.alwaysApprove,
@@ -1486,10 +1731,12 @@ export async function handleGrokRequest(deps, params) {
         correlationId: corrId,
         cli: "grok",
         model: prep.resolvedModel || "default",
-        prompt: params.prompt,
+        prompt: prep.effectivePrompt,
         sessionId: params.sessionId,
+        stablePrefixHash: prep.stablePrefixHash ?? undefined,
+        stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
     }, runtime);
-    deps.logger.info(`[${corrId}] grok_request invoked with model=${prep.resolvedModel || "default"}, permissionMode=${params.permissionMode}, prompt length=${params.prompt.length}`);
+    deps.logger.info(`[${corrId}] grok_request invoked with model=${prep.resolvedModel || "default"}, permissionMode=${params.permissionMode}, prompt length=${prep.effectivePrompt.length}`);
     try {
         // Session arg planning (pure, no I/O)
         const sessionResult = resolveGrokSessionArgs({
@@ -1578,6 +1825,7 @@ export async function handleGrokRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
     const prep = prepareGrokRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         outputFormat: params.outputFormat,
         alwaysApprove: params.alwaysApprove,
@@ -1658,6 +1906,7 @@ export async function handleMistralRequest(deps, params) {
     const startTime = Date.now();
     const prep = prepareMistralRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         outputFormat: params.outputFormat,
         permissionMode: params.permissionMode,
@@ -1681,10 +1930,12 @@ export async function handleMistralRequest(deps, params) {
         correlationId: corrId,
         cli: "mistral",
         model: prep.resolvedModel || "default",
-        prompt: params.prompt,
+        prompt: prep.effectivePrompt,
         sessionId: params.sessionId,
+        stablePrefixHash: prep.stablePrefixHash ?? undefined,
+        stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
     }, runtime);
-    deps.logger.info(`[${corrId}] mistral_request invoked with model=${prep.resolvedModel || "default"}, permissionMode=${params.permissionMode || "auto-approve"}, prompt length=${params.prompt.length}`);
+    deps.logger.info(`[${corrId}] mistral_request invoked with model=${prep.resolvedModel || "default"}, permissionMode=${params.permissionMode || "auto-approve"}, prompt length=${prep.effectivePrompt.length}`);
     try {
         const sessionResult = resolveMistralSessionArgs({
             sessionId: params.sessionId,
@@ -1795,6 +2046,7 @@ export async function handleMistralRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
     const prep = prepareMistralRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         outputFormat: params.outputFormat,
         permissionMode: params.permissionMode,
@@ -1870,6 +2122,7 @@ export async function handleCodexRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
     const prep = prepareCodexRequest({
         prompt: params.prompt,
+        promptParts: params.promptParts,
         model: params.model,
         fullAuto: params.fullAuto,
         sandboxMode: params.sandboxMode,
@@ -1986,7 +2239,14 @@ export async function handleCodexRequestAsync(deps, params) {
 //──────────────────────────────────────────────────────────────────────────────
 export function createGatewayServer(deps = {}) {
     const runtime = resolveGatewayServerRuntime(deps, { isolateState: true });
-    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, } = runtime;
+    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, flightRecorder, cacheAwareness, } = runtime;
+    // `flightRecorder` is destructured into closure scope so the session_get
+    // handler (see ~line 5590) has the FlightRecorderQuery read capability
+    // available without re-resolving runtime. Slice 2 will populate the
+    // `cacheState` field of session_get's response from this read surface.
+    // `cacheAwareness` is the loaded [cache_awareness] block (config.ts).
+    void flightRecorder;
+    void cacheAwareness;
     // Structural invariant: tools register iff ALL THREE conditions hold:
     //   (1) persistence.backend !== "none"  — the operator/config has not
     //       explicitly disabled durable persistence;
@@ -2012,7 +2272,9 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
-            .describe("Prompt text for Claude"),
+            .optional()
+            .describe("Prompt text for Claude (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
         model: z
             .string()
             .optional()
@@ -2107,13 +2369,14 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-    }, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
         const startTime = Date.now();
         if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
             return createErrorResponse("claude", 1, "", correlationId, new Error("systemPrompt and appendSystemPrompt are mutually exclusive; use one or the other (not both)."));
         }
         const prep = prepareClaudeRequest({
             prompt,
+            promptParts,
             model,
             outputFormat,
             allowedTools,
@@ -2142,26 +2405,53 @@ export function createGatewayServer(deps = {}) {
         const { corrId, args } = prep;
         let durationMs = 0;
         let wasSuccessful = false;
+        // Session resolution happens BEFORE safeFlightStart so that:
+        //   (1) the TTL warning reads the PRIOR session's lastWriteAt
+        //       rather than the row about to be inserted (codex-r1/F1).
+        //   (2) the flight-recorder row is tagged with effectiveSessionId
+        //       (the session the CLI will actually resume), not the raw
+        //       user-provided sessionId.
+        let effectiveSessionId = sessionId;
+        let useContinue = continueSession;
+        // Guard the active-session lookup: in some test harnesses the
+        // sessionManager is undefined; the original try-catch wrapped this
+        // block, so we replicate that tolerance here. Failure leaves
+        // effectiveSessionId as the user-provided sessionId.
+        let activeSession = null;
+        try {
+            activeSession = await sessionManager.getActiveSession("claude");
+        }
+        catch (err) {
+            logger.warn(`[${corrId}] sessionManager.getActiveSession failed (non-fatal): ${err.message}`);
+        }
+        if (!createNewSession && !continueSession && !sessionId && activeSession) {
+            effectiveSessionId = activeSession.id;
+            useContinue = true;
+        }
+        if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
+            useContinue = true;
+        }
+        // Slice 3: if the resolved session has a near-expiry Anthropic
+        // cache breakpoint, attach a structured warning (NOT a hard error)
+        // to the response. Computed BEFORE safeFlightStart so the current
+        // row does not skew lastRequestAt.
+        const ttlWarning = maybeBuildCacheTtlWarning({
+            runtime,
+            sessionId: effectiveSessionId,
+            cli: "claude",
+        });
+        const warnings = ttlWarning ? [ttlWarning] : [];
         safeFlightStart({
             correlationId: corrId,
             cli: "claude",
             model: prep.resolvedModel || "default",
-            prompt,
-            sessionId,
+            prompt: prep.effectivePrompt,
+            sessionId: effectiveSessionId,
+            stablePrefixHash: prep.stablePrefixHash ?? undefined,
+            stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
         }, runtime);
-        logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prompt.length}, sessionId=${sessionId}`);
+        logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prep.effectivePrompt.length}, sessionId=${effectiveSessionId}`);
         try {
-            // Session management
-            let effectiveSessionId = sessionId;
-            let useContinue = continueSession;
-            const activeSession = await sessionManager.getActiveSession("claude");
-            if (!createNewSession && !continueSession && !sessionId && activeSession) {
-                effectiveSessionId = activeSession.id;
-                useContinue = true;
-            }
-            if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
-                useContinue = true;
-            }
             if (useContinue) {
                 args.push("--continue");
             }
@@ -2190,7 +2480,14 @@ export function createGatewayServer(deps = {}) {
                     errorMessage: stderr || `Exit code ${code}`,
                     status: "failed",
                 }, runtime);
-                return createErrorResponse("claude", code, stderr, corrId);
+                // Slice 3: attach any computed warnings to the error response so
+                // the caller still sees cache_ttl_expiring_soon when the CLI
+                // happens to fail for an unrelated reason.
+                const errResp = createErrorResponse("claude", code, stderr, corrId);
+                if (warnings.length > 0) {
+                    errResp.warnings = warnings;
+                }
+                return errResp;
             }
             wasSuccessful = true;
             // If we used a session ID and it's not tracked yet, create a session record
@@ -2221,7 +2518,7 @@ export function createGatewayServer(deps = {}) {
                     exitCode: 0,
                     status: "completed",
                 }, runtime);
-                return buildCliResponse("claude", parsed.text, optimizeResponse, corrId, effectiveSessionId, prep, durationMs, undefined, outputFormat);
+                return buildCliResponse("claude", parsed.text, optimizeResponse, corrId, effectiveSessionId, prep, durationMs, undefined, outputFormat, warnings);
             }
             safeFlightComplete(corrId, {
                 response: stdout,
@@ -2232,7 +2529,7 @@ export function createGatewayServer(deps = {}) {
                 exitCode: 0,
                 status: "completed",
             }, runtime);
-            return buildCliResponse("claude", stdout, optimizeResponse, corrId, effectiveSessionId, prep, durationMs, undefined, outputFormat);
+            return buildCliResponse("claude", stdout, optimizeResponse, corrId, effectiveSessionId, prep, durationMs, undefined, outputFormat, warnings);
         }
         catch (error) {
             const elapsedMs = Math.max(0, Date.now() - startTime);
@@ -2262,7 +2559,9 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
-            .describe("Prompt text for Codex"),
+            .optional()
+            .describe("Prompt text for Codex (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
         model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
         fullAuto: z
             .boolean()
@@ -2353,10 +2652,11 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Codex --ignore-rules: skip project rule files for this run."),
-    }, async ({ prompt, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, }) => {
+    }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, }) => {
         const startTime = Date.now();
         const prep = prepareCodexRequest({
             prompt,
+            promptParts,
             model,
             fullAuto,
             sandboxMode,
@@ -2391,10 +2691,12 @@ export function createGatewayServer(deps = {}) {
             correlationId: corrId,
             cli: "codex",
             model: prep.resolvedModel || "default",
-            prompt,
+            prompt: prep.effectivePrompt,
             sessionId,
+            stablePrefixHash: prep.stablePrefixHash ?? undefined,
+            stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
         }, runtime);
-        logger.info(`[${corrId}] codex_request invoked with model=${prep.resolvedModel || "default"}, fullAuto=${fullAuto}, prompt length=${prompt.length}`);
+        logger.info(`[${corrId}] codex_request invoked with model=${prep.resolvedModel || "default"}, fullAuto=${fullAuto}, prompt length=${prep.effectivePrompt.length}`);
         // U26 fix: pass the outputSchema cleanup to awaitJobOrDefer, which
         // guarantees the cleanup runs exactly once — inline for direct
         // execution, on terminal status for the job-backed path (sync
@@ -2587,7 +2889,9 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
-            .describe("Prompt text for Gemini"),
+            .optional()
+            .describe("Prompt text for Gemini (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
         model: z
             .string()
             .optional()
@@ -2640,9 +2944,10 @@ export function createGatewayServer(deps = {}) {
         policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Policy file paths (--policy <path>, one per file). Paths must exist."),
         adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Admin policy file paths (--admin-policy <path>, one per file). Paths must exist."),
         attachments: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.attachments.describe("Absolute file paths prepended as @<path> tokens to the prompt"),
-    }, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, }) => {
+    }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, }) => {
         return handleGeminiRequest({ sessionManager, logger, runtime }, {
             prompt,
+            promptParts,
             model,
             sessionId,
             resumeLatest,
@@ -2673,7 +2978,9 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
-            .describe("Prompt text for Grok"),
+            .optional()
+            .describe("Prompt text for Grok (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
         model: z.string().optional().describe("Model name or alias (e.g. grok-build, latest)"),
         outputFormat: z
             .enum(["plain", "json", "streaming-json"])
@@ -2735,9 +3042,10 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-    }, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
+            promptParts,
             model,
             outputFormat,
             sessionId,
@@ -2767,7 +3075,9 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1, "Prompt cannot be empty")
             .max(100000, "Prompt too long (max 100k chars)")
-            .describe("Prompt text for Mistral Vibe"),
+            .optional()
+            .describe("Prompt text for Mistral Vibe (mutually exclusive with promptParts)"),
+        promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
         model: z
             .string()
             .optional()
@@ -2828,9 +3138,10 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .default(false)
             .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-    }, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
         return handleMistralRequest({ sessionManager, logger, runtime }, {
             prompt,
+            promptParts,
             model,
             outputFormat,
             sessionId,
@@ -2867,7 +3178,9 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
-                .describe("Prompt text for Claude"),
+                .optional()
+                .describe("Prompt text for Claude (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
             model: z
                 .string()
                 .optional()
@@ -2961,12 +3274,13 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-        }, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, permissionMode, agent, agents, forkSession, systemPrompt, appendSystemPrompt, maxBudgetUsd, maxTurns, effort, excludeDynamicSystemPromptSections, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
             if (systemPrompt !== undefined && appendSystemPrompt !== undefined) {
                 return createErrorResponse("claude", 1, "", correlationId, new Error("systemPrompt and appendSystemPrompt are mutually exclusive; use one or the other (not both)."));
             }
             const prep = prepareClaudeRequest({
                 prompt,
+                promptParts,
                 model,
                 outputFormat,
                 allowedTools,
@@ -3018,6 +3332,12 @@ export function createGatewayServer(deps = {}) {
                         await sessionManager.createSession("claude", "Claude Session", effectiveSessionId);
                     }
                 }
+                // Slice 3: TTL warning on resume (async path too).
+                const ttlWarning = maybeBuildCacheTtlWarning({
+                    runtime,
+                    sessionId: effectiveSessionId,
+                    cli: "claude",
+                });
                 // Idle timeout only for stream-json (text/json produce no output until done)
                 const effectiveIdleTimeout = outputFormat === "stream-json"
                     ? resolveIdleTimeout("claude", idleTimeoutMs)
@@ -3040,6 +3360,9 @@ export function createGatewayServer(deps = {}) {
                 if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
                     asyncResponse.reviewIntegrity = prep.reviewIntegrity;
                 }
+                if (ttlWarning) {
+                    asyncResponse.warnings = [ttlWarning];
+                }
                 return {
                     content: [
                         {
@@ -3058,7 +3381,9 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
-                .describe("Prompt text for Codex"),
+                .optional()
+                .describe("Prompt text for Codex (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
             model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
             fullAuto: z
                 .boolean()
@@ -3131,9 +3456,10 @@ export function createGatewayServer(deps = {}) {
             images: z.array(z.string()).optional().describe("Codex -i <path>: image attachments."),
             ignoreUserConfig: z.boolean().optional().describe("Codex --ignore-user-config."),
             ignoreRules: z.boolean().optional().describe("Codex --ignore-rules."),
-        }, async ({ prompt, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, }) => {
+        }, async ({ prompt, promptParts, model, fullAuto, sandboxMode, askForApproval, useLegacyFullAutoFlag, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, outputSchema, search, profile, configOverrides, ephemeral, images, ignoreUserConfig, ignoreRules, }) => {
             return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
+                promptParts,
                 model,
                 fullAuto,
                 sandboxMode,
@@ -3166,7 +3492,9 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
-                .describe("Prompt text for Gemini"),
+                .optional()
+                .describe("Prompt text for Gemini (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
             model: z
                 .string()
                 .optional()
@@ -3221,9 +3549,10 @@ export function createGatewayServer(deps = {}) {
             policyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.policyFiles.describe("Policy file paths (--policy <path>, one per file). Paths must exist."),
             adminPolicyFiles: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.adminPolicyFiles.describe("Admin policy file paths (--admin-policy <path>, one per file). Paths must exist."),
             attachments: GEMINI_HIGH_IMPACT_PARAMS_SCHEMA.shape.attachments.describe("Absolute file paths prepended as @<path> tokens to the prompt"),
-        }, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, }) => {
+        }, async ({ prompt, promptParts, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, outputFormat, sandbox, policyFiles, adminPolicyFiles, attachments, }) => {
             return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
+                promptParts,
                 model,
                 sessionId,
                 resumeLatest,
@@ -3250,7 +3579,9 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
-                .describe("Prompt text for Grok"),
+                .optional()
+                .describe("Prompt text for Grok (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
             model: z.string().optional().describe("Model name or alias (e.g. grok-build, latest)"),
             outputFormat: z
                 .enum(["plain", "json", "streaming-json"])
@@ -3311,9 +3642,10 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-        }, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
+                promptParts,
                 model,
                 outputFormat,
                 sessionId,
@@ -3339,7 +3671,9 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1, "Prompt cannot be empty")
                 .max(100000, "Prompt too long (max 100k chars)")
-                .describe("Prompt text for Mistral Vibe"),
+                .optional()
+                .describe("Prompt text for Mistral Vibe (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. Stable parts hash into cache_state for prefix-discipline tracking."),
             model: z
                 .string()
                 .optional()
@@ -3399,9 +3733,10 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .default(false)
                 .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
-        }, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
             return handleMistralRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
+                promptParts,
                 model,
                 outputFormat,
                 sessionId,
@@ -3852,6 +4187,38 @@ export function createGatewayServer(deps = {}) {
                 };
             }
             const activeSession = await sessionManager.getActiveSession(session.cli);
+            // Slice 2: project a compact cacheState view from the flight
+            // recorder at read time. NOT persisted on the Session interface
+            // (sessions.json stays content-free per the project invariant).
+            // The field is OMITTED entirely (not null, not empty object) when
+            // the session has zero rows in the flight recorder so the response
+            // stays compact for fresh sessions.
+            //
+            // Slice 3: include ttlRemainingMs derived from the gateway's
+            // configured TTL policy. Null for non-claude sessions.
+            let cacheState;
+            try {
+                const stats = computeSessionCacheStats(flightRecorder, session.id);
+                if (stats.requestCount > 0) {
+                    const ttlRemainingMs = computeTtlRemaining(stats, stats.cli, {
+                        anthropicTtlSeconds: cacheAwareness?.anthropicTtlSeconds ?? 300,
+                    });
+                    cacheState = {
+                        cli: stats.cli,
+                        prefixDistinct: stats.distinctPrefixCount,
+                        totalCacheReadTokens: stats.totalCacheReadTokens,
+                        totalCacheCreationTokens: stats.totalCacheCreationTokens,
+                        requestCount: stats.requestCount,
+                        hitCount: stats.hitCount,
+                        hitRate: stats.hitRate,
+                        estimatedSavingsUsd: stats.estimatedSavingsUsd,
+                        ttlRemainingMs,
+                    };
+                }
+            }
+            catch (err) {
+                logger.warn?.(`[session_get] cache-stats lookup failed (non-fatal)`, err);
+            }
             return {
                 content: [
                     {
@@ -3861,6 +4228,7 @@ export function createGatewayServer(deps = {}) {
                             session: {
                                 ...session,
                                 isActive: activeSession?.id === session.id,
+                                ...(cacheState ? { cacheState } : {}),
                             },
                         }, null, 2),
                     },
@@ -3913,7 +4281,7 @@ async function initializeSessionManager() {
         sessionManager = await createSessionManager(config, undefined, logger);
         logger.info("File-based session manager initialized");
     }
-    resourceProvider = new ResourceProvider(sessionManager, performanceMetrics);
+    resourceProvider = new ResourceProvider(sessionManager, performanceMetrics, getFlightRecorder(logger), getCacheAwarenessConfig(logger));
 }
 //──────────────────────────────────────────────────────────────────────────────
 // Health Check Resource (only if using PostgreSQL)
@@ -3944,7 +4312,7 @@ function registerHealthResource(server) {
         description: "Async job health (CPU, memory, zombie detection)",
         mimeType: "application/json",
     }, async (uri) => {
-        const health = asyncJobManager.getJobHealth();
+        const health = getAsyncJobManager().getJobHealth();
         return {
             contents: [
                 {
@@ -3980,8 +4348,10 @@ async function shutdown(signal) {
             await db.disconnect();
             logger.info("Database connections closed");
         }
-        flightRecorder.close();
-        logger.info("Flight recorder closed");
+        if (flightRecorder) {
+            flightRecorder.close();
+            logger.info("Flight recorder closed");
+        }
         process.exit(0);
     }
     catch (error) {
@@ -3997,6 +4367,20 @@ process.on("SIGINT", () => shutdown("SIGINT"));
 async function main() {
     startWindowsBootstrapperSelfHeal();
     const args = process.argv.slice(2);
+    if (args[0] === "--version" || args[0] === "-version" || args[0] === "version") {
+        process.stdout.write(`${packageVersion()}\n`);
+        return;
+    }
+    if (args[0] === "--help" || args[0] === "-help" || args[0] === "/?" || args[0] === "help") {
+        process.stdout.write([
+            "llm-cli-gateway MCP server",
+            "",
+            "Usage:",
+            "  llm-cli-gateway [doctor --json|contracts --json|--transport=http|--version]",
+            "",
+        ].join("\n"));
+        return;
+    }
     if (args[0] === "doctor") {
         if (args.includes("--json")) {
             printDoctorJson();
@@ -4035,9 +4419,9 @@ async function main() {
         resourceProvider,
         db,
         performanceMetrics,
-        asyncJobManager,
-        approvalManager,
-        flightRecorder,
+        asyncJobManager: getAsyncJobManager(logger),
+        approvalManager: getApprovalManager(logger),
+        flightRecorder: getFlightRecorder(logger),
         logger,
     };
     if (transportMode === "http") {