llm-cli-gateway 1.17.9 → 2.1.0

package/dist/index.js

@@ -143,8 +143,8 @@ function loadSkills() {
 const loadedSkills = loadSkills();
 const SERVER_INSTRUCTIONS = `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync) | *_request_async (async)
-Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync) | *_request_async (async) | codex_fork_session (fork a Codex session into a new branch)
+Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation, list_available_models | job_status/job_result (validation jobs)
 Jobs: llm_job_status, llm_job_result, llm_job_cancel
 Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
 Other: list_models, cli_versions, upstream_contracts (use --probe-installed after CLI upgrades to detect drift), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
@@ -159,7 +159,7 @@ Key behaviors:
 Skills (full docs via MCP resources):
 ${loadedSkills.map(s => `- skills://${s.name} — ${s.description}`).join("\n")}`;
 function newGatewayMcpServer() {
-    return new McpServer({ name: "llm-cli-gateway", version: "1.0.0" }, { instructions: SERVER_INSTRUCTIONS });
+    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: SERVER_INSTRUCTIONS });
 }
 let sessionManager;
 let db = null;
@@ -1474,6 +1474,9 @@ export function prepareGrokRequest(params, runtime = resolveGatewayServerRuntime
     if (params.restoreCode) {
         args.push("--restore-code");
     }
+    if (params.leaderSocket) {
+        args.push("--leader-socket", params.leaderSocket);
+    }
     if (params.nativeWorktree === true) {
         args.push("--worktree");
     }
@@ -1976,6 +1979,7 @@ export async function handleGrokRequest(deps, params) {
         noSubagents: params.noSubagents,
         oauth: params.oauth,
         restoreCode: params.restoreCode,
+        leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
     }, runtime);
     if (!("args" in prep))
@@ -2133,6 +2137,7 @@ export async function handleGrokRequestAsync(deps, params) {
         noSubagents: params.noSubagents,
         oauth: params.oauth,
         restoreCode: params.restoreCode,
+        leaderSocket: params.leaderSocket,
         nativeWorktree: params.nativeWorktree,
     }, runtime);
     if (!("args" in prep))
@@ -3488,12 +3493,17 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Grok --restore-code: check out the original session commit when resuming."),
+        leaderSocket: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Grok 0.2.32+ --leader-socket <PATH>: custom leader socket path (default ~/.grok/leader.sock). Targets an isolated leader process, e.g. a local/branch Grok build; name it ~/.grok/leader-*.sock to keep `grok leader list/kill` discovery working."),
         nativeWorktree: z
             .union([z.boolean(), z.string().min(1)])
             .optional()
             .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
         worktree: WORKTREE_SCHEMA.optional(),
-    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, nativeWorktree, worktree, }) => {
+    }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
         return handleGrokRequest({ sessionManager, logger, runtime }, {
             prompt,
             promptParts,
@@ -3542,6 +3552,7 @@ export function createGatewayServer(deps = {}) {
             noSubagents,
             oauth,
             restoreCode,
+            leaderSocket,
             nativeWorktree,
             worktree,
         });
@@ -4298,12 +4309,17 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Grok --restore-code: check out the original session commit when resuming."),
+            leaderSocket: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Grok 0.2.32+ --leader-socket <PATH>: custom leader socket path (default ~/.grok/leader.sock). Targets an isolated leader process, e.g. a local/branch Grok build; name it ~/.grok/leader-*.sock to keep `grok leader list/kill` discovery working."),
             nativeWorktree: z
                 .union([z.boolean(), z.string().min(1)])
                 .optional()
                 .describe("Grok -w/--worktree: native CLI worktree flag (`true` → bare `--worktree`, string → named). NOT gateway slice λ `worktree`."),
             worktree: WORKTREE_SCHEMA.optional(),
-        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, nativeWorktree, worktree, }) => {
+        }, async ({ prompt, promptParts, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, maxTurns, workingDir, sandbox, rules, systemPromptOverride, allow, deny, compactionMode, compactionDetail, agent, bestOfN, check, disableWebSearch, todoGate, verbatim, agents, promptFile, promptJson, single, experimentalMemory, noAltScreen, noMemory, noPlan, noSubagents, oauth, restoreCode, leaderSocket, nativeWorktree, worktree, }) => {
             return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
                 prompt,
                 promptParts,
@@ -4351,6 +4367,7 @@ export function createGatewayServer(deps = {}) {
                 noSubagents,
                 oauth,
                 restoreCode,
+                leaderSocket,
                 nativeWorktree,
                 worktree,
             });

