llm-cli-gateway 2.13.1 → 2.14.0-rc.1

package/dist/postgres-job-store-worker.js

@@ -0,0 +1,327 @@
+import { writeFileSync } from "node:fs";
+import { parentPort, workerData } from "node:worker_threads";
+let pool = null;
+function signal(shared, status) {
+    const view = new Int32Array(shared);
+    Atomics.store(view, 0, status);
+    Atomics.notify(view, 0, 1);
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function fail(error) {
+    return {
+        ok: false,
+        error: {
+            message: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        },
+    };
+}
+function getPool() {
+    if (!pool)
+        throw new Error("PostgresJobStore worker pool is not initialized");
+    return pool;
+}
+async function withClient(fn) {
+    const client = await getPool().connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        client.release();
+    }
+}
+async function init() {
+    let pg;
+    try {
+        pg = await import("pg");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
+            throw new Error("Postgres persistence requires optional peer dependency 'pg'. Install it alongside llm-cli-gateway to use backend = 'postgres'.", { cause: error });
+        }
+        throw error;
+    }
+    pool = new pg.Pool({
+        connectionString: workerData.dsn,
+        connectionTimeoutMillis: workerData.connectionTimeoutMillis,
+    });
+    await getPool().query("SELECT 1");
+    await getPool().query(`
+    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 BOOLEAN NOT NULL DEFAULT FALSE,
+      error TEXT,
+      started_at TEXT NOT NULL,
+      finished_at TEXT,
+      pid INTEGER,
+      expires_at TEXT NOT NULL,
+      owner_principal TEXT,
+      transport TEXT NOT NULL DEFAULT 'process',
+      http_status INTEGER,
+      payload_json TEXT
+    );
+    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);
+
+    CREATE TABLE IF NOT EXISTS validation_runs (
+      validation_id TEXT PRIMARY KEY,
+      owner_principal TEXT NOT NULL,
+      intent TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      request_json TEXT NOT NULL,
+      provider_links TEXT NOT NULL,
+      judge_link TEXT,
+      status TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_validation_runs_owner ON validation_runs(owner_principal);
+
+    CREATE TABLE IF NOT EXISTS validation_run_jobs (
+      job_id TEXT PRIMARY KEY,
+      validation_id TEXT NOT NULL,
+      role TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_validation_run_jobs_run ON validation_run_jobs(validation_id);
+
+    CREATE TABLE IF NOT EXISTS validation_receipts (
+      validation_id TEXT PRIMARY KEY,
+      owner_principal TEXT NOT NULL,
+      minted_at TEXT NOT NULL,
+      schema_version TEXT NOT NULL,
+      report_json TEXT NOT NULL,
+      canonical_sha256 TEXT NOT NULL,
+      prev_sha256 TEXT,
+      seq INTEGER,
+      signature TEXT,
+      models TEXT NOT NULL,
+      has_material_disagreement BOOLEAN NOT NULL,
+      confidence TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_validation_receipts_owner ON validation_receipts(owner_principal);
+  `);
+    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS owner_principal TEXT");
+    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS transport TEXT NOT NULL DEFAULT 'process'");
+    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS http_status INTEGER");
+    await getPool().query("ALTER TABLE jobs ADD COLUMN IF NOT EXISTS payload_json TEXT");
+}
+async function op(method, args) {
+    switch (method) {
+        case "init":
+            await init();
+            return null;
+        case "recordStart": {
+            const input = args[0];
+            await getPool().query(`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, owner_principal,
+                           transport, http_status, payload_json)
+         VALUES ($1, $2, $3, $4, $5, $6, 'running', NULL, '', '', FALSE, NULL,
+                 $7, NULL, $8, $9, $10, $11, NULL, $12)`, [
+                input.id,
+                input.correlationId,
+                input.requestKey,
+                input.cli,
+                JSON.stringify(input.args),
+                input.outputFormat ?? null,
+                input.startedAt,
+                input.pid,
+                workerData.farFutureIso,
+                input.ownerPrincipal ?? null,
+                input.transport ?? "process",
+                input.payloadJson ?? null,
+            ]);
+            return null;
+        }
+        case "recordOutput":
+            await getPool().query("UPDATE jobs SET stdout = $2, stderr = $3, output_truncated = $4 WHERE id = $1", args);
+            return null;
+        case "recordComplete": {
+            const input = args[0];
+            const expiresAt = new Date(Date.parse(input.finishedAt) + workerData.retentionMs).toISOString();
+            await getPool().query(`UPDATE jobs
+         SET status = $2, exit_code = $3, stdout = $4, stderr = $5,
+             output_truncated = $6, error = $7, finished_at = $8,
+             expires_at = $9, http_status = $10
+         WHERE id = $1`, [
+                input.id,
+                input.status,
+                input.exitCode,
+                input.stdout,
+                input.stderr,
+                input.outputTruncated,
+                input.error,
+                input.finishedAt,
+                expiresAt,
+                input.httpStatus ?? null,
+            ]);
+            return null;
+        }
+        case "getById": {
+            const result = await getPool().query("SELECT * FROM jobs WHERE id = $1", [args[0]]);
+            return result.rows[0] ?? null;
+        }
+        case "findByRequestKey": {
+            const cutoff = new Date(Date.now() - workerData.dedupWindowMs).toISOString();
+            const result = await getPool().query(`SELECT * FROM jobs
+         WHERE request_key = $1
+           AND started_at >= $2
+           AND status IN ('running', 'completed')
+         ORDER BY started_at DESC
+         LIMIT 1`, [args[0], cutoff]);
+            return result.rows[0] ?? null;
+        }
+        case "markOrphanedOnStartup":
+            return await withClient(async (client) => {
+                const now = new Date().toISOString();
+                const expiresAt = new Date(Date.now() + workerData.retentionMs).toISOString();
+                await client.query("BEGIN");
+                try {
+                    const rows = await client.query("SELECT id, correlation_id, started_at, stdout, stderr, exit_code, transport, http_status FROM jobs WHERE status = 'running'");
+                    const update = await client.query(`UPDATE jobs
+             SET status = 'orphaned',
+                 error = COALESCE(error, 'Gateway restarted while job was running'),
+                 finished_at = COALESCE(finished_at, $1),
+                 expires_at = $2
+             WHERE status = 'running'`, [now, expiresAt]);
+                    await client.query("COMMIT");
+                    return { count: update.rowCount ?? 0, orphaned: rows.rows };
+                }
+                catch (error) {
+                    await client.query("ROLLBACK");
+                    throw error;
+                }
+            });
+        case "evictExpired": {
+            const result = await getPool().query("DELETE FROM jobs WHERE expires_at < $1", [
+                new Date().toISOString(),
+            ]);
+            return result.rowCount ?? 0;
+        }
+        case "recordValidationRun": {
+            const run = args[0];
+            await withClient(async (client) => {
+                await client.query("BEGIN");
+                try {
+                    await client.query(`INSERT INTO validation_runs
+               (validation_id, owner_principal, intent, created_at, request_json,
+                provider_links, judge_link, status)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+             ON CONFLICT (validation_id) DO NOTHING`, [
+                        run.validationId,
+                        run.ownerPrincipal,
+                        run.intent,
+                        run.createdAt,
+                        run.requestJson,
+                        JSON.stringify(run.providerLinks),
+                        run.judgeLink ? JSON.stringify(run.judgeLink) : null,
+                        run.status,
+                    ]);
+                    for (const link of run.providerLinks) {
+                        await client.query(`INSERT INTO validation_run_jobs (job_id, validation_id, role)
+               VALUES ($1, $2, 'provider')
+               ON CONFLICT (job_id) DO NOTHING`, [link.jobId, run.validationId]);
+                    }
+                    await client.query("COMMIT");
+                }
+                catch (error) {
+                    await client.query("ROLLBACK");
+                    throw error;
+                }
+            });
+            return null;
+        }
+        case "getValidationRun": {
+            const result = await getPool().query("SELECT * FROM validation_runs WHERE validation_id = $1", [args[0]]);
+            return result.rows[0] ?? null;
+        }
+        case "setValidationJudgeLink": {
+            const [validationId, judgeLink] = args;
+            await withClient(async (client) => {
+                await client.query("BEGIN");
+                try {
+                    await client.query("UPDATE validation_runs SET judge_link = $2 WHERE validation_id = $1", [validationId, JSON.stringify(judgeLink)]);
+                    await client.query(`INSERT INTO validation_run_jobs (job_id, validation_id, role)
+             VALUES ($1, $2, 'judge')
+             ON CONFLICT (job_id) DO NOTHING`, [judgeLink.jobId, validationId]);
+                    await client.query("COMMIT");
+                }
+                catch (error) {
+                    await client.query("ROLLBACK");
+                    throw error;
+                }
+            });
+            return null;
+        }
+        case "setValidationRunStatus":
+            await getPool().query("UPDATE validation_runs SET status = $2 WHERE validation_id = $1", args);
+            return null;
+        case "getValidationRunIdByJobId": {
+            const result = await getPool().query("SELECT validation_id FROM validation_run_jobs WHERE job_id = $1", [args[0]]);
+            return result.rows[0] ? result.rows[0].validation_id : null;
+        }
+        case "recordValidationReceipt": {
+            const receipt = args[0];
+            await getPool().query(`INSERT INTO validation_receipts
+           (validation_id, owner_principal, minted_at, schema_version, report_json,
+            canonical_sha256, prev_sha256, seq, signature, models,
+            has_material_disagreement, confidence)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+         ON CONFLICT (validation_id) DO NOTHING`, [
+                receipt.validationId,
+                receipt.ownerPrincipal,
+                receipt.mintedAt,
+                receipt.schemaVersion,
+                receipt.reportJson,
+                receipt.canonicalSha256,
+                receipt.prevSha256,
+                receipt.seq,
+                receipt.signature,
+                JSON.stringify(receipt.models),
+                receipt.hasMaterialDisagreement,
+                receipt.confidence,
+            ]);
+            return null;
+        }
+        case "getValidationReceipt": {
+            const result = await getPool().query("SELECT * FROM validation_receipts WHERE validation_id = $1", [args[0]]);
+            return result.rows[0] ?? null;
+        }
+        case "close":
+            if (pool)
+                await pool.end();
+            pool = null;
+            return null;
+        default:
+            throw new Error(`Unknown PostgresJobStore worker method: ${method}`);
+    }
+}
+parentPort?.on("message", async (message) => {
+    const { method, args, resultPath, shared } = message;
+    let payload;
+    try {
+        payload = ok(await op(method, args));
+    }
+    catch (error) {
+        payload = fail(error);
+    }
+    try {
+        writeFileSync(resultPath, JSON.stringify(payload));
+        signal(shared, 1);
+    }
+    catch {
+        signal(shared, 2);
+    }
+});

