llm-cli-gateway 1.1.0 → 1.4.0

package/dist/index.js

@@ -16,11 +16,13 @@ import { loadConfig } from "./config.js";
 import { checkHealth } from "./health.js";
 import { getCliInfo, resolveModelAlias } from "./model-registry.js";
 import { AsyncJobManager } from "./async-job-manager.js";
+import { JobStore, resolveJobStoreDbPath } from "./job-store.js";
 import { ApprovalManager } from "./approval-manager.js";
 import { checkReviewIntegrity } from "./review-integrity.js";
 import { buildClaudeMcpConfig, CLAUDE_MCP_SERVER_NAMES, } from "./claude-mcp-config.js";
-import { resolveSessionResumeArgs, sanitizeCliArgValues, GATEWAY_SESSION_PREFIX, } from "./request-helpers.js";
+import { resolveSessionResumeArgs, resolveGrokSessionArgs, resolveCodexSessionArgs, sanitizeCliArgValues, GATEWAY_SESSION_PREFIX, } from "./request-helpers.js";
 import { createFlightRecorder } from "./flight-recorder.js";
+import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 // Simple logger that writes to stderr (stdout is used for MCP protocol)
 const logger = {
     info: (message, ...args) => {
@@ -88,14 +90,14 @@ const loadedSkills = loadSkills();
 // system prompt at connection time. Covers key patterns + pointers to L2 resources.
 const SERVER_INSTRUCTIONS = `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request (sync) | *_request_async (async)
+Tools: claude_request, codex_request, gemini_request, grok_request (sync) | *_request_async (async)
 Jobs: llm_job_status, llm_job_result, llm_job_cancel
 Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
-Other: list_models, approval_list, llm_process_health
+Other: list_models, cli_versions, cli_upgrade, approval_list, llm_process_health
 
 Key behaviors:
 - Sync auto-defers at ${SYNC_DEADLINE_MS}ms. Poll deferred jobs via llm_job_status/llm_job_result.
-- Sessions: Claude --continue, Gemini --resume (real CLI continuity). Codex bookkeeping only.
+- Sessions: Claude --continue, Gemini --resume, Grok --resume/--continue, 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".
 - Idle timeout kills stuck processes (default 10min, configurable via idleTimeoutMs).
 
@@ -108,9 +110,26 @@ let db = null;
 const performanceMetrics = new PerformanceMetrics();
 let resourceProvider;
 const flightRecorder = createFlightRecorder(logger);
+// Durable job store: persists every async job to ~/.llm-cli-gateway/logs.db so callers
+// can collect results across long polling gaps and gateway restarts, and so repeated
+// identical requests dedup onto the running/completed job instead of starting over.
+const jobStore = (() => {
+    const dbPath = resolveJobStoreDbPath();
+    if (!dbPath) {
+        logger.info("Durable job store disabled (LLM_GATEWAY_LOGS_DB=none)");
+        return null;
+    }
+    try {
+        return new JobStore(dbPath, logger);
+    }
+    catch (err) {
+        logger.error("Failed to open durable job store; continuing in-memory only", err);
+        return null;
+    }
+})();
 const asyncJobManager = new AsyncJobManager(logger, (cli, durationMs, success) => {
     performanceMetrics.recordRequest(cli, durationMs, success);
-});
+}, jobStore);
 const approvalManager = new ApprovalManager(undefined, logger);
 const MCP_SERVER_ENUM = z.enum(CLAUDE_MCP_SERVER_NAMES);
 // Per-CLI idle timeouts: kill process if no stdout/stderr activity for this duration.
@@ -120,6 +139,7 @@ const CLI_IDLE_TIMEOUTS = {
     claude: 600_000, // 10 minutes — only used when outputFormat=stream-json
     codex: 600_000, // 10 minutes — Codex streams stderr progress
     gemini: 600_000, // 10 minutes — Gemini streams stdout in real-time
+    grok: 600_000, // 10 minutes — Grok streams stderr/stdout activity in headless mode
 };
 function resolveIdleTimeout(cli, override) {
     if (override !== undefined)
@@ -131,12 +151,21 @@ const SYNC_POLL_INTERVAL_MS = 1_000;
  * Start an async job and poll until completion or deadline.
  * Returns the job result if it finishes in time, or a deferral marker.
  */
-async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat) {
+async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, forceRefresh) {
     if (SYNC_DEADLINE_MS === 0) {
-        // Disabled — fall through to direct execution
+        // Disabled — fall through to direct execution.
+        // Note: direct execution bypasses dedup. forceRefresh is implied.
         return executeCli(cli, args, { idleTimeout: idleTimeoutMs, logger });
     }
-    const job = asyncJobManager.startJob(cli, args, corrId, undefined, idleTimeoutMs, outputFormat);
+    const outcome = asyncJobManager.startJobWithDedup(cli, args, corrId, {
+        idleTimeoutMs,
+        outputFormat,
+        forceRefresh,
+    });
+    const job = outcome.snapshot;
+    if (outcome.deduped) {
+        logger.info(`[${corrId}] sync request deduped onto running job ${job.id} (original corrId=${outcome.originalCorrelationId})`);
+    }
     const deadline = Date.now() + SYNC_DEADLINE_MS;
     while (Date.now() < deadline) {
         const snapshot = asyncJobManager.getJobSnapshot(job.id);
@@ -378,6 +407,16 @@ server.registerResource("gemini-sessions", "sessions://gemini", {
     const contents = await resourceProvider.readResource(uri.href);
     return { contents: contents ? [contents] : [] };
 });
+// Register Grok sessions resource
+server.registerResource("grok-sessions", "sessions://grok", {
+    title: "⚡ Grok Sessions",
+    description: "Grok conversation sessions",
+    mimeType: "application/json",
+}, async (uri) => {
+    logger.debug("Reading Grok sessions resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
 // Register Claude models resource
 server.registerResource("claude-models", "models://claude", {
     title: "🧠 Claude Models",
@@ -408,6 +447,16 @@ server.registerResource("gemini-models", "models://gemini", {
     const contents = await resourceProvider.readResource(uri.href);
     return { contents: contents ? [contents] : [] };
 });
+// Register Grok models resource
+server.registerResource("grok-models", "models://grok", {
+    title: "⚡ Grok Models",
+    description: "Grok models and capabilities",
+    mimeType: "application/json",
+}, async (uri) => {
+    logger.debug("Reading Grok models resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
 // Register performance metrics resource
 server.registerResource("performance-metrics", "metrics://performance", {
     title: "📈 Performance Metrics",
@@ -543,15 +592,40 @@ function prepareCodexRequest(params) {
             return createApprovalDeniedResponse(params.operation, approvalDecision);
         }
     }
+    // Resume mode: codex exec resume <SESSION_ID|--last> [flags] PROMPT
+    // Note: `codex exec resume` does NOT accept `--full-auto`; the original
+    // session's approval policy is inherited. We silently drop fullAuto on resume.
+    let sessionPlan;
+    try {
+        sessionPlan = resolveCodexSessionArgs({
+            sessionId: params.sessionId,
+            resumeLatest: params.resumeLatest,
+            createNewSession: params.createNewSession,
+        });
+    }
+    catch (err) {
+        return createErrorResponse(params.operation, 1, "", corrId, err);
+    }
     const args = ["exec"];
+    if (sessionPlan.mode !== "new") {
+        args.push("resume");
+        if (sessionPlan.mode === "resume-latest") {
+            args.push("--last");
+        }
+    }
     if (resolvedModel)
         args.push("--model", resolvedModel);
-    if (params.fullAuto)
+    if (sessionPlan.mode === "new" && params.fullAuto) {
         args.push("--full-auto");
+    }
     if (params.dangerouslyBypassApprovalsAndSandbox) {
         args.push("--dangerously-bypass-approvals-and-sandbox");
     }
-    args.push("--skip-git-repo-check", effectivePrompt);
+    args.push("--skip-git-repo-check");
+    if (sessionPlan.mode === "resume-by-id" && sessionPlan.sessionId) {
+        args.push(sessionPlan.sessionId);
+    }
+    args.push(effectivePrompt);
     return {
         corrId,
         effectivePrompt,
@@ -631,6 +705,81 @@ function prepareGeminiRequest(params) {
         args,
     };
 }
+function prepareGrokRequest(params) {
+    const corrId = params.correlationId || randomUUID();
+    const cliInfo = getCliInfo();
+    const resolvedModel = resolveModelAlias("grok", params.model, cliInfo);
+    // Review integrity check on raw prompt (before optimization)
+    const reviewIntegrity = checkReviewIntegrity({
+        prompt: params.prompt,
+        allowedTools: params.allowedTools,
+        disallowedTools: params.disallowedTools,
+    });
+    if (reviewIntegrity.violations.length > 0) {
+        logger.info(`[${corrId}] Review integrity violations detected: ${reviewIntegrity.violations.map(v => v.type).join(", ")}`, {
+            cli: "grok",
+            operation: params.operation,
+            score: reviewIntegrity.totalScore,
+        });
+    }
+    let effectivePrompt = params.prompt;
+    if (params.optimizePrompt) {
+        const optimized = optimizePromptText(effectivePrompt);
+        logOptimizationTokens("prompt", corrId, effectivePrompt, optimized);
+        effectivePrompt = optimized;
+    }
+    const requestedMcpServers = normalizeMcpServers(params.mcpServers);
+    let approvalDecision = null;
+    if (params.approvalStrategy === "mcp_managed") {
+        approvalDecision = approvalManager.decide({
+            cli: "grok",
+            operation: params.operation,
+            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            bypassRequested: Boolean(params.alwaysApprove) || params.permissionMode === "bypassPermissions",
+            fullAuto: false,
+            requestedMcpServers,
+            allowedTools: params.allowedTools,
+            disallowedTools: params.disallowedTools,
+            policy: params.approvalPolicy,
+            metadata: { model: resolvedModel || "default" },
+            reviewIntegrity,
+        });
+        if (approvalDecision.status !== "approved") {
+            return createApprovalDeniedResponse(params.operation, approvalDecision);
+        }
+    }
+    const effectiveAlwaysApprove = params.approvalStrategy === "mcp_managed" ? true : Boolean(params.alwaysApprove);
+    const args = ["-p", effectivePrompt];
+    if (resolvedModel)
+        args.push("--model", resolvedModel);
+    if (params.outputFormat)
+        args.push("--output-format", params.outputFormat);
+    if (effectiveAlwaysApprove) {
+        args.push("--always-approve");
+    }
+    else if (params.permissionMode) {
+        args.push("--permission-mode", params.permissionMode);
+    }
+    if (params.effort)
+        args.push("--effort", params.effort);
+    if (params.reasoningEffort)
+        args.push("--reasoning-effort", params.reasoningEffort);
+    if (params.allowedTools && params.allowedTools.length > 0) {
+        args.push("--tools", params.allowedTools.join(","));
+    }
+    if (params.disallowedTools && params.disallowedTools.length > 0) {
+        args.push("--disallowed-tools", params.disallowedTools.join(","));
+    }
+    return {
+        corrId,
+        effectivePrompt,
+        resolvedModel,
+        requestedMcpServers,
+        approvalDecision,
+        reviewIntegrity,
+        args,
+    };
+}
 function buildCliResponse(cli, stdout, optimizeResponse, corrId, sessionId, prep, durationMs, resumable, outputFormat) {
     let finalStdout = stdout;
     // Skip response optimization for JSON output to prevent corrupting structured data
@@ -718,7 +867,7 @@ export async function handleGeminiRequest(deps, params) {
             createNewSession: params.createNewSession,
         });
         args.push(...sessionResult.resumeArgs);
-        const result = await awaitJobOrDefer("gemini", args, corrId, resolveIdleTimeout("gemini", params.idleTimeoutMs));
+        const result = await awaitJobOrDefer("gemini", args, corrId, resolveIdleTimeout("gemini", params.idleTimeoutMs), undefined, params.forceRefresh);
         // Deferred — job still running, return async reference
         if (isDeferredResponse(result)) {
             return buildDeferredToolResponse(result, sessionResult.effectiveSessionId);
@@ -840,7 +989,7 @@ export async function handleGeminiRequestAsync(deps, params) {
             effectiveSessionId = newSession.id;
         }
         // Start job only after all session I/O succeeds
-        const job = deps.asyncJobManager.startJob("gemini", args, corrId, undefined, resolveIdleTimeout("gemini", params.idleTimeoutMs));
+        const job = deps.asyncJobManager.startJob("gemini", args, corrId, undefined, resolveIdleTimeout("gemini", params.idleTimeoutMs), undefined, params.forceRefresh);
         deps.logger.info(`[${corrId}] gemini_request_async started job ${job.id}`);
         const asyncResponse = {
             success: true,
@@ -866,6 +1015,198 @@ export async function handleGeminiRequestAsync(deps, params) {
         return createErrorResponse("gemini_request_async", 1, "", corrId, error);
     }
 }
+export async function handleGrokRequest(deps, params) {
+    const startTime = Date.now();
+    const prep = prepareGrokRequest({
+        prompt: params.prompt,
+        model: params.model,
+        outputFormat: params.outputFormat,
+        alwaysApprove: params.alwaysApprove,
+        permissionMode: params.permissionMode,
+        effort: params.effort,
+        reasoningEffort: params.reasoningEffort,
+        allowedTools: params.allowedTools,
+        disallowedTools: params.disallowedTools,
+        approvalStrategy: params.approvalStrategy,
+        approvalPolicy: params.approvalPolicy,
+        mcpServers: params.mcpServers,
+        correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt,
+        operation: "grok_request",
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    safeFlightStart({
+        correlationId: corrId,
+        cli: "grok",
+        model: prep.resolvedModel || "default",
+        prompt: params.prompt,
+        sessionId: params.sessionId,
+    });
+    deps.logger.info(`[${corrId}] grok_request invoked with model=${prep.resolvedModel || "default"}, permissionMode=${params.permissionMode}, prompt length=${params.prompt.length}`);
+    try {
+        // Session arg planning (pure, no I/O)
+        const sessionResult = resolveGrokSessionArgs({
+            sessionId: params.sessionId,
+            resumeLatest: params.resumeLatest,
+            createNewSession: params.createNewSession,
+        });
+        args.push(...sessionResult.resumeArgs);
+        const result = await awaitJobOrDefer("grok", args, corrId, resolveIdleTimeout("grok", params.idleTimeoutMs), params.outputFormat, params.forceRefresh);
+        // Deferred — job still running, return async reference
+        if (isDeferredResponse(result)) {
+            return buildDeferredToolResponse(result, sessionResult.effectiveSessionId);
+        }
+        const { stdout, stderr, code } = result;
+        durationMs = Math.max(0, Date.now() - startTime);
+        if (code !== 0) {
+            deps.logger.info(`[${corrId}] grok_request failed in ${durationMs}ms`);
+            safeFlightComplete(corrId, {
+                response: stderr || "",
+                durationMs,
+                retryCount: 0,
+                circuitBreakerState: "closed",
+                optimizationApplied: false,
+                exitCode: code,
+                errorMessage: stderr || `Exit code ${code}`,
+                status: "failed",
+            });
+            return createErrorResponse("grok", code, stderr, corrId);
+        }
+        wasSuccessful = true;
+        // Post-success session I/O (sync handlers: no phantom sessions on CLI failure)
+        let effectiveSessionId = sessionResult.effectiveSessionId;
+        if (sessionResult.userProvidedSession && effectiveSessionId) {
+            const existing = await deps.sessionManager.getSession(effectiveSessionId);
+            if (!existing) {
+                try {
+                    await deps.sessionManager.createSession("grok", "Grok Session", effectiveSessionId);
+                }
+                catch {
+                    const rechecked = await deps.sessionManager.getSession(effectiveSessionId);
+                    if (!rechecked)
+                        throw new Error(`Failed to create or find session ${effectiveSessionId}`);
+                }
+            }
+            await deps.sessionManager.updateSessionUsage(effectiveSessionId);
+        }
+        else if (!params.createNewSession && !effectiveSessionId) {
+            const newSession = await deps.sessionManager.createSession("grok", "Grok Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            effectiveSessionId = newSession.id;
+        }
+        deps.logger.info(`[${corrId}] grok_request completed successfully in ${durationMs}ms`);
+        const response = buildCliResponse("grok", stdout, params.optimizeResponse ?? false, corrId, effectiveSessionId, prep, durationMs, sessionResult.userProvidedSession, params.outputFormat);
+        safeFlightComplete(corrId, {
+            response: stdout,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            approvalDecision: prep.approvalDecision?.status,
+            optimizationApplied: params.optimizePrompt || (params.optimizeResponse ?? false),
+            exitCode: 0,
+            status: "completed",
+        });
+        return response;
+    }
+    catch (error) {
+        const elapsedMs = Math.max(0, Date.now() - startTime);
+        deps.logger.info(`[${corrId}] grok_request threw exception after ${elapsedMs}ms`);
+        safeFlightComplete(corrId, {
+            response: "",
+            durationMs: elapsedMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: false,
+            exitCode: 1,
+            errorMessage: error.message,
+            status: "failed",
+        });
+        return createErrorResponse("grok", 1, "", corrId, error);
+    }
+    finally {
+        const finalizedDurationMs = Math.max(0, durationMs || Date.now() - startTime);
+        performanceMetrics.recordRequest("grok", finalizedDurationMs, wasSuccessful);
+    }
+}
+export async function handleGrokRequestAsync(deps, params) {
+    const prep = prepareGrokRequest({
+        prompt: params.prompt,
+        model: params.model,
+        outputFormat: params.outputFormat,
+        alwaysApprove: params.alwaysApprove,
+        permissionMode: params.permissionMode,
+        effort: params.effort,
+        reasoningEffort: params.reasoningEffort,
+        allowedTools: params.allowedTools,
+        disallowedTools: params.disallowedTools,
+        approvalStrategy: params.approvalStrategy,
+        approvalPolicy: params.approvalPolicy,
+        mcpServers: params.mcpServers,
+        correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt,
+        operation: "grok_request_async",
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args, requestedMcpServers, approvalDecision } = prep;
+    try {
+        // Session arg planning (pure, no I/O)
+        const sessionResult = resolveGrokSessionArgs({
+            sessionId: params.sessionId,
+            resumeLatest: params.resumeLatest,
+            createNewSession: params.createNewSession,
+        });
+        args.push(...sessionResult.resumeArgs);
+        // Pre-start session I/O (async handlers: prevent orphaned jobs)
+        let effectiveSessionId = sessionResult.effectiveSessionId;
+        if (sessionResult.userProvidedSession && effectiveSessionId) {
+            const existing = await deps.sessionManager.getSession(effectiveSessionId);
+            if (!existing) {
+                try {
+                    await deps.sessionManager.createSession("grok", "Grok Session", effectiveSessionId);
+                }
+                catch {
+                    const rechecked = await deps.sessionManager.getSession(effectiveSessionId);
+                    if (!rechecked)
+                        throw new Error(`Failed to create or find session ${effectiveSessionId}`);
+                }
+            }
+            await deps.sessionManager.updateSessionUsage(effectiveSessionId);
+        }
+        else if (!params.createNewSession && !effectiveSessionId) {
+            const newSession = await deps.sessionManager.createSession("grok", "Grok Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            effectiveSessionId = newSession.id;
+        }
+        // Start job only after all session I/O succeeds
+        const job = deps.asyncJobManager.startJob("grok", args, corrId, undefined, resolveIdleTimeout("grok", params.idleTimeoutMs), params.outputFormat, params.forceRefresh);
+        deps.logger.info(`[${corrId}] grok_request_async started job ${job.id}`);
+        const asyncResponse = {
+            success: true,
+            job,
+            sessionId: effectiveSessionId || null,
+            resumable: sessionResult.userProvidedSession,
+            approval: approvalDecision,
+            mcpServers: { requested: requestedMcpServers },
+        };
+        if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
+            asyncResponse.reviewIntegrity = prep.reviewIntegrity;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(asyncResponse, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return createErrorResponse("grok_request_async", 1, "", corrId, error);
+    }
+}
 export async function handleCodexRequestAsync(deps, params) {
     const prep = prepareCodexRequest({
         prompt: params.prompt,
@@ -875,6 +1216,9 @@ export async function handleCodexRequestAsync(deps, params) {
         approvalStrategy: params.approvalStrategy,
         approvalPolicy: params.approvalPolicy,
         mcpServers: params.mcpServers,
+        sessionId: params.sessionId,
+        resumeLatest: params.resumeLatest,
+        createNewSession: params.createNewSession,
         correlationId: params.correlationId,
         optimizePrompt: params.optimizePrompt,
         operation: "codex_request_async",
@@ -903,7 +1247,7 @@ export async function handleCodexRequestAsync(deps, params) {
             effectiveSessionId = newSession.id;
         }
         // Start job only after all session I/O succeeds
-        const job = deps.asyncJobManager.startJob("codex", args, corrId, undefined, resolveIdleTimeout("codex", params.idleTimeoutMs));
+        const job = deps.asyncJobManager.startJob("codex", args, corrId, undefined, resolveIdleTimeout("codex", params.idleTimeoutMs), undefined, params.forceRefresh);
         deps.logger.info(`[${corrId}] codex_request_async started job ${job.id}`);
         const asyncResponse = {
             success: true,
@@ -983,7 +1327,11 @@ server.tool("claude_request", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
     const startTime = Date.now();
     const prep = prepareClaudeRequest({
         prompt,
@@ -1034,7 +1382,7 @@ server.tool("claude_request", {
         }
         // Idle timeout only for stream-json (text/json produce no output until done)
         const effectiveIdleTimeout = outputFormat === "stream-json" ? resolveIdleTimeout("claude", idleTimeoutMs) : undefined;
-        const result = await awaitJobOrDefer("claude", args, corrId, effectiveIdleTimeout, outputFormat);
+        const result = await awaitJobOrDefer("claude", args, corrId, effectiveIdleTimeout, outputFormat, forceRefresh);
         // Deferred — job still running, return async reference
         if (isDeferredResponse(result)) {
             return buildDeferredToolResponse(result, effectiveSessionId);
@@ -1142,8 +1490,15 @@ server.tool("codex_request", {
         .array(MCP_SERVER_ENUM)
         .default(["sqry"])
         .describe("MCP server names for approval tracking (Codex manages its own MCP config)"),
-    sessionId: z.string().optional().describe("Session ID (Codex manages internally)"),
-    createNewSession: z.boolean().default(false).describe("Force new session"),
+    sessionId: z
+        .string()
+        .optional()
+        .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected."),
+    resumeLatest: z
+        .boolean()
+        .default(false)
+        .describe("Resume the most recent Codex session in the current cwd via `codex exec resume --last`. Ignored if sessionId is set."),
+    createNewSession: z.boolean().default(false).describe("Force a fresh session (no resume)"),
     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"),
@@ -1154,7 +1509,11 @@ server.tool("codex_request", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
     const startTime = Date.now();
     const prep = prepareCodexRequest({
         prompt,
@@ -1164,6 +1523,9 @@ server.tool("codex_request", {
         approvalStrategy,
         approvalPolicy,
         mcpServers,
+        sessionId,
+        resumeLatest,
+        createNewSession,
         correlationId,
         optimizePrompt,
         operation: "codex_request",
@@ -1182,7 +1544,7 @@ server.tool("codex_request", {
     });
     logger.info(`[${corrId}] codex_request invoked with model=${prep.resolvedModel || "default"}, fullAuto=${fullAuto}, prompt length=${prompt.length}`);
     try {
-        const result = await awaitJobOrDefer("codex", args, corrId, resolveIdleTimeout("codex", idleTimeoutMs));
+        const result = await awaitJobOrDefer("codex", args, corrId, resolveIdleTimeout("codex", idleTimeoutMs), undefined, forceRefresh);
         // Deferred — job still running, return async reference
         if (isDeferredResponse(result)) {
             return buildDeferredToolResponse(result, sessionId);
@@ -1302,7 +1664,11 @@ server.tool("gemini_request", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
     return handleGeminiRequest({ sessionManager, logger }, {
         prompt,
         model,
@@ -1319,6 +1685,98 @@ server.tool("gemini_request", {
         optimizePrompt,
         optimizeResponse,
         idleTimeoutMs,
+        forceRefresh,
+    });
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Grok Tool
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("grok_request", {
+    prompt: z
+        .string()
+        .min(1, "Prompt cannot be empty")
+        .max(100000, "Prompt too long (max 100k chars)")
+        .describe("Prompt text for Grok"),
+    model: z.string().optional().describe("Model name or alias (e.g. grok-build, latest)"),
+    outputFormat: z
+        .enum(["plain", "json", "streaming-json"])
+        .optional()
+        .describe("Output format (plain|json|streaming-json). Grok default is plain."),
+    sessionId: z.string().optional().describe("Session ID (user-provided CLI handle for --resume)"),
+    resumeLatest: z
+        .boolean()
+        .default(false)
+        .describe("Resume most recent Grok session in cwd (--continue)"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    alwaysApprove: z
+        .boolean()
+        .default(false)
+        .describe("Auto-approve all tool executions (--always-approve)"),
+    permissionMode: z
+        .enum(["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"])
+        .optional()
+        .describe("Grok permission mode"),
+    effort: z
+        .enum(["low", "medium", "high", "xhigh", "max"])
+        .optional()
+        .describe("Grok effort level"),
+    reasoningEffort: z.string().optional().describe("Reasoning effort for reasoning models"),
+    approvalStrategy: z
+        .enum(["legacy", "mcp_managed"])
+        .default("legacy")
+        .describe("Approval strategy"),
+    approvalPolicy: z
+        .enum(["strict", "balanced", "permissive"])
+        .optional()
+        .describe("Approval policy override"),
+    mcpServers: z
+        .array(MCP_SERVER_ENUM)
+        .default(["sqry"])
+        .describe("MCP server names for approval tracking (Grok manages its own MCP config via `grok mcp`)"),
+    allowedTools: z
+        .array(z.string())
+        .optional()
+        .describe("Allowed built-in tools (passed as --tools comma list)"),
+    disallowedTools: z
+        .array(z.string())
+        .optional()
+        .describe("Disallowed built-in tools (passed as --disallowed-tools comma list)"),
+    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"),
+    idleTimeoutMs: z
+        .number()
+        .int()
+        .min(30_000)
+        .max(3_600_000)
+        .optional()
+        .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+    return handleGrokRequest({ sessionManager, logger }, {
+        prompt,
+        model,
+        outputFormat,
+        sessionId,
+        resumeLatest,
+        createNewSession,
+        alwaysApprove,
+        permissionMode,
+        effort,
+        reasoningEffort,
+        approvalStrategy,
+        approvalPolicy,
+        mcpServers,
+        allowedTools,
+        disallowedTools,
+        correlationId,
+        optimizePrompt,
+        optimizeResponse,
+        idleTimeoutMs,
+        forceRefresh,
     });
 });
 //──────────────────────────────────────────────────────────────────────────────
@@ -1375,7 +1833,11 @@ server.tool("claude_request_async", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
     const prep = prepareClaudeRequest({
         prompt,
         model,
@@ -1421,7 +1883,7 @@ server.tool("claude_request_async", {
         }
         // Idle timeout only for stream-json (text/json produce no output until done)
         const effectiveIdleTimeout = outputFormat === "stream-json" ? resolveIdleTimeout("claude", idleTimeoutMs) : undefined;
-        const job = asyncJobManager.startJob("claude", args, corrId, undefined, effectiveIdleTimeout, outputFormat);
+        const job = asyncJobManager.startJob("claude", args, corrId, undefined, effectiveIdleTimeout, outputFormat, forceRefresh);
         logger.info(`[${corrId}] claude_request_async started job ${job.id}, outputFormat=${outputFormat}`);
         const asyncResponse = {
             success: true,
@@ -1474,8 +1936,15 @@ server.tool("codex_request_async", {
         .array(MCP_SERVER_ENUM)
         .default(["sqry"])
         .describe("MCP server names for approval tracking (Codex manages its own MCP config)"),
-    sessionId: z.string().optional().describe("Session ID (Codex manages internally)"),
-    createNewSession: z.boolean().default(false).describe("Force new session"),
+    sessionId: z
+        .string()
+        .optional()
+        .describe("Codex session UUID to resume via `codex exec resume <ID>`. Must be a real Codex session ID (from `~/.codex/sessions/` or the `codex resume` picker). Gateway-generated `gw-*` IDs are rejected."),
+    resumeLatest: z
+        .boolean()
+        .default(false)
+        .describe("Resume the most recent Codex session in the current cwd via `codex exec resume --last`. Ignored if sessionId is set."),
+    createNewSession: z.boolean().default(false).describe("Force a fresh session (no resume)"),
     correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
     optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
     idleTimeoutMs: z
@@ -1485,7 +1954,11 @@ server.tool("codex_request_async", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, resumeLatest, createNewSession, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
     return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger }, {
         prompt,
         model,
@@ -1495,10 +1968,12 @@ server.tool("codex_request_async", {
         approvalPolicy,
         mcpServers,
         sessionId,
+        resumeLatest,
         createNewSession,
         correlationId,
         optimizePrompt,
         idleTimeoutMs,
+        forceRefresh,
     });
 });
 server.tool("gemini_request_async", {
@@ -1544,7 +2019,11 @@ server.tool("gemini_request_async", {
         .max(3_600_000)
         .optional()
         .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, }) => {
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
     return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger }, {
         prompt,
         model,
@@ -1560,6 +2039,93 @@ server.tool("gemini_request_async", {
         correlationId,
         optimizePrompt,
         idleTimeoutMs,
+        forceRefresh,
+    });
+});
+server.tool("grok_request_async", {
+    prompt: z
+        .string()
+        .min(1, "Prompt cannot be empty")
+        .max(100000, "Prompt too long (max 100k chars)")
+        .describe("Prompt text for Grok"),
+    model: z.string().optional().describe("Model name or alias (e.g. grok-build, latest)"),
+    outputFormat: z
+        .enum(["plain", "json", "streaming-json"])
+        .optional()
+        .describe("Output format (plain|json|streaming-json). Grok default is plain."),
+    sessionId: z.string().optional().describe("Session ID (user-provided CLI handle for --resume)"),
+    resumeLatest: z
+        .boolean()
+        .default(false)
+        .describe("Resume most recent Grok session in cwd (--continue)"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    alwaysApprove: z
+        .boolean()
+        .default(false)
+        .describe("Auto-approve all tool executions (--always-approve)"),
+    permissionMode: z
+        .enum(["default", "acceptEdits", "auto", "dontAsk", "bypassPermissions", "plan"])
+        .optional()
+        .describe("Grok permission mode"),
+    effort: z
+        .enum(["low", "medium", "high", "xhigh", "max"])
+        .optional()
+        .describe("Grok effort level"),
+    reasoningEffort: z.string().optional().describe("Reasoning effort for reasoning models"),
+    approvalStrategy: z
+        .enum(["legacy", "mcp_managed"])
+        .default("legacy")
+        .describe("Approval strategy"),
+    approvalPolicy: z
+        .enum(["strict", "balanced", "permissive"])
+        .optional()
+        .describe("Approval policy override"),
+    mcpServers: z
+        .array(MCP_SERVER_ENUM)
+        .default(["sqry"])
+        .describe("MCP server names for approval tracking (Grok manages its own MCP config via `grok mcp`)"),
+    allowedTools: z
+        .array(z.string())
+        .optional()
+        .describe("Allowed built-in tools (passed as --tools comma list)"),
+    disallowedTools: z
+        .array(z.string())
+        .optional()
+        .describe("Disallowed built-in tools (passed as --disallowed-tools comma list)"),
+    correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
+    optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
+    idleTimeoutMs: z
+        .number()
+        .int()
+        .min(30_000)
+        .max(3_600_000)
+        .optional()
+        .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
+    forceRefresh: z
+        .boolean()
+        .default(false)
+        .describe("Bypass dedup and force a fresh CLI run even if a recent identical request exists"),
+}, async ({ prompt, model, outputFormat, sessionId, resumeLatest, createNewSession, alwaysApprove, permissionMode, effort, reasoningEffort, approvalStrategy, approvalPolicy, mcpServers, allowedTools, disallowedTools, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+    return handleGrokRequestAsync({ sessionManager, asyncJobManager, logger }, {
+        prompt,
+        model,
+        outputFormat,
+        sessionId,
+        resumeLatest,
+        createNewSession,
+        alwaysApprove,
+        permissionMode,
+        effort,
+        reasoningEffort,
+        approvalStrategy,
+        approvalPolicy,
+        mcpServers,
+        allowedTools,
+        disallowedTools,
+        correlationId,
+        optimizePrompt,
+        idleTimeoutMs,
+        forceRefresh,
     });
 });
 server.tool("llm_job_status", {
@@ -1723,6 +2289,63 @@ server.tool("list_models", {
     const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
+server.tool("cli_versions", {
+    cli: z
+        .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini"]).optional())
+        .describe("CLI filter (claude|codex|gemini)"),
+}, async ({ cli }) => {
+    const versions = await getCliVersions(cli);
+    return { content: [{ type: "text", text: JSON.stringify({ versions }, null, 2) }] };
+});
+server.tool("cli_upgrade", {
+    cli: z.enum(["claude", "codex", "gemini"]).describe("CLI to upgrade"),
+    target: z
+        .string()
+        .min(1)
+        .default("latest")
+        .describe("Package tag/version/target to install (default: latest)"),
+    dryRun: z
+        .boolean()
+        .default(true)
+        .describe("When true, return the upgrade plan without running it"),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(30_000)
+        .max(3_600_000)
+        .optional()
+        .describe("Upgrade timeout in ms when dryRun=false"),
+}, async ({ cli, target, dryRun, timeoutMs }) => {
+    try {
+        const result = await runCliUpgrade({ cli, target, dryRun, timeoutMs, logger });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        ...result,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: message,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 //──────────────────────────────────────────────────────────────────────────────
 // Session Management Tools
 //──────────────────────────────────────────────────────────────────────────────
@@ -1771,6 +2394,7 @@ server.tool("session_list", {
             claude: await sessionManager.getActiveSession("claude"),
             codex: await sessionManager.getActiveSession("codex"),
             gemini: await sessionManager.getActiveSession("gemini"),
+            grok: await sessionManager.getActiveSession("grok"),
         };
         const sessionList = sessions.map(s => ({
             id: s.id,
@@ -1791,6 +2415,7 @@ server.tool("session_list", {
                             claude: activeSessions.claude?.id || null,
                             codex: activeSessions.codex?.id || null,
                             gemini: activeSessions.gemini?.id || null,
+                            grok: activeSessions.grok?.id || null,
                         },
                     }, null, 2),
                 },