llm-cli-gateway 1.1.0 → 1.5.4

package/dist/job-store.d.ts

@@ -0,0 +1,84 @@
+import type { Logger } from "./logger.js";
+export type JobStoreStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
+export interface JobRecord {
+    id: string;
+    correlationId: string;
+    requestKey: string;
+    cli: string;
+    argsJson: string;
+    outputFormat?: string | null;
+    status: JobStoreStatus;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    outputTruncated: boolean;
+    error: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+    pid: number | null;
+    expiresAt: string;
+}
+export declare function resolveJobStoreDbPath(): string | null;
+export declare function resolveJobRetentionMs(): number;
+export declare function resolveDedupWindowMs(): number;
+export declare function computeRequestKey(cli: string, args: string[], extra?: string): string;
+export declare class JobStore {
+    private logger;
+    private db;
+    private retentionMs;
+    private dedupWindowMs;
+    private insertStmt;
+    private updateOutputStmt;
+    private updateCompleteStmt;
+    private getByIdStmt;
+    private findByRequestKeyStmt;
+    private markOrphanedStmt;
+    private deleteExpiredStmt;
+    constructor(dbPath: string, logger?: Logger);
+    /**
+     * Insert a new running job row. Caller has already computed requestKey.
+     */
+    recordStart(input: {
+        id: string;
+        correlationId: string;
+        requestKey: string;
+        cli: string;
+        args: string[];
+        outputFormat?: string;
+        startedAt: string;
+        pid: number | null;
+    }): void;
+    /**
+     * Batched output flush. Cheap to call repeatedly; better-sqlite3 is sync.
+     */
+    recordOutput(id: string, stdout: string, stderr: string, outputTruncated: boolean): void;
+    /**
+     * Mark a job as completed/failed/canceled. Sets expires_at = now + retention.
+     */
+    recordComplete(input: {
+        id: string;
+        status: Exclude<JobStoreStatus, "running">;
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+        outputTruncated: boolean;
+        error: string | null;
+        finishedAt: string;
+    }): void;
+    getById(id: string): JobRecord | null;
+    /**
+     * Returns the most recent matching job within the dedup window, if any.
+     * Caller pre-filters out forceRefresh requests.
+     */
+    findByRequestKey(requestKey: string): JobRecord | null;
+    /**
+     * On gateway boot, flip any jobs that were 'running' to 'orphaned'.
+     * The child processes were detached but can't be reattached to in this process.
+     */
+    markOrphanedOnStartup(): number;
+    /**
+     * Delete rows whose expires_at has passed. Returns number of rows deleted.
+     */
+    evictExpired(): number;
+    close(): void;
+}

package/dist/job-store.js

