llm-cli-gateway 2.12.2 → 2.13.0

package/dist/index.js

@@ -162,7 +162,7 @@ export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled =
         : '- Async jobs are DISABLED (persistence.backend = "none"): *_request_async and llm_job_* tools are not registered, and sync requests run to completion (no auto-deferral).';
     return `llm-cli-gateway: Multi-LLM orchestration via MCP.
 
-Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request, devin_request${apiToolsNote} (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
+Tools: claude_request, codex_request, gemini_request, grok_request, mistral_request, devin_request, cursor_request${apiToolsNote} (sync)${asyncToolsNote} | codex_fork_session (fork a Codex session into a new branch)
 Validation: validate_with_models, second_opinion, compare_answers, red_team_review, consensus_check, ask_model, synthesize_validation, list_available_models | job_status/job_result (validation jobs)
 ${jobsLine}Sessions: session_create, session_list, session_set_active, session_get, session_delete, session_clear_all
 Other: list_models, provider_tool_capabilities, cli_versions, upstream_contracts, provider_subcommands_* (read-only subcommand contract/drift introspection), cli_upgrade, approval_list, llm_process_health, llm_request_result (read back any persisted request, sync or async, by correlationId)
@@ -345,6 +345,7 @@ const CLI_IDLE_TIMEOUTS = {
     gemini: 600_000,
     grok: 600_000,
     mistral: 600_000,
+    cursor: 600_000,
 };
 function resolveIdleTimeout(cli, override) {
     if (override !== undefined)
@@ -884,6 +885,7 @@ export function createErrorResponse(cli, code, stderr, correlationId, error, api
         grok: "Run `grok login` (or re-authenticate) and retry.",
         mistral: "Run `vibe --setup` (or re-authenticate) and retry.",
         devin: "Run `devin auth login` (or set WINDSURF_API_KEY) and retry.",
+        cursor: "Run `cursor-agent login` (or set CURSOR_API_KEY) and retry.",
     };
     if (error) {
         errorMessage += `:\n${error.message}`;
@@ -3647,6 +3649,347 @@ export async function handleDevinRequestAsync(deps, params) {
         return createErrorResponse("devin_request_async", 1, "", corrId, error);
     }
 }
+export function prepareCursorRequest(params, runtime) {
+    const corrId = params.correlationId ?? randomUUID();
+    let prompt = (params.prompt ?? "").trim();
+    if (!prompt) {
+        return createErrorResponse(params.operation, 1, "prompt is required and cannot be empty", corrId);
+    }
+    const reviewIntegrity = checkReviewIntegrity({ prompt });
+    if (reviewIntegrity.violations.length > 0) {
+        runtime.logger.info(`[${corrId}] Review integrity violations detected: ${reviewIntegrity.violations.map(v => v.type).join(", ")}`, {
+            cli: "cursor",
+            operation: params.operation,
+            score: reviewIntegrity.totalScore,
+        });
+    }
+    const highImpactRequested = Boolean(params.force) || Boolean(params.trust) || params.sandbox === "disabled";
+    let approvalDecision = null;
+    if (params.approvalStrategy === "mcp_managed") {
+        approvalDecision = runtime.approvalManager.decide({
+            cli: "cursor",
+            operation: params.operation,
+            prompt,
+            bypassRequested: highImpactRequested,
+            fullAuto: false,
+            requestedMcpServers: [],
+            policy: params.approvalPolicy,
+            metadata: {
+                model: params.model ?? "default",
+                force: Boolean(params.force),
+                trust: Boolean(params.trust),
+                sandbox: params.sandbox ?? null,
+            },
+            reviewIntegrity,
+        });
+        if (approvalDecision.status !== "approved") {
+            return createApprovalDeniedResponse(params.operation, approvalDecision);
+        }
+    }
+    if (params.optimizePrompt)
+        prompt = optimizePromptText(prompt);
+    const resolvedModel = resolveModelAlias("cursor", params.model, getCliInfo());
+    const args = ["--print"];
+    const outputFormat = params.outputFormat ?? "text";
+    if (outputFormat !== "text")
+        args.push("--output-format", outputFormat);
+    if (resolvedModel)
+        args.push("--model", resolvedModel);
+    if (params.mode)
+        args.push("--mode", params.mode);
+    if (params.force)
+        args.push("--force");
+    if (params.autoReview)
+        args.push("--auto-review");
+    if (params.sandbox)
+        args.push("--sandbox", params.sandbox);
+    if (params.trust)
+        args.push("--trust");
+    if (params.workspace)
+        args.push("--workspace", params.workspace);
+    for (const dir of params.addDir ?? [])
+        args.push("--add-dir", dir);
+    args.push(prompt);
+    return {
+        corrId,
+        effectivePrompt: prompt,
+        resolvedModel,
+        requestedMcpServers: [],
+        approvalDecision,
+        reviewIntegrity,
+        args,
+        stablePrefixHash: null,
+        stablePrefixTokens: null,
+    };
+}
+function rejectUnsupportedCursorAcpParams(params, operation) {
+    const unsupported = [];
+    if (params.mode)
+        unsupported.push("mode");
+    if (params.outputFormat && params.outputFormat !== "text")
+        unsupported.push("outputFormat");
+    if (params.force)
+        unsupported.push("force");
+    if (params.autoReview)
+        unsupported.push("autoReview");
+    if (params.sandbox)
+        unsupported.push("sandbox");
+    if (params.trust)
+        unsupported.push("trust");
+    if (params.workspace)
+        unsupported.push("workspace");
+    if ((params.addDir ?? []).length > 0)
+        unsupported.push("addDir");
+    if (params.resumeLatest)
+        unsupported.push("resumeLatest");
+    if (params.createNewSession)
+        unsupported.push("createNewSession");
+    if (params.optimizePrompt)
+        unsupported.push("optimizePrompt");
+    if (params.optimizeResponse)
+        unsupported.push("optimizeResponse");
+    if (params.forceRefresh)
+        unsupported.push("forceRefresh");
+    if (unsupported.length === 0)
+        return null;
+    return createErrorResponse(operation, 1, "", params.correlationId, new Error(`cursor_request transport=acp does not support these Cursor CLI-only options yet: ${unsupported.join(", ")}. Omit them or use transport=cli.`));
+}
+export async function handleCursorRequest(deps, params) {
+    if (params.transport === "acp") {
+        const unsupported = rejectUnsupportedCursorAcpParams(params, "cursor_request");
+        if (unsupported)
+            return unsupported;
+        return runAcpTransport(deps, {
+            provider: "cursor",
+            prompt: params.prompt,
+            model: params.model,
+            sessionId: params.sessionId,
+            correlationId: params.correlationId,
+        });
+    }
+    const runtime = resolveHandlerRuntime(deps);
+    const startTime = Date.now();
+    const prep = prepareCursorRequest({
+        prompt: params.prompt,
+        model: params.model,
+        mode: params.mode,
+        outputFormat: params.outputFormat,
+        force: params.force,
+        autoReview: params.autoReview,
+        sandbox: params.sandbox,
+        trust: params.trust,
+        workspace: params.workspace,
+        addDir: params.addDir,
+        approvalStrategy: params.approvalStrategy,
+        approvalPolicy: params.approvalPolicy,
+        correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt,
+        operation: "cursor_request",
+    }, runtime);
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    let durationMs = 0;
+    let wasSuccessful = false;
+    safeFlightStart({
+        correlationId: corrId,
+        cli: "cursor",
+        model: prep.resolvedModel || "default",
+        prompt: prep.effectivePrompt,
+        sessionId: params.sessionId,
+    }, runtime);
+    try {
+        const sessionResult = resolveGrokSessionArgs({
+            sessionId: params.sessionId,
+            resumeLatest: params.resumeLatest,
+            createNewSession: params.createNewSession,
+        });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "cursor");
+        }
+        args.splice(args.length - 1, 0, ...sessionResult.resumeArgs);
+        let worktreeResolution = {};
+        try {
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "cursor",
+                workspace: params.workspace,
+                sessionId: sessionResult.effectiveSessionId,
+                runtime,
+                addDir: params.addDir,
+            });
+        }
+        catch (err) {
+            return createErrorResponse("cursor_request", 1, "", corrId, err);
+        }
+        if (worktreeResolution.workspace && params.workspace) {
+            const workspaceFlagIndex = args.indexOf("--workspace");
+            if (workspaceFlagIndex >= 0 && workspaceFlagIndex + 1 < args.length) {
+                args[workspaceFlagIndex + 1] = worktreeResolution.workspace.cwd;
+            }
+        }
+        const cursorFrHandoff = buildAsyncFlightRecorderHandoff("cursor", prep, params.sessionId, params.outputFormat);
+        const result = await awaitJobOrDefer("cursor", args, corrId, resolveIdleTimeout("cursor", params.idleTimeoutMs), params.outputFormat, params.forceRefresh, runtime, undefined, undefined, cursorFrHandoff.flightRecorderEntry, cursorFrHandoff.extractUsage, undefined, worktreeResolution.cwd);
+        if (isDeferredResponse(result)) {
+            return buildDeferredToolResponse(result, sessionResult.effectiveSessionId);
+        }
+        const { stdout, stderr, code } = result;
+        durationMs = Math.max(0, Date.now() - startTime);
+        if (code !== 0) {
+            safeFlightComplete(corrId, {
+                response: stderr || "",
+                durationMs,
+                retryCount: 0,
+                circuitBreakerState: "closed",
+                optimizationApplied: false,
+                exitCode: code,
+                errorMessage: stderr || `Exit code ${code}`,
+                status: "failed",
+            }, runtime);
+            return createErrorResponse("cursor", code, stderr, corrId);
+        }
+        wasSuccessful = true;
+        let effectiveSessionId = sessionResult.effectiveSessionId;
+        if (sessionResult.userProvidedSession && effectiveSessionId) {
+            const existing = await deps.sessionManager.getSession(effectiveSessionId);
+            if (!existing) {
+                try {
+                    await deps.sessionManager.createSession("cursor", "Cursor 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("cursor", "Cursor Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            effectiveSessionId = newSession.id;
+        }
+        const response = buildCliResponse("cursor", stdout, params.optimizeResponse ?? false, corrId, effectiveSessionId, prep, durationMs, sessionResult.userProvidedSession, params.outputFormat);
+        safeFlightComplete(corrId, {
+            response: stdout,
+            durationMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: params.optimizePrompt || (params.optimizeResponse ?? false),
+            exitCode: 0,
+            status: "completed",
+        }, runtime);
+        return response;
+    }
+    catch (error) {
+        const elapsedMs = Math.max(0, Date.now() - startTime);
+        safeFlightComplete(corrId, {
+            response: "",
+            durationMs: elapsedMs,
+            retryCount: 0,
+            circuitBreakerState: "closed",
+            optimizationApplied: false,
+            exitCode: 1,
+            errorMessage: error.message,
+            status: "failed",
+        }, runtime);
+        return createErrorResponse("cursor", 1, "", corrId, error);
+    }
+    finally {
+        runtime.performanceMetrics.recordRequest("cursor", Math.max(0, durationMs || Date.now() - startTime), wasSuccessful);
+    }
+}
+export async function handleCursorRequestAsync(deps, params) {
+    const runtime = resolveHandlerRuntime(deps);
+    const prep = prepareCursorRequest({
+        prompt: params.prompt,
+        model: params.model,
+        mode: params.mode,
+        outputFormat: params.outputFormat,
+        force: params.force,
+        autoReview: params.autoReview,
+        sandbox: params.sandbox,
+        trust: params.trust,
+        workspace: params.workspace,
+        addDir: params.addDir,
+        approvalStrategy: params.approvalStrategy,
+        approvalPolicy: params.approvalPolicy,
+        correlationId: params.correlationId,
+        optimizePrompt: params.optimizePrompt,
+        operation: "cursor_request_async",
+    }, runtime);
+    if (!("args" in prep))
+        return prep;
+    const { corrId, args } = prep;
+    try {
+        const sessionResult = resolveGrokSessionArgs({
+            sessionId: params.sessionId,
+            resumeLatest: params.resumeLatest,
+            createNewSession: params.createNewSession,
+        });
+        if (sessionResult.userProvidedSession) {
+            await getExistingSessionForProvider(deps.sessionManager, sessionResult.effectiveSessionId, "cursor");
+        }
+        args.splice(args.length - 1, 0, ...sessionResult.resumeArgs);
+        let effectiveSessionId = sessionResult.effectiveSessionId;
+        if (sessionResult.userProvidedSession && effectiveSessionId) {
+            const existing = await deps.sessionManager.getSession(effectiveSessionId);
+            if (!existing) {
+                try {
+                    await deps.sessionManager.createSession("cursor", "Cursor 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("cursor", "Cursor Session", `${GATEWAY_SESSION_PREFIX}${randomUUID()}`);
+            effectiveSessionId = newSession.id;
+        }
+        let worktreeResolution = {};
+        try {
+            worktreeResolution = await resolveWorkspaceAndWorktreeForRequest({
+                provider: "cursor",
+                workspace: params.workspace,
+                sessionId: effectiveSessionId,
+                runtime,
+                addDir: params.addDir,
+            });
+        }
+        catch (err) {
+            return createErrorResponse("cursor_request_async", 1, "", corrId, err);
+        }
+        if (worktreeResolution.workspace && params.workspace) {
+            const workspaceFlagIndex = args.indexOf("--workspace");
+            if (workspaceFlagIndex >= 0 && workspaceFlagIndex + 1 < args.length) {
+                args[workspaceFlagIndex + 1] = worktreeResolution.workspace.cwd;
+            }
+        }
+        assertUpstreamCliArgs("cursor", args);
+        assertUpstreamCliEnv("cursor", undefined);
+        const cursorAsyncFrHandoff = buildAsyncFlightRecorderHandoff("cursor", prep, effectiveSessionId, params.outputFormat);
+        const job = deps.asyncJobManager.startJob("cursor", args, corrId, worktreeResolution.cwd, resolveIdleTimeout("cursor", params.idleTimeoutMs), params.outputFormat, params.forceRefresh, undefined, undefined, cursorAsyncFrHandoff.flightRecorderEntry, cursorAsyncFrHandoff.extractUsage, true);
+        deps.logger.info(`[${corrId}] cursor_request_async started job ${job.id}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        job,
+                        sessionId: effectiveSessionId || null,
+                        resumable: sessionResult.userProvidedSession,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return createErrorResponse("cursor_request_async", 1, "", corrId, error);
+    }
+}
 export async function handleMistralRequest(deps, params) {
     if (params.transport === "acp") {
         return runAcpTransport(deps, {
@@ -4393,7 +4736,11 @@ export function createGatewayServer(deps = {}) {
             const claudeSyncFrHandoff = buildAsyncFlightRecorderHandoff("claude", prep, effectiveSessionId, outputFormat);
             const result = await awaitJobOrDefer("claude", args, corrId, effectiveIdleTimeout, outputFormat, forceRefresh, runtime, undefined, undefined, claudeSyncFrHandoff.flightRecorderEntry, claudeSyncFrHandoff.extractUsage, prep.stdinPayload, worktreeResolution.cwd);
             if (isDeferredResponse(result)) {
-                return buildDeferredToolResponse(result, effectiveSessionId);
+                const deferred = buildDeferredToolResponse(result, effectiveSessionId);
+                if (warnings.length > 0) {
+                    deferred.warnings = warnings;
+                }
+                return deferred;
             }
             const { stdout, stderr, code } = result;
             durationMs = Math.max(0, Date.now() - startTime);
@@ -5215,6 +5562,108 @@ export function createGatewayServer(deps = {}) {
             forceRefresh,
         });
     });
+    server.tool("cursor_request", "Run a Cursor Agent CLI request synchronously (auto-defers to a pollable job past the sync deadline when async jobs are enabled; otherwise runs to completion). Headless print mode (`cursor-agent --print`).", {
+        prompt: z
+            .string()
+            .min(1, "Prompt cannot be empty")
+            .max(100000, "Prompt too long (max 100k chars)")
+            .describe("Prompt text for Cursor Agent CLI"),
+        model: z.string().optional().describe("Model name or alias passed via --model"),
+        mode: z
+            .enum(["plan", "ask"])
+            .optional()
+            .describe("Cursor execution mode: plan (read-only planning) or ask (Q&A/read-only)"),
+        outputFormat: z
+            .enum(["text", "json", "stream-json"])
+            .default("text")
+            .describe("Cursor --output-format for --print mode"),
+        transport: z
+            .enum(["cli", "acp"])
+            .default("cli")
+            .describe("Transport selector. Default `cli` uses cursor-agent --print. `acp` uses the native cursor-agent acp transport and fails closed unless [acp] and [acp.providers.cursor].runtime_enabled are true."),
+        force: z
+            .boolean()
+            .default(false)
+            .describe("Emit --force (Cursor yolo mode; auto-allows commands unless explicitly denied)"),
+        autoReview: z
+            .boolean()
+            .default(false)
+            .describe("Emit --auto-review (Cursor Smart Auto classifier for tool calls)"),
+        sandbox: z
+            .enum(["enabled", "disabled"])
+            .optional()
+            .describe("Cursor sandbox mode override (--sandbox enabled|disabled)"),
+        trust: z.boolean().default(false).describe("Trust the workspace in headless mode (--trust)"),
+        workspace: z
+            .string()
+            .optional()
+            .describe("Workspace directory or saved workspace name (--workspace). Remote HTTP/OAuth callers must pass a registered workspace alias; local stdio callers may pass local Cursor workspace paths."),
+        addDir: z
+            .array(z.string())
+            .optional()
+            .describe("Additional workspace root directories (--add-dir, repeatable)"),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Cursor chat/session ID to resume (emits --resume <id>). Note: the gw-* id minted for a brand-new gateway session is not resumable via sessionId; continue with resumeLatest:true."),
+        resumeLatest: z
+            .boolean()
+            .default(false)
+            .describe("Resume the latest Cursor chat (--continue). Note: the gw-* id minted for a brand-new gateway session is not resumable via sessionId; continue with resumeLatest:true."),
+        createNewSession: z.boolean().default(false).describe("Force a new session"),
+        approvalStrategy: z
+            .enum(["legacy", "mcp_managed"])
+            .default("legacy")
+            .describe("Approval strategy: legacy (default) lets Cursor's own flags decide; mcp_managed routes high-impact Cursor controls (force, trust, sandbox disabled) through the gateway approval gate."),
+        approvalPolicy: z
+            .enum(["strict", "balanced", "permissive"])
+            .optional()
+            .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
+        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"),
+    }, {
+        title: "Cursor Agent CLI request",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    }, async ({ prompt, model, mode, outputFormat, transport, force, autoReview, sandbox, trust, workspace, addDir, sessionId, resumeLatest, createNewSession, approvalStrategy, approvalPolicy, correlationId, optimizePrompt, optimizeResponse, idleTimeoutMs, forceRefresh, }) => {
+        return handleCursorRequest({ sessionManager, logger, runtime }, {
+            prompt,
+            model,
+            mode,
+            outputFormat,
+            transport,
+            force,
+            autoReview,
+            sandbox,
+            trust,
+            workspace,
+            addDir,
+            sessionId,
+            resumeLatest,
+            createNewSession,
+            approvalStrategy,
+            approvalPolicy,
+            correlationId,
+            optimizePrompt,
+            optimizeResponse,
+            idleTimeoutMs,
+            forceRefresh,
+        });
+    });
     server.tool("mistral_request", "Run a Mistral Vibe CLI request synchronously (when async jobs are enabled, auto-defers to a pollable job past the sync deadline; otherwise runs to completion). Requires exactly one of prompt or promptParts. Defaults to --agent auto-approve (unattended tool execution); pass permissionMode plan or accept-edits for safer runs.", {
         prompt: z
             .string()
@@ -6186,6 +6635,101 @@ export function createGatewayServer(deps = {}) {
                 forceRefresh,
             });
         });
+        server.tool("cursor_request_async", "Start a Cursor Agent CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
+            prompt: z
+                .string()
+                .min(1, "Prompt cannot be empty")
+                .max(100000, "Prompt too long (max 100k chars)")
+                .describe("Prompt text for Cursor Agent CLI"),
+            model: z.string().optional().describe("Model name or alias passed via --model"),
+            mode: z
+                .enum(["plan", "ask"])
+                .optional()
+                .describe("Cursor execution mode: plan (read-only planning) or ask (Q&A/read-only)"),
+            outputFormat: z
+                .enum(["text", "json", "stream-json"])
+                .default("text")
+                .describe("Cursor --output-format for --print mode"),
+            force: z
+                .boolean()
+                .default(false)
+                .describe("Emit --force (Cursor yolo mode; auto-allows commands unless explicitly denied)"),
+            autoReview: z
+                .boolean()
+                .default(false)
+                .describe("Emit --auto-review (Cursor Smart Auto classifier for tool calls)"),
+            sandbox: z
+                .enum(["enabled", "disabled"])
+                .optional()
+                .describe("Cursor sandbox mode override (--sandbox enabled|disabled)"),
+            trust: z.boolean().default(false).describe("Trust the workspace in headless mode"),
+            workspace: z
+                .string()
+                .optional()
+                .describe("Workspace directory or saved workspace name (--workspace). Remote HTTP/OAuth callers must pass a registered workspace alias; local stdio callers may pass local Cursor workspace paths."),
+            addDir: z
+                .array(z.string())
+                .optional()
+                .describe("Additional workspace root directories (--add-dir, repeatable)"),
+            sessionId: z
+                .string()
+                .optional()
+                .describe("Cursor chat/session ID to resume (emits --resume <id>). Note: the gw-* id minted for a brand-new gateway session is not resumable via sessionId; continue with resumeLatest:true."),
+            resumeLatest: z
+                .boolean()
+                .default(false)
+                .describe("Resume the latest Cursor chat (--continue). Note: the gw-* id minted for a brand-new gateway session is not resumable via sessionId; continue with resumeLatest:true."),
+            createNewSession: z.boolean().default(false).describe("Force a new session"),
+            approvalStrategy: z
+                .enum(["legacy", "mcp_managed"])
+                .default("legacy")
+                .describe("Approval strategy: legacy (default) lets Cursor's own flags decide; mcp_managed routes high-impact Cursor controls (force, trust, sandbox disabled) through the gateway approval gate."),
+            approvalPolicy: z
+                .enum(["strict", "balanced", "permissive"])
+                .optional()
+                .describe("Approval policy when approvalStrategy is mcp_managed: strict|balanced|permissive (default balanced). Ignored under legacy strategy."),
+            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"),
+        }, {
+            title: "Cursor Agent CLI request (async)",
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        }, async ({ prompt, model, mode, outputFormat, force, autoReview, sandbox, trust, workspace, addDir, sessionId, resumeLatest, createNewSession, approvalStrategy, approvalPolicy, correlationId, optimizePrompt, idleTimeoutMs, forceRefresh, }) => {
+            return handleCursorRequestAsync({ sessionManager, asyncJobManager, logger, runtime }, {
+                prompt,
+                model,
+                mode,
+                outputFormat,
+                force,
+                autoReview,
+                sandbox,
+                trust,
+                workspace,
+                addDir,
+                sessionId,
+                resumeLatest,
+                createNewSession,
+                approvalStrategy,
+                approvalPolicy,
+                correlationId,
+                optimizePrompt,
+                idleTimeoutMs,
+                forceRefresh,
+            });
+        });
         server.tool("mistral_request_async", "Start a Mistral Vibe CLI request as a durable background job. Poll with llm_job_status, collect with llm_job_result.", {
             prompt: z
                 .string()
@@ -6655,10 +7199,10 @@ export function createGatewayServer(deps = {}) {
     const listModelsFilterValues = [
         ...new Set([...CLI_TYPES, ...enabledApiProviders(providers).map(p => p.name)]),
     ];
-    server.tool("list_models", "List models, aliases, and defaults for one provider (claude|codex|gemini|grok|mistral|devin, or an enabled API provider name), or omit cli to list all providers. API providers are returned under an `apiProviders` array.", {
+    server.tool("list_models", "List models, aliases, and defaults for one provider (claude|codex|gemini|grok|mistral|devin|cursor, or an enabled API provider name), or omit cli to list all providers. API providers are returned under an `apiProviders` array.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(listModelsFilterValues).optional())
-            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin, or an enabled API provider name)"),
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|cursor, or an enabled API provider name)"),
     }, {
         title: "Provider models",
         readOnlyHint: true,
@@ -6689,10 +7233,10 @@ export function createGatewayServer(deps = {}) {
             ...enabledApiProviders(providers).map(p => p.name),
         ]),
     ];
-    server.tool("provider_tool_capabilities", "Report provider tool/feature capabilities and discovered local skill/tool integrations for claude|codex|gemini|grok|mistral|devin|grok_api, or an enabled API provider name.", {
+    server.tool("provider_tool_capabilities", "Report provider tool/feature capabilities and discovered local skill/tool integrations for claude|codex|gemini|grok|mistral|devin|cursor|grok_api, or an enabled API provider name.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(providerToolCapabilitiesFilterValues).optional())
-            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|grok_api, or an enabled API provider name)"),
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|cursor|grok_api, or an enabled API provider name)"),
         includeSkills: z
             .boolean()
             .default(true)
@@ -6728,10 +7272,10 @@ export function createGatewayServer(deps = {}) {
         });
         return { content: [{ type: "text", text: JSON.stringify(capabilities, null, 2) }] };
     });