package/dist/job-store.js

@@ -1,8 +1,8 @@
-import { chmodSync, existsSync, mkdirSync } from "fs";
+import { chmodSync } from "fs";
 import os from "os";
 import path from "path";
 import { createHash } from "crypto";
-import { createRequire } from "module";
+import { openDatabase } from "./sqlite-driver.js";
 import { noopLogger } from "./logger.js";
 export function resolveJobStoreDbPath() {
     const configured = process.env.LLM_GATEWAY_JOBS_DB ?? process.env.LLM_GATEWAY_LOGS_DB;
@@ -74,13 +74,7 @@ export class SqliteJobStore {
     deleteExpiredStmt;
     constructor(dbPath, logger = noopLogger, options = {}) {
         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 = openDatabase(dbPath);
         this.db.exec("PRAGMA journal_mode = WAL");
         this.db.exec("PRAGMA synchronous = NORMAL");
         this.db.exec(`
@@ -211,7 +205,7 @@ export class SqliteJobStore {
     markOrphanedOnStartup() {
         const now = new Date().toISOString();
         const expiresAt = new Date(Date.now() + this.retentionMs).toISOString();
-        const rows = (this.selectRunningOrphansStmt.all?.() ?? []);
+        const rows = this.selectRunningOrphansStmt.all();
         const orphaned = rows.map(row => ({
             id: row.id,
             correlationId: row.correlation_id,
@@ -221,12 +215,12 @@ export class SqliteJobStore {
             exitCode: row.exit_code,
         }));
         const result = this.markOrphanedStmt.run(now, expiresAt);
-        return { count: result?.changes ?? 0, orphaned };
+        return { count: Number(result.changes), orphaned };
     }
     evictExpired() {
         const now = new Date().toISOString();
         const result = this.deleteExpiredStmt.run(now);
-        return result?.changes ?? 0;
+        return Number(result.changes);
     }
     close() {
         try {

package/dist/sqlite-driver.d.ts

@@ -0,0 +1,16 @@
+export interface GatewayStatement {
+    run(...args: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...args: unknown[]): unknown;
+    all(...args: unknown[]): unknown[];
+}
+export interface GatewayDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): GatewayStatement;
+    withTransaction<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+    close(): void;
+}
+export declare function openDatabase(dbPath: string): GatewayDatabase;
+export declare function openReadOnly(dbPath: string): GatewayDatabase;

package/dist/sqlite-driver.js

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync } from "fs";
+import path from "path";
+import { createRequire } from "module";
+function loadNodeSqlite() {
+    const require = createRequire(import.meta.url);
+    return require("node:sqlite");
+}
+function wrapStatement(stmt) {
+    return {
+        run(...args) {
+            return stmt.run(...args);
+        },
+        get(...args) {
+            return stmt.get(...args);
+        },
+        all(...args) {
+            return stmt.all(...args);
+        },
+    };
+}
+function statementLeadingKeywords(sql) {
+    const keywords = [];
+    let i = 0;
+    const skipTrivia = () => {
+        for (;;) {
+            while (i < sql.length && /\s|;/.test(sql[i] ?? ""))
+                i++;
+            if (sql.startsWith("--", i)) {
+                i += 2;
+                while (i < sql.length && sql[i] !== "\n")
+                    i++;
+                continue;
+            }
+            if (sql.startsWith("/*", i)) {
+                const end = sql.indexOf("*/", i + 2);
+                i = end === -1 ? sql.length : end + 2;
+                continue;
+            }
+            break;
+        }
+    };
+    const skipQuoted = (quote) => {
+        i++;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                return;
+            }
+            i++;
+        }
+    };
+    while (i < sql.length) {
+        skipTrivia();
+        const m = /^[a-zA-Z]+/.exec(sql.slice(i));
+        if (m) {
+            keywords.push(m[0].toUpperCase());
+        }
+        while (i < sql.length && sql[i] !== ";") {
+            if (sql.startsWith("--", i)) {
+                i += 2;
+                while (i < sql.length && sql[i] !== "\n")
+                    i++;
+            }
+            else if (sql.startsWith("/*", i)) {
+                const end = sql.indexOf("*/", i + 2);
+                i = end === -1 ? sql.length : end + 2;
+            }
+            else if (sql[i] === "'" || sql[i] === '"' || sql[i] === "`") {
+                skipQuoted(sql[i]);
+            }
+            else if (sql[i] === "[") {
+                i++;
+                while (i < sql.length && sql[i] !== "]")
+                    i++;
+                if (i < sql.length)
+                    i++;
+            }
+            else {
+                i++;
+            }
+        }
+    }
+    return keywords;
+}
+class GatewayDatabaseImpl {
+    db;
+    readOnly;
+    inTransaction = false;
+    constructor(db, readOnly = false) {
+        this.db = db;
+        this.readOnly = readOnly;
+    }
+    guardReadOnly(sql) {
+        if (this.readOnly && statementLeadingKeywords(sql).includes("VACUUM")) {
+            throw new Error("read-only connection rejects VACUUM (writes to disk despite readOnly)");
+        }
+    }
+    exec(sql) {
+        this.guardReadOnly(sql);
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        this.guardReadOnly(sql);
+        return wrapStatement(this.db.prepare(sql));
+    }
+    withTransaction(fn) {
+        return (...args) => {
+            if (this.inTransaction) {
+                throw new Error("nested transaction");
+            }
+            this.db.exec("BEGIN");
+            this.inTransaction = true;
+            try {
+                fn(...args);
+                this.db.exec("COMMIT");
+            }
+            catch (error) {
+                try {
+                    this.db.exec("ROLLBACK");
+                }
+                catch {
+                }
+                throw error;
+            }
+            finally {
+                this.inTransaction = false;
+            }
+        };
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function openDatabase(dbPath) {
+    const { DatabaseSync } = loadNodeSqlite();
+    const directory = path.dirname(dbPath);
+    if (!existsSync(directory)) {
+        mkdirSync(directory, { recursive: true });
+    }
+    return new GatewayDatabaseImpl(new DatabaseSync(dbPath));
+}
+export function openReadOnly(dbPath) {
+    const { DatabaseSync } = loadNodeSqlite();
+    return new GatewayDatabaseImpl(new DatabaseSync(dbPath, { readOnly: true }), true);
+}

package/dist/upstream-contracts.d.ts

@@ -5,6 +5,7 @@ export interface CliFlagContract {
     values?: readonly string[];
     pattern?: RegExp;
     description: string;
+    hiddenFromHelp?: boolean;
 }
 export interface CliUpstreamMetadata {
     sourceUrls: readonly string[];
@@ -32,6 +33,7 @@ export interface CliContract {
     resumeMaxPositionals?: number;
     resumeOnlyFlags?: readonly string[];
     resumeForbiddenFlags?: readonly string[];
+    acknowledgedUpstreamFlags?: readonly string[];
     upstreamMetadata?: CliUpstreamMetadata;
 }
 export interface CliContractFixture {
@@ -57,6 +59,13 @@ export declare function assertUpstreamCliArgs(cli: CliType, args: readonly strin
 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 declare function extractDiscoveredFlags(helpText: string): readonly string[];
+export interface FlagDriftResult {
+    missingFlags: string[];
+    extraFlags: readonly string[];
+    acknowledgedExtraFlags: readonly string[];
+    warnings: string[];
+}
+export declare function computeFlagDrift(contract: CliContract, helpText: string, discoveredFlags: readonly string[]): FlagDriftResult;
 export interface InstalledCliContractProbe {
     cli: CliType;
     executable: string;
@@ -66,6 +75,7 @@ export interface InstalledCliContractProbe {
     checkedHelpCommands: string[][];
     missingFlags: string[];
     extraFlags: readonly string[];
+    acknowledgedExtraFlags: readonly string[];
     discoveredFlags: readonly string[];
     helpHash?: string;
     versionHint?: string;

package/dist/upstream-contracts.js

@@ -99,7 +99,12 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 pattern: /^[0-9]+(?:\.[0-9]+)?$/,
                 description: "Budget cap in USD",
             },
-            "--max-turns": { arity: "one", pattern: /^[1-9][0-9]*$/, description: "Turn cap" },
+            "--max-turns": {
+                arity: "one",
+                pattern: /^[1-9][0-9]*$/,
+                description: "Turn cap",
+                hiddenFromHelp: true,
+            },
             "--effort": { arity: "one", values: EFFORT_LEVELS, description: "Reasoning effort" },
             "--exclude-dynamic-system-prompt-sections": {
                 arity: "none",
@@ -136,6 +141,37 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 description: 'Restrict the available built-in tool set ("" disables all)',
             },
         },
+        acknowledgedUpstreamFlags: [
+            "--allow-dangerously-skip-permissions",
+            "--allowed",
+            "--bare",
+            "--betas",
+            "--brief",
+            "--chrome",
+            "--dangerously-skip-permissions",
+            "--debug",
+            "--debug-file",
+            "--disable-slash-commands",
+            "--disallowed",
+            "--file",
+            "--from-pr",
+            "--ide",
+            "--include-hook-events",
+            "--mcp-debug",
+            "--name",
+            "--no-chrome",
+            "--plugin-dir",
+            "--plugin-url",
+            "--print",
+            "--prompt-suggestions",
+            "--remote-control",
+            "--remote-control-session-name-prefix",
+            "--replay-user-messages",
+            "--resume",
+            "--tmux",
+            "--version",
+            "--worktree",
+        ],
         env: {},
         conformanceFixtures: [
             {
@@ -518,6 +554,26 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 description: "Auto-approve all actions (gemini -y/--yolo). Functionally equivalent to --approval-mode yolo; the gateway emits at most one of the two.",
             },
         },
+        acknowledgedUpstreamFlags: [
+            "--accept-raw-output-risk",
+            "--acp",
+            "--debug",
+            "--delete-session",
+            "--experimental-acp",
+            "--extensions",
+            "--list-extensions",
+            "--list-sessions",
+            "--output-format",
+            "--prompt",
+            "--prompt-interactive",
+            "--raw-output",
+            "--sandbox",
+            "--screen-reader",
+            "--session-file",
+            "--session-id",
+            "--version",
+            "--worktree",
+        ],
         env: {},
         conformanceFixtures: [
             {
@@ -612,6 +668,7 @@ export const UPSTREAM_CLI_CONTRACTS = {
             "noSubagents",
             "oauth",
             "restoreCode",
+            "leaderSocket",
             "nativeWorktree",
         ],
         flags: {
@@ -693,6 +750,10 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 arity: "none",
                 description: "Check out the original session commit when resuming",
             },
+            "--leader-socket": {
+                arity: "one",
+                description: "Custom leader socket path (isolated leader, Grok 0.2.32+)",
+            },
             "--single": { arity: "one", description: "Single-turn prompt" },
             "--todo-gate": { arity: "none", description: "Enable runtime turn-end TodoGate" },
             "--verbatim": { arity: "none", description: "Send prompt exactly as given" },
@@ -843,6 +904,18 @@ export const UPSTREAM_CLI_CONTRACTS = {
                 ],
                 expect: "pass",
             },
+            {
+                id: "grok-leader-socket",
+                description: "Grok 0.2.32: --leader-socket <PATH> is accepted",
+                args: ["-p", "hello", "--leader-socket", "/home/user/.grok/leader-branch.sock"],
+                expect: "pass",
+            },
+            {
+                id: "grok-leader-socket-missing-value",
+                description: "Grok 0.2.32: --leader-socket without a path is rejected (arity one)",
+                args: ["-p", "hello", "--leader-socket"],
+                expect: "fail",
+            },
         ],
     },
     mistral: {
@@ -1220,6 +1293,42 @@ export function extractDiscoveredFlags(helpText) {
     }
     return Array.from(discovered).sort();
 }
+export function computeFlagDrift(contract, helpText, discoveredFlags) {
+    const warnings = [];
+    const missingFlags = [];
+    for (const [flag, spec] of Object.entries(contract.flags)) {
+        const inHelp = helpText.includes(flag);
+        if (spec.hiddenFromHelp) {
+            if (inHelp) {
+                warnings.push(`${flag} is marked hiddenFromHelp but now appears in ${contract.executable} help output; remove the hiddenFromHelp marker from the contract`);
+            }
+            continue;
+        }
+        if (!inHelp)
+            missingFlags.push(flag);
+    }
+    const contractFlagSet = new Set(Object.keys(contract.flags));
+    const acknowledged = new Set(contract.acknowledgedUpstreamFlags ?? []);
+    const extraFlags = [];
+    const acknowledgedExtraFlags = [];
+    for (const flag of discoveredFlags) {
+        if (contractFlagSet.has(flag))
+            continue;
+        if (acknowledged.has(flag)) {
+            acknowledgedExtraFlags.push(flag);
+        }
+        else {
+            extraFlags.push(flag);
+        }
+    }
+    const discoveredSet = new Set(discoveredFlags);
+    for (const flag of acknowledged) {
+        if (!discoveredSet.has(flag)) {
+            warnings.push(`acknowledged upstream flag ${flag} no longer appears in ${contract.executable} help output; remove it from acknowledgedUpstreamFlags`);
+        }
+    }
+    return { missingFlags, extraFlags, acknowledgedExtraFlags, warnings };
+}
 export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
     const contract = UPSTREAM_CLI_CONTRACTS[cli];
     const outputs = [];
@@ -1252,6 +1361,7 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
                 checkedHelpCommands: contract.helpArgs,
                 missingFlags: [],
                 extraFlags: [],
+                acknowledgedExtraFlags: [],
                 discoveredFlags: [],
                 helpHash: undefined,
                 versionHint: undefined,
@@ -1265,10 +1375,9 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
         }
     }
     const helpText = outputs.join("\n");
-    const missingFlags = Object.keys(contract.flags).filter(flag => !helpText.includes(flag));
     const discoveredFlags = extractDiscoveredFlags(helpText);
-    const contractFlagSet = new Set(Object.keys(contract.flags));
-    const extraFlags = discoveredFlags.filter(f => !contractFlagSet.has(f));
+    const drift = computeFlagDrift(contract, helpText, discoveredFlags);
+    warnings.push(...drift.warnings);
     const versionMatch = helpText.match(/^\s*(?:[A-Za-z][\w .-]+)?v?\d+\.\d+\S*/m);
     const versionHint = versionMatch ? versionMatch[0].trim().slice(0, 80) : undefined;
     const helpHash = createHash("sha256").update(helpText).digest("hex");
@@ -1279,8 +1388,9 @@ export function probeInstalledCliContract(cli, timeoutMs = 5_000) {
         resolvedArgs,
         available: true,
         checkedHelpCommands: contract.helpArgs,
-        missingFlags,
-        extraFlags,
+        missingFlags: drift.missingFlags,
+        extraFlags: drift.extraFlags,
+        acknowledgedExtraFlags: drift.acknowledgedExtraFlags,
         discoveredFlags,
         helpHash,
         versionHint,