llm-cli-gateway 2.12.2 → 2.13.1

package/.agents/skills/multi-llm-review/SKILL.md

@@ -3,7 +3,7 @@ name: multi-llm-review
 description: Parallel code reviews across Claude, Codex, Gemini, Grok, and Mistral. Use for quality analysis, bug finding, or security audit.
 metadata:
   author: verivus-oss
-  version: "1.6"
+  version: "1.7"
 ---
 
 # Multi-LLM Code Review
@@ -24,10 +24,89 @@ Parallel reviews using gateway MCP tools. Each LLM has different strengths — c
 
 Apply these on every dispatch unless the caller has explicitly overridden a rule in the current turn:
 
-1. **Omit `model`** — let the gateway use its configured default per CLI. Nominating a model risks deprecated IDs (`o3`, `o3-pro`, `gpt-4o`, …) and capability mismatches. Call `list_models` only when the caller has asked for a specific variant.
-2. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). It gates the request before execution; Claude then runs with `--permission-mode bypassPermissions`, Gemini with `--approval-mode yolo`, and Codex still needs `fullAuto:true` for autonomous file/shell work. Prefer this over raw bypass flags.
-3. **No wallclock timeout; poll every 60 s** — let sync auto-defer at 45 s or use `*_request_async`. Poll `llm_job_status` once every 60 seconds. Do **not** cancel jobs for taking too long; cancel only on explicit instruction or hard failure. `idleTimeoutMs` (no-output safeguard) is separate.
-4. **Iterate until unconditional APPROVED** (review dispatches only) — every review prompt must end with "End with APPROVED or NOT APPROVED with findings." On `NOT APPROVED` or conditional approval, consolidate findings, dispatch fixes (Codex + `fullAuto:true`), re-dispatch the review to the same reviewer. Repeat until unconditional APPROVED. Escalate after 3 rounds without convergence. This rule does **not** apply to pure implementation or non-review analysis dispatches.
+1. **Use the stdio gateway MCP surface only** — call the host's `mcp__gtwy__*` tools (or the equivalent stdio `gtwy` namespace exposed to the current agent). Do not use connector/shadow gateway tools when the user asked for stdio gateway validation.
+2. **Omit `model`** — let the gateway use its configured default per CLI. Nominating a model risks deprecated IDs (`o3`, `o3-pro`, `gpt-4o`, ...) and capability mismatches. Call `list_models` only when the caller has asked for a specific variant.
+3. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). It gates the request before execution. Grant full non-interactive verification permissions on every review round because permission grants are not assumed durable.
+4. **Full verification access for reviewers is required** — reviewers need read, test/build, code-search, docs lookup, web/search, and provider-safe gateway introspection access where appropriate. Do not suppress tools or pass empty allowlists. If a provider-specific permission or MCP server required for verification is rejected, treat that as a review dispatch failure and fix the gateway/permission setup before proceeding, unless the user explicitly authorizes a degraded review.
+5. **No wallclock timeout; poll every 90 s** — use `*_request_async`. Poll `llm_job_status` no more than once every 90 seconds. Do **not** cancel reviewer jobs for taking too long; cancel only on explicit user instruction or a terminal provider/runtime failure. `idleTimeoutMs` (no-output safeguard) is separate.
+6. **Iterate until unconditional APPROVED** (review dispatches only) — every review prompt must end with a strict verdict requirement. On `NOT APPROVED`, `CHANGES_REQUIRED`, `BLOCKER`, or conditional approval, consolidate findings, apply fixes, refresh the verification report and exact diff/commit evidence, then re-dispatch the same reviewers. Repeat until unconditional approval or a concrete blocker remains after evidence-based rebuttal. This rule does **not** apply to pure implementation or non-review analysis dispatches.
+
+## Standard Validation Gate
+
+Use this gate whenever the user asks for "the other LLMs", "cross review",
+"red team", "validation", or similar review work.
+
+### Evidence Packet
+
+Before dispatch, prepare a stable packet and pass the same packet to every
+reviewer:
+
+- **Corrective-program verification report**: the local verification report used
+  as the spec for the review. It must list claims, commands run, test names,
+  command-result digests, and code/doc evidence.
+- **Exact change set**: commit SHA(s) when available, the diff range or explicit
+  `git diff` command, and the changed-file list. If the work is uncommitted,
+  state that clearly and include the exact dirty-file list.
+- **Scope and invariants**: DAG step(s), issue/PR references, security
+  invariants, docs that define intended behavior, and out-of-scope files.
+- **Review log from prior rounds**: verbatim reviewer findings plus per-finding
+  responses marked `FIXED`, `DISAGREE`, or `BLOCKER`, each with file:line, test,
+  command, or doc evidence.
+
+The packet is not a substitute for inspection. The prompt must explicitly say
+that the verification report and summary are claims, not evidence.
+
+### Reviewer Contract
+
+Every reviewer prompt must require:
+
+- Verify claims against actual code, tests, docs, and upstream documentation.
+- Open/read the changed files and relevant neighboring code directly.
+- Run or inspect the cited tests/builds; approval cannot be based on a summary,
+  intent, plan-compliance, or "should be fixed" language.
+- Cite concrete evidence for each finding: `file:line`, test name + command, or
+  upstream doc URL. If a claim cannot be verified, report it as at least a major
+  finding.
+- Return strict structured output with `verdict`, `findings`, `inspected`, and
+  `unconditional_approval_blockers`.
+
+Recommended final verdict enum:
+
+```json
+{
+  "verdict": "APPROVED | CHANGES_REQUIRED | BLOCKER",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "blocker | major | minor | nit",
+      "file": "src/example.ts",
+      "line": 123,
+      "claim": "Exact claim reviewed",
+      "issue": "What is wrong",
+      "evidence": "file:line, command/test output digest, URL, or unable to verify: reason",
+      "suggested_fix": "Concrete fix"
+    }
+  ],
+  "inspected": ["files, tests, commands, docs actually inspected"],
+  "unconditional_approval_blockers": ["F1"]
+}
+```
+
+### Evidence-Based Triage
+
+For every finding:
+
+- If correct: fix it, run the relevant local gates, update the verification
+  report, and start a new review round with a fresh exact change set.
+- If disputed: respond to that reviewer through the gateway with code/doc/test
+  evidence. Do not rebut with assertion, intent, "by design", or "the code should
+  already do that" unless accompanied by the exact evidence. The reviewer must
+  withdraw the finding or provide counter-evidence.
+- If unresolvable in scope: record it as a concrete `BLOCKER` with evidence and
+  stop advancing the change until the user decides scope.
+
+"Approved with nits" is not unconditional approval. Fix the nits or get the
+reviewer to withdraw them as non-blocking with evidence.
 
 ## Workflow
 
