llm-cli-gateway 1.5.35 → 1.6.1

package/dist/config.js

@@ -227,3 +227,112 @@ export function loadPersistenceConfig(logger = noopLogger) {
         sources,
     };
 }
+//──────────────────────────────────────────────────────────────────────────────
+// Cache-awareness configuration
+//
+// Reads the [cache_awareness] block from the same ~/.llm-cli-gateway/config.toml
+// file as [persistence], but uses a SEPARATE loader and schema. Keeping the two
+// independent means a malformed [cache_awareness] never breaks persistence
+// loading and vice versa. No env-var overrides — purely TOML.
+//
+// All defaults are "off"; behavioural changes (slice 1 cache_control, slice 3
+// TTL warnings) ship dormant until operators opt in.
+//──────────────────────────────────────────────────────────────────────────────
+export const ANTHROPIC_TTL_SECONDS_VALUES = [300, 3600];
+/**
+ * Per-Anthropic-model-family minimum cacheable tokens. Sourced from
+ * docs/personal-mcp/PROVIDER_CACHE_SURFACES.md (Anthropic API docs as of
+ * 2026-05-26). Models below the threshold cannot be cached even with
+ * cache_control set — Anthropic silently returns un-cached.
+ */
+export const DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL = {
+    sonnet: 1024,
+    opus: 4096,
+    haiku: 4096,
+    default: 4096,
+};
+const MinStableTokensSchema = z
+    .object({
+    sonnet: z.number().int().positive().default(DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.sonnet),
+    opus: z.number().int().positive().default(DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.opus),
+    haiku: z.number().int().positive().default(DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.haiku),
+    default: z
+        .number()
+        .int()
+        .positive()
+        .default(DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.default),
+})
+    .strict()
+    .default({
+    sonnet: DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.sonnet,
+    opus: DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.opus,
+    haiku: DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.haiku,
+    default: DEFAULT_MIN_STABLE_TOKENS_FOR_CACHE_CONTROL.default,
+});
+const CacheAwarenessSchema = z
+    .object({
+    emit_anthropic_cache_control: z.boolean().default(false),
+    anthropic_ttl_seconds: z.union([z.literal(300), z.literal(3600)]).default(300),
+    warn_on_ttl_expiry: z.boolean().default(false),
+    min_stable_tokens_for_cache_control: MinStableTokensSchema,
+})
+    .strict();
+function readCacheAwarenessFile(configPath, logger) {
+    if (!existsSync(configPath)) {
+        return { raw: undefined, sourcePath: null };
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const TOML = require("smol-toml");
+        const text = readFileSync(configPath, "utf-8");
+        const parsed = TOML.parse(text);
+        return { raw: parsed?.cache_awareness, sourcePath: configPath };
+    }
+    catch (err) {
+        logger.error(`Failed to parse gateway config at ${configPath}; using cache_awareness defaults`, err);
+        return { raw: undefined, sourcePath: null };
+    }
+}
+/**
+ * Load [cache_awareness] from ~/.llm-cli-gateway/config.toml. Defaults: all
+ * behaviour off, per-model min-token thresholds from PROVIDER_CACHE_SURFACES.md.
+ */
+export function loadCacheAwarenessConfig(logger = noopLogger) {
+    const configPath = defaultPersistenceConfigPath();
+    const { raw, sourcePath } = readCacheAwarenessFile(configPath, logger);
+    let parsed;
+    try {
+        parsed = CacheAwarenessSchema.parse(raw ?? {});
+    }
+    catch (err) {
+        throw new Error(`Invalid [cache_awareness] config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        emitAnthropicCacheControl: parsed.emit_anthropic_cache_control,
+        anthropicTtlSeconds: parsed.anthropic_ttl_seconds,
+        warnOnTtlExpiry: parsed.warn_on_ttl_expiry,
+        minStableTokensForCacheControl: {
+            sonnet: parsed.min_stable_tokens_for_cache_control.sonnet,
+            opus: parsed.min_stable_tokens_for_cache_control.opus,
+            haiku: parsed.min_stable_tokens_for_cache_control.haiku,
+            default: parsed.min_stable_tokens_for_cache_control.default,
+        },
+        sources: { configFile: sourcePath },
+    };
+}
+/**
+ * Look up the per-model-family threshold. `modelName` is the user-facing model
+ * string (e.g. "claude-sonnet-4-6", "claude-opus-4-7"). Falls back to `default`
+ * when the family is unrecognised.
+ */
+export function minStableTokensForModel(config, modelName) {
+    const lower = modelName.toLowerCase();
+    const table = config.minStableTokensForCacheControl;
+    if (lower.includes("sonnet"))
+        return table.sonnet;
+    if (lower.includes("opus"))
+        return table.opus;
+    if (lower.includes("haiku"))
+        return table.haiku;
+    return table.default;
+}

package/dist/doctor.d.ts

@@ -1,5 +1,31 @@
 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";
+export type CliType = "claude" | "codex" | "gemini" | "grok" | "mistral";
+/**
+ * Slice 3 cross-cutting: doctor report block summarising the gateway's
+ * cache-awareness posture. Always PRESENT in the report (zeroed when the
+ * flight recorder has no rows for the last 24h).
+ *
+ * `enabled_features` is an empty array (NOT omitted) when all flags are
+ * off so callers can distinguish "configured but dormant" from
+ * "cache_awareness block missing".
+ */
+export interface CacheAwarenessReport {
+    enabled_features: Array<"anthropic_cache_control" | "ttl_warnings">;
+    last_24h: {
+        hit_rate: number;
+        total_hits: number;
+        total_requests: number;
+        estimated_savings_usd: number;
+    };
+    per_cli: Partial<Record<CliType, {
+        hit_rate: number;
+        total_hits: number;
+        total_cache_read_tokens: number;
+    }>>;
+}
 export interface VibeSessionLoggingStatus {
     config_path: string;
     config_present: boolean;
@@ -105,7 +131,22 @@ export interface DoctorReport {
         gemini_config: GeminiConfigStatus;
         vibe_session_logging: VibeSessionLoggingStatus;
     };
+    cache_awareness: CacheAwarenessReport;
     next_actions: string[];
 }
-export declare function createDoctorReport(env?: NodeJS.ProcessEnv): DoctorReport;
+export interface CreateDoctorReportOptions {
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Optional read access to the flight recorder. Drives the
+     * cache_awareness.last_24h and per_cli aggregates. When absent, those
+     * blocks report zeroed aggregates (still PRESENT in the report).
+     */
+    flightRecorder?: FlightRecorderQuery;
+    /**
+     * Optional CacheAwarenessConfig. Drives `enabled_features`. When
+     * absent, `enabled_features` is empty (all behaviour considered off).
+     */
+    cacheAwareness?: CacheAwarenessConfig;
+}
+export declare function createDoctorReport(envOrOptions?: NodeJS.ProcessEnv | CreateDoctorReportOptions): DoctorReport;
 export declare function printDoctorJson(): void;

package/dist/doctor.js

@@ -6,6 +6,9 @@ import { loadAuthConfig } from "./auth.js";
 import { createEndpointExposureReport, redactDiagnosticUrl, } from "./endpoint-exposure.js";
 import { listProviderRuntimeStatuses, } from "./provider-status.js";
 import { CLAUDE_MCP_SERVER_NAMES } from "./claude-mcp-config.js";
+import { loadCacheAwarenessConfig } from "./config.js";
+import { computeGlobalCacheStats } from "./cache-stats.js";
+import { FlightRecorder, resolveFlightRecorderDbPath } from "./flight-recorder.js";
 /**
  * Probe ~/.vibe/config.toml to see whether session_logging is enabled. Vibe
  * persists session logs (which sessionId/--continue depends on) only when
@@ -190,7 +193,71 @@ function chatGPTConnectorUrl(env, rawPublicUrl) {
         return null;
     }
 }
-export function createDoctorReport(env = process.env) {
+/**
+ * Build the cache_awareness block. ALWAYS present in the report; fields
+ * are zeroed when the flight recorder is missing or empty.
+ */
+function buildCacheAwarenessReport(opts) {
+    const enabled = [];
+    if (opts.cacheAwareness?.emitAnthropicCacheControl) {
+        enabled.push("anthropic_cache_control");
+    }
+    if (opts.cacheAwareness?.warnOnTtlExpiry) {
+        enabled.push("ttl_warnings");
+    }
+    if (!opts.flightRecorder) {
+        return {
+            enabled_features: enabled,
+            last_24h: {
+                hit_rate: 0,
+                total_hits: 0,
+                total_requests: 0,
+                estimated_savings_usd: 0,
+            },
+            per_cli: {},
+        };
+    }
+    let stats;
+    try {
+        stats = computeGlobalCacheStats(opts.flightRecorder, { lastNHours: 24 });
+    }
+    catch {
+        return {
+            enabled_features: enabled,
+            last_24h: {
+                hit_rate: 0,
+                total_hits: 0,
+                total_requests: 0,
+                estimated_savings_usd: 0,
+            },
+            per_cli: {},
+        };
+    }
+    const perCli = {};
+    for (const entry of stats.perCli) {
+        perCli[entry.cli] = {
+            hit_rate: entry.hitRate,
+            total_hits: entry.hitCount,
+            total_cache_read_tokens: entry.totalCacheReadTokens,
+        };
+    }
+    return {
+        enabled_features: enabled,
+        last_24h: {
+            hit_rate: stats.hitRate,
+            total_hits: stats.totalHits,
+            total_requests: stats.totalRequests,
+            estimated_savings_usd: stats.estimatedSavingsUsd,
+        },
+        per_cli: perCli,
+    };
+}
+export function createDoctorReport(envOrOptions = process.env) {
+    // Preserve back-compat: previous signature accepted a bare `env` object.
+    const opts = isCreateDoctorReportOptions(envOrOptions)
+        ? envOrOptions
+        : { env: envOrOptions };
+    const env = opts.env ?? process.env;
     const auth = loadAuthConfig(env);
     const transport = defaultTransport(env);
     const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || null;
@@ -237,6 +304,7 @@ export function createDoctorReport(env = process.env) {
         },
         endpoint_exposure: endpointExposure,
         client_config: clientConfigStatus(),
+        cache_awareness: buildCacheAwarenessReport(opts),
         next_actions: [],
     };
     if (transport === "http" && auth.required && !auth.tokenConfigured) {
@@ -271,7 +339,58 @@ export function createDoctorReport(env = process.env) {
     return report;
 }
 export function printDoctorJson() {
-    process.stdout.write(`${JSON.stringify(createDoctorReport(), null, 2)}\n`);
+    // Load cache-awareness config + open the flight recorder so the doctor
+    // command can populate cache_awareness.last_24h. Both are best-effort —
+    // failures degrade to the zeroed block (buildCacheAwarenessReport
+    // handles missing deps).
+    let cacheAwareness;
+    let flightRecorder;
+    try {
+        cacheAwareness = loadCacheAwarenessConfig();
+    }
+    catch {
+        // ignore
+    }
+    try {
+        const dbPath = resolveFlightRecorderDbPath();
+        if (dbPath)
+            flightRecorder = new FlightRecorder(dbPath);
+    }
+    catch {
+        // ignore
+    }
+    const report = createDoctorReport({
+        env: process.env,
+        cacheAwareness,
+        flightRecorder,
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (flightRecorder) {
+        try {
+            flightRecorder.close();
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+function isCreateDoctorReportOptions(value) {
+    // CreateDoctorReportOptions carries either `env` (an object) or
+    // `flightRecorder` (an object). A NodeJS.ProcessEnv is a flat
+    // Record<string, string|undefined> — even if a shell happens to export
+    // `env=production` or `flightRecorder=...`, the value at that key is a
+    // STRING, not an object, so the typeof checks here cannot collide.
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Object.prototype.hasOwnProperty.call(value, "flightRecorder")) {
+        const candidate = value.flightRecorder;
+        return candidate === undefined || typeof candidate === "object";
+    }
+    if (Object.prototype.hasOwnProperty.call(value, "env")) {
+        const candidate = value.env;
+        return candidate === undefined || typeof candidate === "object";
+    }
+    return false;
 }
 function doctorProviderStatus(provider) {
     return {

package/dist/flight-recorder.d.ts

@@ -6,6 +6,8 @@ export interface FlightLogStart {
     system?: string;
     sessionId?: string;
     asyncJobId?: string;
+    stablePrefixHash?: string;
+    stablePrefixTokens?: number;
 }
 export interface FlightLogResult {
     response: string;
@@ -36,15 +38,40 @@ export declare class FlightRecorder {
     constructor(dbPath: string);
     logStart(entry: FlightLogStart): void;
     logComplete(correlationId: string, result: FlightLogResult): void;
+    /**
+     * Read-only query over the requests + gateway_metadata tables. Used by
+     * cache-stats / MCP resources / doctor without exposing a second SQLite
+     * connection. better-sqlite3 in WAL mode handles concurrent readers
+     * inside a single process safely.
+     *
+     * Safety:
+     * - Caller MUST pass parameterised SQL — direct string interpolation of
+     *   untrusted values is unsafe.
+     * - The compiled statement's `.readonly` flag is checked at runtime;
+     *   anything that can mutate rows (INSERT/UPDATE/DELETE, including the
+     *   `RETURNING` forms that better-sqlite3 surfaces via `.all()`) throws.
+     *   This blocks the writer-disguised-as-reader vector codex-r1/F3
+     *   flagged, even when the caller is internal gateway code.
+     */
+    queryRequests<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[];
     flush(): void;
     close(): void;
 }
 export declare class NoopFlightRecorder {
     logStart(_entry: FlightLogStart): void;
     logComplete(_correlationId: string, _result: FlightLogResult): void;
+    queryRequests<T = Record<string, unknown>>(_sql: string, ..._params: unknown[]): T[];
     flush(): void;
     close(): void;
 }
 export type FlightRecorderLike = FlightRecorder | NoopFlightRecorder;
+/**
+ * Read-only subset of FlightRecorder used by cache-stats / MCP resources /
+ * doctor. Accepts either FlightRecorder or NoopFlightRecorder; the noop
+ * returns `[]` from every query so downstream aggregation is empty by design.
+ */
+export interface FlightRecorderQuery {
+    queryRequests<T = Record<string, unknown>>(sql: string, ...params: unknown[]): T[];
+}
 export declare function createFlightRecorder(logger: LoggerLike): FlightRecorderLike;
 export {};

package/dist/flight-recorder.js

@@ -1,3 +1,20 @@
+/**
+ * Flight recorder: SQLite-backed request log.
+ *
+ * Read access for cache-stats / MCP resources / doctor goes through the
+ * `queryRequests<T>(sql, ...params)` method exposed on both `FlightRecorder`
+ * and `NoopFlightRecorder` (the `FlightRecorderQuery` interface, see bottom
+ * of file). This is Option A from
+ * docs/plans/cache-awareness.dag.toml#expose-flight-recorder-read-access —
+ * a single read-only query surface on the existing class, NOT a sibling
+ * read-only SQLite connection. better-sqlite3 in WAL mode handles
+ * concurrent readers inside a single process safely, so the additional
+ * connection isn't needed and would have to be threaded through
+ * GatewayServerRuntime as a separate field.
+ *
+ * Callers MUST pass parameterised SQL — string-interpolation of untrusted
+ * values is unsafe even on a "read-only" query.
+ */
 import { chmodSync, existsSync, mkdirSync } from "fs";
 import os from "os";
 import path from "path";
@@ -18,6 +35,26 @@ function ensureRequestsCacheColumns(db) {
         db.exec("ALTER TABLE requests ADD COLUMN cache_creation_tokens INTEGER");
     }
 }
+/**
+ * Idempotent v3 migration: add `stable_prefix_hash` / `stable_prefix_tokens`
+ * columns plus their index. Populated only for new rows that carry a
+ * promptParts structure (slice 1); legacy rows keep NULL forever.
+ *
+ * Read access for cache-stats / MCP resources / doctor goes through the
+ * read-only `queryRequests()` method on FlightRecorder (no separate read
+ * connection — better-sqlite3 in WAL mode handles concurrent readers).
+ */
+function ensureStablePrefixColumns(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("stable_prefix_hash")) {
+        db.exec("ALTER TABLE requests ADD COLUMN stable_prefix_hash TEXT");
+    }
+    if (!names.has("stable_prefix_tokens")) {
+        db.exec("ALTER TABLE requests ADD COLUMN stable_prefix_tokens INTEGER");
+    }
+    db.exec("CREATE INDEX IF NOT EXISTS idx_requests_stable_hash ON requests(stable_prefix_hash)");
+}
 export function resolveFlightRecorderDbPath() {
     const configured = process.env.LLM_GATEWAY_LOGS_DB;
     if (configured !== undefined) {
@@ -131,6 +168,14 @@ export class FlightRecorder {
         this.db
             .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(2, ?)")
             .run(new Date().toISOString());
+        // Migration v3: stable_prefix_hash / stable_prefix_tokens columns plus
+        // their index. Populated only for new rows whose request carried a
+        // promptParts structure (slice 1 of cache-awareness); legacy rows keep
+        // NULL intentionally.
+        ensureStablePrefixColumns(this.db);
+        this.db
+            .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(3, ?)")
+            .run(new Date().toISOString());
         if (process.platform !== "win32") {
             try {
                 chmodSync(dbPath, 0o600);
@@ -140,8 +185,10 @@ export class FlightRecorder {
             }
         }
         const insertRequest = this.db.prepare(`
-      INSERT INTO requests (id, cli, model, prompt, system, session_id, datetime_utc)
-      VALUES (@id, @cli, @model, @prompt, @system, @session_id, @datetime_utc)
+      INSERT INTO requests (id, cli, model, prompt, system, session_id, datetime_utc,
+                            stable_prefix_hash, stable_prefix_tokens)
+      VALUES (@id, @cli, @model, @prompt, @system, @session_id, @datetime_utc,
+              @stable_prefix_hash, @stable_prefix_tokens)
     `);
         const insertMetadata = this.db.prepare(`
       INSERT INTO gateway_metadata (request_id, async_job_id, status)
@@ -156,6 +203,8 @@ export class FlightRecorder {
                 system: entry.system || null,
                 session_id: entry.sessionId || null,
                 datetime_utc: new Date().toISOString(),
+                stable_prefix_hash: entry.stablePrefixHash ?? null,
+                stable_prefix_tokens: entry.stablePrefixTokens ?? null,
             });
             insertMetadata.run({
                 request_id: entry.correlationId,
@@ -218,6 +267,31 @@ export class FlightRecorder {
     logComplete(correlationId, result) {
         this.updateCompleteTxn(correlationId, result);
     }
+    /**
+     * Read-only query over the requests + gateway_metadata tables. Used by
+     * cache-stats / MCP resources / doctor without exposing a second SQLite
+     * connection. better-sqlite3 in WAL mode handles concurrent readers
+     * inside a single process safely.
+     *
+     * Safety:
+     * - Caller MUST pass parameterised SQL — direct string interpolation of
+     *   untrusted values is unsafe.
+     * - The compiled statement's `.readonly` flag is checked at runtime;
+     *   anything that can mutate rows (INSERT/UPDATE/DELETE, including the
+     *   `RETURNING` forms that better-sqlite3 surfaces via `.all()`) throws.
+     *   This blocks the writer-disguised-as-reader vector codex-r1/F3
+     *   flagged, even when the caller is internal gateway code.
+     */
+    queryRequests(sql, ...params) {
+        const stmt = this.db.prepare(sql);
+        if (stmt.readonly === false) {
+            throw new Error("FlightRecorder.queryRequests refuses non-readonly SQL — use a transaction or a separate write surface for INSERT/UPDATE/DELETE.");
+        }
+        if (!stmt.all) {
+            return [];
+        }
+        return stmt.all(...params);
+    }
     flush() {
         // No-op: better-sqlite3 writes synchronously.
     }
@@ -228,6 +302,9 @@ export class FlightRecorder {
 export class NoopFlightRecorder {
     logStart(_entry) { }
     logComplete(_correlationId, _result) { }
+    queryRequests(_sql, ..._params) {
+        return [];
+    }
     flush() { }
     close() { }
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { ISessionManager } from "./session-manager.js";
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
-import { type PersistenceConfig } from "./config.js";
+import { type PersistenceConfig, type CacheAwarenessConfig } from "./config.js";
 import { DatabaseConnection } from "./db.js";
 import { AsyncJobManager } from "./async-job-manager.js";
 import { ApprovalManager, ApprovalRecord } from "./approval-manager.js";
@@ -12,6 +12,22 @@ import { ReviewIntegrityResult } from "./review-integrity.js";
 import { ClaudeMcpConfigResult, ClaudeMcpServerName } from "./claude-mcp-config.js";
 import { type MistralAgentMode, type ClaudePermissionMode, type CodexSandboxMode, type CodexAskForApproval, type ClaudeEffortLevel } from "./request-helpers.js";
 import { FlightRecorderLike } from "./flight-recorder.js";
+import { type PromptParts } from "./prompt-parts.js";
+/**
+ * Slice 3: structured warning entries attached to tool responses.
+ * Distinct from review-integrity warnings (which are text-appended to
+ * the user-visible response). These are programmatic signals for caller
+ * agents to react to.
+ */
+export interface WarningEntry {
+    /** Stable machine-readable code, e.g. "cache_ttl_expiring_soon". */
+    code: string;
+    /** Optional human-readable message for surfaces that render text. */
+    message?: string;
+    /** Code-specific payload — left open for future warning types. */
+    ttlRemainingMs?: number;
+    [key: string]: unknown;
+}
 type ExtendedToolResponse = {
     content: {
         type: "text";
@@ -28,6 +44,8 @@ type ExtendedToolResponse = {
         missing?: ClaudeMcpServerName[];
     };
     reviewIntegrity?: ReviewIntegrityResult;
+    /** Slice 3: structured warnings (e.g. cache_ttl_expiring_soon). */
+    warnings?: WarningEntry[];
 };
 declare const logger: {
     info: (message: string, ...args: any[]) => void;
@@ -49,6 +67,7 @@ export interface GatewayServerDeps {
     flightRecorder?: FlightRecorderLike;
     logger?: GatewayLogger;
     persistence?: PersistenceConfig;
+    cacheAwareness?: CacheAwarenessConfig;
 }
 interface GatewayServerRuntime {
     sessionManager: ISessionManager;
@@ -60,6 +79,7 @@ interface GatewayServerRuntime {
     flightRecorder: FlightRecorderLike;
     logger: GatewayLogger;
     persistence: PersistenceConfig;
+    cacheAwareness: CacheAwarenessConfig;
 }
 interface CliRequestPrep {
     corrId: string;
@@ -70,9 +90,19 @@ interface CliRequestPrep {
     approvalDecision: ApprovalRecord | null;
     reviewIntegrity?: ReviewIntegrityResult;
     args: string[];
+    /**
+     * Sha256 of the assembled prompt's stable prefix bytes when the caller
+     * supplied `promptParts`. Null when the legacy `prompt` field was used.
+     * Populated by `resolvePromptOrPartsForPrep` and threaded into the
+     * flight-recorder row by the caller's safeFlightStart entry.
+     */
+    stablePrefixHash: string | null;
+    /** Heuristic token count (bytes/4) of the same stable prefix. */
+    stablePrefixTokens: number | null;
 }
 export declare function prepareClaudeRequest(params: {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     outputFormat: "text" | "json" | "stream-json";
     allowedTools?: string[];
@@ -106,7 +136,8 @@ export interface CodexRequestPrep extends CliRequestPrep {
     cleanup?: () => void;
 }
 export declare function prepareCodexRequest(params: {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     fullAuto: boolean;
     sandboxMode?: CodexSandboxMode;
@@ -138,7 +169,8 @@ export declare function prepareCodexRequest(params: {
     ignoreRules?: boolean;
 }, runtime?: GatewayServerRuntime): CodexRequestPrep | ExtendedToolResponse;
 export declare function prepareGeminiRequest(params: {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     approvalMode?: string;
     approvalStrategy: "legacy" | "mcp_managed";
@@ -161,7 +193,8 @@ export declare function prepareGeminiRequest(params: {
     attachments?: string[];
 }, runtime?: GatewayServerRuntime): CliRequestPrep | ExtendedToolResponse;
 export declare function prepareMistralRequest(params: {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     outputFormat?: string;
     permissionMode?: MistralAgentMode;
@@ -179,7 +212,8 @@ export declare function prepareMistralRequest(params: {
     mistralEnv: Record<string, string>;
 }) | ExtendedToolResponse;
 export interface GeminiRequestParams {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     sessionId?: string;
     resumeLatest: boolean;
@@ -218,7 +252,8 @@ export interface AsyncHandlerDeps extends HandlerDeps {
 export declare function handleGeminiRequest(deps: HandlerDeps, params: GeminiRequestParams): Promise<ExtendedToolResponse>;
 export declare function handleGeminiRequestAsync(deps: AsyncHandlerDeps, params: Omit<GeminiRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
 export interface GrokRequestParams {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     outputFormat?: string;
     sessionId?: string;
@@ -242,7 +277,8 @@ export interface GrokRequestParams {
 export declare function handleGrokRequest(deps: HandlerDeps, params: GrokRequestParams): Promise<ExtendedToolResponse>;
 export declare function handleGrokRequestAsync(deps: AsyncHandlerDeps, params: Omit<GrokRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
 export interface MistralRequestParams {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     outputFormat?: string;
     sessionId?: string;
@@ -265,7 +301,8 @@ export interface MistralRequestParams {
 export declare function handleMistralRequest(deps: HandlerDeps, params: MistralRequestParams): Promise<ExtendedToolResponse>;
 export declare function handleMistralRequestAsync(deps: AsyncHandlerDeps, params: Omit<MistralRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
 export declare function handleCodexRequestAsync(deps: AsyncHandlerDeps, params: {
-    prompt: string;
+    prompt?: string;
+    promptParts?: PromptParts;
     model?: string;
     fullAuto: boolean;
     sandboxMode?: CodexSandboxMode;