llm-cli-gateway 2.12.1 → 2.13.0

package/dist/index.js

@@ -18,7 +18,7 @@ import { createWorktree, createWorktreeSessionCleanupHook, } from "./worktree-ma
 import { ResourceProvider } from "./resources.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, loadLimitsConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
 import { runAcpRequest } from "./acp/runtime.js";
 import { isAcpError } from "./acp/errors.js";
 import { createApiProvider, runApiRequest, apiProviderBreakerState, } from "./api-provider.js";
@@ -26,7 +26,7 @@ import { prepareApiRequest, apiProviderCatalogEntry, ApiModelNotAllowedError, }
 import { checkHealth } from "./health.js";
 import { clearModelRegistryCache, getAvailableCliInfo, getCliInfo, resolveModelAlias, } from "./model-registry.js";
 import { getProviderToolCapabilities } from "./provider-tool-capabilities.js";
-import { AsyncJobManager, extractApiHttpStatus, extractApiErrorBody, } from "./async-job-manager.js";
+import { AsyncJobManager, JobSaturationError, isAsyncJobInProgress, extractApiHttpStatus, extractApiErrorBody, } from "./async-job-manager.js";
 import { createJobStore } from "./job-store.js";
 import { ApprovalManager, bypassAllowedByOperator, } from "./approval-manager.js";
 import { checkReviewIntegrity } from "./review-integrity.js";
@@ -39,6 +39,7 @@ import { getCliVersions, runCliUpgrade } from "./cli-updater.js";
 import { startHttpGateway } from "./http-transport.js";
 import { getRequestContext, resolveOwnerPrincipal, principalCanAccess } from "./request-context.js";
 import { printDoctorJson } from "./doctor.js";
+import { redactDiagnosticUrl } from "./endpoint-exposure.js";
 import { createWorkspace, describeWorkspace, getWorkspace, loadWorkspaceRegistry, registerExistingWorkspace, resolveWorkspaceForProvider, validatePathInsideWorkspace, } from "./workspace-registry.js";
 import { generateSecret, hashSecret } from "./oauth.js";
 import { registerValidationTools } from "./validation-tools.js";
