cursor-opencode-provider 0.2.3 → 0.2.5

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.5"`.
 
 ### 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
 
@@ -173,11 +175,11 @@ Pass either `accessToken` (JWT from OAuth or key exchange) or `apiKey` (raw `sk-
 | `CURSOR_API_BASE_URL` | Override API base for auth, model discovery, and `GetServerConfig` agent URL resolution (default `https://api2.cursor.sh`) |
 | `CURSOR_GET_SERVER_CONFIG_TELEMETRY` | Set to `1` or `true` to opt the `GetServerConfig` lookup into telemetry in OpenCode/plugin usage |
 | `CURSOR_PROVIDER_DEBUG` | Set to `1` or `true` to enable wire-level debug logging |
-| `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default `/tmp/cursor-provider-debug.log`) |
+| `CURSOR_PROVIDER_DEBUG_FILE` | Debug log path (default: `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) |
 | `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, canonical workspace-path grounding, and preferring `edit` / `write` over shell-based file mutation when those tools are available. 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,21 +242,30 @@ 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. |
-| Need wire-level logs | Set `CURSOR_PROVIDER_DEBUG=1` (optional `CURSOR_PROVIDER_DEBUG_FILE`, default `/tmp/cursor-provider-debug.log`) and reproduce the issue. |
+| 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`; the default is `debug-<pid>.log` under `$TMPDIR/cursor-provider-logs-<uid>/`) and reproduce the issue. |
+
+## Security
+
+Project `instructions` may reference absolute or `~/` paths (OpenCode parity). See [SECURITY.md](./SECURITY.md) for the trust model and `OPENCODE_DISABLE_PROJECT_CONFIG`.
 
 ## 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.
-- **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.
+- **`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. Separately from display `create_plan_tool_call` → `todowrite` mirroring, interaction `create_plan_request_query` is auto-acked (CLI headless parity) with success and an empty `plan_uri`, so Cursor may treat the plan as accepted without an OpenCode UI confirm. 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 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. 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 OpenCode prompt, retaining the live user request and trailing tool results as host observations without replaying stale historical tool output, 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
 
-MIT
+MIT

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security notes
+
+This provider mirrors OpenCode’s trust model for project configuration. That has implications for what ends up in Cursor context.
+
+## Project `instructions` can include arbitrary local paths
+
+OpenCode’s `opencode.json` / `opencode.jsonc` `instructions` array may list:
+
+- relative paths / globs (e.g. `.cursor/rules/*.md`)
+- absolute paths
+- home-relative paths (`~/…`)
+- remote URLs (`https://…`; this provider fetches HTTPS only)
+
+OpenCode itself expands `~/`, accepts absolute paths, and injects those file contents into the model prompt for **every** provider. This package does the same discovery when building Cursor `RequestContext.rules`.
+
+So a project config like:
+
+```json
+{
+  "instructions": ["~/.ssh/id_rsa", "/etc/passwd"]
+}
+```
+
+can cause those files to be read and sent to the model provider (OpenCode prompt path and/or this provider’s Cursor `RequestContext`). That is intentional OpenCode parity, not a Cursor-only hole. There is no path allowlist that rejects absolute/`~/` instruction paths (matching OpenCode; OpenCode has not treated this as a defect).
+
+Treat project `opencode.json` as **trusted**. Do not open untrusted repositories with project config enabled if that is unacceptable.
+
+## Mitigation: disable project config
+
+To ignore project-level OpenCode config (including project `instructions` and project `AGENTS.md` / `CLAUDE.md` / `CONTEXT.md` discovery), set:
+
+```bash
+export OPENCODE_DISABLE_PROJECT_CONFIG=1
+```
+
+OpenCode honors this flag when loading config and assembling prompts. This provider honors the same flag when collecting rules for Cursor `RequestContext`, so project `instructions` are not merged and project instruction files are not auto-discovered. Global config under `~/.config/opencode` (and `~/.claude/CLAUDE.md` when applicable) still applies.
+
+Truthy values: `1` or `true` (case-insensitive), same as OpenCode.
+
+## Related hardening in this provider
+
+- Remote `instructions` URLs are **HTTPS-only** (`http://` is skipped). Redirects (including to a local proxy) are intentional and not blocked.

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/auth.d.ts

@@ -15,6 +15,8 @@ export declare class AuthTimeoutError extends Error {
 }
 export declare function isExpiringSoon(jwt: string, thresholdS?: number): boolean;
 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;
 export declare function useAuthToken(token: string): {
     accessToken: string;
 };
@@ -45,4 +47,3 @@ export declare function generatePkceParams(): PkceParams;
 export declare function generatePkceChallenge(verifier: string): Promise<string>;
 export declare function buildLoginUrl(challenge: string, uuid: string, websiteUrl?: string): string;
 export declare function pollForTokens(uuid: string, verifier: string, baseUrl?: string, signal?: AbortSignal, maxAttempts?: number): Promise<TokenPair>;
-export declare function loginWithBrowser(websiteUrl?: string, apiBaseUrl?: string, signal?: AbortSignal): Promise<TokenPair>;

package/dist/auth.js

@@ -32,22 +32,35 @@ export class AuthTimeoutError extends Error {
 }
 // ── Helpers ──
 export function isExpiringSoon(jwt, thresholdS = 300) {
-    try {
-        const payload = JSON.parse(atob(jwt.split(".")[1]));
-        return (payload.exp * 1000 - Date.now()) < thresholdS * 1000;
-    }
-    catch {
+    const payload = decodeJwtPayload(jwt);
+    if (!payload || typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
         return true;
     }
+    return payload.exp * 1000 - Date.now() < thresholdS * 1000;
 }
 export function decodeJwtPayload(jwt) {
     try {
-        return JSON.parse(atob(jwt.split(".")[1]));
+        const segment = jwt.split(".")[1];
+        if (!segment)
+            return null;
+        const json = Buffer.from(segment, "base64url").toString("utf8");
+        const payload = JSON.parse(json);
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            return null;
+        return payload;
     }
     catch {
         return null;
     }
 }
+/** JWT `exp` claim as epoch milliseconds, or null if missing/malformed. */
+export function decodeJwtExpiryMs(jwt) {
+    const payload = decodeJwtPayload(jwt);
+    if (!payload || typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+        return null;
+    }
+    return payload.exp * 1000;
+}
 function base64url(bytes) {
     return btoa(String.fromCharCode(...bytes))
         .replace(/\+/g, "-")
@@ -191,10 +204,3 @@ export async function pollForTokens(uuid, verifier, baseUrl = API_BASE, signal,
     }
     throw new AuthTimeoutError(`Poll timed out after ${maxAttempts} attempts (~5 min)`);
 }
