llm-cli-gateway 2.10.0 → 2.11.0

package/dist/acp/session-map.d.ts

@@ -0,0 +1,42 @@
+import type { CliType, ISessionManager } from "../session-manager.js";
+export declare const ACP_TRANSPORT: "acp";
+export interface AcpSessionMetadata {
+    readonly provider: CliType;
+    readonly transport: typeof ACP_TRANSPORT;
+    readonly sessionId?: string;
+    readonly protocolVersion?: number;
+    readonly agentName?: string;
+    readonly agentVersion?: string;
+    readonly cwd?: string;
+    readonly workspaceAlias?: string;
+    readonly worktreePath?: string;
+    readonly createdAt: string;
+    readonly lastSeenAt: string;
+}
+export declare function isGatewaySessionId(id: string): boolean;
+export declare function newGatewaySessionId(): string;
+export interface CreateAcpSessionParams {
+    readonly provider: CliType;
+    readonly cwd?: string;
+    readonly workspaceAlias?: string;
+    readonly worktreePath?: string;
+    readonly now?: () => string;
+}
+export declare function createAcpSession(sessionManager: ISessionManager, params: CreateAcpSessionParams): Promise<string>;
+export interface AcpSessionInfo {
+    readonly providerSessionId: string;
+    readonly protocolVersion?: number;
+    readonly agentName?: string;
+    readonly agentVersion?: string;
+    readonly now?: () => string;
+}
+export declare function recordAcpSessionInfo(sessionManager: ISessionManager, gatewaySessionId: string, info: AcpSessionInfo): Promise<boolean>;
+export type AcpResumeResult = {
+    readonly ok: true;
+    readonly providerSessionId: string;
+    readonly metadata: AcpSessionMetadata;
+} | {
+    readonly ok: false;
+    readonly reason: "not_found" | "wrong_provider" | "wrong_transport" | "no_provider_session";
+};
+export declare function resolveAcpResume(sessionManager: ISessionManager, gatewaySessionId: string, provider: CliType): Promise<AcpResumeResult>;

package/dist/acp/session-map.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { GATEWAY_SESSION_PREFIX } from "../request-helpers.js";
+export const ACP_TRANSPORT = "acp";
+export function isGatewaySessionId(id) {
+    return id.startsWith(GATEWAY_SESSION_PREFIX);
+}
+export function newGatewaySessionId() {
+    return `${GATEWAY_SESSION_PREFIX}${randomUUID()}`;
+}
+export async function createAcpSession(sessionManager, params) {
+    const now = (params.now ?? (() => new Date().toISOString()))();
+    const gatewaySessionId = newGatewaySessionId();
+    const metadata = {
+        provider: params.provider,
+        transport: ACP_TRANSPORT,
+        cwd: params.cwd,
+        workspaceAlias: params.workspaceAlias,
+        worktreePath: params.worktreePath,
+        createdAt: now,
+        lastSeenAt: now,
+    };
+    await sessionManager.createSession(params.provider, `${params.provider} ACP Session`, gatewaySessionId);
+    const stamped = await sessionManager.updateSessionMetadata(gatewaySessionId, { acp: metadata });
+    if (!stamped) {
+        throw new Error("failed to stamp ACP metadata on the new gateway session");
+    }
+    return gatewaySessionId;
+}
+export async function recordAcpSessionInfo(sessionManager, gatewaySessionId, info) {
+    const existing = await readAcpMetadata(sessionManager, gatewaySessionId);
+    if (!existing)
+        return false;
+    const now = (info.now ?? (() => new Date().toISOString()))();
+    const merged = {
+        ...existing,
+        sessionId: info.providerSessionId,
+        protocolVersion: info.protocolVersion ?? existing.protocolVersion,
+        agentName: info.agentName ?? existing.agentName,
+        agentVersion: info.agentVersion ?? existing.agentVersion,
+        lastSeenAt: now,
+    };
+    return sessionManager.updateSessionMetadata(gatewaySessionId, { acp: merged });
+}
+export async function resolveAcpResume(sessionManager, gatewaySessionId, provider) {
+    const acp = await readAcpMetadata(sessionManager, gatewaySessionId);
+    if (!acp) {
+        const session = await sessionManager.getSession(gatewaySessionId);
+        return { ok: false, reason: session ? "wrong_transport" : "not_found" };
+    }
+    if (acp.transport !== ACP_TRANSPORT) {
+        return { ok: false, reason: "wrong_transport" };
+    }
+    if (acp.provider !== provider) {
+        return { ok: false, reason: "wrong_provider" };
+    }
+    if (!acp.sessionId) {
+        return { ok: false, reason: "no_provider_session" };
+    }
+    return { ok: true, providerSessionId: acp.sessionId, metadata: acp };
+}
+async function readAcpMetadata(sessionManager, gatewaySessionId) {
+    const session = await sessionManager.getSession(gatewaySessionId);
+    const acp = session?.metadata?.acp;
+    if (!acp || typeof acp !== "object")
+        return null;
+    return acp;
+}