@@ -161,16 +162,17 @@ 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)
-Workspaces: workspace_create, workspace_list, workspace_get, workspace_register_existing_repo
+Workspaces: workspace_create, workspace_list, workspace_get, workspace_register_existing_repo (remote HTTP/OAuth workspace registry only; do not use workspace_* to fix stdio/local provider path access)
 
 Key behaviors:
 ${deferralLine}
 - Sessions: Claude --continue, Gemini (Antigravity) --conversation <id>/--continue, Grok --resume/--continue, Mistral --resume/--continue (current Vibe defaults session logging on; doctor flags explicit session_logging.enabled=false), Codex \`exec resume <ID>\` / \`exec resume --last\`, Devin --resume <id>/--continue (all real CLI continuity). For Codex, sessionId must be a real Codex UUID (from ~/.codex/sessions/); gateway-generated gw-* IDs are rejected.
 - Approval gates: opt-in via approvalStrategy:"mcp_managed".
+- Stdio/local provider calls may pass local workingDir/addDir/includeDirs directly. Workspace aliases are for remote HTTP/OAuth calls and must not be used as a fallback after a stdio provider path error.
 - Upstream drift detection: After upgrading any provider CLI (especially grok), use upstream_contracts with probeInstalled:true and provider_subcommand_drift for declared subcommand help surfaces. Probes are safe, read-only --help checks.
 - Idle timeout kills stuck processes (default 10min, configurable via idleTimeoutMs).
 
@@ -189,6 +191,7 @@ let persistenceConfig = null;
 let cacheAwarenessConfig = null;
 let providersConfig = null;
 let acpConfig = null;
+let limitsConfig = null;
 let jobStore = null;
 let jobStoreInitialized = false;
 let asyncJobManager = null;
@@ -201,6 +204,10 @@ function getPersistenceConfig(runtimeLogger = logger) {
     persistenceConfig ??= loadPersistenceConfig(runtimeLogger);
     return persistenceConfig;
 }
+function getLimitsConfig(runtimeLogger = logger) {
+    limitsConfig ??= loadLimitsConfig(runtimeLogger);
+    return limitsConfig;
+}
 function getAcpConfig(runtimeLogger = logger) {
     acpConfig ??= loadAcpConfig(runtimeLogger);
     return acpConfig;
@@ -229,7 +236,7 @@ function getJobStore(runtimeLogger = logger) {
 function newAsyncJobManager(metrics, runtimeLogger, store = getJobStore(runtimeLogger), fr = getFlightRecorder(runtimeLogger)) {
     return new AsyncJobManager(runtimeLogger, (cli, durationMs, success) => {
         metrics.recordRequest(cli, durationMs, success);
-    }, store, fr);
+    }, store, fr, getLimitsConfig(runtimeLogger).jobs);
 }
 function getAsyncJobManager(runtimeLogger = logger) {
     asyncJobManager ??= newAsyncJobManager(performanceMetrics, runtimeLogger);
@@ -278,7 +285,14 @@ export const WORKSPACE_ALIAS_SCHEMA = z
     .min(1)
     .max(64)
     .regex(/^[A-Za-z][A-Za-z0-9._-]{0,63}$/)
-    .describe("Registered workspace alias. Remote clients use aliases, not absolute paths.");
+    .describe("Registered workspace alias for remote HTTP/OAuth provider calls. Stdio/local callers should not use workspace_* tools to fix provider path access; pass local workingDir/addDir/includeDirs directly.");
+const PROVIDER_WORKSPACE_FIELD_DESCRIPTION = "Registered workspace alias for remote HTTP/OAuth provider calls. Do not use this field, workspace_list, or workspace_register_existing_repo as a fallback for stdio/local provider path access; pass workingDir/addDir/includeDirs directly instead.";
+const LOCAL_WORKING_DIR_FIELD_SUFFIX = " Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access.";
+const LOCAL_ADD_DIR_FIELD_SUFFIX = " Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access.";
+const LOCAL_INCLUDE_DIRS_FIELD_SUFFIX = " Stdio/local callers may pass local paths directly. Remote HTTP/OAuth callers must use relative paths inside a selected registered workspace. Do not call workspace_* tools to fix stdio/local provider path access.";
+function providerWorkspaceAliasSchema() {
+    return WORKSPACE_ALIAS_SCHEMA.describe(PROVIDER_WORKSPACE_FIELD_DESCRIPTION).optional();
+}
 export const SESSION_PROVIDER_VALUES = PROVIDER_TYPES;
 export const SESSION_PROVIDER_ENUM = z.enum(SESSION_PROVIDER_VALUES);
 export function sessionProviderValuesFor(providers) {
@@ -307,7 +321,7 @@ export function resolveGatewayServerRuntime(deps = {}, options = {}) {
         sessionManager: runtimeSessionManager,
         resourceProvider: deps.resourceProvider ??
             (options.isolateState
-                ? new ResourceProvider(runtimeSessionManager, runtimePerformanceMetrics, runtimeFlightRecorder, deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger))
+                ? new ResourceProvider(runtimeSessionManager, runtimePerformanceMetrics, runtimeFlightRecorder, deps.cacheAwareness ?? getCacheAwarenessConfig(runtimeLogger), deps.providers ?? getProvidersConfig(runtimeLogger))
                 : resourceProvider),
         db: "db" in deps ? (deps.db ?? null) : db,
         performanceMetrics: runtimePerformanceMetrics,
@@ -331,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)
@@ -402,6 +417,14 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
         runtime.asyncJobManager.hasStore();
     if (SYNC_DEADLINE_MS === 0 || !deferralAvailable) {
         const command = providerCommandName(cli);
+        let slot;
+        try {
+            slot = await runtime.asyncJobManager.acquireProcessSlot(cli);
+        }
+        catch (err) {
+            consumeOnComplete();
+            throw err;
+        }
         try {
             return await executeCli(command, args, {
                 idleTimeout: idleTimeoutMs,
@@ -412,6 +435,7 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
             });
         }
         finally {
+            slot.release();
             consumeOnComplete();
         }
     }
@@ -441,7 +465,7 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
     const deadline = Date.now() + SYNC_DEADLINE_MS;
     while (Date.now() < deadline) {
         const snapshot = runtime.asyncJobManager.getJobSnapshot(job.id);
-        if (snapshot && snapshot.status !== "running") {
+        if (snapshot && !isAsyncJobInProgress(snapshot.status)) {
             const result = runtime.asyncJobManager.getJobResult(job.id);
             if (!result) {
                 return { stdout: "", stderr: "Job result unavailable", code: 1 };
@@ -481,6 +505,14 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
         runtime.persistence.asyncJobsEnabled &&
         runtime.asyncJobManager.hasStore();
     if (SYNC_DEADLINE_MS === 0 || !deferralAvailable || forceInline) {
+        let slot;
+        try {
+            slot = await runtime.asyncJobManager.acquireProcessSlot(provider.name);
+        }
+        catch (err) {
+            consumeOnComplete();
+            throw err;
+        }
         try {
             const result = await runApiRequest(provider, apiRequest, runtime.logger);
             return {
@@ -504,6 +536,7 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
             };
         }
         finally {
+            slot.release();
             consumeOnComplete();
         }
     }
@@ -531,7 +564,7 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
     const deadline = Date.now() + SYNC_DEADLINE_MS;
     while (Date.now() < deadline) {
         const snapshot = runtime.asyncJobManager.getJobSnapshot(job.id);
-        if (snapshot && snapshot.status !== "running") {
+        if (snapshot && !isAsyncJobInProgress(snapshot.status)) {
             const result = runtime.asyncJobManager.getJobResult(job.id);
             if (!result)
                 return { stdout: "", stderr: "Job result unavailable", code: 1 };
@@ -678,38 +711,50 @@ function workspaceAdminEnabled() {
     const scopes = getRequestContext()?.authScopes ?? [];
     return process.env.LLM_GATEWAY_WORKSPACE_ADMIN === "1" && scopes.includes("workspace:admin");
 }
+function assertWorkspaceToolCaller(toolName) {
+    const context = getRequestContext();
+    if (context?.transport === "http" || context?.authKind === "oauth")
+        return;
+    throw new Error(`${toolName} is only for remote HTTP/OAuth workspace clients. Stdio/local provider calls must not use workspace_* tools for path access; pass workingDir/addDir/includeDirs directly on the provider request instead.`);
+}
 function registerWorkspaceTools(server, runtime) {
-    server.tool("workspace_list", "List registered workspace aliases and summary metadata. Does not browse files.", {}, {
+    server.tool("workspace_list", "List registered workspace aliases for remote HTTP/OAuth provider calls. Does not browse files. Stdio/local callers should not use workspace_* tools to fix provider path access; pass local workingDir/addDir/includeDirs directly.", {}, {
         title: "List workspaces",
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     }, async () => {
-        const registry = loadWorkspaceRegistry(runtime.logger);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        success: true,
-                        enabled: registry.enabled,
-                        default: registry.defaultAlias,
-                        workspaces: registry.repos.map(describeWorkspace),
-                        allowed_roots: registry.allowedRoots.map(root => ({
-                            alias: root.alias,
-                            path: root.path,
-                            allow_register_existing_git_repos: root.allowRegisterExistingGitRepos,
-                            allow_create_directories: root.allowCreateDirectories,
-                            allow_init_git_repos: root.allowInitGitRepos,
-                            max_create_depth: root.maxCreateDepth,
-                        })),
-                    }, null, 2),
-                },
-            ],
-        };
+        try {
+            assertWorkspaceToolCaller("workspace_list");
+            const registry = loadWorkspaceRegistry(runtime.logger);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            enabled: registry.enabled,
+                            default: registry.defaultAlias,
+                            workspaces: registry.repos.map(describeWorkspace),
+                            allowed_roots: registry.allowedRoots.map(root => ({
+                                alias: root.alias,
+                                path: root.path,
+                                allow_register_existing_git_repos: root.allowRegisterExistingGitRepos,
+                                allow_create_directories: root.allowCreateDirectories,
+                                allow_init_git_repos: root.allowInitGitRepos,
+                                max_create_depth: root.maxCreateDepth,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return createErrorResponse("workspace_list", 1, "", undefined, error);
+        }
     });
-    server.tool("workspace_get", "Inspect a registered workspace alias. Does not list files.", { alias: WORKSPACE_ALIAS_SCHEMA }, {
+    server.tool("workspace_get", "Inspect a registered remote HTTP/OAuth workspace alias. Does not list files. Not needed for stdio/local provider calls; do not use workspace_* tools to fix local path access.", { alias: WORKSPACE_ALIAS_SCHEMA }, {
         title: "Get workspace",
         readOnlyHint: true,
         destructiveHint: false,
@@ -717,6 +762,7 @@ function registerWorkspaceTools(server, runtime) {
         openWorldHint: false,
     }, async ({ alias }) => {
         try {
+            assertWorkspaceToolCaller("workspace_get");
             const registry = loadWorkspaceRegistry(runtime.logger);
             return {
                 content: [
@@ -731,7 +777,7 @@ function registerWorkspaceTools(server, runtime) {
             return createErrorResponse("workspace_get", 1, "", undefined, error);
         }
     });
-    server.tool("workspace_create", "Create a new local folder or git repo under a configured allowed root. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
+    server.tool("workspace_create", "Create a remote HTTP/OAuth workspace alias by creating a new local folder or git repo under a configured allowed root. Not for stdio/local provider path access. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
         alias: WORKSPACE_ALIAS_SCHEMA,
         root: WORKSPACE_ALIAS_SCHEMA.describe("Allowed-root alias from workspace_list."),
         slug: z.string().min(1).max(255).describe("Safe relative path under the allowed root."),
@@ -745,6 +791,7 @@ function registerWorkspaceTools(server, runtime) {
         openWorldHint: false,
     }, async ({ alias, root, slug, kind, setDefault }) => {
         try {
+            assertWorkspaceToolCaller("workspace_create");
             if (!workspaceAdminEnabled()) {
                 throw new Error("workspace_create requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin");
             }
@@ -769,7 +816,7 @@ function registerWorkspaceTools(server, runtime) {
             return createErrorResponse("workspace_create", 1, "", undefined, error);
         }
     });
-    server.tool("workspace_register_existing_repo", "Register an existing local Git repo under an allowed root. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
+    server.tool("workspace_register_existing_repo", "Register an existing local Git repo as a remote HTTP/OAuth workspace alias. Not for stdio/local provider path access. Requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin.", {
         alias: WORKSPACE_ALIAS_SCHEMA,
         path: z
             .string()
@@ -784,6 +831,7 @@ function registerWorkspaceTools(server, runtime) {
         openWorldHint: false,
     }, async ({ alias, path, setDefault }) => {
         try {
+            assertWorkspaceToolCaller("workspace_register_existing_repo");
             if (!workspaceAdminEnabled()) {
                 throw new Error("workspace_register_existing_repo requires LLM_GATEWAY_WORKSPACE_ADMIN=1 and OAuth scope workspace:admin");
             }
@@ -808,6 +856,23 @@ function registerWorkspaceTools(server, runtime) {
     });
 }
 export function createErrorResponse(cli, code, stderr, correlationId, error, apiError) {
+    if (error instanceof JobSaturationError) {
+        const satMessage = `${error.message}. The gateway is protecting the host from process/request ` +
+            `overload; this is transient. Retry after a short delay, or reduce concurrent requests.`;
+        logger.error(`[${correlationId || "unknown"}] ${cli} rejected: gateway at capacity`);
+        return {
+            content: [{ type: "text", text: satMessage }],
+            isError: true,
+            structuredContent: {
+                response: satMessage,
+                correlationId: correlationId || null,
+                cli,
+                exitCode: code,
+                errorCategory: "saturated",
+                retryable: true,
+            },
+        };
+    }
     let errorMessage = `Error executing ${cli} CLI`;
     const isLaunchExit = code === 127 || code === -4058;
     const isOutputOverflow = Boolean(error) && /Output exceeded maximum size/i.test(error.message);
@@ -820,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}`;
@@ -3583,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, {
@@ -4162,7 +4569,8 @@ export function createGatewayServer(deps = {}) {
         addDir: z
             .array(z.string())
             .optional()
-            .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance."),
+            .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance." +
+            LOCAL_ADD_DIR_FIELD_SUFFIX),
         noSessionPersistence: z
             .boolean()
             .optional()
@@ -4181,7 +4589,7 @@ export function createGatewayServer(deps = {}) {
             .array(z.string())
             .optional()
             .describe('Claude --tools: restrict the available built-in tool set (distinct from allowedTools permission gating). Pass [""] to disable all tools.'),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+        workspace: providerWorkspaceAliasSchema(),
         worktree: WORKTREE_SCHEMA.optional(),
         approvalStrategy: z
             .enum(["legacy", "mcp_managed"])
@@ -4328,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);
@@ -4525,12 +4937,14 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1)
             .optional()
