llm-cli-gateway 1.0.0

package/dist/index.js

@@ -0,0 +1,1503 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { randomUUID } from "crypto";
+import { readFileSync, readdirSync, realpathSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+import { executeCli, killAllProcessGroups } from "./executor.js";
+import { parseStreamJson } from "./stream-json-parser.js";
+import { createSessionManager } from "./session-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 } from "./config.js";
+import { checkHealth } from "./health.js";
+import { getCliInfo, resolveModelAlias } from "./model-registry.js";
+import { AsyncJobManager } from "./async-job-manager.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, GATEWAY_SESSION_PREFIX } from "./request-helpers.js";
+// Simple logger that writes to stderr (stdout is used for MCP protocol)
+const logger = {
+    info: (message, ...args) => {
+        console.error(`[INFO] ${new Date().toISOString()} - ${message}`, ...args);
+    },
+    error: (message, ...args) => {
+        console.error(`[ERROR] ${new Date().toISOString()} - ${message}`, ...args);
+    },
+    debug: (message, ...args) => {
+        if (process.env.DEBUG) {
+            console.error(`[DEBUG] ${new Date().toISOString()} - ${message}`, ...args);
+        }
+    }
+};
+function logOptimizationTokens(kind, correlationId, original, optimized) {
+    const originalTokens = estimateTokens(original);
+    const optimizedTokens = estimateTokens(optimized);
+    const reduction = originalTokens === 0 ? 0 : ((originalTokens - optimizedTokens) / originalTokens) * 100;
+    logger.info(`[${correlationId}] ${kind} tokens ${originalTokens} → ${optimizedTokens} (${reduction.toFixed(1)}% reduction)`);
+}
+// Sync-to-async deadline: if a sync tool's CLI call hasn't finished within this
+// window, the tool returns a deferred async job reference instead of blocking
+// until the MCP client's tool-call timeout fires (~60s in many runtimes).
+// Configurable via SYNC_DEADLINE_MS env var. Set to 0 to disable (pure sync).
+const SYNC_DEADLINE_MS = (() => {
+    const env = process.env.SYNC_DEADLINE_MS;
+    if (env !== undefined) {
+        const parsed = parseInt(env, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return 45_000; // 45s default — safely under the 60s MCP client cap
+})();
+//──────────────────────────────────────────────────────────────────────────────
+// Skills loader — reads .agents/skills/*/SKILL.md at startup
+//──────────────────────────────────────────────────────────────────────────────
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILLS_DIR = join(__dirname, "..", ".agents", "skills");
+function loadSkills() {
+    const skills = [];
+    try {
+        const dirs = readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory());
+        for (const dir of dirs) {
+            const skillPath = join(SKILLS_DIR, dir.name, "SKILL.md");
+            try {
+                const content = readFileSync(skillPath, "utf-8");
+                // Extract description from YAML frontmatter
+                const descMatch = content.match(/^---[\s\S]*?description:\s*(.+?)$/m);
+                const description = descMatch?.[1]?.trim() || dir.name;
+                skills.push({ name: dir.name, content, description });
+            }
+            catch {
+                // Skill file missing or unreadable — skip silently
+            }
+        }
+    }
+    catch {
+        // Skills directory missing — not fatal
+    }
+    return skills;
+}
+const loadedSkills = loadSkills();
+// L1: Compact server instructions (~200 tokens) — injected into every client's
+// 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)
+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
+
+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.
+- Approval gates: opt-in via approvalStrategy:"mcp_managed".
+- 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")}`;
+const server = new McpServer({ name: "llm-cli-gateway", version: "1.0.0" }, { instructions: SERVER_INSTRUCTIONS });
+// Global state (initialized asynchronously)
+let sessionManager;
+let db = null;
+const performanceMetrics = new PerformanceMetrics();
+let resourceProvider;
+const asyncJobManager = new AsyncJobManager(logger, (cli, durationMs, success) => {
+    performanceMetrics.recordRequest(cli, durationMs, success);
+});
+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.
+// Claude idle timeout only applies in stream-json mode (with --include-partial-messages).
+// In text/json mode, Claude produces no output until done, so idle timeout would false-positive.
+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
+};
+function resolveIdleTimeout(cli, override) {
+    if (override !== undefined)
+        return override;
+    return CLI_IDLE_TIMEOUTS[cli];
+}
+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) {
+    if (SYNC_DEADLINE_MS === 0) {
+        // Disabled — fall through to direct execution
+        return executeCli(cli, args, { idleTimeout: idleTimeoutMs, logger });
+    }
+    const job = asyncJobManager.startJob(cli, args, corrId, undefined, idleTimeoutMs, outputFormat);
+    const deadline = Date.now() + SYNC_DEADLINE_MS;
+    while (Date.now() < deadline) {
+        const snapshot = asyncJobManager.getJobSnapshot(job.id);
+        if (snapshot && snapshot.status !== "running") {
+            // Job finished within deadline — extract result
+            const result = asyncJobManager.getJobResult(job.id);
+            if (!result) {
+                return { stdout: "", stderr: "Job result unavailable", code: 1 };
+            }
+            return {
+                stdout: result.stdout,
+                stderr: result.stderr,
+                code: result.exitCode ?? 1
+            };
+        }
+        await new Promise(resolve => setTimeout(resolve, SYNC_POLL_INTERVAL_MS));
+    }
+    // Deadline exceeded — return deferral
+    logger.info(`[${corrId}] ${cli} sync deadline exceeded (${SYNC_DEADLINE_MS}ms), deferring to async job ${job.id}`);
+    return {
+        deferred: true,
+        jobId: job.id,
+        cli,
+        correlationId: corrId,
+        message: `Execution exceeded sync deadline (${SYNC_DEADLINE_MS}ms). Poll with llm_job_status, fetch with llm_job_result.`
+    };
+}
+function isDeferredResponse(result) {
+    return "deferred" in result && result.deferred === true;
+}
+function buildDeferredToolResponse(deferred, sessionId) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: "deferred",
+                    jobId: deferred.jobId,
+                    cli: deferred.cli,
+                    correlationId: deferred.correlationId,
+                    message: deferred.message,
+                    sessionId: sessionId || null,
+                    pollWith: "llm_job_status",
+                    fetchWith: "llm_job_result",
+                    cancelWith: "llm_job_cancel"
+                }, null, 2)
+            }]
+    };
+}
+// Helper function for standardized error responses
+function createErrorResponse(cli, code, stderr, correlationId, error) {
+    let errorMessage = `Error executing ${cli} CLI`;
+    if (error) {
+        // Command not found or spawn error
+        errorMessage += `:\n${error.message}`;
+        if (error.message.includes("ENOENT")) {
+            errorMessage += `\n\nThe '${cli}' command was not found. Please ensure ${cli} CLI is installed and in your PATH.`;
+        }
+        logger.error(`[${correlationId || "unknown"}] ${cli} CLI execution failed:`, error.message);
+    }
+    else if (code === 124) {
+        // Wall-clock timeout
+        errorMessage += `: Command timed out\n${stderr}`;
+        logger.error(`[${correlationId || "unknown"}] ${cli} CLI timed out`);
+    }
+    else if (code === 125) {
+        // Idle timeout (stuck process)
+        errorMessage += `: Process killed due to inactivity\n${stderr}`;
+        logger.error(`[${correlationId || "unknown"}] ${cli} CLI killed due to inactivity`);
+    }
+    else if (code !== 0) {
+        // Other non-zero exit code
+        errorMessage += ` (exit code ${code}):\n${stderr}`;
+        logger.error(`[${correlationId || "unknown"}] ${cli} CLI failed with exit code ${code}`);
+    }
+    return {
+        content: [{ type: "text", text: errorMessage }],
+        isError: true
+    };
+}
+function createApprovalDeniedResponse(operation, decision) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: false,
+                    error: `${operation} denied by MCP-managed approval policy`,
+                    approval: decision
+                }, null, 2)
+            }],
+        isError: true
+    };
+}
+function normalizeMcpServers(mcpServers) {
+    if (!mcpServers || mcpServers.length === 0) {
+        return ["sqry"];
+    }
+    return [...new Set(mcpServers)];
+}
+function createMcpConfigErrorResponse(operation, correlationId, requested, message, missing = []) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: false,
+                    error: `${operation} failed to prepare Claude MCP config`,
+                    message,
+                    correlationId,
+                    mcpServers: {
+                        requested,
+                        missing
+                    }
+                }, null, 2)
+            }],
+        isError: true
+    };
+}
+function resolveClaudeMcpConfig(operation, correlationId, requestedMcpServers, strictMcpConfig) {
+    let mcpConfig;
+    try {
+        mcpConfig = buildClaudeMcpConfig(requestedMcpServers);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`[${correlationId}] ${operation} failed to build Claude MCP config: ${message}`);
+        return {
+            errorResponse: createMcpConfigErrorResponse(operation, correlationId, requestedMcpServers, message)
+        };
+    }
+    if (strictMcpConfig && mcpConfig.missing.length > 0) {
+        const missing = mcpConfig.missing.join(", ");
+        return {
+            errorResponse: createMcpConfigErrorResponse(operation, correlationId, requestedMcpServers, `strictMcpConfig=true but requested servers are unavailable: ${missing}`, mcpConfig.missing)
+        };
+    }
+    return { config: mcpConfig };
+}
+//──────────────────────────────────────────────────────────────────────────────
+// MCP Resources
+//──────────────────────────────────────────────────────────────────────────────
+// Register skill resources (L2: full docs, read on demand)
+for (const skill of loadedSkills) {
+    server.registerResource(`skill-${skill.name}`, `skills://${skill.name}`, {
+        title: skill.name,
+        description: skill.description,
+        mimeType: "text/markdown"
+    }, async () => ({
+        contents: [{
+                uri: `skills://${skill.name}`,
+                mimeType: "text/markdown",
+                text: skill.content
+            }]
+    }));
+}
+logger.info(`Registered ${loadedSkills.length} skill resources`);
+// Register all sessions resource
+server.registerResource("all-sessions", "sessions://all", {
+    title: "📋 All Sessions",
+    description: "All conversation sessions across CLIs",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading all sessions resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+// Register Claude sessions resource
+server.registerResource("claude-sessions", "sessions://claude", {
+    title: "🤖 Claude Sessions",
+    description: "Claude conversation sessions",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Claude sessions resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+// Register Codex sessions resource
+server.registerResource("codex-sessions", "sessions://codex", {
+    title: "💻 Codex Sessions",
+    description: "Codex conversation sessions",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Codex sessions resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+// Register Gemini sessions resource
+server.registerResource("gemini-sessions", "sessions://gemini", {
+    title: "✨ Gemini Sessions",
+    description: "Gemini conversation sessions",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Gemini 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",
+    description: "Claude models and capabilities",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Claude models resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+// Register Codex models resource
+server.registerResource("codex-models", "models://codex", {
+    title: "🔧 Codex Models",
+    description: "Codex models and capabilities",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Codex models resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+// Register Gemini models resource
+server.registerResource("gemini-models", "models://gemini", {
+    title: "🌟 Gemini Models",
+    description: "Gemini models and capabilities",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading Gemini 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",
+    description: "Request counts, latency, success/failure rates",
+    mimeType: "application/json"
+}, async (uri) => {
+    logger.debug("Reading performance metrics resource");
+    const contents = await resourceProvider.readResource(uri.href);
+    return { contents: contents ? [contents] : [] };
+});
+function prepareClaudeRequest(params) {
+    const corrId = params.correlationId || randomUUID();
+    const cliInfo = getCliInfo();
+    const resolvedModel = resolveModelAlias("claude", 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: "claude", 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);
+    const mcpConfigResolution = resolveClaudeMcpConfig(params.operation, corrId, requestedMcpServers, params.strictMcpConfig);
+    if ("errorResponse" in mcpConfigResolution) {
+        return mcpConfigResolution.errorResponse;
+    }
+    const mcpConfig = mcpConfigResolution.config;
+    let approvalDecision = null;
+    if (params.approvalStrategy === "mcp_managed") {
+        approvalDecision = approvalManager.decide({
+            cli: "claude",
+            operation: params.operation,
+            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            bypassRequested: params.dangerouslySkipPermissions,
+            fullAuto: false,
+            requestedMcpServers,
+            allowedTools: params.allowedTools,
+            disallowedTools: params.disallowedTools,
+            policy: params.approvalPolicy,
+            metadata: { model: resolvedModel || "default", strictMcpConfig: params.strictMcpConfig },
+            reviewIntegrity
+        });
+        if (approvalDecision.status !== "approved") {
+            return createApprovalDeniedResponse(params.operation, approvalDecision);
+        }
+    }
+    const args = ["-p", effectivePrompt];
+    if (resolvedModel)
+        args.push("--model", resolvedModel);
+    if (params.outputFormat === "json") {
+        args.push("--output-format", "json");
+    }
+    else if (params.outputFormat === "stream-json") {
+        args.push("--output-format", "stream-json", "--include-partial-messages");
+    }
+    if (params.allowedTools && params.allowedTools.length > 0) {
+        args.push("--allowed-tools", ...params.allowedTools);
+    }
+    if (params.disallowedTools && params.disallowedTools.length > 0) {
+        args.push("--disallowed-tools", ...params.disallowedTools);
+    }
+    if (params.approvalStrategy === "mcp_managed") {
+        args.push("--permission-mode", "bypassPermissions");
+    }
+    else if (params.dangerouslySkipPermissions) {
+        args.push("--permission-mode", "bypassPermissions");
+    }
+    if (params.strictMcpConfig || mcpConfig.enabled.length > 0) {
+        args.push("--mcp-config", mcpConfig.path);
+        if (params.strictMcpConfig) {
+            args.push("--strict-mcp-config");
+        }
+    }
+    return { corrId, effectivePrompt, resolvedModel, requestedMcpServers, mcpConfig, approvalDecision, reviewIntegrity, args };
+}
+function prepareCodexRequest(params) {
+    const corrId = params.correlationId || randomUUID();
+    const cliInfo = getCliInfo();
+    const resolvedModel = resolveModelAlias("codex", params.model, cliInfo);
+    // Review integrity check on raw prompt (before optimization)
+    const reviewIntegrity = checkReviewIntegrity({ prompt: params.prompt });
+    if (reviewIntegrity.violations.length > 0) {
+        logger.info(`[${corrId}] Review integrity violations detected: ${reviewIntegrity.violations.map(v => v.type).join(", ")}`, {
+            cli: "codex", 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: "codex",
+            operation: params.operation,
+            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            bypassRequested: params.dangerouslyBypassApprovalsAndSandbox,
+            fullAuto: params.fullAuto,
+            requestedMcpServers,
+            policy: params.approvalPolicy,
+            metadata: { model: resolvedModel || "default" },
+            reviewIntegrity
+        });
+        if (approvalDecision.status !== "approved") {
+            return createApprovalDeniedResponse(params.operation, approvalDecision);
+        }
+    }
+    const args = ["exec"];
+    if (resolvedModel)
+        args.push("--model", resolvedModel);
+    if (params.fullAuto)
+        args.push("--full-auto");
+    if (params.dangerouslyBypassApprovalsAndSandbox) {
+        args.push("--dangerously-bypass-approvals-and-sandbox");
+    }
+    args.push("--skip-git-repo-check", effectivePrompt);
+    return { corrId, effectivePrompt, resolvedModel, requestedMcpServers, approvalDecision, reviewIntegrity, args };
+}
+function prepareGeminiRequest(params) {
+    const corrId = params.correlationId || randomUUID();
+    const cliInfo = getCliInfo();
+    const resolvedModel = resolveModelAlias("gemini", params.model, cliInfo);
+    // Review integrity check on raw prompt (before optimization)
+    const reviewIntegrity = checkReviewIntegrity({ prompt: params.prompt, allowedTools: params.allowedTools });
+    if (reviewIntegrity.violations.length > 0) {
+        logger.info(`[${corrId}] Review integrity violations detected: ${reviewIntegrity.violations.map(v => v.type).join(", ")}`, {
+            cli: "gemini", 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: "gemini",
+            operation: params.operation,
+            prompt: params.prompt, // Use raw prompt for review-context detection, not optimized
+            bypassRequested: params.approvalMode === "yolo",
+            fullAuto: false,
+            requestedMcpServers,
+            allowedTools: params.allowedTools,
+            policy: params.approvalPolicy,
+            metadata: { model: resolvedModel || "default" },
+            reviewIntegrity
+        });
+        if (approvalDecision.status !== "approved") {
+            return createApprovalDeniedResponse(params.operation, approvalDecision);
+        }
+    }
+    const effectiveApprovalMode = params.approvalStrategy === "mcp_managed" ? "yolo" : params.approvalMode;
+    const args = [effectivePrompt];
+    if (resolvedModel)
+        args.push("--model", resolvedModel);
+    if (effectiveApprovalMode)
+        args.push("--approval-mode", effectiveApprovalMode);
+    if (params.allowedTools && params.allowedTools.length > 0) {
+        params.allowedTools.forEach(tool => args.push("--allowed-tools", tool));
+    }
+    if (requestedMcpServers.length > 0) {
+        requestedMcpServers.forEach(serverName => args.push("--allowed-mcp-server-names", serverName));
+    }
+    if (params.includeDirs && params.includeDirs.length > 0) {
+        params.includeDirs.forEach(dir => args.push("--include-directories", dir));
+    }
+    return { corrId, effectivePrompt, resolvedModel, requestedMcpServers, approvalDecision, reviewIntegrity, args };
+}
+function buildCliResponse(stdout, optimizeResponse, corrId, sessionId, prep, resumable, outputFormat) {
+    let finalStdout = stdout;
+    // Skip response optimization for JSON output to prevent corrupting structured data
+    if (optimizeResponse && outputFormat !== "json") {
+        const optimized = optimizeResponseText(finalStdout);
+        logOptimizationTokens("response", corrId, finalStdout, optimized);
+        finalStdout = optimized;
+    }
+    // Append review integrity warnings to response text (skip for JSON output to avoid corruption)
+    if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0 && outputFormat !== "json") {
+        const warnings = prep.reviewIntegrity.violations
+            .map(v => `- [${v.type}] ${v.detail}`)
+            .join("\n");
+        finalStdout += `\n\n⚠️ Review Integrity Warnings (score: ${prep.reviewIntegrity.totalScore}):\n${warnings}`;
+    }
+    const response = {
+        content: [{ type: "text", text: finalStdout }],
+        mcpServers: prep.mcpConfig
+            ? { requested: prep.requestedMcpServers, enabled: prep.mcpConfig.enabled, missing: prep.mcpConfig.missing }
+            : { requested: prep.requestedMcpServers }
+    };
+    if (sessionId) {
+        response.sessionId = sessionId;
+    }
+    if (resumable !== undefined) {
+        response.resumable = resumable;
+    }
+    if (prep.approvalDecision) {
+        response.approval = prep.approvalDecision;
+    }
+    if (prep.reviewIntegrity && prep.reviewIntegrity.violations.length > 0) {
+        response.reviewIntegrity = prep.reviewIntegrity;
+    }
+    return response;
+}
+export async function handleGeminiRequest(deps, params) {
+    const startTime = Date.now();
+    const prep = prepareGeminiRequest({
+        prompt: params.prompt, model: params.model, approvalMode: params.approvalMode,
+        approvalStrategy: params.approvalStrategy, approvalPolicy: params.approvalPolicy,
+        allowedTools: params.allowedTools, includeDirs: params.includeDirs,
+        mcpServers: params.mcpServers, correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt, operation: "gemini_request"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    deps.logger.info(`[${corrId}] gemini_request invoked with model=${prep.resolvedModel || "default"}, approvalMode=${params.approvalMode}, prompt length=${params.prompt.length}`);
+    try {
+        // Session arg planning (pure, no I/O)
+        const sessionResult = resolveSessionResumeArgs({
+            sessionId: params.sessionId, resumeLatest: params.resumeLatest, createNewSession: params.createNewSession
+        });
+        args.push(...sessionResult.resumeArgs);
+        const result = await awaitJobOrDefer("gemini", args, corrId, resolveIdleTimeout("gemini", params.idleTimeoutMs));
+        // 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}] gemini_request failed in ${durationMs}ms`);
+            return createErrorResponse("gemini", 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("gemini", "Gemini 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("gemini", "Gemini Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            effectiveSessionId = newSession.id;
+        }
+        deps.logger.info(`[${corrId}] gemini_request completed successfully in ${durationMs}ms`);
+        return buildCliResponse(stdout, params.optimizeResponse ?? false, corrId, effectiveSessionId, prep, sessionResult.userProvidedSession);
+    }
+    catch (error) {
+        const elapsedMs = Math.max(0, Date.now() - startTime);
+        deps.logger.info(`[${corrId}] gemini_request threw exception after ${elapsedMs}ms`);
+        return createErrorResponse("gemini", 1, "", corrId, error);
+    }
+    finally {
+        const finalizedDurationMs = Math.max(0, durationMs || Date.now() - startTime);
+        performanceMetrics.recordRequest("gemini", finalizedDurationMs, wasSuccessful);
+    }
+}
+export async function handleGeminiRequestAsync(deps, params) {
+    const prep = prepareGeminiRequest({
+        prompt: params.prompt, model: params.model, approvalMode: params.approvalMode,
+        approvalStrategy: params.approvalStrategy, approvalPolicy: params.approvalPolicy,
+        allowedTools: params.allowedTools, includeDirs: params.includeDirs,
+        mcpServers: params.mcpServers, correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt, operation: "gemini_request_async"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args, requestedMcpServers, approvalDecision } = prep;
+    try {
+        // Session arg planning (pure, no I/O)
+        const sessionResult = resolveSessionResumeArgs({
+            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("gemini", "Gemini 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("gemini", "Gemini Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            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));
+        deps.logger.info(`[${corrId}] gemini_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("gemini_request_async", 1, "", corrId, error);
+    }
+}
+export async function handleCodexRequestAsync(deps, params) {
+    const prep = prepareCodexRequest({
+        prompt: params.prompt, model: params.model, fullAuto: params.fullAuto,
+        dangerouslyBypassApprovalsAndSandbox: params.dangerouslyBypassApprovalsAndSandbox,
+        approvalStrategy: params.approvalStrategy, approvalPolicy: params.approvalPolicy,
+        mcpServers: params.mcpServers,
+        correlationId: params.correlationId, optimizePrompt: params.optimizePrompt,
+        operation: "codex_request_async"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args, requestedMcpServers, approvalDecision } = prep;
+    try {
+        // Pre-start session I/O (async handlers: prevent orphaned jobs)
+        let effectiveSessionId = params.sessionId;
+        if (!params.createNewSession && !params.sessionId) {
+            const activeSession = await deps.sessionManager.getActiveSession("codex");
+            if (activeSession) {
+                effectiveSessionId = activeSession.id;
+            }
+            else {
+                const newSession = await deps.sessionManager.createSession("codex", "Codex Session");
+                effectiveSessionId = newSession.id;
+            }
+        }
+        else if (params.sessionId) {
+            await deps.sessionManager.updateSessionUsage(params.sessionId);
+        }
+        else if (params.createNewSession) {
+            const newSession = await deps.sessionManager.createSession("codex", "Codex Session");
+            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));
+        deps.logger.info(`[${corrId}] codex_request_async started job ${job.id}`);
+        const asyncResponse = {
+            success: true,
+            job,
+            sessionId: effectiveSessionId || null,
+            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("codex_request_async", 1, "", corrId, error);
+    }
+}
+//──────────────────────────────────────────────────────────────────────────────
+// Claude Code Tool
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("claude_request", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Claude"),
+    model: z.string().optional().describe("Model name or alias (e.g. sonnet, claude-sonnet-4-5-20250929, latest)"),
+    outputFormat: z.enum(["text", "json", "stream-json"]).default("text").describe("Output format (text|json|stream-json). stream-json: NDJSON with idle timeout."),
+    sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
+    continueSession: z.boolean().default(false).describe("Continue active session"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    allowedTools: z.array(z.string()).optional().describe("Allowed tools (['Bash(git:*)','Edit','Write'])"),
+    disallowedTools: z.array(z.string()).optional().describe("Disallowed tools"),
+    dangerouslySkipPermissions: z.boolean().default(false).describe("Bypass permissions (sandbox only)"),
+    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 servers exposed to Claude"),
+    strictMcpConfig: z.boolean().default(false).describe("Restrict Claude to provided MCP config only"),
+    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)")
+}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs }) => {
+    const startTime = Date.now();
+    const prep = prepareClaudeRequest({
+        prompt, model, outputFormat, allowedTools, disallowedTools, dangerouslySkipPermissions,
+        approvalStrategy, approvalPolicy, mcpServers,
+        strictMcpConfig, correlationId, optimizePrompt, operation: "claude_request"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    logger.info(`[${corrId}] claude_request invoked with model=${prep.resolvedModel || "default"}, outputFormat=${outputFormat}, prompt length=${prompt.length}, sessionId=${sessionId}`);
+    try {
+        // Session management
+        let effectiveSessionId = sessionId;
+        let useContinue = continueSession;
+        const activeSession = await sessionManager.getActiveSession("claude");
+        if (!createNewSession && !continueSession && !sessionId && activeSession) {
+            effectiveSessionId = activeSession.id;
+            useContinue = true;
+        }
+        if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
+            useContinue = true;
+        }
+        if (useContinue) {
+            args.push("--continue");
+        }
+        else if (effectiveSessionId) {
+            args.push("--session-id", effectiveSessionId);
+            await sessionManager.updateSessionUsage(effectiveSessionId);
+        }
+        // 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);
+        // Deferred — job still running, return async reference
+        if (isDeferredResponse(result)) {
+            return buildDeferredToolResponse(result, effectiveSessionId);
+        }
+        const { stdout, stderr, code } = result;
+        durationMs = Math.max(0, Date.now() - startTime);
+        if (code !== 0) {
+            logger.info(`[${corrId}] claude_request failed in ${durationMs}ms`);
+            return createErrorResponse("claude", code, stderr, corrId);
+        }
+        wasSuccessful = true;
+        // If we used a session ID and it's not tracked yet, create a session record
+        if (effectiveSessionId) {
+            const existingSession = await sessionManager.getSession(effectiveSessionId);
+            if (!existingSession) {
+                await sessionManager.createSession("claude", "Claude Session", effectiveSessionId);
+            }
+        }
+        logger.info(`[${corrId}] claude_request completed successfully in ${durationMs}ms`);
+        // Parse stream-json NDJSON output to extract result text
+        if (outputFormat === "stream-json") {
+            const parsed = parseStreamJson(stdout);
+            if (parsed.costUsd !== null) {
+                logger.debug(`[${corrId}] stream-json cost=$${parsed.costUsd}, model=${parsed.model}, turns=${parsed.numTurns}`);
+            }
+            return buildCliResponse(parsed.text, optimizeResponse, corrId, effectiveSessionId, prep, undefined, outputFormat);
+        }
+        return buildCliResponse(stdout, optimizeResponse, corrId, effectiveSessionId, prep, undefined, outputFormat);
+    }
+    catch (error) {
+        const elapsedMs = Math.max(0, Date.now() - startTime);
+        logger.info(`[${corrId}] claude_request threw exception after ${elapsedMs}ms`);
+        return createErrorResponse("claude", 1, "", corrId, error);
+    }
+    finally {
+        const finalizedDurationMs = Math.max(0, durationMs || Date.now() - startTime);
+        performanceMetrics.recordRequest("claude", finalizedDurationMs, wasSuccessful);
+    }
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Codex Tool
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("codex_request", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Codex"),
+    model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
+    fullAuto: z.boolean().default(false).describe("Full-auto mode (sandboxed execution)"),
+    dangerouslyBypassApprovalsAndSandbox: z.boolean().default(false).describe("Run Codex without approvals/sandbox"),
+    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 (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"),
+    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)")
+}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, createNewSession, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs }) => {
+    const startTime = Date.now();
+    const prep = prepareCodexRequest({
+        prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox,
+        approvalStrategy, approvalPolicy, mcpServers,
+        correlationId, optimizePrompt, operation: "codex_request"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    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));
+        // Deferred — job still running, return async reference
+        if (isDeferredResponse(result)) {
+            return buildDeferredToolResponse(result, sessionId);
+        }
+        const { stdout, stderr, code } = result;
+        durationMs = Math.max(0, Date.now() - startTime);
+        if (code !== 0) {
+            logger.info(`[${corrId}] codex_request failed in ${durationMs}ms`);
+            return createErrorResponse("codex", code, stderr, corrId);
+        }
+        wasSuccessful = true;
+        // Track session usage
+        let effectiveSessionId = sessionId;
+        if (!createNewSession && !sessionId) {
+            const activeSession = await sessionManager.getActiveSession("codex");
+            if (activeSession) {
+                effectiveSessionId = activeSession.id;
+            }
+            else {
+                const newSession = await sessionManager.createSession("codex", "Codex Session");
+                effectiveSessionId = newSession.id;
+            }
+        }
+        else if (sessionId) {
+            await sessionManager.updateSessionUsage(sessionId);
+        }
+        else if (createNewSession) {
+            const newSession = await sessionManager.createSession("codex", "Codex Session");
+            effectiveSessionId = newSession.id;
+        }
+        logger.info(`[${corrId}] codex_request completed successfully in ${durationMs}ms`);
+        return buildCliResponse(stdout, optimizeResponse, corrId, effectiveSessionId, prep);
+    }
+    catch (error) {
+        const elapsedMs = Math.max(0, Date.now() - startTime);
+        logger.info(`[${corrId}] codex_request threw exception after ${elapsedMs}ms`);
+        return createErrorResponse("codex", 1, "", corrId, error);
+    }
+    finally {
+        const finalizedDurationMs = Math.max(0, durationMs || Date.now() - startTime);
+        performanceMetrics.recordRequest("codex", finalizedDurationMs, wasSuccessful);
+    }
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Gemini Tool
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("gemini_request", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Gemini"),
+    model: z.string().optional().describe("Model name or alias (e.g. gemini-3-pro-preview, gemini-2.5-flash, pro, flash, latest)"),
+    sessionId: z.string().optional().describe("Session ID or 'latest'"),
+    resumeLatest: z.boolean().default(false).describe("Resume latest session"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    approvalMode: z.enum(["default", "auto_edit", "yolo"]).optional().describe("Approval: default|auto_edit|yolo"),
+    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 passed to Gemini as --allowed-mcp-server-names"),
+    allowedTools: z.array(z.string()).optional().describe("Allowed tools (['Write','Edit','Bash'])"),
+    includeDirs: z.array(z.string()).optional().describe("Additional workspace directories"),
+    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)")
+}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs }) => {
+    return handleGeminiRequest({ sessionManager, logger }, { prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs });
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Async Long-Running Job Tools (No Time-Bound LLM Execution)
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("claude_request_async", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Claude"),
+    model: z.string().optional().describe("Model name or alias (e.g. sonnet, claude-sonnet-4-5-20250929, latest)"),
+    outputFormat: z.enum(["text", "json", "stream-json"]).default("text").describe("Output format (text|json|stream-json). stream-json: NDJSON with idle timeout."),
+    sessionId: z.string().optional().describe("Session ID (uses active if omitted)"),
+    continueSession: z.boolean().default(false).describe("Continue active session"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    allowedTools: z.array(z.string()).optional().describe("Allowed tools (['Bash(git:*)','Edit','Write'])"),
+    disallowedTools: z.array(z.string()).optional().describe("Disallowed tools"),
+    dangerouslySkipPermissions: z.boolean().default(false).describe("Bypass permissions (sandbox only)"),
+    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 servers exposed to Claude"),
+    strictMcpConfig: z.boolean().default(false).describe("Restrict Claude to provided MCP config only"),
+    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)")
+}, async ({ prompt, model, outputFormat, sessionId, continueSession, createNewSession, allowedTools, disallowedTools, dangerouslySkipPermissions, approvalStrategy, approvalPolicy, mcpServers, strictMcpConfig, correlationId, optimizePrompt, idleTimeoutMs }) => {
+    const prep = prepareClaudeRequest({
+        prompt, model, outputFormat, allowedTools, disallowedTools, dangerouslySkipPermissions,
+        approvalStrategy, approvalPolicy, mcpServers,
+        strictMcpConfig, correlationId, optimizePrompt, operation: "claude_request_async"
+    });
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args, requestedMcpServers, mcpConfig, approvalDecision } = prep;
+    try {
+        // Session management (before job start for async)
+        let effectiveSessionId = sessionId;
+        let useContinue = continueSession;
+        const activeSession = await sessionManager.getActiveSession("claude");
+        if (!createNewSession && !continueSession && !sessionId && activeSession) {
+            effectiveSessionId = activeSession.id;
+            useContinue = true;
+        }
+        if (!useContinue && effectiveSessionId && activeSession?.id === effectiveSessionId) {
+            useContinue = true;
+        }
+        if (useContinue) {
+            args.push("--continue");
+        }
+        else if (effectiveSessionId) {
+            args.push("--session-id", effectiveSessionId);
+            await sessionManager.updateSessionUsage(effectiveSessionId);
+        }
+        if (effectiveSessionId) {
+            const existingSession = await sessionManager.getSession(effectiveSessionId);
+            if (!existingSession) {
+                await sessionManager.createSession("claude", "Claude Session", effectiveSessionId);
+            }
+        }
+        // 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);
+        logger.info(`[${corrId}] claude_request_async started job ${job.id}, outputFormat=${outputFormat}`);
+        const asyncResponse = {
+            success: true,
+            job,
+            sessionId: effectiveSessionId || activeSession?.id || null,
+            approval: approvalDecision,
+            mcpServers: {
+                requested: requestedMcpServers,
+                enabled: mcpConfig?.enabled,
+                missing: mcpConfig?.missing
+            }
+        };
+        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("claude_request_async", 1, "", corrId, error);
+    }
+});
+server.tool("codex_request_async", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Codex"),
+    model: z.string().optional().describe("Model name or alias (e.g. gpt-5.4, latest)"),
+    fullAuto: z.boolean().default(false).describe("Full-auto mode (sandboxed execution)"),
+    dangerouslyBypassApprovalsAndSandbox: z.boolean().default(false).describe("Run Codex without approvals/sandbox"),
+    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 (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"),
+    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)")
+}, async ({ prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, createNewSession, correlationId, optimizePrompt, idleTimeoutMs }) => {
+    return handleCodexRequestAsync({ sessionManager, asyncJobManager, logger }, { prompt, model, fullAuto, dangerouslyBypassApprovalsAndSandbox, approvalStrategy, approvalPolicy, mcpServers, sessionId, createNewSession, correlationId, optimizePrompt, idleTimeoutMs });
+});
+server.tool("gemini_request_async", {
+    prompt: z.string().min(1, "Prompt cannot be empty").max(100000, "Prompt too long (max 100k chars)").describe("Prompt text for Gemini"),
+    model: z.string().optional().describe("Model name or alias (e.g. gemini-3-pro-preview, gemini-2.5-flash, pro, flash, latest)"),
+    sessionId: z.string().optional().describe("Session ID (user-provided CLI handle for --resume)"),
+    resumeLatest: z.boolean().default(false).describe("Resume latest session"),
+    createNewSession: z.boolean().default(false).describe("Force new session"),
+    approvalMode: z.enum(["default", "auto_edit", "yolo"]).optional().describe("Approval: default|auto_edit|yolo"),
+    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 passed to Gemini as --allowed-mcp-server-names"),
+    allowedTools: z.array(z.string()).optional().describe("Allowed tools (['Write','Edit','Bash'])"),
+    includeDirs: z.array(z.string()).optional().describe("Additional workspace directories"),
+    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)")
+}, async ({ prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs }) => {
+    return handleGeminiRequestAsync({ sessionManager, asyncJobManager, logger }, { prompt, model, sessionId, resumeLatest, createNewSession, approvalMode, approvalStrategy, approvalPolicy, mcpServers, allowedTools, includeDirs, correlationId, optimizePrompt, idleTimeoutMs });
+});
+server.tool("llm_job_status", {
+    jobId: z.string().describe("Async job ID from *_request_async")
+}, async ({ jobId }) => {
+    const job = asyncJobManager.getJobSnapshot(jobId);
+    if (!job) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: "Job not found",
+                        jobId
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    job
+                }, null, 2)
+            }]
+    };
+});
+server.tool("llm_job_result", {
+    jobId: z.string().describe("Async job ID from *_request_async"),
+    maxChars: z.number().int().min(1000).max(2000000).default(200000).describe("Max chars returned per stream")
+}, async ({ jobId, maxChars }) => {
+    const result = asyncJobManager.getJobResult(jobId, maxChars);
+    if (!result) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        error: "Job not found",
+                        jobId
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+    // Parse stream-json output for Claude async jobs
+    const outputFormat = asyncJobManager.getJobOutputFormat(jobId);
+    let parsed;
+    if (outputFormat === "stream-json" && result.stdout) {
+        parsed = parseStreamJson(result.stdout);
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    result,
+                    ...(parsed ? { parsed: { text: parsed.text, costUsd: parsed.costUsd, usage: parsed.usage, model: parsed.model, numTurns: parsed.numTurns } } : {})
+                }, null, 2)
+            }]
+    };
+});
+server.tool("llm_job_cancel", {
+    jobId: z.string().describe("Async job ID from *_request_async")
+}, async ({ jobId }) => {
+    const cancel = asyncJobManager.cancelJob(jobId);
+    if (!cancel.canceled) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: false,
+                        jobId,
+                        reason: cancel.reason || "Unable to cancel"
+                    }, null, 2)
+                }],
+            isError: true
+        };
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    jobId
+                }, null, 2)
+            }]
+    };
+});
+server.tool("llm_process_health", {}, async () => {
+    const health = asyncJobManager.getJobHealth();
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ success: true, ...health }, null, 2)
+            }]
+    };
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Approval Audit Tools
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("approval_list", {
+    limit: z.number().int().min(1).max(500).default(50).describe("Max number of approval records"),
+    cli: z.enum(["claude", "codex", "gemini"]).optional().describe("Optional CLI filter")
+}, async ({ limit, cli }) => {
+    const approvals = approvalManager.list(limit, cli);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    success: true,
+                    count: approvals.length,
+                    approvals
+                }, null, 2)
+            }]
+    };
+});
+//──────────────────────────────────────────────────────────────────────────────
+// List Models Tool
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("list_models", {
+    cli: z.preprocess((value) => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini"]).optional()).describe("CLI filter (claude|codex|gemini)")
+}, async ({ cli }) => {
+    const cliInfo = getCliInfo();
+    const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Session Management Tools
+//──────────────────────────────────────────────────────────────────────────────
+server.tool("session_create", {
+    cli: z.enum(["claude", "codex", "gemini"]).describe("CLI type (claude|codex|gemini)"),
+    description: z.string().optional().describe("Session description"),
+    setAsActive: z.boolean().default(true).describe("Set as active session")
+}, async ({ cli, description, setAsActive }) => {
+    try {
+        const session = await sessionManager.createSession(cli, description);
+        if (setAsActive) {
+            await sessionManager.setActiveSession(cli, session.id);
+        }
+        logger.info(`Created new ${cli} session: ${session.id}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        session: {
+                            id: session.id,
+                            cli: session.cli,
+                            description: session.description,
+                            createdAt: session.createdAt,
+                            isActive: setAsActive
+                        }
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_create", 1, "", undefined, error);
+    }
+});
+server.tool("session_list", {
+    cli: z.enum(["claude", "codex", "gemini"]).optional().describe("CLI filter (claude|codex|gemini)")
+}, 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")
+        };
+        const sessionList = sessions.map(s => ({
+            id: s.id,
+            cli: s.cli,
+            description: s.description,
+            createdAt: s.createdAt,
+            lastUsedAt: s.lastUsedAt,
+            isActive: activeSessions[s.cli]?.id === s.id
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        total: sessionList.length,
+                        sessions: sessionList,
+                        activeSessions: {
+                            claude: activeSessions.claude?.id || null,
+                            codex: activeSessions.codex?.id || null,
+                            gemini: activeSessions.gemini?.id || null
+                        }
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_list", 1, "", undefined, error);
+    }
+});
+server.tool("session_set_active", {
+    cli: z.enum(["claude", "codex", "gemini"]).describe("CLI type (claude|codex|gemini)"),
+    sessionId: z.string().nullable().describe("Session ID (null to clear)")
+}, async ({ cli, sessionId }) => {
+    try {
+        const success = await sessionManager.setActiveSession(cli, sessionId || null);
+        if (!success) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "Session not found or does not belong to the specified CLI"
+                        }, null, 2)
+                    }],
+                isError: true
+            };
+        }
+        logger.info(`Set active ${cli} session to: ${sessionId}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        cli,
+                        activeSessionId: sessionId
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_set_active", 1, "", undefined, error);
+    }
+});
+server.tool("session_delete", {
+    sessionId: z.string().describe("Session ID")
+}, async ({ sessionId }) => {
+    try {
+        const session = await sessionManager.getSession(sessionId);
+        if (!session) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "Session not found"
+                        }, null, 2)
+                    }],
+                isError: true
+            };
+        }
+        const success = await sessionManager.deleteSession(sessionId);
+        logger.info(`Deleted session: ${sessionId}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success,
+                        deletedSession: {
+                            id: session.id,
+                            cli: session.cli,
+                            description: session.description
+                        }
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_delete", 1, "", undefined, error);
+    }
+});
+server.tool("session_get", {
+    sessionId: z.string().describe("Session ID")
+}, async ({ sessionId }) => {
+    try {
+        const session = await sessionManager.getSession(sessionId);
+        if (!session) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "Session not found"
+                        }, null, 2)
+                    }],
+                isError: true
+            };
+        }
+        const activeSession = await sessionManager.getActiveSession(session.cli);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        session: {
+                            ...session,
+                            isActive: activeSession?.id === session.id
+                        }
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_get", 1, "", undefined, error);
+    }
+});
+server.tool("session_clear_all", {
+    cli: z.enum(["claude", "codex", "gemini"]).optional().describe("CLI filter (claude|codex|gemini)")
+}, async ({ cli }) => {
+    try {
+        const count = await sessionManager.clearAllSessions(cli);
+        logger.info(`Cleared ${count} sessions${cli ? ` for ${cli}` : ''}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        deletedCount: count,
+                        cli: cli || "all"
+                    }, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        return createErrorResponse("session_clear_all", 1, "", undefined, error);
+    }
+});
+//──────────────────────────────────────────────────────────────────────────────
+// Async Initialization
+//──────────────────────────────────────────────────────────────────────────────
+async function initializeSessionManager() {
+    const config = loadConfig();
+    if (config.database && config.redis) {
+        logger.info("Initializing PostgreSQL + Redis session manager");
+        const { createDatabaseConnection } = await import("./db.js");
+        db = await createDatabaseConnection(config, logger);
+        sessionManager = await createSessionManager(config, db, logger);
+        logger.info("PostgreSQL session manager initialized");
+    }
+    else {
+        logger.info("Initializing file-based session manager");
+        sessionManager = await createSessionManager(config, undefined, logger);
+        logger.info("File-based session manager initialized");
+    }
+    resourceProvider = new ResourceProvider(sessionManager, performanceMetrics);
+}
+//──────────────────────────────────────────────────────────────────────────────
+// Health Check Resource (only if using PostgreSQL)
+//──────────────────────────────────────────────────────────────────────────────
+function registerHealthResource() {
+    if (db) {
+        server.registerResource("health", "health://status", {
+            title: "🏥 Health Status",
+            description: "DB connectivity and latency",
+            mimeType: "application/json"
+        }, async () => {
+            const health = await checkHealth(db);
+            return {
+                contents: [{
+                        uri: "health://status",
+                        text: JSON.stringify(health, null, 2),
+                        mimeType: "application/json"
+                    }]
+            };
+        });
+        logger.info("Health check resource registered");
+    }
+    // Process health resource (always available, not dependent on DB)
+    server.registerResource("process-health", "metrics://process-health", {
+        title: "Process Health",
+        description: "Async job health (CPU, memory, zombie detection)",
+        mimeType: "application/json"
+    }, async (uri) => {
+        const health = asyncJobManager.getJobHealth();
+        return {
+            contents: [{
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify(health, null, 2)
+                }]
+        };
+    });
+    logger.info("Process health resource registered");
+}
+//──────────────────────────────────────────────────────────────────────────────
+// Graceful Shutdown
+//──────────────────────────────────────────────────────────────────────────────
+async function shutdown(signal) {
+    logger.info(`Received ${signal}, shutting down gracefully...`);
+    try {
+        // Kill all active process groups (SIGTERM → wait 3s → SIGKILL)
+        await killAllProcessGroups();
+        logger.info("All process groups terminated");
+        await server.close();
+        logger.info("MCP server closed");
+        if (db) {
+            await db.disconnect();
+            logger.info("Database connections closed");
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        logger.error("Error during shutdown:", error);
+        process.exit(1);
+    }
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+//──────────────────────────────────────────────────────────────────────────────
+// Server Startup
+//──────────────────────────────────────────────────────────────────────────────
+async function main() {
+    logger.info("Starting llm-cli-gateway MCP server");
+    // Initialize session manager first
+    await initializeSessionManager();
+    // Register health check resource if using PostgreSQL
+    registerHealthResource();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("llm-cli-gateway MCP server connected and ready");
+}
+// Guard: only auto-start when run directly (not imported for testing)
+// Resolve symlinks so `llm-cli-gateway` (npm-linked bin) matches import.meta.url
+const __entryUrl = process.argv[1]
+    ? new URL(realpathSync(process.argv[1]), "file://").href
+    : "";
+if (__entryUrl === import.meta.url) {
+    main().catch((error) => {
+        logger.error("Fatal server error:", error);
+        process.exit(1);
+    });
+}