cursor-opencode-provider 0.1.5 → 0.2.2

package/DISCLAIMER.md

@@ -0,0 +1,9 @@
+# EU Interoperability Disclaimer
+
+This project is expressly designed to comply with European Union law on the legal protection of computer programs, in particular Directive 2009/24/EC of the European Parliament and of the Council of 23 April 2009 (“EU Software Directive”), as implemented in the relevant EU Member States.
+
+The project is architected on the basis that its reverse-engineering and interface-analysis activities are strictly limited to what EU law expressly permits: acts necessary to use a lawfully acquired program for its intended purpose, including error correction, and acts strictly necessary to obtain the information required to achieve interoperability between an independently created computer program and other programs, under Articles 5 and 6 of Directive 2009/24/EC and corresponding national provisions. It is not designed to copy or reproduce proprietary source code or non-essential implementation details of any third-party software, but to access and use only the minimum interface information objectively required to enable technical interoperability where such information is not otherwise readily available through official or documented means.
+
+When used as intended—namely, to enable lawful interoperability between independently created software components in accordance with Directive 2009/24/EC and applicable national law - this project is meant to operate in full compliance with those legal provisions. Any use that departs from this intended, interoperability-focused purpose (for example, to circumvent technical protections, replicate proprietary implementations, or violate third-party service terms) falls outside the scope of the project’s design and may not comply with applicable law; responsibility for such misuse lies solely with the user.
+
+This statement reflects the legal and compliance orientation of the project but does not replace tailored legal advice.

package/README.md

@@ -18,7 +18,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 - **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 tool-call parts; strips OpenCode's `read` XML envelope (`<path>`/`<content>` + `N:` prefixes) before returning content to Cursor so the model cannot echo the wrapper into writes
+- **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
 - **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.1.5"`.
+Pin a version if you want: `"cursor-opencode-provider@0.2.1"`.
 
 ### From a local clone
 
@@ -102,7 +102,7 @@ Choose the **cursor** provider, then one of:
 | **Cursor account (browser login)** | PKCE OAuth — opens cursor.com to sign in |
 | **API key** | Paste a key from [cursor.com/settings](https://cursor.com/settings) (`sk-...`) |
 
-After login, the plugin fetches your available models and writes them to `~/.cache/opencode/cursor-models.json` (or `$XDG_CACHE_HOME/opencode/` when set). On later startups, if that cache is missing or empty but Cursor auth is still present, the plugin fetches again during config load.
+After login, the plugin fetches your available models and writes them to `~/.cache/opencode/cursor-models.json` (or `$XDG_CACHE_HOME/opencode/` when set). On later startups, a missing, empty, expired, or old-schema cache is refreshed during config load when Cursor auth is available; an existing stale cache remains usable if refresh fails.
 
 ### Paths (XDG)
 
@@ -114,12 +114,38 @@ After login, the plugin fetches your available models and writes them to `~/.cac
 
 ### Select a model
 
-Pick a model from the cached list (for example `composer-2.5`, `default`, or a Claude/GPT variant exposed by your subscription):
+Pick a model from the cached list (for example `composer-2.5`, `default`, or a Claude/GPT model exposed by your subscription):
 
 ```bash
 opencode run --model cursor/composer-2.5 "Hello from Cursor via OpenCode"
 ```
 
+#### Variants
+
+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).
+
+#### 1M / long context
+
+OpenCode’s context limit is static per model entry, while Cursor’s long-context tier is a variant parameter (`context=1m`). When a model has both a base tier and a `1m` tier, the plugin emits a separate OpenCode entry `<model-id>-1m` (for example `claude-opus-4-8-1m`) with:
+
+- `limit.context` set to the 1M window (so overflow checks and compaction match the tier)
+- `limit.output` set to `128000` (max generation tokens — not the context window; base entries use `32000`)
+- only the long-context variants in its picker
+- the real Cursor model id carried in `options.cursorModelId` (not `config.id`, which would make OpenCode merge base variants into the 1M entry)
+
+The Run still uses Cursor’s original model id; OpenCode’s synthetic `-1m` id is only for picking and limits.
+
+#### Max mode
+
+Cursor IDE has a separate **Max Mode** toggle that sets `requested_model.max_mode` and selects the default max / 1m variant. OpenCode has no equivalent custom toggle, so this provider approximates it:
+
+- Selecting a `*-1m` model (or any resolved params with `context=1m`) sets wire `max_mode` to `true`
+- An explicit `providerOptions.cursor.maxMode` hint also turns it on
+
+There is no independent Max Mode chrome in OpenCode beyond choosing the 1M model / long-context variant.
+
 ## Programmatic usage
 
 ```ts
@@ -186,7 +212,7 @@ OpenCode
 | `src/models.ts` | `AvailableModels` fetch and `cursor-models.json` cache |
 | `src/agent-url.ts` | `GetServerConfig` fetch + in-process memo (region-specific Run host) |
 | `src/transport/connect.ts` | HTTP/2 bidi stream and unary RPC calls |
-| `src/protocol/` | Protobuf encode/decode, checksum/device ids, tool-call mapping |
+| `src/protocol/` | Protobuf encode/decode, checksum/device ids, exec + display tool-call mapping (`tool-call-bridge.ts`) |
 
 ## Package exports
 
@@ -206,7 +232,7 @@ 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. |
+| 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. |
 
@@ -214,9 +240,13 @@ OpenCode
 
 - **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.
-- **Tool-call display stub** — semantic `tool_call_started` frames are only partially decoded. Tool execution itself goes through the exec channel and works; UI that relied solely on the display type would be incomplete.
+- **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. 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.
+- **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.
 - **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/dist/context/build.js

@@ -24,8 +24,9 @@ export async function buildRequestContext(input) {
         collectGit(workspaceRoot),
         collectProjectLayout(workspaceRoot),
     ]);