package/dist/pricing.d.ts

@@ -1,8 +1,9 @@
+import type { CliType } from "./provider-types.js";
 export interface PricePerMillion {
     inputUsd: number;
     outputUsd: number;
     cacheReadMultiplier: number;
 }
 export declare const PRICING_AS_OF = "2026-06-13";
-export declare function getPricing(cli: "claude" | "codex" | "gemini" | "grok" | "mistral", model: string): PricePerMillion;
-export declare function estimateCacheSavingsUsd(cli: "claude" | "codex" | "gemini" | "grok" | "mistral", model: string, cacheReadTokens: number): number;
+export declare function getPricing(cli: CliType, model: string): PricePerMillion;
+export declare function estimateCacheSavingsUsd(cli: CliType, model: string, cacheReadTokens: number): number;

package/dist/provider-acp-capabilities.d.ts

@@ -0,0 +1,52 @@
+import type { AcpConfig } from "./config.js";
+import type { ParsedAcpInitialize } from "./provider-capability-discovery.js";
+import type { CliType } from "./session-manager.js";
+export interface AcpHostServicePolicy {
+    readonly filesystemRead: "deny-by-default";
+    readonly filesystemWriteAllowed: boolean;
+    readonly terminalAllowed: boolean;
+    readonly mutatingSessionOpsAllowed: boolean;
+    readonly permissionRouting: "approval-manager";
+    readonly unknownToolKind: "deny-by-default";
+}
+export interface ProviderAcpInitializeDetail {
+    readonly source: "discovered" | "static-fallback";
+    readonly degraded: boolean;
+    readonly protocolVersion: number | string | null;
+    readonly agentInfo: {
+        readonly name?: string;
+        readonly version?: string;
+    } | null;
+    readonly authMethods: readonly string[];
+    readonly promptCapabilities: readonly string[];
+    readonly mcpCapabilities: readonly string[];
+    readonly sessionCapabilities: readonly string[];
+    readonly extensionMethods: readonly string[];
+}
+export interface ProviderAcpCapabilityRecord {
+    readonly schemaVersion: "provider-acp-capability.v1";
+    readonly provider: CliType;
+    readonly displayName: string;
+    readonly native: boolean;
+    readonly nativeEntrypoint: string | null;
+    readonly entrypoint: {
+        readonly command: string;
+        readonly args: readonly string[];
+    } | null;
+    readonly probeArgv: readonly (readonly string[])[];
+    readonly agentTypes: readonly {
+        readonly id: string;
+        readonly description: string;
+    }[];
+    readonly evidence: string;
+    readonly initialize: ProviderAcpInitializeDetail | null;
+    readonly supportedSessionMethods: readonly string[];
+    readonly hostServicePolicy: AcpHostServicePolicy;
+}
+export declare function deriveSupportedMethodsFromDiscovered(parsed: ParsedAcpInitialize): readonly string[];
+export interface BuildProviderAcpRecordOptions {
+    readonly discovered?: ParsedAcpInitialize | null;
+    readonly discoveredDegraded?: boolean;
+    readonly acpConfig?: AcpConfig | null;
+}
+export declare function buildProviderAcpCapabilityRecord(provider: CliType, options?: BuildProviderAcpRecordOptions): ProviderAcpCapabilityRecord;

