llm-cli-gateway 2.13.2 → 2.14.0

package/dist/provider-definition-assertions.js

@@ -0,0 +1,147 @@
+import { CLI_TYPES } from "./provider-types.js";
+import { adminSurfaceKind, getAllProviderDefinitions, getProviderDefinition, } from "./provider-definitions.js";
+export function assertNever(x, context = "provider") {
+    throw new Error(`Unhandled ${context}: ${JSON.stringify(x)}`);
+}
+export function providerScopeLabel(id) {
+    switch (id) {
+        case "claude":
+        case "codex":
+        case "gemini":
+        case "grok":
+        case "mistral":
+        case "devin":
+            return "full";
+        case "cursor":
+            return "maintain-only";
+        default:
+            return assertNever(id, "CliType");
+    }
+}
+export const REQUIRED_PROVIDER_PROJECTIONS = [
+    "syncRequestTool",
+    "asyncRequestTool",
+    "modelsResource",
+    "sessionsResource",
+    "modelDiscovery",
+    "sessionContinuity",
+    "capabilityRow",
+    "adminDescriptor",
+    "upstreamContractRow",
+    "docsSummary",
+];
+export function assertExhaustiveProviderCoverage(defs = getAllProviderDefinitions()) {
+    const seen = new Map();
+    for (const def of defs) {
+        seen.set(def.id, (seen.get(def.id) ?? 0) + 1);
+    }
+    const missing = CLI_TYPES.filter(id => !seen.has(id));
+    if (missing.length > 0) {
+        throw new Error(`Provider definitions missing for CLI_TYPES member(s): ${missing.join(", ")}`);
+    }
+    const duplicates = [...seen.entries()].filter(([, count]) => count > 1).map(([id]) => id);
+    if (duplicates.length > 0) {
+        throw new Error(`Duplicate provider definition(s): ${duplicates.join(", ")}`);
+    }
+    const extra = [...seen.keys()].filter(id => !CLI_TYPES.includes(id));
+    if (extra.length > 0) {
+        throw new Error(`Provider definition(s) not in CLI_TYPES: ${extra.join(", ")}`);
+    }
+    for (const id of CLI_TYPES) {
+        if (getProviderDefinition(id).id !== id) {
+            throw new Error(`Provider definition key/id mismatch for ${id}`);
+        }
+    }
+}
+export function assertProviderProjectionsProducible(def) {
+    const producible = new Set();
+    const fail = (projection, reason) => {
+        throw new Error(`Provider "${def.id}" cannot produce ${projection}: ${reason}`);
+    };
+    if (!def.requestSurface.sync || !def.requestSurface.syncToolName.endsWith("_request")) {
+        fail("syncRequestTool", "requestSurface.sync must be true with a *_request tool name");
+    }
+    producible.add("syncRequestTool");
+    if (!def.requestSurface.async || !def.requestSurface.asyncToolName.endsWith("_request_async")) {
+        fail("asyncRequestTool", "requestSurface.async must be true with a *_request_async tool name");
+    }
+    producible.add("asyncRequestTool");
+    if (!def.resourcePolicy.exposesModelsResource) {
+        fail("modelsResource", "resourcePolicy.exposesModelsResource must be true");
+    }
+    producible.add("modelsResource");
+    if (!def.resourcePolicy.exposesSessionsResource) {
+        fail("sessionsResource", "resourcePolicy.exposesSessionsResource must be true");
+    }
+    producible.add("sessionsResource");
+    const md = def.discovery.modelDiscovery;
+    if (md.evidence.trim().length === 0) {
+        fail("modelDiscovery", "modelDiscovery.evidence is required");
+    }
+    if (md.strategy === "native-command") {
+        if (md.argv.length === 0) {
+            fail("modelDiscovery", "native-command strategy requires a non-empty argv");
+        }
+        if (md.parse === "config-or-env" || md.parse === "curated-catalog") {
+            fail("modelDiscovery", "native-command strategy requires a native parse dialect");
+        }
+    }
+    else if (md.argv.length !== 0) {
+        fail("modelDiscovery", "non-native strategy must have an empty argv");
+    }
+    producible.add("modelDiscovery");
+    if (def.discovery.sessionContinuity.flags.length === 0) {
+        fail("sessionContinuity", "at least one continuity flag is required");
+    }
+    producible.add("sessionContinuity");
+    if (def.displayName.trim().length === 0 || def.executables.length === 0) {
+        fail("capabilityRow", "displayName and at least one executable are required");
+    }
+    if (def.primaryExecutable !== def.executables[0]) {
+        fail("capabilityRow", "primaryExecutable must equal executables[0]");
+    }
+    producible.add("capabilityRow");
+    if (!Array.isArray(def.adminSubcommands)) {
+        fail("adminDescriptor", "adminSubcommands must be an array");
+    }
+    for (const family of def.adminSubcommands) {
+        if (adminSurfaceKind(family) === "config-projection" && family.safety !== "read-only") {
+            fail("adminDescriptor", `config-projection family "${family.family}" must be read-only`);
+        }
+    }
+    producible.add("adminDescriptor");
+    if (def.upstreamContract.targetVersion.trim().length === 0) {
+        fail("upstreamContractRow", "upstreamContract.targetVersion is required");
+    }
+    producible.add("upstreamContractRow");
+    if (def.docs.primary.length === 0) {
+        fail("docsSummary", "at least one primary docs URL is required");
+    }
+    producible.add("docsSummary");
+    if (def.acp.classification === "native") {
+        if (def.acp.entrypoint === null || def.acp.nativeEntrypoint === null) {
+            fail("capabilityRow", "native ACP classification requires a non-null entrypoint");
+        }
+        if (def.acp.probeArgv.length === 0) {
+            fail("capabilityRow", "native ACP provider must declare a safe (non-live) probe argv");
+        }
+        const liveArgs = (def.acp.entrypoint?.args ?? []).join(" ");
+        for (const probe of def.acp.probeArgv) {
+            if (probe.join(" ") === liveArgs) {
+                fail("capabilityRow", "ACP probe argv must differ from the live entrypoint argv");
+            }
+        }
+    }
+    else {
+        if (def.acp.entrypoint !== null || def.acp.nativeEntrypoint !== null) {
+            fail("capabilityRow", "non-native ACP classification must have a null entrypoint");
+        }
+    }
+    return producible;
+}
+export function assertRegistryIntegrity(defs = getAllProviderDefinitions()) {
+    assertExhaustiveProviderCoverage(defs);
+    for (const def of defs) {
+        assertProviderProjectionsProducible(def);
+    }
+}

