llm-cli-gateway 1.4.0 → 1.5.4

package/dist/doctor.js

@@ -0,0 +1,280 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform, arch, release } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+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";
+/**
+ * Probe ~/.vibe/config.toml to see whether session_logging is enabled. Vibe
+ * persists session logs (which sessionId/--continue depends on) only when
+ * `[session_logging] enabled = true` is set. The probe is read-only: the
+ * gateway never mutates this file.
+ */
+export function checkVibeSessionLogging(home = homedir()) {
+    const configPath = join(home, ".vibe", "config.toml");
+    if (!existsSync(configPath)) {
+        return {
+            config_path: configPath,
+            config_present: false,
+            session_logging_enabled: false,
+            note: "~/.vibe/config.toml not found. Run `vibe config set session_logging.enabled true` or create the file with a [session_logging]\\nenabled = true block.",
+        };
+    }
+    try {
+        const text = readFileSync(configPath, "utf8");
+        const enabled = parseVibeSessionLoggingEnabled(text);
+        if (enabled) {
+            return {
+                config_path: configPath,
+                config_present: true,
+                session_logging_enabled: true,
+                note: "session_logging.enabled is true; --continue/--resume will work for mistral_request.",
+            };
+        }
+        return {
+            config_path: configPath,
+            config_present: true,
+            session_logging_enabled: false,
+            note: "[session_logging] enabled = false (or missing). Run `vibe config set session_logging.enabled true` or edit ~/.vibe/config.toml so mistral_request --resume / --continue can persist sessions.",
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            config_path: configPath,
+            config_present: true,
+            session_logging_enabled: false,
+            note: `Could not parse ~/.vibe/config.toml: ${message}. Verify the file is valid TOML.`,
+        };
+    }
+}
+/**
+ * Tiny TOML probe focused on `[session_logging] enabled = true`. Avoids pulling
+ * in the full `toml` parser when only one boolean is needed.
+ */
+function parseVibeSessionLoggingEnabled(text) {
+    const lines = text.split(/\r?\n/);
+    let inSection = false;
+    for (let raw of lines) {
+        const line = raw.replace(/#.*$/, "").trim();
+        if (!line)
+            continue;
+        const sectionMatch = line.match(/^\[\s*([A-Za-z0-9_.-]+)\s*\]$/);
+        if (sectionMatch) {
+            inSection = sectionMatch[1] === "session_logging";
+            continue;
+        }
+        if (inSection) {
+            const kv = line.match(/^enabled\s*=\s*(.+)$/);
+            if (kv) {
+                const value = kv[1].trim().toLowerCase();
+                return value === "true";
+            }
+        }
+        else {
+            // Allow dotted form: session_logging.enabled = true
+            const dotted = line.match(/^session_logging\.enabled\s*=\s*(.+)$/);
+            if (dotted) {
+                const value = dotted[1].trim().toLowerCase();
+                return value === "true";
+            }
+        }
+    }
+    return false;
+}
+/**
+ * U27: Probe Gemini's project/user config locations.
+ *
+ * - `./GEMINI.md` (gateway cwd) and `~/.gemini/GEMINI.md` are documented
+ *   "context" surfaces. Missing both means Gemini has no project-specific
+ *   guidance.
+ * - `~/.gemini/settings.json` defines registered MCP servers (`mcpServers`
+ *   block). The gateway tracks its own whitelist (`CLAUDE_MCP_SERVER_NAMES`)
+ *   and surfaces a reconciliation warning for each whitelisted server not
+ *   present in settings.json so callers don't ship requests for unregistered
+ *   servers.
+ */
+export function checkGeminiConfig(cwd = process.cwd(), home = homedir(), whitelist = CLAUDE_MCP_SERVER_NAMES) {
+    const projectGeminiMd = join(cwd, "GEMINI.md");
+    const userGeminiMd = join(home, ".gemini", "GEMINI.md");
+    const settingsPath = join(home, ".gemini", "settings.json");
+    const projectGeminiMdPresent = existsSync(projectGeminiMd);
+    const userGeminiMdPresent = existsSync(userGeminiMd);
+    const settingsPresent = existsSync(settingsPath);
+    let mcpServersRegistered = [];
+    if (settingsPresent) {
+        try {
+            const raw = readFileSync(settingsPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.mcpServers === "object" && parsed.mcpServers) {
+                mcpServersRegistered = Object.keys(parsed.mcpServers);
+            }
+        }
+        catch {
+            // Best-effort: leave list empty so the next_action surfaces the gap.
+        }
+    }
+    const missingFromSettings = whitelist.filter(name => !mcpServersRegistered.includes(name));
+    const nextActions = [];
+    if (!projectGeminiMdPresent && !userGeminiMdPresent) {
+        nextActions.push(`Create ${projectGeminiMd} to give Gemini project-specific context (or ${userGeminiMd} for a user-wide default).`);
+    }
+    if (!settingsPresent) {
+        nextActions.push(`Create ${settingsPath} to register MCP servers (mcpServers block). Run \`gemini mcp add <name>\` for each gateway-whitelisted server.`);
+    }
+    for (const name of missingFromSettings) {
+        nextActions.push(`MCP server \`${name}\` is whitelisted by the gateway but not registered in ${settingsPath}. Run \`gemini mcp add ${name}\` to register it.`);
+    }
+    return {
+        project_gemini_md_present: projectGeminiMdPresent,
+        project_gemini_md_path: projectGeminiMd,
+        user_gemini_md_present: userGeminiMdPresent,
+        user_gemini_md_path: userGeminiMd,
+        settings_json_present: settingsPresent,
+        settings_json_path: settingsPath,
+        mcp_servers_registered: mcpServersRegistered,
+        mcp_reconciliation: {
+            whitelisted: [...whitelist],
+            missing_from_settings: missingFromSettings,
+        },
+        next_actions: nextActions,
+    };
+}
+function packageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(here, "..", "package.json"), join(here, "..", "..", "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 clientConfigStatus(home = homedir()) {
+    return {
+        claude_desktop_config_present: existsSync(join(home, "Library/Application Support/Claude/claude_desktop_config.json")) ||
+            existsSync(join(home, ".config", "Claude", "claude_desktop_config.json")),
+        codex_config_present: existsSync(join(home, ".codex", "config.toml")),
+        gemini_settings_present: existsSync(join(home, ".gemini", "settings.json")) ||
+            existsSync(join(home, ".config", "gemini", "settings.json")),
+        gemini_config: checkGeminiConfig(process.cwd(), home),
+        vibe_session_logging: checkVibeSessionLogging(home),
+    };
+}
+function defaultTransport(env) {
+    if (env.LLM_GATEWAY_TRANSPORT === "http" || env.MCP_TRANSPORT === "http")
+        return "http";
+    return "stdio";
+}
+export function createDoctorReport(env = process.env) {
+    const auth = loadAuthConfig(env);
+    const transport = defaultTransport(env);
+    const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || null;
+    const publicUrl = redactDiagnosticUrl(rawPublicUrl);
+    const endpointExposure = createEndpointExposureReport(env, publicUrl);
+    const providerStatuses = listProviderRuntimeStatuses();
+    const report = {
+        schema_version: "1.0",
+        ok: true,
+        generated_at: new Date().toISOString(),
+        system: {
+            os: platform(),
+            arch: arch(),
+            release: release(),
+            node_version: process.version,
+        },
+        gateway: {
+            name: "llm-cli-gateway",
+            version: packageVersion(),
+        },
+        transport: {
+            default: transport,
+            http: {
+                enabled: transport === "http",
+                host: env.LLM_GATEWAY_HTTP_HOST || "127.0.0.1",
+                port: Number(env.LLM_GATEWAY_HTTP_PORT || 3333),
+                path: env.LLM_GATEWAY_HTTP_PATH || "/mcp",
+                public_url_configured: Boolean(publicUrl),
+                public_url: publicUrl,
+            },
+        },
+        auth: {
+            required: auth.required,
+            token_configured: auth.tokenConfigured,
+            source: auth.source,
+        },
+        providers: {
+            claude: doctorProviderStatus(providerStatuses.claude),
+            codex: doctorProviderStatus(providerStatuses.codex),
+            gemini: doctorProviderStatus(providerStatuses.gemini),
+            grok: doctorProviderStatus(providerStatuses.grok),
+            mistral: doctorProviderStatus(providerStatuses.mistral),
+        },
+        endpoint_exposure: endpointExposure,
+        client_config: clientConfigStatus(),
+        next_actions: [],
+    };
+    if (transport === "http" && auth.required && !auth.tokenConfigured) {
+        report.ok = false;
+        report.next_actions.push("Set LLM_GATEWAY_AUTH_TOKEN before starting HTTP transport.");
+    }
+    report.next_actions.push(...endpointExposure.next_actions);
+    for (const [name, provider] of Object.entries(report.providers)) {
+        if (!provider.cli_available) {
+            report.next_actions.push(provider.install_guidance.summary);
+        }
+        else if (provider.login_status !== "authenticated") {
+            report.next_actions.push(`${name}: ${provider.login_guidance.summary}`);
+        }
+    }
+    // Mistral-specific: surface the session_logging toggle BEFORE a --continue/--resume
+    // request fails opaquely. The check is read-only; the gateway never mutates the file.
+    const vibeStatus = report.client_config.vibe_session_logging;
+    if (report.providers.mistral.cli_available && !vibeStatus.session_logging_enabled) {
+        report.next_actions.push(`mistral: ${vibeStatus.note}`);
+    }
+    // U27: surface Gemini config gaps (missing GEMINI.md, missing settings.json,
+    // MCP-server whitelist drift) only when Gemini CLI is actually installed.
+    if (report.providers.gemini.cli_available) {
+        for (const action of report.client_config.gemini_config.next_actions) {
+            report.next_actions.push(`gemini: ${action}`);
+        }
+    }
+    if (report.next_actions.length === 0) {
+        report.next_actions.push("Run a client setup guide and verify with doctor --json after each step.");
+    }
+    return report;
+}
+export function printDoctorJson() {
+    process.stdout.write(`${JSON.stringify(createDoctorReport(), null, 2)}\n`);
+}
+function doctorProviderStatus(provider) {
+    return {
+        cli_available: provider.installed,
+        version: provider.version,
+        login_status: provider.loginStatus,
+        version_command: provider.versionCommand,
+        login_check: {
+            method: provider.loginCheck.method,
+            command: provider.loginCheck.command,
+            credential_store: provider.loginCheck.credentialStore,
+            detail: provider.loginCheck.detail,
+        },
+        install_guidance: {
+            summary: provider.guidance.install.summary,
+            commands: provider.guidance.install.commands,
+            documentation_url: provider.guidance.install.documentationUrl,
+        },
+        login_guidance: {
+            summary: provider.guidance.login.summary,
+            commands: provider.guidance.login.commands,
+            credential_handling: provider.guidance.login.credentialHandling,
+        },
+    };
+}

package/dist/endpoint-exposure.d.ts

@@ -0,0 +1,22 @@
+export type EndpointExposureMode = "local_only" | "lan" | "tunnel" | "byo_reverse_proxy" | "misconfigured";
+export type EndpointReachability = "not_checked" | "reachable" | "unreachable";
+export interface EndpointExposureReport {
+    mode: EndpointExposureMode;
+    local_url: string;
+    public_url_configured: boolean;
+    public_url: string | null;
+    https_required_for_web: boolean;
+    https_configured: boolean;
+    web_clients_supported: boolean;
+    tunnel_provider: string | null;
+    reachable_from_web: EndpointReachability;
+    verification: {
+        method: "not_checked" | "http_head";
+        checked_url: string | null;
+        status_code: number | null;
+        error: string | null;
+    };
+    next_actions: string[];
+}
+export declare function createEndpointExposureReport(env: NodeJS.ProcessEnv, redactedPublicUrl: string | null): EndpointExposureReport;
+export declare function redactDiagnosticUrl(rawUrl: string | null): string | null;

package/dist/endpoint-exposure.js

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+const TUNNEL_HOST_PATTERNS = [
+    /cloudflare/i,
+    /trycloudflare\.com$/i,
+    /ngrok(?:-free)?\.app$/i,
+    /ngrok\.io$/i,
+    /ts\.net$/i,
+    /tailscale/i,
+];
+export function createEndpointExposureReport(env, redactedPublicUrl) {
+    const host = env.LLM_GATEWAY_HTTP_HOST || "127.0.0.1";
+    const port = Number(env.LLM_GATEWAY_HTTP_PORT || 3333);
+    const path = env.LLM_GATEWAY_HTTP_PATH || "/mcp";
+    const localHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+    const localUrl = `http://${localHost}:${port}${path}`;
+    const rawPublicUrl = env.LLM_GATEWAY_PUBLIC_URL || "";
+    const tunnelProvider = env.LLM_GATEWAY_TUNNEL_PROVIDER || inferTunnelProvider(rawPublicUrl);
+    const httpsConfigured = rawPublicUrl.startsWith("https://");
+    const publicConfigured = Boolean(redactedPublicUrl);
+    const mode = classifyEndpointMode({ host, rawPublicUrl, tunnelProvider, httpsConfigured });
+    const verification = maybeVerifyEndpoint(env, rawPublicUrl, mode);
+    const webClientsSupported = publicConfigured &&
+        httpsConfigured &&
+        mode !== "local_only" &&
+        mode !== "lan" &&
+        verification.reachable_from_web === "reachable";
+    const nextActions = [];
+    if (!publicConfigured) {
+        nextActions.push("Keep using local stdio/CLI clients, or configure an HTTPS tunnel before web-client setup.");
+    }
+    else if (mode === "local_only" || mode === "lan") {
+        nextActions.push("Set LLM_GATEWAY_PUBLIC_URL to a public HTTPS tunnel or reverse-proxy URL, not localhost or a LAN address.");
+    }
+    else if (!httpsConfigured) {
+        nextActions.push("Use an HTTPS public URL before configuring ChatGPT, Claude web, or Grok web connectors.");
+    }
+    if (publicConfigured && mode !== "local_only" && mode !== "lan") {
+        if (verification.method === "not_checked") {
+            nextActions.push("Set LLM_GATEWAY_VERIFY_PUBLIC_URL=1 to have doctor check public endpoint reachability.");
+        }
+        else if (verification.reachable_from_web === "unreachable") {
+            nextActions.push("Fix tunnel/proxy routing until the public MCP URL is reachable, then rerun doctor --json.");
+        }
+    }
+    return {
+        mode,
+        local_url: localUrl,
+        public_url_configured: publicConfigured,
+        public_url: redactedPublicUrl,
+        https_required_for_web: true,
+        https_configured: httpsConfigured,
+        web_clients_supported: webClientsSupported,
+        tunnel_provider: tunnelProvider || null,
+        reachable_from_web: verification.reachable_from_web,
+        verification: {
+            method: verification.method,
+            checked_url: verification.checked_url ? redactDiagnosticUrl(verification.checked_url) : null,
+            status_code: verification.status_code,
+            error: verification.error,
+        },
+        next_actions: nextActions,
+    };
+}
+export function redactDiagnosticUrl(rawUrl) {
+    if (!rawUrl)
+        return null;
+    const sensitiveKeyPattern = /auth|bearer|token|secret|credential|password|authorization|signature|api[_-]?key|access[_-]?key|jwt|cookie|session/i;
+    const redactSensitivePairs = (value) => value.replace(new RegExp(`((${sensitiveKeyPattern.source})=)[^&\\s#]+`, "gi"), "$1<redacted>");
+    try {
+        const url = new URL(rawUrl);
+        if (url.username)
+            url.username = "<redacted>";
+        if (url.password)
+            url.password = "<redacted>";
+        for (const key of Array.from(url.searchParams.keys())) {
+            if (sensitiveKeyPattern.test(key)) {
+                url.searchParams.set(key, "<redacted>");
+            }
+        }
+        url.hash = redactSensitivePairs(url.hash);
+        return url.toString().replace(/%3Credacted%3E/gi, "<redacted>");
+    }
+    catch {
+        return redactSensitivePairs(rawUrl.replace(/(https?:\/\/)[^/@]+@/gi, "$1<redacted>@"));
+    }
+}
+function classifyEndpointMode(input) {
+    if (!input.rawPublicUrl) {
+        if (input.host === "0.0.0.0" || input.host === "::" || isLanHost(input.host))
+            return "lan";
+        return "local_only";
+    }
+    const publicHost = publicUrlHost(input.rawPublicUrl);
+    if (!publicHost)
+        return "misconfigured";
+    if (isLoopbackHost(publicHost))
+        return "local_only";
+    if (isLanHost(publicHost))
+        return "lan";
+    if (!input.httpsConfigured)
+        return "misconfigured";
+    if (input.tunnelProvider)
+        return "tunnel";
+    return "byo_reverse_proxy";
+}
+function inferTunnelProvider(rawUrl) {
+    if (!rawUrl)
+        return "";
+    try {
+        const host = new URL(rawUrl).hostname;
+        if (TUNNEL_HOST_PATTERNS.some(pattern => pattern.test(host)))
+            return host;
+    }
+    catch {
+        // Treat unparsable URLs as not classified.
+    }
+    return "";
+}
+function isLanHost(host) {
+    const normalized = normalizeHost(host);
+    const mappedIpv4 = ipv4FromMappedIpv6(normalized);
+    if (mappedIpv4)
+        return isLanHost(mappedIpv4);
+    return (/^10\./.test(normalized) ||
+        /^192\.168\./.test(normalized) ||
+        /^172\.(1[6-9]|2\d|3[0-1])\./.test(normalized) ||
+        /^f[cd][0-9a-f]{2}:/i.test(normalized) ||
+        /^fe80:/i.test(normalized));
+}
+function isLoopbackHost(host) {
+    const normalized = normalizeHost(host);
+    const mappedIpv4 = ipv4FromMappedIpv6(normalized);
+    if (mappedIpv4)
+        return isLoopbackHost(mappedIpv4);
+    return (normalized === "localhost" ||
+        normalized === "0.0.0.0" ||
+        normalized === "::" ||
+        normalized === "::1" ||
+        /^127\./.test(normalized));
+}
+function publicUrlHost(rawUrl) {
+    try {
+        return normalizeHost(new URL(rawUrl).hostname);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeHost(host) {
+    return host.toLowerCase().replace(/^\[|\]$/g, "");
+}
+function ipv4FromMappedIpv6(host) {
+    const dotted = host.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i);
+    if (dotted)
+        return dotted[1];
+    const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (!hex)
+        return null;
+    const high = Number.parseInt(hex[1], 16);
+    const low = Number.parseInt(hex[2], 16);
+    if (!Number.isFinite(high) || !Number.isFinite(low))
+        return null;
+    return `${(high >> 8) & 255}.${high & 255}.${(low >> 8) & 255}.${low & 255}`;
+}
+function maybeVerifyEndpoint(env, rawPublicUrl, mode) {
+    if (!rawPublicUrl || env.LLM_GATEWAY_VERIFY_PUBLIC_URL !== "1") {
+        return {
+            method: "not_checked",
+            checked_url: rawPublicUrl || null,
+            status_code: null,
+            error: null,
+            reachable_from_web: "not_checked",
+        };
+    }
+    if (mode === "local_only" || mode === "lan") {
+        return {
+            method: "not_checked",
+            checked_url: rawPublicUrl,
+            status_code: null,
+            error: "Public URL points to localhost or a private LAN address.",
+            reachable_from_web: "unreachable",
+        };
+    }
+    const result = verifyEndpointSync(rawPublicUrl, 3_000);
+    return {
+        method: "http_head",
+        checked_url: rawPublicUrl,
+        status_code: result.statusCode,
+        error: result.error,
+        reachable_from_web: result.ok ? "reachable" : "unreachable",
+    };
+}
+function verifyEndpointSync(url, timeoutMs) {
+    const script = `
+    const { request: http } = require("node:http");
+    const { request: https } = require("node:https");
+    const target = new URL(process.argv[1]);
+    const timeout = Number(process.argv[2]);
+    const requester = target.protocol === "https:" ? https : http;
+    const req = requester(target, { method: "HEAD", timeout, headers: { accept: "application/json, text/event-stream" } }, res => {
+      res.resume();
+      const statusCode = res.statusCode || 0;
+      const endpointFound = statusCode < 500 && statusCode !== 404;
+      console.log(JSON.stringify({ ok: endpointFound, statusCode: res.statusCode, error: null }));
+    });
+    req.on("timeout", () => {
+      req.destroy(new Error("Endpoint verification timed out."));
+    });
+    req.on("error", err => {
+      console.log(JSON.stringify({ ok: false, statusCode: null, error: err.message }));
+    });
+    req.end();
+  `;
+    const result = spawnSync(process.execPath, ["-e", script, url, String(timeoutMs)], {
+        encoding: "utf8",
+        timeout: timeoutMs + 1_000,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            statusCode: null,
+            error: result.error.message,
+        };
+    }
+    try {
+        return JSON.parse(result.stdout.trim());
+    }
+    catch {
+        return { ok: false, statusCode: null, error: "Endpoint verification failed." };
+    }
+}

package/dist/executor.d.ts

@@ -5,6 +5,8 @@ export interface ExecuteOptions {
     idleTimeout?: number;
     cwd?: string;
     logger?: Logger;
+    /** Extra environment variables to inject; merged after PATH. */
+    env?: NodeJS.ProcessEnv;
 }
 export interface ExecuteResult {
     stdout: string;

package/dist/executor.js

@@ -125,7 +125,7 @@ export function killProcessGroup(proc, signal) {
     }
 }
 export async function executeCli(command, args, options = {}) {
-    const { timeout, idleTimeout, cwd } = options;
+    const { timeout, idleTimeout, cwd, env: extraEnv } = options;
     const extendedPath = getExtendedPath();
     const circuitBreaker = getCircuitBreaker(command);
     const runOnce = () => new Promise((resolve, reject) => {
@@ -133,7 +133,7 @@ export async function executeCli(command, args, options = {}) {
             cwd,
             detached: true,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, PATH: extendedPath },
+            env: { ...process.env, PATH: extendedPath, ...(extraEnv ?? {}) },
         });
         if (proc.pid)
             registerProcessGroup(proc.pid);

package/dist/flight-recorder.d.ts

@@ -1,6 +1,6 @@
 export interface FlightLogStart {
     correlationId: string;
-    cli: "claude" | "codex" | "gemini" | "grok";
+    cli: "claude" | "codex" | "gemini" | "grok" | "mistral";
     model: string;
     prompt: string;
     system?: string;
@@ -11,6 +11,8 @@ export interface FlightLogResult {
     response: string;
     inputTokens?: number;
     outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
     durationMs: number;
     retryCount: number;
     circuitBreakerState: string;

package/dist/flight-recorder.js

@@ -3,6 +3,21 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 const MAX_THINKING_BYTES = 1_000_000;
+/**
+ * Idempotent migration: add `cache_read_tokens` / `cache_creation_tokens`
+ * columns to the `requests` table if a pre-U23 logs.db is opened. Existing
+ * rows keep NULL for the new columns; that is intentional.
+ */
+function ensureRequestsCacheColumns(db) {
+    const rows = db.prepare("PRAGMA table_info(requests)").all?.() ?? [];
+    const names = new Set(rows.map((row) => (row && typeof row.name === "string" ? row.name : "")));
+    if (!names.has("cache_read_tokens")) {
+        db.exec("ALTER TABLE requests ADD COLUMN cache_read_tokens INTEGER");
+    }
+    if (!names.has("cache_creation_tokens")) {
+        db.exec("ALTER TABLE requests ADD COLUMN cache_creation_tokens INTEGER");
+    }
+}
 export function resolveFlightRecorderDbPath() {
     const configured = process.env.LLM_GATEWAY_LOGS_DB;
     if (configured !== undefined) {
@@ -80,7 +95,9 @@ export class FlightRecorder {
         duration_ms INTEGER,
         datetime_utc TEXT NOT NULL,
         input_tokens INTEGER,
-        output_tokens INTEGER
+        output_tokens INTEGER,
+        cache_read_tokens INTEGER,
+        cache_creation_tokens INTEGER
       );
 
       CREATE TABLE IF NOT EXISTS gateway_metadata (
@@ -106,6 +123,14 @@ export class FlightRecorder {
         this.db
             .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(1, ?)")
             .run(new Date().toISOString());
+        // Migration v2: cache_read_tokens / cache_creation_tokens columns on
+        // pre-U23 logs.db files. ALTER TABLE ADD COLUMN is idempotent only via
+        // a prior PRAGMA table_info() check; better-sqlite3 has no native
+        // "IF NOT EXISTS" for ADD COLUMN.
+        ensureRequestsCacheColumns(this.db);
+        this.db
+            .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(2, ?)")
+            .run(new Date().toISOString());
         if (process.platform !== "win32") {
             try {
                 chmodSync(dbPath, 0o600);
@@ -142,7 +167,9 @@ export class FlightRecorder {
       SET response = @response,
           duration_ms = @duration_ms,
           input_tokens = @input_tokens,
-          output_tokens = @output_tokens
+          output_tokens = @output_tokens,
+          cache_read_tokens = @cache_read_tokens,
+          cache_creation_tokens = @cache_creation_tokens
       WHERE id = @id
     `);
         const updateMetadata = this.db.prepare(`
@@ -168,6 +195,8 @@ export class FlightRecorder {
                 duration_ms: result.durationMs,
                 input_tokens: result.inputTokens ?? null,
                 output_tokens: result.outputTokens ?? null,
+                cache_read_tokens: result.cacheReadTokens ?? null,
+                cache_creation_tokens: result.cacheCreationTokens ?? null,
             });
             updateMetadata.run({
                 id: correlationId,

package/dist/gateway-server.d.ts

@@ -0,0 +1,2 @@
+export type { GatewayServerDeps } from "./index.js";
+export { createGatewayServer } from "./index.js";

package/dist/gateway-server.js

@@ -0,0 +1 @@
+export { createGatewayServer } from "./index.js";

package/dist/gemini-json-parser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Parser for Gemini CLI `-o json` output.
+ *
+ * Gemini emits a single JSON object with:
+ *   - `response`: string final model output
+ *   - `usageMetadata`: { promptTokenCount, candidatesTokenCount,
+ *                        cachedContentTokenCount?, totalTokenCount }
+ *
+ * Returns null when stdout is not parseable as JSON. Returns an object with
+ * only `response` when usageMetadata is missing.
+ */
+export interface GeminiUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens?: number;
+}
+export interface GeminiJsonParseResult {
+    usage?: GeminiUsage;
+    response?: string;
+}
+export declare function parseGeminiJson(stdout: string): GeminiJsonParseResult | null;