llm-cli-gateway 2.3.0 → 2.4.0

package/dist/index.js

@@ -12,12 +12,13 @@ import { parseCodexJsonStream } from "./codex-json-parser.js";
 import { parseGeminiJson, parseGeminiStreamJson } from "./gemini-json-parser.js";
 import { parseVibeMetaJson } from "./mistral-meta-json-parser.js";
 import { homedir } from "os";
-import { createSessionManager } from "./session-manager.js";
+import { CLI_TYPES, PROVIDER_TYPES, createSessionManager, } from "./session-manager.js";
 import { createWorktree, createWorktreeSessionCleanupHook, } from "./worktree-manager.js";
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, minStableTokensForModel, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, isXaiProviderEnabled, minStableTokensForModel, } from "./config.js";
+import { createXaiResponse, XaiApiError, } from "./xai-api-provider.js";
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { AsyncJobManager, } from "./async-job-manager.js";
@@ -33,7 +34,7 @@ import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 import { startHttpGateway } from "./http-transport.js";
 import { printDoctorJson } from "./doctor.js";
 import { registerValidationTools } from "./validation-tools.js";
-import { assertUpstreamCliArgs, assertUpstreamCliEnv, buildUpstreamContractReport, } from "./upstream-contracts.js";
+import { assertUpstreamCliArgs, assertUpstreamCliEnv, buildProviderSubcommandsCompactCatalog, buildUpstreamContractReport, getCliSubcommandContract, probeInstalledCliContract, serializeCliSubcommandContract, } from "./upstream-contracts.js";
 import { entrypointFileURL } from "./entrypoint-url.js";
 const logger = {
     info: (message, ...args) => {
@@ -141,31 +142,32 @@ function loadSkills() {
     return skills;
 }
 const loadedSkills = loadSkills();
-export function buildServerInstructions(asyncJobsEnabled) {
+export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled = false) {
     const asyncToolsNote = asyncJobsEnabled ? " | *_request_async (async)" : "";
+    const apiToolsNote = grokApiToolsEnabled ? ", grok_api_request" : "";
     const jobsLine = asyncJobsEnabled ? "Jobs: llm_job_status, llm_job_result, llm_job_cancel\n" : "";
     const deferralLine = asyncJobsEnabled
         ? `- Sync auto-defers at ${SYNC_DEADLINE_MS}ms. Poll deferred jobs via llm_job_status/llm_job_result.`
         : '- Async jobs are DISABLED (persistence.backend = "none"): *_request_async and llm_job_* tools are not registered, and sync requests run to completion (no auto-deferral).';
     return `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request${apiToolsNote} (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
 Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation, list_available_models | job_status/job_result (validation jobs)
 ${jobsLine}Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
-Other: list_models, cli_versions, upstream_contracts (use --probe-installed after CLI upgrades to detect drift), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
+Other: list_models, cli_versions, upstream_contracts, provider_subcommands_* (read-only subcommand contract/drift introspection), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request — sync or async — by correlationId)
 
 Key behaviors:
 ${deferralLine}
 - Sessions: Claude --continue, Gemini --resume, Grok --resume/--continue, Mistral --resume/--continue (current Vibe defaults session logging on; doctor flags explicit session_logging.enabled=false), Codex \`exec resume <ID>\` / \`exec resume --last\` (all real CLI continuity). For Codex, sessionId must be a real Codex UUID (from ~/.codex/sessions/); gateway-generated gw-* IDs are rejected.
 - Approval gates: opt-in via approvalStrategy:"mcp_managed".
-- Upstream drift detection: After upgrading any provider CLI (especially grok), use the upstream_contracts tool with probeInstalled: true (or the CLI command "llm-cli-gateway contracts --json --probe-installed"). This is the primary reliable way to detect when an installed binary has gained or lost flags compared to the gateway's declared contract. The probe is safe and read-only.
+- Upstream drift detection: After upgrading any provider CLI (especially grok), use upstream_contracts with probeInstalled:true and provider_subcommand_drift for declared subcommand help surfaces. Probes are safe, read-only --help checks.
 - Idle timeout kills stuck processes (default 10min, configurable via idleTimeoutMs).
 
 Skills (full docs via MCP resources):
 ${loadedSkills.map(s => `- skills://${s.name} — ${s.description}`).join("\n")}`;
 }
-function newGatewayMcpServer(asyncJobsEnabled = true) {
-    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: buildServerInstructions(asyncJobsEnabled) });
+function newGatewayMcpServer(asyncJobsEnabled = true, grokApiToolsEnabled = false) {
+    return new McpServer({ name: "llm-cli-gateway", version: packageVersion() }, { instructions: buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled) });
 }
 let sessionManager;
 let db = null;
@@ -174,6 +176,7 @@ let resourceProvider;
 let flightRecorder = null;
 let persistenceConfig = null;
 let cacheAwarenessConfig = null;
+let providersConfig = null;
 let jobStore = null;
 let jobStoreInitialized = false;
 let asyncJobManager = null;
@@ -190,6 +193,10 @@ function getCacheAwarenessConfig(runtimeLogger = logger) {
     cacheAwarenessConfig ??= loadCacheAwarenessConfig(runtimeLogger);
     return cacheAwarenessConfig;
 }
