llm-cli-gateway 2.3.0 → 2.4.0

package/dist/metrics.d.ts

@@ -1,4 +1,4 @@
-import { type CliType } from "./session-manager.js";
+import { type ProviderType } from "./session-manager.js";
 export interface ToolMetricsSnapshot {
     requestCount: number;
     successCount: number;
@@ -13,11 +13,11 @@ export interface PerformanceMetricsSnapshot {
     totalFailures: number;
     overallSuccessRate: number;
     overallFailureRate: number;
-    byTool: Record<CliType, ToolMetricsSnapshot>;
+    byTool: Record<ProviderType, ToolMetricsSnapshot>;
     generatedAt: string;
 }
 export declare class PerformanceMetrics {
     private metrics;
-    recordRequest(cli: CliType, durationMs: number, success: boolean): void;
+    recordRequest(provider: ProviderType, durationMs: number, success: boolean): void;
     snapshot(): PerformanceMetricsSnapshot;
 }

package/dist/metrics.js

@@ -1,12 +1,12 @@
-import { CLI_TYPES } from "./session-manager.js";
-const createEmptyMetrics = () => Object.fromEntries(CLI_TYPES.map(cli => [
-    cli,
+import { PROVIDER_TYPES } from "./session-manager.js";
+const createEmptyMetrics = () => Object.fromEntries(PROVIDER_TYPES.map(provider => [
+    provider,
     { requestCount: 0, successCount: 0, failureCount: 0, totalResponseTimeMs: 0 },
 ]));
 export class PerformanceMetrics {
     metrics = createEmptyMetrics();
-    recordRequest(cli, durationMs, success) {
-        const metrics = this.metrics[cli];
+    recordRequest(provider, durationMs, success) {
+        const metrics = this.metrics[provider];
         metrics.requestCount += 1;
         const normalizedDurationMs = Number.isFinite(durationMs) ? Math.max(0, durationMs) : 0;
         metrics.totalResponseTimeMs += normalizedDurationMs;
@@ -22,12 +22,12 @@ export class PerformanceMetrics {
         let totalRequests = 0;
         let totalSuccesses = 0;
         let totalFailures = 0;
-        for (const cli of CLI_TYPES) {
-            const metrics = this.metrics[cli];
+        for (const provider of PROVIDER_TYPES) {
+            const metrics = this.metrics[provider];
             const averageResponseTimeMs = metrics.requestCount > 0 ? metrics.totalResponseTimeMs / metrics.requestCount : 0;
             const successRate = metrics.requestCount > 0 ? metrics.successCount / metrics.requestCount : 0;
             const failureRate = metrics.requestCount > 0 ? metrics.failureCount / metrics.requestCount : 0;
-            byTool[cli] = {
+            byTool[provider] = {
                 requestCount: metrics.requestCount,
                 successCount: metrics.successCount,
                 failureCount: metrics.failureCount,

package/dist/request-helpers.d.ts

@@ -98,44 +98,44 @@ export declare const CLAUDE_HIGH_IMPACT_PARAMS_SCHEMA: z.ZodEffects<z.ZodObject<
     effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
     excludeDynamicSystemPromptSections: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    agent?: string | undefined;
     agents?: Record<string, Record<string, unknown>> | undefined;
+    agent?: string | undefined;
     forkSession?: boolean | undefined;
     systemPrompt?: string | undefined;
     appendSystemPrompt?: string | undefined;
     maxBudgetUsd?: number | undefined;
     maxTurns?: number | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    effort?: "medium" | "low" | "high" | "xhigh" | "max" | undefined;
     excludeDynamicSystemPromptSections?: boolean | undefined;
 }, {
-    agent?: string | undefined;
     agents?: Record<string, Record<string, unknown>> | undefined;
+    agent?: string | undefined;
     forkSession?: boolean | undefined;
     systemPrompt?: string | undefined;
     appendSystemPrompt?: string | undefined;
     maxBudgetUsd?: number | undefined;
     maxTurns?: number | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    effort?: "medium" | "low" | "high" | "xhigh" | "max" | undefined;
     excludeDynamicSystemPromptSections?: boolean | undefined;
 }>, {
-    agent?: string | undefined;
     agents?: Record<string, Record<string, unknown>> | undefined;
+    agent?: string | undefined;
     forkSession?: boolean | undefined;
     systemPrompt?: string | undefined;
     appendSystemPrompt?: string | undefined;
     maxBudgetUsd?: number | undefined;
     maxTurns?: number | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    effort?: "medium" | "low" | "high" | "xhigh" | "max" | undefined;
     excludeDynamicSystemPromptSections?: boolean | undefined;
 }, {
-    agent?: string | undefined;
     agents?: Record<string, Record<string, unknown>> | undefined;
+    agent?: string | undefined;
     forkSession?: boolean | undefined;
     systemPrompt?: string | undefined;
     appendSystemPrompt?: string | undefined;
     maxBudgetUsd?: number | undefined;
     maxTurns?: number | undefined;
-    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    effort?: "medium" | "low" | "high" | "xhigh" | "max" | undefined;
     excludeDynamicSystemPromptSections?: boolean | undefined;
 }>;
 export declare const CLAUDE_AGENT_DEFINITION_SCHEMA: z.ZodObject<{

package/dist/resources.js

@@ -1,5 +1,7 @@
+import { CLI_TYPES, PROVIDER_TYPES } from "./session-manager.js";
 import { getAvailableCliInfo } from "./model-registry.js";
 import { computeGlobalCacheStats, computePrefixCacheStats, computeSessionCacheStats, computeTtlRemaining, } from "./cache-stats.js";
+import { buildProviderSubcommandsCompactCatalog, getCliSubcommandContract, serializeCliSubcommandContract, } from "./upstream-contracts.js";
 export class ResourceProvider {
     sessionManager;
     performanceMetrics;
@@ -163,11 +165,26 @@ export class ResourceProvider {
                     priority: 0.9,
                 },
             },
+            {
+                uri: "provider-subcommands://catalog",
+                name: "Provider Subcommands Catalog",
+                title: "Provider Subcommands Catalog",
+                description: "Compact read-only catalog of declared provider CLI subcommands",
+                mimeType: "application/json",
+                annotations: {
+                    audience: ["user", "assistant"],
+                    priority: 0.7,
+                },
+            },
         ];
     }
     async readResource(uri) {
         if (uri === "sessions://all") {
             const sessions = await this.sessionManager.listSessions();
+            const activeSessions = Object.fromEntries(await Promise.all(PROVIDER_TYPES.map(async (provider) => [
+                provider,
+                (await this.sessionManager.getActiveSession(provider))?.id || null,
+            ])));
             return {
                 uri,
                 mimeType: "application/json",
@@ -180,13 +197,7 @@ export class ResourceProvider {
                         createdAt: s.createdAt,
                         lastUsedAt: s.lastUsedAt,
                     })),
-                    activeSessions: {
-                        claude: (await this.sessionManager.getActiveSession("claude"))?.id || null,
-                        codex: (await this.sessionManager.getActiveSession("codex"))?.id || null,
-                        gemini: (await this.sessionManager.getActiveSession("gemini"))?.id || null,
-                        grok: (await this.sessionManager.getActiveSession("grok"))?.id || null,
-                        mistral: (await this.sessionManager.getActiveSession("mistral"))?.id || null,
-                    },
+                    activeSessions,
                 }, null, 2),
             };
         }
@@ -302,6 +313,44 @@ export class ResourceProvider {
                 text: JSON.stringify(this.performanceMetrics.snapshot(), null, 2),
             };
         }
+        if (uri === "provider-subcommands://catalog" || uri === "provider_subcommands://catalog") {
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(buildProviderSubcommandsCompactCatalog()),
+            };
+        }
+        const subcommandResource = parseProviderSubcommandUri(uri);
+        if (subcommandResource) {
+            const contract = getCliSubcommandContract(subcommandResource.provider, subcommandResource.commandPath);
+            if (!contract)
+                return null;
+            return {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    schemaVersion: "provider-subcommand-contract.v1",
+                    contract: serializeCliSubcommandContract(subcommandResource.provider, contract),
+                }, null, 2),
+            };
+        }
         return null;
     }
 }
+function parseProviderSubcommandUri(uri) {
+    const prefix = uri.startsWith("provider-subcommands://")
+        ? "provider-subcommands://"
+        : uri.startsWith("provider_subcommands://")
+            ? "provider_subcommands://"
+            : null;
+    if (!prefix || uri === `${prefix}catalog`)
+        return null;
+    const rest = uri.slice(prefix.length);
+    const [providerRaw, ...pathParts] = rest.split("/");
+    if (!CLI_TYPES.includes(providerRaw) || pathParts.length === 0)
+        return null;
+    return {
+        provider: providerRaw,
+        commandPath: pathParts.map(part => decodeURIComponent(part)).filter(Boolean),
+    };
+}

package/dist/session-manager-pg.d.ts

@@ -1,16 +1,16 @@
 import type { Pool } from "pg";
-import { Session, CliType } from "./session-manager.js";
+import { Session, ProviderType } from "./session-manager.js";
 export type { Logger } from "./logger.js";
 export declare class PostgreSQLSessionManager {
     private pool;
     constructor(pool: Pool);
-    createSession(cli: CliType, description?: string, sessionId?: string): Promise<Session>;
+    createSession(cli: ProviderType, description?: string, sessionId?: string): Promise<Session>;
     getSession(sessionId: string): Promise<Session | null>;
-    listSessions(cli?: CliType): Promise<Session[]>;
+    listSessions(cli?: ProviderType): Promise<Session[]>;
     deleteSession(sessionId: string): Promise<boolean>;
-    setActiveSession(cli: CliType, sessionId: string | null): Promise<boolean>;
-    getActiveSession(cli: CliType): Promise<Session | null>;
+    setActiveSession(cli: ProviderType, sessionId: string | null): Promise<boolean>;
+    getActiveSession(cli: ProviderType): Promise<Session | null>;
     updateSessionUsage(sessionId: string): Promise<void>;
     updateSessionMetadata(sessionId: string, metadata: Record<string, any>): Promise<boolean>;
-    clearAllSessions(cli?: CliType): Promise<number>;
+    clearAllSessions(cli?: ProviderType): Promise<number>;
 }

package/dist/session-manager-pg.js

@@ -5,6 +5,7 @@ const DEFAULT_SESSION_DESCRIPTIONS = {
     gemini: "Gemini Session",
     grok: "Grok Session",
     mistral: "Mistral Session",
+    "grok-api": "Grok API Session",
 };
 export class PostgreSQLSessionManager {
     pool;

package/dist/session-manager.d.ts

@@ -3,9 +3,13 @@ import type { DatabaseConnection } from "./db.js";
 import type { Logger } from "./logger.js";
 export declare const CLI_TYPES: readonly ["claude", "codex", "gemini", "grok", "mistral"];
 export type CliType = (typeof CLI_TYPES)[number];
+export declare const API_PROVIDER_TYPES: readonly ["grok-api"];
+export type ApiProviderType = (typeof API_PROVIDER_TYPES)[number];
+export declare const PROVIDER_TYPES: readonly ["claude", "codex", "gemini", "grok", "mistral", "grok-api"];
+export type ProviderType = (typeof PROVIDER_TYPES)[number];
 export interface Session {
     id: string;
-    cli: CliType;
+    cli: ProviderType;
     createdAt: string;
     lastUsedAt: string;
     description?: string;
@@ -13,7 +17,7 @@ export interface Session {
 }
 export interface SessionStorage {
     sessions: Record<string, Session>;
-    activeSession: Record<CliType, string | null>;
+    activeSession: Record<ProviderType, string | null>;
 }
 export type SessionCleanupHook = (session: Session) => void | Promise<void>;
 export declare class FileSessionManager {
@@ -32,27 +36,27 @@ export declare class FileSessionManager {
     private ensureStorageDirectory;
     private loadStorage;
     private saveStorage;
-    createSession(cli: CliType, description?: string, sessionId?: string): Session;
+    createSession(cli: ProviderType, description?: string, sessionId?: string): Session;
     getSession(sessionId: string): Session | null;
-    listSessions(cli?: CliType): Session[];
+    listSessions(cli?: ProviderType): Session[];
     deleteSession(sessionId: string): boolean;
-    setActiveSession(cli: CliType, sessionId: string | null): boolean;
-    getActiveSession(cli: CliType): Session | null;
+    setActiveSession(cli: ProviderType, sessionId: string | null): boolean;
+    getActiveSession(cli: ProviderType): Session | null;
     updateSessionUsage(sessionId: string): void;
     updateSessionMetadata(sessionId: string, metadata: Record<string, any>): boolean;
-    clearAllSessions(cli?: CliType): number;
+    clearAllSessions(cli?: ProviderType): number;
 }
 export declare const SessionManager: typeof FileSessionManager;
 export interface ISessionManager {
-    createSession(cli: CliType, description?: string, sessionId?: string): Session | Promise<Session>;
+    createSession(cli: ProviderType, description?: string, sessionId?: string): Session | Promise<Session>;
     getSession(sessionId: string): Session | null | Promise<Session | null>;
-    listSessions(cli?: CliType): Session[] | Promise<Session[]>;
+    listSessions(cli?: ProviderType): Session[] | Promise<Session[]>;
     deleteSession(sessionId: string): boolean | Promise<boolean>;
-    setActiveSession(cli: CliType, sessionId: string | null): boolean | Promise<boolean>;
-    getActiveSession(cli: CliType): Session | null | Promise<Session | null>;
+    setActiveSession(cli: ProviderType, sessionId: string | null): boolean | Promise<boolean>;
+    getActiveSession(cli: ProviderType): Session | null | Promise<Session | null>;
     updateSessionUsage(sessionId: string): void | Promise<void>;
     updateSessionMetadata(sessionId: string, metadata: Record<string, any>): boolean | Promise<boolean>;
-    clearAllSessions(cli?: CliType): number | Promise<number>;
+    clearAllSessions(cli?: ProviderType): number | Promise<number>;
 }
 export declare function createSessionManager(config?: Config, db?: DatabaseConnection, logger?: Logger, opts?: {
     cleanupHook?: SessionCleanupHook;

package/dist/session-manager.js

@@ -5,13 +5,16 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, openSyn
 import { DEFAULT_SESSION_TTL_SECONDS } from "./config.js";
 import { noopLogger } from "./logger.js";
 export const CLI_TYPES = ["claude", "codex", "gemini", "grok", "mistral"];
-const createEmptyActiveSessions = () => Object.fromEntries(CLI_TYPES.map(cli => [cli, null]));
+export const API_PROVIDER_TYPES = ["grok-api"];
+export const PROVIDER_TYPES = [...CLI_TYPES, ...API_PROVIDER_TYPES];
+const createEmptyActiveSessions = () => Object.fromEntries(PROVIDER_TYPES.map(provider => [provider, null]));
 const DEFAULT_SESSION_DESCRIPTIONS = {
     claude: "Claude Session",
     codex: "Codex Session",
     gemini: "Gemini Session",
     grok: "Grok Session",
     mistral: "Mistral Session",
+    "grok-api": "Grok API Session",
 };
 export class FileSessionManager {
     storagePath;

package/dist/upstream-contracts.d.ts

@@ -21,6 +21,7 @@ export interface CliContract {
     upstream: string;
     helpArgs: string[][];
     flags: Record<string, CliFlagContract>;
+    subcommands?: Record<string, CliSubcommandContract>;
     env?: Record<string, CliFlagContract>;
     mcpTools: readonly string[];
     mcpParameters: readonly string[];
@@ -43,6 +44,25 @@ export interface CliContractFixture {
     env?: Record<string, string>;
     expect: "pass" | "fail";
 }
+export type CliSubcommandRisk = "read_only" | "writes_local_config" | "auth" | "network" | "starts_server" | "updates_binary" | "destructive" | "executes_agent";
+export type CliSubcommandExposure = "tracked_only" | "mcp_readonly" | "mcp_requires_approval" | "not_exposed";
+export type CliSubcommandTier = "catalog" | "inspect" | "execute_candidate" | "diagnostic";
+export type CliSubcommandTokenCost = "tiny" | "small" | "medium" | "large";
+export interface CliSubcommandContract {
+    commandPath: readonly string[];
+    helpArgs: readonly string[][];
+    flags: Record<string, CliFlagContract>;
+    maxPositionals: number;
+    acknowledgedUpstreamFlags?: readonly string[];
+    aliases?: readonly string[];
+    children?: Record<string, CliSubcommandContract>;
+    risk: CliSubcommandRisk;
+    exposure: CliSubcommandExposure;
+    tier: CliSubcommandTier;
+    tokenCost: CliSubcommandTokenCost;
+    summary: string;
+    conformanceFixtures: readonly CliContractFixture[];
+}
 export interface ContractViolation {
     cli: CliType;
     arg?: string;
@@ -53,9 +73,55 @@ export interface ContractValidationResult {
     ok: boolean;
     violations: ContractViolation[];
 }
+export interface SubcommandContractValidationResult extends ContractValidationResult {
+    commandPath: readonly string[];
+    risk?: CliSubcommandRisk;
+    exposure?: CliSubcommandExposure;
+    tier?: CliSubcommandTier;
+}
+export interface ProviderSubcommandCatalogRow {
+    provider: CliType;
+    commandPath: readonly string[];
+    aliases: readonly string[];
+    tier: CliSubcommandTier;
+    risk: CliSubcommandRisk;
+    exposure: CliSubcommandExposure;
+    tokenCost: CliSubcommandTokenCost;
+    summary: string;
+    driftStatus: "unknown" | "clean" | "drift";
+    resourceUri: string;
+}
+export interface ProviderSubcommandCompactCatalog {
+    schemaVersion: "provider-subcommands-catalog.v1";
+    columns: readonly [
+        "provider",
+        "commandPath",
+        "aliases",
+        "tier",
+        "risk",
+        "exposure",
+        "tokenCost",
+        "summary",
+        "driftStatus",
+        "resourceUri"
+    ];
+    rows: readonly (readonly string[])[];
+}
 export declare const UPSTREAM_CLI_CONTRACTS: Record<CliType, CliContract>;
 export declare function validateUpstreamCliArgs(cli: CliType, args: readonly string[]): ContractValidationResult;
 export declare function assertUpstreamCliArgs(cli: CliType, args: readonly string[]): void;
+export declare function flattenCliSubcommands(subcommands: Record<string, CliSubcommandContract> | undefined): CliSubcommandContract[];
+export declare function getCliSubcommandContract(cli: CliType, commandPath: readonly string[]): CliSubcommandContract | null;
+export declare function serializeCliSubcommandContract(cli: CliType, contract: CliSubcommandContract): Record<string, unknown>;
+export declare function listProviderSubcommands(options?: {
+    provider?: CliType;
+    tier?: CliSubcommandTier;
+    risk?: CliSubcommandRisk;
+    exposure?: CliSubcommandExposure;
+    commandPathPrefix?: readonly string[];
+}): ProviderSubcommandCatalogRow[];
+export declare function buildProviderSubcommandsCompactCatalog(options?: Parameters<typeof listProviderSubcommands>[0]): ProviderSubcommandCompactCatalog;
+export declare function validateUpstreamCliSubcommandArgs(cli: CliType, commandPath: readonly string[], args: readonly string[]): SubcommandContractValidationResult;
 export declare function validateUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): ContractValidationResult;
 export declare function assertUpstreamCliEnv(cli: CliType, env: Record<string, string> | undefined): void;
 export declare function extractDiscoveredFlags(helpText: string): readonly string[];
@@ -66,6 +132,23 @@ export interface FlagDriftResult {
     warnings: string[];
 }
 export declare function computeFlagDrift(contract: CliContract, helpText: string, discoveredFlags: readonly string[]): FlagDriftResult;
+export declare function computeSubcommandFlagDrift(contract: CliSubcommandContract, executable: string, helpText: string, discoveredFlags: readonly string[]): FlagDriftResult;
+export interface InstalledCliSubcommandProbe {
+    commandPath: readonly string[];
+    checkedHelpCommands: string[][];
+    available: boolean;
+    missingFlags: string[];
+    extraFlags: readonly string[];
+    acknowledgedExtraFlags: readonly string[];
+    discoveredFlags: readonly string[];
+    helpHash?: string;
+    probedAt: string;
+    warnings: string[];
+    risk: CliSubcommandRisk;
+    exposure: CliSubcommandExposure;
+    tier: CliSubcommandTier;
+    summary: string;
+}
 export interface InstalledCliContractProbe {
     cli: CliType;
     executable: string;
@@ -79,6 +162,7 @@ export interface InstalledCliContractProbe {
     discoveredFlags: readonly string[];
     helpHash?: string;
     versionHint?: string;
+    subcommands: Record<string, InstalledCliSubcommandProbe>;
     probedAt: string;
     warnings: string[];
 }