llm-cli-gateway 2.13.2 → 2.14.0

package/dist/provider-capability-cache.js

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod/v3";
+export const CAPABILITY_CACHE_SCHEMA_VERSION = "provider-capability-cache.v1";
+export function capabilityCacheDir() {
+    const override = process.env.LLM_GATEWAY_CAPABILITY_CACHE_DIR;
+    if (override && override.trim().length > 0)
+        return override;
+    return path.join(os.homedir(), ".llm-cli-gateway", "capability-cache");
+}
+function cacheFilePath(providerId) {
+    return path.join(capabilityCacheDir(), `${providerId}.json`);
+}
+export function cacheKeyFields(set) {
+    return {
+        providerId: set.providerId,
+        executablePath: set.executablePath,
+        version: set.version,
+        rootHelpChecksum: set.checksums.rootHelp,
+        subcommandHelpChecksums: set.checksums.subcommandHelp,
+        acpInitializeChecksum: set.checksums.acpInitialize,
+        modelCatalogChecksum: set.checksums.modelCatalog,
+        gatewayVersion: set.gatewayVersion,
+    };
+}
+export function computeCacheKey(set) {
+    const fields = cacheKeyFields(set);
+    const canonical = JSON.stringify([
+        fields.providerId,
+        fields.executablePath,
+        fields.version,
+        fields.rootHelpChecksum,
+        Object.keys(fields.subcommandHelpChecksums)
+            .sort()
+            .map(key => [key, fields.subcommandHelpChecksums[key]]),
+        fields.acpInitializeChecksum,
+        fields.modelCatalogChecksum,
+        fields.gatewayVersion,
+    ]);
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+const REDACTED = "[REDACTED]";
+const SENSITIVE_KEY_PATTERN = "token|secret|password|passwd|credential|auth|private[_-]?key|api[_-]?key|apikey|" +
+    "(?:access|api|client|customer|user|account|org)[_-]?(?:id|key|token|secret)";
+const ACCOUNT_KEY_NAMES = "account|acct";
+const KV_VALUE = "[^\\s\"',;]+";
+const JSON_VALUE = '(?:[^"\\\\]|\\\\.)*';
+const REDACT_VALUE = (match, keyPart) => `${keyPart}${REDACTED}`;
+const REDACT_JSON_VALUE = (match, keyPart) => `${keyPart}"${REDACTED}"`;
+const SECRET_RULES = [
+    {
+        pattern: /\b(?:sk-ant-|anthropic-|sk-|xai-|gsk_|gh[pousr]_|github_pat_|ya29\.|AKIA|ASIA)[A-Za-z0-9_.-]{8,}/g,
+        replacement: REDACTED,
+    },
+    { pattern: /1\/\/[A-Za-z0-9_.-]{8,}/g, replacement: REDACTED },
+    { pattern: /\bAuthorization\s*:\s*(?:Bearer|Basic)\s+\S+/gi, replacement: REDACTED },
+    { pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{6,}/gi, replacement: REDACTED },
+    {
+        pattern: new RegExp(`("[A-Za-z0-9_.-]*(?:${SENSITIVE_KEY_PATTERN})[A-Za-z0-9_.-]*"\\s*:\\s*)"${JSON_VALUE}"`, "gi"),
+        replacement: REDACT_JSON_VALUE,
+    },
+    {
+        pattern: new RegExp(`\\b([A-Za-z0-9_.-]*(?:${SENSITIVE_KEY_PATTERN})[A-Za-z0-9_.-]*\\s*[:=]\\s*)${KV_VALUE}`, "gi"),
+        replacement: REDACT_VALUE,
+    },
+    {
+        pattern: new RegExp(`\\b((?:${ACCOUNT_KEY_NAMES})\\s*[:=]\\s*)${KV_VALUE}`, "gi"),
+        replacement: REDACT_VALUE,
+    },
+    { pattern: /\b(?:user|customer|account|acct|org)_[0-9]{6,}\b/g, replacement: REDACTED },
+    { pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, replacement: REDACTED },
+];
+export function scrubString(value) {
+    let out = value;
+    for (const rule of SECRET_RULES) {
+        out =
+            typeof rule.replacement === "string"
+                ? out.replace(rule.pattern, rule.replacement)
+                : out.replace(rule.pattern, rule.replacement);
+    }
+    return out;
+}
+export function scrubSecrets(value) {
+    if (typeof value === "string")
+        return scrubString(value);
+    if (Array.isArray(value))
+        return value.map(entry => scrubSecrets(entry));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            out[key] = scrubSecrets(entry);
+        }
+        return out;
+    }
+    return value;
+}
+const ParsedUnmappedSchema = z
+    .object({
+    kind: z.string(),
+    raw: z.string(),
+    checksum: z.string(),
+    reason: z.string(),
+})
+    .passthrough();
+const ParsedHelpSchema = z
+    .object({
+    flags: z.array(z.object({ name: z.string() }).passthrough()),
+    subcommands: z.array(z.object({ name: z.string() }).passthrough()),
+    discoveredUnmapped: z.array(ParsedUnmappedSchema),
+    checksum: z.string(),
+})
+    .passthrough();
+const DiscoveredCapabilitySetSchema = z
+    .object({
+    providerId: z.string(),
+    executable: z.string(),
+    executablePath: z.string(),
+    version: z.string(),
+    rootHelp: ParsedHelpSchema,
+    subcommandHelp: z.record(z.string(), ParsedHelpSchema),
+    modelCatalog: z
+        .object({
+        strategy: z.string(),
+        argv: z.array(z.string()),
+        raw: z.string().nullable(),
+        checksum: z.string(),
+        evidence: z.string(),
+    })
+        .passthrough(),
+    acpInitialize: z.object({}).passthrough().nullable(),
+    checksums: z
+        .object({
+        version: z.string(),
+        rootHelp: z.string(),
+        subcommandHelp: z.record(z.string(), z.string()),
+        modelCatalog: z.string(),
+        acpInitialize: z.string().nullable(),
+    })
+        .passthrough(),
+    sourceEvidence: z.array(z.string()),
+    discoveredUnmapped: z.array(ParsedUnmappedSchema),
+    status: z.enum(["ok", "degraded", "error"]),
+    degradedReason: z.string().optional(),
+    gatewayVersion: z.string(),
+    discoveredAt: z.string(),
+})
+    .passthrough();
+const CachedCapabilityEntrySchema = z
+    .object({
+    schemaVersion: z.literal(CAPABILITY_CACHE_SCHEMA_VERSION),
+    providerId: z.string(),
+    cacheKey: z.string(),
+    keyFields: z.object({}).passthrough(),
+    capabilitySet: DiscoveredCapabilitySetSchema,
+    cachedAt: z.string(),
+    source: z.literal("discovery"),
+})
+    .passthrough();
+export function readCapabilityCache(providerId) {
+    const file = cacheFilePath(providerId);
+    if (!existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const parsed = CachedCapabilityEntrySchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    if (parsed.data.providerId !== providerId)
+        return null;
+    if (parsed.data.capabilitySet.providerId !== providerId)
+        return null;
+    return parsed.data;
+}
+export function writeCapabilityCache(set) {
+    const dir = capabilityCacheDir();
+    mkdirSync(dir, { recursive: true });
+    const scrubbedSet = scrubSecrets(set);
+    const entry = {
+        schemaVersion: CAPABILITY_CACHE_SCHEMA_VERSION,
+        providerId: set.providerId,
+        cacheKey: computeCacheKey(set),
+        keyFields: scrubSecrets(cacheKeyFields(set)),
+        capabilitySet: scrubbedSet,
+        cachedAt: new Date().toISOString(),
+        source: "discovery",
+    };
+    const file = cacheFilePath(set.providerId);
+    writeFileSync(file, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 0o600 });
+    return entry;
+}
+export function lookupCapabilityCache(freshSet) {
+    const entry = readCapabilityCache(freshSet.providerId);
+    if (!entry) {
+        return {
+            hit: false,
+            ageMs: null,
+            cachedAt: null,
+            source: null,
+            version: null,
+            checksum: null,
+            entry: null,
+        };
+    }
+    const freshKey = computeCacheKey(freshSet);
+    const hit = entry.cacheKey === freshKey;
+    const cachedAtMs = Date.parse(entry.cachedAt);
+    return {
+        hit,
+        ageMs: Number.isFinite(cachedAtMs) ? Date.now() - cachedAtMs : null,
+        cachedAt: entry.cachedAt,
+        source: entry.source,
+        version: entry.keyFields.version,
+        checksum: entry.cacheKey,
+        entry,
+    };
+}
+export function resolveCapabilitySet(freshSet) {
+    if (freshSet.status !== "error") {
+        writeCapabilityCache(freshSet);
+        return { set: freshSet, source: "discovery", degraded: freshSet.status === "degraded" };
+    }
+    const entry = readCapabilityCache(freshSet.providerId);
+    if (entry &&
+        entry.keyFields.executablePath === freshSet.executablePath &&
+        entry.keyFields.version === freshSet.version &&
+        freshSet.version.length > 0) {
+        return {
+            set: entry.capabilitySet,
+            source: "cache",
+            degraded: true,
+            reason: freshSet.degradedReason ?? "discovery failed; using last valid cached capability set",
+        };
+    }
+    return {
+        set: freshSet,
+        source: "minimal",
+        degraded: true,
+        reason: freshSet.degradedReason ??
+            "discovery failed and no matching cache exists; minimal prompt surface only",
+    };
+}

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