-    const flat = toolsToDescriptors(tools, providerIdentifier);
-    const nested = toolsToMcpDescriptors(tools, providerIdentifier);
+    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" &&

package/dist/context/rules.d.ts

@@ -7,6 +7,7 @@ export type OpencodeJson = {
     permission?: unknown;
     plugin?: string[];
     plugins?: string[];
+    mcp?: Record<string, unknown>;
 };
 export declare function loadMergedConfig(workspaceRoot: string): Promise<OpencodeJson>;
 /**

package/dist/context/rules.js

@@ -138,6 +138,7 @@ export async function loadMergedConfig(workspaceRoot) {
         instructions: [...(globalConfig.instructions ?? []), ...(projectConfig.instructions ?? [])],
         plugin: [...new Set([...(globalConfig.plugin ?? []), ...(projectConfig.plugin ?? [])])],
         plugins: [...new Set([...(globalConfig.plugins ?? []), ...(projectConfig.plugins ?? [])])],
+        mcp: { ...(globalConfig.mcp ?? {}), ...(projectConfig.mcp ?? {}) },
         permission: projectConfig.permission ?? globalConfig.permission,
     };
 }

package/dist/language-model.d.ts

@@ -1,6 +1,10 @@
-import type { LanguageModelV3, LanguageModelV3CallOptions } from "@ai-sdk/provider";
+import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
 import type { CreateCursorOptions } from "./index.js";
+import { type OpencodeToolDef } from "./protocol/tools.js";
 import { type CursorSession } from "./session.js";
+import type { SeedHistoryMessage } from "./protocol/request.js";
+export declare const MAX_TURN_STATE_SESSIONS = 256;
+type V3Part = LanguageModelV3StreamPart;
 export declare function createCursorLanguageModel(modelId: string, providerId: string, options: CreateCursorOptions): LanguageModelV3;
 /**
  * OpenCode re-sends the full tool-result history on every continuation. Prefer
@@ -10,6 +14,16 @@ export declare function findContinuationSession(toolResults: Array<{
     sessionId: string;
     execId: number;
 }>): 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.
+ */
+export declare function pump(session: CursorSession, controller: ReadableStreamDefaultController<V3Part>, ids: {
+    textId: string;
+    reasoningId: string;
+}, abortSignal?: AbortSignal): Promise<void>;
 type ExtractedToolResult = {
     sessionId: string;
     execId: number;
@@ -24,12 +38,28 @@ type ExtractedToolResult = {
  */
 export declare function extractTrailingToolResults(prompt: LanguageModelV3CallOptions["prompt"]): ExtractedToolResult[];
 /**
- * Map OpenCode's session id header to a stable Cursor conversation_id (UUID).
- * Falls back to a random UUID when headers are absent (direct SDK use).
+ * Cursor's native UI interactions cannot be surfaced through the AI SDK.
+ * 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;
+/** Rough char→token estimate for mid-turn usage before TurnEnded arrives. */
+export declare function estimateTokens(chars: number): 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[];
+/** OpenCode session id header, if present. */
+export declare function opencodeSessionKey(callOptions: LanguageModelV3CallOptions): string | undefined;
+/**
+ * Map OpenCode's session id header to the active Cursor conversation_id.
+ * Compaction resets remint via bindConversationId; otherwise the binding is
+ * sticky for the OpenCode session. Falls back to a random UUID with no header.
  */
 export declare function resolveConversationId(callOptions: LanguageModelV3CallOptions): string;
-/** Deterministic UUID (version-4 shape) from an arbitrary session key. */
-export declare function sessionIdToUuid(sessionId: string): string;
+export { sessionIdToUuid } from "./protocol/conversation-bind.js";
 /** Exported for tests — AI SDK V3 span ends that must precede finish / tool-call. */
 export declare function spanEndParts(opts: {
     textStarted: boolean;
@@ -42,4 +72,20 @@ export declare function spanEndParts(opts: {
 }>;
 /** Exported for tests — false for compaction/summary (no tools) and toolChoice none. */
 export declare function computeAllowTools(toolCount: number, toolChoice: LanguageModelV3CallOptions["toolChoice"] | undefined): boolean;
-export {};
+export declare function resolveTurnToolState(input: {
+    sessionKey?: string;
+    incomingTools: OpencodeToolDef[];
+    toolChoice?: LanguageModelV3CallOptions["toolChoice"];
+    isCompaction: boolean;
+}): {
+    advertisedTools: OpencodeToolDef[];
+    allowTools: boolean;
+};
+export declare function resolveTurnConversationReset(input: {
+    sessionKey?: string;
+    isCompaction: boolean;
+}): {
+    reset: boolean;
+    reason?: "compaction" | "post-compaction-rebase";
+};
+export declare function resetTurnStateForTests(): void;