llm-cli-gateway 1.5.4 → 1.5.14

package/dist/config.js

@@ -1,4 +1,9 @@
+import { existsSync, readFileSync } from "fs";
+import os from "os";
+import path from "path";
+import { createRequire } from "module";
 import { z } from "zod";
+import { logWarn, noopLogger } from "./logger.js";
 // Zod schemas for configuration validation
 const DatabaseUrlSchema = z
     .string()
@@ -60,3 +65,165 @@ export function loadConfig() {
         sessionTtl,
     };
 }
+//──────────────────────────────────────────────────────────────────────────────
+// Persistence configuration
+//
+// The async job store is now driven by a typed config (TOML file +
+// validated env-var overrides) instead of a single LLM_GATEWAY_LOGS_DB env
+// var. The structural invariant: `*_request_async` tools are only registered
+// when a real durable store is attached, so silent in-memory loss after the
+// 1h TTL becomes impossible.
+//
+// Backends:
+//   - "sqlite":   durable on disk (default).
+//   - "postgres": durable in Postgres (interface only — impl not yet shipped).
+//   - "memory":   in-process MemoryJobStore. Process-lifetime durability only.
+//                 Requires acknowledgeEphemeral=true to register async tools.
+//   - "none":     no store. Async tools are NOT registered.
+//──────────────────────────────────────────────────────────────────────────────
+export const PERSISTENCE_BACKENDS = ["sqlite", "postgres", "memory", "none"];
+export const DEFAULT_JOB_RETENTION_DAYS = 30;
+export const DEFAULT_DEDUP_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+const PersistenceSchema = z
+    .object({
+    backend: z.enum(PERSISTENCE_BACKENDS).default("sqlite"),
+    path: z.string().optional(),
+    dsn: z.string().optional(),
+    retentionDays: z.number().positive().default(DEFAULT_JOB_RETENTION_DAYS),
+    dedupWindowMs: z.number().int().nonnegative().default(DEFAULT_DEDUP_WINDOW_MS),
+    acknowledgeEphemeral: z.boolean().default(false),
+})
+    .strict();
+const DEFAULT_SQLITE_PATH = path.join(os.homedir(), ".llm-cli-gateway", "logs.db");
+function defaultPersistenceConfigPath() {
+    return (process.env.LLM_GATEWAY_CONFIG ?? path.join(os.homedir(), ".llm-cli-gateway", "config.toml"));
+}
+/**
+ * Read and parse the optional TOML config file. Returns the raw `[persistence]`
+ * table (if present) and the file path. Missing file is fine — defaults apply.
+ */
+function readPersistenceFile(configPath, logger) {
+    if (!existsSync(configPath)) {
+        return { raw: undefined, sourcePath: null };
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const TOML = require("toml");
+        const text = readFileSync(configPath, "utf-8");
+        const parsed = TOML.parse(text);
+        return { raw: parsed?.persistence, sourcePath: configPath };
+    }
+    catch (err) {
+        logger.error(`Failed to parse gateway config at ${configPath}; using defaults`, err);
+        return { raw: undefined, sourcePath: null };
+    }
+}
+/**
+ * Apply legacy env-var overrides on top of the file/defaults. Each application
+ * appends a string to `sources.envOverrides` and emits a one-time deprecation
+ * warning so operators can migrate to the config file.
+ */
+function applyEnvOverrides(base, logger, sources) {
+    const out = { ...base };
+    const jobsDbEnv = process.env.LLM_GATEWAY_JOBS_DB;
+    const logsDbEnv = process.env.LLM_GATEWAY_LOGS_DB;
+    // Empty string is treated as "not set" — only an explicitly non-empty value
+    // (or the literal "none") overrides the file/defaults. This avoids the
+    // old footgun where `LLM_GATEWAY_LOGS_DB=` silently disabled persistence.
+    const dbEnvRaw = jobsDbEnv && jobsDbEnv.length > 0
+        ? jobsDbEnv
+        : logsDbEnv && logsDbEnv.length > 0
+            ? logsDbEnv
+            : undefined;
+    if (dbEnvRaw !== undefined) {
+        const normalized = dbEnvRaw.trim().toLowerCase();
+        if (normalized === "none") {
+            out.backend = "none";
+            out.path = undefined;
+        }
+        else {
+            out.backend = "sqlite";
+            out.path = dbEnvRaw.trim();
+        }
+        const which = jobsDbEnv && jobsDbEnv.length > 0 ? "LLM_GATEWAY_JOBS_DB" : "LLM_GATEWAY_LOGS_DB";
+        sources.envOverrides.push(which);
+        logWarn(logger, `${which} is deprecated; migrate to [persistence] in ~/.llm-cli-gateway/config.toml`, { backend: out.backend, path: out.path ?? null });
+    }
+    const retEnv = process.env.LLM_GATEWAY_JOB_RETENTION_DAYS;
+    if (retEnv !== undefined) {
+        const n = Number(retEnv);
+        if (Number.isFinite(n) && n > 0) {
+            out.retentionDays = n;
+            sources.envOverrides.push("LLM_GATEWAY_JOB_RETENTION_DAYS");
+            logWarn(logger, "LLM_GATEWAY_JOB_RETENTION_DAYS is deprecated; set [persistence].retentionDays in config.toml", { retentionDays: n });
+        }
+    }
+    const dedupEnv = process.env.LLM_GATEWAY_DEDUP_WINDOW_MS;
+    if (dedupEnv !== undefined) {
+        const n = Number(dedupEnv);
+        if (Number.isFinite(n) && n >= 0) {
+            out.dedupWindowMs = n;
+            sources.envOverrides.push("LLM_GATEWAY_DEDUP_WINDOW_MS");
+            logWarn(logger, "LLM_GATEWAY_DEDUP_WINDOW_MS is deprecated; set [persistence].dedupWindowMs in config.toml", { dedupWindowMs: n });
+        }
+    }
+    const ackEnv = process.env.LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL;
+    if (ackEnv && ackEnv.length > 0) {
+        out.acknowledgeEphemeral = /^(1|true|yes)$/i.test(ackEnv.trim());
+        sources.envOverrides.push("LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL");
+        logWarn(logger, "LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL is deprecated; set [persistence].acknowledgeEphemeral in config.toml", { acknowledgeEphemeral: out.acknowledgeEphemeral });
+    }
+    return out;
+}
+function expandHome(p) {
+    return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+/**
+ * Load and validate the persistence config from (in order, last-write-wins):
+ *   1. Built-in defaults (backend=sqlite, default retention/dedup).
+ *   2. ~/.llm-cli-gateway/config.toml (or $LLM_GATEWAY_CONFIG).
+ *   3. Legacy env vars (with deprecation warning).
+ *
+ * Throws on incoherent configs (memory/none + asyncJobsEnabled without ack).
+ */
+export function loadPersistenceConfig(logger = noopLogger) {
+    const configPath = defaultPersistenceConfigPath();
+    const { raw, sourcePath } = readPersistenceFile(configPath, logger);
+    const sources = {
+        configFile: sourcePath,
+        envOverrides: [],
+    };
+    const merged = applyEnvOverrides(raw ?? {}, logger, sources);
+    let parsed;
+    try {
+        parsed = PersistenceSchema.parse(merged);
+    }
+    catch (err) {
+        throw new Error(`Invalid [persistence] config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const backend = parsed.backend;
+    const resolvedPath = backend === "sqlite" ? expandHome(parsed.path ?? DEFAULT_SQLITE_PATH) : null;
+    const dsn = backend === "postgres" ? (parsed.dsn ?? null) : null;
+    if (backend === "postgres" && !dsn) {
+        throw new Error("[persistence].backend = 'postgres' requires a non-empty 'dsn' (e.g. postgresql://user:pw@host/db)");
+    }
+    if (backend === "memory" && !parsed.acknowledgeEphemeral) {
+        throw new Error("[persistence].backend = 'memory' is ephemeral — async job results are lost on gateway exit. " +
+            "Set [persistence].acknowledgeEphemeral = true (or LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL=1) to confirm this is intentional.");
+    }
+    const asyncJobsEnabled = backend === "sqlite" || backend === "postgres" || backend === "memory";
+    if (backend === "none") {
+        logWarn(logger, "Async job persistence is DISABLED (backend = 'none'). " +
+            "*_request_async tools will NOT be registered on this gateway.");
+    }
+    return {
+        backend,
+        path: resolvedPath,
+        dsn,
+        retentionDays: parsed.retentionDays,
+        dedupWindowMs: parsed.dedupWindowMs,
+        acknowledgeEphemeral: parsed.acknowledgeEphemeral,
+        asyncJobsEnabled,
+        sources,
+    };
+}

package/dist/entrypoint-url.d.ts

@@ -0,0 +1 @@
+export declare function entrypointFileURL(path: string | undefined): string;

package/dist/entrypoint-url.js

@@ -0,0 +1,5 @@
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+export function entrypointFileURL(path) {
+    return path ? pathToFileURL(realpathSync(path)).href : "";
+}

package/dist/executor.d.ts

@@ -1,4 +1,4 @@
-import { ChildProcess } from "child_process";
+import { ChildProcess, type SpawnOptions } from "child_process";
 import type { Logger } from "./logger.js";
 export interface ExecuteOptions {
     timeout?: number;
@@ -14,6 +14,7 @@ export interface ExecuteResult {
     code: number;
 }
 export declare function getExtendedPath(): string;
+export declare function shouldDetachProviderProcess(platform?: NodeJS.Platform): boolean;
 export declare function registerProcessGroup(pid: number): void;
 export declare function unregisterProcessGroup(pid: number): void;
 /**
@@ -29,4 +30,9 @@ export declare function killAllProcessGroups(): Promise<void>;
  * if the group kill fails (e.g., pid not yet assigned).
  */
 export declare function killProcessGroup(proc: ChildProcess, signal: NodeJS.Signals): boolean;
+export declare function spawnCliProcess(command: string, args: string[], options: {
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+    stdio: SpawnOptions["stdio"];
+}): ChildProcess;
 export declare function executeCli(command: string, args: string[], options?: ExecuteOptions): Promise<ExecuteResult>;

package/dist/executor.js

@@ -1,4 +1,4 @@
-import { spawn } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { readdirSync, existsSync } from "fs";
@@ -55,6 +55,12 @@ export function getExtendedPath() {
 }
 /** Registry of active detached process groups for shutdown cleanup. */
 const activeProcessGroups = new Set();
+export function shouldDetachProviderProcess(platform = process.platform) {
+    // On Windows, detached console children can flash visible cmd/conhost windows
+    // when provider CLIs are native console apps or .cmd shims. Keep them in the
+    // gateway process tree and rely on hidden-window spawn plus taskkill cleanup.
+    return platform !== "win32";
+}
 export function registerProcessGroup(pid) {
     activeProcessGroups.add(pid);
 }
@@ -72,21 +78,31 @@ export function killAllProcessGroups() {
     if (activeProcessGroups.size === 0)
         return Promise.resolve();
     for (const pid of activeProcessGroups) {
-        try {
-            process.kill(-pid, "SIGTERM");
+        if (process.platform === "win32") {
+            killWindowsProcessTree(pid);
         }
-        catch {
-            /* ESRCH ok */
+        else {
+            try {
+                process.kill(-pid, "SIGTERM");
+            }
+            catch {
+                /* ESRCH ok */
+            }
         }
     }
     return new Promise(resolve => {
         setTimeout(() => {
             for (const pid of activeProcessGroups) {
-                try {
-                    process.kill(-pid, "SIGKILL");
+                if (process.platform === "win32") {
+                    killWindowsProcessTree(pid);
                 }
-                catch {
-                    /* ESRCH ok */
+                else {
+                    try {
+                        process.kill(-pid, "SIGKILL");
+                    }
+                    catch {
+                        /* ESRCH ok */
+                    }
                 }
             }
             activeProcessGroups.clear();
@@ -100,6 +116,9 @@ export function killAllProcessGroups() {
  */
 export function killProcessGroup(proc, signal) {
     if (proc.pid) {
+        if (process.platform === "win32") {
+            return killWindowsProcessTree(proc.pid);
+        }
         try {
             process.kill(-proc.pid, signal);
             return true;
@@ -124,21 +143,37 @@ export function killProcessGroup(proc, signal) {
         return false;
     }
 }
+function killWindowsProcessTree(pid) {
+    const result = spawnSync("taskkill.exe", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    return result.status === 0;
+}
+export function spawnCliProcess(command, args, options) {
+    const detached = shouldDetachProviderProcess();
+    const proc = spawn(command, args, {
+        cwd: options.cwd,
+        detached,
+        windowsHide: true,
+        stdio: options.stdio,
+        env: options.env,
+    });
+    if (proc.pid)
+        registerProcessGroup(proc.pid);
+    proc.unref();
+    return proc;
+}
 export async function executeCli(command, args, options = {}) {
     const { timeout, idleTimeout, cwd, env: extraEnv } = options;
     const extendedPath = getExtendedPath();
     const circuitBreaker = getCircuitBreaker(command);
     const runOnce = () => new Promise((resolve, reject) => {
-        const proc = spawn(command, args, {
+        const proc = spawnCliProcess(command, args, {
             cwd,
-            detached: true,
             stdio: ["ignore", "pipe", "pipe"],
             env: { ...process.env, PATH: extendedPath, ...(extraEnv ?? {}) },
         });
-        if (proc.pid)
-            registerProcessGroup(proc.pid);
-        // Prevent detached process from keeping parent alive when not needed
-        proc.unref();
         let stdout = "";
         let stderr = "";
         let timedOut = false;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { ISessionManager } from "./session-manager.js";
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
+import { type PersistenceConfig } from "./config.js";
 import { DatabaseConnection } from "./db.js";
 import { AsyncJobManager } from "./async-job-manager.js";
 import { ApprovalManager, ApprovalRecord } from "./approval-manager.js";
@@ -47,6 +48,7 @@ export interface GatewayServerDeps {
     approvalManager?: ApprovalManager;
     flightRecorder?: FlightRecorderLike;
     logger?: GatewayLogger;
+    persistence?: PersistenceConfig;
 }
 interface GatewayServerRuntime {
     sessionManager: ISessionManager;
@@ -57,6 +59,7 @@ interface GatewayServerRuntime {
     approvalManager: ApprovalManager;
     flightRecorder: FlightRecorderLike;
     logger: GatewayLogger;
+    persistence: PersistenceConfig;
 }
 interface CliRequestPrep {
     corrId: string;