feat(providers): Cursor API provider (crsr_ keys) and Cursor CLI passthrough

[dpozimski]

Summary

Two things, both about using Cursor without an IDE session:

1. A new provider, cursor-api (dashboard card "Cursor API", alias cua). It is an API-key provider that holds a Cursor user API key (crsr_..., from cursor.com/dashboard/api) and reuses the existing Cursor agent executor, wire format and model catalog. The IDE provider (cursor, OAuth/IDE session) is untouched: separate registry entry, separate catalog card, separate executor binding (new CursorExecutor("cursor-api")), so API-key and IDE-session connections never share renewal, quota or dashboard semantics. A crsr_ key is not usable as a Bearer on api2.cursor.sh (it answers 401); cursor-agent POSTs it to /auth/exchange_user_api_key and gets a 1h session JWT whose refreshToken carries the same exp. open-sse/services/cursorApiKeyAuth.ts does that exchange, caches one session token per key, re-exchanges 5 minutes before expiry and drops the cache when Cursor answers 401. CursorExecutor resolves cursor-api connections to the exchanged token right before opening the h2 stream. The connection test for cursor-api is the exchange itself, so the credential-health sweep gets a real verdict instead of "not supported".

2. A Cursor CLI passthrough at /api/cursor-cli/[...path]. The CLI honours CURSOR_API_ENDPOINT, and with network.useHttp1ForAgent: true in ~/.cursor/cli-config.json every call it makes is plain HTTP/1.1: unary Connect RPCs, agent.v1.AgentService/RunSSE (SSE), BidiService/BidiAppend, OTLP traces and the key exchange. The handler (open-sse/handlers/cursorCliProxy.ts) authenticates /auth/exchange_user_api_key with an OmniRoute API key and answers with an OmniRoute-minted HS256 JWT (1h, JWT_SECRET); every other path verifies that JWT (issuer, audience, expiry, key still active), picks an active cursor-api connection, swaps in the Cursor credential and streams the upstream reply back. Each hop becomes a call_logs row (provider cursor-api, request type cursor-cli, the OmniRoute key and the connection that served it). The prefix is in PUBLIC_API_ROUTE_PREFIXES with handler-enforced auth, same as /api/codex/connect/.

The minted token has to be a real JWT: the CLI reads exp from whatever it gets back and re-exchanges before almost every request when the token is opaque (measured: 37 exchanges for 40 RPCs with an opaque token, 1 exchange with a JWT).

Provider count moves 341 to 342 (generated reference, diagrams, README, llm.txt mirrors, package.json description). Docs: docs/providers/CURSOR-API-KEY-AND-CLI.md.

History note: the first revision of this PR added API-key support as dual-auth on the cursor IDE provider; it was reworked into the separate cursor-api provider after review.

Related Issues

• None filed; this came out of running the Cursor CLI behind OmniRoute for usage attribution.

Validation

• Change type: provider
• Focused tests: node --import tsx/esm --test tests/unit/cursor-api-key-auth.test.ts tests/unit/cursor-cli-proxy.test.ts tests/unit/cursor-apikey-provider.test.ts tests/unit/public-api-routes.test.ts tests/unit/providers-constants-split.test.ts tests/unit/clinepass-provider.test.ts tests/unit/cursor-executor-split.test.ts tests/unit/cursor-streaming.test.ts tests/unit/cursor-registry-claude-families.test.ts tests/unit/deepai-provider.test.ts; npx bun scripts/check/check-provider-consistency.ts
• npx eslint and npx prettier --check on the changed files; npm run check:docs-all; npm run check:changelog-integrity; npm run gen:provider-reference
• Based on current release/v3.8.50 head (b754e44)
• Production-code changes include new automated tests in this PR

Live run (Docker image built from this branch, docker run omniroute:base with REQUIRE_API_KEY=true):

POST /api/providers {"provider":"cursor-api","name":"cursor-api-docker","apiKey":"crsr_..."} -> provider cursor-api, authType apikey
POST /api/providers/{id}/test                                                               -> {"valid":true,...,"diagnosis":{"type":"ok"}}
POST /v1/chat/completions model=cursor-api/auto                                             -> "CURSOR API PROVIDER VIA OMNIROUTE DOCKER WORKS", tokens in 56 / out 38
CURSOR_API_ENDPOINT=http://localhost:20128/api/cursor-cli CURSOR_API_KEY=<omniroute key> \
  agent -p --trust --model auto "..."                                                       -> "CURSOR CLI VIA OMNIROUTE DOCKER WORKS"

/api/usage/call-logs afterwards: 37 cursor-cli rows for the CLI run (1 auth/exchange_user_api_key, 1 agent.v1.AgentService/RunSSE 4.9 s, BidiService/BidiAppend turns, the rest dashboard/config RPCs), all with provider cursor-api, attributed to the OmniRoute key and the connection cursor-api-docker, plus the chat row with requestedModel cursor-api/auto. /v1/models lists the catalog as cursor-api/<id> and cua/<id>. Direct probes that drove the design: GetMe with the raw key gives 401, with the exchanged JWT gives 200.

Tests Added Or Updated

• tests/unit/cursor-api-key-auth.test.ts (new): exchange request shape, 401/5xx/malformed mapping, cache refresh window, in-flight dedupe, invalidation, bearer resolver for both connection shapes.
• tests/unit/cursor-cli-proxy.test.ts (new): exchange mint and 401/503/400/405 paths, token verification (missing, expired, foreign audience, tampered, revoked key), raw key rejected on RPC paths, header stripping and Authorization swap, connection cooldown/fallthrough, upstream 401 cache invalidation, SSE streaming with one log row, sanitized 502.
• tests/unit/cursor-apikey-provider.test.ts (new): cursor-api registry/catalog/executor wiring, cursor stays OAuth-only, executor credential resolution, connection test via exchange.
• tests/unit/providers-constants-split.test.ts: APIKEY_PROVIDERS count 228 to 229.
• tests/snapshots/executors/executor-map.json: cursor-api and cua entries.

Coverage Notes

cursorApiKeyAuth.ts, cursorCliProxy.ts and validateCursorApiProvider are covered end to end by the new unit tests through injected dependencies or a stubbed fetch (no DB or network). The executor change is three small paths (resolveExecutionCredentials, buildHeaders, the 401 invalidation) and the first two are asserted directly.

Reviewer Notes

• /api/cursor-cli/ does not spawn anything; it only calls fetch against api2.cursor.sh, so it is not in the LOCAL_ONLY set.
• The exchange endpoint mirrors the /v1/* policy when REQUIRE_API_KEY=false (anonymous session). Every other path still needs the minted JWT, so a stale Cursor token from a previous real login gets a 401 and the CLI re-exchanges, which is the behaviour the CLI already has.
• cursor-api model listing comes from the static Cursor registry (providerUsesExclusiveSyncedListing stays cursor-only), so no cursor-agent is needed on the host. Usage/quota fetch is not wired for cursor-api (the IDE path uses a session cookie); can follow up if wanted.

[dpozimski]

@diegosouzapw confirmed its working on my teammates' hosts