+function getProvidersConfig(runtimeLogger = logger) {
+    providersConfig ??= loadProvidersConfig(runtimeLogger);
+    return providersConfig;
+}
 function getJobStore(runtimeLogger = logger) {
     if (jobStoreInitialized)
         return jobStore;
@@ -217,6 +224,7 @@ function getApprovalManager(runtimeLogger = logger) {
     return approvalManager;
 }
 const MCP_SERVER_ENUM = z.enum(CLAUDE_MCP_SERVER_NAMES);
+const CLI_TYPE_ENUM = z.enum(CLI_TYPES);
 export const MAX_TURNS_SCHEMA = z.number().int().positive().safe().max(10_000);
 export const MAX_TOKENS_SCHEMA = z.number().int().positive().safe().max(100_000_000);
 export const MAX_PRICE_SCHEMA = z.number().positive().finite().min(1e-6).max(10_000);
@@ -244,7 +252,7 @@ export const WORKTREE_SCHEMA = z
     "path. NOTE: callers should `.gitignore` the `.worktrees/` " +
     "directory in their repo (the gateway does NOT auto-gitignore — " +
     "see slice λ spec Q4).");
-export const SESSION_PROVIDER_VALUES = ["claude", "codex", "gemini", "grok", "mistral"];
+export const SESSION_PROVIDER_VALUES = PROVIDER_TYPES;
 export const SESSION_PROVIDER_ENUM = z.enum(SESSION_PROVIDER_VALUES);
 let activeServer = null;
 let activeHttpGateway = null;
@@ -277,8 +285,12 @@ export function resolveGatewayServerRuntime(deps = {}, options = {}) {
         logger: runtimeLogger,
         persistence: deps.persistence ?? getPersistenceConfig(runtimeLogger),
         cacheAwareness: deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger),
+        providers: deps.providers ?? getProvidersConfig(runtimeLogger),
     };
 }
+export function shouldRegisterGrokApiTools(providers) {
+    return isXaiProviderEnabled(providers);
+}
 const CLI_IDLE_TIMEOUTS = {
     claude: 600_000,
     codex: 600_000,
@@ -741,12 +753,12 @@ function registerBaseResources(server, runtime) {
         const contents = await runtime.resourceProvider.readResource(uri.href);
         return { contents: contents ? [contents] : [] };
     });
