llm-cli-gateway 2.12.0 → 2.12.2

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";
@@ -165,12 +166,13 @@ Tools: claude_request, codex_request, gemini_request, grok_request, mistral_requ
 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,
@@ -402,6 +416,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 +434,7 @@ async function awaitJobOrDefer(cli, args, corrId, idleTimeoutMs, outputFormat, f
             });
         }
         finally {
+            slot.release();
             consumeOnComplete();
         }
     }
@@ -441,7 +464,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 +504,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 +535,7 @@ async function awaitApiJobOrDefer(provider, apiRequest, corrId, runtime = resolv
             };
         }
         finally {
+            slot.release();
             consumeOnComplete();
         }
     }
@@ -531,7 +563,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 +710,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 +761,7 @@ function registerWorkspaceTools(server, runtime) {
         openWorldHint: false,
     }, async ({ alias }) => {
         try {
+            assertWorkspaceToolCaller("workspace_get");
             const registry = loadWorkspaceRegistry(runtime.logger);
             return {
                 content: [
@@ -731,7 +776,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 +790,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 +815,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 +830,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 +855,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);
@@ -4162,7 +4226,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 +4246,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"])
@@ -4525,12 +4590,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 +4796,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 +4920,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 +4960,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 +5082,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",
@@ -5226,12 +5293,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 +5429,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 +5449,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 +5699,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 +5793,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 +5833,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 +5945,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 +6062,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)",
@@ -6185,12 +6259,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 +6303,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 +6523,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 +6547,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 +6562,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 +6652,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, 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, or an enabled API provider name)"),
     }, {
         title: "Provider models",
         readOnlyHint: true,
@@ -6541,13 +6667,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|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|grok_api, or an enabled API provider name)"),
         includeSkills: z
             .boolean()
             .default(true)
@@ -6579,6 +6724,7 @@ export function createGatewayServer(deps = {}) {
             includeUnsupported,
             includePaths,
             refresh,
+            providersConfig: providers,
         });
         return { content: [{ type: "text", text: JSON.stringify(capabilities, null, 2) }] };
     });
@@ -7124,7 +7270,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 +7576,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");