package/dist/acp/smoke-harness.d.ts

@@ -0,0 +1,28 @@
+import { type AcpSpawnFn, type ProcessEnv } from "./process-manager.js";
+import type { AcpConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+import type { CliType } from "../session-manager.js";
+export interface AcpSmokeResult {
+    readonly provider: CliType;
+    readonly ok: boolean;
+    readonly protocolVersion: number | null;
+    readonly agentName: string | null;
+    readonly agentVersion: string | null;
+    readonly sessionCreated: boolean;
+    readonly durationMs: number;
+    readonly error: {
+        readonly kind: string;
+        readonly message: string;
+    } | null;
+}
+export interface AcpSmokeOptions {
+    readonly config: AcpConfig;
+    readonly logger?: Logger;
+    readonly spawn?: AcpSpawnFn;
+    readonly baseEnv?: ProcessEnv;
+    readonly cwd?: string;
+    readonly now?: () => number;
+}
+export declare function runAcpSmoke(provider: CliType, options: AcpSmokeOptions): Promise<AcpSmokeResult>;
+export declare function runAcpSmokes(providers: readonly CliType[], options: AcpSmokeOptions): Promise<AcpSmokeResult[]>;
+export declare function eligibleSmokeProviders(config: AcpConfig): CliType[];

package/dist/acp/smoke-harness.js

@@ -0,0 +1,90 @@
+import { tmpdir } from "node:os";
+import { AcpError } from "./errors.js";
+import { AcpProcessManager } from "./process-manager.js";
+import { getAcpProviderEntry, providerHasNativeAcp } from "./provider-registry.js";
+import { noopLogger } from "../logger.js";
+const SMOKE_HOST_SERVICES = Object.freeze({});
+export async function runAcpSmoke(provider, options) {
+    const logger = options.logger ?? noopLogger;
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const elapsed = () => Math.max(0, now() - startedAt);
+    if (!providerHasNativeAcp(provider)) {
+        return {
+            provider,
+            ok: false,
+            protocolVersion: null,
+            agentName: null,
+            agentVersion: null,
+            sessionCreated: false,
+            durationMs: elapsed(),
+            error: {
+                kind: "provider_unavailable",
+                message: `${getAcpProviderEntry(provider).displayName} has no native ACP entrypoint.`,
+            },
+        };
+    }
+    const manager = new AcpProcessManager({
+        config: options.config,
+        logger,
+        spawn: options.spawn,
+        baseEnv: options.baseEnv,
+    });
+    const cwd = options.cwd ?? `${tmpdir()}/llm-gateway-acp-smoke-${provider}`;
+    try {
+        const proc = await manager.start({ provider, cwd, hostServices: SMOKE_HOST_SERVICES });
+        try {
+            const init = proc.client.agentInfo;
+            const session = await proc.client.newSession({ cwd, mcpServers: [] });
+            logger.info("acp.smoke.success", {
+                provider,
+                protocolVersion: init?.protocolVersion,
+                durationMs: elapsed(),
+            });
+            return {
+                provider,
+                ok: true,
+                protocolVersion: init?.protocolVersion ?? null,
+                agentName: init?.agentInfo?.name ?? null,
+                agentVersion: init?.agentInfo?.version ?? null,
+                sessionCreated: session.sessionId.length > 0,
+                durationMs: elapsed(),
+                error: null,
+            };
+        }
+        finally {
+            proc.shutdown("SIGTERM");
+        }
+    }
+    catch (err) {
+        const kind = err instanceof AcpError ? err.kind : "unknown";
+        const message = err instanceof AcpError ? err.userMessage : `ACP smoke for ${provider} failed unexpectedly.`;
+        logger.error("acp.smoke.failure", { provider, kind, durationMs: elapsed() });
+        return {
+            provider,
+            ok: false,
+            protocolVersion: null,
+            agentName: null,
+            agentVersion: null,
+            sessionCreated: false,
+            durationMs: elapsed(),
+            error: { kind, message },
+        };
+    }
+    finally {
+        manager.shutdownAll("SIGKILL");
+    }
+}
+export async function runAcpSmokes(providers, options) {
+    const results = [];
+    for (const provider of providers) {
+        results.push(await runAcpSmoke(provider, options));
+    }
+    return results;
+}
+export function eligibleSmokeProviders(config) {
+    if (!config.enabled) {
+        return [];
+    }
+    return Object.keys(config.providers).filter(provider => providerHasNativeAcp(provider) && config.providers[provider]?.enabled === true);
+}

package/dist/api-http.d.ts

@@ -0,0 +1,18 @@
+import { URL } from "node:url";
+export declare const MAX_API_RESPONSE_BYTES: number;
+export declare const DEFAULT_API_TIMEOUT_MS = 600000;
+export declare class ApiHttpError extends Error {
+    readonly status: number | null;
+    readonly responseText: string;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | null, responseText?: string, code?: string | undefined);
+}
+export declare function isHttpsOrLoopbackUrl(value: string): boolean;
+export declare function isLoopbackUrl(value: string): boolean;
+export declare function buildEndpointUrl(baseUrl: string, path: string): URL;
+export declare function isHttpTransient(error: unknown): boolean;
+export interface ApiHttpResponse {
+    status: number;
+    text: string;
+}
+export declare function postJson(url: URL, body: unknown, headers: Record<string, string>, timeoutMs: number, extractErrorMessage?: (status: number, responseBody: string) => string, signal?: AbortSignal): Promise<ApiHttpResponse>;