-            .describe("Codex -C/--cd <DIR>: working root for this session. Emitted on new sessions only; resume inherits the original session's cwd via CODEX_RESUME_FILTERED_FLAGS."),
+            .describe("Codex -C/--cd <DIR>: working root for this session. Emitted on new sessions only; resume inherits the original session's cwd via CODEX_RESUME_FILTERED_FLAGS." +
+            LOCAL_WORKING_DIR_FIELD_SUFFIX),
         addDir: z
             .array(z.string())
             .optional()
-            .describe("Codex --add-dir <DIR>: additional writable workspace directories. Emitted once per entry on new sessions only; resume inherits the original session's writable-dir policy."),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+            .describe("Codex --add-dir <DIR>: additional writable workspace directories. Emitted once per entry on new sessions only; resume inherits the original session's writable-dir policy." +
+            LOCAL_ADD_DIR_FIELD_SUFFIX),
+        workspace: providerWorkspaceAliasSchema(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Codex request",
@@ -4729,7 +5143,7 @@ export function createGatewayServer(deps = {}) {
             .max(3_600_000)
             .optional()
             .describe("Idle timeout in ms (min 30s, max 1h, omit=CLI default)"),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+        workspace: providerWorkspaceAliasSchema(),
     }, {
         title: "Fork Codex session",
         readOnlyHint: false,
@@ -4853,7 +5267,7 @@ export function createGatewayServer(deps = {}) {
         includeDirs: z
             .array(z.string())
             .optional()
-            .describe("Additional workspace directories passed as --add-dir"),
+            .describe("Additional workspace directories passed as --add-dir." + LOCAL_INCLUDE_DIRS_FIELD_SUFFIX),
         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"),
@@ -4893,7 +5307,7 @@ export function createGatewayServer(deps = {}) {
             .boolean()
             .optional()
             .describe("Antigravity 1.0.13 --new-project: create a new project for this session. Mutually exclusive with project."),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+        workspace: providerWorkspaceAliasSchema(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Gemini request",
@@ -5015,7 +5429,7 @@ export function createGatewayServer(deps = {}) {
             .union([z.string().min(1), z.record(z.string(), z.unknown())])
             .optional()
             .describe("Grok 0.2.73 --json-schema: constrain output to a JSON Schema (string literal or object; implies json output). Set outputFormat:json so the gateway treats the reply as structured output (skips response optimization and warning injection); the default output format is not json, so pass it explicitly."),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+        workspace: providerWorkspaceAliasSchema(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Grok request",
@@ -5148,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()
@@ -5226,12 +5742,14 @@ export function createGatewayServer(deps = {}) {
             .string()
             .min(1)
             .optional()
-            .describe("Vibe --workdir <DIR>: change to this directory before running. Single value (Vibe accepts one --workdir per invocation)."),
+            .describe("Vibe --workdir <DIR>: change to this directory before running. Single value (Vibe accepts one --workdir per invocation)." +
+            LOCAL_WORKING_DIR_FIELD_SUFFIX),
         addDir: z
             .array(z.string())
             .optional()
-            .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance (Vibe states this flag may be specified multiple times)."),
-        workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+            .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance (Vibe states this flag may be specified multiple times)." +
+            LOCAL_ADD_DIR_FIELD_SUFFIX),
+        workspace: providerWorkspaceAliasSchema(),
         worktree: WORKTREE_SCHEMA.optional(),
     }, {
         title: "Mistral Vibe request",
@@ -5360,7 +5878,8 @@ export function createGatewayServer(deps = {}) {
             addDir: z
                 .array(z.string())
                 .optional()
-                .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance."),
+                .describe("Claude --add-dir: additional directories the CLI is allowed to read/write beyond the process cwd. Each entry is emitted as its own --add-dir instance." +
+                LOCAL_ADD_DIR_FIELD_SUFFIX),
             noSessionPersistence: z
                 .boolean()
                 .optional()
@@ -5379,7 +5898,7 @@ export function createGatewayServer(deps = {}) {
                 .array(z.string())
                 .optional()
                 .describe('Claude --tools: restrict the available built-in tool set (distinct from allowedTools permission gating). Pass [""] to disable all tools.'),
-            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+            workspace: providerWorkspaceAliasSchema(),
             worktree: WORKTREE_SCHEMA.optional(),
             approvalStrategy: z
                 .enum(["legacy", "mcp_managed"])
@@ -5629,12 +6148,14 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1)
                 .optional()
-                .describe("Codex -C/--cd <DIR>: working root for this session. New sessions only; resume inherits the original session's cwd."),
+                .describe("Codex -C/--cd <DIR>: working root for this session. New sessions only; resume inherits the original session's cwd." +
+                LOCAL_WORKING_DIR_FIELD_SUFFIX),
             addDir: z
                 .array(z.string())
                 .optional()
-                .describe("Codex --add-dir <DIR>: additional writable workspace directories (repeat per entry). New sessions only."),
-            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+                .describe("Codex --add-dir <DIR>: additional writable workspace directories (repeat per entry). New sessions only." +
+                LOCAL_ADD_DIR_FIELD_SUFFIX),
+            workspace: providerWorkspaceAliasSchema(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Codex request (async job)",
@@ -5721,7 +6242,8 @@ export function createGatewayServer(deps = {}) {
             includeDirs: z
                 .array(z.string())
                 .optional()
-                .describe("Additional workspace directories passed as --add-dir"),
+                .describe("Additional workspace directories passed as --add-dir." +
+                LOCAL_INCLUDE_DIRS_FIELD_SUFFIX),
             correlationId: z.string().optional().describe("Request trace ID (auto if omitted)"),
             optimizePrompt: z.boolean().default(false).describe("Optimize prompt before execution"),
             idleTimeoutMs: z
@@ -5760,7 +6282,7 @@ export function createGatewayServer(deps = {}) {
                 .boolean()
                 .optional()
                 .describe("Antigravity 1.0.13 --new-project: create a new project for this session. Mutually exclusive with project."),
-            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+            workspace: providerWorkspaceAliasSchema(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Gemini request (async job)",
@@ -5872,7 +6394,8 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1)
                 .optional()
-                .describe("Grok --cwd <DIR>: working directory for this invocation. Lets headless callers run Grok against a directory other than the gateway process's cwd."),
+                .describe("Grok --cwd <DIR>: working directory for this invocation. Lets headless callers run Grok against a directory other than the gateway process's cwd." +
+                LOCAL_WORKING_DIR_FIELD_SUFFIX),
             sandbox: z
                 .string()
                 .min(1)
@@ -5988,7 +6511,7 @@ export function createGatewayServer(deps = {}) {
                 .union([z.string().min(1), z.record(z.string(), z.unknown())])
                 .optional()
                 .describe("Grok 0.2.73 --json-schema: constrain output to a JSON Schema (string literal or object; implies json output). Set outputFormat:json so the gateway treats the reply as structured output (skips response optimization and warning injection); the default output format is not json, so pass it explicitly."),
-            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+            workspace: providerWorkspaceAliasSchema(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Grok request (async job)",
@@ -6112,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()
@@ -6185,12 +6803,14 @@ export function createGatewayServer(deps = {}) {
                 .string()
                 .min(1)
                 .optional()
-                .describe("Vibe --workdir <DIR>: change to this directory before running. Single value per invocation."),
+                .describe("Vibe --workdir <DIR>: change to this directory before running. Single value per invocation." +
+                LOCAL_WORKING_DIR_FIELD_SUFFIX),
             addDir: z
                 .array(z.string())
                 .optional()
-                .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance."),
-            workspace: WORKSPACE_ALIAS_SCHEMA.optional(),
+                .describe("Vibe --add-dir <DIR>: additional writable workspace directories. Each entry is emitted as its own --add-dir instance." +
+                LOCAL_ADD_DIR_FIELD_SUFFIX),
+            workspace: providerWorkspaceAliasSchema(),
             worktree: WORKTREE_SCHEMA.optional(),
         }, {
             title: "Mistral Vibe request (async job)",
@@ -6227,7 +6847,7 @@ export function createGatewayServer(deps = {}) {
                 worktree,
             });
         });
-        server.tool("llm_job_status", "Check lifecycle status (running|completed|failed|canceled|orphaned) of a gateway async or deferred-sync job by jobId.", {
+        server.tool("llm_job_status", "Check lifecycle status (queued|running|completed|failed|canceled|orphaned) of a gateway async or deferred-sync job by jobId.", {
             jobId: z.string().describe("Async job ID from *_request_async"),
         }, {
             title: "Async job status",
@@ -6447,18 +7067,22 @@ export function createGatewayServer(deps = {}) {
         openWorldHint: false,
     }, async () => {
         const health = asyncJobManager.getJobHealth();
+        const storeAttached = asyncJobManager.hasStore();
+        const asyncJobsEffective = persistence.backend !== "none" && persistence.asyncJobsEnabled && storeAttached;
         const persistenceBlock = {
             backend: persistence.backend,
             dbPath: persistence.path,
             dsn: persistence.dsn ? "[redacted]" : null,
             retentionDays: persistence.retentionDays,
             dedupWindowMs: persistence.dedupWindowMs,
-            asyncJobsEnabled: persistence.asyncJobsEnabled,
+            asyncJobsEnabled: asyncJobsEffective,
             acknowledgeEphemeral: persistence.acknowledgeEphemeral,
             sources: persistence.sources,
-            warning: persistence.asyncJobsEnabled
+            warning: asyncJobsEffective
                 ? null
-                : "Async job persistence is disabled (backend = 'none'). *_request_async tools are NOT registered on this gateway. Set [persistence].backend = 'sqlite' (or 'memory' + acknowledgeEphemeral = true) to enable them.",
+                : persistence.backend === "none"
+                    ? "Async job persistence is disabled (backend = 'none'). *_request_async tools are NOT registered on this gateway. Set [persistence].backend = 'sqlite' (or 'memory' + acknowledgeEphemeral = true) to enable them."
+                    : `Async job persistence is configured (backend = '${persistence.backend}') but the durable job store failed to open, so *_request_async tools are NOT registered on this gateway. Check gateway startup logs for the store-open error.`,
         };
         const outboundProviders = {
             xai: providers.xai
@@ -6467,7 +7091,7 @@ export function createGatewayServer(deps = {}) {
                     enabled: isXaiProviderEnabled(providers),
                     apiKeyEnv: providers.xai.apiKeyEnv,
                     apiKeyPresent: isXaiProviderEnabled(providers),
-                    baseUrl: providers.xai.baseUrl,
+                    baseUrl: redactDiagnosticUrl(providers.xai.baseUrl) ?? providers.xai.baseUrl,
                     defaultModel: providers.xai.defaultModel,
                     mode: isXaiProviderEnabled(providers) ? "sync" : "configured-missing-key",
                 }
@@ -6482,16 +7106,59 @@ export function createGatewayServer(deps = {}) {
                 },
             apiProviders: enabledApiProviders(providers).map(p => ({
                 ...apiProviderCatalogEntry(p),
-                baseUrl: p.baseUrl,
+                baseUrl: redactDiagnosticUrl(p.baseUrl) ?? p.baseUrl,
                 breakerState: apiProviderBreakerState(p.name),
             })),
             sources: providers.sources,
         };
+        const limiter = asyncJobManager.getLimiterSnapshot();
+        const jobLimits = asyncJobManager.getConfiguredLimits();
+        const httpLimits = getLimitsConfig().http;
+        const mem = process.memoryUsage();
+        const backpressure = {
+            jobs: {
+                running: limiter.running,
+                queued: limiter.queued,
+                runningByProvider: limiter.runningByProvider,
+                queuedByProvider: limiter.queuedByProvider,
+                maxRunning: limiter.maxRunning,
+                maxRunningPerProvider: limiter.maxRunningPerProvider,
+                maxQueued: limiter.maxQueued,
+                rejected: limiter.rejected,
+                timedOut: limiter.timedOut,
+                saturated: limiter.saturated,
+                completedJobMemoryTtlMs: jobLimits.completedJobMemoryTtlMs,
+                maxJobOutputBytes: jobLimits.maxJobOutputBytes,
+            },
+            httpSessions: activeHttpGateway
+                ? { active: true, ...activeHttpGateway.sessionHealth() }
+                : {
+                    active: false,
+                    current: 0,
+                    max: httpLimits.maxSessions,
+                    oldestAgeMs: 0,
+                    idleTtlMs: httpLimits.sessionIdleTtlMs,
+                    reaperIntervalMs: httpLimits.sessionReaperIntervalMs,
+                    saturated: false,
+                },
+            memory: {
+                rss: mem.rss,
+                heapUsed: mem.heapUsed,
+                heapTotal: mem.heapTotal,
+                external: mem.external,
+            },
+        };
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({ success: true, ...health, persistence: persistenceBlock, outboundProviders }, null, 2),
+                    text: JSON.stringify({
+                        success: true,
+                        ...health,
+                        backpressure,
+                        persistence: persistenceBlock,
+                        outboundProviders,
+                    }, null, 2),
                 },
             ],
         };
@@ -6529,10 +7196,13 @@ export function createGatewayServer(deps = {}) {
             ],
         };
     });
-    server.tool("list_models", "List models, aliases, and defaults for one provider CLI (claude|codex|gemini|grok|mistral|devin), or omit cli to list all providers.", {
+    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|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), CLI_TYPE_ENUM.optional())
-            .describe("CLI filter (claude|codex|gemini|grok|mistral|devin)"),
+            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(listModelsFilterValues).optional())
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|cursor, or an enabled API provider name)"),
     }, {
         title: "Provider models",
         readOnlyHint: true,
@@ -6541,13 +7211,32 @@ export function createGatewayServer(deps = {}) {
         openWorldHint: false,
     }, async ({ cli }) => {
         const cliInfo = getAvailableCliInfo();
-        const result = cli ? { [cli]: cliInfo[cli] } : cliInfo;
+        const apiRuntimes = enabledApiProviders(providers);
+        let result;
+        if (cli && CLI_TYPES.includes(cli)) {
+            result = { [cli]: cliInfo[cli] };
+        }
+        else if (cli) {
+            const runtime = apiRuntimes.find(p => p.name === cli);
+            result = { apiProviders: runtime ? [apiProviderCatalogEntry(runtime)] : [] };
+        }
+        else {
+            const apiProviders = apiRuntimes.map(apiProviderCatalogEntry);
+            result = { ...cliInfo, ...(apiProviders.length > 0 ? { apiProviders } : {}) };
+        }
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
-    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.", {
+    const providerToolCapabilitiesFilterValues = [
+        ...new Set([
+            ...CLI_TYPES,
+            "grok_api",
+            ...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|cursor|grok_api, or an enabled API provider name.", {
         cli: z
-            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(["claude", "codex", "gemini", "grok", "mistral", "devin", "grok_api"]).optional())
-            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|grok_api)"),
+            .preprocess(value => (value === "" || value === null ? undefined : value), z.enum(providerToolCapabilitiesFilterValues).optional())
+            .describe("Provider filter (claude|codex|gemini|grok|mistral|devin|cursor|grok_api, or an enabled API provider name)"),
         includeSkills: z
             .boolean()
             .default(true)
@@ -6579,13 +7268,14 @@ export function createGatewayServer(deps = {}) {
             includeUnsupported,
             includePaths,
             refresh,
+            providersConfig: providers,
         });
         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,
@@ -6599,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)
@@ -6617,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()
@@ -6667,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",
@@ -6691,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)
@@ -6742,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)
@@ -7124,7 +7814,7 @@ async function initializeSessionManager() {
         });
         logger.info("File-based session manager initialized");
     }
-    resourceProvider = new ResourceProvider(sessionManager, performanceMetrics, getFlightRecorder(logger), getCacheAwarenessConfig(logger));
+    resourceProvider = new ResourceProvider(sessionManager, performanceMetrics, getFlightRecorder(logger), getCacheAwarenessConfig(logger), getProvidersConfig(logger));
 }
 function registerHealthResource(server) {
     if (db) {
@@ -7430,7 +8120,8 @@ async function main() {
     if (args[0] === "doctor") {
         if (args.includes("--json")) {
             const probeUpstream = args.includes("--probe-upstream") || args.includes("--probe-installed");
-            printDoctorJson({ probeUpstream });
+            const probeApiProviders = args.includes("--probe-api-providers");
+            await printDoctorJson({ probeUpstream, probeApiProviders });
             return;
         }
         process.stderr.write("Only doctor --json is supported in this layer.\n");