llm-cli-gateway 1.1.0 → 1.4.0

package/dist/async-job-manager.js

@@ -3,9 +3,11 @@ import { randomUUID } from "crypto";
 import { getExtendedPath, killProcessGroup, registerProcessGroup, unregisterProcessGroup, } from "./executor.js";
 import { noopLogger } from "./logger.js";
 import { ProcessMonitor } from "./process-monitor.js";
+import { computeRequestKey } from "./job-store.js";
 const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
-const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour
+const JOB_TTL_MS = 60 * 60 * 1000; // 1 hour in-memory retention; durable store has its own (longer) retention
 const EVICTION_INTERVAL_MS = 5 * 60 * 1000; // Check every 5 minutes
+const OUTPUT_FLUSH_INTERVAL_MS = 1000; // Throttle DB writes for streaming stdout/stderr
 function truncateText(value, maxChars) {
     if (value.length <= maxChars) {
         return { text: value, truncated: false };
@@ -21,10 +23,23 @@ export class AsyncJobManager {
     jobs = new Map();
     evictionTimer = null;
     processMonitor;
-    constructor(logger = noopLogger, onJobComplete) {
+    store;
+    constructor(logger = noopLogger, onJobComplete, store = null) {
         this.logger = logger;
         this.onJobComplete = onJobComplete;
         this.processMonitor = new ProcessMonitor(logger);
+        this.store = store;
+        if (this.store) {
+            try {
+                const orphaned = this.store.markOrphanedOnStartup();
+                if (orphaned > 0) {
+                    this.logger.info(`Marked ${orphaned} in-flight job(s) as orphaned after gateway restart`);
+                }
+            }
+            catch (err) {
+                this.logger.error("markOrphanedOnStartup failed", err);
+            }
+        }
         this.evictionTimer = setInterval(() => this.evictCompletedJobs(), EVICTION_INTERVAL_MS);
         // Allow the process to exit even if the timer is active
         if (this.evictionTimer.unref) {
@@ -52,7 +67,7 @@ export class AsyncJobManager {
         let evicted = 0;
         // Dead process auto-recovery: check for running jobs whose process no longer exists
         for (const [id, job] of this.jobs) {
-            if (job.status === "running" && job.process.pid) {
+            if (job.status === "running" && job.process && job.process.pid) {
                 try {
                     process.kill(job.process.pid, 0);
                 }
@@ -66,6 +81,7 @@ export class AsyncJobManager {
                         unregisterProcessGroup(job.process.pid);
                         this.logger.error(`Job ${id} process ${job.process.pid} no longer exists, marking as failed`);
                         this.emitMetrics(job);
+                        this.persistComplete(job);
                     }
                     // EPERM: process exists but we can't signal it — ignore
                 }
@@ -75,10 +91,11 @@ export class AsyncJobManager {
                 job.status = "failed";
                 job.error = "Process exited without proper status transition";
                 job.finishedAt = job.finishedAt || new Date().toISOString();
-                if (job.process.pid)
+                if (job.process && job.process.pid)
                     unregisterProcessGroup(job.process.pid);
                 this.logger.error(`Job ${id} has exited flag but was still in running state, marking as failed`);
                 this.emitMetrics(job);
+                this.persistComplete(job);
             }
         }
         for (const [id, job] of this.jobs) {
@@ -91,10 +108,178 @@ export class AsyncJobManager {
             }
         }
         if (evicted > 0) {
-            this.logger.debug(`Evicted ${evicted} completed jobs`);
+            this.logger.debug(`Evicted ${evicted} completed jobs from memory (durable store retains them)`);
+        }
+        // Sweep the durable store, too. Errors are non-fatal — the job rows just stay until next sweep.
+        if (this.store) {
+            try {
+                const removed = this.store.evictExpired();
+                if (removed > 0) {
+                    this.logger.debug(`Evicted ${removed} expired jobs from durable store`);
+                }
+            }
+            catch (err) {
+                this.logger.error("durable store eviction failed", err);
+            }
         }
     }
-    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat) {
+    /**
+     * Compute the dedup key for a job. Stable across re-issues of the same request,
+     * which is exactly what allows agents to safely retry without restarting the run.
+     */
+    buildRequestKey(cli, args) {
+        return computeRequestKey(cli, args);
+    }
+    safeStoreCall(label, fn) {
+        if (!this.store)
+            return;
+        try {
+            fn();
+        }
+        catch (err) {
+            this.logger.error(`JobStore.${label} failed`, err);
+        }
+    }
+    /**
+     * Flush in-memory stdout/stderr to the durable store if anything changed
+     * since the last flush. Throttled by OUTPUT_FLUSH_INTERVAL_MS to avoid
+     * pounding sqlite on every chunk of streaming output.
+     */
+    maybeFlushOutput(job, force = false) {
+        if (!this.store)
+            return;
+        if (!job.outputDirty)
+            return;
+        const now = Date.now();
+        if (!force && now - job.lastOutputFlushAt < OUTPUT_FLUSH_INTERVAL_MS)
+            return;
+        job.outputDirty = false;
+        job.lastOutputFlushAt = now;
+        this.safeStoreCall("recordOutput", () => this.store.recordOutput(job.id, job.stdout, job.stderr, job.outputTruncated));
+    }
+    persistComplete(job) {
+        if (!this.store)
+            return;
+        if (job.status === "running")
+            return;
+        if (!job.finishedAt)
+            return;
+        // Make sure the latest output is captured in the same row update.
+        job.outputDirty = false;
+        this.safeStoreCall("recordComplete", () => this.store.recordComplete({
+            id: job.id,
+            status: job.status === "running" ? "failed" : job.status,
+            exitCode: job.exitCode,
+            stdout: job.stdout,
+            stderr: job.stderr,
+            outputTruncated: job.outputTruncated,
+            error: job.error,
+            finishedAt: job.finishedAt,
+        }));
+    }
+    /**
+     * Reconstitute an in-memory AsyncJobRecord from a durable row, so subsequent
+     * getJobSnapshot/getJobResult calls hit the in-memory cache.
+     * The reconstituted record has process=null — it represents historical data only.
+     */
+    hydrateFromStore(jobId) {
+        if (!this.store)
+            return null;
+        let row;
+        try {
+            row = this.store.getById(jobId);
+        }
+        catch (err) {
+            this.logger.error("JobStore.getById failed", err);
+            return null;
+        }
+        if (!row)
+            return null;
+        const args = (() => {
+            try {
+                const parsed = JSON.parse(row.argsJson);
+                return Array.isArray(parsed) ? parsed.map(String) : [];
+            }
+            catch {
+                return [];
+            }
+        })();
+        const reconstituted = {
+            id: row.id,
+            cli: row.cli,
+            args,
+            requestKey: row.requestKey,
+            correlationId: row.correlationId,
+            status: row.status,
+            startedAt: row.startedAt,
+            finishedAt: row.finishedAt,
+            exitCode: row.exitCode,
+            stdout: row.stdout,
+            stderr: row.stderr,
+            outputTruncated: row.outputTruncated,
+            canceled: row.status === "canceled",
+            error: row.error,
+            process: null,
+            exited: row.status !== "running",
+            metricsRecorded: true,
+            outputFormat: row.outputFormat ?? undefined,
+            outputDirty: false,
+            lastOutputFlushAt: Date.now(),
+        };
+        this.jobs.set(jobId, reconstituted);
+        return reconstituted;
+    }
+    /**
+     * Backwards-compatible entry point. Equivalent to startJobWithDedup({...}).snapshot.
+     * Existing callers keep working unchanged; forceRefresh is exposed as a trailing
+     * optional param for the dedup-aware path.
+     */
+    startJob(cli, args, correlationId, cwd, idleTimeoutMs, outputFormat, forceRefresh) {
+        return this.startJobWithDedup(cli, args, correlationId, {
+            cwd,
+            idleTimeoutMs,
+            outputFormat,
+            forceRefresh,
+        }).snapshot;
+    }
+    /**
+     * Start a job, with optional dedup against recent identical requests.
+     * Returns `{ snapshot, deduped }` so callers can log/report the short-circuit.
+     *
+     * Dedup is keyed on (cli, args). If a job with the same key was started within
+     * the dedup window (default 1h) and is still running or completed, its snapshot
+     * is returned without spawning a new process. forceRefresh skips dedup entirely.
+     */
+    startJobWithDedup(cli, args, correlationId, opts = {}) {
+        const { cwd, idleTimeoutMs, outputFormat, forceRefresh } = opts;
+        const requestKey = this.buildRequestKey(cli, args);
+        if (!forceRefresh && this.store) {
+            try {
+                const existing = this.store.findByRequestKey(requestKey);
+                if (existing) {
+                    // Prefer the in-memory record if we still have it (live process, idle timers, etc).
+                    let record = this.jobs.get(existing.id);
+                    if (!record) {
+                        record = this.hydrateFromStore(existing.id) ?? undefined;
+                    }
+                    if (record) {
+                        this.logger.info(`Job ${existing.id} reused via dedup for ${cli}`, {
+                            correlationId,
+                            originalCorrelationId: record.correlationId,
+                            status: record.status,
+                        });
+                        return {
+                            snapshot: this.snapshot(record),
+                            deduped: true,
+                            originalCorrelationId: record.correlationId,
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                this.logger.error("dedup lookup failed; proceeding with fresh run", err);
+            }
+        }
         const id = randomUUID();
         const startedAt = new Date().toISOString();
         const child = spawn(cli, args, {
@@ -119,6 +304,7 @@ export class AsyncJobManager {
             id,
             cli,
             args: [...args],
+            requestKey,
             correlationId,
             status: "running",
             startedAt,
@@ -134,8 +320,20 @@ export class AsyncJobManager {
             metricsRecorded: false,
             outputFormat,
             cleanupGroup,
+            outputDirty: false,
+            lastOutputFlushAt: Date.now(),
         };
         this.jobs.set(id, job);
+        this.safeStoreCall("recordStart", () => this.store.recordStart({
+            id,
+            correlationId,
+            requestKey,
+            cli,
+            args: [...args],
+            outputFormat,
+            startedAt,
+            pid: child.pid ?? null,
+        }));
         this.logger.info(`Job ${id} started for ${cli}`, { correlationId });
         // Idle timeout: kill process if no output activity for idleTimeoutMs
         let idleTimerId;
@@ -151,13 +349,15 @@ export class AsyncJobManager {
                 job.exitCode = 125;
                 job.error = `Process killed after ${idleTimeoutMs}ms of inactivity`;
                 job.finishedAt = new Date().toISOString();
-                killProcessGroup(job.process, "SIGTERM");
+                if (job.process)
+                    killProcessGroup(job.process, "SIGTERM");
                 this.logger.info(`Job ${id} killed due to inactivity (${idleTimeoutMs}ms)`, {
                     correlationId,
                 });
                 this.emitMetrics(job);
+                this.persistComplete(job);
                 setTimeout(() => {
-                    if (!job.exited)
+                    if (!job.exited && job.process)
                         killProcessGroup(job.process, "SIGKILL");
                     job.cleanupGroup?.();
                 }, 5000);
@@ -185,6 +385,7 @@ export class AsyncJobManager {
                 job.finishedAt = new Date().toISOString();
                 this.logger.error(`Job ${id} error: ${error.message}`, { correlationId });
                 this.emitMetrics(job);
+                this.persistComplete(job);
             }
         });
         child.on("close", (code) => {
@@ -199,6 +400,8 @@ export class AsyncJobManager {
                 if (!job.finishedAt) {
                     job.finishedAt = new Date().toISOString();
                 }
+                // Ensure terminal state reaches the durable store (idle-timeout/output-overflow already persisted).
+                this.persistComplete(job);
                 return;
             }
             job.exitCode = code ?? 0;
@@ -213,20 +416,25 @@ export class AsyncJobManager {
                 job.status = "failed";
             }
             this.emitMetrics(job);
+            this.persistComplete(job);
         });
-        return this.snapshot(job);
+        return { snapshot: this.snapshot(job), deduped: false };
     }
     getJobSnapshot(jobId) {
-        const job = this.jobs.get(jobId);
+        let job = this.jobs.get(jobId);
         if (!job) {
-            return null;
+            job = this.hydrateFromStore(jobId) ?? undefined;
+            if (!job)
+                return null;
         }
         return this.snapshot(job);
     }
     getJobResult(jobId, maxChars = 200000) {
-        const job = this.jobs.get(jobId);
+        let job = this.jobs.get(jobId);
         if (!job) {
-            return null;
+            job = this.hydrateFromStore(jobId) ?? undefined;
+            if (!job)
+                return null;
         }
         const stdout = truncateText(job.stdout, maxChars);
         const stderr = truncateText(job.stderr, maxChars);
@@ -246,14 +454,22 @@ export class AsyncJobManager {
         if (job.status !== "running") {
             return { canceled: false, reason: `Job is already ${job.status}` };
         }
+        // Reconstituted (orphaned) jobs have no live process to signal — refuse cancel.
+        if (!job.process) {
+            return {
+                canceled: false,
+                reason: "Job has no live process (orphaned from prior gateway run)",
+            };
+        }
         job.canceled = true;
         job.status = "canceled";
         job.finishedAt = new Date().toISOString();
         job.clearIdleTimer?.();
         killProcessGroup(job.process, "SIGTERM");
         this.logger.info(`Job ${jobId} canceled`, { correlationId: job.correlationId });
+        this.persistComplete(job);
         setTimeout(() => {
-            if (!job.exited)
+            if (!job.exited && job.process)
                 killProcessGroup(job.process, "SIGKILL");
             job.cleanupGroup?.();
         }, 5000);
@@ -267,7 +483,7 @@ export class AsyncJobManager {
                     jobId: id,
                     cli: job.cli,
                     status: job.status,
-                    pid: job.process.pid ?? null,
+                    pid: job.process?.pid ?? null,
                     startedAt: job.startedAt,
                 });
             }
@@ -316,13 +532,15 @@ export class AsyncJobManager {
                 job.error = "Output exceeded maximum size (50MB)";
                 job.finishedAt = new Date().toISOString();
                 job.clearIdleTimer?.();
-                killProcessGroup(job.process, "SIGTERM");
+                if (job.process)
+                    killProcessGroup(job.process, "SIGTERM");
                 this.logger.info(`Job ${job.id} killed due to output overflow`, {
                     correlationId: job.correlationId,
                 });
                 this.emitMetrics(job);
+                this.persistComplete(job);
                 setTimeout(() => {
-                    if (!job.exited)
+                    if (!job.exited && job.process)
                         killProcessGroup(job.process, "SIGKILL");
                     job.cleanupGroup?.();
                 }, 5000);
@@ -337,5 +555,7 @@ export class AsyncJobManager {
         else {
             job.stderr += text;
         }
+        job.outputDirty = true;
+        this.maybeFlushOutput(job);
     }
 }

package/dist/cli-updater.d.ts

@@ -0,0 +1,38 @@
+import type { Logger } from "./logger.js";
+import type { CliType } from "./session-manager.js";
+export interface CliVersionInfo {
+    cli: CliType;
+    command: string;
+    args: string[];
+    installed: boolean;
+    version?: string;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export interface CliUpgradePlan {
+    cli: CliType;
+    target: string;
+    command: string;
+    args: string[];
+    strategy: "self-update" | "npm-global-install";
+    requiresNetwork: boolean;
+    note?: string;
+}
+export interface CliUpgradeResult {
+    dryRun: boolean;
+    plan: CliUpgradePlan;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+}
+export declare function buildCliUpgradePlan(cli: CliType, target?: string): CliUpgradePlan;
+export declare function getCliVersion(cli: CliType): Promise<CliVersionInfo>;
+export declare function getCliVersions(cli?: CliType): Promise<CliVersionInfo[]>;
+export declare function runCliUpgrade(params: {
+    cli: CliType;
+    target?: string;
+    dryRun: boolean;
+    timeoutMs?: number;
+    logger?: Logger;
+}): Promise<CliUpgradeResult>;

package/dist/cli-updater.js

@@ -0,0 +1,145 @@
+import { executeCli } from "./executor.js";
+const VERSION_ARGS = {
+    claude: ["--version"],
+    codex: ["--version"],
+    gemini: ["--version"],
+    grok: ["--version"],
+};
+const NPM_PACKAGES = {
+    codex: "@openai/codex",
+    gemini: "@google/gemini-cli",
+};
+export function buildCliUpgradePlan(cli, target = "latest") {
+    const normalizedTarget = normalizeTarget(target);
+    if (cli === "claude") {
+        if (normalizedTarget === "latest") {
+            return {
+                cli,
+                target: normalizedTarget,
+                command: "claude",
+                args: ["update"],
+                strategy: "self-update",
+                requiresNetwork: true,
+            };
+        }
+        return {
+            cli,
+            target: normalizedTarget,
+            command: "claude",
+            args: ["install", normalizedTarget],
+            strategy: "self-update",
+            requiresNetwork: true,
+            note: "Claude Code supports explicit install targets through 'claude install <target>'.",
+        };
+    }
+    if (cli === "grok") {
+        if (normalizedTarget === "latest") {
+            return {
+                cli,
+                target: normalizedTarget,
+                command: "grok",
+                args: ["update"],
+                strategy: "self-update",
+                requiresNetwork: true,
+            };
+        }
+        return {
+            cli,
+            target: normalizedTarget,
+            command: "grok",
+            args: ["update", "--version", normalizedTarget],
+            strategy: "self-update",
+            requiresNetwork: true,
+            note: "Grok CLI supports explicit version targets via 'grok update --version <target>'.",
+        };
+    }
+    if (cli === "codex" && normalizedTarget === "latest") {
+        return {
+            cli,
+            target: normalizedTarget,
+            command: "codex",
+            args: ["update"],
+            strategy: "self-update",
+            requiresNetwork: true,
+        };
+    }
+    const packageName = cli === "codex" ? NPM_PACKAGES.codex : NPM_PACKAGES.gemini;
+    return {
+        cli,
+        target: normalizedTarget,
+        command: "npm",
+        args: ["install", "-g", `${packageName}@${normalizedTarget}`],
+        strategy: "npm-global-install",
+        requiresNetwork: true,
+        note: cli === "codex"
+            ? "Explicit Codex targets use the documented npm package path; latest can use 'codex update'."
+            : "Gemini CLI does not expose a self-update command in the gateway-supported CLI surface, so upgrades use npm.",
+    };
+}
+export async function getCliVersion(cli) {
+    const args = VERSION_ARGS[cli];
+    try {
+        const result = await executeCli(cli, args, { timeout: 15_000 });
+        return {
+            cli,
+            command: cli,
+            args,
+            installed: true,
+            version: extractVersion(result.stdout, result.stderr),
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            cli,
+            command: cli,
+            args,
+            installed: false,
+            stdout: "",
+            stderr: "",
+            error: message,
+        };
+    }
+}
+export async function getCliVersions(cli) {
+    const clis = cli ? [cli] : ["claude", "codex", "gemini", "grok"];
+    return Promise.all(clis.map(item => getCliVersion(item)));
+}
+export async function runCliUpgrade(params) {
+    const plan = buildCliUpgradePlan(params.cli, params.target);
+    if (params.dryRun) {
+        return { dryRun: true, plan };
+    }
+    params.logger?.info(`Upgrading ${params.cli} CLI`, {
+        target: plan.target,
+        command: plan.command,
+        args: plan.args,
+    });
+    const result = await executeCli(plan.command, plan.args, {
+        timeout: params.timeoutMs ?? 600_000,
+        logger: params.logger,
+    });
+    return {
+        dryRun: false,
+        plan,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.code,
+    };
+}
+function normalizeTarget(target) {
+    const normalized = target.trim();
+    if (!normalized || normalized.startsWith("-") || /[\u0000-\u001f\u007f\s]/.test(normalized)) {
+        throw new Error("Upgrade target must be a non-empty package tag or version without whitespace and cannot start with '-'");
+    }
+    return normalized;
+}
+function extractVersion(stdout, stderr) {
+    const text = `${stdout}\n${stderr}`
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(line => line.length > 0);
+    return text || undefined;
+}

package/dist/flight-recorder.d.ts

@@ -1,6 +1,6 @@
 export interface FlightLogStart {
     correlationId: string;
-    cli: "claude" | "codex" | "gemini";
+    cli: "claude" | "codex" | "gemini" | "grok";
     model: string;
     prompt: string;
     system?: string;

package/dist/index.d.ts

@@ -37,6 +37,7 @@ export interface GeminiRequestParams {
     optimizePrompt: boolean;
     optimizeResponse?: boolean;
     idleTimeoutMs?: number;
+    forceRefresh?: boolean;
 }
 export interface HandlerDeps {
     sessionManager: ISessionManager;
@@ -51,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;
@@ -60,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 {};