cursor-opencode-provider 0.7.6 → 0.8.0

package/README.md

@@ -132,7 +132,7 @@ The provider never detects or names fork hosts. Compatibility layers own host id
 | Model, version, and 24-hour conversation **cache** | `~/.cache/opencode/` | A host bridge may replace the root |
 | Cursor **project metadata** (`agent-tools`, terminals, …) | `~/.cache/opencode/projects/<slug>/` | under `<host-cache>/projects/` |
 | OpenCode **auth** (`auth.json`) | `~/.local/share/opencode/` | `$XDG_DATA_HOME/opencode/` when set |
-| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | still OpenCode-named for rule discovery |
+| OpenCode **config** (AGENTS, skills, …) | `~/.config/opencode/` | `$XDG_CONFIG_HOME/opencode/` when set, as OpenCode resolves it |
 
 ### Select a model
 
@@ -220,7 +220,7 @@ const model = cursor.languageModel("composer-2.5")
 // model implements AI SDK LanguageModelV3 (doStream / doGenerate)
 ```
 
-Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `crsr_...` key). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses an injected structural host path bridge or the native OpenCode XDG cache described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Once that budget is spent, or replay is unsafe, the terminal error does not re-arm OpenCode's outer retry loop. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
+Give one credential source. The provider uses the first present and never falls back from one to another: `getAccessToken` (an async function returning the current access token, called for every Run so a long-running process can renew its login; it receives `{ forceRefresh: true }` once after Cursor rejects a token), then `accessToken` (a JWT sent as-is, never renewed), then `apiKey` (a raw `crsr_...` key, exchanged for a JWT and exchanged again near its expiry, the way Cursor CLI renews an API-key login). Optional: `apiBaseURL`, `agentBaseURL`, `cacheDir`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. `cacheDir` pins the host cache root for model/version caches and Cursor project metadata; when omitted, the provider uses an injected structural host path bridge or the native OpenCode XDG cache described in [Paths](#paths-host-cache). Transient failures resume from the latest checkpoint produced by that Run, matching Cursor CLI; without an eligible checkpoint, retries remain limited to replay-safe attempts so completed text or tool work is not duplicated. Once that budget is spent, or replay is unsafe, the terminal error does not re-arm OpenCode's outer retry loop. Pending-tool inactivity is renewed by OpenCode activity from the session or its descendants. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
 
 ## Environment variables
 
@@ -268,7 +268,7 @@ OpenCode
 
 | Module | Role |
 |--------|------|
-| `src/plugin.ts` | Classic OpenCode hooks: provider registration, OAuth, API key exchange, token refresh |
+| `src/plugin.ts` | Classic OpenCode hooks: provider registration, OAuth, API key exchange, login renewal and persistence |
 | `src/plugin-v2.ts` | OpenCode 1.18 Effect/Promise v2 plugin (`ctx.aisdk.*`); load via `./plugin/v2` only |
 | `src/plugin-opencode2.ts` | OpenCode 2.0 plugin (`provider.transform`, integration, tools, aisdk, `shell.create.before`, `websearch`, plan kickoff); load via `./plugin/opencode2` or `./server` |
 | `src/opencode2/` | 2.0-only provider inventory, integration/auth, and local API types |
@@ -280,7 +280,8 @@ OpenCode
 | `src/language-model.ts` | AI SDK `LanguageModelV3` adapter (`doStream`, `doGenerate`) |
 | `src/session.ts` | Held-open agent Run session and pending exec correlation |
 | `src/debug.ts` | Opt-in wire-level debug logging (`CURSOR_PROVIDER_DEBUG`) |
-| `src/auth.ts` | PKCE OAuth, API key exchange, JWT refresh |
+| `src/auth.ts` | PKCE OAuth, API key exchange, browser-login session refresh (`/oauth/token`) |
+| `src/auth-renewal.ts` | Credential renewal policy: session and API-key renewal kept separate, backoff, on-demand renewal, Bearer resolution |
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
 | `src/protocol/conversation-persistence.ts` | Atomic per-session restart snapshots under the 24-hour `cursor-conversations/` cache |
 | `src/context/paths.ts` | Host cache root + Cursor project metadata under `<host-cache>/projects/<slug>/` |
@@ -293,7 +294,7 @@ OpenCode
 
 The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability, canonical workspace-path grounding, preferring OpenCode `todowrite` / `todoread` over Cursor TodoWrite when those tools are advertised without inviting catalog-comparison narration, and preferring `edit` / `write` (or `apply_patch`, when the host advertises that instead) over shell-based file mutation when those tools are available. Compaction keeps its dedicated prompt unchanged.
 
-Cursor keeps OpenCode `skill` and configured MCP tools off its native top-level function list on **both** OpenCode 1.x and OpenCode 2.0 — they appear as MCP descriptors and are reached through GetDynamicTools / CallDynamicTool. When the host advertises `skill` and/or tools of MCP servers configured in `opencode.json`, the provider names those routes in system guidance and mirrors OpenCode's load-when-matches / do-not-reinvoke rules. Mid-Conversation skill reminders fire only when the available-skills catalog changes after baseline admission (same contract as OpenCode `SkillGuidance` / `SkillInstructions`) — not on every user turn that happens to mention a skill id — so models prefer `skill` / MCP over Grep/Shell and do not narrate that those tools are unavailable. OpenCode 2 still moves MCP servers that did not set `"codemode": true` onto the direct AI SDK catalog first; without that placement they never reach Cursor's MCP ads at all (see [OpenCode 2 MCP tools](docs/opencode-2.md#mcp-tools)).
+Cursor keeps OpenCode `skill` and configured MCP tools off its native top-level function list on **both** OpenCode 1.x and OpenCode 2.0 — they appear as names-only MCP descriptors and are reached through GetDynamicTools / CallDynamicTool (exec #36 supplies full definitions). When the host advertises `skill` and/or tools of MCP servers configured in `opencode.json`, the provider names those routes in system guidance and mirrors OpenCode's load-when-matches / do-not-reinvoke rules so models prefer `skill` / MCP over Grep/Shell and do not narrate that those tools are unavailable. Skill catalog changes after admission are host `<system-update>` notes, not a second RequestContext skill list. OpenCode 2 still moves MCP servers that did not set `"codemode": true` onto the direct AI SDK catalog first; without that placement they never reach Cursor's MCP ads at all (see [OpenCode 2 MCP tools](docs/opencode-2.md#mcp-tools)).
 
 Native Cursor todo display updates (`update_todos_tool_call` / `read_todos_tool_call`) are mirrored into `todowrite` / `todoread` when those host tools are advertised. OpenCode 2 dropped the host builtins; set `CURSOR_OPENCODE2_TODOS=1` (or `true`) to register the same canonical names when the catalog omits them (in-memory per session, cleared on `session.deleted` and process restart). With the flag unset, the plugin registers no todo tools. Enabled plugin tools are **direct** catalog tools (`options.codemode: false` plus an `output` schema), not Code Mode helpers. The provider retains the last known full list per OpenCode session — refreshed by bridged writes, direct host `todowrite` calls, and `todoread` results, surviving Run close, checkpoint resume, and later turns — so `merge: true` updates that omit Cursor's completed list still become a host replace-all snapshot (matched by id, then by content across id spaces). This snapshot is in-memory only and never enters the prompt, RequestContext, or persisted restart state, so Cursor's prompt-cache prefix is unaffected; a provider process restart clears it until the next write/read (intentional — see `tasks/lessons.md`).
 
@@ -346,7 +347,7 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 |---------|-------------|
 | No Cursor models in the picker (OpenCode 1.x) | Confirm Cursor auth (`opencode auth login` → **cursor**). Restart OpenCode — if auth is present and the cache is empty, models are fetched on startup. Confirm `provider.cursor.npm` is the package name (or a built `file://…/dist/index.js`). See [OpenCode 1.x troubleshooting](docs/opencode-1.md#troubleshooting). |
 | No Cursor models in the picker (`opencode2`) | Confirm `/connect` → **Cursor** (or shared `auth.json`). Use a dedicated `OPENCODE_CONFIG_DIR` (not mixed with 1.x). Ensure `$OPENCODE_CONFIG_DIR/plugins/cursor/` is a package directory re-exporting `plugin/opencode2` (not a bare `.js`). After auth, Cursor models appear in the picker from the in-memory inventory — no `opencode.json` model list is required. Filter by provider **Cursor** (`time.released` is `0`, so models sort last). Leftover `providers.cursor` fights that inventory — [safe transition](docs/opencode-2.md#safe-transition). |
-| Auth / 401 errors mid-session | Re-login. OAuth and exchanged API-key JWTs refresh automatically when near expiry; a revoked refresh token needs a fresh login. |
+| Auth / 401 errors mid-session | Logins renew themselves: a browser login (60-day session) is renewed through Cursor's `/oauth/token` once less than 1272 h of it remain, as Cursor's IDE decides, whenever a request needs a token (there is no background timer, as with OpenCode's own OAuth providers); an API-key login exchanges its stored key again within five minutes of the exchanged JWT's expiry, as Cursor CLI does. The two never stand in for each other. Sign in again when the error says the session was ended, the key was rejected, or a sign-in policy blocks it. An API-key login saved before the key was kept (`metadata.apiKey`) cannot be renewed and needs one fresh API-key sign-in. Renewal attempts and failures go to the debug log (`CURSOR_PROVIDER_DEBUG`). |
 | Local OpenCode 2.0 still runs the published package | Set `CURSOR_OPENCODE2_DEV_ENTRY` to an absolute `…/dist/index.js` path **before** starting the daemon, persist it with `opencode2 service set env CURSOR_OPENCODE2_DEV_ENTRY …`, rebuild (`bun run build`), then `opencode2 service restart`. Loading only `dist/plugin-opencode2.js` is not enough — without the env var, 2.0 still `npm install`s the published package into the host cache. |
 | “Too many connections from different devices” | Device IDs are derived from stable OS identifiers (same approach as the Cursor CLI). Avoid running multiple clients that invent different machine fingerprints for the same account. |
 | Empty or stale model list | Delete `<host-cache>/cursor-models.json` (native default `~/.cache/opencode/`) and restart OpenCode. A compatibility layer may supply a different host-cache root through the structural path bridge. Existing Cursor auth is enough to refill the cache; re-login only if auth itself is broken. Cache TTL is 24h; a failed background refresh keeps serving the previous cache. |
@@ -367,7 +368,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 
 - **Personal use / ToS** — this provider speaks Cursor’s private agent protocol (CLI-shaped client identity). Use only with an account you own; Cursor may change or restrict the API without notice.
 - **Cursor's checkpoint controls displayed totals** — live continuation captures show `TurnEnded` counters can decrease between turns and can represent aggregate model work rather than final context occupancy. When a checkpoint contains `ConversationStateStructure.token_details`, the provider makes AI SDK input + output equal Cursor's `used_tokens`; at `TurnEnded`, output/reasoning remain based on `TurnEnded`, while uncached/cache-read/cache-write input are proportionally normalized to the remaining context input. OpenCode TUI/GUI replace each assistant message's tokens (TUI requires `tokens.output > 0`) and add cost per step, so mid-turn tool boundaries emit the last-known occupancy snapshot rather than a delta or a billed zero. Those snapshots set `output=1` so the footer updates and `providerMetadata.copilot.totalNanoAiu: 0` so OpenCode's getUsage reports $0 instead of charging occupancy as a new prompt. A Run without fresh token details retains the previous checkpoint snapshot and marks `providerMetadata.cursor.context` as `source: "checkpoint-previous-turn", stale: true`. If no checkpoint has ever supplied token details, standard usage is zero and context metadata is absent, so `TurnEnded` is never misrepresented as occupancy; its exact values remain under `providerMetadata.cursor.*Raw`. The full known snapshot includes `usedTokens`, `maxTokens`, percentage, category breakdown, source, and staleness. Cursor consistently sends `cache_write=0` in captured Runs, so no alternate write count is available.
-- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Expensive workspace state (rules, environment, repository, git, and layout) is frozen per Cursor conversation and persisted for restart recovery. Tools/MCP descriptors, skills, subagents, and plugin metadata are rediscovered each Run then epoch-held (equal ids keep frozen bytes; new ids append); unchanged overlays reuse byte-identical encoded context. Concurrent first Runs share one base build, and compaction/reset clears it. Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
+- **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` with OpenCode's system prompt (its `AGENTS.md` / `instructions`, skill list, MCP instructions) plus the provider's interaction guidance as one always-apply rule, workspace env, git, layout, host-advertised `task`/`subagent` names, names-only tool overlay, and plugin lines. Cursor does not follow a client-seeded `system` message or an untyped rule, so the always-apply (`global`) rule is the channel that makes `AGENTS.md` effective; the provider does not read instruction or skill files itself. Merged `opencode.json` is still read for MCP server ids, plugin lists, and interaction guidance. Expensive workspace state (environment, repository, git, and layout) is frozen per Cursor conversation and persisted for restart recovery. Tools/MCP names, host subagents, and plugin metadata are rediscovered each Run then epoch-held (equal ids keep frozen bytes; new ids append); unchanged overlays reuse byte-identical encoded context. Concurrent first Runs share one base build, and compaction/reset clears it. Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **Configured MCP tools keep their upstream server id** — OpenCode builtins and plugin/custom tools are advertised under a synthetic `opencode` MCP server. Tools whose flattened name matches an MCP server in merged `opencode.json` configuration (`github_create_pull_request`, …) are grouped into that server's `mcp_descriptors` / `provider_identifier` (`github`, …). Unknown underscore-containing names stay under `opencode` rather than being guessed incorrectly. Cursor's MCP-state exec probe is answered from the same advertised descriptors before the actual tool request, using the full canonical tool-definition identity required by native `get_mcp_tools` / GetDynamicTools; exec still reconstructs the full OpenCode tool id. That discovery call is Cursor-native (not an OpenCode catalog tool). Oversized catalogs spill through `write_args` into `agent-tools/<uuid>.txt`; `WriteSuccess.path` echoes the requested path so the model receives a real `filePath` instead of an empty spill.
 - **Display completions are notifications, not execution requests** — Cursor `tool_call_*` frames use a typed `ToolCall` oneof. The provider decodes them for diagnostics but only mirrors finalized todo/plan state (`update_todos_tool_call` → `todowrite`, `read_todos_tool_call` → `todoread`, `create_plan_tool_call` → `todowrite`); the completed payload already contains the authoritative final list. Interactive, data-returning, and side-effecting completions are never replayed as new tools because their result could not be returned to Cursor. Exec-backed native subagent/Task and Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged. All 37 Cursor CLI exec request/result pairs are inventoried by field and name. Known-but-unsupported variants are soft-denied on the held Run with a populated typed error/`rejected`/`allowlisted:false` result (or `throw` when the CLI has no typed error shape) so the turn continues; unknown future request fields still fail the Run explicitly rather than receiving a guessed response that could deadlock it.
 - **Progress-only fragments can get one continuation** — if a real tool-enabled turn ends with a short progress fragment ("Checking the workspace", "Looking into it now") and no host tool call, the provider opens one follow-up Run with a synthetic user nudge so the model can call a listed tool or finish the answer. Complete answers that merely start with those verbs are not continued. Title/compaction turns (`allowTools=false`) never continue. If the continuation fails, the original `turn_ended` is still reported as a successful stop.
@@ -378,6 +379,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **Cursor-native AskQuestion reaches you through OpenCode's question tool** — when Cursor asks a clarifying question, the provider translates the interaction into the host `question` tool, so the prompt appears in OpenCode with its real options and your answer is mapped back to Cursor's option ids (an answer you type yourself becomes Cursor's freeform text). Questions Cursor marks as non-blocking are acknowledged immediately and answered later, matching Cursor CLI. If the current agent does not offer `question` — most subagents deny it, and compaction turns have no tools — the request is declined with that reason and the model asks in its reply instead.
 - **Cursor-native SwitchMode follows each OpenCode generation's planning model** — on OpenCode 1.x, advertised `plan_enter` / `plan_exit` tools remain authoritative and Cursor waits for their approve/reject result. OpenCode 2.0 replaced those tools with vendor-maintained primary `plan` / `build` agents, so its plugin applies an approved Cursor mode change through `session.switchAgent` after the owning Run is terminal; leaving plan still uses the advertised `question` gate when no `plan_exit` tool exists. Direct host UI agent switches are also observed. Any real host-agent or stable system-prompt change rotates and reseeds the Cursor conversation instead of resuming an incompatible checkpoint, while title/generation lifecycle prompts remain ephemeral and do not evict the primary cache. Provider-owned Cursor reminders remain the fallback when a host cannot switch agents.
 - **Cursor image generation saves through OpenCode's permission where the host API exposes it** — Cursor generates the image on its servers and then writes it like any other file. On the classic plugin/OCP surfaces, the provider holds raw bytes and asks for the same permissions as a normal write (`external_directory`, then `edit`) before saving byte-for-byte. OpenCode 2.0's public plugin `ToolContext` does not expose a permission-request method, so its entrypoint deliberately does not advertise `cursor_image_save`; generation and binary writes are refused before staging instead of bypassing permissions or exposing an always-failing tool. By default supported-host images land in the Cursor project folder under `assets/`, kept out of the git tree as agent artifacts. Editing an existing image with `reference_image_paths` is not supported yet. The classic implementation is adapted from [`jkalasas/opencode-antigravity-image`](https://github.com/jkalasas/opencode-antigravity-image) (MIT) by jkalasas.
+- **Switching models mid-session reseeds Cursor instead of resuming a stale checkpoint** — a Cursor conversation only contains what Cursor itself produced. When the host's latest assistant turn in a session came from another model (another provider or a local model), the provider starts a fresh Cursor conversation seeded with the full host history, tool results included, rather than resuming the old checkpoint that would hide the other model's work (and has been observed to end Runs with `Cursor API error (code=internal)`). If that history would fill more than 80% of the target model's context, the provider reports a context overflow before opening a Run so the host compacts first.
 - **Cursor-native CreatePlan writes a host plan file, then asks before executing it** — when Cursor raises `create_plan_request_query`, the provider writes plain markdown to your host's own plans directory (`<hostGlobalDataDir>/plans/`, never your repository and never Cursor's `~/.cursor/plans`), with no Cursor YAML frontmatter. Writing the plan does not ask; running it does. If you are in plan mode, the provider prints the plan into the conversation — Cursor sends it over a side channel that would otherwise never display it — and then asks *"Plan at &lt;path&gt; is complete. Would you like to switch to the build agent and start implementing?"* — the same prompt OpenCode's own `plan_exit` uses — and keeps Cursor waiting for your answer. Answer **Yes** and the plan is reported as approved and implementation begins; answer **No** (or dismiss it) and Cursor is told the plan was not accepted, so the model refines it and proposes again instead of starting work. Hosts that advertise their own plan-staging tool run their native review UI instead, and it reports the same approve/refine outcome. Empty args still get the CLI empty-`plan_uri` success ack. Display `create_plan_tool_call` continues to mirror into `todowrite` separately.
 - **Other Cursor-native interaction queries remain headless** — remaining UI/approval *queries* (as distinct from display tool calls and the AskQuestion / SwitchMode / CreatePlan / GenerateImage bridges) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects available web capabilities to executable host tools (`custom_websearch`, `custom_webfetch`); native web/PR/MCP/SCM requests are declined so they remain behind host tool permissions. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **Compaction resets Cursor conversation state without resetting stable workspace context** — the classic plugin marks OpenCode's `compaction` agent explicitly. On those turns the provider mints an isolated Cursor `conversation_id`, drops the prior checkpoint + KV blobs, preserves real tool outputs as OpenCode-host observations in the seed history, and re-advertises the session's last tool catalog while refusing execution during the summary itself. The first normal turn then rebases once more onto a fresh conversation seeded with OpenCode's compacted prompt and normal system instructions, so the summary-agent checkpoint cannot suppress later tool calls. Across both id rotations, the frozen workspace/rules/environment base and its prior encoded-context comparison seed are transferred instead of rebuilt; tools, skills, agents, plugins, and MCP state are still rediscovered, and the complete context is reused only when its bytes remain identical. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state. Debug logs include system-prompt and encoded RequestContext hashes for cache-prefix verification.

package/dist/agent-url.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { fetchAgentUrl } from "./transport/connect.js";
-import { trace } from "./debug.js";
+import { errorMessage, trace } from "./debug.js";
 import { CURSOR_API_HOST } from "./shared.js";
 const DEFAULT_API_BASE = `https://${CURSOR_API_HOST}`;
 // In-process memo of the region-specific Run stream origin (agentnUrl). Resolved
@@ -59,7 +59,7 @@ export async function resolveAgentUrl(token, options = {}) {
             return url;
         }
         catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
+            const reason = errorMessage(err);
             trace(`agent-url: GetServerConfig failed (${reason}); no fallback agent host will be used`);
             throw err;
         }

package/dist/auth-renewal.d.ts

@@ -0,0 +1,85 @@
+/** Cursor IDE renews a session once less than this remains (`hir = 1272h`). */
+export declare const SESSION_RENEWAL_WINDOW_MS: number;
+/** Never renew a session token younger than this, whatever its lifetime. */
+export declare const SESSION_MIN_AGE_MS = 3600000;
+export type TokenTimes = {
+    issuedAtMs?: number;
+    expiresAtMs?: number;
+};
+/**
+ * Issue and expiry times of a Cursor JWT. Cursor session tokens carry the
+ * issue time in a `time` claim (seconds, as a string); standard `iat` is used
+ * when present instead.
+ */
+export declare function tokenTimes(token: string): TokenTimes;
+/**
+ * When a session token is due for renewal: 1272 h before expiry, but never
+ * within an hour of issue. Undefined when the token has no readable expiry.
+ */
+export declare function sessionRenewalDueAt(token: string): number | undefined;
+export type SessionTokens = {
+    accessToken: string;
+    refreshToken: string;
+};
+export type SessionRenewal = {
+    accessToken: string;
+    /** True when `accessToken` differs from the stored one and should be persisted. */
+    renewed: boolean;
+    /** Set while a failed renewal is backing off: when the next attempt is allowed. */
+    retryAt?: number;
+};
+/**
+ * Follow renewals this process already made, so a caller still holding an
+ * older stored credential (persisting failed, or a host that persists only
+ * later) gets the newest token instead of renewing again.
+ */
+export declare function latestSessionTokens(tokens: SessionTokens): SessionTokens;
+export declare function isSessionRenewalDue(token: string, now?: number): boolean;
+/**
+ * Return a usable session token, renewing it first when it is due (or when
+ * `force` is set after Cursor rejected it). Renewal failures that leave the
+ * current token valid keep it; a session Cursor ended, or one that expired
+ * and could not be renewed, raises `CursorAuthError`.
+ */
+export declare function renewSessionIfDue(tokens: SessionTokens, options?: {
+    baseUrl?: string;
+    force?: boolean;
+}): Promise<SessionRenewal>;
+export type ApiKeyToken = {
+    accessToken: string;
+    /** True when `accessToken` differs from the stored `seed` and should be persisted. */
+    renewed: boolean;
+};
+/**
+ * JWT for a raw `crsr_` API key: the cached or `seed` JWT while it is not
+ * within five minutes of expiry, otherwise a fresh exchange. Cached per API
+ * base URL and key. Never returns the raw key itself.
+ */
+export declare function resolveApiKeyToken(apiKey: string, options?: {
+    baseUrl?: string;
+    seed?: string;
+    force?: boolean;
+}): Promise<ApiKeyToken>;
+export type AccessTokenRequest = {
+    forceRefresh?: boolean;
+};
+/** Host-supplied source of the current Cursor access token. */
+export type AccessTokenProvider = (request?: AccessTokenRequest) => Promise<string>;
+/**
+ * Bearer token for a Cursor request. One credential source is used, in this
+ * order, and none of them falls back to another:
+ *
+ * 1. `getAccessToken` — the host resolves (and renews) the token per request.
+ * 2. `accessToken` — sent as-is.
+ * 3. `apiKey` — a raw `crsr_` key is exchanged and renewed; any other value is
+ *    a token a host forwarded through the generic API-key slot, sent as-is.
+ */
+export declare function resolveBearerToken(input: {
+    getAccessToken?: AccessTokenProvider;
+    accessToken?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    forceRefresh?: boolean;
+}): Promise<string>;
+/** Reset all renewal state (tests). */
+export declare function resetAuthRenewalState(): void;

package/dist/auth-renewal.js

@@ -0,0 +1,284 @@
+import { CURSOR_API_HOST, TOKEN_EXPIRY_THRESHOLD_S } from "./shared.js";
+import { AuthExchangeError, decodeJwtPayload, exchangeApiKey, isExchangeableApiKey, isExpiringSoon, refreshCursorSession, } from "./auth.js";
+// Failure details quote HTTP status text ("503 Service Unavailable"), and
+// OpenCode's SessionRetry keys off such words in provider error messages.
+import { CursorAuthError, CursorServerError, sanitizeHostTerminalMessage } from "./errors.js";
+import { errorMessage, trace } from "./debug.js";
+// Credential renewal policy. The two Cursor credential kinds are renewed by
+// independent paths and never stand in for each other:
+//
+// - Browser-login session (OAuth): `POST /oauth/token`, the way Cursor's IDE
+//   renews it, starting once less than 1272 h of its 60-day life remain.
+// - API key: re-exchange the raw `crsr_` key when the exchanged JWT nears
+//   expiry, the way Cursor CLI renews it. Its refresh token is never used.
+//
+// Renewal happens only on demand, when a request needs a token, as OpenCode's
+// own OAuth providers do (a per-request `fetch` that reads `getAuth()`); there
+// is no timer. Both keep the current token through a transient failure while
+// it is still valid, back off between attempts, and latch final failures so
+// they are not retried for the same credential.
+const API_BASE = `https://${CURSOR_API_HOST}`;
+/** Cursor IDE renews a session once less than this remains (`hir = 1272h`). */
+export const SESSION_RENEWAL_WINDOW_MS = 1272 * 3_600_000;
+/** Never renew a session token younger than this, whatever its lifetime. */
+export const SESSION_MIN_AGE_MS = 3_600_000;
+/** A token is still worth sending while it has at least this long left. */
+const USABLE_MARGIN_MS = 30_000;
+const BACKOFF_INITIAL_MS = 30_000;
+const BACKOFF_MAX_MS = 15 * 60_000;
+/** Remember at most this many in-process session renewals. */
+const MAX_SESSION_SUCCESSORS = 32;
+const SIGN_IN_AGAIN = "sign in to Cursor again";
+/**
+ * Issue and expiry times of a Cursor JWT. Cursor session tokens carry the
+ * issue time in a `time` claim (seconds, as a string); standard `iat` is used
+ * when present instead.
+ */
+export function tokenTimes(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return {};
+    const seconds = (value) => {
+        const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+        return typeof n === "number" && Number.isFinite(n) ? n * 1000 : undefined;
+    };
+    const expiresAtMs = seconds(payload.exp);
+    const issuedAtMs = seconds(payload.iat) ?? seconds(payload.time);
+    return {
+        ...(issuedAtMs !== undefined ? { issuedAtMs } : {}),
+        ...(expiresAtMs !== undefined ? { expiresAtMs } : {}),
+    };
+}
+/**
+ * When a session token is due for renewal: 1272 h before expiry, but never
+ * within an hour of issue. Undefined when the token has no readable expiry.
+ */
+export function sessionRenewalDueAt(token) {
+    const { issuedAtMs, expiresAtMs } = tokenTimes(token);
+    if (expiresAtMs === undefined)
+        return undefined;
+    const due = expiresAtMs - SESSION_RENEWAL_WINDOW_MS;
+    return issuedAtMs === undefined ? due : Math.max(due, issuedAtMs + SESSION_MIN_AGE_MS);
+}
+function isUsable(token, now) {
+    const { expiresAtMs } = tokenTimes(token);
+    return expiresAtMs === undefined || expiresAtMs - now > USABLE_MARGIN_MS;
+}
+/** The token that stays valid longer (the first one on a tie or unknown expiry). */
+function longerLived(a, b) {
+    const aExp = tokenTimes(a).expiresAtMs;
+    const bExp = tokenTimes(b).expiresAtMs;
+    return bExp !== undefined && (aExp === undefined || bExp > aExp) ? b : a;
+}
+function isoTime(ms) {
+    return ms === undefined ? "unknown" : new Date(ms).toISOString();
+}
+function backoffMs(failures) {
+    return Math.min(BACKOFF_MAX_MS, BACKOFF_INITIAL_MS * 2 ** Math.max(0, failures - 1));
+}
+function stateFor(map, key) {
+    let state = map.get(key);
+    if (!state) {
+        state = { failures: 0 };
+        map.set(key, state);
+    }
+    return state;
+}
+function recordTransientFailure(state, message) {
+    state.failures++;
+    state.retryAt = Date.now() + backoffMs(state.failures);
+    state.lastFailure = message;
+}
+function recordSuccess(state) {
+    state.failures = 0;
+    state.retryAt = undefined;
+    state.lastFailure = undefined;
+}
+const sessionStates = new Map();
+/** Stored refresh token → newer session token this process obtained for it. */
+const sessionSuccessors = new Map();
+/**
+ * Follow renewals this process already made, so a caller still holding an
+ * older stored credential (persisting failed, or a host that persists only
+ * later) gets the newest token instead of renewing again.
+ */
+export function latestSessionTokens(tokens) {
+    let current = tokens;
+    for (let hops = 0; hops < MAX_SESSION_SUCCESSORS; hops++) {
+        const next = sessionSuccessors.get(current.refreshToken);
+        if (!next || next === current.refreshToken)
+            break;
+        current = { accessToken: next, refreshToken: next };
+    }
+    return longerLived(tokens.accessToken, current.accessToken) === current.accessToken ? current : tokens;
+}
+function rememberSuccessor(refreshToken, accessToken) {
+    sessionSuccessors.delete(refreshToken);
+    sessionSuccessors.set(refreshToken, accessToken);
+    while (sessionSuccessors.size > MAX_SESSION_SUCCESSORS) {
+        const oldest = sessionSuccessors.keys().next().value;
+        if (oldest === undefined)
+            break;
+        sessionSuccessors.delete(oldest);
+    }
+}
+export function isSessionRenewalDue(token, now = Date.now()) {
+    const due = sessionRenewalDueAt(token);
+    return due !== undefined && now >= due;
+}
+/**
+ * Return a usable session token, renewing it first when it is due (or when
+ * `force` is set after Cursor rejected it). Renewal failures that leave the
+ * current token valid keep it; a session Cursor ended, or one that expired
+ * and could not be renewed, raises `CursorAuthError`.
+ */
+export async function renewSessionIfDue(tokens, options = {}) {
+    const baseUrl = options.baseUrl ?? API_BASE;
+    const base = latestSessionTokens(tokens);
+    const fromMemory = base.accessToken !== tokens.accessToken;
+    if (!options.force && !isSessionRenewalDue(base.accessToken)) {
+        return { accessToken: base.accessToken, renewed: fromMemory };
+    }
+    const state = stateFor(sessionStates, `${baseUrl}\0${base.refreshToken}`);
+    if (!state.terminal && (options.force || state.retryAt === undefined || Date.now() >= state.retryAt)) {
+        state.inflight ??= (async () => {
+            const result = await refreshCursorSession(base.refreshToken, baseUrl);
+            if (result.ok) {
+                const { expiresAtMs } = tokenTimes(result.accessToken);
+                if (expiresAtMs === undefined) {
+                    recordTransientFailure(state, "session refresh returned a token without expiry");
+                }
+                else {
+                    rememberSuccessor(base.refreshToken, result.accessToken);
+                    recordSuccess(state);
+                    trace(`auth: session renewed exp=${isoTime(expiresAtMs)}`);
+                    return;
+                }
+            }
+            else if (result.kind === "transient") {
+                recordTransientFailure(state, result.message);
+            }
+            else {
+                state.terminal = new CursorAuthError(result.kind === "policy"
+                    ? `Cursor sign-in policy blocks this login (sign_in_policy_violation); ${SIGN_IN_AGAIN} with an allowed account`
+                    : `Cursor ended this login session; ${SIGN_IN_AGAIN}`, { code: result.kind === "policy" ? "sign_in_policy_violation" : "session_logout", statusCode: result.status });
+                trace(`auth: session renewal final failure kind=${result.kind}`);
+                return;
+            }
+            trace(`auth: session renewal failed (${state.lastFailure}) attempt=${state.failures} ` +
+                `retryAt=${isoTime(state.retryAt)} currentExp=${isoTime(tokenTimes(base.accessToken).expiresAtMs)}`);
+        })().finally(() => {
+            state.inflight = undefined;
+        });
+        await state.inflight;
+    }
+    const renewed = latestSessionTokens(base);
+    if (renewed.accessToken !== base.accessToken) {
+        return { accessToken: renewed.accessToken, renewed: true };
+    }
+    if (state.terminal)
+        throw state.terminal;
+    if (!isUsable(base.accessToken, Date.now())) {
+        throw new CursorAuthError(`Cursor login expired and could not be renewed (${sanitizeHostTerminalMessage(state.lastFailure ?? "no renewal attempt allowed yet")}); ${SIGN_IN_AGAIN}`, { code: "session_expired" });
+    }
+    return {
+        accessToken: base.accessToken,
+        renewed: fromMemory,
+        ...(state.retryAt !== undefined ? { retryAt: state.retryAt } : {}),
+    };
+}
+// ── API key ──
+const apiKeyStates = new Map();
+/**
+ * JWT for a raw `crsr_` API key: the cached or `seed` JWT while it is not
+ * within five minutes of expiry, otherwise a fresh exchange. Cached per API
+ * base URL and key. Never returns the raw key itself.
+ */
+export async function resolveApiKeyToken(apiKey, options = {}) {
+    if (!isExchangeableApiKey(apiKey)) {
+        throw new CursorAuthError("Cursor API key must start with crsr_");
+    }
+    const baseUrl = options.baseUrl ?? API_BASE;
+    const state = stateFor(apiKeyStates, `${baseUrl}\0${apiKey}`);
+    const seed = options.seed && !isExchangeableApiKey(options.seed) && tokenTimes(options.seed).expiresAtMs !== undefined
+        ? options.seed
+        : undefined;
+    if (seed)
+        state.token = state.token ? longerLived(state.token, seed) : seed;
+    const result = (token) => ({ accessToken: token, renewed: token !== seed });
+    if (state.token && !options.force && !isExpiringSoon(state.token, TOKEN_EXPIRY_THRESHOLD_S)) {
+        return result(state.token);
+    }
+    if (!state.terminal && (options.force || state.retryAt === undefined || Date.now() >= state.retryAt)) {
+        state.inflight ??= (async () => {
+            try {
+                const pair = await exchangeApiKey(apiKey, baseUrl);
+                state.token = state.token ? longerLived(state.token, pair.accessToken) : pair.accessToken;
+                recordSuccess(state);
+                trace(`auth: API key exchanged exp=${isoTime(tokenTimes(pair.accessToken).expiresAtMs)}`);
+            }
+            catch (error) {
+                const kind = error instanceof AuthExchangeError ? error.kind : "transient";
+                if (kind === "transient") {
+                    recordTransientFailure(state, errorMessage(error));
+                    trace(`auth: API key exchange failed (${state.lastFailure}) attempt=${state.failures} retryAt=${isoTime(state.retryAt)}`);
+                }
+                else {
+                    const status = error instanceof AuthExchangeError ? error.status : undefined;
+                    state.terminal = new CursorAuthError(kind === "policy"
+                        ? "Cursor sign-in policy blocks this API key (sign_in_policy_violation); use an allowed account"
+                        : `Cursor rejected the API key${status ? ` (HTTP ${status})` : ""}; create a new key and sign in with it`, { code: kind === "policy" ? "sign_in_policy_violation" : "api_key_rejected", ...(status ? { statusCode: status } : {}) });
+                    trace(`auth: API key exchange final failure kind=${kind} status=${status ?? "none"}`);
+                }
+            }
+        })().finally(() => {
+            state.inflight = undefined;
+        });
+        await state.inflight;
+    }
+    // A fresh exchange is always usable; an older token only until it expires.
+    if (state.token && isUsable(state.token, Date.now()))
+        return result(state.token);
+    if (state.terminal)
+        throw state.terminal;
+    throw new CursorServerError(`Cursor API key exchange failed (${sanitizeHostTerminalMessage(state.lastFailure ?? "waiting before the next attempt")}); it is retried automatically`, { transient: true, replaySafe: true });
+}
+/**
+ * Bearer token for a Cursor request. One credential source is used, in this
+ * order, and none of them falls back to another:
+ *
+ * 1. `getAccessToken` — the host resolves (and renews) the token per request.
+ * 2. `accessToken` — sent as-is.
+ * 3. `apiKey` — a raw `crsr_` key is exchanged and renewed; any other value is
+ *    a token a host forwarded through the generic API-key slot, sent as-is.
+ */
+export async function resolveBearerToken(input) {
+    let token;
+    if (input.getAccessToken) {
+        token = await input.getAccessToken(input.forceRefresh ? { forceRefresh: true } : undefined);
+    }
+    else if (input.accessToken) {
+        token = input.accessToken;
+    }
+    else if (input.apiKey) {
+        token = isExchangeableApiKey(input.apiKey)
+            ? (await resolveApiKeyToken(input.apiKey, { baseUrl: input.baseUrl, force: input.forceRefresh })).accessToken
+            : input.apiKey;
+    }
+    else {
+        throw new CursorAuthError("Cursor provider: no access token or API key provided");
+    }
+    if (!token)
+        throw new CursorAuthError(`Cursor provider: no access token available; ${SIGN_IN_AGAIN}`);
+    if (isExchangeableApiKey(token)) {
+        // A raw key is never a valid Bearer token; Cursor answers 401.
+        throw new CursorAuthError("Cursor provider: a raw crsr_ API key was supplied as an access token; pass it as apiKey");
+    }
+    return token;
+}
+/** Reset all renewal state (tests). */
+export function resetAuthRenewalState() {
+    sessionStates.clear();
+    sessionSuccessors.clear();
+    apiKeyStates.clear();
+}

package/dist/auth.d.ts

@@ -1,10 +1,15 @@
+/**
+ * How an API key exchange failed. A policy block (403
+ * `sign_in_policy_violation`, as Cursor CLI's `loginWithApiKey` reports it) and
+ * an authentication refusal (401/403) are final for that key; anything else —
+ * rate limit, timeout, server or network failure — is worth retrying later.
+ */
+export type AuthExchangeFailureKind = "policy" | "rejected" | "transient";
 export declare class AuthExchangeError extends Error {
     cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
-}
-export declare class AuthRefreshError extends Error {
-    cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly kind: AuthExchangeFailureKind;
+    readonly status?: number | undefined;
+    constructor(message: string, cause?: unknown | undefined, kind?: AuthExchangeFailureKind, status?: number | undefined);
 }
 export declare class AuthPollError extends Error {
     cause?: unknown | undefined;
@@ -17,6 +22,8 @@ export declare function isExpiringSoon(jwt: string, thresholdS?: number): boolea
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
 /** JWT `exp` claim as epoch milliseconds, or null if missing/malformed. */
 export declare function decodeJwtExpiryMs(jwt: string): number | null;
+/** A raw Cursor API key (as opposed to a JWT already exchanged from one). */
+export declare function isExchangeableApiKey(value: string): boolean;
 export declare function useAuthToken(token: string): {
     accessToken: string;
 };
@@ -24,27 +31,36 @@ export type TokenPair = {
     accessToken: string;
     refreshToken: string;
 };
+/**
+ * Exchange a raw `crsr_` API key for a short-lived JWT. This is also how an
+ * API-key login is renewed: Cursor CLI re-runs the exchange and never uses the
+ * returned refresh token (`auth-refresh.ts` → `loginWithApiKey`).
+ */
 export declare function exchangeApiKey(apiKey: string, baseUrl?: string): Promise<TokenPair>;
-export declare function refreshAccessToken(refreshToken: string, baseUrl?: string): Promise<TokenPair>;
-/** Clear the apiKey→JWT cache (tests). */
-export declare function clearBearerTokenCache(): void;
+export type SessionRefreshResult = {
+    ok: true;
+    accessToken: string;
+} | {
+    ok: false;
+    /**
+     * `logout`: Cursor ended the session. `policy`: a sign-in policy blocks
+     * it. Both are final for this token. `transient`: try again later.
+     */
+    kind: "logout" | "policy" | "transient";
+    status?: number;
+    message: string;
+};
 /**
- * Resolve a Bearer JWT for Cursor API calls. Prefer an already-exchanged
- * `accessToken`; otherwise exchange (and cache) from `apiKey`, refreshing
- * when the cached JWT is near expiry.
+ * Renew a browser-login session token, exactly as Cursor's IDE does
+ * (`_performAccessTokenRefresh`): `POST /oauth/token` with a refresh_token
+ * grant and the IDE's client id. The response carries no new refresh token;
+ * the IDE stores the new access token as both, and so must callers.
  *
- * `apiKey` is only ever a raw exchangeable secret when it has Cursor's
- * `crsr_` prefix. Callers that generically forward whatever credential value
- * they hold — e.g. a host's package-agnostic "aisdk:" SDK loader, which
- * doesn't distinguish our OAuth vs. API-key connection methods and may pass
- * an already-issued JWT through the `apiKey` field — hand us a token that's
- * already good to use as-is; POSTing it to the exchange endpoint 401s.
+ * A rejected token is not an HTTP error: Cursor answers 200 with
+ * `{"access_token":"","shouldLogout":true}`, so the body decides the outcome.
+ * Never throws; every failure is a classified result.
  */
-export declare function resolveBearerToken(input: {
-    accessToken?: string;
-    apiKey?: string;
-    baseUrl?: string;
-}): Promise<string>;
+export declare function refreshCursorSession(refreshToken: string, baseUrl?: string): Promise<SessionRefreshResult>;
 export type PkceParams = {
     verifier: string;
     challenge: string;