llm-cli-gateway 2.13.2 → 2.14.0

package/dist/provider-help-parser.d.ts

@@ -0,0 +1,34 @@
+export type ParsedFlagArity = "none" | "one" | "many";
+export type ParsedFlagValueType = "boolean" | "string" | "enum" | "number" | "unknown";
+export type ParsedFlagSafety = "safe" | "dangerous" | "unknown";
+export type ParsedArgvPlacement = "flag" | "flag-then-value";
+export interface ParsedFlag {
+    readonly name: string;
+    readonly aliases: readonly string[];
+    readonly arity: ParsedFlagArity;
+    readonly valueType: ParsedFlagValueType;
+    readonly enumValues: readonly string[];
+    readonly repeatable: boolean;
+    readonly safety: ParsedFlagSafety;
+    readonly argvPlacement: ParsedArgvPlacement;
+    readonly description: string;
+}
+export interface ParsedSubcommand {
+    readonly name: string;
+    readonly description: string;
+    readonly helpChecksum: string;
+}
+export interface DiscoveredUnmapped {
+    readonly kind: "flag" | "subcommand" | "acp-method" | "model";
+    readonly raw: string;
+    readonly checksum: string;
+    readonly reason: string;
+}
+export interface ParsedHelp {
+    readonly flags: readonly ParsedFlag[];
+    readonly subcommands: readonly ParsedSubcommand[];
+    readonly discoveredUnmapped: readonly DiscoveredUnmapped[];
+    readonly checksum: string;
+}
+export declare function checksumText(text: string): string;
+export declare function parseHelpText(helpText: string): ParsedHelp;