-    server.registerResource("cache-state-global", "cache_state://global", {
+    server.registerResource("cache-state-global", "cache-state://global", {
         title: "💾 Cache State (Global)",
         description: "Aggregate cache hit/miss/savings across all CLIs in the flight recorder. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
     }, async (uri) => {
-        runtime.logger.debug("Reading cache_state://global resource");
+        runtime.logger.debug("Reading cache-state://global resource");
         const stats = runtime.resourceProvider.readCacheStateGlobal({
             lastNHours: 24,
         });
@@ -760,7 +772,7 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
-    server.registerResource("cache-state-session", new ResourceTemplate("cache_state://session/{sessionId}", { list: undefined }), {
+    server.registerResource("cache-state-session", new ResourceTemplate("cache-state://session/{sessionId}", { list: undefined }), {
         title: "💾 Cache State (Session)",
         description: "Per-session cache hit/miss/savings. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
@@ -768,7 +780,7 @@ function registerBaseResources(server, runtime) {
         const sessionId = Array.isArray(variables.sessionId)
             ? variables.sessionId[0]
             : variables.sessionId;
-        runtime.logger.debug(`Reading cache_state://session/${sessionId}`);
+        runtime.logger.debug(`Reading cache-state://session/${sessionId}`);
         const stats = runtime.resourceProvider.readCacheStateSession(String(sessionId));
         return {
             contents: [
@@ -780,13 +792,13 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
-    server.registerResource("cache-state-prefix", new ResourceTemplate("cache_state://prefix/{hash}", { list: undefined }), {
+    server.registerResource("cache-state-prefix", new ResourceTemplate("cache-state://prefix/{hash}", { list: undefined }), {
         title: "💾 Cache State (Prefix)",
         description: "Per-stable-prefix-hash cache hit/miss/savings, with CLI breakdown. Tokens/hashes only — no prompt text.",
         mimeType: "application/json",
     }, async (uri, variables) => {
         const hash = Array.isArray(variables.hash) ? variables.hash[0] : variables.hash;
-        runtime.logger.debug(`Reading cache_state://prefix/${hash}`);
+        runtime.logger.debug(`Reading cache-state://prefix/${hash}`);
         const stats = runtime.resourceProvider.readCacheStateForPrefix(String(hash));
         return {
             contents: [
@@ -798,6 +810,30 @@ function registerBaseResources(server, runtime) {
             ],
         };
     });
+    server.registerResource("provider-subcommands-catalog", "provider-subcommands://catalog", {
+        title: "Provider Subcommands Catalog",
+        description: "Compact read-only catalog of declared provider CLI subcommands",
+        mimeType: "application/json",
+    }, async (uri) => {
+        runtime.logger.debug("Reading provider-subcommands://catalog resource");
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
+    server.registerResource("provider-subcommand-contract", new ResourceTemplate("provider-subcommands://{provider}/{+commandPath}", { list: undefined }), {
+        title: "Provider Subcommand Contract",
+        description: "Detailed read-only contract for one declared provider CLI subcommand",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const provider = Array.isArray(variables.provider)
+            ? variables.provider[0]
+            : variables.provider;
+        const commandPath = Array.isArray(variables.commandPath)
+            ? variables.commandPath[0]
+            : variables.commandPath;
+        runtime.logger.debug(`Reading provider-subcommands://${provider}/${commandPath}`);
+        const contents = await runtime.resourceProvider.readResource(uri.href);
+        return { contents: contents ? [contents] : [] };
+    });
 }
 function resolvePromptOrPartsForPrep(args) {
     const hasPrompt = typeof args.prompt === "string" && args.prompt.length > 0;
@@ -1676,6 +1712,271 @@ function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep
     }
     return response;
 }
+function buildXaiPromptPartsUserContent(promptParts) {
+    const userSections = [];
+    if (promptParts.tools && promptParts.tools.length > 0) {
+        userSections.push(`<tools>\n${promptParts.tools}\n</tools>`);
+    }
+    if (promptParts.context && promptParts.context.length > 0) {
+        userSections.push(`<context>\n${promptParts.context}\n</context>`);
+    }
+    if (promptParts.task && promptParts.task.length > 0) {
+        userSections.push(promptParts.task);
+    }
+    return userSections.join("\n\n");
+}
+function buildXaiPromptPartsEffectivePrompt(instructions, userContent) {
+    return instructions && instructions.length > 0
+        ? `${instructions}\n\n${userContent}`
+        : userContent;
+}
+function prepareGrokApiRequest(params, providers) {
+    const corrId = params.correlationId || randomUUID();
+    if (!providers.xai) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("[providers.xai] is not configured"));
+    }
+    const inputResolution = resolvePromptOrPartsForPrep({
+        prompt: params.prompt,
+        promptParts: params.promptParts,
+        operation: "grok_api_request",
+        correlationId: corrId,
+    });
+    if (!inputResolution.ok)
+        return inputResolution.error;
+    const instructions = params.promptParts?.system && params.promptParts.system.length > 0
+        ? params.promptParts.system
+        : undefined;
+    let effectivePrompt = inputResolution.assembledPrompt;
+    let input;
+    if (params.promptParts) {
+        let userContent = buildXaiPromptPartsUserContent(params.promptParts);
+        if (params.optimizePrompt) {
+            const optimized = optimizePromptText(userContent);
+            logOptimizationTokens("prompt", corrId, userContent, optimized);
+            userContent = optimized;
+        }
+        effectivePrompt = buildXaiPromptPartsEffectivePrompt(instructions, userContent);
+        input = [{ role: "user", content: userContent }];
+    }
+    else {
+        if (params.optimizePrompt) {
+            const optimized = optimizePromptText(effectivePrompt);
+            logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
+            effectivePrompt = optimized;
+        }
+        input = effectivePrompt;
+    }
+    const resolvedModel = params.model ?? providers.xai.defaultModel;
+    if (params.reasoningEffort && !/^grok-4\.3(?:$|[-.])/.test(resolvedModel)) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("reasoningEffort is currently supported only for xAI model grok-4.3"));
+    }
+    return {
+        corrId,
+        effectivePrompt,
+        resolvedModel,
+        instructions,
+        input,
+        stablePrefixHash: inputResolution.stablePrefixHash,
+        stablePrefixTokens: inputResolution.stablePrefixTokens,
+    };
+}
+function usageFromXaiResult(result) {
+    return {
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        cacheReadTokens: result.usage.cacheReadTokens,
+        costUsd: result.usage.costUsd,
+    };
+}
+async function getExistingSessionForProvider(sessionManager, sessionId, provider) {
+    if (!sessionId)
+        return null;
+    const existing = await sessionManager.getSession(sessionId);
+    if (existing && existing.cli !== provider) {
+        throw new Error(`Session ${sessionId} belongs to provider '${existing.cli}', not '${provider}'`);
+    }
+    return existing;
+}
+function asXaiApiError(error) {
+    if (error instanceof XaiApiError)
+        return error;
+    const cause = error?.cause;
+    return cause instanceof XaiApiError ? cause : null;
+}
+function buildGrokApiToolResponse(args) {
+    let text = args.result.text;
+    if (args.optimizeResponse) {
+        const optimized = optimizeResponseText(text);
+        logOptimizationTokens("response", args.corrId, text, optimized);
+        text = optimized;
+    }
+    const response = {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            provider: "grok-api",
+            cli: "grok-api",
+            model: args.result.model || args.prep.resolvedModel,
+            correlationId: args.corrId,
+            sessionId: args.sessionId || null,
+            responseId: args.result.responseId,
+            previousResponseId: args.previousResponseId || null,
+            stalePreviousResponseCleared: args.stalePreviousResponseCleared,
+            status: args.result.status,
+            httpStatus: args.result.httpStatus,
+            durationMs: args.durationMs,
+            ...usageFromXaiResult(args.result),
+            exitCode: 0,
+            retryCount: 0,
+        },
+    };
+    if (args.sessionId)
+        response.sessionId = args.sessionId;
+    return response;
+}
+async function resolveGrokApiSession(params, runtime) {
+    if (params.sessionId) {
+        const existing = await getExistingSessionForProvider(runtime.sessionManager, params.sessionId, "grok-api");
+        const session = existing ??
+            (await runtime.sessionManager.createSession("grok-api", "Grok API Session", params.sessionId));
+        const previous = !params.createNewSession && typeof session.metadata?.xaiPreviousResponseId === "string"
+            ? session.metadata.xaiPreviousResponseId
+            : undefined;
+        return { sessionId: session.id, previousResponseId: previous };
+    }
+    if (!params.createNewSession) {
+        const active = await runtime.sessionManager.getActiveSession("grok-api");
+        if (active) {
+            const previous = typeof active.metadata?.xaiPreviousResponseId === "string"
+                ? active.metadata.xaiPreviousResponseId
+                : undefined;
+            return { sessionId: active.id, previousResponseId: previous };
+        }
+    }
+    const session = await runtime.sessionManager.createSession("grok-api", "Grok API Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+    return { sessionId: session.id };
+}
+export async function handleGrokApiRequest(deps, params) {
+    const runtime = resolveHandlerRuntime(deps);
+    const startTime = Date.now();
+    const prep = prepareGrokApiRequest(params, runtime.providers);
+    if ("content" in prep)
+        return prep;
+    const { corrId } = prep;
+    const xaiConfig = runtime.providers.xai;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    try {
+        await getExistingSessionForProvider(runtime.sessionManager, params.sessionId, "grok-api");
+    }
+    catch (err) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, err);
+    }
+    if (!xaiConfig) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error("[providers.xai] is not configured"));
+    }
+    const apiKey = process.env[xaiConfig.apiKeyEnv]?.trim();
+    if (!apiKey) {
+        return createErrorResponse("grok_api_request", 1, "", corrId, new Error(`xAI API key env var ${xaiConfig.apiKeyEnv} is not set`));
+    }
+    safeFlightStart({
+        correlationId: corrId,
+        cli: "grok-api",
+        model: prep.resolvedModel,
+        prompt: prep.effectivePrompt,
+        sessionId: params.sessionId,
+        stablePrefixHash: prep.stablePrefixHash ?? undefined,
+        stablePrefixTokens: prep.stablePrefixTokens ?? undefined,
+    }, runtime);
+    let sessionId;
+    let previousResponseId;
+    let stalePreviousResponseCleared = false;
+    try {
+        const session = await resolveGrokApiSession(params, runtime);
+        sessionId = session.sessionId;
+        previousResponseId = session.previousResponseId;
+        const call = (prev) => createXaiResponse({
+            baseUrl: xaiConfig.baseUrl,
+            apiKey,
+            model: prep.resolvedModel,
+            input: prep.input,
+            instructions: prep.instructions,
+            previousResponseId: prev,
+            maxOutputTokens: params.maxOutputTokens,
+            temperature: params.temperature,
+            topP: params.topP,
+            reasoningEffort: params.reasoningEffort,
+            timeoutMs: params.timeoutMs,
+        }, runtime.logger);
+        let result;
+        try {
+            result = await call(previousResponseId);
+        }
+        catch (error) {
+            const xaiError = asXaiApiError(error);
+            if (xaiError?.status === 404 && previousResponseId) {
+                runtime.logger.warn(`[${corrId}] xAI previous_response_id was rejected; clearing stale session metadata and retrying fresh`);
+                await runtime.sessionManager.updateSessionMetadata(sessionId, {
+                    xaiPreviousResponseId: null,
+                    xaiResponseCreatedAt: null,
+                });
+                stalePreviousResponseCleared = true;
+                previousResponseId = undefined;
+                result = await call(undefined);
+            }
+            else {
+                throw error;
+            }
+        }
+        durationMs = Math.max(0, Date.now() - startTime);
+        wasSuccessful = true;
+        await runtime.sessionManager.updateSessionMetadata(sessionId, {
+            xaiPreviousResponseId: result.responseId,
+            xaiResponseCreatedAt: new Date().toISOString(),
+            xaiModel: result.model || prep.resolvedModel,
+        });
+        await runtime.sessionManager.updateSessionUsage(sessionId);
+        safeFlightComplete(corrId, {
+            response: result.text,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: params.optimizePrompt || (params.optimizeResponse ?? false),
+            exitCode: 0,
+            status: "completed",
+            ...usageFromXaiResult(result),
+        }, runtime);
+        return buildGrokApiToolResponse({
+            result,
+            prep,
+            corrId,
+            durationMs,
+            sessionId,
+            previousResponseId,
+            stalePreviousResponseCleared,
+            optimizeResponse: params.optimizeResponse ?? false,
+        });
+    }
+    catch (error) {
+        durationMs = Math.max(0, Date.now() - startTime);
+        const err = error;
+        const xaiError = asXaiApiError(error);
+        runtime.logger.error(`[${corrId}] grok_api_request failed`, err.message);
+        safeFlightComplete(corrId, {
+            response: xaiError?.responseText ?? "",
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: false,
+            exitCode: 1,
+            errorMessage: err.message,
+            status: "failed",
+        }, runtime);
+        return createErrorResponse("grok_api_request", 1, "", corrId, err);
+    }
+    finally {
+        runtime.performanceMetrics.recordRequest("grok-api", durationMs || Math.max(0, Date.now() - startTime), wasSuccessful);
+    }
+}
 function maybeBuildCacheTtlWarning(args) {
     if (args.cli !== "claude")
         return null;
@@ -1762,9 +2063,12 @@ export async function handleGeminiRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionPlan.args);
         const userProvidedSession = sessionPlan.resumed;
         const effectiveSessionIdHint = sessionPlan.resumed ? params.sessionId : undefined;
+        if (effectiveSessionIdHint) {
+            await getExistingSessionForProvider(deps.sessionManager, effectiveSessionIdHint, "gemini");
+        }
+        args.push(...sessionPlan.args);
         let worktreeResolution = {};
         try {
             worktreeResolution = await resolveWorktreeForRequest(params.worktree, effectiveSessionIdHint, runtime);
@@ -1887,11 +2191,11 @@ export async function handleGeminiRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionPlan.args);
         let effectiveSessionId = sessionPlan.resumed ? params.sessionId : undefined;
+        const existingSession = await getExistingSessionForProvider(deps.sessionManager, effectiveSessionId, "gemini");
+        args.push(...sessionPlan.args);
         if (effectiveSessionId) {
-            const existing = await deps.sessionManager.getSession(effectiveSessionId);
-            if (!existing) {
+            if (!existingSession) {
                 try {
                     await deps.sessionManager.createSession("gemini", "Gemini Session", effectiveSessionId);
                 }
@@ -2012,6 +2316,9 @@ export async function handleGrokRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "grok");
+        }
         args.push(...sessionResult.resumeArgs);
         let worktreeResolution = {};
         try {
@@ -2158,6 +2465,9 @@ export async function handleGrokRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "grok");
+        }
         args.push(...sessionResult.resumeArgs);
         let effectiveSessionId = sessionResult.effectiveSessionId;
         if (sessionResult.userProvidedSession && effectiveSessionId) {
@@ -2262,6 +2572,9 @@ export async function handleMistralRequest(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "mistral");
+        }
         args.push(...sessionResult.resumeArgs);
         let worktreeResolution = {};
         try {
@@ -2397,11 +2710,11 @@ export async function handleMistralRequestAsync(deps, params) {
             resumeLatest: params.resumeLatest,
             createNewSession: params.createNewSession,
         });
-        args.push(...sessionResult.resumeArgs);
         let effectiveSessionId = sessionResult.effectiveSessionId;
+        const existingSession = await getExistingSessionForProvider(deps.sessionManager, sessionResult.userProvidedSession ? effectiveSessionId : undefined, "mistral");
+        args.push(...sessionResult.resumeArgs);
         if (sessionResult.userProvidedSession && effectiveSessionId) {
-            const existing = await deps.sessionManager.getSession(effectiveSessionId);
-            if (!existing) {
+            if (!existingSession) {
                 try {
                     await deps.sessionManager.createSession("mistral", "Mistral Session", effectiveSessionId);
                 }
@@ -2458,6 +2771,12 @@ export async function handleMistralRequestAsync(deps, params) {
 }
 export async function handleCodexRequestAsync(deps, params) {
     const runtime = resolveHandlerRuntime(deps);
+    try {
+        await getExistingSessionForProvider(deps.sessionManager, params.sessionId, "codex");
+    }
+    catch (err) {
+        return createErrorResponse("codex_request_async", 1, "", params.correlationId, err);
+    }
     const prep = prepareCodexRequest({
         prompt: params.prompt,
         promptParts: params.promptParts,
@@ -2572,13 +2891,89 @@ export async function handleCodexRequestAsync(deps, params) {
 }
 export function createGatewayServer(deps = {}) {
     const runtime = resolveGatewayServerRuntime(deps, { isolateState: true });
-    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, flightRecorder, cacheAwareness, } = runtime;
+    const { sessionManager, asyncJobManager, approvalManager, performanceMetrics, logger, persistence, flightRecorder, cacheAwareness, providers, } = runtime;
     void flightRecorder;
     void cacheAwareness;
+    const grokApiToolsEnabled = shouldRegisterGrokApiTools(providers);
     const asyncJobsEnabled = persistence.backend !== "none" && persistence.asyncJobsEnabled && asyncJobManager.hasStore();
-    const server = newGatewayMcpServer(asyncJobsEnabled);
+    const server = newGatewayMcpServer(asyncJobsEnabled, grokApiToolsEnabled);
     registerBaseResources(server, runtime);
     registerValidationTools(server, { asyncJobManager });
+    if (grokApiToolsEnabled) {
+        server.tool("grok_api_request", "Run an xAI Grok API request synchronously through the Responses API. Requires exactly one of prompt or promptParts. Registered only when [providers.xai] is configured and its API-key env var is present.", {
+            prompt: z
+                .string()
+                .min(1, "Prompt cannot be empty")
+                .max(100000, "Prompt too long (max 100k chars)")
+                .optional()
+                .describe("Prompt text for xAI Grok API (mutually exclusive with promptParts)"),
+            promptParts: PromptPartsSchema.optional().describe("Cache-aware structured prompt: { system?, tools?, context?, task }. Mutually exclusive with prompt. The stable prefix hash is logged for cache_state aggregates; xAI does not receive cache_control hints."),
+            model: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("xAI model id; defaults to [providers.xai].default_model"),
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Gateway grok-api session to continue. The gateway stores xAI previous_response_id in session metadata."),
+            createNewSession: z
+                .boolean()
+                .default(false)
+                .describe("Start a fresh xAI response chain. With sessionId, ignores any stored previous_response_id for this request."),
+            correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
+            optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
+            optimizeResponse: z.boolean().default(false).describe("Optimize response output"),
+            maxOutputTokens: MAX_TOKENS_SCHEMA.optional().describe("xAI Responses API max_output_tokens. Bounded to safe integers <= 100000000."),
+            temperature: z
+                .number()
+                .finite()
+                .min(0)
+                .max(2)
+                .optional()
+                .describe("Sampling temperature passed to xAI Responses API"),
+            topP: z
+                .number()
+                .finite()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("Nucleus sampling top_p passed to xAI Responses API"),
+            reasoningEffort: z
+                .enum(["none", "low", "medium", "high"])
+                .optional()
+                .describe("xAI Responses API reasoning.effort"),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(30_000)
+                .max(3_600_000)
+                .optional()
+                .describe("HTTP request timeout in ms (min 30s, max 1h, default 10m)"),
+        }, {
+            title: "Grok API request",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        }, async ({ prompt, promptParts, model, sessionId, createNewSession, correlationId, optimizePrompt, optimizeResponse, maxOutputTokens, temperature, topP, reasoningEffort, timeoutMs, }) => {
+            return handleGrokApiRequest({ sessionManager, logger, runtime }, {
+                prompt,
+                promptParts,
+                model,
+                sessionId,
+                createNewSession,
+                correlationId,
+                optimizePrompt,
+                optimizeResponse,
+                maxOutputTokens,
+                temperature,
+                topP,
+                reasoningEffort,
+                timeoutMs,
+            });
+        });
+    }
     server.tool("claude_request", "Run a Claude Code CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts.", {
         prompt: z
             .string()
@@ -2783,6 +3178,12 @@ export function createGatewayServer(deps = {}) {
         if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
             useContinue = true;
         }
+        try {
+            await getExistingSessionForProvider(sessionManager, effectiveSessionId, "claude");
+        }
+        catch (err) {
+            return createErrorResponse("claude_request", 1, "", corrId, err);
+        }
         const ttlWarning = maybeBuildCacheTtlWarning({
             runtime,
             sessionId: effectiveSessionId,
@@ -3068,6 +3469,12 @@ export function createGatewayServer(deps = {}) {
         const { corrId, args } = prep;
         let durationMs = 0;
         let wasSuccessful = false;
+        try {
+            await getExistingSessionForProvider(sessionManager, sessionId, "codex");
+        }
+        catch (err) {
+            return createErrorResponse("codex_request", 1, "", corrId, err);
+        }
         safeFlightStart({
             correlationId: corrId,
             cli: "codex",
@@ -3220,6 +3627,12 @@ export function createGatewayServer(deps = {}) {
         if (!sessionId && !forkLast) {
             return createErrorResponse("codex_fork_session", 1, "", corrId, new Error("one of sessionId or forkLast is required"));
         }
+        try {
+            await getExistingSessionForProvider(sessionManager, sessionId, "codex");
+        }
+        catch (err) {
+            return createErrorResponse("codex_fork_session", 1, "", corrId, err);
+        }
         let forkArgs;
         try {
             forkArgs = prepareCodexForkRequest({ prompt, sessionId, forkLast }).args;
@@ -3916,6 +4329,7 @@ export function createGatewayServer(deps = {}) {
                 if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
                     useContinue = true;
                 }
+                const existingSession = await getExistingSessionForProvider(sessionManager, effectiveSessionId, "claude");
                 if (useContinue) {
                     args.push("--continue");
                 }
@@ -3924,7 +4338,6 @@ export function createGatewayServer(deps = {}) {
                     await sessionManager.updateSessionUsage(effectiveSessionId);
                 }
                 if (effectiveSessionId) {
-                    const existingSession = await sessionManager.getSession(effectiveSessionId);
                     if (!existingSession) {
                         await sessionManager.createSession("claude", "Claude Session", effectiveSessionId);
                     }
@@ -4777,11 +5190,33 @@ export function createGatewayServer(deps = {}) {
                 ? null
                 : "Async job persistence is disabled (backend = 'none'). *_request_async tools are NOT registered on this gateway. Set [persistence].backend = 'sqlite' (or 'memory' + acknowledgeEphemeral = true) to enable them.",
         };
+        const outboundProviders = {
+            xai: providers.xai
+                ? {
+                    configured: true,
+                    enabled: isXaiProviderEnabled(providers),
+                    apiKeyEnv: providers.xai.apiKeyEnv,
+                    apiKeyPresent: isXaiProviderEnabled(providers),
+                    baseUrl: providers.xai.baseUrl,
+                    defaultModel: providers.xai.defaultModel,
+                    mode: isXaiProviderEnabled(providers) ? "sync" : "configured-missing-key",
+                }
+                : {
+                    configured: false,
+                    enabled: false,
+                    apiKeyEnv: null,
+                    apiKeyPresent: false,
+                    baseUrl: null,
+                    defaultModel: null,
+                    mode: "disabled",
+                },
+            sources: providers.sources,
+        };
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({ success: true, ...health, persistence: persistenceBlock }, null, 2),
+                    text: JSON.stringify({ success: true, ...health, persistence: persistenceBlock, outboundProviders }, null, 2),
                 },
             ],
         };
@@ -4850,7 +5285,7 @@ export function createGatewayServer(deps = {}) {
     });
     server.tool("upstream_contracts", "Return the gateway's declared provider CLI contracts; with probeInstalled true, diff against installed --help surfaces to detect flag drift.", {
         cli: z
-            .preprocess(value => (value === "" || value === null ? undefined : value), SESSION_PROVIDER_ENUM.optional())
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
             .describe("CLI filter (claude|codex|gemini|grok|mistral)"),
         probeInstalled: z
             .boolean()
@@ -4866,6 +5301,133 @@ export function createGatewayServer(deps = {}) {
         const report = buildUpstreamContractReport({ cli, probeInstalled });
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
     });
+    server.tool("provider_subcommands_list", "Return a compact, filterable read-only catalog of declared provider CLI subcommands without flags or raw help.", {
+        provider: z
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral)"),
+        tier: z
+            .enum(["catalog", "inspect", "execute_candidate", "diagnostic"])
+            .optional()
+            .describe("Optional subcommand tier filter"),
+        risk: z
+            .enum([
+            "read_only",
+            "writes_local_config",
+            "auth",
+            "network",
+            "starts_server",
+            "updates_binary",
+            "destructive",
+            "executes_agent",
+        ])
+            .optional()
+            .describe("Optional risk classification filter"),
+        exposure: z
+            .enum(["tracked_only", "mcp_readonly", "mcp_requires_approval", "not_exposed"])
+            .optional()
+            .describe("Optional MCP exposure filter"),
+        commandPathPrefix: z
+            .array(z.string().min(1))
+            .optional()
+            .describe("Optional command path prefix filter, e.g. ['agent']"),
+    }, {
+        title: "Provider subcommands catalog",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, tier, risk, exposure, commandPathPrefix }) => {
+        const catalog = buildProviderSubcommandsCompactCatalog({
+            provider,
+            tier,
+            risk,
+            exposure,
+            commandPathPrefix,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ...catalog, total: catalog.rows.length }),
+                },
+            ],
+        };
+    });
+    server.tool("provider_subcommand_contract", "Return the detailed read-only contract for exactly one declared provider CLI subcommand.", {
+        provider: CLI_TYPE_ENUM.describe("Provider (claude|codex|gemini|grok|mistral)"),
+        commandPath: z.array(z.string().min(1)).min(1).describe("Command path segments"),
+    }, {
+        title: "Provider subcommand contract",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, commandPath }) => {
+        const contract = getCliSubcommandContract(provider, commandPath);
+        const payload = contract
+            ? {
+                schemaVersion: "provider-subcommand-contract.v1",
+                contract: serializeCliSubcommandContract(provider, contract),
+            }
+            : {
+                schemaVersion: "provider-subcommand-contract.v1",
+                error: `No declared ${provider} subcommand contract for ${commandPath.join(" ")}`,
+            };
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    });
+    server.tool("provider_subcommand_drift", "Probe declared provider subcommand --help surfaces and return compact drift rows without raw help output.", {
+        provider: z
+            .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral)"),
+        includeClean: z
+            .boolean()
+            .default(false)
+            .describe("When false, return only unavailable or drifted command paths"),
+    }, {
+        title: "Provider subcommand drift",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ provider, includeClean }) => {
+        const providers = provider ? [provider] : CLI_TYPES;
+        const rows = providers.flatMap(cli => {
+            const probe = probeInstalledCliContract(cli);
+            return Object.values(probe.subcommands).flatMap(sub => {
+                const drifted = !sub.available || sub.extraFlags.length > 0 || sub.missingFlags.length > 0;
+                if (!includeClean && !drifted)
+                    return [];
+                return [
+                    {
+                        provider: cli,
+                        commandPath: sub.commandPath,
+                        driftStatus: drifted ? "drift" : "clean",
+                        available: sub.available,
+                        extraVsContract: sub.extraFlags,
+                        missingFromBinary: sub.missingFlags,
+                        helpHash: sub.helpHash ?? null,
+                        risk: sub.risk,
+                        exposure: sub.exposure,
+                        tier: sub.tier,
+                        summary: sub.summary,
+                        warnings: sub.warnings,
+                    },
+                ];
+            });
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        schemaVersion: "provider-subcommand-drift.v1",
+                        total: rows.length,
+                        rows,
+                    }),
+                },
+            ],
+        };
+    });
     server.tool("cli_upgrade", "Plan (dryRun, default true) or execute an upgrade for one provider CLI using its native update mechanism.", {
         cli: z.enum(["claude", "codex", "gemini", "grok", "mistral"]).describe("CLI to upgrade"),
         target: z
@@ -4921,8 +5483,8 @@ export function createGatewayServer(deps = {}) {
             };
         }
     });
-    server.tool("session_create", "Create a gateway session record for a provider CLI. NOTE: this is gateway bookkeeping (gw-* ID), not a provider-native session — Codex resume needs a real Codex UUID.", {
-        cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
+    server.tool("session_create", "Create a gateway session record for a provider. NOTE: this is gateway bookkeeping (gw-* ID), not a provider-native session — Codex resume needs a real Codex UUID.", {
+        cli: SESSION_PROVIDER_ENUM.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
         description: z.string().optional().describe("Session description"),
         setAsActive: z.boolean().default(true).describe("Set as active session"),
     }, {
@@ -4960,8 +5522,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_create", 1, "", undefined, error);
         }
     });
-    server.tool("session_list", "List gateway session records and the active session per CLI, optionally filtered by CLI.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+    server.tool("session_list", "List gateway session records and the active session per provider, optionally filtered by provider.", {
+        cli: SESSION_PROVIDER_ENUM.optional().describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
     }, {
         title: "List sessions",
         readOnlyHint: true,
@@ -4971,13 +5533,10 @@ export function createGatewayServer(deps = {}) {
     }, async ({ cli }) => {
         try {
             const sessions = await sessionManager.listSessions(cli);
-            const activeSessions = {
-                claude: await sessionManager.getActiveSession("claude"),
-                codex: await sessionManager.getActiveSession("codex"),
-                gemini: await sessionManager.getActiveSession("gemini"),
-                grok: await sessionManager.getActiveSession("grok"),
-                mistral: await sessionManager.getActiveSession("mistral"),
-            };
+            const activeSessions = Object.fromEntries(await Promise.all(SESSION_PROVIDER_VALUES.map(async (provider) => [
+                provider,
+                await sessionManager.getActiveSession(provider),
+            ])));
             const sessionList = sessions.map(s => ({
                 id: s.id,
                 cli: s.cli,
@@ -4993,13 +5552,10 @@ export function createGatewayServer(deps = {}) {
                         text: JSON.stringify({
                             total: sessionList.length,
                             sessions: sessionList,
-                            activeSessions: {
-                                claude: activeSessions.claude?.id || null,
-                                codex: activeSessions.codex?.id || null,
-                                gemini: activeSessions.gemini?.id || null,
-                                grok: activeSessions.grok?.id || null,
-                                mistral: activeSessions.mistral?.id || null,
-                            },
+                            activeSessions: Object.fromEntries(SESSION_PROVIDER_VALUES.map(provider => [
+                                provider,
+                                activeSessions[provider]?.id || null,
+                            ])),
                         }, null, 2),
                     },
                 ],
@@ -5009,8 +5565,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_list", 1, "", undefined, error);
         }
     });
-    server.tool("session_set_active", "Set or clear the active session for a CLI; the active session is used when a request omits sessionId.", {
-        cli: SESSION_PROVIDER_ENUM.describe("CLI type (claude|codex|gemini|grok|mistral)"),
+    server.tool("session_set_active", "Set or clear the active session for a provider; the active session is used when a request omits sessionId.", {
+        cli: SESSION_PROVIDER_ENUM.describe("Provider type (claude|codex|gemini|grok|mistral|grok-api)"),
         sessionId: z.string().nullable().describe("Session ID (null to clear)"),
     }, {
         title: "Set active session",
@@ -5028,7 +5584,7 @@ export function createGatewayServer(deps = {}) {
                             type: "text",
                             text: JSON.stringify({
                                 success: false,
-                                error: "Session not found or does not belong to the specified CLI",
+                                error: "Session not found or does not belong to the specified provider",
                             }, null, 2),
                         },
                     ],
@@ -5169,8 +5725,8 @@ export function createGatewayServer(deps = {}) {
             return createErrorResponse("session_get", 1, "", undefined, error);
         }
     });
-    server.tool("session_clear_all", "Delete all gateway session records, optionally scoped to one CLI.", {
-        cli: SESSION_PROVIDER_ENUM.optional().describe("CLI filter (claude|codex|gemini|grok|mistral)"),
+    server.tool("session_clear_all", "Delete all gateway session records, optionally scoped to one provider.", {
+        cli: SESSION_PROVIDER_ENUM.optional().describe("Provider filter (claude|codex|gemini|grok|mistral|grok-api)"),
     }, {
         title: "Clear sessions",
         readOnlyHint: false,
@@ -5326,9 +5882,7 @@ async function main() {
     if (args[0] === "contracts") {
         if (args.includes("--json")) {
             const cliArg = args.find(arg => arg.startsWith("--cli="))?.split("=")[1];
-            const cli = SESSION_PROVIDER_VALUES.includes(cliArg)
-                ? cliArg
-                : undefined;
+            const cli = CLI_TYPES.includes(cliArg) ? cliArg : undefined;
             if (cliArg && !cli) {
                 process.stderr.write(`Unsupported --cli value: ${cliArg}\n`);
                 process.exit(2);