@@ -0,0 +1,251 @@
+import { chmodSync, existsSync, mkdirSync } from "fs";
+import os from "os";
+import path from "path";
+import { createHash } from "crypto";
+import { createRequire } from "module";
+import { noopLogger } from "./logger.js";
+export function resolveJobStoreDbPath() {
+    const configured = process.env.LLM_GATEWAY_JOBS_DB ?? 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 DEFAULT_RETENTION_DAYS = 30;
+const FAR_FUTURE_ISO = "9999-12-31T23:59:59.999Z";
+export function resolveJobRetentionMs() {
+    const raw = process.env.LLM_GATEWAY_JOB_RETENTION_DAYS;
+    const days = raw ? Number(raw) : DEFAULT_RETENTION_DAYS;
+    if (!Number.isFinite(days) || days <= 0) {
+        return DEFAULT_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    }
+    return days * 24 * 60 * 60 * 1000;
+}
+const DEFAULT_DEDUP_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+export function resolveDedupWindowMs() {
+    const raw = process.env.LLM_GATEWAY_DEDUP_WINDOW_MS;
+    if (raw === undefined)
+        return DEFAULT_DEDUP_WINDOW_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_DEDUP_WINDOW_MS;
+    return n;
+}
+export function computeRequestKey(cli, args, extra) {
+    const payload = JSON.stringify({ cli, args, extra: extra ?? "" });
+    return createHash("sha256").update(payload).digest("hex");
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        correlationId: row.correlation_id,
+        requestKey: row.request_key,
+        cli: row.cli,
+        argsJson: row.args_json,
+        outputFormat: row.output_format ?? null,
+        status: row.status,
+        exitCode: row.exit_code,
+        stdout: row.stdout ?? "",
+        stderr: row.stderr ?? "",
+        outputTruncated: Boolean(row.output_truncated),
+        error: row.error ?? null,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
+        pid: row.pid,
+        expiresAt: row.expires_at,
+    };
+}
+export class JobStore {
+    logger;
+    db;
+    retentionMs;
+    dedupWindowMs;
+    insertStmt;
+    updateOutputStmt;
+    updateCompleteStmt;
+    getByIdStmt;
+    findByRequestKeyStmt;
+    markOrphanedStmt;
+    deleteExpiredStmt;
+    constructor(dbPath, logger = noopLogger) {
+        this.logger = logger;
+        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("synchronous = NORMAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS jobs (
+        id TEXT PRIMARY KEY,
+        correlation_id TEXT NOT NULL,
+        request_key TEXT NOT NULL,
+        cli TEXT NOT NULL,
+        args_json TEXT NOT NULL,
+        output_format TEXT,
+        status TEXT NOT NULL,
+        exit_code INTEGER,
+        stdout TEXT,
+        stderr TEXT,
+        output_truncated INTEGER NOT NULL DEFAULT 0,
+        error TEXT,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        pid INTEGER,
+        expires_at TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_jobs_request_key ON jobs(request_key);
+      CREATE INDEX IF NOT EXISTS idx_jobs_status ON jobs(status);
+      CREATE INDEX IF NOT EXISTS idx_jobs_expires_at ON jobs(expires_at);
+      CREATE INDEX IF NOT EXISTS idx_jobs_request_key_finished ON jobs(request_key, finished_at);
+    `);
+        if (process.platform !== "win32") {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch {
+                // Best effort permissions hardening.
+            }
+        }
+        this.retentionMs = resolveJobRetentionMs();
+        this.dedupWindowMs = resolveDedupWindowMs();
+        this.insertStmt = this.db.prepare(`
+      INSERT INTO jobs (id, correlation_id, request_key, cli, args_json, output_format,
+                        status, exit_code, stdout, stderr, output_truncated, error,
+                        started_at, finished_at, pid, expires_at)
+      VALUES (@id, @correlation_id, @request_key, @cli, @args_json, @output_format,
+              @status, @exit_code, @stdout, @stderr, @output_truncated, @error,
+              @started_at, @finished_at, @pid, @expires_at)
+    `);
+        this.updateOutputStmt = this.db.prepare(`
+      UPDATE jobs SET stdout = @stdout, stderr = @stderr, output_truncated = @output_truncated
+      WHERE id = @id
+    `);
+        this.updateCompleteStmt = this.db.prepare(`
+      UPDATE jobs SET status = @status, exit_code = @exit_code, stdout = @stdout, stderr = @stderr,
+                      output_truncated = @output_truncated, error = @error,
+                      finished_at = @finished_at, expires_at = @expires_at
+      WHERE id = @id
+    `);
+        this.getByIdStmt = this.db.prepare(`SELECT * FROM jobs WHERE id = ?`);
+        // Dedup query: most recent non-orphaned job with matching request_key, started within window.
+        // Exclude orphaned/canceled/failed-with-error from dedup so a broken run isn't reused.
+        this.findByRequestKeyStmt = this.db.prepare(`
+      SELECT * FROM jobs
+      WHERE request_key = ?
+        AND started_at >= ?
+        AND status IN ('running', 'completed')
+      ORDER BY started_at DESC
+      LIMIT 1
+    `);
+        this.markOrphanedStmt = this.db.prepare(`
+      UPDATE jobs
+      SET status = 'orphaned',
+          error = COALESCE(error, 'Gateway restarted while job was running'),
+          finished_at = COALESCE(finished_at, ?),
+          expires_at = ?
+      WHERE status = 'running'
+    `);
+        this.deleteExpiredStmt = this.db.prepare(`DELETE FROM jobs WHERE expires_at < ?`);
+    }
+    /**
+     * Insert a new running job row. Caller has already computed requestKey.
+     */
+    recordStart(input) {
+        this.insertStmt.run({
+            id: input.id,
+            correlation_id: input.correlationId,
+            request_key: input.requestKey,
+            cli: input.cli,
+            args_json: JSON.stringify(input.args),
+            output_format: input.outputFormat ?? null,
+            status: "running",
+            exit_code: null,
+            stdout: "",
+            stderr: "",
+            output_truncated: 0,
+            error: null,
+            started_at: input.startedAt,
+            finished_at: null,
+            pid: input.pid,
+            // Running jobs never expire — only completed/failed/canceled do.
+            expires_at: FAR_FUTURE_ISO,
+        });
+    }
+    /**
+     * Batched output flush. Cheap to call repeatedly; better-sqlite3 is sync.
+     */
+    recordOutput(id, stdout, stderr, outputTruncated) {
+        this.updateOutputStmt.run({
+            id,
+            stdout,
+            stderr,
+            output_truncated: outputTruncated ? 1 : 0,
+        });
+    }
+    /**
+     * Mark a job as completed/failed/canceled. Sets expires_at = now + retention.
+     */
+    recordComplete(input) {
+        const expiresAt = new Date(Date.parse(input.finishedAt) + this.retentionMs).toISOString();
+        this.updateCompleteStmt.run({
+            id: input.id,
+            status: input.status,
+            exit_code: input.exitCode,
+            stdout: input.stdout,
+            stderr: input.stderr,
+            output_truncated: input.outputTruncated ? 1 : 0,
+            error: input.error,
+            finished_at: input.finishedAt,
+            expires_at: expiresAt,
+        });
+    }
+    getById(id) {
+        const row = this.getByIdStmt.get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Returns the most recent matching job within the dedup window, if any.
+     * Caller pre-filters out forceRefresh requests.
+     */
+    findByRequestKey(requestKey) {
+        const cutoff = new Date(Date.now() - this.dedupWindowMs).toISOString();
+        const row = this.findByRequestKeyStmt.get(requestKey, cutoff);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * On gateway boot, flip any jobs that were 'running' to 'orphaned'.
+     * The child processes were detached but can't be reattached to in this process.
+     */
+    markOrphanedOnStartup() {
+        const now = new Date().toISOString();
+        // Orphaned jobs retain a short window so callers can fetch the partial output,
+        // then evict. Reuse the standard retention.
+        const expiresAt = new Date(Date.now() + this.retentionMs).toISOString();
+        const result = this.markOrphanedStmt.run(now, expiresAt);
+        return result?.changes ?? 0;
+    }
+    /**
+     * Delete rows whose expires_at has passed. Returns number of rows deleted.
+     */
+    evictExpired() {
+        const now = new Date().toISOString();
+        const result = this.deleteExpiredStmt.run(now);
+        return result?.changes ?? 0;
+    }
+    close() {
+        try {
+            this.db.close();
+        }
+        catch (err) {
+            this.logger.error("JobStore close failed", err);
+        }
+    }
+}

package/dist/logger.d.ts

@@ -2,5 +2,14 @@ export interface Logger {
     info(message: string, meta?: unknown): void;
     error(message: string, meta?: unknown): void;
     debug(message: string, meta?: unknown): void;
+    /** Optional: callers that want explicit WARN routing can implement this. */
+    warn?(message: string, meta?: unknown): void;
 }
 export declare const noopLogger: Logger;
+/**
+ * Emit a warning through whichever logger surface is available. Some Logger
+ * implementations (legacy) only provide `info`/`error`/`debug`; in that case
+ * the message is prefixed with `[WARN]` and routed through `info` so it still
+ * reaches stderr.
+ */
+export declare function logWarn(logger: Logger, message: string, meta?: unknown): void;

package/dist/logger.js

@@ -2,4 +2,18 @@ export const noopLogger = {
     info: () => { },
     error: () => { },
     debug: () => { },
+    warn: () => { },
 };
+/**
+ * Emit a warning through whichever logger surface is available. Some Logger
+ * implementations (legacy) only provide `info`/`error`/`debug`; in that case
+ * the message is prefixed with `[WARN]` and routed through `info` so it still
+ * reaches stderr.
+ */
+export function logWarn(logger, message, meta) {
+    if (typeof logger.warn === "function") {
+        logger.warn(message, meta);
+        return;
+    }
+    logger.info(`[WARN] ${message}`, meta);
+}

package/dist/model-registry.d.ts

@@ -1,10 +1,24 @@
 import type { CliType } from "./session-manager.js";
+type ModelSource = "fallback" | "observed" | "config" | "env";
+type ModelConfidence = "low" | "medium" | "high";
+export interface ModelMetadata {
+    source: ModelSource;
+    sourceDetail: string;
+    confidence: ModelConfidence;
+    lastSeen?: string;
+}
 export interface CliInfo {
     description: string;
     models: Record<string, string>;
     defaultModel?: string;
+    defaultModelSource?: string;
     modelOrder?: string[];
+    aliases?: Record<string, string>;
+    modelMetadata?: Record<string, ModelMetadata>;
+    warnings?: string[];
 }
 export type CliInfoMap = Record<CliType, CliInfo>;
 export declare function getCliInfo(forceRefresh?: boolean): CliInfoMap;
+export declare function clearModelRegistryCache(): void;
 export declare function resolveModelAlias(cli: CliType, model: string | undefined, info: CliInfoMap): string | undefined;
+export {};