@@ -61,28 +140,30 @@ CLIs share Claude's tool names or MCP semantics. The same data is available as
 
 ### 2. Send Parallel Reviews
 
-Sync tools auto-defer at 45s — if response contains `status:"deferred"`, poll `jobId` via `llm_job_status` every 60s, fetch with `llm_job_result`.
+Sync tools auto-defer at 45s, but review gates should prefer async tools. Poll
+`jobId` via `llm_job_status` no more than once every 90s, fetch with
+`llm_job_result` only after a terminal status.
 
 **Tip — share the stable prefix across reviewers:** when the same long brief / file dump is sent to every reviewer, switch from `prompt` to the structured `promptParts` field. The gateway concatenates in canonical order `system → tools → context → task`, so every reviewer sees byte-identical stable prefix bytes, raising implicit cache hit rate at each provider. `prompt` and `promptParts` are mutually exclusive — the runtime returns `provide exactly one of \`prompt\` or \`promptParts\`` if both are supplied. After the round, read `cache-state://prefix/{hash}` (tokens/hashes only, no prompt text) to confirm reviewers actually shared the prefix.
 
 **Claude — Quality & Architecture:**
 ```
-claude_request({prompt:"Review changes in {path} for architecture, design patterns, maintainability, documentation gaps. Read the files directly. Specific line numbers and fixes. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+claude_request_async({prompt:"Review the attached evidence packet and exact change set for architecture, design patterns, maintainability, and documentation gaps. The packet is a claim, not evidence. Verify against the changed files, neighboring source, tests, and docs directly. Cite file:line/test/doc evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Codex — Logic & Correctness:**
 ```
-codex_request({prompt:"Analyze {path} for logic bugs, off-by-one, missing error handling, race conditions, test gaps. Read the files directly. Severity: critical/high/medium/low. End with APPROVED or NOT APPROVED with findings.",fullAuto:true,approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+codex_request_async({prompt:"Review the attached evidence packet and exact change set for logic bugs, off-by-one errors, missing error handling, races, and test gaps. The packet is a claim, not evidence. Verify against code/tests/docs directly. Cite file:line/test/doc evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",fullAuto:true,approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Gemini — Security & Edge Cases:**
 ```
-gemini_request({prompt:"Security audit {path}: injection, auth bypasses, data leaks, OWASP Top 10, crash-causing edge cases. Read the files directly. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+gemini_request_async({prompt:"Review the attached evidence packet and exact change set for security issues: injection, auth bypasses, data leaks, OWASP Top 10, and crash-causing edge cases. The packet is a claim, not evidence. Verify against code/tests/docs/upstream docs directly. Cite evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Grok — Independent Diversity (optional 4th reviewer):**
 ```
-grok_request({prompt:"Independent review of {path}. Read the files directly. Flag issues the other reviewers may have missed, contradict findings you disagree with, and call out blind spots. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+grok_request_async({prompt:"Independent review of the attached evidence packet and exact change set. The packet is a claim, not evidence. Verify against code/tests/docs directly, flag blind spots, and contradict weak findings with evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 Add Grok when consensus matters (high-stakes changes, security-critical paths) or to break ties between the other three. Auth must already be set up (`grok login` OAuth or `GROK_CODE_XAI_API_KEY`).
@@ -122,7 +203,10 @@ grok_request_async({prompt:"Independent diversity review of all TS files in src/
 mistral_request_async({prompt:"Independent Vibe review of all TS files in src/... End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",correlationId:"review-mistral"})
 ```
 
-Poll with `llm_job_status` every 60s, retrieve with `llm_job_result` when terminal. Jobs are durable — if your polling wrapper times out, re-issue the same call (the gateway auto-dedups onto the live job) or fetch by `jobId` later (default 30-day retention).
+Poll with `llm_job_status` no more than once every 90s, retrieve with
+`llm_job_result` when terminal. Jobs are durable — if your polling wrapper times
+out, re-issue the same call (the gateway auto-dedups onto the live job) or fetch
+by `jobId` later (default 30-day retention).
 
 For iterative Gemini reviews, pass `sessionId` for resumability:
 
@@ -135,23 +219,34 @@ gemini_request_async({prompt:"Deep security audit of src/... End with APPROVED o
 
 These patterns undermine review quality and trigger review integrity warnings:
 
-- **Don't inline code in `<code>` blocks** — provide file paths and let reviewers read files directly
+- **Don't use non-stdio gateway surfaces** when the requested validation path is
+  the local stdio gateway.
+- **Don't provide only a summary** — provide the verification report and exact
+  change set, while requiring reviewers to verify against files/tests/docs
+  directly.
+- **Don't under-grant review access** — full read, test/build, and MCP
+  verification access is the default. A partial-access review is not a valid
+  approval unless the user explicitly accepts that limitation.
 - **Don't suppress tools** — never include "do not run tools" or "respond only based on code provided" in review prompts
 - **Don't use `allowedTools:[]`** for reviews — reviewers need tool access to
   verify claims
 - **Don't copy tool names between providers** — Claude's `Read` / `Grep` /
   `Glob` names are not Grok, Codex, Gemini, or Vibe allowlist names. Check
   `provider_tool_capabilities` first, or omit provider tool allowlists.
-- **Do provide file paths** — `"Review changes in src/auth.ts"` instead of dumping file contents
+- **Don't cancel reviewer jobs** just because they are slow. Let them reach a
+  terminal status unless the user explicitly says to stop them.
+- **Do provide file paths and exact diff identifiers** — `"Review commit
+  abc123, diff range base..head, changed files src/auth.ts ..."` instead of
+  vague summaries.
 
 ## Iteration Loop (mandatory)
 
 Reviews are not one-shot. The caller runs this loop:
 
 1. Dispatch reviewer(s) with the verdict clause in the prompt
-2. Poll every 60s if deferred; fetch result
+2. Poll every 90s if deferred; fetch result only after terminal status
 3. Parse verdict from each reviewer — APPROVED / NOT APPROVED / conditional
-4. **Any NOT APPROVED or conditional** → consolidate findings → dispatch fixes (Codex + `fullAuto:true`) → re-dispatch same review → goto 2
+4. **Any NOT APPROVED, CHANGES_REQUIRED, BLOCKER, or conditional** → triage each finding with evidence → fix or rebut with code/doc/test citations → refresh verification report and exact diff → re-dispatch same review → goto 2
 5. **All APPROVED (unconditional)** → done
 6. After 3 rounds without convergence, escalate to the user
 
@@ -169,6 +264,6 @@ Reviews are not one-shot. The caller runs this loop:
 - Use all five async variants for true parallel reviews when you want Grok's
   independent perspective and Mistral Vibe's fifth review
 - Pass `sessionId` to `gemini_request_async` / `grok_request_async` for resumable follow-up
-- Check for `status:"deferred"` in sync responses — poll `jobId` every 60s if present
+- Check for `status:"deferred"` in sync responses — poll `jobId` no more than once every 90s if present
 - Gateway `mcpServers` default to the host's configured Claude MCP set; pass explicit server names only when the review needs those capabilities
 - **Re-issuing after a polling timeout is safe** — auto-dedup (default 1 h window, `LLM_GATEWAY_DEDUP_WINDOW_MS`) reattaches the new call to the existing job. Use `forceRefresh:true` only when inputs genuinely changed

package/CHANGELOG.md

@@ -2,7 +2,56 @@
 
 All notable changes to the llm-cli-gateway project.
 
-## [Unreleased]
+## [2.13.1] - 2026-07-01: code-scanning hardening and review-gate discipline
+
+### Security
+
+- **CodeQL remediation for URL, ReDoS, logging, and OAuth cookie alerts.**
+  API endpoint joining no longer uses slash-trimming regexes; ACP message
+  redaction now uses a stack-based single-pass JSON payload scanner with
+  truncated structured-payload fallback; central gateway stderr logging redacts
+  message strings, structured args, and nested `Error` name/message/stack
+  values; the xAI missing-key error no longer leaks the configured env var name;
+  and OAuth consent CSRF cookies now include `HttpOnly`, `Secure`,
+  `SameSite=Lax`, `Path=/oauth`, and `Max-Age=300`.
+- **Regression coverage for the fixed alert surfaces.** Added focused tests for
+  endpoint slash normalization, nested and truncated ACP payload redaction,
+  logger redaction before stderr output, generic xAI missing-key messaging, and
+  complete OAuth CSRF cookie attributes.
+
+### Docs
+
+- **Standardized cross-LLM review validation.** The shipped multi-LLM review
+  skill and best-practices guide now require the stdio gateway surface, no
+  provider model nomination, full non-interactive verification access,
+  90-second polling, exact evidence packets, no cancellation of slow reviewers,
+  evidence-based rebuttals, and iteration until unconditional approval or a
+  concrete blocker.
+
+## [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
 

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)**
 
@@ -960,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`
 
-Start a long-running Claude, Codex, Gemini, Grok, Mistral, or Devin request without waiting for completion in the same MCP call.
+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
+
+##### `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:
 
@@ -1021,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
@@ -1032,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
 
@@ -1052,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:**
 
@@ -1101,7 +1130,7 @@ List available models for each CLI.
 
 **Parameters:**
 
-- `cli` (string, optional): Specific provider to list models for (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, 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).
+- `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:**
 
@@ -1149,7 +1178,7 @@ inputs.
 
 **Parameters:**
 
-- `cli` (string, optional): Provider filter (`"claude"`, `"codex"`, `"gemini"`, `"grok"`, `"mistral"`, `"devin"`, `"grok_api"`, or an enabled API provider name)
+- `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
@@ -1170,6 +1199,7 @@ 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
@@ -1186,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`
 
@@ -1194,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`
@@ -1210,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:**
 
@@ -1227,7 +1258,7 @@ In addition to the spawnable CLI tools, the gateway can route requests to first-
 
 ### 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`); a collision is rejected with a warning and the provider is disabled.
+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

package/dist/acp/errors.js

@@ -1,7 +1,5 @@
 export function redactAcpMessage(input) {
-    let out = input;
-    out = out.replace(/\{[\s\S]*?\}/g, "<redacted-json>");
-    out = out.replace(/\[[\s\S]*?\]/g, "<redacted-json>");
+    let out = redactJsonLikeBodies(input);
     out = out.replace(/\b(bearer|token|api[_-]?key|secret)\b\s*[:=]?\s*\S+/gi, "$1 <redacted>");
     out = out.replace(/\b(sk|xai|gsk|key)-[A-Za-z0-9_-]{8,}\b/gi, "<redacted-token>");
     out = out.replace(/(^|[^A-Za-z0-9._~\\/-])[A-Za-z]:\\[^\s"')\]}>]*/g, "$1<redacted-path>");
@@ -11,6 +9,64 @@ export function redactAcpMessage(input) {
     out = out.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "<redacted-email>");
     return out;
 }
+function redactJsonLikeBodies(input) {
+    let out = "";
+    let cursor = 0;
+    let bodyStart = -1;
+    let stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input.charAt(index);
+        if (bodyStart === -1) {
+            const close = char === "{" ? "}" : char === "[" ? "]" : "";
+            if (!close)
+                continue;
+            bodyStart = index;
+            stack = [close];
+            inString = false;
+            escaped = false;
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = inString;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        const nestedClose = char === "{" ? "}" : char === "[" ? "]" : "";
+        if (nestedClose) {
+            stack.push(nestedClose);
+            continue;
+        }
+        if (char !== stack[stack.length - 1])
+            continue;
+        stack.pop();
+        if (stack.length > 0)
+            continue;
+        out += input.slice(cursor, bodyStart);
+        out += "<redacted-json>";
+        cursor = index + 1;
+        bodyStart = -1;
+    }
+    if (bodyStart !== -1 && isLikelyJsonPayload(input.slice(bodyStart))) {
+        out += input.slice(cursor, bodyStart);
+        out += "<redacted-json>";
+        cursor = input.length;
+    }
+    return cursor === 0 ? input : out + input.slice(cursor);
+}
+function isLikelyJsonPayload(span) {
+    return /"(?:jsonrpc|method|params|prompt|content|body|token|secret|api[_-]?key|credential|auth|cwd|path|[A-Za-z0-9_-]+)"\s*:/i.test(span);
+}
 export function redactAcpDebug(value) {
     const sensitiveKey = /(payload|body|prompt|content|token|secret|api[_-]?key|credential|auth|cwd|path)/i;
     if (typeof value === "string") {

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-http.js

@@ -40,8 +40,8 @@ export function isLoopbackUrl(value) {
     }
 }
 export function buildEndpointUrl(baseUrl, path) {
-    const trimmedBase = baseUrl.replace(/\/+$/, "");
-    const trimmedPath = path.replace(/^\/+/, "");
+    const trimmedBase = stripTrailingSlashChars(baseUrl);
+    const trimmedPath = stripLeadingSlashChars(path);
     const url = new URL(`${trimmedBase}/${trimmedPath}`);
     if (url.protocol !== "https:" &&
         !(url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname))) {
@@ -49,6 +49,20 @@ export function buildEndpointUrl(baseUrl, path) {
     }
     return url;
 }
+function stripTrailingSlashChars(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function stripLeadingSlashChars(value) {
+    let start = 0;
+    while (start < value.length && value.charCodeAt(start) === 47) {
+        start += 1;
+    }
+    return value.slice(start);
+}
 export function isHttpTransient(error) {
     const status = typeof error?.status === "number" ? error.status : null;
     if (status === 429 || (status !== null && status >= 500))

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

@@ -7,7 +7,7 @@ import { type ApiProvider, type ApiRequest, type ApiUsage } from "./api-provider
 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 = "queued" | "running" | "completed" | "failed" | "canceled" | "orphaned";
 export declare function isAsyncJobInProgress(status: AsyncJobStatus): boolean;

package/dist/cli-updater.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "./logger.js";
-import type { CliType } from "./session-manager.js";
+import { type CliType } from "./provider-types.js";
 import { type ProviderLoginStatus } from "./provider-status.js";
 import type { ProviderLoginGuidance } from "./provider-login-guidance.js";
 export interface CliVersionInfo {