llm-cli-gateway 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [1.1.0] - 2026-04-04
+
+### Added
+
+- **SQLite flight recorder** — New `src/flight-recorder.ts` module logs all LLM requests/responses to `~/.llm-cli-gateway/logs.db` with two-phase logging (logStart/logComplete), WAL mode for concurrent Datasette reads, and graceful degradation when better-sqlite3 is unavailable
+- **`LLM_GATEWAY_LOGS_DB` env var** — Configure flight recorder database path; set to empty string or `"none"` to disable logging entirely
+- **`structuredContent` in MCP tool responses** — All tool handlers now return machine-readable metadata (model, cli, correlationId, sessionId, durationMs, token usage, exitCode) alongside the text response
+- **`better-sqlite3` dependency** — Native SQLite addon for flight recorder (synchronous writes, WAL support)
+
+### Changed
+
+- **review-integrity.ts simplified** — Reduced from 323 lines to 83 lines. Retains 3 violation types: empty_allowed_tools, critical_tools_disallowed, tool_suppression. Removed inlined_code detection and multi-pattern matching
+- **`buildCliResponse` signature** — Now requires `cli` and `durationMs` parameters for structuredContent population
+- **`createErrorResponse`** — Returns sanitized `errorCategory` enum in structuredContent instead of raw error messages (prevents path/secret leakage)
+- **Flight recorder writes are idempotent** — logComplete only updates rows with status='started', preventing double-completion
+
+### Tests
+
+- 284 tests passing (15 test files)
+- Rewritten review-integrity tests to match simplified API
+
 ## [1.3.0] - 2026-02-15
 
 ### Fixed

package/README.md

@@ -14,6 +14,10 @@ A Model Context Protocol (MCP) server providing unified access to Claude Code, C
 - **Correlation ID Tracking**: Full request tracing across all LLM interactions
 - **Cross-Tool Collaboration**: LLMs can use each other via MCP (validated through dogfooding)
 