package/dist/provider-definitions.d.ts

@@ -0,0 +1,127 @@
+import { CLI_TYPES, type CliType } from "./provider-types.js";
+export { CLI_TYPES, type CliType };
+export type ProviderId = CliType;
+export type RequestTransport = "cli";
+export type AcpClassification = "native" | "none";
+export type AdminSafetyClass = "read-only" | "mutating-gated";
+export type AdminSurfaceKind = "cli-subcommand" | "cli-flag" | "config-projection";
+export type ModelDiscoveryStrategy = "native-command" | "config-inspection" | "env-inspection" | "static-catalog";
+export type CapabilityScope = "full" | "maintain-only";
+export interface ProviderProbe {
+    readonly argv: readonly string[];
+    readonly purpose: "version" | "root-help" | "subcommand-help" | "model-catalog";
+    readonly executable?: string;
+}
+export type ModelCatalogParseFormat = "codex-debug-json" | "grok-models-text" | "agy-models-text" | "config-or-env" | "curated-catalog";
+export type ModelFallbackPolicy = "live-catalog-primary" | "config-active-model" | "cli-owned-surface-only" | "curated-static-catalog";
+export interface ProviderModelConfigSource {
+    readonly kind: "env" | "config-file";
+    readonly keys: readonly string[];
+    readonly path?: string;
+    readonly note: string;
+}
+export interface ProviderModelFacts {
+    readonly effortLevels: readonly string[];
+    readonly supportsFallbackModelChain: boolean;
+    readonly aliases: readonly string[];
+    readonly agentProfiles: readonly string[];
+}
+export interface ProviderModelDiscovery {
+    readonly strategy: ModelDiscoveryStrategy;
+    readonly argv: readonly string[];
+    readonly parse: ModelCatalogParseFormat;
+    readonly fallbackPolicy: ModelFallbackPolicy;
+    readonly configSources: readonly ProviderModelConfigSource[];
+    readonly facts: ProviderModelFacts;
+    readonly evidence: string;
+}
+export interface ProviderSessionContinuity {
+    readonly continue: boolean;
+    readonly resume: boolean;
+    readonly fork: boolean;
+    readonly sessionIdSelection: boolean;
+    readonly flags: readonly string[];
+    readonly evidence: string;
+}
+export interface ProviderDiscovery {
+    readonly version: ProviderProbe;
+    readonly rootHelp: ProviderProbe;
+    readonly subcommandHelp: readonly ProviderProbe[];
+    readonly modelDiscovery: ProviderModelDiscovery;
+    readonly sessionContinuity: ProviderSessionContinuity;
+}
+export interface ProviderAdminFamily {
+    readonly family: string;
+    readonly safety: AdminSafetyClass;
+    readonly kind?: AdminSurfaceKind;
+    readonly evidence: string;
+}
+export declare function adminSurfaceKind(family: ProviderAdminFamily): AdminSurfaceKind;
+export interface ProviderAcpEntrypoint {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface ProviderAcpAgentType {
+    readonly id: string;
+    readonly description: string;
+}
+export declare const DEVIN_ACP_AGENT_TYPES: readonly ["summarizer", "review"];
+export type DevinAcpAgentType = (typeof DEVIN_ACP_AGENT_TYPES)[number];
+export interface ProviderAcpMetadata {
+    readonly classification: AcpClassification;
+    readonly nativeEntrypoint: string | null;
+    readonly entrypoint: ProviderAcpEntrypoint | null;
+    readonly probeArgv: readonly (readonly string[])[];
+    readonly agentTypes?: readonly ProviderAcpAgentType[];
+    readonly evidence: string;
+}
+export interface ProviderSafetyModes {
+    readonly sandbox: boolean;
+    readonly permissionMode: boolean;
+    readonly approvalMode: boolean;
+    readonly trust: boolean;
+    readonly flags: readonly string[];
+}
+export interface ProviderResourcePolicy {
+    readonly exposesModelsResource: boolean;
+    readonly exposesSessionsResource: boolean;
+}
+export interface ProviderUpstreamLinkage {
+    readonly targetVersion: string;
+    readonly helpChecksumRef: string | null;
+}
+export interface ProviderRequestSurface {
+    readonly sync: boolean;
+    readonly async: boolean;
+    readonly transport: RequestTransport;
+    readonly acpCapable: boolean;
+    readonly syncToolName: string;
+    readonly asyncToolName: string;
+}
+export interface ProviderDefinition {
+    readonly id: ProviderId;
+    readonly displayName: string;
+    readonly sessionLabel: string;
+    readonly icon: string;
+    readonly executables: readonly string[];
+    readonly primaryExecutable: string;
+    readonly requestSurface: ProviderRequestSurface;
+    readonly docs: {
+        readonly primary: readonly string[];
+    };
+    readonly discovery: ProviderDiscovery;
+    readonly adminSubcommands: readonly ProviderAdminFamily[];
+    readonly acp: ProviderAcpMetadata;
+    readonly safetyModes: ProviderSafetyModes;
+    readonly outputFormats: readonly string[];
+    readonly streamingFormats: readonly string[];
+    readonly resourcePolicy: ProviderResourcePolicy;
+    readonly upstreamContract: ProviderUpstreamLinkage;
+    readonly capabilityScope: CapabilityScope;
+}
+export declare const PROVIDER_DEFINITIONS_BY_ID: Readonly<Record<CliType, ProviderDefinition>>;
+export declare function getAllProviderDefinitions(): readonly ProviderDefinition[];
+export declare function getProviderDefinition(id: CliType): ProviderDefinition;
+export declare function listProviderIds(): readonly CliType[];
+export declare function getProviderDisplayName(id: CliType): string;
+export declare function getProviderSessionLabel(id: CliType): string;