package/dist/api-http.js

@@ -0,0 +1,122 @@
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { URL } from "node:url";
+export const MAX_API_RESPONSE_BYTES = 50 * 1024 * 1024;
+export const DEFAULT_API_TIMEOUT_MS = 600_000;
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "::1", "[::1]"];
+export class ApiHttpError extends Error {
+    status;
+    responseText;
+    code;
+    constructor(message, status = null, responseText = "", code) {
+        super(message);
+        this.status = status;
+        this.responseText = responseText;
+        this.code = code;
+        this.name = "ApiHttpError";
+    }
+}
+export function isHttpsOrLoopbackUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "https:")
+            return true;
+        if (url.protocol !== "http:")
+            return false;
+        return LOOPBACK_HOSTS.includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+export function isLoopbackUrl(value) {
+    try {
+        const url = new URL(value);
+        return ((url.protocol === "http:" || url.protocol === "https:") &&
+            LOOPBACK_HOSTS.includes(url.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+export function buildEndpointUrl(baseUrl, path) {
+    const trimmedBase = baseUrl.replace(/\/+$/, "");
+    const trimmedPath = path.replace(/^\/+/, "");
+    const url = new URL(`${trimmedBase}/${trimmedPath}`);
+    if (url.protocol !== "https:" &&
+        !(url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname))) {
+        throw new ApiHttpError(`API base_url must use https unless it targets localhost/loopback (got ${url.protocol}//${url.hostname})`);
+    }
+    return url;
+}
+export function isHttpTransient(error) {
+    const status = typeof error?.status === "number" ? error.status : null;
+    if (status === 429 || (status !== null && status >= 500))
+        return true;
+    return ["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "EPIPE"].includes(String(error?.code ?? ""));
+}
+export function postJson(url, body, headers, timeoutMs, extractErrorMessage = defaultErrorMessage, signal) {
+    const payload = JSON.stringify(body);
+    const requester = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new ApiHttpError("API request aborted", null, "", "ABORT_ERR"));
+            return;
+        }
+        const req = requester(url, {
+            method: "POST",
+            timeout: timeoutMs,
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+                ...headers,
+                "content-length": Buffer.byteLength(payload),
+            },
+        }, res => {
+            const chunks = [];
+            let bytes = 0;
+            res.on("data", chunk => {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                bytes += buf.length;
+                if (bytes > MAX_API_RESPONSE_BYTES) {
+                    req.destroy(new ApiHttpError("API response exceeded the 50MB limit", null));
+                    return;
+                }
+                chunks.push(buf);
+            });
+            res.on("end", () => {
+                const text = Buffer.concat(chunks).toString("utf8");
+                const status = res.statusCode ?? 0;
+                if (status < 200 || status >= 300) {
+                    reject(new ApiHttpError(extractErrorMessage(status, text), status, text));
+                    return;
+                }
+                resolve({ status, text });
+            });
+        });
+        req.on("timeout", () => {
+            req.destroy(new ApiHttpError("API request timed out", null, "", "ETIMEDOUT"));
+        });
+        const onAbort = () => {
+            req.destroy(new ApiHttpError("API request aborted", null, "", "ABORT_ERR"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        req.on("close", () => signal?.removeEventListener("abort", onAbort));
+        req.on("error", reject);
+        req.end(payload);
+    });
+}
+function defaultErrorMessage(status, body) {
+    if (!body)
+        return `API request failed with HTTP ${status}`;
+    try {
+        const parsed = JSON.parse(body);
+        const message = parsed?.error?.message ?? parsed?.message ?? parsed?.error;
+        if (typeof message === "string" && message.length > 0) {
+            return `API request failed with HTTP ${status}: ${message}`;
+        }
+    }
+    catch {
+    }
+    return `API request failed with HTTP ${status}: ${body.slice(0, 1000)}`;
+}

package/dist/api-provider.d.ts

@@ -0,0 +1,83 @@
+import type { URL } from "node:url";
+import type { Logger } from "./logger.js";
+import { ApiHttpError } from "./api-http.js";
+export type ApiProviderKind = "openai-compatible" | "anthropic" | "xai-responses";
+export interface ApiChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface ApiRequest {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    messages: ApiChatMessage[];
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    reasoningEffort?: "none" | "low" | "medium" | "high";
+    timeoutMs?: number;
+    previousResponseId?: string;
+}
+export interface ApiUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    costUsd?: number;
+    raw?: unknown;
+}
+export interface ApiResult {
+    model: string;
+    text: string;
+    usage: ApiUsage;
+    raw: unknown;
+    httpStatus: number;
+    responseId?: string | null;
+}
+export interface ApiProvider {
+    readonly name: string;
+    readonly kind: ApiProviderKind;
+    endpointUrl(baseUrl: string): URL;
+    buildBody(req: ApiRequest): Record<string, unknown>;
+    parseResult(httpStatus: number, body: string): ApiResult;
+    authHeaders(apiKey: string): Record<string, string>;
+    isTransient(err: unknown): boolean;
+}
+export declare class OpenAiCompatibleProvider implements ApiProvider {
+    readonly name: string;
+    readonly kind: "openai-compatible";
+    constructor(name: string);
+    endpointUrl(baseUrl: string): URL;
+    buildBody(req: ApiRequest): Record<string, unknown>;
+    parseResult(httpStatus: number, body: string): ApiResult;
+    authHeaders(apiKey: string): Record<string, string>;
+    isTransient(err: unknown): boolean;
+}
+export declare const DEFAULT_ANTHROPIC_VERSION = "2023-06-01";
+export declare class AnthropicProvider implements ApiProvider {
+    readonly name: string;
+    private readonly anthropicVersion;
+    readonly kind: "anthropic";
+    constructor(name: string, anthropicVersion?: string);
+    endpointUrl(baseUrl: string): URL;
+    buildBody(req: ApiRequest): Record<string, unknown>;
+    parseResult(httpStatus: number, body: string): ApiResult;
+    authHeaders(apiKey: string): Record<string, string>;
+    isTransient(err: unknown): boolean;
+}
+export declare class XaiResponsesProvider implements ApiProvider {
+    readonly name: string;
+    readonly kind: "xai-responses";
+    constructor(name: string);
+    endpointUrl(baseUrl: string): URL;
+    buildBody(req: ApiRequest): Record<string, unknown>;
+    parseResult(httpStatus: number, body: string): ApiResult;
+    authHeaders(apiKey: string): Record<string, string>;
+    isTransient(err: unknown): boolean;
+}
+export declare function createApiProvider(name: string, kind: ApiProviderKind): ApiProvider;
+export declare function resetApiProviderBreakers(): void;
+export declare function apiProviderBreakerState(name: string): string;
+export declare function runApiRequest(provider: ApiProvider, req: ApiRequest, logger?: Logger, opts?: {
+    signal?: AbortSignal;
+}): Promise<ApiResult>;
+export { ApiHttpError };