+### Observability
+- **SQLite Flight Recorder**: Every request/response logged to `~/.llm-cli-gateway/logs.db` with correlation IDs, token usage, duration, retry counts, and circuit breaker state. Browse with [Datasette](https://datasette.io/): `datasette ~/.llm-cli-gateway/logs.db`
+- **Structured Metadata**: Tool responses include machine-readable `structuredContent` (model, cli, correlationId, sessionId, durationMs, token counts)
+
 ### Reliability & Performance
 - **Retry Logic**: Exponential backoff with circuit breaker for transient failures
 - **Atomic File Writes**: Process-specific temp files with fsync for data integrity
@@ -22,7 +26,7 @@ A Model Context Protocol (MCP) server providing unified access to Claude Code, C
 - **Long-Running Jobs**: Non-time-bound async execution via `*_request_async` + polling tools
 
 ### Security & Quality
-- **Comprehensive Testing**: 221 tests covering unit, integration, and regression scenarios
+- **Comprehensive Testing**: 284 tests covering unit, integration, and regression scenarios
 - **Input Validation**: Zod schemas prevent injection attacks
 - **No Secret Leakage**: Generic session descriptions only (file permissions 0o600)
 - **No ReDoS**: Bounded regex patterns prevent catastrophic backtracking
@@ -360,6 +364,13 @@ await callTool("session_delete", {
   ```bash
   LLM_GATEWAY_APPROVAL_POLICY=strict node dist/index.js
   ```
+- `LLM_GATEWAY_LOGS_DB`: Path to SQLite flight recorder database. Default: `~/.llm-cli-gateway/logs.db`. Set to empty string or `none` to disable logging.
+  ```bash
+  # Custom path
+  LLM_GATEWAY_LOGS_DB=/var/log/gateway/logs.db node dist/index.js
+  # Disable flight recorder
+  LLM_GATEWAY_LOGS_DB=none node dist/index.js
+  ```
 
 ### CLI-Specific Settings
 
@@ -368,6 +379,25 @@ Each CLI can be configured through its own configuration files:
 - Codex: `~/.codex/config.toml`
 - Gemini: `~/.gemini/config.json`
 
+## For Fans of Simon Willison
+
+Simon's `llm` tool made it trivially easy to talk to any LLM from the command line. But as AI-assisted development matures, the challenge shifts from "how do I call a model" to "how do I orchestrate multiple models reliably, and what did they actually do?"
+
+**Multiple models increase the confidence factor.** When Claude writes code, Codex reviews it, and Gemini checks for bugs -- each bringing different training data and reasoning patterns -- the result is more robust than any single model alone. And often this isn't even enough. Having the models do iterative reviews is where you start getting real confidence.
+
+**Every interaction should be queryable data.** Inspired by `llm`'s SQLite logging philosophy, the gateway records every request and response to a local SQLite database. Not just prompts and responses -- retry counts, circuit breaker states, approval decisions, thinking blocks, cost estimates. Open it with Datasette and you have a complete operational picture of your AI usage:
+
+    datasette ~/.llm-cli-gateway/logs.db
+
+**The `llm-gateway` plugin bridges both worlds.** Install it, and your existing `llm` workflows gain orchestration features without changing how you work:
+
+    llm install llm-gateway
+    llm -m gateway-claude "explain this function"
+
+Your gateway interactions appear in both `llm logs` (for your personal history) and the gateway's flight recorder (for operational observability). Two audiences, one workflow.
+
+**Composability over monoliths.** The gateway doesn't replace `llm` -- it complements it. Use `llm` directly when you want simplicity. Route through the gateway when you want resilience, multi-model coordination, or detailed operational telemetry. The plugin is the bridge, not the destination.
+
 ## Development
 
 ### Project Structure

package/dist/approval-manager.js

@@ -83,7 +83,9 @@ export class ApprovalManager {
             // Canonicalize to handle scoped forms like "Read(*)", "Bash(git:*)"
             const canonicalized = request.disallowedTools.map(s => {
                 const trimmed = s.trim();
-                const cut = Math.min(...[trimmed.indexOf("("), trimmed.indexOf(":")].filter(i => i >= 0).concat([trimmed.length]));
+                const cut = Math.min(...[trimmed.indexOf("("), trimmed.indexOf(":")]
+                    .filter(i => i >= 0)
+                    .concat([trimmed.length]));
                 return trimmed.slice(0, cut).trim();
             });
             const blockedCritical = criticalTools.filter(t => canonicalized.includes(t));
@@ -103,7 +105,8 @@ export class ApprovalManager {
         if (request.reviewIntegrity && request.reviewIntegrity.violations.length > 0) {
             for (const violation of request.reviewIntegrity.violations) {
                 // Skip empty_allowed_tools and critical_tools_disallowed — already handled in context-dependent scoring above
-                if (violation.type === "empty_allowed_tools" || violation.type === "critical_tools_disallowed")
+                if (violation.type === "empty_allowed_tools" ||
+                    violation.type === "critical_tools_disallowed")
                     continue;
                 score += violation.score;
                 reasons.push(`Review integrity: ${violation.detail}`);
@@ -128,12 +131,12 @@ export class ApprovalManager {
             bypassRequested: request.bypassRequested,
             fullAuto: request.fullAuto,
             metadata: request.metadata,
-            reviewIntegrity: request.reviewIntegrity
+            reviewIntegrity: request.reviewIntegrity,
         };
         appendFileSync(this.logPath, `${JSON.stringify(record)}\n`, { encoding: "utf-8", mode: 0o600 });
         this.logger.info(`Approval decision: ${status} (score=${score}, policy=${policy})`, {
             cli: request.cli,
-            operation: request.operation
+            operation: request.operation,
         });
         return record;
     }

package/dist/async-job-manager.js

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
-import { getExtendedPath, killProcessGroup, registerProcessGroup, unregisterProcessGroup } from "./executor.js";
+import { getExtendedPath, killProcessGroup, registerProcessGroup, unregisterProcessGroup, } from "./executor.js";
 import { noopLogger } from "./logger.js";
 import { ProcessMonitor } from "./process-monitor.js";
 const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
@@ -12,7 +12,7 @@ function truncateText(value, maxChars) {
     }
     return {
         text: value.slice(value.length - maxChars),
-        truncated: true
+        truncated: true,
     };
 }
 export class AsyncJobManager {
@@ -101,7 +101,7 @@ export class AsyncJobManager {
             cwd,
             detached: true,
             stdio: ["ignore", "pipe", "pipe"],
-            env: { ...process.env, PATH: getExtendedPath() }
+            env: { ...process.env, PATH: getExtendedPath() },
         });
         if (child.pid)
             registerProcessGroup(child.pid);
@@ -133,7 +133,7 @@ export class AsyncJobManager {
             exited: false,
             metricsRecorded: false,
             outputFormat,
-            cleanupGroup
+            cleanupGroup,
         };
         this.jobs.set(id, job);
         this.logger.info(`Job ${id} started for ${cli}`, { correlationId });
@@ -152,7 +152,9 @@ export class AsyncJobManager {
                 job.error = `Process killed after ${idleTimeoutMs}ms of inactivity`;
                 job.finishedAt = new Date().toISOString();
                 killProcessGroup(job.process, "SIGTERM");
-                this.logger.info(`Job ${id} killed due to inactivity (${idleTimeoutMs}ms)`, { correlationId });
+                this.logger.info(`Job ${id} killed due to inactivity (${idleTimeoutMs}ms)`, {
+                    correlationId,
+                });
                 this.emitMetrics(job);
                 setTimeout(() => {
                     if (!job.exited)
@@ -233,7 +235,7 @@ export class AsyncJobManager {
             stdout: stdout.text,
             stderr: stderr.text,
             stdoutTruncated: stdout.truncated,
-            stderrTruncated: stderr.truncated
+            stderrTruncated: stderr.truncated,
         };
     }
     cancelJob(jobId) {
@@ -262,8 +264,11 @@ export class AsyncJobManager {
         for (const [id, job] of this.jobs) {
             if (job.status === "running") {
                 result.push({
-                    jobId: id, cli: job.cli, status: job.status,
-                    pid: job.process.pid ?? null, startedAt: job.startedAt
+                    jobId: id,
+                    cli: job.cli,
+                    status: job.status,
+                    pid: job.process.pid ?? null,
+                    startedAt: job.startedAt,
                 });
             }
         }
@@ -279,7 +284,7 @@ export class AsyncJobManager {
             runningJobs: running.length,
             deadJobs: health.filter(h => h.isDead).length,
             zombieJobs: health.filter(h => h.isZombie).length,
-            jobs: health
+            jobs: health,
         };
     }
     getJobOutputFormat(jobId) {
@@ -298,7 +303,7 @@ export class AsyncJobManager {
             stdoutBytes: Buffer.byteLength(job.stdout),
             stderrBytes: Buffer.byteLength(job.stderr),
             error: job.error,
-            exited: job.exited
+            exited: job.exited,
         };
     }
     appendOutput(job, stream, chunk) {
@@ -312,7 +317,9 @@ export class AsyncJobManager {
                 job.finishedAt = new Date().toISOString();
                 job.clearIdleTimer?.();
                 killProcessGroup(job.process, "SIGTERM");
-                this.logger.info(`Job ${job.id} killed due to output overflow`, { correlationId: job.correlationId });
+                this.logger.info(`Job ${job.id} killed due to output overflow`, {
+                    correlationId: job.correlationId,
+                });
                 this.emitMetrics(job);
                 setTimeout(() => {
                     if (!job.exited)

package/dist/claude-mcp-config.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync, openSync, fsyncSync, closeSync, chmodSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, renameSync, openSync, fsyncSync, closeSync, chmodSync, } from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { parse as parseToml } from "toml";
@@ -45,7 +45,7 @@ function readCodexServerConfig(server) {
         return {
             command,
             args,
-            env
+            env,
         };
     }
     catch {
@@ -120,7 +120,7 @@ function toClaudeServerDef(server) {
     return {
         command,
         args,
-        ...(Object.keys(env).length > 0 ? { env } : {})
+        ...(Object.keys(env).length > 0 ? { env } : {}),
     };
 }
 export function buildClaudeMcpConfig(servers) {
@@ -142,7 +142,10 @@ export function buildClaudeMcpConfig(servers) {
     try {
         mkdirSync(configDir, { recursive: true });
         const tempPath = `${configPath}.tmp.${process.pid}`;
-        writeFileSync(tempPath, JSON.stringify({ mcpServers }, null, 2), { encoding: "utf-8", mode: 0o600 });
+        writeFileSync(tempPath, JSON.stringify({ mcpServers }, null, 2), {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
         const fd = openSync(tempPath, "r+");
         try {
             fsyncSync(fd);

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";
+    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 {};