package/dist/provider-acp-capabilities.js

@@ -0,0 +1,101 @@
+import { redactAcpMessage } from "./acp/errors.js";
+import { BASELINE_ACP_METHODS, deriveAcpMethodAvailability, } from "./acp/types.js";
+import { getProviderDefinition } from "./provider-definitions.js";
+export function deriveSupportedMethodsFromDiscovered(parsed) {
+    const init = {
+        protocolVersion: typeof parsed.protocolVersion === "number" ? parsed.protocolVersion : 0,
+        agentCapabilities: parsed.agentCapabilities ?? undefined,
+        authMethods: parsed.authMethods.map(id => ({ id })),
+    };
+    const methods = new Set(deriveAcpMethodAvailability(init));
+    for (const method of parsed.knownMethods) {
+        methods.add(method);
+    }
+    return [...methods].sort();
+}
+function hostServicePolicy(config) {
+    return {
+        filesystemRead: "deny-by-default",
+        filesystemWriteAllowed: config?.allowWriteHostServices ?? false,
+        terminalAllowed: config?.allowTerminalHostServices ?? false,
+        mutatingSessionOpsAllowed: config?.allowMutatingSessionOps ?? false,
+        permissionRouting: "approval-manager",
+        unknownToolKind: "deny-by-default",
+    };
+}
+export function buildProviderAcpCapabilityRecord(provider, options = {}) {
+    const def = getProviderDefinition(provider);
+    const acp = def.acp;
+    const native = acp.classification === "native";
+    const policy = hostServicePolicy(options.acpConfig);
+    if (!native) {
+        return {
+            schemaVersion: "provider-acp-capability.v1",
+            provider,
+            displayName: def.displayName,
+            native: false,
+            nativeEntrypoint: null,
+            entrypoint: null,
+            probeArgv: [],
+            agentTypes: [],
+            evidence: acp.evidence,
+            initialize: null,
+            supportedSessionMethods: [],
+            hostServicePolicy: policy,
+        };
+    }
+    const discovered = options.discovered ?? null;
+    const initialize = discovered
+        ? {
+            source: "discovered",
+            degraded: options.discoveredDegraded ?? false,
+            protocolVersion: discovered.protocolVersion,
+            agentInfo: discovered.agentInfo
+                ? {
+                    ...(discovered.agentInfo.name !== undefined
+                        ? { name: redactAcpMessage(discovered.agentInfo.name) }
+                        : {}),
+                    ...(discovered.agentInfo.version !== undefined
+                        ? { version: redactAcpMessage(discovered.agentInfo.version) }
+                        : {}),
+                }
+                : null,
+            authMethods: discovered.authMethods,
+            promptCapabilities: discovered.promptCapabilities,
+            mcpCapabilities: discovered.mcpCapabilities,
+            sessionCapabilities: discovered.sessionCapabilities,
+            extensionMethods: discovered.extensionMethods,
+        }
+        : {
+            source: "static-fallback",
+            degraded: false,
+            protocolVersion: null,
+            agentInfo: null,
+            authMethods: [],
+            promptCapabilities: [],
+            mcpCapabilities: [],
+            sessionCapabilities: [],
+            extensionMethods: [],
+        };
+    const supportedSessionMethods = discovered
+        ? deriveSupportedMethodsFromDiscovered(discovered)
+        : [...BASELINE_ACP_METHODS].sort();
+    return {
+        schemaVersion: "provider-acp-capability.v1",
+        provider,
+        displayName: def.displayName,
+        native: true,
+        nativeEntrypoint: acp.nativeEntrypoint,
+        entrypoint: acp.entrypoint
+            ? { command: acp.entrypoint.command, args: [...acp.entrypoint.args] }
+            : null,
+        probeArgv: acp.probeArgv.map(argv => [...argv]),
+        agentTypes: acp.agentTypes
+            ? acp.agentTypes.map(t => ({ id: t.id, description: t.description }))
+            : [],
+        evidence: acp.evidence,
+        initialize,
+        supportedSessionMethods,
+        hostServicePolicy: policy,
+    };
+}

