llm-cli-gateway 2.13.2 → 2.14.0

package/dist/provider-capability-discovery.js

@@ -0,0 +1,461 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { InitializeResponseSchema } from "./acp/types.js";
+import { envWithExtendedPath, getExtendedPath, resolveCommandForSpawn } from "./executor.js";
+import { noopLogger } from "./logger.js";
+import { getAllProviderDefinitions, } from "./provider-definitions.js";
+import { checksumText, parseHelpText, } from "./provider-help-parser.js";
+import { computeDiscoveryContractDrift, } from "./upstream-contracts.js";
+export const KNOWN_ACP_METHODS = [
+    "initialize",
+    "authenticate",
+    "session/new",
+    "session/load",
+    "session/resume",
+    "session/list",
+    "session/prompt",
+    "session/cancel",
+    "session/close",
+    "session/delete",
+    "session/update",
+    "session/set_mode",
+    "session/set_config_option",
+    "session/request_permission",
+    "fs/read_text_file",
+    "fs/write_text_file",
+    "terminal/create",
+    "terminal/output",
+    "terminal/release",
+];
+let cachedGatewayVersion;
+export function gatewayVersion() {
+    if (cachedGatewayVersion !== undefined)
+        return cachedGatewayVersion;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(here, "..", "package.json"), join(here, "..", "..", "package.json")];
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+            if (parsed.version) {
+                cachedGatewayVersion = parsed.version;
+                return cachedGatewayVersion;
+            }
+        }
+        catch {
+        }
+    }
+    cachedGatewayVersion = "unknown";
+    return cachedGatewayVersion;
+}
+export function resolveExecutableAbsolutePath(exe) {
+    const extendedPath = getExtendedPath();
+    const resolved = resolveCommandForSpawn(exe, [], { envPath: extendedPath });
+    if (resolved.command !== exe)
+        return resolved.command;
+    const result = spawnSync(process.platform === "win32" ? "where" : "command", ["-v", exe], {
+        encoding: "utf8",
+        timeout: 3000,
+        windowsHide: true,
+        shell: process.platform !== "win32",
+    });
+    const out = (result.stdout ?? "").split(/\r?\n/).find(line => line.trim().length > 0);
+    return out?.trim() || exe;
+}
+export function createDefaultProbeRunner(timeoutMs = 5000) {
+    return async (exe, argv) => {
+        const extendedPath = getExtendedPath();
+        const env = envWithExtendedPath(process.env, extendedPath);
+        const resolved = resolveCommandForSpawn(exe, [...argv], { envPath: extendedPath });
+        const result = spawnSync(resolved.command, resolved.args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            maxBuffer: 8 * 1024 * 1024,
+            env,
+            windowsHide: true,
+            windowsVerbatimArguments: resolved.windowsVerbatimArguments,
+        });
+        if (result.error)
+            throw result.error;
+        return {
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            code: result.status ?? 0,
+        };
+    };
+}
+export const defaultProbeRunner = createDefaultProbeRunner();
+function probeExecutable(def, probe) {
+    return probe.executable ?? def.primaryExecutable;
+}
+function subcommandProbeKey(def, probe) {
+    const exe = probeExecutable(def, probe);
+    const prefix = exe === def.primaryExecutable ? "" : `${exe} `;
+    return `${prefix}${probe.argv.join(" ")}`;
+}
+function presentCapabilityTokens(bag) {
+    if (!bag || typeof bag !== "object")
+        return [];
+    return Object.entries(bag)
+        .filter(([key]) => key !== "_meta")
+        .filter(([, value]) => value !== false && value !== null && value !== undefined)
+        .map(([key]) => key);
+}
+function authMethodTokens(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map(entry => {
+        if (typeof entry === "string")
+            return entry;
+        if (entry && typeof entry === "object") {
+            const record = entry;
+            if (typeof record.id === "string")
+                return record.id;
+            if (typeof record.name === "string")
+                return record.name;
+        }
+        return null;
+    })
+        .filter((entry) => typeof entry === "string");
+}
+function methodListToStrings(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map(entry => typeof entry === "string"
+        ? entry
+        : entry &&
+            typeof entry === "object" &&
+            typeof entry.name === "string"
+            ? entry.name
+            : null)
+        .filter((entry) => typeof entry === "string");
+}
+export function parseAcpInitialize(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0 || !(trimmed.startsWith("{") || trimmed.startsWith("["))) {
+        return { kind: "none" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { kind: "invalid", reason: "ACP initialize output is not valid JSON" };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { kind: "invalid", reason: "ACP initialize output is not a JSON object" };
+    }
+    const root = parsed;
+    const candidate = root.result !== undefined && typeof root.result === "object" && root.result !== null
+        ? root.result
+        : root;
+    const validated = InitializeResponseSchema.safeParse(candidate);
+    if (!validated.success) {
+        return {
+            kind: "invalid",
+            reason: `ACP initialize response failed validation: ${validated.error.message}`,
+        };
+    }
+    const result = validated.data;
+    const caps = result.agentCapabilities ?? null;
+    const agentInfo = result.agentInfo
+        ? {
+            ...(typeof result.agentInfo.name === "string" ? { name: result.agentInfo.name } : {}),
+            ...(typeof result.agentInfo.version === "string"
+                ? { version: result.agentInfo.version }
+                : {}),
+        }
+        : null;
+    const advertisedMethods = methodListToStrings(candidate.methods ??
+        candidate.availableMethods);
+    const knownMethods = advertisedMethods.filter(method => KNOWN_ACP_METHODS.includes(method));
+    const extensionMethods = advertisedMethods.filter(method => !KNOWN_ACP_METHODS.includes(method));
+    const protocolVersion = typeof result.protocolVersion === "number" ? result.protocolVersion : null;
+    const sessionTokens = presentCapabilityTokens(caps?.sessionCapabilities);
+    if (caps?.loadSession === true)
+        sessionTokens.push("load");
+    return {
+        kind: "ok",
+        value: {
+            protocolVersion,
+            agentInfo,
+            authMethods: authMethodTokens(result.authMethods),
+            promptCapabilities: presentCapabilityTokens(caps?.promptCapabilities),
+            mcpCapabilities: presentCapabilityTokens(caps?.mcpCapabilities),
+            sessionCapabilities: sessionTokens,
+            agentCapabilities: caps,
+            knownMethods,
+            extensionMethods,
+            checksum: checksumText(trimmed),
+        },
+    };
+}
+const EMPTY_HELP = {
+    flags: [],
+    subcommands: [],
+    discoveredUnmapped: [],
+    checksum: checksumText(""),
+};
+export async function discoverProviderCapabilities(def, options = {}) {
+    const runner = options.runner ?? defaultProbeRunner;
+    const resolvePath = options.resolveExecutablePath ?? resolveExecutableAbsolutePath;
+    const version = options.gatewayVersion ?? gatewayVersion();
+    const logger = options.logger ?? noopLogger;
+    const evidence = [];
+    const unmapped = [];
+    const discoveredAt = new Date().toISOString();
+    let executablePath;
+    try {
+        executablePath = resolvePath(def.primaryExecutable);
+    }
+    catch {
+        executablePath = def.primaryExecutable;
+    }
+    let versionString;
+    try {
+        const result = await runner(def.primaryExecutable, def.discovery.version.argv);
+        versionString = (result.stdout || result.stderr).split(/\r?\n/)[0]?.trim() ?? "";
+        evidence.push(`version: ${def.primaryExecutable} ${def.discovery.version.argv.join(" ")}`);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.debug(`capability discovery: ${def.id} version probe failed`, { reason });
+        return {
+            providerId: def.id,
+            executable: def.primaryExecutable,
+            executablePath,
+            version: "",
+            rootHelp: EMPTY_HELP,
+            subcommandHelp: {},
+            modelCatalog: {
+                strategy: def.discovery.modelDiscovery.strategy,
+                argv: def.discovery.modelDiscovery.argv,
+                raw: null,
+                checksum: checksumText(def.discovery.modelDiscovery.evidence),
+                evidence: def.discovery.modelDiscovery.evidence,
+            },
+            acpInitialize: null,
+            checksums: {
+                version: checksumText(""),
+                rootHelp: EMPTY_HELP.checksum,
+                subcommandHelp: {},
+                modelCatalog: checksumText(def.discovery.modelDiscovery.evidence),
+                acpInitialize: null,
+            },
+            sourceEvidence: evidence,
+            discoveredUnmapped: unmapped,
+            status: "error",
+            degradedReason: `version probe failed: ${reason}`,
+            gatewayVersion: version,
+            discoveredAt,
+        };
+    }
+    let degraded = false;
+    let degradedReason;
+    let rootHelp = EMPTY_HELP;
+    try {
+        const result = await runner(def.primaryExecutable, def.discovery.rootHelp.argv);
+        rootHelp = parseHelpText(result.stdout || result.stderr);
+        unmapped.push(...rootHelp.discoveredUnmapped);
+        evidence.push(`root-help: ${def.primaryExecutable} ${def.discovery.rootHelp.argv.join(" ")}`);
+    }
+    catch (err) {
+        degraded = true;
+        degradedReason = `root help probe failed: ${err instanceof Error ? err.message : String(err)}`;
+        logger.debug(`capability discovery: ${def.id} root help probe failed`, { degradedReason });
+    }
+    const subcommandHelp = {};
+    const subcommandChecksums = {};
+    for (const probe of def.discovery.subcommandHelp) {
+        const key = subcommandProbeKey(def, probe);
+        const exe = probeExecutable(def, probe);
+        try {
+            const result = await runner(exe, probe.argv);
+            const parsed = parseHelpText(result.stdout || result.stderr);
+            subcommandHelp[key] = parsed;
+            subcommandChecksums[key] = parsed.checksum;
+            unmapped.push(...parsed.discoveredUnmapped);
+            evidence.push(`subcommand-help: ${exe} ${probe.argv.join(" ")}`);
+        }
+        catch (err) {
+            degraded = true;
+            degradedReason = `subcommand help probe failed (${key}): ${err instanceof Error ? err.message : String(err)}`;
+            logger.debug(`capability discovery: ${def.id} subcommand help probe failed`, {
+                key,
+                degradedReason,
+            });
+        }
+    }
+    const md = def.discovery.modelDiscovery;
+    let modelRaw = null;
+    let modelChecksum = checksumText(md.evidence);
+    if (md.strategy === "native-command" && md.argv.length > 0) {
+        try {
+            const result = await runner(def.primaryExecutable, md.argv);
+            const stdout = result.stdout ?? "";
+            if (result.code === 0 && stdout.trim().length > 0) {
+                modelRaw = stdout;
+                modelChecksum = checksumText(modelRaw);
+                evidence.push(`model-catalog: ${def.primaryExecutable} ${md.argv.join(" ")}`);
+            }
+            else {
+                degraded = true;
+                const why = stdout.trim().length === 0 ? "empty stdout" : "stderr-only output";
+                degradedReason = `model catalog probe unusable (exit ${result.code}, ${why}); not treated as a catalog`;
+                evidence.push(`model-catalog: ${def.primaryExecutable} ${md.argv.join(" ")} (exit ${result.code}; ignored)`);
+                logger.debug(`capability discovery: ${def.id} model catalog probe unusable`, {
+                    degradedReason,
+                });
+            }
+        }
+        catch (err) {
+            degraded = true;
+            degradedReason = `model catalog probe failed: ${err instanceof Error ? err.message : String(err)}`;
+            logger.debug(`capability discovery: ${def.id} model catalog probe failed`, {
+                degradedReason,
+            });
+        }
+    }
+    else {
+        evidence.push(`model-catalog: ${md.strategy} (no read-only listing command)`);
+    }
+    const modelCatalog = {
+        strategy: md.strategy,
+        argv: md.argv,
+        raw: modelRaw,
+        checksum: modelChecksum,
+        evidence: md.evidence,
+    };
+    let acpInitialize = null;
+    let acpChecksum = null;
+    if (def.acp.classification === "native" && def.acp.probeArgv.length > 0) {
+        const acpProbe = def.acp.probeArgv[0];
+        const exe = def.acp.entrypoint?.command ?? def.primaryExecutable;
+        try {
+            const result = await runner(exe, acpProbe);
+            const parsed = parseAcpInitialize(result.stdout || result.stderr);
+            if (parsed.kind === "ok") {
+                acpInitialize = parsed.value;
+                acpChecksum = parsed.value.checksum;
+                evidence.push(`acp-initialize: ${exe} ${acpProbe.join(" ")}`);
+                for (const method of parsed.value.extensionMethods) {
+                    unmapped.push({
+                        kind: "acp-method",
+                        raw: method,
+                        checksum: checksumText(method),
+                        reason: "ACP method advertised by initialize is not known to the ACP spec and has no extension-namespace normalizer",
+                    });
+                }
+            }
+            else if (parsed.kind === "invalid") {
+                degraded = true;
+                degradedReason = `acp initialize invalid: ${parsed.reason}`;
+                evidence.push(`acp-probe: ${exe} ${acpProbe.join(" ")} (invalid initialize response)`);
+                logger.debug(`capability discovery: ${def.id} acp initialize invalid`, { degradedReason });
+            }
+            else {
+                evidence.push(`acp-probe: ${exe} ${acpProbe.join(" ")} (no initialize response)`);
+            }
+        }
+        catch (err) {
+            degraded = true;
+            degradedReason = `acp probe failed: ${err instanceof Error ? err.message : String(err)}`;
+            logger.debug(`capability discovery: ${def.id} acp probe failed`, { degradedReason });
+        }
+    }
+    return {
+        providerId: def.id,
+        executable: def.primaryExecutable,
+        executablePath,
+        version: versionString,
+        rootHelp,
+        subcommandHelp,
+        modelCatalog,
+        acpInitialize,
+        checksums: {
+            version: checksumText(versionString),
+            rootHelp: rootHelp.checksum,
+            subcommandHelp: subcommandChecksums,
+            modelCatalog: modelChecksum,
+            acpInitialize: acpChecksum,
+        },
+        sourceEvidence: evidence,
+        discoveredUnmapped: unmapped,
+        status: degraded ? "degraded" : "ok",
+        ...(degraded ? { degradedReason } : {}),
+        gatewayVersion: version,
+        discoveredAt,
+    };
+}
+export async function discoverAllProviders(options = {}) {
+    const out = new Map();
+    const results = await Promise.all(getAllProviderDefinitions().map(async (def) => {
+        try {
+            return await discoverProviderCapabilities(def, options);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            const version = options.gatewayVersion ?? gatewayVersion();
+            const set = {
+                providerId: def.id,
+                executable: def.primaryExecutable,
+                executablePath: def.primaryExecutable,
+                version: "",
+                rootHelp: EMPTY_HELP,
+                subcommandHelp: {},
+                modelCatalog: {
+                    strategy: def.discovery.modelDiscovery.strategy,
+                    argv: def.discovery.modelDiscovery.argv,
+                    raw: null,
+                    checksum: checksumText(def.discovery.modelDiscovery.evidence),
+                    evidence: def.discovery.modelDiscovery.evidence,
+                },
+                acpInitialize: null,
+                checksums: {
+                    version: checksumText(""),
+                    rootHelp: EMPTY_HELP.checksum,
+                    subcommandHelp: {},
+                    modelCatalog: checksumText(def.discovery.modelDiscovery.evidence),
+                    acpInitialize: null,
+                },
+                sourceEvidence: [],
+                discoveredUnmapped: [],
+                status: "error",
+                degradedReason: `discovery threw: ${reason}`,
+                gatewayVersion: version,
+                discoveredAt: new Date().toISOString(),
+            };
+            return set;
+        }
+    }));
+    for (const set of results)
+        out.set(set.providerId, set);
+    return out;
+}
+export function acpMethodAvailability(set) {
+    if (!set.acpInitialize) {
+        return { acpAvailable: false, knownMethods: [], extensionMethods: [] };
+    }
+    return {
+        acpAvailable: true,
+        knownMethods: set.acpInitialize.knownMethods,
+        extensionMethods: set.acpInitialize.extensionMethods,
+    };
+}
+export function discoveryContractDrift(set) {
+    const discoveredFlagNames = new Set();
+    for (const flag of set.rootHelp.flags) {
+        discoveredFlagNames.add(flag.name);
+        for (const alias of flag.aliases)
+            discoveredFlagNames.add(alias);
+    }
+    return computeDiscoveryContractDrift(set.providerId, {
+        version: set.version,
+        discoveredFlagNames: [...discoveredFlagNames],
+        discoveredUnmappedCount: set.discoveredUnmapped.length,
+        status: set.status,
+    });
+}

