llm-cli-gateway 2.6.3 → 2.8.0

package/dist/acp/types.js

@@ -0,0 +1,335 @@
+import { z } from "zod/v3";
+import { AcpProtocolError } from "./errors.js";
+export const ProtocolVersionSchema = z.number().int().nonnegative();
+export const SessionIdSchema = z.string().min(1);
+const MetaSchema = z.record(z.unknown()).optional();
+const KNOWN_CONTENT_BLOCK_TYPES = new Set(["text", "image", "audio", "resource_link", "resource"]);
+export const ContentBlockSchema = z.lazy(() => z.union([
+    z.object({ type: z.literal("text"), text: z.string(), _meta: MetaSchema }).passthrough(),
+    z
+        .object({
+        type: z.literal("image"),
+        data: z.string(),
+        mimeType: z.string(),
+        _meta: MetaSchema,
+    })
+        .passthrough(),
+    z
+        .object({
+        type: z.literal("audio"),
+        data: z.string(),
+        mimeType: z.string(),
+        _meta: MetaSchema,
+    })
+        .passthrough(),
+    z
+        .object({
+        type: z.literal("resource_link"),
+        uri: z.string(),
+        _meta: MetaSchema,
+    })
+        .passthrough(),
+    z.object({ type: z.literal("resource"), _meta: MetaSchema }).passthrough(),
+    z
+        .object({
+        type: z.string().refine(t => !KNOWN_CONTENT_BLOCK_TYPES.has(t), {
+            message: "known content block type missing required fields",
+        }),
+    })
+        .passthrough(),
+]));
+export const ClientFsCapabilitiesSchema = z
+    .object({
+    readTextFile: z.boolean().optional(),
+    writeTextFile: z.boolean().optional(),
+})
+    .passthrough();
+export const ClientCapabilitiesSchema = z
+    .object({
+    fs: ClientFsCapabilitiesSchema.optional(),
+    terminal: z.boolean().optional(),
+})
+    .passthrough();
+export const InitializeRequestSchema = z
+    .object({
+    protocolVersion: ProtocolVersionSchema,
+    clientCapabilities: ClientCapabilitiesSchema.optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const InitializeResponseSchema = z
+    .object({
+    protocolVersion: ProtocolVersionSchema,
+    agentCapabilities: z.record(z.unknown()).optional(),
+    agentInfo: z
+        .object({
+        name: z.string().optional(),
+        version: z.string().optional(),
+    })
+        .passthrough()
+        .optional(),
+    authMethods: z.array(z.record(z.unknown())).optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const McpServerSchema = z.record(z.unknown());
+export const SessionNewRequestSchema = z
+    .object({
+    cwd: z.string().min(1),
+    mcpServers: z.array(McpServerSchema).default([]),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const SessionNewResponseSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    modes: z.record(z.unknown()).optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const SessionLoadRequestSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    cwd: z.string().min(1),
+    mcpServers: z.array(McpServerSchema).default([]),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const SessionLoadResponseSchema = z
+    .object({
+    modes: z.record(z.unknown()).optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const SessionPromptRequestSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    prompt: z.array(ContentBlockSchema).min(1),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const STOP_REASONS = [
+    "end_turn",
+    "max_tokens",
+    "max_turn_requests",
+    "refusal",
+    "cancelled",
+];
+export const SessionPromptResponseSchema = z
+    .object({
+    stopReason: z.string().min(1),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const SessionCancelNotificationSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    _meta: MetaSchema,
+})
+    .passthrough();
+const MessageChunkUpdate = (variant) => z
+    .object({
+    sessionUpdate: z.literal(variant),
+    content: ContentBlockSchema,
+    messageId: z.string().nullish(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const ToolCallUpdate = z
+    .object({
+    sessionUpdate: z.literal("tool_call"),
+    toolCallId: z.string().min(1),
+    title: z.string(),
+    status: z.string().optional(),
+    kind: z.string().optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const ToolCallUpdateUpdate = z
+    .object({
+    sessionUpdate: z.literal("tool_call_update"),
+    toolCallId: z.string().min(1),
+    status: z.string().nullish(),
+    title: z.string().nullish(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const PlanUpdate = z
+    .object({
+    sessionUpdate: z.literal("plan"),
+    entries: z.array(z.record(z.unknown())),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const AvailableCommandsUpdate = z
+    .object({
+    sessionUpdate: z.literal("available_commands_update"),
+    availableCommands: z.array(z.record(z.unknown())),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const CurrentModeUpdate = z
+    .object({
+    sessionUpdate: z.literal("current_mode_update"),
+    currentModeId: z.string().min(1),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const UsageUpdate = z
+    .object({
+    sessionUpdate: z.literal("usage_update"),
+    size: z.number().int().nonnegative(),
+    used: z.number().int().nonnegative(),
+    cost: z.record(z.unknown()).nullish(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+const KNOWN_UPDATE_SCHEMAS = {
+    user_message_chunk: MessageChunkUpdate("user_message_chunk"),
+    agent_message_chunk: MessageChunkUpdate("agent_message_chunk"),
+    agent_thought_chunk: MessageChunkUpdate("agent_thought_chunk"),
+    tool_call: ToolCallUpdate,
+    tool_call_update: ToolCallUpdateUpdate,
+    plan: PlanUpdate,
+    available_commands_update: AvailableCommandsUpdate,
+    current_mode_update: CurrentModeUpdate,
+    usage_update: UsageUpdate,
+};
+export const SessionUpdateSchema = z
+    .object({ sessionUpdate: z.string().min(1) })
+    .passthrough()
+    .superRefine((value, ctx) => {
+    const known = KNOWN_UPDATE_SCHEMAS[value.sessionUpdate];
+    if (!known) {
+        return;
+    }
+    const result = known.safeParse(value);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            ctx.addIssue(issue);
+        }
+    }
+});
+export const SessionUpdateNotificationSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    update: SessionUpdateSchema,
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const KNOWN_SESSION_UPDATE_VARIANTS = [
+    "user_message_chunk",
+    "agent_message_chunk",
+    "agent_thought_chunk",
+    "tool_call",
+    "tool_call_update",
+    "plan",
+    "available_commands_update",
+    "current_mode_update",
+    "config_option_update",
+    "session_info_update",
+    "usage_update",
+];
+export function isUnknownSessionUpdate(update) {
+    return !KNOWN_SESSION_UPDATE_VARIANTS.includes(update.sessionUpdate);
+}
+export const PermissionOptionSchema = z
+    .object({
+    optionId: z.string().min(1),
+    name: z.string(),
+    kind: z.string().optional(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const RequestPermissionRequestSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    options: z.array(PermissionOptionSchema).min(1),
+    toolCall: z.record(z.unknown()),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const RequestPermissionOutcomeSchema = z.union([
+    z.object({ outcome: z.literal("cancelled") }).passthrough(),
+    z.object({ outcome: z.literal("selected"), optionId: z.string().min(1) }).passthrough(),
+]);
+export const RequestPermissionResponseSchema = z
+    .object({
+    outcome: RequestPermissionOutcomeSchema,
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const ReadTextFileRequestSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    path: z.string().min(1),
+    line: z.number().int().nonnegative().nullish(),
+    limit: z.number().int().nonnegative().nullish(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const ReadTextFileResponseSchema = z
+    .object({
+    content: z.string(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const WriteTextFileRequestSchema = z
+    .object({
+    sessionId: SessionIdSchema,
+    path: z.string().min(1),
+    content: z.string(),
+    _meta: MetaSchema,
+})
+    .passthrough();
+export const WriteTextFileResponseSchema = z.object({ _meta: MetaSchema }).passthrough();
+export function parseAcp(schema, value, context) {
+    const result = schema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const issuePaths = result.error.issues.map(issue => ({
+        path: issue.path.join("."),
+        code: issue.code,
+    }));
+    throw new AcpProtocolError(`Malformed ACP ${context.method} payload`, {
+        provider: context.provider,
+        debug: { method: context.method, issues: issuePaths },
+    });
+}
+export function parseInitializeResponse(value, provider) {
+    return parseAcp(InitializeResponseSchema, value, { method: "initialize", provider });
+}
+export function parseSessionNewResponse(value, provider) {
+    return parseAcp(SessionNewResponseSchema, value, { method: "session/new", provider });
+}
+export function parseSessionLoadResponse(value, provider) {
+    return parseAcp(SessionLoadResponseSchema, value, { method: "session/load", provider });
+}
+export function parseSessionPromptResponse(value, provider) {
+    return parseAcp(SessionPromptResponseSchema, value, { method: "session/prompt", provider });
+}
+export function parseSessionUpdateNotification(value, provider) {
+    return parseAcp(SessionUpdateNotificationSchema, value, {
+        method: "session/update",
+        provider,
+    });
+}
+export function parseRequestPermissionRequest(value, provider) {
+    return parseAcp(RequestPermissionRequestSchema, value, {
+        method: "session/request_permission",
+        provider,
+    });
+}
+export function parseReadTextFileRequest(value, provider) {
+    return parseAcp(ReadTextFileRequestSchema, value, {
+        method: "fs/read_text_file",
+        provider,
+    });
+}
+export function parseWriteTextFileRequest(value, provider) {
+    return parseAcp(WriteTextFileRequestSchema, value, {
+        method: "fs/write_text_file",
+        provider,
+    });
+}

package/dist/async-job-manager.d.ts

@@ -67,6 +67,7 @@ export declare class AsyncJobManager {
     private store;
     private flightRecorder;
     constructor(logger?: Logger, onJobComplete?: ((cli: LlmCli, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null, flightRecorder?: FlightRecorderLike);
+    private buildOrphanFlightResult;
     checkStalledJobs(now?: number): void;
     hasStore(): boolean;
     private emitMetrics;
@@ -103,6 +104,7 @@ export declare class AsyncJobManager {
         jobs: JobHealth[];
     };
     getJobOutputFormat(jobId: string): string | undefined;
+    getJobCli(jobId: string): LlmCli | undefined;
     private snapshot;
     private appendOutput;
 }

package/dist/async-job-manager.js

@@ -3,7 +3,8 @@ import { envWithExtendedPath, getExtendedPath, killProcessGroup, providerCommand
 import { noopLogger, logWarn } from "./logger.js";
 import { ProcessMonitor } from "./process-monitor.js";
 import { computeRequestKey } from "./job-store.js";
-import { NoopFlightRecorder } from "./flight-recorder.js";
+import { NoopFlightRecorder, } from "./flight-recorder.js";
+import { codexFrResponse } from "./codex-json-parser.js";
 const MAX_OUTPUT_SIZE = 50 * 1024 * 1024;
 const JOB_TTL_MS = 60 * 60 * 1000;
 const EVICTION_INTERVAL_MS = 5 * 60 * 1000;
@@ -75,17 +76,7 @@ export class AsyncJobManager {
                 }
                 for (const orphan of orphaned) {
                     try {
-                        const durationMs = Math.max(0, Date.now() - new Date(orphan.startedAt).getTime());
-                        this.flightRecorder.logComplete(orphan.correlationId, {
-                            response: orphan.stderr || orphan.stdout,
-                            durationMs,
-                            retryCount: 0,
-                            circuitBreakerState: "closed",
-                            optimizationApplied: false,
-                            exitCode: orphan.exitCode ?? 1,
-                            errorMessage: "orphaned after gateway restart",
-                            status: "failed",
-                        });
+                        this.flightRecorder.logComplete(orphan.correlationId, this.buildOrphanFlightResult(orphan));
                     }
                     catch (err) {
                         this.logger.error(`Async-path FR logComplete for orphaned job ${orphan.id} failed`, err);
@@ -105,6 +96,33 @@ export class AsyncJobManager {
             this.stallTimer.unref();
         }
     }
+    buildOrphanFlightResult(orphan) {
+        const durationMs = Math.max(0, Date.now() - new Date(orphan.startedAt).getTime());
+        const hasCapturedStdout = orphan.stdout.length > 0;
+        const hasKnownSuccessfulExit = orphan.exitCode === 0;
+        const hasCapturedResponseWithoutFailure = orphan.exitCode === null && hasCapturedStdout;
+        if (hasKnownSuccessfulExit || hasCapturedResponseWithoutFailure) {
+            return {
+                response: orphan.stdout,
+                durationMs,
+                retryCount: 0,
+                circuitBreakerState: "closed",
+                optimizationApplied: false,
+                exitCode: 0,
+                status: "completed",
+            };
+        }
+        return {
+            response: orphan.stderr || orphan.stdout,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: false,
+            exitCode: orphan.exitCode ?? 1,
+            errorMessage: "orphaned after gateway restart",
+            status: "failed",
+        };
+    }
     checkStalledJobs(now = Date.now()) {
         for (const job of this.jobs.values()) {
             if (job.status !== "running")
@@ -218,10 +236,11 @@ export class AsyncJobManager {
             }
         }
     }
-    buildRequestKey(cli, args, env, stdin, cwd) {
+    buildRequestKey(cli, args, env, stdin, cwd, outputFormat) {
         const extraEnv = canonicaliseEnvForKey(env);
         const withStdin = stdin === undefined ? extraEnv : `${extraEnv}|stdin:${stdin}`;
-        const extra = cwd === undefined ? withStdin : `${withStdin}|cwd:${cwd}`;
+        const withCwd = cwd === undefined ? withStdin : `${withStdin}|cwd:${cwd}`;
+        const extra = cli === "codex" ? `${withCwd}|fmt:${outputFormat ?? "text"}` : withCwd;
         return computeRequestKey(cli, args, extra);
     }
     fireOnComplete(job) {
@@ -247,7 +266,14 @@ export class AsyncJobManager {
         const durationMs = Math.max(0, Date.now() - new Date(job.startedAt).getTime());
         const usage = finalStatus === "completed" && job.extractUsage ? this.safeExtractUsage(job) : {};
         const isFailure = finalStatus === "failed";
-        const response = isFailure ? job.stderr || job.stdout : job.stdout;
+        let response;
+        if (job.cli === "codex") {
+            const codexText = codexFrResponse(job.outputFormat, job.stdout);
+            response = isFailure ? job.stderr || codexText : codexText;
+        }
+        else {
+            response = isFailure ? job.stderr || job.stdout : job.stdout;
+        }
         const exitCode = job.exitCode ?? (finalStatus === "completed" ? 0 : 1);
         const errorMessage = isFailure
             ? (overrideErrorMessage ?? job.error ?? job.stderr ?? `Exit code ${exitCode}`)
@@ -402,7 +428,7 @@ export class AsyncJobManager {
     }
     startJobWithDedup(cli, args, correlationId, opts = {}) {
         const { cwd, idleTimeoutMs, outputFormat, forceRefresh, env: extraEnv, stdin, onComplete, flightRecorderEntry, extractUsage, writeFlightStart, } = opts;
-        const requestKey = this.buildRequestKey(cli, args, extraEnv, stdin, cwd);
+        const requestKey = this.buildRequestKey(cli, args, extraEnv, stdin, cwd, outputFormat);
         if (!forceRefresh && this.store) {
             try {
                 const existing = this.store.findByRequestKey(requestKey);
@@ -713,6 +739,9 @@ export class AsyncJobManager {
     getJobOutputFormat(jobId) {
         return this.jobs.get(jobId)?.outputFormat;
     }
+    getJobCli(jobId) {
+        return this.jobs.get(jobId)?.cli;
+    }
     snapshot(job) {
         return {
             id: job.id,

package/dist/cache-stats.js

@@ -5,6 +5,11 @@ function safeNum(n) {
 function isCacheStatsCli(s) {
     return s === "claude" || s === "codex" || s === "gemini" || s === "grok" || s === "mistral";
 }
+function normalizeCacheStatsCli(s) {
+    if (s === "grok-api")
+        return "grok";
+    return isCacheStatsCli(s) ? s : null;
+}
 export function computeSessionCacheStats(db, sessionId) {
     const rows = db.queryRequests(`SELECT cli, model,
             COALESCE(cache_read_tokens, 0) AS cache_read_tokens,
@@ -34,10 +39,11 @@ export function computeSessionCacheStats(db, sessionId) {
             prefixSet.add(row.stable_prefix_hash);
         if (!lastAt || row.datetime_utc > lastAt)
             lastAt = row.datetime_utc;
-        if (cli === null && isCacheStatsCli(row.cli))
-            cli = row.cli;
-        if (isCacheStatsCli(row.cli)) {
-            estimatedSavingsUsd += estimateCacheSavingsUsd(row.cli, row.model, reads);
+        const rowCli = normalizeCacheStatsCli(row.cli);
+        if (cli === null && rowCli !== null)
+            cli = rowCli;
+        if (rowCli !== null) {
+            estimatedSavingsUsd += estimateCacheSavingsUsd(rowCli, row.model, reads);
         }
     }
     const requestCount = rows.length;
@@ -102,15 +108,16 @@ export function computePrefixCacheStats(db, stablePrefixHash) {
         if (!firstAt)
             firstAt = row.datetime_utc;
         lastAt = row.datetime_utc;
-        if (isCacheStatsCli(row.cli)) {
-            estimatedSavingsUsd += estimateCacheSavingsUsd(row.cli, row.model, reads);
-            const key = `${row.cli}::${row.model}`;
+        const rowCli = normalizeCacheStatsCli(row.cli);
+        if (rowCli !== null) {
+            estimatedSavingsUsd += estimateCacheSavingsUsd(rowCli, row.model, reads);
+            const key = `${rowCli}::${row.model}`;
             const entry = cliMap.get(key);
             if (entry) {
                 entry.count += 1;
             }
             else {
-                cliMap.set(key, { cli: row.cli, model: row.model, count: 1 });
+                cliMap.set(key, { cli: rowCli, model: row.model, count: 1 });
             }
         }
     }
@@ -180,9 +187,9 @@ export function computeGlobalCacheStats(db, opts = {}) {
             arr.push({ datetime_utc: row.datetime_utc, cache_creation_tokens: creation });
             perPrefix.set(row.stable_prefix_hash, arr);
         }
-        if (!isCacheStatsCli(row.cli))
+        const cli = normalizeCacheStatsCli(row.cli);
+        if (cli === null)
             continue;
-        const cli = row.cli;
         const savings = estimateCacheSavingsUsd(cli, row.model, reads);
         totalSavings += savings;
         const agg = perCliMap.get(cli) ?? {

package/dist/codex-json-parser.d.ts

@@ -10,5 +10,8 @@ export interface CodexJsonParseResult {
     error?: string;
     threadId?: string;
     finalMessage?: string;
+    sawEvent?: boolean;
 }
 export declare function parseCodexJsonStream(stdout: string): CodexJsonParseResult;
+export declare function codexDisplayText(stdout: string): string;
+export declare function codexFrResponse(outputFormat: string | undefined, stdout: string): string;

package/dist/codex-json-parser.js

@@ -13,6 +13,7 @@ export function parseCodexJsonStream(stdout) {
         if (!parsed || typeof parsed !== "object") {
             continue;
         }
+        result.sawEvent = true;
         switch (parsed.type) {
             case "thread.started":
                 if (typeof parsed.thread_id === "string") {
@@ -85,3 +86,19 @@ export function parseCodexJsonStream(stdout) {
     }
     return result;
 }
+export function codexDisplayText(stdout) {
+    const parsed = parseCodexJsonStream(stdout);
+    if (parsed.finalMessage !== undefined) {
+        return parsed.finalMessage;
+    }
+    if (parsed.error !== undefined) {
+        return parsed.error;
+    }
+    if (parsed.sawEvent) {
+        return "";
+    }
+    return stdout;
+}
+export function codexFrResponse(outputFormat, stdout) {
+    return outputFormat === "json" ? stdout : codexDisplayText(stdout);
+}

package/dist/config.d.ts

@@ -76,4 +76,34 @@ export interface ProvidersConfig {
 }
 export declare function loadProvidersConfig(logger?: Logger): ProvidersConfig;
 export declare function isXaiProviderEnabled(config: ProvidersConfig, env?: NodeJS.ProcessEnv): boolean;
+export declare const ACP_TRANSPORTS: readonly ["cli", "acp"];
+export type AcpTransport = (typeof ACP_TRANSPORTS)[number];
+export declare const DEFAULT_ACP_PROCESS_IDLE_TIMEOUT_MS = 600000;
+export declare const DEFAULT_ACP_INITIALIZE_TIMEOUT_MS = 10000;
+export declare const DEFAULT_ACP_SESSION_NEW_TIMEOUT_MS = 10000;
+export declare const DEFAULT_ACP_PROMPT_TIMEOUT_MS = 600000;
+export interface AcpProviderConfig {
+    enabled: boolean;
+    command: string;
+    args: string[];
+    runtimeEnabled: boolean;
+    isolatedLeaderSocket: boolean;
+}
+export interface AcpConfig {
+    enabled: boolean;
+    defaultTransport: AcpTransport;
+    smokeOnStartup: boolean;
+    processIdleTimeoutMs: number;
+    initializeTimeoutMs: number;
+    sessionNewTimeoutMs: number;
+    promptTimeoutMs: number;
+    allowWriteHostServices: boolean;
+    allowTerminalHostServices: boolean;
+    fallbackToCliWhenUnhealthy: boolean;
+    providers: Record<string, AcpProviderConfig>;
+    sources: {
+        configFile: string | null;
+    };
+}
+export declare function loadAcpConfig(logger?: Logger): AcpConfig;
 export declare function loadRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfig;