llm-cli-gateway 2.12.1 → 2.13.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [2.13.0] - 2026-07-01: Cursor Agent CLI provider
+
+### Added
+
+- **Cursor Agent CLI (7th gateway provider).** `cursor_request` / `cursor_request_async`
+  drive `cursor-agent --print` headless mode with model selection, `plan`/`ask`
+  mode, output format, force/auto-review/sandbox/trust controls, workspace and
+  extra `--add-dir` roots, and session resume (`--resume`/`--continue`). Cursor
+  has no `promptParts` surface (plain `prompt` only, like Devin) and is not
+  wired for request-time MCP server injection because Cursor owns MCP config via
+  `cursor-agent mcp`. Covered by doctor, provider capability inventory,
+  provider-login guidance, upstream-contract drift detection, and CLI upgrade
+  support (`cursor-agent update`).
+- **Cursor native ACP discovery and gated transport.** The installed Cursor Agent
+  CLI exposes a native `cursor-agent acp` stdio entrypoint; initialize plus
+  `session/new` smoke passed locally. Gateway request tools still default to the
+  CLI headless path. Explicit `transport:"acp"` stays config-gated and rejects
+  unsupported Cursor CLI-only controls instead of silently dropping them.
+- **Cursor review hardening.** Cursor validation reviewers now run through
+  `cursor-agent --print --mode ask --sandbox enabled`; high-impact Cursor flags
+  (`force`, `trust`, `sandbox:"disabled"`) are gated under
+  `approvalStrategy:"mcp_managed"`; remote HTTP/OAuth workspace inputs must use
+  registered workspace aliases/roots; and docs/schema warn that gateway-created
+  `gw-*` ids are not resumable Cursor chat ids.
+
+## [2.12.2] - 2026-07-01: backpressure hardening and release-gate stability
+
+### Security
+
+- **HTTP/session and async-job backpressure hardening for issue #130.** HTTP MCP session initialization is now bounded before gateway session creation, including concurrent initialize bursts and `createGatewayServer()` / `server.connect()` failure cleanup. Async process/API jobs now share bounded global, per-provider, and queue caps; queued jobs are treated as in-progress by sync/deferred paths; direct sync and inline API execution are covered by the same limiter; and `/healthz` / `llm_process_health` expose prompt-free session, queue, limiter, and memory pressure metrics. The release includes deterministic regression coverage for HTTP initialize bursts, pending-initialize accounting, queued deferral behavior, and async job caps.
+- **`llm_process_health` now redacts `base_url` userinfo.** The outbound-providers health block surfaces each API provider's `base_url`, which is config-supplied and may legally carry URL userinfo (`https://user:pass@host/v1`). Both the dedicated `xai` block and the generic `apiProviders` array now run `base_url` through `redactDiagnosticUrl` (stripping `username`/`password` and sensitive query params) before emitting it, matching the redaction already applied on the `doctor` and login-guidance surfaces. The live request path and circuit breakers are unaffected.
+- **`redactDiagnosticUrl` now leaves clean URLs byte-identical.** When a URL has nothing to redact (no userinfo, no sensitive query/hash params), the helper returns the caller's exact bytes instead of the URL parser's canonicalized form (lowercased host, dropped default port, normalized path/encoding). This keeps non-secret `base_url` / public-URL values unchanged on every diagnostic surface (`doctor`, login-guidance, `llm_process_health`).
+
+### Added
+
+- **Doctor, status, login-guidance, tool-capabilities, and resources now surface enabled API providers (Slice 6).** The five peripheral discovery surfaces were CLI-only; they now report enabled `[providers.<name>]` (kind:`api`) providers too, staying byte-identical when none are enabled:
+  - `doctor --json` gains an `api_providers` health block (per provider: kind, base_url, default_model, models, the key env var name, whether the key is present, and login guidance). The block is omitted entirely when no API providers are enabled. An opt-in `--probe-api-providers` flag adds a reachability result per provider; a normal `doctor` run spends no network or tokens (`reachable` stays null). The key value is never reported, only its presence. `setup/status.schema.json` is updated to match.
+  - `provider-status` gains `getApiProviderStatus` (enabled + key-present projection; no spawnable binary) and `provider-login-guidance` gains `getApiProviderLoginGuidance` (where to get the key, which env var, the base_url; keyless-local guidance for loopback providers).
+  - `provider_tool_capabilities` now builds real per-`api`-kind metadata on demand instead of the former unreachable defensive throw: API providers support model + sampling + (xai-responses) reasoning + continuity, and never expose allow/deny lists, MCP servers, local skills, or workspace/worktree controls. The capability filter enum, the `provider-tools://<id>` resource allowlist, and the capability-id set widen together to include enabled API provider names.
+  - `models://<api-provider>` resources are exposed for every enabled API provider, and `sessions://<api-provider>` for continuity-tracked kinds. The `CLI_TYPES` guard on the `provider-subcommands://` resources is unchanged, so API providers stay correctly excluded there.
+- **`list_models` now surfaces enabled API providers (Slice 5).** When one or more `[providers.<name>]` API providers are enabled, `list_models` returns them under an `apiProviders` array (each tagged `providerKind:"api"` with `defaultModel` and the optional model allowlist), mirroring `list_available_models` and the `llm_process_health` outbound block. The `cli` filter accepts an enabled API provider name in addition to the six CLI providers. The field is omitted entirely when no API providers are enabled, so dormant output is byte-identical to before.
+
+### CI
+
+- **Lychee no longer fails release/security CI on GitHub's unauthenticated latest-release API.** The link-rot gate now excludes `https://api.github.com/repos/*/*/releases/latest`, matching the upstream-scan model where these advisory release metadata URLs are verified separately and GitHub Actions 403/rate-limit responses should not block an otherwise clean release.
+
 ## [2.12.1] - 2026-06-30: fast-uri transitive vulnerability remediation
 
 ### Security

package/README.md

@@ -9,9 +9,9 @@
 > _"Without consultation, plans are frustrated, but with many counselors they succeed."_
 > — Proverbs 15:22 (LSB)
 
-A Model Context Protocol (MCP) gateway for running Claude Code, Codex, Gemini, Grok, Mistral (Vibe), and Devin CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
+A Model Context Protocol (MCP) gateway for running Claude Code, Codex, Gemini, Grok, Mistral (Vibe), Devin, and Cursor Agent CLIs from one MCP endpoint, with durable async jobs, session continuity, cache-aware prompting, observability, and personal-appliance setup tooling.
 
-**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across six provider CLIs.
+**Why developers try it:** one local MCP endpoint for cross-LLM validation, multi-agent coding workflows, and repeatable assistant-led setup across registered provider CLIs.
 
 **Current signals:** CI and security workflows pass on `main`, OpenSSF Scorecard is published, OpenSSF Best Practices is passing, releases use Sigstore signing, and the package is MIT licensed.
 
@@ -38,7 +38,7 @@ Or use directly with `npx` from an MCP client:
 
 `llm-cli-gateway` is a single-user MCP gateway for cross-LLM validation and multi-agent coding workflows. It is more than a thin CLI wrapper:
 
-- Runs six provider CLIs through consistent sync and async MCP tools.
+- Runs registered provider CLIs through consistent sync and async MCP tools.
 - Persists long-running jobs, supports restart-safe result collection, deduplication, cancellation, and sync-to-async deferral.
 - Tracks sessions, real CLI resume paths, structured response metadata, and cache telemetry.
 - Supports cache-aware `promptParts`, including explicit Claude `cache_control` when opted in.
@@ -157,7 +157,7 @@ docker compose -f docker/personal.compose.yml run --rm doctor
 
 ### Core Capabilities
 
-- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, Gemini, Grok, Mistral (Vibe), and Devin CLIs
+- **Multi-LLM Orchestration**: Unified interface for Claude Code, Codex, Gemini, Grok, Mistral (Vibe), Devin, and Cursor Agent CLIs
 - **Session Management**: Track and resume conversations across all CLIs with persistent storage
 - **Gateway-owned worktrees**: Run any sync or async provider request inside a managed git worktree, with per-session reuse and cleanup
 - **Token Optimization**: Automatic 44% reduction on prompts, 37% on responses (opt-in)
@@ -169,11 +169,11 @@ docker compose -f docker/personal.compose.yml run --rm doctor
 - **SQLite Flight Recorder**: Every request/response logged to `~/.llm-cli-gateway/logs.db` with correlation IDs, token usage, duration, retry counts, and circuit breaker state. Browse with [Datasette](https://datasette.io/): `datasette ~/.llm-cli-gateway/logs.db`
 - **Structured Metadata**: Tool responses include machine-readable `structuredContent` (model, cli, correlationId, sessionId, durationMs, token counts)
 - **Cache observability resources**: `cache-state://global`, `cache-state://session/{id}`, and `cache-state://prefix/{hash}` MCP resources return aggregate cache hit/miss/savings — tokens and hashes only, no prompt text. `session_get` includes a `cacheState` block when the session has prior requests.
-- **Provider capability inventory**: `provider_tool_capabilities` and `provider-tools://catalog` expose the gateway request fields, supported/degraded provider controls, local skill/tool discovery, and safe config-surface hints for Claude Code, Codex CLI, Gemini/Antigravity, Grok CLI/API, Mistral Vibe, and Cognition Devin. `doctor --json` includes a compact `provider_capabilities` summary for setup assistants.
+- **Provider capability inventory**: `provider_tool_capabilities` and `provider-tools://catalog` expose the gateway request fields, supported/degraded provider controls, local skill/tool discovery, and safe config-surface hints for Claude Code, Codex CLI, Gemini/Antigravity, Grok CLI/API, Mistral Vibe, Cognition Devin, and Cursor Agent. `doctor --json` includes a compact `provider_capabilities` summary for setup assistants.
 
 ### Cache-aware operation
 
-Every `*_request` and `*_request_async` tool except `devin_request` / `devin_request_async` accepts an optional `promptParts` field that structures the prompt for better cache hit rates (the Devin headless path takes a plain `prompt` only). The gateway concatenates the parts in canonical order (`system → tools → context → task`) so that the stable prefix bytes precede the volatile task tail unchanged across calls, letting each provider's automatic prompt-caching land on the same content hash each time.
+Every `*_request` and `*_request_async` tool except `devin_request` / `devin_request_async` and `cursor_request` / `cursor_request_async` accepts an optional `promptParts` field that structures the prompt for better cache hit rates (the Devin and Cursor headless paths take a plain `prompt` only). The gateway concatenates the parts in canonical order (`system → tools → context → task`) so that the stable prefix bytes precede the volatile task tail unchanged across calls, letting each provider's automatic prompt-caching land on the same content hash each time.
 
 ```json
 {
@@ -188,7 +188,7 @@ Every `*_request` and `*_request_async` tool except `devin_request` / `devin_req
 
 `prompt` and `promptParts` are mutually exclusive — pass exactly one.
 
-Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for all providers except Devin, which has no `promptParts` surface; explicit levers are provider-specific):
+Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for all providers except Devin and Cursor, which have no `promptParts` surface; explicit levers are provider-specific):
 
 | CLI     | Prefix discipline | Explicit lever(s) |
 | ------- | ----------------- | ----------------- |