package/dist/provider-capability-resolver.d.ts

@@ -0,0 +1,29 @@
+import type { CliType } from "./provider-definitions.js";
+import { type ProviderDefinition } from "./provider-definitions.js";
+import { type DiscoveredCapabilitySet, type ProbeRunner } from "./provider-capability-discovery.js";
+import { type DiscoveredModelListing } from "./provider-model-discovery.js";
+import type { CliInfo } from "./model-registry.js";
+import { type Logger } from "./logger.js";
+export type CapabilityResolutionSource = "live" | "cache" | "static-fallback";
+export interface ResolvedProviderCapability {
+    readonly set: DiscoveredCapabilitySet;
+    readonly source: "live" | "cache";
+    readonly degraded: boolean;
+}
+export interface ResolveCapabilityOptions {
+    readonly runner?: ProbeRunner;
+    readonly inject?: (def: ProviderDefinition) => Promise<ResolvedProviderCapability | null> | ResolvedProviderCapability | null;
+    readonly forceRefresh?: boolean;
+    readonly logger?: Logger;
+}
+export declare function __resetCapabilityResolverMemoForTest(): void;
+export declare function __seedCapabilityResolverMemoForTest(id: CliType, resolution: ResolvedProviderCapability): void;
+export declare function peekProviderCapabilitySet(id: CliType): ResolvedProviderCapability | null;
+export declare function resolveProviderCapabilitySet(def: ProviderDefinition, options?: ResolveCapabilityOptions): Promise<ResolvedProviderCapability | null>;
+export declare function warmProviderCapabilities(options?: ResolveCapabilityOptions): Promise<void>;
+export interface ProviderDiscoveredView {
+    readonly source: CapabilityResolutionSource;
+    readonly degraded: boolean;
+    readonly listing: DiscoveredModelListing | null;
+}
+export declare function buildProviderDiscoveredView(def: ProviderDefinition, registryInfo: CliInfo | undefined, peek?: (id: CliType) => ResolvedProviderCapability | null): ProviderDiscoveredView;

