llm-cli-gateway 1.4.0 → 1.5.13

package/dist/codex-json-parser.js

@@ -0,0 +1,105 @@
+/**
+ * Parser for Codex CLI `--json` JSONL event stream.
+ *
+ * Codex emits one JSON object per line, e.g.:
+ *   {"type":"thread.started","thread_id":"t-abc"}
+ *   {"type":"turn.started","turn_id":"u-001"}
+ *   {"type":"item.started","item":{...}}
+ *   {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ *   {"type":"turn.completed","usage":{"input_tokens":...,"output_tokens":...,...}}
+ *   {"type":"turn.failed","error":{...}}
+ *   {"type":"error","message":"..."}
+ *
+ * This parser is lenient: malformed lines are skipped, partial streams are
+ * tolerated (usage is `undefined` if no turn.completed event arrived), and
+ * error events are surfaced.
+ *
+ * Cost is intentionally NOT computed here — Codex does not price client-side
+ * and U23 only plumbs tokens. A future unit can compute cost from the model
+ * registry.
+ */
+export function parseCodexJsonStream(stdout) {
+    const lines = stdout.split("\n").filter(line => line.trim().length > 0);
+    const result = {};
+    let lastAgentMessage;
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            // Skip preamble/garbage lines that aren't valid JSON.
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object") {
+            continue;
+        }
+        switch (parsed.type) {
+            case "thread.started":
+                if (typeof parsed.thread_id === "string") {
+                    result.threadId = parsed.thread_id;
+                }
+                break;
+            case "turn.completed": {
+                const u = parsed.usage;
+                if (u && typeof u === "object") {
+                    const usage = {
+                        input_tokens: typeof u.input_tokens === "number" ? u.input_tokens : 0,
+                        output_tokens: typeof u.output_tokens === "number" ? u.output_tokens : 0,
+                    };
+                    if (typeof u.cache_read_input_tokens === "number") {
+                        usage.cache_read_tokens = u.cache_read_input_tokens;
+                    }
+                    else if (typeof u.cache_read_tokens === "number") {
+                        usage.cache_read_tokens = u.cache_read_tokens;
+                    }
+                    if (typeof u.cache_creation_input_tokens === "number") {
+                        usage.cache_creation_tokens = u.cache_creation_input_tokens;
+                    }
+                    else if (typeof u.cache_creation_tokens === "number") {
+                        usage.cache_creation_tokens = u.cache_creation_tokens;
+                    }
+                    if (typeof u.cost_usd === "number") {
+                        usage.cost_usd = u.cost_usd;
+                    }
+                    result.usage = usage;
+                }
+                break;
+            }
+            case "turn.failed": {
+                const err = parsed.error;
+                if (typeof err === "string") {
+                    result.error = err;
+                }
+                else if (err && typeof err === "object" && typeof err.message === "string") {
+                    result.error = err.message;
+                }
+                else {
+                    result.error = "turn failed";
+                }
+                break;
+            }
+            case "error":
+                if (typeof parsed.message === "string") {
+                    result.error = parsed.message;
+                }
+                break;
+            case "item.completed": {
+                const item = parsed.item;
+                if (item &&
+                    typeof item === "object" &&
+                    item.type === "agent_message" &&
+                    typeof item.text === "string") {
+                    lastAgentMessage = item.text;
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (lastAgentMessage !== undefined) {
+        result.finalMessage = lastAgentMessage;
+    }
+    return result;
+}

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "./logger.js";
 export interface CacheTtl {
     session: number;
     activeSession: number;
@@ -33,3 +34,32 @@ export interface Config {
  * Database and Redis fields are populated only when both env vars are set.
  */
 export declare function loadConfig(): Config;
+export declare const PERSISTENCE_BACKENDS: readonly ["sqlite", "postgres", "memory", "none"];
+export type PersistenceBackend = (typeof PERSISTENCE_BACKENDS)[number];
+export declare const DEFAULT_JOB_RETENTION_DAYS = 30;
+export declare const DEFAULT_DEDUP_WINDOW_MS: number;
+export interface PersistenceConfig {
+    backend: PersistenceBackend;
+    path: string | null;
+    dsn: string | null;
+    retentionDays: number;
+    dedupWindowMs: number;
+    acknowledgeEphemeral: boolean;
+    /** True iff async-job tools should be registered on the MCP server. */
+    asyncJobsEnabled: boolean;
+    /** Audit trail: which inputs (file, env vars) contributed to the resolved config. */
+    sources: PersistenceConfigSources;
+}
+export interface PersistenceConfigSources {
+    configFile: string | null;
+    envOverrides: string[];
+}
+/**
+ * Load and validate the persistence config from (in order, last-write-wins):
+ *   1. Built-in defaults (backend=sqlite, default retention/dedup).
+ *   2. ~/.llm-cli-gateway/config.toml (or $LLM_GATEWAY_CONFIG).
+ *   3. Legacy env vars (with deprecation warning).
+ *
+ * Throws on incoherent configs (memory/none + asyncJobsEnabled without ack).
+ */
+export declare function loadPersistenceConfig(logger?: Logger): PersistenceConfig;

package/dist/config.js

@@ -1,4 +1,9 @@
+import { existsSync, readFileSync } from "fs";
+import os from "os";
+import path from "path";
+import { createRequire } from "module";
 import { z } from "zod";
+import { logWarn, noopLogger } from "./logger.js";
 // Zod schemas for configuration validation
 const DatabaseUrlSchema = z
     .string()
@@ -60,3 +65,165 @@ export function loadConfig() {
         sessionTtl,
     };
 }
+//──────────────────────────────────────────────────────────────────────────────
+// Persistence configuration
+//
+// The async job store is now driven by a typed config (TOML file +
+// validated env-var overrides) instead of a single LLM_GATEWAY_LOGS_DB env
+// var. The structural invariant: `*_request_async` tools are only registered
+// when a real durable store is attached, so silent in-memory loss after the
+// 1h TTL becomes impossible.
+//
+// Backends:
+//   - "sqlite":   durable on disk (default).
+//   - "postgres": durable in Postgres (interface only — impl not yet shipped).
+//   - "memory":   in-process MemoryJobStore. Process-lifetime durability only.
+//                 Requires acknowledgeEphemeral=true to register async tools.
+//   - "none":     no store. Async tools are NOT registered.
+//──────────────────────────────────────────────────────────────────────────────
+export const PERSISTENCE_BACKENDS = ["sqlite", "postgres", "memory", "none"];
+export const DEFAULT_JOB_RETENTION_DAYS = 30;
+export const DEFAULT_DEDUP_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+const PersistenceSchema = z
+    .object({
+    backend: z.enum(PERSISTENCE_BACKENDS).default("sqlite"),
+    path: z.string().optional(),
+    dsn: z.string().optional(),
+    retentionDays: z.number().positive().default(DEFAULT_JOB_RETENTION_DAYS),
+    dedupWindowMs: z.number().int().nonnegative().default(DEFAULT_DEDUP_WINDOW_MS),
+    acknowledgeEphemeral: z.boolean().default(false),
+})
+    .strict();
+const DEFAULT_SQLITE_PATH = path.join(os.homedir(), ".llm-cli-gateway", "logs.db");
+function defaultPersistenceConfigPath() {
+    return (process.env.LLM_GATEWAY_CONFIG ?? path.join(os.homedir(), ".llm-cli-gateway", "config.toml"));
+}
+/**
+ * Read and parse the optional TOML config file. Returns the raw `[persistence]`
+ * table (if present) and the file path. Missing file is fine — defaults apply.
+ */
+function readPersistenceFile(configPath, logger) {
+    if (!existsSync(configPath)) {
+        return { raw: undefined, sourcePath: null };
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const TOML = require("toml");
+        const text = readFileSync(configPath, "utf-8");
+        const parsed = TOML.parse(text);
+        return { raw: parsed?.persistence, sourcePath: configPath };
+    }
+    catch (err) {
+        logger.error(`Failed to parse gateway config at ${configPath}; using defaults`, err);
+        return { raw: undefined, sourcePath: null };
+    }
+}
+/**
+ * Apply legacy env-var overrides on top of the file/defaults. Each application
+ * appends a string to `sources.envOverrides` and emits a one-time deprecation
+ * warning so operators can migrate to the config file.
+ */
+function applyEnvOverrides(base, logger, sources) {
+    const out = { ...base };
+    const jobsDbEnv = process.env.LLM_GATEWAY_JOBS_DB;
+    const logsDbEnv = process.env.LLM_GATEWAY_LOGS_DB;
+    // Empty string is treated as "not set" — only an explicitly non-empty value
+    // (or the literal "none") overrides the file/defaults. This avoids the
+    // old footgun where `LLM_GATEWAY_LOGS_DB=` silently disabled persistence.
+    const dbEnvRaw = jobsDbEnv && jobsDbEnv.length > 0
+        ? jobsDbEnv
+        : logsDbEnv && logsDbEnv.length > 0
+            ? logsDbEnv
+            : undefined;
+    if (dbEnvRaw !== undefined) {
+        const normalized = dbEnvRaw.trim().toLowerCase();
+        if (normalized === "none") {
+            out.backend = "none";
+            out.path = undefined;
+        }
+        else {
+            out.backend = "sqlite";
+            out.path = dbEnvRaw.trim();
+        }
+        const which = jobsDbEnv && jobsDbEnv.length > 0 ? "LLM_GATEWAY_JOBS_DB" : "LLM_GATEWAY_LOGS_DB";
+        sources.envOverrides.push(which);
+        logWarn(logger, `${which} is deprecated; migrate to [persistence] in ~/.llm-cli-gateway/config.toml`, { backend: out.backend, path: out.path ?? null });
+    }
+    const retEnv = process.env.LLM_GATEWAY_JOB_RETENTION_DAYS;
+    if (retEnv !== undefined) {
+        const n = Number(retEnv);
+        if (Number.isFinite(n) && n > 0) {
+            out.retentionDays = n;
+            sources.envOverrides.push("LLM_GATEWAY_JOB_RETENTION_DAYS");
+            logWarn(logger, "LLM_GATEWAY_JOB_RETENTION_DAYS is deprecated; set [persistence].retentionDays in config.toml", { retentionDays: n });
+        }
+    }
+    const dedupEnv = process.env.LLM_GATEWAY_DEDUP_WINDOW_MS;
+    if (dedupEnv !== undefined) {
+        const n = Number(dedupEnv);
+        if (Number.isFinite(n) && n >= 0) {
+            out.dedupWindowMs = n;
+            sources.envOverrides.push("LLM_GATEWAY_DEDUP_WINDOW_MS");
+            logWarn(logger, "LLM_GATEWAY_DEDUP_WINDOW_MS is deprecated; set [persistence].dedupWindowMs in config.toml", { dedupWindowMs: n });
+        }
+    }
+    const ackEnv = process.env.LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL;
+    if (ackEnv && ackEnv.length > 0) {
+        out.acknowledgeEphemeral = /^(1|true|yes)$/i.test(ackEnv.trim());
+        sources.envOverrides.push("LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL");
+        logWarn(logger, "LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL is deprecated; set [persistence].acknowledgeEphemeral in config.toml", { acknowledgeEphemeral: out.acknowledgeEphemeral });
+    }
+    return out;
+}
+function expandHome(p) {
+    return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+/**
+ * Load and validate the persistence config from (in order, last-write-wins):
+ *   1. Built-in defaults (backend=sqlite, default retention/dedup).
+ *   2. ~/.llm-cli-gateway/config.toml (or $LLM_GATEWAY_CONFIG).
+ *   3. Legacy env vars (with deprecation warning).
+ *
+ * Throws on incoherent configs (memory/none + asyncJobsEnabled without ack).
+ */
+export function loadPersistenceConfig(logger = noopLogger) {
+    const configPath = defaultPersistenceConfigPath();
+    const { raw, sourcePath } = readPersistenceFile(configPath, logger);
+    const sources = {
+        configFile: sourcePath,
+        envOverrides: [],
+    };
+    const merged = applyEnvOverrides(raw ?? {}, logger, sources);
+    let parsed;
+    try {
+        parsed = PersistenceSchema.parse(merged);
+    }
+    catch (err) {
+        throw new Error(`Invalid [persistence] config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const backend = parsed.backend;
+    const resolvedPath = backend === "sqlite" ? expandHome(parsed.path ?? DEFAULT_SQLITE_PATH) : null;
+    const dsn = backend === "postgres" ? (parsed.dsn ?? null) : null;
+    if (backend === "postgres" && !dsn) {
+        throw new Error("[persistence].backend = 'postgres' requires a non-empty 'dsn' (e.g. postgresql://user:pw@host/db)");
+    }
+    if (backend === "memory" && !parsed.acknowledgeEphemeral) {
+        throw new Error("[persistence].backend = 'memory' is ephemeral — async job results are lost on gateway exit. " +
+            "Set [persistence].acknowledgeEphemeral = true (or LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL=1) to confirm this is intentional.");
+    }
+    const asyncJobsEnabled = backend === "sqlite" || backend === "postgres" || backend === "memory";
+    if (backend === "none") {
+        logWarn(logger, "Async job persistence is DISABLED (backend = 'none'). " +
+            "*_request_async tools will NOT be registered on this gateway.");
+    }
+    return {
+        backend,
+        path: resolvedPath,
+        dsn,
+        retentionDays: parsed.retentionDays,
+        dedupWindowMs: parsed.dedupWindowMs,
+        acknowledgeEphemeral: parsed.acknowledgeEphemeral,
+        asyncJobsEnabled,
+        sources,
+    };
+}

package/dist/doctor.d.ts

@@ -0,0 +1,110 @@
+import { type EndpointExposureReport } from "./endpoint-exposure.js";
+import { type ProviderLoginStatus } from "./provider-status.js";
+export interface VibeSessionLoggingStatus {
+    config_path: string;
+    config_present: boolean;
+    session_logging_enabled: boolean;
+    note: string;
+}
+export interface GeminiConfigStatus {
+    /** Presence of a project-local `GEMINI.md` in the gateway's cwd. */
+    project_gemini_md_present: boolean;
+    project_gemini_md_path: string;
+    /** Presence of `~/.gemini/GEMINI.md`. */
+    user_gemini_md_present: boolean;
+    user_gemini_md_path: string;
+    /** Presence and contents of `~/.gemini/settings.json` `mcpServers` block. */
+    settings_json_present: boolean;
+    settings_json_path: string;
+    mcp_servers_registered: string[];
+    /** Per-server reconciliation against the gateway's `--allowed-mcp-server-names` whitelist. */
+    mcp_reconciliation: {
+        whitelisted: string[];
+        missing_from_settings: string[];
+    };
+    next_actions: string[];
+}
+/**
+ * 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 declare function checkVibeSessionLogging(home?: string): VibeSessionLoggingStatus;
+/**
+ * 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 declare function checkGeminiConfig(cwd?: string, home?: string, whitelist?: readonly string[]): GeminiConfigStatus;
+export interface DoctorReport {
+    schema_version: "1.0";
+    ok: boolean;
+    generated_at: string;
+    system: {
+        os: NodeJS.Platform;
+        arch: string;
+        release: string;
+        node_version: string;
+    };
+    gateway: {
+        name: string;
+        version: string;
+    };
+    transport: {
+        default: "stdio" | "http";
+        http: {
+            enabled: boolean;
+            host: string;
+            port: number;
+            path: string;
+            public_url_configured: boolean;
+            public_url: string | null;
+        };
+    };
+    auth: {
+        required: boolean;
+        token_configured: boolean;
+        source: string;
+    };
+    providers: Record<"claude" | "codex" | "gemini" | "grok" | "mistral", {
+        cli_available: boolean;
+        version: string | null;
+        login_status: ProviderLoginStatus;
+        version_command: string[];
+        login_check: {
+            method: "cli" | "credential_store" | "not_checked";
+            command: string[] | null;
+            credential_store: "present" | "not_found" | "not_checked";
+            detail: string;
+        };
+        install_guidance: {
+            summary: string;
+            commands: string[];
+            documentation_url?: string;
+        };
+        login_guidance: {
+            summary: string;
+            commands: string[];
+            credential_handling: string;
+        };
+    }>;
+    endpoint_exposure: EndpointExposureReport;
+    client_config: {
+        claude_desktop_config_present: boolean;
+        codex_config_present: boolean;
+        gemini_settings_present: boolean;
+        gemini_config: GeminiConfigStatus;
+        vibe_session_logging: VibeSessionLoggingStatus;
+    };
+    next_actions: string[];
+}
+export declare function createDoctorReport(env?: NodeJS.ProcessEnv): DoctorReport;
+export declare function printDoctorJson(): void;