llm-cli-gateway 1.5.4 → 1.5.14

package/dist/job-store.d.ts

@@ -1,4 +1,5 @@
 import type { Logger } from "./logger.js";
+import type { PersistenceConfig } from "./config.js";
 export type JobStoreStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
 export interface JobRecord {
     id: string;
@@ -22,7 +23,43 @@ 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 {
+/**
+ * Public surface every backend (sqlite/postgres/memory) must implement. The
+ * AsyncJobManager talks to this interface only.
+ */
+export interface JobStore {
+    recordStart(input: {
+        id: string;
+        correlationId: string;
+        requestKey: string;
+        cli: string;
+        args: string[];
+        outputFormat?: string;
+        startedAt: string;
+        pid: number | null;
+    }): void;
+    recordOutput(id: string, stdout: string, stderr: string, outputTruncated: boolean): void;
+    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;
+    findByRequestKey(requestKey: string): JobRecord | null;
+    markOrphanedOnStartup(): number;
+    evictExpired(): number;
+    close(): void;
+}
+/**
+ * SQLite-backed job store. Default backend for production. Durable across
+ * gateway restarts; safe for single-instance deployments.
+ */
+export declare class SqliteJobStore implements JobStore {
     private logger;
     private db;
     private retentionMs;
@@ -34,7 +71,10 @@ export declare class JobStore {
     private findByRequestKeyStmt;
     private markOrphanedStmt;
     private deleteExpiredStmt;
-    constructor(dbPath: string, logger?: Logger);
+    constructor(dbPath: string, logger?: Logger, options?: {
+        retentionMs?: number;
+        dedupWindowMs?: number;
+    });
     /**
      * Insert a new running job row. Caller has already computed requestKey.
      */
@@ -82,3 +122,79 @@ export declare class JobStore {
     evictExpired(): number;
     close(): void;
 }
+/**
+ * Backwards-compatibility alias. Older code and tests construct `new JobStore(path)`
+ * directly; that surface now resolves to the SQLite implementation. Prefer
+ * `createJobStore(config)` in new code.
+ *
+ * @deprecated Use `SqliteJobStore` directly, or `createJobStore(persistenceConfig)`.
+ */
+export declare const JobStoreClass: typeof SqliteJobStore;
+/**
+ * In-process job store. Same semantics as SqliteJobStore but state lives in a
+ * Map and is lost on process exit. Use for tests and ephemeral/CI gateways
+ * that have explicitly acknowledged the trade-off via
+ * `[persistence].acknowledgeEphemeral = true`.
+ */
+export declare class MemoryJobStore implements JobStore {
+    private rows;
+    private retentionMs;
+    private dedupWindowMs;
+    constructor(options?: {
+        retentionMs?: number;
+        dedupWindowMs?: number;
+    });
+    recordStart(input: {
+        id: string;
+        correlationId: string;
+        requestKey: string;
+        cli: string;
+        args: string[];
+        outputFormat?: string;
+        startedAt: string;
+        pid: number | null;
+    }): void;
+    recordOutput(id: string, stdout: string, stderr: string, outputTruncated: boolean): void;
+    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;
+    findByRequestKey(requestKey: string): JobRecord | null;
+    /**
+     * In-memory stores have no cross-process state, so any "running" rows here
+     * came from this very process and aren't actually orphaned. No-op.
+     */
+    markOrphanedOnStartup(): number;
+    evictExpired(): number;
+    close(): void;
+}
+/**
+ * Stub for the planned Postgres backend. The interface and config surface ship
+ * now so multi-instance deployments can plan around them, but the
+ * implementation is intentionally not yet provided — calling code must select
+ * `sqlite` or `memory` until a real impl lands.
+ */
+export declare class PostgresJobStore implements JobStore {
+    constructor(_dsn: string, _logger?: Logger);
+    recordStart(): void;
+    recordOutput(): void;
+    recordComplete(): void;
+    getById(): JobRecord | null;
+    findByRequestKey(): JobRecord | null;
+    markOrphanedOnStartup(): number;
+    evictExpired(): number;
+    close(): void;
+}
+/**
+ * Construct the JobStore appropriate to the resolved PersistenceConfig.
+ * Returns `null` when `backend = "none"` — callers must not register
+ * `*_request_async` tools in that case (use `config.asyncJobsEnabled`).
+ */
+export declare function createJobStore(config: PersistenceConfig, logger?: Logger): JobStore | null;

package/dist/job-store.js

@@ -59,7 +59,11 @@ function rowToRecord(row) {
         expiresAt: row.expires_at,
     };
 }
-export class JobStore {
+/**
+ * SQLite-backed job store. Default backend for production. Durable across
+ * gateway restarts; safe for single-instance deployments.
+ */
+export class SqliteJobStore {
     logger;
     db;
     retentionMs;
@@ -71,7 +75,7 @@ export class JobStore {
     findByRequestKeyStmt;
     markOrphanedStmt;
     deleteExpiredStmt;
-    constructor(dbPath, logger = noopLogger) {
+    constructor(dbPath, logger = noopLogger, options = {}) {
         this.logger = logger;
         const require = createRequire(import.meta.url);
         const BetterSqlite3 = require("better-sqlite3");
@@ -114,8 +118,8 @@ export class JobStore {
                 // Best effort permissions hardening.
             }
         }
-        this.retentionMs = resolveJobRetentionMs();
-        this.dedupWindowMs = resolveDedupWindowMs();
+        this.retentionMs = options.retentionMs ?? resolveJobRetentionMs();
+        this.dedupWindowMs = options.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,
@@ -245,7 +249,174 @@ export class JobStore {
             this.db.close();
         }
         catch (err) {
-            this.logger.error("JobStore close failed", err);
+            this.logger.error("SqliteJobStore close failed", err);
         }
     }
 }
+/**
+ * Backwards-compatibility alias. Older code and tests construct `new JobStore(path)`
+ * directly; that surface now resolves to the SQLite implementation. Prefer
+ * `createJobStore(config)` in new code.
+ *
+ * @deprecated Use `SqliteJobStore` directly, or `createJobStore(persistenceConfig)`.
+ */
+export const JobStoreClass = SqliteJobStore;
+/**
+ * In-process job store. Same semantics as SqliteJobStore but state lives in a
+ * Map and is lost on process exit. Use for tests and ephemeral/CI gateways
+ * that have explicitly acknowledged the trade-off via
+ * `[persistence].acknowledgeEphemeral = true`.
+ */
+export class MemoryJobStore {
+    rows = new Map();
+    retentionMs;
+    dedupWindowMs;
+    constructor(options = {}) {
+        this.retentionMs = options.retentionMs ?? resolveJobRetentionMs();
+        this.dedupWindowMs = options.dedupWindowMs ?? resolveDedupWindowMs();
+    }
+    recordStart(input) {
+        this.rows.set(input.id, {
+            id: input.id,
+            correlationId: input.correlationId,
+            requestKey: input.requestKey,
+            cli: input.cli,
+            argsJson: JSON.stringify(input.args),
+            outputFormat: input.outputFormat ?? null,
+            status: "running",
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            outputTruncated: false,
+            error: null,
+            startedAt: input.startedAt,
+            finishedAt: null,
+            pid: input.pid,
+            expiresAt: FAR_FUTURE_ISO,
+        });
+    }
+    recordOutput(id, stdout, stderr, outputTruncated) {
+        const row = this.rows.get(id);
+        if (!row)
+            return;
+        row.stdout = stdout;
+        row.stderr = stderr;
+        row.outputTruncated = outputTruncated;
+    }
+    recordComplete(input) {
+        const row = this.rows.get(input.id);
+        if (!row)
+            return;
+        row.status = input.status;
+        row.exitCode = input.exitCode;
+        row.stdout = input.stdout;
+        row.stderr = input.stderr;
+        row.outputTruncated = input.outputTruncated;
+        row.error = input.error;
+        row.finishedAt = input.finishedAt;
+        row.expiresAt = new Date(Date.parse(input.finishedAt) + this.retentionMs).toISOString();
+    }
+    getById(id) {
+        const row = this.rows.get(id);
+        return row ? { ...row } : null;
+    }
+    findByRequestKey(requestKey) {
+        const cutoffMs = Date.now() - this.dedupWindowMs;
+        let best = null;
+        for (const row of this.rows.values()) {
+            if (row.requestKey !== requestKey)
+                continue;
+            if (row.status !== "running" && row.status !== "completed")
+                continue;
+            if (Date.parse(row.startedAt) < cutoffMs)
+                continue;
+            if (!best || Date.parse(row.startedAt) > Date.parse(best.startedAt)) {
+                best = row;
+            }
+        }
+        return best ? { ...best } : null;
+    }
+    /**
+     * In-memory stores have no cross-process state, so any "running" rows here
+     * came from this very process and aren't actually orphaned. No-op.
+     */
+    markOrphanedOnStartup() {
+        return 0;
+    }
+    evictExpired() {
+        const nowIso = new Date().toISOString();
+        let removed = 0;
+        for (const [id, row] of this.rows) {
+            if (row.expiresAt < nowIso) {
+                this.rows.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    close() {
+        this.rows.clear();
+    }
+}
+/**
+ * Stub for the planned Postgres backend. The interface and config surface ship
+ * now so multi-instance deployments can plan around them, but the
+ * implementation is intentionally not yet provided — calling code must select
+ * `sqlite` or `memory` until a real impl lands.
+ */
+export class PostgresJobStore {
+    constructor(_dsn, _logger = noopLogger) {
+        throw new Error("PostgresJobStore is not yet implemented. Use backend = 'sqlite' (single-instance) or " +
+            "backend = 'memory' (ephemeral) until the Postgres backend ships.");
+    }
+    recordStart() {
+        throw new Error("not implemented");
+    }
+    recordOutput() {
+        throw new Error("not implemented");
+    }
+    recordComplete() {
+        throw new Error("not implemented");
+    }
+    getById() {
+        throw new Error("not implemented");
+    }
+    findByRequestKey() {
+        throw new Error("not implemented");
+    }
+    markOrphanedOnStartup() {
+        throw new Error("not implemented");
+    }
+    evictExpired() {
+        throw new Error("not implemented");
+    }
+    close() {
+        /* no-op */
+    }
+}
+/**
+ * Construct the JobStore appropriate to the resolved PersistenceConfig.
+ * Returns `null` when `backend = "none"` — callers must not register
+ * `*_request_async` tools in that case (use `config.asyncJobsEnabled`).
+ */
+export function createJobStore(config, logger = noopLogger) {
+    const opts = {
+        retentionMs: config.retentionDays * 24 * 60 * 60 * 1000,
+        dedupWindowMs: config.dedupWindowMs,
+    };
+    switch (config.backend) {
+        case "none":
+            return null;
+        case "memory":
+            return new MemoryJobStore(opts);
+        case "postgres":
+            // Throws today; design surface is honest so callers can react.
+            return new PostgresJobStore(config.dsn ?? "", logger);
+        case "sqlite":
+        default:
+            if (!config.path) {
+                throw new Error("SqliteJobStore requires a non-empty path");
+            }
+            return new SqliteJobStore(config.path, logger, opts);
+    }
+}

package/dist/session-manager-pg.d.ts

@@ -24,8 +24,9 @@ export declare class PostgreSQLSessionManager {
      */
     private acquireLockWithRetry;
     /**
-     * Release distributed lock using Lua script for atomic compare-and-delete
-     * Only releases if lockValue matches (prevents releasing another process's lock)
+     * Release distributed lock with optimistic Redis transaction semantics.
+     * Only releases if lockValue matches, which prevents releasing another
+     * process's lock after expiry/reacquire.
      */
     private releaseLock;
     /**

package/dist/session-manager-pg.js

@@ -52,20 +52,25 @@ export class PostgreSQLSessionManager {
         }
     }
     /**
-     * Release distributed lock using Lua script for atomic compare-and-delete
-     * Only releases if lockValue matches (prevents releasing another process's lock)
+     * Release distributed lock with optimistic Redis transaction semantics.
+     * Only releases if lockValue matches, which prevents releasing another
+     * process's lock after expiry/reacquire.
      */
     async releaseLock(key, lockValue) {
         const lockKey = `lock:${key}`;
-        // Lua script for atomic compare-and-delete
-        const script = `
-      if redis.call("get", KEYS[1]) == ARGV[1] then
-        return redis.call("del", KEYS[1])
-      else
-        return 0
-      end
-    `;
-        await this.redis.eval(script, 1, lockKey, lockValue);
+        await this.redis.watch(lockKey);
+        try {
+            const currentValue = await this.redis.get(lockKey);
+            if (currentValue !== lockValue) {
+                await this.redis.unwatch();
+                return;
+            }
+            await this.redis.multi().del(lockKey).exec();
+        }
+        catch (error) {
+            await this.redis.unwatch().catch(() => undefined);
+            throw error;
+        }
     }
     /**
      * Invalidate session cache

package/dist/upstream-contracts.d.ts

@@ -0,0 +1,62 @@
+import type { CliType } from "./session-manager.js";
+export type CliFlagArity = "none" | "one" | "variadic";
+export interface CliFlagContract {
+    arity: CliFlagArity;
+    values?: readonly string[];
+    pattern?: RegExp;
+    description: string;
+}
+export interface CliContract {
+    cli: CliType;
+    executable: string;
+    upstream: string;
+    helpArgs: string[][];
+    flags: Record<string, CliFlagContract>;
+    env?: Record<string, CliFlagContract>;
+    mcpTools: readonly string[];
+    mcpParameters: readonly string[];
+    conformanceFixtures: readonly CliContractFixture[];
+    command?: {
+        requiredFirstArg: string;
+        optionalSecondArg?: string;
+    };
+    maxPositionals: number;
+    resumeMaxPositionals?: number;
+    resumeOnlyFlags?: readonly string[];
+    resumeForbiddenFlags?: readonly string[];
+}
+export interface CliContractFixture {
+    id: string;
+    description: string;
+    args: readonly string[];
+    env?: Record<string, string>;
+    expect: "pass" | "fail";
+}
+export interface ContractViolation {
+    cli: CliType;
+    arg?: string;
+    index?: number;
+    message: string;
+}
+export interface ContractValidationResult {
+    ok: boolean;
+    violations: ContractViolation[];
+}
+export declare const UPSTREAM_CLI_CONTRACTS: Record<CliType, CliContract>;
+export declare function validateUpstreamCliArgs(cli: CliType, args: readonly string[]): ContractValidationResult;
+export declare function assertUpstreamCliArgs(cli: CliType, args: readonly string[]): void;
+export declare function validateUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): ContractValidationResult;
+export declare function assertUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): void;
+export interface InstalledCliContractProbe {
+    cli: CliType;
+    executable: string;
+    available: boolean;
+    checkedHelpCommands: string[][];
+    missingFlags: string[];
+    warnings: string[];
+}
+export declare function probeInstalledCliContract(cli: CliType, timeoutMs?: number): InstalledCliContractProbe;
+export declare function buildUpstreamContractReport(options?: {
+    cli?: CliType;
+    probeInstalled?: boolean;
+}): Record<string, unknown>;