package/dist/provider-help-parser.js

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+export function checksumText(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+const FLAG_TOKEN = /^-{1,2}[a-zA-Z][a-zA-Z0-9-]*$/;
+const DANGEROUS_KEYWORDS = [
+    "dangerous",
+    "bypass",
+    "yolo",
+    "skip-permission",
+    "skip permissions",
+    "skip-git",
+    "no-sandbox",
+    "without sandbox",
+    "auto-approve",
+    "always-approve",
+    "disable-web-search",
+    "force",
+];
+const NUMBER_PLACEHOLDERS = /^(n|num|count|number|seconds|secs|ms|port|size|turns|budget|price|tokens|max[-_]?turns)$/i;
+const PATH_PLACEHOLDERS = /^(file|files|dir|path|dir(ectory)?|glob)$/i;
+const SUBCOMMAND_LINE = /^([a-zA-Z][a-zA-Z0-9_-]*)((?:\s+(?:<[^<>]*>|\[[^[\]]*\]|\.\.\.))*)(?:\s{2,}(\S.*)?)?$/;
+function isDangerous(name, description) {
+    const haystack = `${name} ${description}`.toLowerCase();
+    return DANGEROUS_KEYWORDS.some(keyword => haystack.includes(keyword));
+}
+function extractEnumValues(fragment) {
+    const possible = /\bpossible values:\s*([^\]\n]+)/i.exec(fragment);
+    if (possible) {
+        return possible[1]
+            .split(",")
+            .map(value => value.trim())
+            .filter(value => value.length > 0);
+    }
+    const piped = /[<[]([a-zA-Z0-9._-]+(?:\s*\|\s*[a-zA-Z0-9._-]+)+)[\]>]/.exec(fragment);
+    if (piped) {
+        return piped[1]
+            .split("|")
+            .map(value => value.trim())
+            .filter(value => value.length > 0);
+    }
+    return [];
+}
+function hasValuePlaceholder(afterFlags) {
+    if (/[<[][^\]>]*[\]>]/.test(afterFlags))
+        return true;
+    if (/\b[A-Z][A-Z0-9_]{1,}\b/.test(afterFlags.split(/\s{2,}/, 1)[0] ?? ""))
+        return true;
+    if (/=/.test(afterFlags.split(/\s{2,}/, 1)[0] ?? ""))
+        return true;
+    return false;
+}
+function inferValueType(placeholder, enumValues) {
+    if (enumValues.length > 0)
+        return "enum";
+    const inner = /[<[]([^\]>]+)[\]>]/.exec(placeholder)?.[1]?.trim() ?? placeholder.trim();
+    const token = inner
+        .replace(/\.\.\.$/, "")
+        .replace(/[<>[\]]/g, "")
+        .trim();
+    if (token.length === 0)
+        return "string";
+    if (token.includes("="))
+        return "string";
+    if (NUMBER_PLACEHOLDERS.test(token))
+        return "number";
+    if (PATH_PLACEHOLDERS.test(token))
+        return "string";
+    if (/^[a-zA-Z0-9_./|-]+$/.test(token))
+        return "string";
+    return "unknown";
+}
+function splitFlagLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("-"))
+        return null;
+    const gap = /\s{2,}/.exec(trimmed);
+    const declPart = gap ? trimmed.slice(0, gap.index) : trimmed;
+    const description = gap ? trimmed.slice(gap.index).trim() : "";
+    const pieces = declPart.split(/[,\s]+/).filter(Boolean);
+    const tokens = [];
+    let i = 0;
+    for (; i < pieces.length; i++) {
+        if (pieces[i].startsWith("-")) {
+            tokens.push(pieces[i]);
+        }
+        else {
+            break;
+        }
+    }
+    const afterFlags = pieces.slice(i).join(" ");
+    return { tokens, afterFlags, description };
+}
+export function parseHelpText(helpText) {
+    const normalized = helpText.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const flags = [];
+    const subcommands = [];
+    const discoveredUnmapped = [];
+    const seenFlagNames = new Set();
+    const seenSubcommands = new Set();
+    let inSubcommandSection = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const lower = trimmed.toLowerCase();
+        if (/^(commands|available subcommands|subcommands):$/.test(lower)) {
+            inSubcommandSection = true;
+            continue;
+        }
+        if (/^(options|arguments|flags):$/.test(lower) || lower.startsWith("usage")) {
+            inSubcommandSection = false;
+            if (lower.startsWith("usage"))
+                continue;
+            continue;
+        }
+        const decl = splitFlagLine(line);
+        if (inSubcommandSection && !decl) {
+            const match = SUBCOMMAND_LINE.exec(trimmed);
+            if (match) {
+                const name = match[1];
+                if (name === "help")
+                    continue;
+                if (!seenSubcommands.has(name)) {
+                    seenSubcommands.add(name);
+                    const description = (match[3] ?? "").trim();
+                    subcommands.push({
+                        name,
+                        description,
+                        helpChecksum: checksumText(`${name}\t${description}`),
+                    });
+                }
+                continue;
+            }
+        }
+        if (!decl)
+            continue;
+        if (decl.tokens.length === 0 || !decl.tokens.every(token => FLAG_TOKEN.test(token))) {
+            discoveredUnmapped.push({
+                kind: "flag",
+                raw: trimmed,
+                checksum: checksumText(trimmed),
+                reason: "help line begins with '-' but its leading token is not a parseable flag (non-ASCII or malformed flag name)",
+            });
+            continue;
+        }
+        const longFlag = decl.tokens.find(token => token.startsWith("--"));
+        const name = longFlag ?? decl.tokens[0];
+        const aliases = decl.tokens.filter(token => token !== name);
+        if (seenFlagNames.has(name))
+            continue;
+        seenFlagNames.add(name);
+        let enumSource = `${decl.afterFlags} ${decl.description}`;
+        for (let j = index + 1; j < lines.length; j++) {
+            const cont = lines[j];
+            if (cont.trim().length === 0)
+                break;
+            const contDecl = splitFlagLine(cont);
+            if (contDecl && contDecl.tokens.length > 0)
+                break;
+            enumSource += ` ${cont.trim()}`;
+            if (/possible values:/i.test(cont))
+                break;
+        }
+        const enumValues = extractEnumValues(enumSource);
+        const takesValue = hasValuePlaceholder(decl.afterFlags) || enumValues.length > 0;
+        const repeatable = /\.\.\./.test(decl.afterFlags) ||
+            /repeat/i.test(decl.description) ||
+            /repeatable/i.test(enumSource);
+        let arity;
+        if (!takesValue) {
+            arity = "none";
+        }
+        else if (repeatable) {
+            arity = "many";
+        }
+        else {
+            arity = "one";
+        }
+        const valueType = arity === "none" ? "boolean" : inferValueType(decl.afterFlags, enumValues);
+        const description = decl.description;
+        const safety = isDangerous(name, description) ? "dangerous" : "safe";
+        flags.push({
+            name,
+            aliases,
+            arity,
+            valueType,
+            enumValues,
+            repeatable,
+            safety,
+            argvPlacement: arity === "none" ? "flag" : "flag-then-value",
+            description,
+        });
+    }
+    return {
+        flags,
+        subcommands,
+        discoveredUnmapped,
+        checksum: checksumText(normalized.trim()),
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { CliType, ModelCatalogParseFormat, ModelFallbackPolicy, ProviderDefinition, ProviderModelConfigSource, ProviderModelFacts } from "./provider-definitions.js";
+import type { DiscoveredCapabilitySet } from "./provider-capability-discovery.js";
+import { type DiscoveredUnmapped } from "./provider-help-parser.js";
+import type { CliInfo } from "./model-registry.js";
+export type ModelOrigin = "live-catalog" | "live-hidden" | "account-label" | "config" | "env" | "curated-fallback";
+export interface DiscoveredModel {
+    readonly id: string;
+    readonly label?: string;
+    readonly description?: string;
+    readonly origin: ModelOrigin;
+    readonly isDefault: boolean;
+}
+export interface DiscoveredModelListing {
+    readonly providerId: CliType;
+    readonly strategy: string;
+    readonly parse: ModelCatalogParseFormat;
+    readonly fallbackPolicy: ModelFallbackPolicy;
+    readonly source: "live-command" | "config-or-env" | "curated-catalog";
+    readonly defaultModel: string | null;
+    readonly models: readonly DiscoveredModel[];
+    readonly facts: ProviderModelFacts;
+    readonly configSources: readonly ProviderModelConfigSource[];
+    readonly catalogChecksum: string;
+    readonly discoveredUnmapped: readonly DiscoveredUnmapped[];
+    readonly evidence: string;
+}
+export interface ModelDiscoveryOptions {
+    readonly registryInfo?: CliInfo;
+}
+export declare function discoverProviderModels(def: ProviderDefinition, set: DiscoveredCapabilitySet, options?: ModelDiscoveryOptions): DiscoveredModelListing;

package/dist/provider-model-discovery.js

@@ -0,0 +1,229 @@
+import { assertNever } from "./provider-definition-assertions.js";
+import { checksumText } from "./provider-help-parser.js";
+import { scrubString } from "./provider-capability-cache.js";
+function shortDescription(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length > 200 ? `${trimmed.slice(0, 197)}...` : trimmed;
+}
+function isPlausibleModelId(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]{1,80}$/.test(value);
+}
+const EMPTY_NATIVE = { models: [], defaultModel: null, unmapped: [] };
+function parseCodexDebugJson(raw) {
+    const models = [];
+    const unmapped = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        unmapped.push({
+            kind: "model",
+            raw: raw.slice(0, 120),
+            checksum: checksumText(raw),
+            reason: "codex debug models output is not valid JSON",
+        });
+        return { models, defaultModel: null, unmapped };
+    }
+    const list = parsed && typeof parsed === "object" && Array.isArray(parsed.models)
+        ? parsed.models
+        : null;
+    if (!list) {
+        unmapped.push({
+            kind: "model",
+            raw: JSON.stringify(parsed).slice(0, 120),
+            checksum: checksumText(raw),
+            reason: "codex debug models JSON has no models[] array",
+        });
+        return { models, defaultModel: null, unmapped };
+    }
+    for (const entry of list) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const record = entry;
+        const slug = typeof record.slug === "string" ? record.slug.trim() : "";
+        if (!slug || !isPlausibleModelId(slug)) {
+            unmapped.push({
+                kind: "model",
+                raw: JSON.stringify(record).slice(0, 120),
+                checksum: checksumText(JSON.stringify(record)),
+                reason: "codex model entry has a missing or non-id slug",
+            });
+            continue;
+        }
+        const origin = record.visibility === "list" ? "live-catalog" : "live-hidden";
+        models.push({
+            id: slug,
+            label: typeof record.display_name === "string" ? record.display_name : undefined,
+            description: shortDescription(record.description),
+            origin,
+            isDefault: false,
+        });
+    }
+    return { models, defaultModel: null, unmapped };
+}
+function parseGrokModelsText(raw) {
+    const models = [];
+    const unmapped = [];
+    let defaultModel = null;
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const defaultMatch = /^default model:\s*(\S+)/i.exec(trimmed);
+        if (defaultMatch) {
+            defaultModel = defaultMatch[1];
+            continue;
+        }
+        const bullet = /^[*-]\s+(\S+)(\s*\(default\))?\s*$/.exec(trimmed);
+        if (!bullet)
+            continue;
+        const id = bullet[1];
+        if (!isPlausibleModelId(id)) {
+            unmapped.push({
+                kind: "model",
+                raw: trimmed,
+                checksum: checksumText(trimmed),
+                reason: "grok models bullet line has a non-id token",
+            });
+            continue;
+        }
+        const isDefault = Boolean(bullet[2]) || id === defaultModel;
+        if (isDefault)
+            defaultModel = id;
+        models.push({ id, origin: "live-catalog", isDefault });
+    }
+    return { models, defaultModel, unmapped };
+}
+function isPlausibleModelLabel(label) {
+    if (label.length < 2 || label.length > 60)
+        return false;
+    if (label.endsWith(":"))
+        return false;
+    if (/^[-*=_#>|]+/.test(label))
+        return false;
+    if (/\s{2,}/.test(label))
+        return false;
+    if (/https?:\/\//i.test(label))
+        return false;
+    if ((label.match(/\s/g)?.length ?? 0) > 8)
+        return false;
+    return true;
+}
+function parseAgyModelsText(raw) {
+    const models = [];
+    const unmapped = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const label = line.trim();
+        if (label.length === 0)
+            continue;
+        if (!isPlausibleModelLabel(label)) {
+            unmapped.push({
+                kind: "model",
+                raw: label.slice(0, 120),
+                checksum: checksumText(label),
+                reason: "agy models line is not a plausible model label",
+            });
+            continue;
+        }
+        models.push({ id: label, label, origin: "account-label", isDefault: false });
+    }
+    return { models, defaultModel: null, unmapped };
+}
+function registryOrigin(source) {
+    switch (source) {
+        case "env":
+            return "env";
+        case "config":
+            return "config";
+        default:
+            return "curated-fallback";
+    }
+}
+function mergeRegistryModels(base, defaultModel, info) {
+    if (!info)
+        return { models: base, defaultModel };
+    const byId = new Map();
+    for (const model of base)
+        byId.set(model.id, model);
+    const resolvedDefault = defaultModel ?? info.defaultModel ?? null;
+    for (const [id, description] of Object.entries(info.models)) {
+        if (byId.has(id))
+            continue;
+        byId.set(id, {
+            id,
+            description: shortDescription(description),
+            origin: registryOrigin(info.modelMetadata?.[id]?.source),
+            isDefault: id === resolvedDefault,
+        });
+    }
+    const models = [...byId.values()].map(model => ({
+        ...model,
+        isDefault: model.id === resolvedDefault ? true : model.isDefault,
+    }));
+    return { models, defaultModel: resolvedDefault };
+}
+export function discoverProviderModels(def, set, options = {}) {
+    const md = def.discovery.modelDiscovery;
+    const raw = set.modelCatalog.raw ?? "";
+    let native;
+    let source;
+    switch (md.parse) {
+        case "codex-debug-json":
+            native = raw.trim().length > 0 ? parseCodexDebugJson(raw) : EMPTY_NATIVE;
+            source = "live-command";
+            break;
+        case "grok-models-text":
+            native = raw.trim().length > 0 ? parseGrokModelsText(raw) : EMPTY_NATIVE;
+            source = "live-command";
+            break;
+        case "agy-models-text":
+            native = raw.trim().length > 0 ? parseAgyModelsText(raw) : EMPTY_NATIVE;
+            source = "live-command";
+            break;
+        case "config-or-env":
+            native = EMPTY_NATIVE;
+            source = "config-or-env";
+            break;
+        case "curated-catalog":
+            native = EMPTY_NATIVE;
+            source = "curated-catalog";
+            break;
+        default:
+            return assertNever(md.parse, "ModelCatalogParseFormat");
+    }
+    const merged = mergeRegistryModels(native.models, native.defaultModel, options.registryInfo);
+    return {
+        providerId: def.id,
+        strategy: md.strategy,
+        parse: md.parse,
+        fallbackPolicy: md.fallbackPolicy,
+        source,
+        defaultModel: merged.defaultModel ? scrubString(merged.defaultModel) : merged.defaultModel,
+        models: merged.models.map(scrubModel),
+        facts: md.facts,
+        configSources: md.configSources,
+        catalogChecksum: set.checksums.modelCatalog,
+        discoveredUnmapped: native.unmapped.map(scrubUnmapped),
+        evidence: scrubString(md.evidence),
+    };
+}
+function scrubModel(model) {
+    return {
+        ...model,
+        id: scrubString(model.id),
+        ...(model.label !== undefined ? { label: scrubString(model.label) } : {}),
+        ...(model.description !== undefined ? { description: scrubString(model.description) } : {}),
+    };
+}
+function scrubUnmapped(unmapped) {
+    return {
+        ...unmapped,
+        raw: scrubString(unmapped.raw),
+        reason: scrubString(unmapped.reason),
+    };
+}

package/dist/provider-output-metadata.d.ts

@@ -0,0 +1,7 @@
+export type ProviderMetadataAbsentField = "sessionId" | "stopReason" | "usage";
+export interface ProviderOutputMetadata {
+    sessionId?: string;
+    stopReason?: string;
+    absentFields: readonly ProviderMetadataAbsentField[];
+}
+export declare function extractProviderOutputMetadata(cli: string, stdout: string, outputFormat: string | undefined): ProviderOutputMetadata;

package/dist/provider-output-metadata.js

@@ -0,0 +1,68 @@
+import { parseStreamJson } from "./stream-json-parser.js";
+import { parseCodexJsonStream } from "./codex-json-parser.js";
+import { parseGeminiJson, parseGeminiStreamJson } from "./gemini-json-parser.js";
+import { parseGrokOutput } from "./grok-json-parser.js";
+export function extractProviderOutputMetadata(cli, stdout, outputFormat) {
+    switch (cli) {
+        case "claude": {
+            const parsed = parseStreamJson(stdout);
+            const out = { absentFields: [] };
+            if (parsed.sessionId)
+                out.sessionId = parsed.sessionId;
+            if (parsed.stopReason)
+                out.stopReason = parsed.stopReason;
+            if (!out.sessionId)
+                out.absentFields.push("sessionId");
+            if (!out.stopReason)
+                out.absentFields.push("stopReason");
+            return out;
+        }
+        case "codex": {
+            const parsed = parseCodexJsonStream(stdout);
+            const out = { absentFields: [] };
+            if (parsed.threadId)
+                out.sessionId = parsed.threadId;
+            if (parsed.stopReason)
+                out.stopReason = parsed.stopReason;
+            if (!out.sessionId)
+                out.absentFields.push("sessionId");
+            if (!out.stopReason)
+                out.absentFields.push("stopReason");
+            return out;
+        }
+        case "gemini": {
+            const parsed = outputFormat === "stream-json"
+                ? parseGeminiStreamJson(stdout)
+                : outputFormat === "json"
+                    ? parseGeminiJson(stdout)
+                    : null;
+            const out = { absentFields: [] };
+            if (parsed?.sessionId)
+                out.sessionId = parsed.sessionId;
+            if (parsed?.stopReason)
+                out.stopReason = parsed.stopReason;
+            if (!out.sessionId)
+                out.absentFields.push("sessionId");
+            if (!out.stopReason)
+                out.absentFields.push("stopReason");
+            return out;
+        }
+        case "grok": {
+            const parsed = parseGrokOutput(outputFormat, stdout);
+            const out = { absentFields: ["usage"] };
+            if (parsed?.sessionId)
+                out.sessionId = parsed.sessionId;
+            if (parsed?.stopReason)
+                out.stopReason = parsed.stopReason;
+            if (!out.sessionId)
+                out.absentFields.push("sessionId");
+            if (!out.stopReason)
+                out.absentFields.push("stopReason");
+            return out;
+        }
+        case "mistral":
+            return { absentFields: ["sessionId", "stopReason"] };
+        default:
+            return { absentFields: ["sessionId", "stopReason"] };
+    }
+}

package/dist/provider-schema-builder.d.ts

@@ -0,0 +1,22 @@
+import type { CliType } from "./provider-definitions.js";
+import type { DiscoveredCapabilitySet } from "./provider-capability-discovery.js";
+import { type DiscoveredUnmapped, type ParsedArgvPlacement, type ParsedFlagSafety } from "./provider-help-parser.js";
+export type RequestFieldZodType = "boolean" | "string" | "number" | "enum" | "string-array";
+export interface RequestFieldDescriptor {
+    readonly name: string;
+    readonly flag: string;
+    readonly aliases: readonly string[];
+    readonly zodType: RequestFieldZodType;
+    readonly enumValues: readonly string[];
+    readonly repeatable: boolean;
+    readonly argvPlacement: ParsedArgvPlacement;
+    readonly safety: ParsedFlagSafety;
+    readonly description: string;
+}
+export interface ProviderSchemaProjection {
+    readonly providerId: CliType;
+    readonly fields: readonly RequestFieldDescriptor[];
+    readonly discoveredUnmapped: readonly DiscoveredUnmapped[];
+}
+export declare function flagToFieldName(flag: string): string;
+export declare function buildProviderSchema(set: DiscoveredCapabilitySet): ProviderSchemaProjection;

package/dist/provider-schema-builder.js

@@ -0,0 +1,55 @@
+import { checksumText, } from "./provider-help-parser.js";
+export function flagToFieldName(flag) {
+    const stripped = flag.replace(/^-+/, "");
+    return stripped
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map((part, index) => (index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+        .join("");
+}
+function zodTypeForFlag(flag) {
+    if (flag.arity === "none")
+        return "boolean";
+    if (flag.valueType === "unknown")
+        return null;
+    if (flag.valueType === "enum")
+        return flag.arity === "many" ? "string-array" : "enum";
+    if (flag.arity === "many" || flag.repeatable)
+        return "string-array";
+    if (flag.valueType === "number")
+        return "number";
+    return "string";
+}
+export function buildProviderSchema(set) {
+    const fields = [];
+    const unmapped = [...set.discoveredUnmapped];
+    const seen = new Set();
+    for (const flag of set.rootHelp.flags) {
+        const zodType = zodTypeForFlag(flag);
+        if (zodType === null) {
+            unmapped.push({
+                kind: "flag",
+                raw: `${flag.name} ${flag.description}`.trim(),
+                checksum: checksumText(`${flag.name} ${flag.description}`.trim()),
+                reason: "flag takes a value but its type could not be inferred (arity/type/safety incomplete); exposed as discovered-unmapped rather than a request field",
+            });
+            continue;
+        }
+        const name = flagToFieldName(flag.name);
+        if (name.length === 0 || seen.has(name))
+            continue;
+        seen.add(name);
+        fields.push({
+            name,
+            flag: flag.name,
+            aliases: flag.aliases,
+            zodType,
+            enumValues: flag.enumValues,
+            repeatable: flag.repeatable,
+            argvPlacement: flag.argvPlacement,
+            safety: flag.safety,
+            description: flag.description,
+        });
+    }
+    return { providerId: set.providerId, fields, discoveredUnmapped: unmapped };
+}