cursor-opencode-provider 0.2.3 → 0.2.4

package/README.md

@@ -17,8 +17,8 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **OpenCode integration** — registers a `cursor` provider with auth hooks and cached model list
 - **Authentication** — browser OAuth (PKCE), or API key from [cursor.com/settings](https://cursor.com/settings)
 - **Model discovery** — fetches available models from Cursor's API and caches them locally
-- **Streaming** — bidirectional Connect-RPC stream for agent runs
-- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including the Pi read/bash/edit/write/grep/find/ls request/result field range; mirrors finalized display-only todo/plan state into OpenCode; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
+- **Streaming** — bidirectional Connect-RPC Runs with stale-session rotation, health checks, semantic/read-idle deadlines, bounded replay-safe recovery, and activity-aware held tool continuations
+- **Tool calls** — maps Cursor exec-server messages to AI SDK / OpenCode tool-call parts, including native subagent/Task execution (Cursor's `generalPurpose` maps to OpenCode `general`; read-oriented `bugbot` reviews map to `explore`) and the Pi read/bash/edit/write/grep/find/ls request/result field range; enforces the exact current OpenCode agent catalog before emitting any tool call; mirrors finalized display-only todo/plan state into OpenCode; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
 - **Thinking / reasoning** — surfaces extended-thinking deltas where the model supports it
 
 ## Requirements
@@ -47,7 +47,7 @@ Add the package name to OpenCode config. OpenCode installs npm plugins with Bun
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.2.1"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.4"`.
 
 ### From a local clone
 
@@ -124,7 +124,7 @@ opencode run --model cursor/composer-2.5 "Hello from Cursor via OpenCode"
 
 Cursor models often expose parameterized variants (effort, thinking, fast, context tier, …). The plugin materializes those as OpenCode **model variants**. In the TUI, pick one from the variant dialog or cycle with OpenCode’s `variant_cycle` keybind (default `ctrl+t`).
 
-The selected variant’s Cursor parameter map is forwarded on the Run as `requested_model.parameters` (isolated under `providerOptions.cursor.cursorVariantParameters` so unrelated OpenCode options are not leaked onto the wire).
+The selected variant’s Cursor parameter map is forwarded on the Run as `requested_model.parameters` (isolated under `providerOptions.cursor.cursorVariantParameters` so unrelated OpenCode options are not leaked onto the wire). The provider validates that explicit selection against the current cached tuple; malformed, reordered, or stale selections fail clearly instead of silently falling back to another variant.
 
 #### 1M / long context
 
@@ -157,13 +157,15 @@ const cursor = createCursor({
   // apiBaseURL: "https://api2.cursor.sh",
   // agentBaseURL: "https://agentn.us.api5.cursor.sh", // explicit Run host override
   // telemetryEnabled: true, // opt in to GetServerConfig telemetry
+  // retry: { maxAttempts: 3, baseDelayMs: 500, maxDelayMs: 8_000 },
+  // continuation: { heartbeatMs: 5_000, semanticIdleMs: 120_000, hardCapMs: 600_000 },
 })
 
 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 `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `headers`, `telemetryEnabled`. The older `baseURL` option is still accepted as a legacy alias for `agentBaseURL`.
+Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-...` key). Optional: `apiBaseURL`, `agentBaseURL`, `headers`, `telemetryEnabled`, `retry`, and `continuation`. Retries occur only before visible output or stateful server activity; unsafe replay is surfaced instead of risking duplicate text or tool work. 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
 
@@ -177,7 +179,7 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `XDG_CACHE_HOME` | When set, model/version caches go under `$XDG_CACHE_HOME/opencode/` instead of `~/.cache/opencode/` |
 | `XDG_DATA_HOME` | When set, OpenCode `auth.json` is read from `$XDG_DATA_HOME/opencode/` instead of `~/.local/share/opencode/` |
 
-`createCursor({ agentBaseURL })` overrides the agent Run host. When unset, the provider resolves the host from Cursor's `GetServerConfig` API (`agentUrlConfig.agentnUrl`, region-specific — e.g. `agentn.us.api5.cursor.sh`, `agent-gcpp-uswest.api5.cursor.sh`) once per process and holds it in memory (never written to disk), so a held-open Run stream is never repointed mid-session. Explicit agent overrides and GetServerConfig results are validated as HTTPS `*.cursor.sh` hosts (Cursor's agent hostnames vary and may change); non-`cursor.sh` hosts are rejected. The lookup sends `{ "telem_enabled": false }` by default; set `telemetryEnabled: true` in provider config, or `CURSOR_GET_SERVER_CONFIG_TELEMETRY=1` for OpenCode/plugin usage, to opt in. If the lookup fails or does not return a valid Cursor agent host, the model call fails clearly instead of falling back to `agentn.global.api5.cursor.sh`.
+`createCursor({ agentBaseURL })` overrides the agent Run host. When unset, the provider resolves the host from Cursor's `GetServerConfig` API (`agentUrlConfig.agentnUrl`, region-specific — e.g. `agentn.us.api5.cursor.sh`, `agent-gcpp-uswest.api5.cursor.sh`) once per process and holds it in memory (never written to disk), so a held-open Run stream is never repointed mid-session. Explicit agent overrides and GetServerConfig results are validated as HTTPS `*.cursor.sh` hosts (Cursor's agent hostnames vary and may change); non-`cursor.sh` hosts are rejected. Shared HTTP/2 connections are rotated before they become server-aged, while existing Runs may finish on their original connection. The lookup sends `{ "telem_enabled": false }` by default; set `telemetryEnabled: true` in provider config, or `CURSOR_GET_SERVER_CONFIG_TELEMETRY=1` for OpenCode/plugin usage, to opt in. If the lookup fails or does not return a valid Cursor agent host, the model call fails clearly instead of falling back to `agentn.global.api5.cursor.sh`.
 
 ## Development
 
@@ -186,6 +188,7 @@ bun install          # install dependencies
 bun run build        # compile TypeScript → dist/
 bun run typecheck    # type-check without emit
 bun test             # run unit tests
+bun run test:node-http2 # Node-specific HTTP/2 detach regression
 bun run test:watch   # watch mode
 ```
 
@@ -214,6 +217,12 @@ OpenCode
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
 | `src/protocol/` | Protobuf encode/decode, checksum/device ids, exec + display tool-call mapping (`tool-call-bridge.ts`) |
 
+### Injected system guidance
+
+The provider adds OpenCode-specific system guidance to normal tool-capable conversations, including tool availability and canonical workspace-path grounding. Compaction keeps its dedicated prompt unchanged.
+
+If this guidance causes issues, update `buildOpenCodeInteractionGuidance` in [`src/language-model.ts`](src/language-model.ts) and its focused coverage in [`test/prompt-history.test.ts`](test/prompt-history.test.ts).
+
 ## Package exports
 
 | Import path | Export |
@@ -221,8 +230,9 @@ OpenCode
 | `cursor-opencode-provider` | `createCursor`, `CursorPlugin` (named + default) |
 | `cursor-opencode-provider/plugin` | `CursorPlugin` (classic Hooks — auth) |
 | `cursor-opencode-provider/plugin/v2` | OpenCode Effect/Promise v2 plugin (`ctx.aisdk.*`) |
+| `cursor-opencode-provider/errors` | Structured provider error classes |
 
-`CursorPluginV2` is **not** re-exported from the package root — the classic plugin loader would treat it as a broken Hooks export. Always load it via `./plugin/v2`.
+The package root intentionally stays plugin-safe for OpenCode's classic loader. `CursorPluginV2` and non-plugin runtime APIs are **not** re-exported from the package root; load them through their dedicated subpaths.
 
 ## Troubleshooting
 
@@ -232,19 +242,24 @@ OpenCode
 | 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. |
 | “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 `~/.cache/opencode/cursor-models.json` (or under `$XDG_CACHE_HOME/opencode/`) and restart OpenCode. 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. |
-| Stream hangs or HTTP/2 errors | Abort the turn and retry. The agent Run uses a bidirectional HTTP/2 stream; a dropped connection leaves the in-flight session unusable. With debug logging enabled, `interaction_query: replied` means a Cursor UI/approval request was answered; a later heartbeat-only stall without that line usually means OpenCode is running an older build and should be restarted after `bun run build`. |
-| No response / silent 200 + close | The provider resolves the Run host from `GetServerConfig` (`agentUrlConfig.agentnUrl`). The URL is resolved once per process and not cached on disk. If resolution fails, the model call reports the endpoint-resolution error instead of falling back to `agentn.global.api5.cursor.sh`, which some accounts reject silently ("This region is not yet available for your team"). Set `CURSOR_PROVIDER_DEBUG=1` to confirm the resolved host in the debug log. |
+| Stream hangs or HTTP/2 errors | The provider keeps Cursor's Run open across OpenCode tool calls, rotates aged shared connections, and transparently rebases once from full OpenCode history if the Run ends before `turn_ended`. Repeated interruption is surfaced as an error instead of a false successful stop; retry the turn after checking connectivity. With debug logging enabled, look for `Run interrupted` and `rebasing fresh Run`. Restart OpenCode after rebuilding a local `file://` install. |
+| No response / silent 200 + close | HTTP 200 alone is not a successful agent turn: the provider now requires Cursor's explicit `turn_ended`, captures HTTP/2 trailers/GOAWAY, and recovers once from bare EOF. The Run host still comes from in-memory `GetServerConfig` resolution; set `CURSOR_PROVIDER_DEBUG=1` to confirm the host and termination reason. |
+| Visible `<shell_metadata>` timeout text | Rebuild and restart a local install. Cursor's shell timeout is carried on its exec request; the provider now removes OpenCode's internal timeout envelope before it is rendered or stored, then returns Cursor's typed timeout or background-handoff event instead of treating the text as successful stdout. |
+| `Unsupported Cursor exec variant …` | The error names the canonical Cursor CLI request field, its expected result field, and this provider's handling classification. `handling=unsupported` is a known Cursor-native capability without a safe OpenCode AI SDK bridge; `unknown request field` indicates new protocol drift; `handling=opencode-tool` or `provider-control` indicates a provider decoder/dispatch regression. Enable the debug log and report the full named error. |
 | Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`, default `/tmp/cursor-provider-debug.log`) and reproduce the issue. |
 
 ## Known limitations
 
 - **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.
-- **`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). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted.
-- **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, and exec still reconstructs the full OpenCode tool id.
-- **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` / `create_plan_tool_call`) into advertised OpenCode `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 Pi read/bash/edit/write/grep/find/ls calls use their typed request/result fields instead. Unknown display variants are logged; unknown exec variants fail the turn explicitly rather than receiving a guessed response that could deadlock the Run.
+- **`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). 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. 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`; exec still reconstructs the full OpenCode tool id.
+- **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` / `create_plan_tool_call`) into advertised OpenCode `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 and future unknown exec variants fail explicitly rather than receiving a guessed response that could deadlock the Run.
+- **Tool availability is per OpenCode agent** — Cursor can request native capabilities such as Task even when a child or restricted OpenCode agent did not advertise the corresponding host tool. The provider prompts Cursor with the exact current catalog and checks every decoded host-tool exec request against it. An unavailable request is answered on Cursor's correlated typed result channel and is never emitted as OpenCode's `invalid` tool.
+- **Background shells are non-interactive** — Cursor's native background-shell spawn is bridged through OpenCode's foreground-only `bash` tool by detaching the requested command, redirecting its output to `${TMPDIR:-/tmp}/cursor-opencode-bg.*`, and returning the real PID in Cursor's typed field-16 result. Shell-stream requests also preserve Cursor's foreground timeout, `timeout_behavior`, and `hard_timeout`: cancellation becomes a typed aborted exit, while a soft timeout requested with background behavior becomes a typed background handoff. OpenCode's internal `<shell_metadata>` envelope and the bridge's private markers are stripped before the result reaches the UI. Requests that require `write_shell_stdin` are rejected explicitly because OpenCode does not expose an interactive background-process lifecycle through its AI SDK tool interface.
 - **Cursor-native interaction queries remain headless** — Cursor UI/approval *queries* (as distinct from display tool calls) still cannot be surfaced through the AI SDK provider interface. The normal system prompt redirects questions, planning, plan-mode transitions, and known-URL fetching to equivalent OpenCode tools only when they are advertised (`question`, `todowrite`, `plan_enter` / `plan_exit`, `webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind OpenCode's tools and permissions. Compaction prompts are unchanged. Unknown future interaction variants fail the turn explicitly instead of hanging the Run stream.
 - **Compaction resets Cursor conversation state** — 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-result text 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. Ordinary no-tool / `toolChoice:none` calls do not reset conversation state.
 - **Conversation bindings and compaction catalogs are bounded** — process-global per-session bindings, prior tool catalogs, and pending post-compaction rebases use a 256-session LRU bound. Evicting a conversation binding also drops its checkpoint and KV blobs.
+- **Interrupted Runs rebase once** — a remote EOF, Connect end-stream, trailer error, failed continuation write, or closed pending-tool session is never emitted as a successful `stop`. The provider starts one fresh Cursor conversation seeded from the complete OpenCode prompt (including trailing tool results and the live user request), re-advertises the same tools, and preserves compaction's no-execution behavior. A second interruption is returned as an explicit error. Recovery cannot see tokens already streamed to the UI on the interrupted attempt, so mid-generation recovery may briefly duplicate visible text/reasoning even though the rebase prompt asks the model not to repeat completed work.
 - **No fallback models** — if Cursor’s `AvailableModels` API is unreachable and there is no local cache, the provider exposes no models.
 
 ## License

package/dist/activity.d.ts

@@ -0,0 +1,15 @@
+export type SessionActivitySource = {
+    lastActivityAt(sessionId: string): number | undefined;
+};
+/** Tracks OpenCode message progress and propagates it through subagent ancestry. */
+export declare class SessionActivityTracker implements SessionActivitySource {
+    private readonly parentBySession;
+    private readonly lastActivityBySession;
+    linkSession(sessionId: string, parentId?: string): void;
+    recordActivity(sessionId: string, at?: number): void;
+    lastActivityAt(sessionId: string): number | undefined;
+    removeSession(sessionId: string): void;
+    clear(): void;
+    private prune;
+}
+export declare const sessionActivity: SessionActivityTracker;

package/dist/activity.js

@@ -0,0 +1,76 @@
+const MAX_ANCESTRY_DEPTH = 64;
+const MAX_TRACKED_SESSIONS = 1_024;
+const ACTIVITY_RETENTION_MS = 24 * 60 * 60 * 1_000;
+/** Tracks OpenCode message progress and propagates it through subagent ancestry. */
+export class SessionActivityTracker {
+    parentBySession = new Map();
+    lastActivityBySession = new Map();
+    linkSession(sessionId, parentId) {
+        if (!sessionId)
+            return;
+        this.prune(Date.now());
+        if (parentId && parentId !== sessionId)
+            this.parentBySession.set(sessionId, parentId);
+        else
+            this.parentBySession.delete(sessionId);
+        const existing = this.lastActivityBySession.get(sessionId);
+        if (existing !== undefined)
+            this.recordActivity(sessionId, existing);
+        this.prune(Date.now());
+    }
+    recordActivity(sessionId, at = Date.now()) {
+        if (!sessionId || !Number.isFinite(at))
+            return;
+        this.prune(at);
+        const visited = new Set();
+        let current = sessionId;
+        for (let depth = 0; current && depth < MAX_ANCESTRY_DEPTH; depth++) {
+            if (visited.has(current))
+                return;
+            visited.add(current);
+            const previous = this.lastActivityBySession.get(current);
+            if (previous === undefined || at > previous) {
+                // Map insertion order is our least-recently-active eviction order.
+                this.lastActivityBySession.delete(current);
+                this.lastActivityBySession.set(current, at);
+            }
+            current = this.parentBySession.get(current);
+        }
+        this.prune(at);
+    }
+    lastActivityAt(sessionId) {
+        this.prune(Date.now());
+        return this.lastActivityBySession.get(sessionId);
+    }
+    removeSession(sessionId) {
+        this.parentBySession.delete(sessionId);
+        this.lastActivityBySession.delete(sessionId);
+    }
+    clear() {
+        this.parentBySession.clear();
+        this.lastActivityBySession.clear();
+    }
+    prune(now) {
+        const oldestAllowed = now - ACTIVITY_RETENTION_MS;
+        for (const [sessionId, activityAt] of this.lastActivityBySession) {
+            if (activityAt >= oldestAllowed)
+                break;
+            this.lastActivityBySession.delete(sessionId);
+            this.parentBySession.delete(sessionId);
+        }
+        while (this.lastActivityBySession.size > MAX_TRACKED_SESSIONS) {
+            const oldest = this.lastActivityBySession.keys().next().value;
+            if (!oldest)
+                break;
+            this.lastActivityBySession.delete(oldest);
+            this.parentBySession.delete(oldest);
+        }
+        while (this.parentBySession.size > MAX_TRACKED_SESSIONS) {
+            const oldest = this.parentBySession.keys().next().value;
+            if (!oldest)
+                break;
+            this.parentBySession.delete(oldest);
+        }
+    }
+}
+export const sessionActivity = new SessionActivityTracker();

package/dist/context/build.js

@@ -27,11 +27,6 @@ export async function buildRequestContext(input) {
     const mcpServerNames = Object.keys(config.mcp ?? {});
     const flat = toolsToDescriptors(tools, providerIdentifier, mcpServerNames);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, mcpServerNames);
-    const permission = config.permission;
-    const autoRun = permission === "allow" ||
-        (typeof permission === "object" &&
-            permission !== null &&
-            permission["*"] === "allow");
     const ctx = {
         env: buildEnv(workspaceRoot),
         tools: flat,
@@ -72,8 +67,6 @@ export async function buildRequestContext(input) {
         custom_subagents_info_complete: true,
         mcp_file_system_info_complete: true,
         mcp_info_complete: true,
-        user_permissions_auto_run: autoRun,
-        project_permissions_auto_run: autoRun,
     };
     if (plugins.length > 0) {
         ctx.hooks_additional_context = plugins

package/dist/errors.d.ts

@@ -0,0 +1,59 @@
+export type CursorErrorOrigin = "local-cancel" | "transport" | "server" | "protocol" | "auth";
+export type CursorErrorDiagnostics = {
+    statusCode?: number;
+    grpcStatus?: number | string;
+    rstCode?: number;
+    code?: string;
+    retryAfterMs?: number;
+};
+export type CursorProviderErrorOptions = CursorErrorDiagnostics & {
+    origin: CursorErrorOrigin;
+    transient: boolean;
+    replaySafe: boolean;
+    cause?: unknown;
+};
+/** Structured provider failure with retry and transport diagnostics. */
+export declare class CursorProviderError extends Error {
+    readonly origin: CursorErrorOrigin;
+    readonly transient: boolean;
+    replaySafe: boolean;
+    readonly statusCode?: number;
+    readonly grpcStatus?: number | string;
+    readonly rstCode?: number;
+    readonly code?: string;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options: CursorProviderErrorOptions);
+}
+export declare class CursorLocalCancellationError extends CursorProviderError {
+    constructor(message?: string, cause?: unknown);
+}
+export declare class CursorTransportError extends CursorProviderError {
+    constructor(message: string, options?: Omit<CursorProviderErrorOptions, "origin">);
+}
+export declare class CursorServerError extends CursorProviderError {
+    constructor(message: string, options: Omit<CursorProviderErrorOptions, "origin">);
+}
+export declare class CursorProtocolError extends CursorProviderError {
+    constructor(message: string, options?: Partial<CursorErrorDiagnostics> & {
+        cause?: unknown;
+    });
+}
+export declare class CursorAuthError extends CursorProviderError {
+    constructor(message?: string, options?: Partial<CursorErrorDiagnostics> & {
+        cause?: unknown;
+    });
+}
+export declare class CursorRetryExhaustedError extends CursorProviderError {
+    readonly attempts: number;
+    constructor(attempts: number, last: CursorProviderError);
+}
+export declare function isTransientGrpcStatus(status: number | string): boolean;
+export declare function isAuthGrpcStatus(status: number | string): boolean;
+export declare function cursorHttpError(operation: string, statusCode: number, diagnostics?: Omit<CursorErrorDiagnostics, "statusCode">): CursorProviderError;
+export declare function cursorGrpcError(operation: string, grpcStatus: number | string, diagnostics?: Omit<CursorErrorDiagnostics, "grpcStatus">): CursorProviderError;
+export declare function errorCode(error: unknown): string | undefined;
+export declare function toCursorProviderError(error: unknown, options?: {
+    replaySafe: boolean;
+    fallback?: string;
+}): CursorProviderError;
+export declare function retrySuppressedError(cause: CursorProviderError, reason: string, attempt: number, maxAttempts: number): CursorProviderError;

package/dist/errors.js

@@ -0,0 +1,199 @@
+/** Structured provider failure with retry and transport diagnostics. */
+export class CursorProviderError extends Error {
+    origin;
+    transient;
+    replaySafe;
+    statusCode;
+    grpcStatus;
+    rstCode;
+    code;
+    retryAfterMs;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "CursorProviderError";
+        this.origin = options.origin;
+        this.transient = options.transient;
+        this.replaySafe = options.replaySafe;
+        this.statusCode = options.statusCode;
+        this.grpcStatus = options.grpcStatus;
+        this.rstCode = options.rstCode;
+        this.code = options.code;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+}
+export class CursorLocalCancellationError extends CursorProviderError {
+    constructor(message = "Cursor request cancelled locally", cause) {
+        super(message, {
+            origin: "local-cancel",
+            transient: false,
+            replaySafe: false,
+            cause,
+        });
+        this.name = "CursorLocalCancellationError";
+    }
+}
+export class CursorTransportError extends CursorProviderError {
+    constructor(message, options = {
+        transient: true,
+        replaySafe: true,
+    }) {
+        super(message, { ...options, origin: "transport" });
+        this.name = "CursorTransportError";
+    }
+}
+export class CursorServerError extends CursorProviderError {
+    constructor(message, options) {
+        super(message, { ...options, origin: "server" });
+        this.name = "CursorServerError";
+    }
+}
+export class CursorProtocolError extends CursorProviderError {
+    constructor(message, options = {}) {
+        super(message, {
+            ...options,
+            origin: "protocol",
+            transient: false,
+            replaySafe: false,
+        });
+        this.name = "CursorProtocolError";
+    }
+}
+export class CursorAuthError extends CursorProviderError {
+    constructor(message = "Cursor authentication failed; reauthenticate with Cursor", options = {}) {
+        super(message, {
+            ...options,
+            origin: "auth",
+            transient: false,
+            replaySafe: false,
+        });
+        this.name = "CursorAuthError";
+    }
+}
+export class CursorRetryExhaustedError extends CursorProviderError {
+    attempts;
+    constructor(attempts, last) {
+        super(`Cursor retry exhausted after ${attempts} attempts: ${last.message}`, {
+            origin: last.origin,
+            transient: false,
+            replaySafe: false,
+            statusCode: last.statusCode,
+            grpcStatus: last.grpcStatus,
+            rstCode: last.rstCode,
+            code: last.code,
+            retryAfterMs: last.retryAfterMs,
+            cause: last,
+        });
+        this.name = "CursorRetryExhaustedError";
+        this.attempts = attempts;
+    }
+}
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNABORTED",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETDOWN",
+    "ENETRESET",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+    "ERR_HTTP2_GOAWAY_SESSION",
+    "ERR_HTTP2_SESSION_ERROR",
+    "ERR_HTTP2_STREAM_CANCEL",
+    "ERR_HTTP2_STREAM_ERROR",
+    "ETIMEDOUT",
+]);
+export function isTransientGrpcStatus(status) {
+    const normalized = String(status).toLowerCase().replaceAll("-", "_");
+    return (normalized === "8" ||
+        normalized === "13" ||
+        normalized === "14" ||
+        normalized === "internal" ||
+        normalized === "resource_exhausted" ||
+        normalized === "unavailable");
+}
+export function isAuthGrpcStatus(status) {
+    const normalized = String(status).toLowerCase().replaceAll("-", "_");
+    return (normalized === "7" ||
+        normalized === "16" ||
+        normalized === "permission_denied" ||
+        normalized === "unauthenticated");
+}
+export function cursorHttpError(operation, statusCode, diagnostics = {}) {
+    if (statusCode === 401 || statusCode === 403) {
+        return new CursorAuthError(`Cursor authentication failed (HTTP ${statusCode}); reauthenticate with Cursor`, { ...diagnostics, statusCode });
+    }
+    return new CursorServerError(`${operation} HTTP ${statusCode}`, {
+        ...diagnostics,
+        statusCode,
+        transient: statusCode === 429 || statusCode >= 500,
+        replaySafe: true,
+    });
+}
+export function cursorGrpcError(operation, grpcStatus, diagnostics = {}) {
+    if (isAuthGrpcStatus(grpcStatus)) {
+        return new CursorAuthError(`Cursor authentication failed (gRPC ${grpcStatus}); reauthenticate with Cursor`, { ...diagnostics, grpcStatus });
+    }
+    return new CursorServerError(`${operation} gRPC status ${grpcStatus}`, {
+        ...diagnostics,
+        grpcStatus,
+        transient: isTransientGrpcStatus(grpcStatus),
+        replaySafe: true,
+    });
+}
+export function errorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+export function toCursorProviderError(error, options = { replaySafe: false }) {
+    if (error instanceof CursorProviderError) {
+        error.replaySafe = options.replaySafe && error.replaySafe;
+        return error;
+    }
+    const code = errorCode(error);
+    const name = error instanceof Error ? error.name : "Error";
+    const message = error instanceof Error ? error.message : "";
+    if (name.startsWith("Auth") || /access token|api key|authentication/i.test(message)) {
+        return new CursorAuthError(undefined, { code, cause: error });
+    }
+    const httpStatus = /\bHTTP\s+(\d{3})\b/i.exec(message)?.[1];
+    if (httpStatus) {
+        const failure = cursorHttpError("Cursor request failed with", Number(httpStatus), { code });
+        failure.replaySafe = options.replaySafe && failure.replaySafe;
+        return failure;
+    }
+    if (code && TRANSIENT_NETWORK_CODES.has(code)) {
+        return new CursorTransportError(`Cursor transport failure (${code})`, {
+            transient: true,
+            replaySafe: options.replaySafe,
+            code,
+            cause: error,
+        });
+    }
+    if (error instanceof TypeError) {
+        return new CursorProtocolError(options.fallback ?? "Invalid Cursor provider configuration", {
+            code,
+            cause: error,
+        });
+    }
+    return new CursorProtocolError(options.fallback ?? `Cursor provider failure (${name})`, {
+        code,
+        cause: error,
+    });
+}
+export function retrySuppressedError(cause, reason, attempt, maxAttempts) {
+    const subject = cause.message.replace(/^Cursor Run stream /, "Cursor stream ");
+    return new CursorProviderError(`${subject} ${reason}; automatic retry unsafe (attempt ${attempt}/${maxAttempts})`, {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        statusCode: cause.statusCode,
+        grpcStatus: cause.grpcStatus,
+        rstCode: cause.rstCode,
+        code: cause.code,
+        retryAfterMs: cause.retryAfterMs,
+        cause,
+    });
+}

package/dist/index.d.ts

@@ -1,4 +1,13 @@
 import { CursorPlugin } from "./plugin.js";
+import type { CursorContinuationOptions } from "./session.js";
+export type CursorRetryOptions = {
+    /** Total attempts including the initial request. Default: 3. */
+    maxAttempts?: number;
+    /** Initial full-jitter backoff ceiling. Default: 500ms. */
+    baseDelayMs?: number;
+    /** Exponential backoff ceiling. Default: 8000ms. */
+    maxDelayMs?: number;
+};
 export type CreateCursorOptions = {
     name: string;
     accessToken?: string;
@@ -14,9 +23,14 @@ export type CreateCursorOptions = {
     telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: string;
+    /** Held-stream policy. Defaults: heartbeat 5s, semantic idle 120s, tool inactivity 10m. */
+    continuation?: CursorContinuationOptions;
+    /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */
+    retry?: CursorRetryOptions;
 };
 export declare function createCursor(options: CreateCursorOptions): {
     languageModel(modelId: string): import("@ai-sdk/provider").LanguageModelV3;
 };
 export { CursorPlugin };
+export type { CursorContinuationOptions, CursorContinuationPolicy } from "./session.js";
 export default CursorPlugin;

package/dist/index.js

@@ -11,6 +11,10 @@ export function createCursor(options) {
 }
 export { CursorPlugin };
 export default CursorPlugin;
+// Keep root runtime exports plugin-safe. OpenCode's legacy plugin loader
+// treats package-root exports as potential plugins, so extra public runtime
+// APIs belong on subpaths such as "cursor-opencode-provider/errors".
+//
 // CursorPluginV2 is NOT re-exported here — see plugin-v2.ts.
 // OpenCode's legacy plugin loader (getLegacyPlugins) iterates all exports
 // and calls getServerPlugin on each; the v2 define() return is not a

package/dist/language-model.d.ts

@@ -1,11 +1,29 @@
 import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
-import type { CreateCursorOptions } from "./index.js";
+import type { CreateCursorOptions, CursorRetryOptions } from "./index.js";
 import { type OpencodeToolDef } from "./protocol/tools.js";
 import { type CursorSession } from "./session.js";
+import { CursorProviderError } from "./errors.js";
 import type { SeedHistoryMessage } from "./protocol/request.js";
 export declare const MAX_TURN_STATE_SESSIONS = 256;
+export type CursorRetryPolicy = {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export declare function resolveRetryPolicy(options: CursorRetryOptions | undefined): CursorRetryPolicy;
+export declare function connectFrameError(payload: string): CursorProviderError;
 type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
+export declare function pumpWithRecovery(input: {
+    initialSession: CursorSession;
+    controller: ReadableStreamDefaultController<V3Part>;
+    abortSignal?: AbortSignal;
+    promptTokens?: number;
+    retryPolicy?: CursorRetryPolicy;
+    recover: () => Promise<CursorSession>;
+    onSession?: (session: CursorSession) => void;
+    maxRecoveries?: number;
+}): Promise<CursorSession>;
 /**
  * OpenCode re-sends the full tool-result history on every continuation. Prefer
  * the newest result that still has a live pending exec on its tagged session.
@@ -14,17 +32,27 @@ export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
 }>): CursorSession | undefined;
+/**
+ * Deliver trailing tool results onto a live continuation session.
+ * Returns the same session when writes succeed (or only bridged results were
+ * cleared). Returns undefined after closing the session when a write fails, so
+ * the caller can rebase onto a fresh Run instead of pumping a dead stream.
+ */
+export declare function deliverContinuationResults(session: CursorSession, trailingToolResults: ExtractedToolResult[]): CursorSession | undefined;
 /**
  * Read the held-open stream, emitting stream parts, until the turn boundary:
  *  - a tool call (exec_server_message) → emit tool-call, finish "tool-calls",
  *    and KEEP the session open for the result on the next doStream call;
- *  - turn_ended / stream end → finish "stop" and close the session.
+ *  - turn_ended → finish "stop" and close the session;
+ *  - transport EOF before turn_ended → throw for one fresh-Run recovery.
  */
 export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
     textId: string;
     reasoningId: string;
+    promptTokens?: number;
 }, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
+    toolCallId: string;
     sessionId: string;
     execId: number;
     toolName: string;
@@ -42,15 +70,30 @@ export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOp
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
  * compaction keeps its dedicated summary prompt unchanged.
  */
-export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean): string | undefined;
+export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[], isCompaction: boolean, workspaceRoot: string): string | undefined;
 /** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
 export declare function estimateTokens(chars: number): number;
+/** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
+export declare function estimatePromptTokens(prompt: LanguageModelV3CallOptions["prompt"]): number;
+/** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
+    cursor: {
+        usageVersion: number;
+        inputTokensRaw: number;
+        outputTokensRaw: number;
+        cacheReadRaw: number;
+        cacheWriteRaw: number;
+        reasoningTokensRaw: number;
+    };
+};
 /**
  * Prior prompt turns for a seed ConversationStateStructure after compaction
  * reset. Drops the trailing user message (live action), but preserves tool
  * result payloads as labeled assistant observations for Cursor's text history.
  */
-export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"]): SeedHistoryMessage[];
+export declare function extractPromptHistory(prompt: LanguageModelV3CallOptions["prompt"], options?: {
+    preserveTrailingUser?: boolean;
+}): SeedHistoryMessage[];
 /** OpenCode session id header, if present. */
 export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptions): string | undefined;
 /**