@@ -197,6 +197,8 @@ Per-CLI capability matrix (prefix discipline is automatic via `promptParts` for
 | gemini  | yes               | none (implicit server-side) |
 | grok    | yes               | `compactionMode` / `compactionDetail` (context compaction: `summary|transcript|segments`; `segments` writes per-segment markdown) |
 | mistral | yes               | none (implicit) |
+| devin   | no                | plain `prompt` only |
+| cursor  | no                | plain `prompt` only |
 
 **Claude example (explicit cacheControl)**
 
@@ -234,7 +236,7 @@ Opt-in flags (all default off) live under `[cache_awareness]` in `~/.llm-cli-gat
 
 - **Retry Logic**: Exponential backoff with circuit breaker for transient failures
 - **Atomic File Writes**: Process-specific temp files with fsync for data integrity
-- **Memory Limits**: 50MB cap on CLI output prevents DoS attacks
+- **Host-protection backpressure**: bounded HTTP session lifecycle (max sessions + idle reaper), global and per-provider job-execution limits with a bounded FIFO queue, and a configurable per-job output cap (default 50MB). See [Host-protection limits](#host-protection-limits-http-and-limits).
 - **NVM Path Caching**: Eliminates I/O overhead on every request
 - **Long-Running Jobs**: Non-time-bound async execution via `*_request_async` + polling tools
 
@@ -665,6 +667,61 @@ Legacy environment variables (deprecated; emit a warning at startup):
 - `LLM_GATEWAY_DEDUP_WINDOW_MS` — overrides `dedupWindowMs`.
 - `LLM_GATEWAY_ACKNOWLEDGE_EPHEMERAL` — `1`/`true`/`yes` sets `acknowledgeEphemeral = true`.
 
+##### Host-protection limits (`[http]` and `[limits]`)
+
+The gateway bounds HTTP session growth and async/sync job execution so a burst of
+clients or requests cannot drive unbounded memory, process, CPU, or provider-request
+growth. All keys live in the same `~/.llm-cli-gateway/config.toml`; defaults are
+conservative but chosen not to surprise local stdio development.
+
+```toml
+[http]                              # HTTP MCP transport session lifecycle
+max_sessions = 100                  # max concurrent live sessions; excess initialize returns HTTP 429
+session_idle_ttl_ms = 1800000       # 30 min: reap a session idle longer than this (no client DELETE needed)
+session_reaper_interval_ms = 60000  # 1 min: how often the idle reaper sweeps
+
+[limits]                            # async + sync job-execution backpressure (per gateway process)
+max_running_jobs = 32               # global concurrent running jobs (process CLI + HTTP API)
+max_running_jobs_per_provider = 16  # per-provider concurrent running jobs
+max_queued_jobs = 128               # bounded wait queue; a full queue rejects new work
+queue_timeout_ms = 120000           # 2 min: max time a job waits in the queue before failing
+completed_job_memory_ttl_ms = 3600000  # 1 h: in-memory retention for finished jobs (durable rows kept separately)
+max_job_output_bytes = 52428800     # 50 MB: per-job stdout+stderr cap
+```
+
+Failure modes (all deterministic and safe to retry):
+
+- **HTTP session cap reached**: the initialize request returns `429` with `Retry-After: 5` and a structured `{ error, code: "session_capacity", retryable: true }` body. No new session is created.
+- **Idle HTTP session**: the reaper closes it (transport + gateway server) once idle past `session_idle_ttl_ms`, independent of the client sending `DELETE`. A session with an in-flight request is never reaped mid-request.
+- **Job limiter saturated**: when the running limit is reached and the queue is full, `*_request` / `*_request_async` and the direct-sync fallback return a retryable `saturated` error (`structuredContent.errorCategory = "saturated"`, `retryable: true`). Nothing is spawned. When the queue has room the job waits (FIFO, per-provider fair) up to `queue_timeout_ms`, then fails with the same category.
+- **Sync direct execution**: the `SYNC_DEADLINE_MS=0` and storeless/`backend="none"` paths acquire the same process permit before spawning, so no execution bypasses the limiter.
+- **Output overflow**: a job whose combined stdout+stderr exceeds `max_job_output_bytes` is failed (exit code 126), its process terminated, its completion persisted, and its run slot released.
+- **In-memory vs durable retention**: `completed_job_memory_ttl_ms` only ages finished jobs out of the in-memory map; the durable job store keeps its own (longer) `[persistence].retentionDays` retention, so results stay readable via `llm_job_result` / `llm_request_result` after in-memory eviction.
+
+Live counters are exposed on `GET /healthz` (unauthenticated, HTTP transport) and via the `llm_process_health` tool `backpressure` block: session current/max/oldest-age/idle-TTL/saturation, running and queued job counts globally and per provider, limiter saturation counters, configured TTL/output caps, and parent-process RSS/heap. These surfaces report **counts, ages, and bytes only**, never prompt text, response content, tokens, session IDs, bearer/OAuth tokens, API keys, or machine secrets.
+
+For production user services, pair the in-process limits above with systemd's
+outer guardrails so an unexpected bug, provider CLI leak, or evaluation burst
+cannot consume the host:
+
+```bash
+systemctl --user edit llm-cli-gateway.service
+```
+
+```ini
+[Service]
+MemoryMax=2G
+TasksMax=512
+```
+
+Choose values for your workload: `MemoryMax` should cover the gateway process,
+the configured `max_running_jobs` provider children, and normal output buffering;
+`TasksMax` should exceed the process/thread count implied by `max_running_jobs`
+plus the HTTP server and SQLite work, but still be far below host exhaustion. If
+systemd terminates the service at those limits, durable jobs can be inspected
+after restart and `llm_process_health.backpressure` should be used to tune
+`[http]`, `[limits]`, `MemoryMax`, and `TasksMax` together.
+
 ##### Per-project isolation
 
 By default, **all gateway data is global per user**, not per project. With no overrides, every Claude Code window — across every repo — spawns its own gateway subprocess but they all read and write the same files:
@@ -905,9 +962,36 @@ Run a Cognition Devin CLI request synchronously (headless print mode, `devin -p`
 - `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
 - `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
-##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async` / `devin_request_async`
+##### `cursor_request`
+
+Run a Cursor Agent CLI request synchronously. Defaults to headless print mode (`cursor-agent --print`) and auto-defers to a pollable job past the sync deadline when async jobs are enabled. Set `transport: "acp"` to use Cursor's native `cursor-agent acp` transport when `[acp]` and `[acp.providers.cursor].runtime_enabled` are enabled; current ACP routing accepts only prompt/model/session inputs and rejects CLI-only options such as `mode`, `workspace`, `sandbox`, `force`, and `trust`.
+
+**Parameters:**
+
+- `prompt` (string, required): Prompt text for Cursor Agent CLI (1-100,000 chars)
+- `model` (string, optional): Model name or alias (for example `gpt-5`, `sonnet-4-thinking`, or `latest`)
+- `mode` (string, optional): Cursor mode, `"plan"` or `"ask"` (`--mode`)
+- `outputFormat` (string, optional): `"text"` (default), `"json"`, or `"stream-json"`
+- `transport` (string, optional): `"cli"` (default) or `"acp"`; ACP fails closed unless enabled in gateway config and rejects unsupported Cursor CLI-only controls instead of dropping them
+- `force` (boolean, optional): Emit `--force` for non-interactive operation
+- `autoReview` (boolean, optional): Emit `--auto-review`
+- `sandbox` (string, optional): `"enabled"` or `"disabled"` (`--sandbox`)
+- `trust` (boolean, optional): Emit `--trust` for this invocation
+- `workspace` (string, optional): Cursor workspace path or name (`--workspace`); remote HTTP/OAuth callers must pass a registered workspace alias, while local stdio callers may pass paths
+- `addDir` (string[], optional): Additional workspace roots (one `--add-dir` per entry); remote HTTP/OAuth callers must use registered workspace roots
+- `sessionId` (string, optional): Cursor chat/session ID to resume (`--resume <id>`). The `gw-*` id minted for a brand-new gateway session is not resumable through `sessionId`; continue with `resumeLatest: true`
+- `resumeLatest` (boolean, optional): Resume the most recent Cursor chat (`--continue`)
+- `createNewSession` (boolean, optional): Force a new session
+- `approvalStrategy` (string, optional): `"legacy"` (default) or `"mcp_managed"`; under MCP-managed approval, high-impact Cursor flags (`force`, `trust`, or `sandbox: "disabled"`) are denied unless bypass approval is explicitly allowed
+- `approvalPolicy` (string, optional): `"strict"`, `"balanced"`, or `"permissive"` override for MCP-managed approval
+- `optimizePrompt` / `optimizeResponse` (boolean, optional): Token-efficiency optimisation, default: false
+- `correlationId` (string, optional): Request trace ID (auto-generated if omitted)
+- `idleTimeoutMs` (integer, optional): Kill a stuck process after output inactivity; 30,000 to 3,600,000 ms
+- `forceRefresh` (boolean, optional): Bypass dedup and force a fresh CLI run, default: false
 
-Start a long-running Claude, Codex, Gemini, Grok, Mistral, or Devin request without waiting for completion in the same MCP call.
+##### `claude_request_async` / `codex_request_async` / `gemini_request_async` / `grok_request_async` / `mistral_request_async` / `devin_request_async` / `cursor_request_async`
+
+Start a long-running Claude, Codex, Gemini, Grok, Mistral, Devin, or Cursor request without waiting for completion in the same MCP call.
 
 Use this flow when analysis/runtime can exceed client tool-call limits:
 
@@ -925,7 +1009,7 @@ Async request tools accept the same approval strategy fields as their sync varia
 
 ##### `llm_job_status`
 
-Return lifecycle status (`running`, `completed`, `failed`, `canceled`) and metadata for an async job.
+Return lifecycle status (`queued`, `running`, `completed`, `failed`, `canceled`, `orphaned`) and metadata for an async job.
 
 ##### `llm_job_result`
 
@@ -966,7 +1050,7 @@ Return the gateway's declared provider CLI contracts, optionally probing the ins
 
 **Parameters:**
 
-- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral|devin`)
+- `cli` (string, optional): Filter (`claude|codex|gemini|grok|mistral|devin|cursor`)
 - `probeInstalled` (boolean, optional, default `false`): Run local `--help` probes and compare advertised flags against the declared contract — strongly recommended after any provider CLI upgrade. The probe reports `missingFlags`, `extraFlags`, `acknowledgedExtraFlags` (known upstream-only flags filtered from `extraFlags`), `discoveredFlags`, and stale-marker `warnings`.
 
 #### Session Management Tools
@@ -977,7 +1061,7 @@ Create a new session for a specific CLI.
 
 **Parameters:**
 
-- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok", "mistral", "devin")
+- `cli` (string, required): CLI to create session for ("claude", "codex", "gemini", "grok", "mistral", "devin", "cursor")
 - `description` (string, optional): Description for the session
 - `setAsActive` (boolean, optional): Set as active session, default: true
 
@@ -997,7 +1081,7 @@ List all sessions, optionally filtered by CLI.
 
 **Parameters:**
 
-- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok", "mistral", "devin")
+- `cli` (string, optional): Filter by CLI ("claude", "codex", "gemini", "grok", "mistral", "devin", "cursor")
 
 **Response includes:**
 
@@ -1046,7 +1130,7 @@ List available models for each CLI.
 
 **Parameters:**
 
-- `cli` (string, optional): Specific CLI to list models for ("claude", "codex", "gemini", "grok", "mistral", "devin")
+- `cli` (string, optional): Specific provider to list models for (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, `"cursor"`, or an enabled API provider name). When one or more `[providers.<name>]` API providers are enabled, the unfiltered response also carries an `apiProviders` array (each entry tagged `providerKind: "api"`); see [API providers (HTTP)](#api-providers-http).
 
 **Response includes:**
 
@@ -1094,7 +1178,7 @@ inputs.
 
 **Parameters:**
 
-- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, or `"grok_api"`)
+- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, `"cursor"`, `"grok_api"`, or an enabled API provider name)
 - `includeSkills` (boolean, default `true`): Include bounded local skill discovery
 - `includeProviderTools` (boolean, default `true`): Include provider-native tools extracted from discovered skills
 - `includeUnsupported` (boolean, default `true`): Include explicit unsupported/degraded input records
@@ -1115,12 +1199,16 @@ Equivalent MCP resources:
 - `provider-tools://grok_api`
 - `provider-tools://mistral`
 - `provider-tools://devin`
+- `provider-tools://cursor`
+- `provider-tools://<api-provider>` for each enabled `[providers.<name>]` API provider
 
 `doctor --json` also emits a compact `provider_capabilities` block with the
 same schema version, per-provider request tool names, supported feature names,
 unsupported input names, config-surface counts, discovery counts, and resource
 URIs. This block is intended for setup assistants that need a concise capability
-summary without local skill bodies or raw paths.
+summary without local skill bodies or raw paths. When API providers are enabled,
+`doctor --json` additionally emits an `api_providers` health block; see
+[API providers (HTTP)](#api-providers-http).
 
 ##### `cli_versions`
 
@@ -1128,7 +1216,7 @@ Report installed CLI versions.
 
 **Parameters:**
 
-- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok", "mistral", "devin")
+- `cli` (string, optional): Specific CLI to inspect ("claude", "codex", "gemini", "grok", "mistral", "devin", "cursor")
 
 ##### `cli_upgrade`
 
@@ -1136,7 +1224,7 @@ Plan or run an upgrade for one CLI.
 
 **Parameters:**
 
-- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok", "mistral", "devin")
+- `cli` (string, required): CLI to upgrade ("claude", "codex", "gemini", "grok", "mistral", "devin", "cursor")
 - `target` (string, optional): Package tag/version/target, default: `latest`
 - `dryRun` (boolean, optional): Return the upgrade plan without running it, default: `true`
 - `timeoutMs` (number, optional): Upgrade timeout when `dryRun=false`
@@ -1152,6 +1240,7 @@ Plan or run an upgrade for one CLI.
 - Grok explicit target: `grok update --version <target>`
 - Mistral (Vibe): dispatches to the detected installer (`pip`/`uv`/`brew`); errors with guidance when none is detected (Vibe ships no self-update command)
 - Devin latest: `devin update` (self-update; explicit version targets are unsupported)
+- Cursor latest: `cursor-agent update` (self-update; explicit version targets are unsupported)
 
 **Example dry run:**
 
@@ -1163,6 +1252,73 @@ Plan or run an upgrade for one CLI.
 }
 ```
 
+## API providers (HTTP)
+
+In addition to the spawnable CLI tools, the gateway can route requests to first-class **HTTP/API providers** (OpenRouter and other OpenAI-compatible endpoints, the Anthropic Messages API, and the xAI Responses API). These use Node's built-in HTTP client (`node:https`, or `node:http` for loopback endpoints) rather than spawning a CLI, and they run through the same request/job/validation/flight-recorder machinery as the CLI tools, so they reach parity for sessions, async jobs, dedup, retries, usage/cost capture, and cross-LLM validation.
+
+### Configuring a provider
+
+API providers are declared as `[providers.<name>]` blocks in `~/.llm-cli-gateway/config.toml` (override with `LLM_GATEWAY_CONFIG`). The `<name>` becomes the provider's identity across every tool and resource and **must not** collide with a spawnable CLI name (`claude`, `codex`, `gemini`, `grok`, `mistral`, `devin`, `cursor`); a collision is rejected with a warning and the provider is disabled.
+
+```toml
+# OpenRouter (OpenAI-compatible). The key is read from the named env var at
+# request time and is never written to config, logs, the flight recorder, or
+# the dedup key.
+[providers.openrouter]
+kind = "openai-compatible"                 # "openai-compatible" | "anthropic" | "xai-responses"
+base_url = "https://openrouter.ai/api/v1"
+api_key_env = "OPENROUTER_API_KEY"         # env var NAME, not the key itself
+default_model = "x-ai/grok-2"
+models = ["x-ai/grok-2", "anthropic/claude-sonnet-4.6"]   # optional allowlist: an explicit model must be listed (omit model to use default_model)
+usage_include = true                       # OpenRouter token/cost reporting (usage:{include:true})
+
+# Keyless-local: an openai-compatible provider on a loopback base_url (Ollama,
+# llama.cpp) is enabled with no api_key_env at all.
+[providers.ollama]
+kind = "openai-compatible"
+base_url = "http://127.0.0.1:11434/v1"
+default_model = "qwen2.5"
+```
+
+A provider is **enabled** when its `api_key_env` resolves to a non-empty value, OR it is a keyless-local `openai-compatible` provider on a loopback `base_url`. `base_url` must use `https` unless it targets localhost/loopback. A **schema-invalid** single `[providers.<name>]` block disables only itself (with a warning) and leaves the other providers untouched; a TOML **syntax** error anywhere in the file is different, it makes the whole config fall back to defaults.
+
+The pre-existing `[providers.xai]` block keeps its dedicated `grok_api_request` tool and xAI identity. It is also exposed through the generic surface like any other enabled provider, so a configured xAI key registers **both** `grok_api_request` and the generic `api_xai_request` (and the `xai` entry appears in `apiProviders`, `models://xai`, etc.).
+
+### Request tools
+
+For each enabled provider, the gateway registers `api_<name>_request` (and `api_<name>_request_async` when async jobs are enabled). They accept the same shape as the CLI request tools:
+
+- `prompt` (or the cache-aware `promptParts` `{ system?, tools?, context?, task }`, mutually exclusive), optional `system`
+- `model` (omit to use `default_model`; an explicit value is rejected if outside a configured `models` allowlist), `maxOutputTokens`, `temperature`, `topP`
+- `reasoningEffort` (`none|low|medium|high`): forwarded only by the `xai-responses` adapter; accepted but ignored by the other kinds
+- `timeoutMs`, `optimizePrompt`, `optimizeResponse`, `forceRefresh`, `correlationId`
+- `sessionId` / `createNewSession` for continuity on the synchronous `api_<name>_request` (see below); on the async variant they are currently inert
+
+Responses (and the 50 MB output cap, dedup window, cancellation, retention) behave exactly as for the CLI tools, and HTTP requests are logged to the flight recorder with status/usage/cost like everything else.
+
+### Continuity
+
+Continuity is capability-typed per provider kind and never stores conversation content in the session record (the gateway's no-transcript-in-sessions invariant holds):
+
+- **`xai-responses`** uses real server-side continuation: the gateway persists the provider's `previous_response_id` in session metadata and threads it back on resume, self-healing on a stale-handle 404.
+- **`openai-compatible`** and **`anthropic`** are stateless-resend: the session tracks active/owner state for principal isolation, but the caller resends prior context (no server-side conversation handle exists).
+
+### Discovery surfaces
+
+Enabled API providers appear, alongside the CLI providers, across the discovery surfaces. The model, capability, doctor, and resource surfaces below **omit** their API field entirely when no API providers are enabled, so their output is byte-identical to before; `llm_process_health` is the exception (it always carries an `apiProviders` array that is simply empty when none are enabled):
+
+- **`list_models`** / **`list_available_models`**: an `apiProviders` array tagged `providerKind: "api"` with `defaultModel` and the optional allowlist, omitted entirely when no API providers are enabled.
+- **`llm_process_health`**: an always-present `outboundProviders.apiProviders` array (empty when none are enabled) carrying the same projection plus each provider's circuit-breaker state.
+- **`provider_tool_capabilities`**: per-`api`-kind capability metadata. Model + sampling + (for `xai-responses`) reasoning + continuity are supported; allow/deny tool lists, MCP servers, local skills, and workspace/worktree controls are not (those are CLI-only).
+- **`doctor --json`**: an `api_providers` health block (kind, `base_url`, `default_model`, models, the key env var name, whether the key is present, and login guidance), omitted entirely when none are enabled. The optional flag `doctor --json --probe-api-providers` adds a per-provider endpoint-reachability result (a bare `GET`, treating any HTTP response as reachable). The probe is **opt-in and off by default**: a normal `doctor` run opens no socket and spends no tokens (`reachable` stays `null`).
+- **MCP resources**: `models://<provider>` for every enabled provider and `sessions://<provider>` for continuity-tracked kinds, plus `provider-tools://<provider>`. The `provider-subcommands://` resources stay CLI-only (API providers have no subcommands).
+
+The API key value is never emitted on any of these surfaces (only the env var name and a presence boolean). Because `base_url` is config-supplied and may legally carry URL userinfo, the diagnostic surfaces (`doctor`, login guidance) redact any embedded credentials before displaying it; the actual request path and the reachability probe still use the original configured URL.
+
+### Security note
+
+The resolved API key is excluded from `payloadJson`, the dedup key, logs, and the flight recorder. However, the **request prompt is persisted in plaintext** in the async job store (the SQLite file at `[persistence].path`, default `~/.llm-cli-gateway/logs.db`) and is not covered by secret redaction. This mirrors the CLI tools, whose prompt is persisted in `argsJson` whenever it is passed as a command argument (a few CLI paths instead stream the prompt over stdin and so do not persist it). Treat the job store as sensitive at rest. See [Security Considerations](#security-considerations).
+
 ## Session Management
 
 ### How It Works
@@ -1418,6 +1574,8 @@ The gateway supports concurrent requests across different CLIs. Each request spa
 ## Security Considerations
 
 - **Input Validation**: All prompts are validated (min 1 char, max 100k chars)
+- **API-provider keys**: For `[providers.<name>]` HTTP providers, the gateway reads the key from the named environment variable at request time only. The resolved key is excluded from the persisted `payloadJson`, the dedup key, logs, and the flight recorder, and is never surfaced on the discovery/diagnostic surfaces (which report only the env var name and a presence boolean). `base_url` userinfo is redacted on the diagnostic surfaces. See [API providers (HTTP)](#api-providers-http).
+- **Prompt persistence at rest**: Async job rows store the request **prompt in plaintext** (HTTP `payloadJson`, and CLI `argsJson` whenever the prompt is passed as a command argument rather than streamed over stdin); this is not covered by secret redaction. The SQLite job-store file (default `~/.llm-cli-gateway/logs.db`, configurable via `[persistence].path`) is `chmod`ed to `0o600` on non-Windows hosts; treat it as sensitive and scope/rotate it like any prompt log. Set `[persistence].backend = "none"` to disable the async job store entirely (the `*_request_async` / `llm_job_*` tools are then not registered).
 - **Command Execution**: Uses `spawn` with separate arguments (not shell execution)
 - **No Eval**: No dynamic code evaluation in our source (see "Socket alerts" below for the transitive `ajv` codegen case)
 - **Sandboxing**: Consider running in containers for production use

package/dist/acp/provider-registry.js

@@ -77,6 +77,19 @@ const ACP_PROVIDER_REGISTRY = Object.freeze({
         adapterCandidates: Object.freeze([]),
         caveat: "Native ACP entrypoint `devin acp` (stdio JSON-RPC). Manual initialize + session/new smoke passed with the installed CLI managing credentials (`devin auth login`; WINDSURF_API_KEY for empty-env); empty-env smoke is expected to fail. Third native runtime pilot; runtime routing stays config-gated.",
     }),
+    cursor: Object.freeze({
+        provider: "cursor",
+        displayName: "Cursor Agent CLI",
+        status: "native_smoke_passed",
+        supportKind: "native",
+        targetVersion: "cursor-agent 2026.06.29-2ad2186",
+        entrypoint: Object.freeze({ command: "cursor-agent", args: Object.freeze(["acp"]) }),
+        runtimeEnabledDefault: false,
+        shipRuntimePilot: true,
+        runtimePriority: 4,
+        adapterCandidates: Object.freeze([]),
+        caveat: "Native ACP entrypoint `cursor-agent acp` (stdio JSON-RPC) is available as a hidden advanced command. Manual initialize + session/new smoke passed locally (protocolVersion 1, session created; no agentInfo returned). Fourth native runtime pilot; runtime routing stays config-gated.",
+    }),
 });
 export function getAcpProviderRegistry() {
     return ACP_PROVIDER_REGISTRY;

package/dist/api-provider.d.ts

@@ -3,6 +3,7 @@ import type { Logger } from "./logger.js";
 import { ApiHttpError } from "./api-http.js";
 export type ApiProviderKind = "openai-compatible" | "anthropic" | "xai-responses";
 export type ApiContinuity = "server-side-id" | "stateless-resend" | "none";
+export declare function apiContinuityForKind(kind: ApiProviderKind): ApiContinuity;
 export interface ApiChatMessage {
     role: "system" | "user" | "assistant";
     content: string;

package/dist/api-provider.js

@@ -1,6 +1,19 @@
 import { createCircuitBreaker, withRetry } from "./retry.js";
 import { logWarn, noopLogger } from "./logger.js";
 import { ApiHttpError, buildEndpointUrl, isHttpTransient, postJson, DEFAULT_API_TIMEOUT_MS, } from "./api-http.js";
+export function apiContinuityForKind(kind) {
+    switch (kind) {
+        case "xai-responses":
+            return "server-side-id";
+        case "openai-compatible":
+        case "anthropic":
+            return "stateless-resend";
+        default: {
+            const exhaustive = kind;
+            throw new Error(`Unknown api provider kind: ${String(exhaustive)}`);
+        }
+    }
+}
 function numberOrUndefined(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }

package/dist/approval-manager.d.ts

@@ -2,7 +2,7 @@ import type { Logger } from "./logger.js";
 import type { ReviewIntegrityResult } from "./review-integrity.js";
 export type ApprovalPolicy = "strict" | "balanced" | "permissive";
 export type ApprovalStrategy = "legacy" | "mcp_managed";
-export type ApprovalCli = "claude" | "codex" | "gemini" | "grok" | "mistral" | "devin";
+export type ApprovalCli = "claude" | "codex" | "gemini" | "grok" | "mistral" | "devin" | "cursor";
 export type ApprovalStatus = "approved" | "denied";
 export interface ApprovalRequest {
     cli: ApprovalCli;

package/dist/async-job-manager.d.ts

@@ -4,11 +4,31 @@ import { JobStore } from "./job-store.js";
 import { type FlightRecorderLike } from "./flight-recorder.js";
 import type { ValidationRunStore } from "./job-store.js";
 import { type ApiProvider, type ApiRequest, type ApiUsage } from "./api-provider.js";
+import { type JobLimitsConfig } from "./config.js";
 export declare function extractApiHttpStatus(error: unknown): number | null;
 export declare function extractApiErrorBody(error: unknown): string | undefined;
-export type LlmCli = "claude" | "codex" | "gemini" | "grok" | "mistral" | "devin";
+export type LlmCli = "claude" | "codex" | "gemini" | "grok" | "mistral" | "devin" | "cursor";
 export type JobProvider = LlmCli | (string & {});
-export type AsyncJobStatus = "running" | "completed" | "failed" | "canceled" | "orphaned";
+export type AsyncJobStatus = "queued" | "running" | "completed" | "failed" | "canceled" | "orphaned";
+export declare function isAsyncJobInProgress(status: AsyncJobStatus): boolean;
+export declare class JobSaturationError extends Error {
+    readonly provider: string;
+    readonly detail: string;
+    readonly retryable = true;
+    constructor(provider: string, detail: string);
+}
+export interface JobLimiterSnapshot {
+    maxRunning: number;
+    maxRunningPerProvider: number;
+    maxQueued: number;
+    running: number;
+    queued: number;
+    runningByProvider: Record<string, number>;
+    queuedByProvider: Record<string, number>;
+    rejected: number;
+    timedOut: number;
+    saturated: boolean;
+}
 export interface AsyncJobFlightRecorderEntry {
     model: string;
     prompt: string;
@@ -76,7 +96,11 @@ export declare class AsyncJobManager {
     private processMonitor;
     private store;
     private flightRecorder;
-    constructor(logger?: Logger, onJobComplete?: ((cli: JobProvider, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null, flightRecorder?: FlightRecorderLike);
+    private readonly limits;
+    private readonly limiter;
+    private readonly completedJobMemoryTtlMs;
+    private readonly maxJobOutputBytes;
+    constructor(logger?: Logger, onJobComplete?: ((cli: JobProvider, durationMs: number, success: boolean) => void) | undefined, store?: JobStore | null, flightRecorder?: FlightRecorderLike, limits?: JobLimitsConfig);
     private buildOrphanFlightResult;
     checkStalledJobs(now?: number): void;
     hasStore(): boolean;
@@ -98,6 +122,7 @@ export declare class AsyncJobManager {
     }): StartJobOutcome;
     private finalizeHttpJob;
     private fireOnComplete;
+    private releaseJobPermit;
     private writeFlightComplete;
     private safeExtractUsage;
     private httpUsage;
@@ -109,6 +134,8 @@ export declare class AsyncJobManager {
     getJobOwner(jobId: string): string | null | undefined;
     startJob(cli: LlmCli, args: string[], correlationId: string, cwd?: string, idleTimeoutMs?: number, outputFormat?: string, forceRefresh?: boolean, env?: Record<string, string>, onComplete?: () => void, flightRecorderEntry?: AsyncJobFlightRecorderEntry, extractUsage?: AsyncJobUsageExtractor, writeFlightStart?: boolean, stdin?: string): AsyncJobSnapshot;
     startJobWithDedup(cli: LlmCli, args: string[], correlationId: string, opts?: StartJobOptions): StartJobOutcome;
+    private launchProcessJob;
+    private failQueuedJob;
     getJobSnapshot(jobId: string): AsyncJobSnapshot | null;
     getJobSnapshots(jobIds: string[]): Record<string, AsyncJobSnapshot | null>;
     getJobResult(jobId: string, maxChars?: number): AsyncJobResult | null;
@@ -129,6 +156,11 @@ export declare class AsyncJobManager {
         zombieJobs: number;
         jobs: JobHealth[];
     };
+    acquireProcessSlot(provider: string): Promise<{
+        release: () => void;
+    }>;
+    getLimiterSnapshot(): JobLimiterSnapshot;
+    getConfiguredLimits(): JobLimitsConfig;
     getJobOutputFormat(jobId: string): string | undefined;
     getJobCli(jobId: string): JobProvider | undefined;
     private snapshot;