-    server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all six providers (claude|codex|gemini|grok|mistral|devin) or one.", {
+    server.tool("cli_versions", "Report installed provider CLI versions, availability, and login status for all registered CLI providers (claude|codex|gemini|grok|mistral|devin|cursor) or one.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
+            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin|cursor)"),
     }, {
         title: "Provider CLI versions",
         readOnlyHint: true,
@@ -6745,7 +7289,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("upstream_contracts", "Return the gateway's declared provider CLI contracts; with probeInstalled true, diff against installed --help surfaces to detect flag drift.", {
         cli: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
+            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin|cursor)"),
         probeInstalled: z
             .boolean()
             .default(false)
@@ -6763,7 +7307,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("provider_subcommands_list", "Return a compact, filterable read-only catalog of declared provider CLI subcommands without flags or raw help.", {
         provider: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin)"),
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin|cursor)"),
         tier: z
             .enum(["catalog", "inspect", "execute_candidate", "diagnostic"])
             .optional()
@@ -6813,7 +7357,7 @@ export function createGatewayServer(deps = {}) {
         };
     });
     server.tool("provider_subcommand_contract", "Return the detailed read-only contract for exactly one declared provider CLI subcommand.", {
-        provider: CLI_TYPE_ENUM.describe("Provider (claude|codex|gemini|grok|mistral|devin)"),
+        provider: CLI_TYPE_ENUM.describe("Provider (claude|codex|gemini|grok|mistral|devin|cursor)"),
         commandPath: z.array(z.string().min(1)).min(1).describe("Command path segments"),
     }, {
         title: "Provider subcommand contract",
@@ -6837,7 +7381,7 @@ export function createGatewayServer(deps = {}) {
     server.tool("provider_subcommand_drift", "Probe declared provider subcommand --help surfaces and return compact drift rows without raw help output.", {
         provider: z
             .preprocess(value => (value === "" || value === null ? undefined : value), CLI_TYPE_ENUM.optional())
-            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin)"),
+            .describe("Optional provider filter (claude|codex|gemini|grok|mistral|devin|cursor)"),
         includeClean: z
             .boolean()
             .default(false)
@@ -6888,7 +7432,7 @@ export function createGatewayServer(deps = {}) {
         };
     });
     server.tool("cli_upgrade", "Plan (dryRun, default true) or execute an upgrade for one provider CLI using its native update mechanism.", {
-        cli: CLI_TYPE_ENUM.describe("CLI to upgrade (claude|codex|gemini|grok|mistral|devin)"),
+        cli: CLI_TYPE_ENUM.describe("CLI to upgrade (claude|codex|gemini|grok|mistral|devin|cursor)"),
         target: z
             .string()
             .min(1)