package/dist/provider-admin-tools.d.ts

@@ -0,0 +1,100 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ExecuteResult } from "./executor.js";
+import { type Logger } from "./logger.js";
+import { type CliType, type ProviderAdminFamily, type ProviderDefinition } from "./provider-definitions.js";
+import type { DiscoveredCapabilitySet } from "./provider-capability-discovery.js";
+import { type CliSubcommandExposure, type CliSubcommandRisk } from "./upstream-contracts.js";
+import type { ApprovalManager } from "./approval-manager.js";
+import { type GatewayRequestContext } from "./request-context.js";
+export declare function adminRiskToExposure(risk: CliSubcommandRisk): CliSubcommandExposure;
+export declare function classifyOperationRisk(operationName: string, familyRisk: CliSubcommandRisk, opts?: {
+    isSubcommand?: boolean;
+}): CliSubcommandRisk;
+export declare function familyBaseRisk(provider: CliType, fam: ProviderAdminFamily): CliSubcommandRisk;
+export type AdminDiscoverySource = "subcommand-help" | "root-help" | "not-advertised" | "no-discovery";
+export interface AdminOperation {
+    readonly provider: CliType;
+    readonly family: string;
+    readonly operationId: string;
+    readonly argv: readonly string[];
+    readonly risk: CliSubcommandRisk;
+    readonly exposure: CliSubcommandExposure;
+    readonly mutating: boolean;
+    readonly available: boolean;
+    readonly discoverySource: AdminDiscoverySource;
+    readonly summary: string;
+}
+export declare function projectProviderAdminOperations(def: ProviderDefinition, discovered: DiscoveredCapabilitySet | null): AdminOperation[];
+export interface AdminCatalogRow {
+    readonly provider: CliType;
+    readonly operationId: string;
+    readonly family: string;
+    readonly argv: readonly string[];
+    readonly risk: CliSubcommandRisk;
+    readonly exposure: CliSubcommandExposure;
+    readonly mutating: boolean;
+    readonly available: boolean;
+    readonly discoverySource: AdminDiscoverySource;
+    readonly summary: string;
+}
+export declare function buildProviderAdminCatalog(options?: {
+    provider?: CliType;
+    lookup?: (id: CliType) => DiscoveredCapabilitySet | null;
+    includeUnavailable?: boolean;
+}): AdminCatalogRow[];
+export declare function redactAdminOutput(text: string): string;
+export type AdminCommandRunner = (executable: string, argv: readonly string[], options: {
+    timeoutMs?: number;
+}) => Promise<ExecuteResult>;
+export declare function isSafeAdminToken(token: string): boolean;
+export interface AdminRunResult {
+    readonly ok: boolean;
+    readonly provider: CliType;
+    readonly operationId: string;
+    readonly argv: readonly string[];
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly redacted: true;
+    readonly error?: string;
+}
+export declare function runReadOnlyAdminOperation(op: AdminOperation, deps?: {
+    runner?: AdminCommandRunner;
+    timeoutMs?: number;
+    logger?: Logger;
+}): Promise<AdminRunResult>;
+export interface AdminAuditRecord {
+    readonly ts: string;
+    readonly provider: CliType;
+    readonly operationId: string;
+    readonly argv: readonly string[];
+    readonly outcome: "gate_closed" | "denied" | "approved" | "executed";
+    readonly approvalId?: string;
+    readonly exitCode?: number | null;
+    readonly principal?: string;
+}
+export declare function defaultAdminAuditPath(): string;
+export type AdminAuditSink = (record: AdminAuditRecord) => void;
+export declare function defaultAdminAuditSink(auditPath?: string): AdminAuditSink;
+export declare function appendAdminAudit(record: AdminAuditRecord, auditPath?: string): void;
+export interface AdminMutateContext {
+    readonly allowMutating: boolean;
+    readonly remoteCaller?: boolean;
+    readonly remoteAdminAllowed?: boolean;
+    readonly approvalManager: ApprovalManager;
+    readonly runner?: AdminCommandRunner;
+    readonly timeoutMs?: number;
+    readonly logger?: Logger;
+    readonly principal?: string;
+    readonly auditPath?: string;
+    readonly auditSink?: AdminAuditSink;
+}
+export declare function runMutatingAdminOperation(op: AdminOperation, ctx: AdminMutateContext): Promise<AdminRunResult>;
+export declare function isRemoteAdminCaller(ctx: GatewayRequestContext | undefined): boolean;
+export declare function remoteCliAdminEnabled(ctx: GatewayRequestContext | undefined): boolean;
+export interface ProviderAdminToolRuntime {
+    readonly approvalManager: ApprovalManager;
+    readonly logger: Logger;
+    readonly allowMutatingCliAdminOps: boolean;
+}
+export declare function registerProviderAdminTools(server: McpServer, runtime: ProviderAdminToolRuntime): void;