package/dist/provider-capability-resolver.js

@@ -0,0 +1,92 @@
+import { getAllProviderDefinitions } from "./provider-definitions.js";
+import { defaultProbeRunner, discoverProviderCapabilities, } from "./provider-capability-discovery.js";
+import { readCapabilityCache, resolveCapabilitySet } from "./provider-capability-cache.js";
+import { discoverProviderModels } from "./provider-model-discovery.js";
+import { noopLogger } from "./logger.js";
+const DEFAULT_CAPABILITY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+function capabilityCacheTtlMs() {
+    const raw = process.env.LLM_GATEWAY_CAPABILITY_CACHE_TTL_MS;
+    if (raw === undefined)
+        return DEFAULT_CAPABILITY_CACHE_TTL_MS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : DEFAULT_CAPABILITY_CACHE_TTL_MS;
+}
+function isCacheSeedFresh(cachedAt) {
+    const ttl = capabilityCacheTtlMs();
+    if (ttl <= 0)
+        return false;
+    const cachedAtMs = Date.parse(cachedAt);
+    if (!Number.isFinite(cachedAtMs))
+        return false;
+    return Date.now() - cachedAtMs <= ttl;
+}
+const memo = new Map();
+export function __resetCapabilityResolverMemoForTest() {
+    memo.clear();
+}
+export function __seedCapabilityResolverMemoForTest(id, resolution) {
+    memo.set(id, resolution);
+}
+export function peekProviderCapabilitySet(id) {
+    return memo.get(id) ?? null;
+}
+export async function resolveProviderCapabilitySet(def, options = {}) {
+    const logger = options.logger ?? noopLogger;
+    if (!options.forceRefresh) {
+        const memoized = memo.get(def.id);
+        if (memoized)
+            return memoized;
+    }
+    try {
+        if (options.inject) {
+            const injected = await options.inject(def);
+            if (injected)
+                memo.set(def.id, injected);
+            return injected;
+        }
+        if (!options.forceRefresh) {
+            const cached = readCapabilityCache(def.id);
+            if (cached && cached.capabilitySet.status !== "error" && isCacheSeedFresh(cached.cachedAt)) {
+                const resolution = {
+                    set: cached.capabilitySet,
+                    source: "cache",
+                    degraded: cached.capabilitySet.status === "degraded",
+                };
+                memo.set(def.id, resolution);
+                return resolution;
+            }
+        }
+        const fresh = await discoverProviderCapabilities(def, {
+            runner: options.runner ?? defaultProbeRunner,
+            logger,
+        });
+        const resolved = resolveCapabilitySet(fresh);
+        if (resolved.source === "minimal") {
+            return null;
+        }
+        const resolution = {
+            set: resolved.set,
+            source: resolved.source === "discovery" ? "live" : "cache",
+            degraded: resolved.degraded,
+        };
+        memo.set(def.id, resolution);
+        return resolution;
+    }
+    catch (err) {
+        logger.debug(`capability resolve failed for ${def.id}`, {
+            reason: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+export async function warmProviderCapabilities(options = {}) {
+    await Promise.all(getAllProviderDefinitions().map(def => resolveProviderCapabilitySet(def, options).catch(() => null)));
+}
+export function buildProviderDiscoveredView(def, registryInfo, peek = peekProviderCapabilitySet) {
+    const resolved = peek(def.id);
+    if (!resolved) {
+        return { source: "static-fallback", degraded: false, listing: null };
+    }
+    const listing = discoverProviderModels(def, resolved.set, { registryInfo });
+    return { source: resolved.source, degraded: resolved.degraded, listing };
+}

package/dist/provider-definition-assertions.d.ts

@@ -0,0 +1,9 @@
+import { type CliType } from "./provider-types.js";
+import { type ProviderDefinition } from "./provider-definitions.js";
+export declare function assertNever(x: never, context?: string): never;
+export declare function providerScopeLabel(id: CliType): string;
+export declare const REQUIRED_PROVIDER_PROJECTIONS: readonly ["syncRequestTool", "asyncRequestTool", "modelsResource", "sessionsResource", "modelDiscovery", "sessionContinuity", "capabilityRow", "adminDescriptor", "upstreamContractRow", "docsSummary"];
+export type RequiredProviderProjection = (typeof REQUIRED_PROVIDER_PROJECTIONS)[number];
+export declare function assertExhaustiveProviderCoverage(defs?: readonly ProviderDefinition[]): void;
+export declare function assertProviderProjectionsProducible(def: ProviderDefinition): ReadonlySet<RequiredProviderProjection>;
+export declare function assertRegistryIntegrity(defs?: readonly ProviderDefinition[]): void;