llm-cli-gateway 1.0.1 → 1.4.0

package/dist/config.js

@@ -1,6 +1,11 @@
 import { z } from "zod";
 // Zod schemas for configuration validation
-const DatabaseUrlSchema = z.string().url().refine((url) => url.startsWith("postgresql://") || url.startsWith("postgres://"), { message: "Database URL must start with postgresql:// or postgres://" });
+const DatabaseUrlSchema = z
+    .string()
+    .url()
+    .refine(url => url.startsWith("postgresql://") || url.startsWith("postgres://"), {
+    message: "Database URL must start with postgresql:// or postgres://",
+});
 const RedisUrlSchema = z.string().url().startsWith("redis://");
 export const DEFAULT_SESSION_TTL_SECONDS = 2592000; // 30 days
 /**
@@ -15,11 +20,12 @@ export function loadConfig() {
     const cacheTtl = {
         session: 3600, // 1 hour
         activeSession: 1800, // 30 minutes
-        sessionList: 120 // 2 minutes
+        sessionList: 120, // 2 minutes
     };
     const rawSessionTtl = parseInt(process.env.SESSION_TTL || String(DEFAULT_SESSION_TTL_SECONDS), 10);
-    const sessionTtl = (Number.isFinite(rawSessionTtl) && rawSessionTtl > 0)
-        ? rawSessionTtl : DEFAULT_SESSION_TTL_SECONDS;
+    const sessionTtl = Number.isFinite(rawSessionTtl) && rawSessionTtl > 0
+        ? rawSessionTtl
+        : DEFAULT_SESSION_TTL_SECONDS;
     // If no database config, return base config (file-based storage)
     if (!databaseUrl || !redisUrl) {
         return { cacheTtl, sessionTtl };
@@ -39,18 +45,18 @@ export function loadConfig() {
                 max: 10,
                 idleTimeoutMillis: 30000,
                 connectionTimeoutMillis: 5000,
-                statementTimeout: 10000
-            }
+                statementTimeout: 10000,
+            },
         },
         redis: {
             url: redisUrl,
             retryStrategy: {
                 maxRetries: 3,
                 initialDelay: 50,
-                maxDelay: 2000
-            }
+                maxDelay: 2000,
+            },
         },
         cacheTtl,
-        sessionTtl
+        sessionTtl,
     };
 }

package/dist/db.js

@@ -26,7 +26,7 @@ export class DatabaseConnection {
             max: this.config.database.pool.max,
             idleTimeoutMillis: this.config.database.pool.idleTimeoutMillis,
             connectionTimeoutMillis: this.config.database.pool.connectionTimeoutMillis,
-            statement_timeout: this.config.database.pool.statementTimeout
+            statement_timeout: this.config.database.pool.statementTimeout,
         };
         this.pool = new Pool(poolConfig);
         // Test PostgreSQL connection
@@ -54,7 +54,7 @@ export class DatabaseConnection {
                 // Reconnect on READONLY and ECONNRESET errors
                 const targetErrors = ["READONLY", "ECONNRESET"];
                 return targetErrors.some(targetError => err.message.includes(targetError));
-            }
+            },
         };
         this.redis = new Redis(this.config.redis.url, redisOptions);
         // Test Redis connection
@@ -101,7 +101,7 @@ export class DatabaseConnection {
     async healthCheck() {
         const result = {
             postgres: { connected: false, latency: 0 },
-            redis: { connected: false, latency: 0 }
+            redis: { connected: false, latency: 0 },
         };
         // Check PostgreSQL
         if (this.pool) {
@@ -137,7 +137,7 @@ export class DatabaseConnection {
         }
         this.logger.debug("Health check completed", {
             postgres: result.postgres.connected,
-            redis: result.redis.connected
+            redis: result.redis.connected,
         });
         return result;
     }

package/dist/executor.js

@@ -28,7 +28,7 @@ function getNvmPath() {
     try {
         const versions = readdirSync(nvmVersionsDir);
         cachedNvmPath = versions.length
-            ? versions.map((version) => join(nvmVersionsDir, version, "bin")).join(":")
+            ? versions.map(version => join(nvmVersionsDir, version, "bin")).join(":")
             : null;
     }
     catch {
@@ -43,7 +43,7 @@ export function getExtendedPath() {
         join(home, ".local/bin"),
         dirname(process.execPath), // Current node's bin directory
         "/usr/local/bin",
-        "/usr/bin"
+        "/usr/bin",
     ];
     // Add all nvm node version bin directories
     const nvmPath = getNvmPath();
@@ -75,7 +75,9 @@ export function killAllProcessGroups() {
         try {
             process.kill(-pid, "SIGTERM");
         }
-        catch { /* ESRCH ok */ }
+        catch {
+            /* ESRCH ok */
+        }
     }
     return new Promise(resolve => {
         setTimeout(() => {
@@ -83,7 +85,9 @@ export function killAllProcessGroups() {
                 try {
                     process.kill(-pid, "SIGKILL");
                 }
-                catch { /* ESRCH ok */ }
+                catch {
+                    /* ESRCH ok */
+                }
             }
             activeProcessGroups.clear();
             resolve();
@@ -129,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 },
         });
         if (proc.pid)
             registerProcessGroup(proc.pid);
@@ -152,7 +156,9 @@ export async function executeCli(command, args, options = {}) {
             if (proc.pid)
                 unregisterProcessGroup(proc.pid);
         };
-        const timeoutMs = typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0 ? timeout : undefined;
+        const timeoutMs = typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
+            ? timeout
+            : undefined;
         const timeoutId = timeoutMs
             ? setTimeout(() => {
                 timedOut = true;
@@ -166,7 +172,8 @@ export async function executeCli(command, args, options = {}) {
             : undefined;
         // Idle timeout: kill process if no stdout/stderr activity for idleMs
         const idleMs = typeof idleTimeout === "number" && Number.isFinite(idleTimeout) && idleTimeout > 0
-            ? idleTimeout : undefined;
+            ? idleTimeout
+            : undefined;
         let idleTimerId;
         const resetIdleTimer = () => {
             if (!idleMs)
@@ -222,19 +229,19 @@ export async function executeCli(command, args, options = {}) {
                 stderr += text;
             }
         };
-        proc.stdout.on("data", (data) => {
+        proc.stdout.on("data", data => {
             if (settled) {
                 return;
             }
             handleOutputChunk(data, "stdout");
         });
-        proc.stderr.on("data", (data) => {
+        proc.stderr.on("data", data => {
             if (settled) {
                 return;
             }
             handleOutputChunk(data, "stderr");
         });
-        proc.on("close", (code) => {
+        proc.on("close", code => {
             exited = true;
             if (idleTimerId) {
                 clearTimeout(idleTimerId);
@@ -253,7 +260,7 @@ export async function executeCli(command, args, options = {}) {
                 const result = {
                     stdout,
                     stderr: stderr + `\nProcess timed out after ${timeoutMs}ms`,
-                    code: 124 // Standard timeout exit code
+                    code: 124, // Standard timeout exit code
                 };
                 const error = new Error(result.stderr);
                 error.code = 124;
@@ -265,7 +272,7 @@ export async function executeCli(command, args, options = {}) {
                 const result = {
                     stdout,
                     stderr: stderr + `\nProcess killed after ${idleMs}ms of inactivity`,
-                    code: 125
+                    code: 125,
                 };
                 const error = new Error(result.stderr);
                 error.code = 125;
@@ -283,7 +290,7 @@ export async function executeCli(command, args, options = {}) {
             }
             resolve(result);
         });
-        proc.on("error", (err) => {
+        proc.on("error", err => {
             exited = true;
             if (idleTimerId) {
                 clearTimeout(idleTimerId);

package/dist/flight-recorder.d.ts

@@ -0,0 +1,48 @@
+export interface FlightLogStart {
+    correlationId: string;
+    cli: "claude" | "codex" | "gemini" | "grok";
+    model: string;
+    prompt: string;
+    system?: string;
+    sessionId?: string;
+    asyncJobId?: string;
+}
+export interface FlightLogResult {
+    response: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    durationMs: number;
+    retryCount: number;
+    circuitBreakerState: string;
+    costUsd?: number;
+    approvalDecision?: string;
+    optimizationApplied: boolean;
+    thinkingBlocks?: string[];
+    exitCode: number;
+    errorMessage?: string;
+    status: "completed" | "failed";
+}
+interface LoggerLike {
+    info: (message: string, ...args: any[]) => void;
+    error: (message: string, ...args: any[]) => void;
+}
+export declare function resolveFlightRecorderDbPath(): string | null;
+export declare class FlightRecorder {
+    private db;
+    private insertStartTxn;
+    private updateCompleteTxn;
+    constructor(dbPath: string);
+    logStart(entry: FlightLogStart): void;
+    logComplete(correlationId: string, result: FlightLogResult): void;
+    flush(): void;
+    close(): void;
+}
+export declare class NoopFlightRecorder {
+    logStart(_entry: FlightLogStart): void;
+    logComplete(_correlationId: string, _result: FlightLogResult): void;
+    flush(): void;
+    close(): void;
+}
+export type FlightRecorderLike = FlightRecorder | NoopFlightRecorder;
+export declare function createFlightRecorder(logger: LoggerLike): FlightRecorderLike;
+export {};

package/dist/flight-recorder.js

@@ -0,0 +1,220 @@
+import { chmodSync, existsSync, mkdirSync } from "fs";
+import os from "os";
+import path from "path";
+import { createRequire } from "module";
+const MAX_THINKING_BYTES = 1_000_000;
+export function resolveFlightRecorderDbPath() {
+    const configured = process.env.LLM_GATEWAY_LOGS_DB;
+    if (configured !== undefined) {
+        const normalized = configured.trim().toLowerCase();
+        if (!normalized || normalized === "none") {
+            return null;
+        }
+        return configured.trim();
+    }
+    return path.join(os.homedir(), ".llm-cli-gateway", "logs.db");
+}
+const TRUNCATION_SUFFIX = "[TRUNCATED]";
+const TRUNCATION_SUFFIX_BYTES = Buffer.byteLength(TRUNCATION_SUFFIX, "utf8");
+function truncateThinkingBlocks(blocks) {
+    const result = [];
+    let used = 0;
+    for (const block of blocks) {
+        const bytes = Buffer.byteLength(block, "utf8");
+        if (used + bytes <= MAX_THINKING_BYTES) {
+            result.push(block);
+            used += bytes;
+            continue;
+        }
+        // Reserve space for the suffix so total stays within budget
+        const budget = Math.max(0, MAX_THINKING_BYTES - used - TRUNCATION_SUFFIX_BYTES);
+        if (budget > 0) {
+            // Truncate on code point boundaries by using string iteration
+            let charBytes = 0;
+            let safeEnd = 0;
+            for (const char of block) {
+                const charSize = Buffer.byteLength(char, "utf8");
+                if (charBytes + charSize > budget)
+                    break;
+                charBytes += charSize;
+                safeEnd += char.length; // char.length handles surrogate pairs
+            }
+            const sliced = block.slice(0, safeEnd);
+            result.push(sliced ? `${sliced}${TRUNCATION_SUFFIX}` : TRUNCATION_SUFFIX);
+        }
+        else {
+            result.push(TRUNCATION_SUFFIX);
+        }
+        break;
+    }
+    return result;
+}
+export class FlightRecorder {
+    db;
+    insertStartTxn;
+    updateCompleteTxn;
+    constructor(dbPath) {
+        const require = createRequire(import.meta.url);
+        const BetterSqlite3 = require("better-sqlite3");
+        const directory = path.dirname(dbPath);
+        if (!existsSync(directory)) {
+            mkdirSync(directory, { recursive: true });
+        }
+        this.db = new BetterSqlite3(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("foreign_keys = ON");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _migrations (
+        version INTEGER PRIMARY KEY,
+        applied_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS requests (
+        id TEXT PRIMARY KEY,
+        cli TEXT NOT NULL,
+        model TEXT NOT NULL,
+        prompt TEXT NOT NULL,
+        system TEXT,
+        response TEXT,
+        session_id TEXT,
+        duration_ms INTEGER,
+        datetime_utc TEXT NOT NULL,
+        input_tokens INTEGER,
+        output_tokens INTEGER
+      );
+
+      CREATE TABLE IF NOT EXISTS gateway_metadata (
+        request_id TEXT PRIMARY KEY REFERENCES requests(id),
+        retry_count INTEGER DEFAULT 0,
+        circuit_breaker_state TEXT,
+        cost_usd REAL,
+        approval_decision TEXT,
+        optimization_applied INTEGER DEFAULT 0,
+        thinking_blocks TEXT,
+        exit_code INTEGER,
+        error_message TEXT,
+        async_job_id TEXT,
+        status TEXT NOT NULL DEFAULT 'started'
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_requests_datetime ON requests(datetime_utc);
+      CREATE INDEX IF NOT EXISTS idx_requests_model ON requests(model);
+      CREATE INDEX IF NOT EXISTS idx_requests_cli ON requests(cli);
+      CREATE INDEX IF NOT EXISTS idx_requests_session ON requests(session_id);
+      CREATE INDEX IF NOT EXISTS idx_metadata_status ON gateway_metadata(status);
+    `);
+        this.db
+            .prepare("INSERT OR IGNORE INTO _migrations(version, applied_at) VALUES(1, ?)")
+            .run(new Date().toISOString());
+        if (process.platform !== "win32") {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch {
+                // Best effort permissions hardening.
+            }
+        }
+        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)
+    `);
+        const insertMetadata = this.db.prepare(`
+      INSERT INTO gateway_metadata (request_id, async_job_id, status)
+      VALUES (@request_id, @async_job_id, 'started')
+    `);
+        this.insertStartTxn = this.db.transaction((entry) => {
+            insertRequest.run({
+                id: entry.correlationId,
+                cli: entry.cli,
+                model: entry.model,
+                prompt: entry.prompt,
+                system: entry.system || null,
+                session_id: entry.sessionId || null,
+                datetime_utc: new Date().toISOString(),
+            });
+            insertMetadata.run({
+                request_id: entry.correlationId,
+                async_job_id: entry.asyncJobId || null,
+            });
+        });
+        const updateRequests = this.db.prepare(`
+      UPDATE requests
+      SET response = @response,
+          duration_ms = @duration_ms,
+          input_tokens = @input_tokens,
+          output_tokens = @output_tokens
+      WHERE id = @id
+    `);
+        const updateMetadata = this.db.prepare(`
+      UPDATE gateway_metadata
+      SET retry_count = @retry_count,
+          circuit_breaker_state = @circuit_breaker_state,
+          cost_usd = @cost_usd,
+          approval_decision = @approval_decision,
+          optimization_applied = @optimization_applied,
+          thinking_blocks = @thinking_blocks,
+          exit_code = @exit_code,
+          error_message = @error_message,
+          status = @status
+      WHERE request_id = @id AND status = 'started'
+    `);
+        this.updateCompleteTxn = this.db.transaction((correlationId, result) => {
+            const thinkingBlocks = result.thinkingBlocks && result.thinkingBlocks.length > 0
+                ? JSON.stringify(truncateThinkingBlocks(result.thinkingBlocks))
+                : null;
+            updateRequests.run({
+                id: correlationId,
+                response: result.response,
+                duration_ms: result.durationMs,
+                input_tokens: result.inputTokens ?? null,
+                output_tokens: result.outputTokens ?? null,
+            });
+            updateMetadata.run({
+                id: correlationId,
+                retry_count: result.retryCount,
+                circuit_breaker_state: result.circuitBreakerState,
+                cost_usd: result.costUsd ?? null,
+                approval_decision: result.approvalDecision ?? null,
+                optimization_applied: result.optimizationApplied ? 1 : 0,
+                thinking_blocks: thinkingBlocks,
+                exit_code: result.exitCode,
+                error_message: result.errorMessage ?? null,
+                status: result.status,
+            });
+        });
+    }
+    logStart(entry) {
+        this.insertStartTxn(entry);
+    }
+    logComplete(correlationId, result) {
+        this.updateCompleteTxn(correlationId, result);
+    }
+    flush() {
+        // No-op: better-sqlite3 writes synchronously.
+    }
+    close() {
+        this.db.close();
+    }
+}
+export class NoopFlightRecorder {
+    logStart(_entry) { }
+    logComplete(_correlationId, _result) { }
+    flush() { }
+    close() { }
+}
+export function createFlightRecorder(logger) {
+    const dbPath = resolveFlightRecorderDbPath();
+    if (!dbPath) {
+        logger.info("Flight recorder disabled (LLM_GATEWAY_LOGS_DB=none)");
+        return new NoopFlightRecorder();
+    }
+    try {
+        const recorder = new FlightRecorder(dbPath);
+        logger.info(`Flight recorder enabled at ${dbPath}`);
+        return recorder;
+    }
+    catch (error) {
+        logger.error("Flight recorder unavailable; continuing without SQLite logging", error);
+        return new NoopFlightRecorder();
+    }
+}

package/dist/health.js

@@ -10,13 +10,13 @@ export async function checkHealth(db) {
         status: "unhealthy",
         postgres: {
             status: result.postgres.connected ? "up" : "down",
-            latency: result.postgres.latency
+            latency: result.postgres.latency,
         },
         redis: {
             status: result.redis.connected ? "up" : "down",
-            latency: result.redis.latency
+            latency: result.redis.latency,
         },
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
     };
     // Determine overall health status
     if (result.postgres.connected && result.redis.connected) {

package/dist/index.d.ts

@@ -12,6 +12,7 @@ type ExtendedToolResponse = {
     isError?: boolean;
     sessionId?: string;
     resumable?: boolean;
+    structuredContent?: Record<string, unknown>;
     approval?: ApprovalRecord | null;
     mcpServers?: {
         requested: ClaudeMcpServerName[];
@@ -36,6 +37,7 @@ export interface GeminiRequestParams {
     optimizePrompt: boolean;
     optimizeResponse?: boolean;
     idleTimeoutMs?: number;
+    forceRefresh?: boolean;
 }
 export interface HandlerDeps {
     sessionManager: ISessionManager;
@@ -50,6 +52,30 @@ 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;
+    model?: string;
+    outputFormat?: string;
+    sessionId?: string;
+    resumeLatest: boolean;
+    createNewSession: boolean;
+    alwaysApprove?: boolean;
+    permissionMode?: string;
+    effort?: string;
+    reasoningEffort?: string;
+    approvalStrategy: "legacy" | "mcp_managed";
+    approvalPolicy?: string;
+    mcpServers?: ClaudeMcpServerName[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    correlationId?: string;
+    optimizePrompt: boolean;
+    optimizeResponse?: boolean;
+    idleTimeoutMs?: number;
+    forceRefresh?: boolean;
+}
+export declare function handleGrokRequest(deps: HandlerDeps, params: GrokRequestParams): Promise<ExtendedToolResponse>;
+export declare function handleGrokRequestAsync(deps: AsyncHandlerDeps, params: Omit<GrokRequestParams, "optimizeResponse">): Promise<ExtendedToolResponse>;
 export declare function handleCodexRequestAsync(deps: AsyncHandlerDeps, params: {
     prompt: string;
     model?: string;
@@ -59,9 +85,11 @@ export declare function handleCodexRequestAsync(deps: AsyncHandlerDeps, params:
     approvalPolicy?: string;
     mcpServers?: ClaudeMcpServerName[];
     sessionId?: string;
+    resumeLatest?: boolean;
     createNewSession: boolean;
     correlationId?: string;
     optimizePrompt: boolean;
     idleTimeoutMs?: number;
+    forceRefresh?: boolean;
 }): Promise<ExtendedToolResponse>;
 export {};