@@ -0,0 +1,85 @@
+import { type AgentCapabilities } from "./acp/types.js";
+import { type Logger } from "./logger.js";
+import { type CliType, type ProviderDefinition } from "./provider-definitions.js";
+import { type DiscoveredUnmapped, type ParsedHelp } from "./provider-help-parser.js";
+import { type DiscoveryContractDrift } from "./upstream-contracts.js";
+export interface ProbeResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export type ProbeRunner = (exe: string, argv: readonly string[]) => Promise<ProbeResult>;
+export interface DiscoveredModelCatalog {
+    readonly strategy: string;
+    readonly argv: readonly string[];
+    readonly raw: string | null;
+    readonly checksum: string;
+    readonly evidence: string;
+}
+export declare const KNOWN_ACP_METHODS: readonly string[];
+export interface ParsedAcpInitialize {
+    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 agentCapabilities: AgentCapabilities | null;
+    readonly knownMethods: readonly string[];
+    readonly extensionMethods: readonly string[];
+    readonly checksum: string;
+}
+export interface DiscoveredCapabilitySet {
+    readonly providerId: CliType;
+    readonly executable: string;
+    readonly executablePath: string;
+    readonly version: string;
+    readonly rootHelp: ParsedHelp;
+    readonly subcommandHelp: Readonly<Record<string, ParsedHelp>>;
+    readonly modelCatalog: DiscoveredModelCatalog;
+    readonly acpInitialize: ParsedAcpInitialize | null;
+    readonly checksums: {
+        readonly version: string;
+        readonly rootHelp: string;
+        readonly subcommandHelp: Readonly<Record<string, string>>;
+        readonly modelCatalog: string;
+        readonly acpInitialize: string | null;
+    };
+    readonly sourceEvidence: readonly string[];
+    readonly discoveredUnmapped: readonly DiscoveredUnmapped[];
+    readonly status: "ok" | "degraded" | "error";
+    readonly degradedReason?: string;
+    readonly gatewayVersion: string;
+    readonly discoveredAt: string;
+}
+export interface DiscoveryOptions {
+    readonly runner?: ProbeRunner;
+    readonly gatewayVersion?: string;
+    readonly resolveExecutablePath?: (exe: string) => string;
+    readonly logger?: Logger;
+}
+export declare function gatewayVersion(): string;
+export declare function resolveExecutableAbsolutePath(exe: string): string;
+export declare function createDefaultProbeRunner(timeoutMs?: number): ProbeRunner;
+export declare const defaultProbeRunner: ProbeRunner;
+export type AcpInitializeParse = {
+    readonly kind: "none";
+} | {
+    readonly kind: "ok";
+    readonly value: ParsedAcpInitialize;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+export declare function parseAcpInitialize(text: string): AcpInitializeParse;
+export declare function discoverProviderCapabilities(def: ProviderDefinition, options?: DiscoveryOptions): Promise<DiscoveredCapabilitySet>;
+export declare function discoverAllProviders(options?: DiscoveryOptions): Promise<Map<CliType, DiscoveredCapabilitySet>>;
+export declare function acpMethodAvailability(set: DiscoveredCapabilitySet): {
+    readonly acpAvailable: boolean;
+    readonly knownMethods: readonly string[];
+    readonly extensionMethods: readonly string[];
+};
+export declare function discoveryContractDrift(set: DiscoveredCapabilitySet): DiscoveryContractDrift;