llm-cli-gateway 2.6.3 → 2.8.0

package/dist/acp/errors.js

@@ -0,0 +1,139 @@
+export function redactAcpMessage(input) {
+    let out = input;
+    out = out.replace(/\{[\s\S]*?\}/g, "<redacted-json>");
+    out = out.replace(/\[[\s\S]*?\]/g, "<redacted-json>");
+    out = out.replace(/\b(bearer|token|api[_-]?key|secret)\b\s*[:=]?\s*\S+/gi, "$1 <redacted>");
+    out = out.replace(/\b(sk|xai|gsk|key)-[A-Za-z0-9_-]{8,}\b/gi, "<redacted-token>");
+    out = out.replace(/(^|[^A-Za-z0-9._~\\/-])[A-Za-z]:\\[^\s"')\]}>]*/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~\\/-])\\\\[^\s"')\]}>]+/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~/-])~\/[^\s"')\]}>]+/g, "$1<redacted-path>");
+    out = out.replace(/(^|[^A-Za-z0-9._~/-])\/[A-Za-z0-9._/-]{2,}/g, "$1<redacted-path>");
+    out = out.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "<redacted-email>");
+    return out;
+}
+export function redactAcpDebug(value) {
+    const sensitiveKey = /(payload|body|prompt|content|token|secret|api[_-]?key|credential|auth|cwd|path)/i;
+    if (typeof value === "string") {
+        return redactAcpMessage(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => redactAcpDebug(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            if (sensitiveKey.test(key)) {
+                out[key] = "<redacted>";
+                continue;
+            }
+            out[key] = redactAcpDebug(inner);
+        }
+        return out;
+    }
+    return value;
+}
+export function redactAcpCause(cause) {
+    if (cause instanceof Error) {
+        const redacted = new Error(redactAcpMessage(cause.message));
+        redacted.name = redactAcpMessage(cause.name);
+        if (typeof cause.stack === "string") {
+            redacted.stack = redactAcpMessage(cause.stack);
+        }
+        return redacted;
+    }
+    return redactAcpDebug(cause);
+}
+export class AcpError extends Error {
+    kind;
+    provider;
+    debug;
+    constructor(kind, userMessage, options) {
+        super(redactAcpMessage(userMessage));
+        this.name = "AcpError";
+        this.kind = kind;
+        this.provider = options?.provider;
+        this.debug = redactAcpDebug(options?.debug ?? {}) ?? {};
+        if (options?.cause !== undefined) {
+            this.cause = redactAcpCause(options.cause);
+        }
+    }
+    get userMessage() {
+        return this.message;
+    }
+}
+export class AcpDisabledError extends AcpError {
+    constructor(debug) {
+        super("acp_disabled", "ACP transport is disabled. Enable [acp] in the gateway config to use transport=acp, or omit transport to use the default CLI path.", { debug });
+        this.name = "AcpDisabledError";
+    }
+}
+export class ProviderAcpDisabledError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_acp_disabled", `ACP is disabled for provider ${provider}. Enable it under [acp.providers.${provider}] or omit transport to use the default CLI path.`, { provider, debug });
+        this.name = "ProviderAcpDisabledError";
+    }
+}
+export class ProviderAcpUnsupportedError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_acp_unsupported", `Provider ${provider} has no native ACP support at its target version. Use the default CLI transport for this provider.`, { provider, debug });
+        this.name = "ProviderAcpUnsupportedError";
+    }
+}
+export class ProviderRuntimeDisabledError extends AcpError {
+    constructor(provider, debug) {
+        super("provider_runtime_disabled", `ACP runtime routing is not enabled for provider ${provider}. Set runtime_enabled=true under [acp.providers.${provider}] to allow prompt routing.`, { provider, debug });
+        this.name = "ProviderRuntimeDisabledError";
+    }
+}
+export class ProviderUnavailableError extends AcpError {
+    constructor(provider, reason, debug) {
+        super("provider_unavailable", `Provider ${provider} ACP entrypoint is unavailable: ${reason}`, {
+            provider,
+            debug,
+        });
+        this.name = "ProviderUnavailableError";
+    }
+}
+export class AcpProtocolError extends AcpError {
+    code;
+    constructor(userMessage, options) {
+        super("protocol", userMessage, { provider: options?.provider, debug: options?.debug });
+        this.name = "AcpProtocolError";
+        this.code = options?.code;
+    }
+}
+export class AcpTimeoutError extends AcpError {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs, options) {
+        super("timeout", `ACP request ${method} timed out after ${timeoutMs}ms.`, {
+            provider: options?.provider,
+            debug: options?.debug,
+        });
+        this.name = "AcpTimeoutError";
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class AcpPermissionDeniedError extends AcpError {
+    constructor(provider, reason, debug) {
+        super("permission_denied", `ACP permission request was denied: ${reason}`, { provider, debug });
+        this.name = "AcpPermissionDeniedError";
+    }
+}
+export class AcpProcessExitError extends AcpError {
+    exitCode;
+    signal;
+    constructor(provider, options) {
+        super("process_exit", `Provider ${provider} ACP process exited before the request completed.`, {
+            provider,
+            debug: options?.debug,
+        });
+        this.name = "AcpProcessExitError";
+        this.exitCode = options?.exitCode ?? null;
+        this.signal = options?.signal ?? null;
+    }
+}
+export function isAcpError(value) {
+    return value instanceof AcpError;
+}

package/dist/acp/json-rpc-stdio.d.ts

@@ -0,0 +1,71 @@
+import type { Readable, Writable } from "node:stream";
+import type { Logger } from "../logger.js";
+import type { CliType } from "../session-manager.js";
+export type JsonRpcId = number | string;
+export interface JsonRpcErrorObject {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: unknown;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface JsonRpcInboundRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params?: unknown;
+}
+export interface ProviderStdioStreams {
+    readonly stdin: Writable;
+    readonly stdout: Readable;
+    readonly stderr?: Readable | null;
+}
+export interface JsonRpcStdioTransportOptions {
+    readonly streams: ProviderStdioStreams;
+    readonly logger?: Logger;
+    readonly provider?: CliType;
+    readonly defaultTimeoutMs?: number;
+    readonly onNotification?: (notification: JsonRpcNotification) => void;
+    readonly onRequest?: (request: JsonRpcInboundRequest) => void;
+    readonly onActivity?: () => void;
+    readonly onClose?: () => void;
+}
+export declare class JsonRpcStdioTransport {
+    private readonly streams;
+    private readonly logger;
+    private readonly provider?;
+    private readonly defaultTimeoutMs;
+    private readonly onNotification?;
+    private readonly onRequest?;
+    private readonly onActivity?;
+    private readonly onClose?;
+    private readonly pending;
+    private nextId;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private closed;
+    private exitError;
+    constructor(options: JsonRpcStdioTransportOptions);
+    private attach;
+    private onStdoutData;
+    private onStderrData;
+    private handleLine;
+    private dispatchNotification;
+    private dispatchInboundRequest;
+    private resolveResponse;
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+    notify(method: string, params?: unknown): void;
+    respond(id: JsonRpcId, result: unknown): void;
+    respondError(id: JsonRpcId, error: JsonRpcErrorObject): void;
+    handleProcessExit(exitCode: number | null, signal: string | null): void;
+    private handleStreamClose;
+    private emitActivity;
+    private emitClose;
+    private failPending;
+    dispose(): void;
+    get pendingCount(): number;
+    get isClosed(): boolean;
+}

package/dist/acp/json-rpc-stdio.js

@@ -0,0 +1,375 @@
+import { AcpProcessExitError, AcpProtocolError, AcpTimeoutError, redactAcpMessage, } from "./errors.js";
+import { noopLogger } from "../logger.js";
+function isJsonRpcId(value) {
+    return typeof value === "number" || typeof value === "string";
+}
+function isJsonRpcErrorObject(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.code === "number" &&
+        typeof value.message === "string");
+}
+export class JsonRpcStdioTransport {
+    streams;
+    logger;
+    provider;
+    defaultTimeoutMs;
+    onNotification;
+    onRequest;
+    onActivity;
+    onClose;
+    pending = new Map();
+    nextId = 1;
+    stdoutBuffer = "";
+    stderrBuffer = "";
+    closed = false;
+    exitError = null;
+    constructor(options) {
+        this.streams = options.streams;
+        this.logger = options.logger ?? noopLogger;
+        this.provider = options.provider;
+        this.defaultTimeoutMs = options.defaultTimeoutMs ?? 0;
+        this.onNotification = options.onNotification;
+        this.onRequest = options.onRequest;
+        this.onActivity = options.onActivity;
+        this.onClose = options.onClose;
+        this.attach();
+    }
+    attach() {
+        const { stdout, stderr } = this.streams;
+        stdout.setEncoding("utf8");
+        stdout.on("data", (chunk) => this.onStdoutData(chunk));
+        stdout.on("error", (err) => {
+            this.logger.error("acp.transport.stdout.error", {
+                provider: this.provider,
+                errorClass: err.name,
+            });
+            this.handleStreamClose();
+        });
+        stdout.on("close", () => this.handleStreamClose());
+        stdout.on("end", () => this.handleStreamClose());
+        if (stderr) {
+            stderr.setEncoding("utf8");
+            stderr.on("data", (chunk) => this.onStderrData(chunk));
+            stderr.on("error", (err) => {
+                this.logger.error("acp.transport.stderr.error", {
+                    provider: this.provider,
+                    errorClass: err.name,
+                });
+            });
+        }
+    }
+    onStdoutData(chunk) {
+        this.stdoutBuffer += chunk;
+        let newlineIndex = this.stdoutBuffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.stdoutBuffer.slice(0, newlineIndex);
+            this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+            this.handleLine(line);
+            newlineIndex = this.stdoutBuffer.indexOf("\n");
+        }
+    }
+    onStderrData(chunk) {
+        this.stderrBuffer += chunk;
+        let newlineIndex = this.stderrBuffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.stderrBuffer.slice(0, newlineIndex).replace(/\r$/, "");
+            this.stderrBuffer = this.stderrBuffer.slice(newlineIndex + 1);
+            if (line.length > 0) {
+                const redacted = redactAcpMessage(line) !== line;
+                this.logger.debug("acp.provider.stderr", {
+                    provider: this.provider,
+                    bytes: Buffer.byteLength(line, "utf8"),
+                    redacted,
+                });
+            }
+            newlineIndex = this.stderrBuffer.indexOf("\n");
+        }
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            this.logger.error("acp.transport.invalid_json", {
+                provider: this.provider,
+                errorClass: "SyntaxError",
+                bytes: trimmed.length,
+            });
+            return;
+        }
+        if (parsed === null || typeof parsed !== "object") {
+            this.logger.error("acp.transport.invalid_message", { provider: this.provider });
+            return;
+        }
+        const hasId = isJsonRpcId(parsed.id);
+        const hasMethod = typeof parsed.method === "string";
+        if (hasMethod || hasId) {
+            this.emitActivity();
+        }
+        if (hasMethod && hasId) {
+            this.dispatchInboundRequest(parsed);
+            return;
+        }
+        if (hasMethod && !hasId) {
+            this.dispatchNotification(parsed.method, parsed.params);
+            return;
+        }
+        if (hasId) {
+            this.resolveResponse(parsed.id, parsed);
+            return;
+        }
+        this.logger.error("acp.transport.unroutable_message", { provider: this.provider });
+    }
+    dispatchNotification(method, params) {
+        const notification = { jsonrpc: "2.0", method, params };
+        try {
+            this.onNotification?.(notification);
+        }
+        catch (err) {
+            this.logger.error("acp.transport.notification_handler_error", {
+                provider: this.provider,
+                method,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    dispatchInboundRequest(parsed) {
+        const request = {
+            jsonrpc: "2.0",
+            id: parsed.id,
+            method: parsed.method,
+            params: parsed.params,
+        };
+        try {
+            this.onRequest?.(request);
+        }
+        catch (err) {
+            this.logger.error("acp.transport.request_handler_error", {
+                provider: this.provider,
+                method: request.method,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    resolveResponse(id, parsed) {
+        const pending = this.pending.get(id);
+        if (!pending) {
+            this.logger.debug("acp.transport.orphan_response", { provider: this.provider });
+            return;
+        }
+        this.pending.delete(id);
+        if (pending.timer) {
+            clearTimeout(pending.timer);
+        }
+        if (parsed.error !== undefined && parsed.error !== null) {
+            if (isJsonRpcErrorObject(parsed.error)) {
+                pending.reject(new AcpProtocolError(`ACP request ${pending.method} failed with JSON-RPC error ${parsed.error.code}.`, {
+                    provider: this.provider,
+                    code: parsed.error.code,
+                    debug: {
+                        method: pending.method,
+                        code: parsed.error.code,
+                        providerMessage: parsed.error.message,
+                    },
+                }));
+                return;
+            }
+            pending.reject(new AcpProtocolError(`ACP request ${pending.method} returned a malformed error object.`, {
+                provider: this.provider,
+                debug: { method: pending.method },
+            }));
+            return;
+        }
+        pending.resolve(parsed.result);
+    }
+    request(method, params, timeoutMs) {
+        if (this.exitError) {
+            return Promise.reject(this.exitError);
+        }
+        if (this.closed) {
+            return Promise.reject(new AcpProcessExitError(this.provider ?? "unknown", {
+                debug: { method, reason: "transport_closed" },
+            }));
+        }
+        const id = this.nextId++;
+        const effectiveTimeout = timeoutMs ?? this.defaultTimeoutMs;
+        this.emitActivity();
+        return new Promise((resolve, reject) => {
+            const pending = { method, resolve, reject, timer: null };
+            if (effectiveTimeout > 0) {
+                pending.timer = setTimeout(() => {
+                    if (this.pending.get(id) === pending) {
+                        this.pending.delete(id);
+                        this.logger.error("acp.transport.timeout", {
+                            provider: this.provider,
+                            method,
+                            timeoutMs: effectiveTimeout,
+                        });
+                        reject(new AcpTimeoutError(method, effectiveTimeout, {
+                            provider: this.provider,
+                            debug: { method },
+                        }));
+                    }
+                }, effectiveTimeout);
+                pending.timer.unref?.();
+            }
+            this.pending.set(id, pending);
+            const frame = JSON.stringify({
+                jsonrpc: "2.0",
+                id,
+                method,
+                ...(params !== undefined ? { params } : {}),
+            }) + "\n";
+            try {
+                this.streams.stdin.write(frame);
+            }
+            catch (err) {
+                this.pending.delete(id);
+                if (pending.timer) {
+                    clearTimeout(pending.timer);
+                }
+                reject(new AcpProcessExitError(this.provider ?? "unknown", {
+                    debug: {
+                        method,
+                        reason: "stdin_write_failed",
+                        errorClass: err instanceof Error ? err.name : "unknown",
+                    },
+                }));
+            }
+        });
+    }
+    notify(method, params) {
+        if (this.exitError || this.closed) {
+            return;
+        }
+        const frame = JSON.stringify({ jsonrpc: "2.0", method, ...(params !== undefined ? { params } : {}) }) +
+            "\n";
+        try {
+            this.streams.stdin.write(frame);
+        }
+        catch (err) {
+            this.logger.error("acp.transport.notify_write_failed", {
+                provider: this.provider,
+                method,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    respond(id, result) {
+        if (this.exitError || this.closed) {
+            return;
+        }
+        const frame = JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n";
+        try {
+            this.streams.stdin.write(frame);
+        }
+        catch (err) {
+            this.logger.error("acp.transport.respond_write_failed", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    respondError(id, error) {
+        if (this.exitError || this.closed) {
+            return;
+        }
+        const frame = JSON.stringify({
+            jsonrpc: "2.0",
+            id,
+            error: {
+                code: error.code,
+                message: error.message,
+                ...(error.data !== undefined ? { data: error.data } : {}),
+            },
+        }) + "\n";
+        try {
+            this.streams.stdin.write(frame);
+        }
+        catch (err) {
+            this.logger.error("acp.transport.respond_error_write_failed", {
+                provider: this.provider,
+                errorClass: err instanceof Error ? err.name : "unknown",
+            });
+        }
+    }
+    handleProcessExit(exitCode, signal) {
+        if (this.exitError) {
+            return;
+        }
+        this.exitError = new AcpProcessExitError(this.provider ?? "unknown", {
+            exitCode,
+            signal,
+            debug: { exitCode, signal },
+        });
+        this.logger.error("acp.process.exit", {
+            provider: this.provider,
+            exitCode,
+            signal,
+            pending: this.pending.size,
+        });
+        this.failPending(this.exitError);
+        this.closed = true;
+    }
+    handleStreamClose() {
+        if (this.exitError || this.closed) {
+            return;
+        }
+        this.exitError = new AcpProcessExitError(this.provider ?? "unknown", {
+            debug: { reason: "stdout_closed" },
+        });
+        this.logger.error("acp.transport.stdout_closed", {
+            provider: this.provider,
+            pending: this.pending.size,
+        });
+        this.failPending(this.exitError);
+        this.closed = true;
+        this.emitClose();
+    }
+    emitActivity() {
+        try {
+            this.onActivity?.();
+        }
+        catch {
+        }
+    }
+    emitClose() {
+        try {
+            this.onClose?.();
+        }
+        catch {
+        }
+    }
+    failPending(error) {
+        for (const [id, pending] of this.pending) {
+            if (pending.timer) {
+                clearTimeout(pending.timer);
+            }
+            this.pending.delete(id);
+            pending.reject(error);
+        }
+    }
+    dispose() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        const error = this.exitError ??
+            new AcpProcessExitError(this.provider ?? "unknown", {
+                debug: { reason: "disposed" },
+            });
+        this.failPending(error);
+    }
+    get pendingCount() {
+        return this.pending.size;
+    }
+    get isClosed() {
+        return this.closed;
+    }
+}

package/dist/acp/process-manager.d.ts

@@ -0,0 +1,66 @@
+import type { Readable, Writable } from "node:stream";
+import { AcpClient, type AcpClientCallbacks, type HostServices } from "./client.js";
+import { AcpError } from "./errors.js";
+import { JsonRpcStdioTransport } from "./json-rpc-stdio.js";
+import type { AcpConfig, AcpProviderConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+import type { CliType } from "../session-manager.js";
+export type ProcessEnv = Record<string, string | undefined>;
+export type TerminationSignal = "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP";
+export interface AcpChildProcess {
+    readonly pid?: number | undefined;
+    readonly stdin: Writable | null;
+    readonly stdout: Readable | null;
+    readonly stderr: Readable | null;
+    on(event: "exit", listener: (code: number | null, signal: TerminationSignal | null) => void): unknown;
+    on(event: "error", listener: (err: Error) => void): unknown;
+    kill(signal?: TerminationSignal | number): boolean;
+}
+export interface ResolvedAcpSpawn {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env: ProcessEnv;
+}
+export type AcpSpawnFn = (resolved: ResolvedAcpSpawn) => AcpChildProcess;
+export type AcpProcessState = "starting" | "running" | "exited" | "quarantined";
+export interface AcpProcessManagerOptions {
+    readonly config: AcpConfig;
+    readonly logger?: Logger;
+    readonly spawn?: AcpSpawnFn;
+    readonly baseEnv?: ProcessEnv;
+}
+export interface StartProviderOptions {
+    readonly provider: CliType;
+    readonly cwd?: string;
+    readonly hostServices: HostServices;
+    readonly callbacks?: AcpClientCallbacks;
+    readonly idleTimeoutMs?: number;
+}
+export interface ManagedAcpProcess {
+    readonly provider: CliType;
+    readonly pid: number | undefined;
+    readonly transport: JsonRpcStdioTransport;
+    readonly client: AcpClient;
+    readonly state: AcpProcessState;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly terminalError: AcpError | null;
+    readonly resolved: ResolvedAcpSpawn;
+    shutdown(signal?: TerminationSignal): void;
+    isHealthy(): boolean;
+}
+export declare function buildProviderEnv(provider: CliType, providerConfig: AcpProviderConfig, baseEnv: ProcessEnv): ProcessEnv;
+export declare function resolveProviderSpawn(provider: CliType, config: AcpConfig, baseEnv: ProcessEnv, cwd?: string): ResolvedAcpSpawn;
+export declare const defaultSpawn: AcpSpawnFn;
+export declare class AcpProcessManager {
+    private readonly config;
+    private readonly logger;
+    private readonly spawnFn;
+    private readonly baseEnv;
+    private readonly live;
+    constructor(options: AcpProcessManagerOptions);
+    start(options: StartProviderOptions): Promise<ManagedAcpProcess>;
+    shutdownAll(signal?: TerminationSignal): void;
+    get liveCount(): number;
+}