-// ── Combined login (Mode C, one-shot) ──
-export async function loginWithBrowser(websiteUrl, apiBaseUrl, signal) {
-    const params = generatePkceParams();
-    const challenge = await generatePkceChallenge(params.verifier);
-    const loginUrl = buildLoginUrl(challenge, params.uuid, websiteUrl);
-    return await pollForTokens(params.uuid, params.verifier, apiBaseUrl, signal);
-}

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/context/rules.d.ts

@@ -9,6 +9,10 @@ export type OpencodeJson = {
     plugins?: string[];
     mcp?: Record<string, unknown>;
 };
+/** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
+export declare function isProjectConfigDisabled(): boolean;
+/** Fetch a remote instruction with one deadline covering headers and body. */
+export declare function fetchRemoteInstruction(url: string, timeoutMs?: number): Promise<string | undefined>;
 export declare function loadMergedConfig(workspaceRoot: string): Promise<OpencodeJson>;
 /**
  * Collect OpenCode instruction files.

package/dist/context/rules.js

@@ -129,8 +129,40 @@ async function expandGlob(pattern, workspaceRoot) {
     await walk(startDir, 0);
     return out;
 }
+/** Same truthy rule as OpenCode's Flag.OPENCODE_DISABLE_PROJECT_CONFIG. */
+export function isProjectConfigDisabled() {
+    const value = process.env.OPENCODE_DISABLE_PROJECT_CONFIG?.toLowerCase();
+    return value === "true" || value === "1";
+}
+/** Fetch a remote instruction with one deadline covering headers and body. */
+export async function fetchRemoteInstruction(url, timeoutMs = 5000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), Math.max(1, timeoutMs));
+    try {
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return undefined;
+        return await res.text();
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 export async function loadMergedConfig(workspaceRoot) {
     const globalConfig = await readJsonConfig(opencodeGlobalConfigDir());
+    if (isProjectConfigDisabled()) {
+        return {
+            ...globalConfig,
+            instructions: [...(globalConfig.instructions ?? [])],
+            plugin: [...(globalConfig.plugin ?? [])],
+            plugins: [...(globalConfig.plugins ?? [])],
+            mcp: { ...(globalConfig.mcp ?? {}) },
+            permission: globalConfig.permission,
+        };
+    }
     const projectConfig = await readJsonConfig(workspaceRoot);
     return {
         ...globalConfig,
@@ -162,33 +194,37 @@ export async function collectRules(workspaceRoot) {
         seen.add(resolved);
         rules.push(rule);
     };
-    for (const name of ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]) {
-        const hit = await findUp(name, workspaceRoot, worktree);
-        if (hit) {
-            await add(hit);
-            break;
+    // Match OpenCode: OPENCODE_DISABLE_PROJECT_CONFIG skips project AGENTS/CLAUDE/CONTEXT
+    // discovery and project opencode.json (see loadMergedConfig).
+    if (!isProjectConfigDisabled()) {
+        for (const name of ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]) {
+            const hit = await findUp(name, workspaceRoot, worktree);
+            if (hit) {
+                await add(hit);
+                break;
+            }
         }
     }
     await add(path.join(opencodeGlobalConfigDir(), "AGENTS.md"));
     await add(path.join(homedir(), ".claude", "CLAUDE.md"));
     for (const raw of config.instructions ?? []) {
         if (raw.startsWith("http://") || raw.startsWith("https://")) {
+            // HTTPS-only. Redirects (incl. to a local proxy) are intentional — do not
+            // disable follow-redirects or reject localhost/private/metadata hosts.
+            let remoteUrl;
             try {
-                const ctrl = new AbortController();
-                const t = setTimeout(() => ctrl.abort(), 5000);
-                const res = await fetch(raw, { signal: ctrl.signal });
-                clearTimeout(t);
-                if (!res.ok)
-                    continue;
-                const content = await res.text();
-                if (!content.trim() || seen.has(raw))
-                    continue;
-                seen.add(raw);
-                rules.push({ fullPath: raw, content });
+                remoteUrl = new URL(raw);
             }
             catch {
-                /* ignore */
+                continue;
             }
+            if (remoteUrl.protocol !== "https:")
+                continue;
+            const content = await fetchRemoteInstruction(remoteUrl.href);
+            if (!content?.trim() || seen.has(raw))
+                continue;
+            seen.add(raw);
+            rules.push({ fullPath: raw, content });
             continue;
         }
         const expanded = resolveHomeRelative(raw);

package/dist/debug.d.ts

@@ -1 +1,10 @@
+/** Resolve the debug log path (env override or per-uid tmpdir default). */
+export declare function resolveDebugLogPath(): string;
+/**
+ * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Exported for tests; callers normally go through `trace`.
+ */
+export declare function ensureSecureDebugLog(filePath: string, options?: {
+    secureParent?: boolean;
+}): void;
 export declare function trace(msg: string): void;

package/dist/debug.js

@@ -1,20 +1,60 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 // Wire-level diagnostics. Opt in with CURSOR_PROVIDER_DEBUG=1 (or "true").
-// Writes to CURSOR_PROVIDER_DEBUG_FILE (default /tmp/cursor-provider-debug.log).
+// Default path mirrors Cursor CLI: $TMPDIR/cursor-provider-logs-<uid>/debug-<pid>.log
+// with directory mode 0o700 and file mode 0o600. Override with CURSOR_PROVIDER_DEBUG_FILE.
 // Truncated once per process. Tokens / checksums should be redacted by callers.
 const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
     process.env.CURSOR_PROVIDER_DEBUG === "true";
-const DEBUG_FILE = process.env.CURSOR_PROVIDER_DEBUG_FILE || "/tmp/cursor-provider-debug.log";
 let _traceInitialized = false;
+let _debugFile;
+let _debugFileUsesManagedDirectory = false;
+/** Resolve the debug log path (env override or per-uid tmpdir default). */
+export function resolveDebugLogPath() {
+    if (process.env.CURSOR_PROVIDER_DEBUG_FILE) {
+        return process.env.CURSOR_PROVIDER_DEBUG_FILE;
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : process.pid;
+    return path.join(os.tmpdir(), `cursor-provider-logs-${uid}`, `debug-${process.pid}.log`);
+}
+/**
+ * Ensure the log directory is 0o700 and create/truncate the log file as 0o600.
+ * Exported for tests; callers normally go through `trace`.
+ */
+export function ensureSecureDebugLog(filePath, options = {}) {
+    const dir = path.dirname(filePath);
+    const secureParent = options.secureParent ?? true;
+    fs.mkdirSync(dir, secureParent
+        ? { recursive: true, mode: 0o700 }
+        : { recursive: true });
+    if (secureParent) {
+        const stat = fs.lstatSync(dir);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`Debug log directory is not a real directory: ${dir}`);
+        }
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+            throw new Error(`Debug log directory is not owned by the current user: ${dir}`);
+        }
+        fs.chmodSync(dir, 0o700);
+    }
+    fs.writeFileSync(filePath, "", { mode: 0o600 });
+    fs.chmodSync(filePath, 0o600);
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
     try {
+        if (!_debugFile) {
+            _debugFileUsesManagedDirectory = !process.env.CURSOR_PROVIDER_DEBUG_FILE;
+            _debugFile = resolveDebugLogPath();
+        }
         if (!_traceInitialized) {
+            ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
+            fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
             _traceInitialized = true;
-            fs.writeFileSync(DEBUG_FILE, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`);
         }
-        fs.appendFileSync(DEBUG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+        fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
     catch {
         /* ignore */

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;