cursor-opencode-provider 0.4.1 → 0.4.2

package/README.md

@@ -1,10 +1,38 @@
 # cursor-opencode-provider
 
-Use [Cursor](https://cursor.com) subscription models from [OpenCode](https://opencode.ai) by speaking Cursor's Connect-RPC agent protocol.
+Use [Cursor](https://cursor.com) subscription models from [OpenCode](https://opencode.ai) and compatible coding agents by speaking Cursor's Connect-RPC agent protocol.
 
 This project is a custom **AI SDK provider** (`LanguageModelV3`) plus an **OpenCode plugin** that handles authentication and model discovery. Instead of calling a generic chat-completions API, it encodes and decodes Cursor's protobuf agent protocol over HTTP/2 to Cursor's agent backend.
 
-> **Status:** Usable end-to-end in OpenCode (auth, models, streaming, tools). See [Known limitations](#known-limitations).
+> **Runs unchanged across OpenCode, OpenCode 2.0, and four additional coding agents.** OpenCode loads this plugin natively, including through the dedicated OpenCode 2.0 entrypoint. [OCP — OpenCode Plugin Compatibility](https://github.com/oakimov/opencode-plugin-compat) runs the same published plugin, without a provider fork, in **Kilo Code, MiMo Code, pi, and oh-my-pi**. See [Coding-agent compatibility](#coding-agent-compatibility).
+>
+> **Status:** Usable end-to-end for authentication, model discovery, streaming, and tools. See [Known limitations](#known-limitations).
+
+## Coding-agent compatibility
+
+This package remains one OpenCode plugin and AI SDK provider. The external
+**[OCP compatibility layer](https://github.com/oakimov/opencode-plugin-compat)**
+adapts other hosts around that unchanged package: it translates their plugin
+surfaces, model catalogs, tool vocabulary, authentication, and streaming events
+instead of requiring a host-specific Cursor provider.
+
+| Coding agent | How this package runs |
+|---|---|
+| **OpenCode** | Native plugin and AI SDK provider |
+| **OpenCode 2.0** | Native dedicated `cursor-opencode-provider/plugin/opencode2` entrypoint |
+| **Kilo Code** | Unchanged through OCP's OpenCode-clone compatibility layer |
+| **MiMo Code** | Unchanged through OCP's OpenCode-clone compatibility layer |
+| **pi** | Unchanged through `@opencode-compat/pi-bridge` and pi's provider extension API |
+| **oh-my-pi (omp)** | Unchanged through the same Pi-family bridge |
+
+Start with OCP's host guides:
+
+- [OpenCode clones: Kilo Code and MiMo Code](https://github.com/oakimov/opencode-plugin-compat/blob/main/docs/hosts/opencode-clones.md)
+- [Pi family: pi and oh-my-pi](https://github.com/oakimov/opencode-plugin-compat/blob/main/docs/hosts/pi-family.md)
+
+OCP is designed to grow by adding host profiles and narrow adapters or bridges,
+so support for other coding agents can be added there while this provider and
+its package remain unchanged.
 
 ## Demo
 
@@ -14,6 +42,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 
 ## Features
 
+- **Multi-host compatibility** — the same plugin package runs natively in OpenCode and OpenCode 2.0, and unchanged through OCP in Kilo Code, MiMo Code, pi, and oh-my-pi; new host support belongs in the compatibility layer rather than a provider fork
 - **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
@@ -25,7 +54,7 @@ OpenCode driving a Cursor-routed Grok model through this provider:
 ## Requirements
 
 - [Bun](https://bun.sh) (for development and tests)
-- [OpenCode](https://opencode.ai) with plugin support
+- [OpenCode](https://opencode.ai), or a supported host configured through [OCP](https://github.com/oakimov/opencode-plugin-compat)
 - An active Cursor account with API access
 
 ## Installation
@@ -447,6 +476,7 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 - **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.
 - **Host web tools use collision-safe aliases** — Cursor sees `custom_websearch` / `custom_webfetch`, and the held Run maps each alias back to an executable OpenCode tool with its schema, permission check, and correlated result intact. The plugin registers its search fallback directly as `custom_websearch`, avoiding OpenCode's reserved `websearch` id filter for third-party providers and taking precedence over MCP search providers such as Brave without host environment configuration. Exact host `webfetch` is translated the same way. Cursor's UI-bound native web interactions stay disabled because their approval replies cannot carry OpenCode tool results.
+- **MCP resource tools (`list_mcp_resources` / `read_mcp_resource`) also use collision-safe aliases, and Cursor's native resource exec is always answered** — OpenCode's resource tools (advertised only when a connected MCP server declares `capabilities.resources`) share bare names with two of Cursor's own native tool-call variants. Left unaliased, Cursor's client can route a call onto its native exec channel instead of the ordinary MCP tool path, which this provider does not translate — confirmed live: reading a resource was dispatched natively and killed the Run before this fix. The provider now aliases both names to `custom_list_mcp_resources` / `custom_read_mcp_resource` (same mechanism as web search/fetch) so normal calls execute through OpenCode's tools, and separately answers Cursor's native resource-exec fields directly on the protocol floor — an empty list, or a "server not found" error for read — so an unsolicited native request from Cursor can never fail the Run. Downloads (`download_path`) have no OpenCode equivalent and are always refused; binary resource content is subject to the same [50 KB / attachment-type limits](#known-limitations) as other tool results.
 - **Background shells are non-interactive** — Cursor's native background-shell spawn and soft-background shell-stream timeouts are bridged through OpenCode's foreground-only `bash` tool. With bash/zsh, the classic plugin keeps the original permission/UI command and executes the wrapper through `shell.env` (`BASH_ENV` / `ZDOTDIR`); OpenCode's non-interactive sh/dash argv ignores those startup variables, so the plugin uses a short `exec /bin/sh '<wrapper-file>'` command backed by the same private wrapper. Native background-spawn requests also carry a self-contained marker-producing fallback when the classic hooks are absent. Spawn/soft-bg wrappers detach with `nohup`, redirect output under `${TMPDIR:-/tmp}/cursor-opencode-{bg,shell}.*`, and return the real PID (or typed timeout/exit) to Cursor. Private markers and OpenCode's `<shell_metadata>` envelope are stripped before storage/render, with a short still-running / started / timed-out status line left for the bash bubble. 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. The POSIX wrap path is not implemented for native Windows PowerShell/`cmd`.
 - **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 available web capabilities to executable host tools (`question`, `todowrite`, `plan_enter` / `plan_exit`, `custom_websearch`, `custom_webfetch`); native web/PR/MCP/image/SCM requests are declined so they remain behind host tool 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.

package/dist/language-model.js

@@ -6,7 +6,7 @@ import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
 import { debugWalkTurnEnded, decodeMessage } from "./protocol/messages.js";
-import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, } from "./protocol/tools.js";
+import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } from "./protocol/tools.js";
 import { describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.js";
@@ -1089,6 +1089,14 @@ export async function pump(session, controller, ids, abortSignal) {
         const requested = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
         if (!requested)
             return false;
+        // A scheme-addressed target is the host's to resolve, not a local file to
+        // stat. Rejecting it here makes host-mounted capabilities (oh-my-pi's
+        // `xd://` device URLs, which is how every MCP tool is exposed by default)
+        // permanently unreachable through this provider.
+        if (isUriReadTarget(requested)) {
+            trace(`exec: forwarding URI read target id=${parsed.id} target=${JSON.stringify(requested)}`);
+            return false;
+        }
         const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
         const absolutePath = resolveReadTargetPath(requested, workspaceRoot);
         const readResult = classifyMissingReadTarget(absolutePath);
@@ -1460,6 +1468,33 @@ export async function pump(session, controller, ids, abortSignal) {
                         failRunProtocol("Cursor MCP-state reply failed", RUN_REPLY_FAILED);
                     }
                 }
+                else if (esm.list_mcp_resources_exec_args) {
+                    // Native Cursor exec (agent.v1 field 17), no OpenCode route under
+                    // Option B — see tasks/plans/fix-cursor-mcp-resource-exec.md. Answer
+                    // with Cursor's own no-client-qualifies shape and keep pumping.
+                    const args = esm.list_mcp_resources_exec_args;
+                    const server = typeof args.server === "string" ? args.server : "";
+                    try {
+                        session.stream.write(buildListMcpResourcesFallback(esmId));
+                        trace(`exec list_mcp_resources: replied id=${esmId} server=${server || "(all)"} success{resources:[]}`);
+                    }
+                    catch {
+                        failRunProtocol("Cursor list_mcp_resources reply failed", RUN_REPLY_FAILED);
+                    }
+                }
+                else if (esm.read_mcp_resource_exec_args) {
+                    // Native Cursor exec (agent.v1 field 18) — same rationale as above.
+                    const args = esm.read_mcp_resource_exec_args;
+                    const server = typeof args.server === "string" ? args.server : "";
+                    const uri = typeof args.uri === "string" ? args.uri : "";
+                    try {
+                        session.stream.write(buildReadMcpResourceFallback(esmId, server, uri));
+                        trace(`exec read_mcp_resource: replied id=${esmId} server=${server} uri=${uri} error{server not found}`);
+                    }
+                    catch {
+                        failRunProtocol("Cursor read_mcp_resource reply failed", RUN_REPLY_FAILED);
+                    }
+                }
                 else {
                     replaySafety.markBarrier("non-control-exec");
                     const displayCallId = extractExecDisplayCallId(esm);
@@ -1759,6 +1794,12 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has(CUSTOM_WEBFETCH_TOOL)) {
         instructions.push(`- To fetch a known URL, call \`${CUSTOM_WEBFETCH_TOOL}\`; do not use Cursor's native WebFetch interaction.`);
     }
+    if (names.has(CUSTOM_LIST_MCP_RESOURCES_TOOL)) {
+        instructions.push(`- To list MCP resources, call \`${CUSTOM_LIST_MCP_RESOURCES_TOOL}\`; do not use Cursor's native resource-listing interaction.`);
+    }
+    if (names.has(CUSTOM_READ_MCP_RESOURCE_TOOL)) {
+        instructions.push(`- To read an MCP resource, call \`${CUSTOM_READ_MCP_RESOURCE_TOOL}\`; do not use Cursor's native resource-reading interaction.`);
+    }
     if (names.has("task") || names.has("actor")) {
         const target = names.has("actor") ? "`actor`" : "`task`";
         const available = subagents.agents.map((agent) => `\`${agent.name}\``).join(", ");

package/dist/protocol/exec-variants.js

@@ -10,8 +10,8 @@ export const CURSOR_EXEC_VARIANTS = [
     { requestField: 11, requestName: "mcp_args", resultField: 11, resultName: "mcp_result", handling: "opencode-tool" },
     { requestField: 14, requestName: "shell_stream_args", resultField: 14, resultName: "shell_stream", handling: "opencode-tool" },
     { requestField: 16, requestName: "background_shell_spawn_args", resultField: 16, resultName: "background_shell_spawn_result", handling: "opencode-tool" },
-    { requestField: 17, requestName: "list_mcp_resources_exec_args", resultField: 17, resultName: "list_mcp_resources_exec_result", handling: "unsupported" },
-    { requestField: 18, requestName: "read_mcp_resource_exec_args", resultField: 18, resultName: "read_mcp_resource_exec_result", handling: "unsupported" },
+    { requestField: 17, requestName: "list_mcp_resources_exec_args", resultField: 17, resultName: "list_mcp_resources_exec_result", handling: "provider-control" },
+    { requestField: 18, requestName: "read_mcp_resource_exec_args", resultField: 18, resultName: "read_mcp_resource_exec_result", handling: "provider-control" },
     { requestField: 20, requestName: "fetch_args", resultField: 20, resultName: "fetch_result", handling: "unsupported" },
     { requestField: 21, requestName: "record_screen_args", resultField: 21, resultName: "record_screen_result", handling: "unsupported" },
     { requestField: 22, requestName: "computer_use_args", resultField: 22, resultName: "computer_use_result", handling: "unsupported" },

package/dist/protocol/messages.js

@@ -679,6 +679,87 @@ export function createMessageTypes() {
         { id: 4, name: "provider_identifier", type: "string" },
         { id: 5, name: "tool_name", type: "string" },
     ]);
+    // ── MCP resource exec (fields 17/18) ──
+    // agent.v1 ListMcpResourcesExecArgs/Result, ReadMcpResourceExecArgs/Result.
+    // Native Cursor exec variants: no descriptor, no advertisement, and Cursor
+    // may emit either unsolicited regardless of what this provider advertises
+    // (tasks/plans/fix-cursor-mcp-resource-exec.md, Correction 2). Under Option
+    // B, list_mcp_resources/read_mcp_resource execute through the ordinary
+    // field-11 MCP path via the alias rules below, so any 17/18 that still
+    // reaches this provider gets the total fallback built in tools.ts.
+    addType(root, "SmartModeApproval", [
+        { id: 1, name: "request_id", type: "string" },
+        { id: 2, name: "reason", type: "string" },
+    ]);
+    addType(root, "OutputLocation", [
+        { id: 1, name: "file_path", type: "string" },
+        { id: 2, name: "size_bytes", type: "int64" },
+        { id: 3, name: "line_count", type: "int64" },
+    ]);
+    addType(root, "ListMcpResourcesExecArgs", [
+        { id: 1, name: "server", type: "string" },
+    ]);
+    {
+        const t = new protobuf.Type("ListMcpResourcesExecResult_McpResource");
+        t.add(new protobuf.Field("uri", 1, "string"));
+        t.add(new protobuf.Field("name", 2, "string"));
+        t.add(new protobuf.Field("description", 3, "string"));
+        t.add(new protobuf.Field("mime_type", 4, "string"));
+        t.add(new protobuf.Field("server", 5, "string"));
+        t.add(new protobuf.MapField("annotations", 6, "string", "string"));
+        root.add(t);
+    }
+    addType(root, "ListMcpResourcesSuccess", [
+        { id: 1, name: "resources", type: "ListMcpResourcesExecResult_McpResource", repeated: true },
+    ]);
+    addType(root, "ListMcpResourcesError", [{ id: 1, name: "error", type: "string" }]);
+    addType(root, "ListMcpResourcesRejected", [{ id: 1, name: "reason", type: "string" }]);
+    addType(root, "ListMcpResourcesExecResult", [
+        { id: 1, name: "success", type: "ListMcpResourcesSuccess" },
+        { id: 2, name: "error", type: "ListMcpResourcesError" },
+        { id: 3, name: "rejected", type: "ListMcpResourcesRejected" },
+    ], [{ name: "result", fields: ["success", "error", "rejected"] }]);
+    addType(root, "ReadMcpResourceExecArgs", [
+        { id: 1, name: "server", type: "string" },
+        { id: 2, name: "uri", type: "string" },
+        { id: 3, name: "download_path", type: "string" },
+        { id: 4, name: "tool_call_id", type: "string" },
+        { id: 5, name: "smart_mode_approval", type: "SmartModeApproval" },
+    ]);
+    {
+        // Interleaved field order matches agent.proto exactly: the text/blob oneof
+        // (5/6) sits between the shared metadata (1-4) and the trailing
+        // annotations/download/output fields (7-9).
+        const t = new protobuf.Type("ReadMcpResourceSuccess");
+        t.add(new protobuf.Field("uri", 1, "string"));
+        t.add(new protobuf.Field("name", 2, "string"));
+        t.add(new protobuf.Field("description", 3, "string"));
+        t.add(new protobuf.Field("mime_type", 4, "string"));
+        t.add(new protobuf.Field("text", 5, "string"));
+        t.add(new protobuf.Field("blob", 6, "bytes"));
+        t.add(new protobuf.MapField("annotations", 7, "string", "string"));
+        t.add(new protobuf.Field("download_path", 8, "string"));
+        t.add(new protobuf.Field("output_location", 9, "OutputLocation"));
+        t.add(new protobuf.OneOf("content", ["text", "blob"]));
+        root.add(t);
+    }
+    addType(root, "ReadMcpResourceError", [
+        { id: 1, name: "uri", type: "string" },
+        { id: 2, name: "error", type: "string" },
+    ]);
+    // Cursor quirk: on `rejected` only `reason` is set — `uri` (field 1) is
+    // deliberately left empty. Mirror this; do not backfill uri on encode.
+    addType(root, "ReadMcpResourceRejected", [
+        { id: 1, name: "uri", type: "string" },
+        { id: 2, name: "reason", type: "string" },
+    ]);
+    addType(root, "ReadMcpResourceNotFound", [{ id: 1, name: "uri", type: "string" }]);
+    addType(root, "ReadMcpResourceExecResult", [
+        { id: 1, name: "success", type: "ReadMcpResourceSuccess" },
+        { id: 2, name: "error", type: "ReadMcpResourceError" },
+        { id: 3, name: "rejected", type: "ReadMcpResourceRejected" },
+        { id: 4, name: "not_found", type: "ReadMcpResourceNotFound" },
+    ], [{ name: "result", fields: ["success", "error", "rejected", "not_found"] }]);
     // ── request_context (#10): server-initiated setup probe ──
     // At the start of an agent turn the server sends ExecServerMessage
     // {request_context_args} to ask the client for workspace/env/tool context.
@@ -841,6 +922,8 @@ export function createMessageTypes() {
         { id: 11, name: "mcp_args", type: "McpArgs" },
         { id: 14, name: "shell_stream_args", type: "ShellArgs" },
         { id: 16, name: "background_shell_spawn_args", type: "BackgroundShellSpawnArgs" },
+        { id: 17, name: "list_mcp_resources_exec_args", type: "ListMcpResourcesExecArgs" },
+        { id: 18, name: "read_mcp_resource_exec_args", type: "ReadMcpResourceExecArgs" },
         { id: 28, name: "subagent_args", type: "SubagentArgs" },
         { id: 36, name: "mcp_state_exec_args", type: "McpStateExecArgs" },
         { id: 45, name: "pi_read_args", type: "PiReadToolArgs" },
@@ -852,7 +935,8 @@ export function createMessageTypes() {
         { id: 51, name: "pi_ls_args", type: "PiLsToolArgs" },
     ], [{ name: "args", fields: [
                 "write_args", "delete_args", "grep_args", "read_args", "ls_args",
-                "request_context_args", "mcp_args", "shell_stream_args", "background_shell_spawn_args", "mcp_state_exec_args",
+                "request_context_args", "mcp_args", "shell_stream_args", "background_shell_spawn_args",
+                "list_mcp_resources_exec_args", "read_mcp_resource_exec_args", "mcp_state_exec_args",
                 "subagent_args",
                 "pi_read_args", "pi_bash_args", "pi_edit_args", "pi_write_args",
                 "pi_grep_args", "pi_find_args", "pi_ls_args",
@@ -871,6 +955,8 @@ export function createMessageTypes() {
         { id: 11, name: "mcp_result", type: "McpResult" },
         { id: 14, name: "shell_stream", type: "ShellStream" },
         { id: 16, name: "background_shell_spawn_result", type: "BackgroundShellSpawnResult" },
+        { id: 17, name: "list_mcp_resources_exec_result", type: "ListMcpResourcesExecResult" },
+        { id: 18, name: "read_mcp_resource_exec_result", type: "ReadMcpResourceExecResult" },
         { id: 28, name: "subagent_result", type: "SubagentResult" },
         { id: 36, name: "mcp_state_exec_result", type: "McpStateExecResult" },
         { id: 46, name: "pi_read_result", type: "PiReadExecResult" },
@@ -882,7 +968,8 @@ export function createMessageTypes() {
         { id: 52, name: "pi_ls_result", type: "PiLsExecResult" },
     ], [{ name: "result", fields: [
                 "write_result", "delete_result", "grep_result", "read_result", "ls_result",
-                "request_context_result", "mcp_result", "shell_stream", "background_shell_spawn_result", "mcp_state_exec_result",
+                "request_context_result", "mcp_result", "shell_stream", "background_shell_spawn_result",
+                "list_mcp_resources_exec_result", "read_mcp_resource_exec_result", "mcp_state_exec_result",
                 "subagent_result",
                 "pi_read_result", "pi_bash_result", "pi_edit_result", "pi_write_result",
                 "pi_grep_result", "pi_find_result", "pi_ls_result",

package/dist/protocol/tools.d.ts

@@ -9,6 +9,8 @@ export type OpencodeToolDef = {
 };
 export declare const CUSTOM_WEBSEARCH_TOOL = "custom_websearch";
 export declare const CUSTOM_WEBFETCH_TOOL = "custom_webfetch";
+export declare const CUSTOM_LIST_MCP_RESOURCES_TOOL = "custom_list_mcp_resources";
+export declare const CUSTOM_READ_MCP_RESOURCE_TOOL = "custom_read_mcp_resource";
 /** Cursor-facing alias → exact host tool name accepted by the AI SDK call. */
 export type ToolAliasRegistry = ReadonlyMap<string, string>;
 export type AliasedToolCatalog = {
@@ -139,11 +141,31 @@ export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<st
  * → github_create_pull_request). Builtins under the default server stay bare.
  */
 export declare function mcpRealToolName(mcpArgs: Record<string, unknown>, defaultServer?: string): string;
+/**
+ * A read target addressed by URI scheme rather than by local filesystem path.
+ *
+ * Cursor's LocalReadExecutor only ever reads local files, so this provider
+ * mirrors its pre-execution validation. Host read tools are not so limited:
+ * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
+ * discoverable tool — including all MCP server tools — under `xd://<tool>`
+ * device URLs that are read for their schema and written to for execution
+ * (`tools.xdev`, on by default). Resolving those against the workspace root
+ * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
+ * as missing and gets refused as `file_not_found` — so the host's read tool is
+ * never called and every xd://-mounted MCP tool is unreachable through this
+ * provider. Such targets must be forwarded untouched and left to the host.
+ *
+ * Requires a scheme of two or more characters followed by `://`, so Windows
+ * drive letters (`C:\src`, `C:/src`) stay local paths.
+ */
+export declare function isUriReadTarget(requested: string): boolean;
 /**
  * Resolve a read target the way Cursor's LocalReadExecutor does before it
  * stats the file: untildify, then resolve a relative path against the workspace
  * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
  * agent utils `resolvePath(path, workspaceRoot)`.
+ *
+ * Only meaningful for local paths; check {@link isUriReadTarget} first.
  */
 export declare function resolveReadTargetPath(requested: string, workspaceRoot: string): string;
 /**
@@ -253,3 +275,16 @@ export declare function buildRequestContextResult(execId: number, requestContext
  * provider's virtual MCP servers and their tools are available.
  */
 export declare function buildMcpStateResult(execId: number, args: Record<string, unknown>, requestContext: Record<string, unknown>): Uint8Array;
+/**
+ * Total fallback for Cursor's native MCP-resource exec channel (agent.v1
+ * fields #17/#18, tasks/plans/fix-cursor-mcp-resource-exec.md). Under Option B
+ * `list_mcp_resources`/`read_mcp_resource` execute through the ordinary
+ * field-11 MCP path via the alias rules above, so any 17/18 that still reaches
+ * this provider is Cursor emitting the native variant unsolicited (its own
+ * client owns both executors unconditionally — there is no descriptor to
+ * un-advertise). Cursor's executors are total; mirror that here rather than
+ * guessing a generic success, which risks an endless heartbeat loop.
+ */
+export declare function buildListMcpResourcesFallback(execId: number): Uint8Array;
+/** See buildListMcpResourcesFallback. Always an `error`, even for `download_path`. */
+export declare function buildReadMcpResourceFallback(execId: number, server: string, uri: string): Uint8Array;

package/dist/protocol/tools.js

@@ -15,6 +15,8 @@ import { BACKGROUND_SHELL_MARKER, buildBackgroundShellCommand, } from "../shell-
 export const REQUEST_CONTEXT_RESULT_FIELD = 10;
 export const CUSTOM_WEBSEARCH_TOOL = "custom_websearch";
 export const CUSTOM_WEBFETCH_TOOL = "custom_webfetch";
+export const CUSTOM_LIST_MCP_RESOURCES_TOOL = "custom_list_mcp_resources";
+export const CUSTOM_READ_MCP_RESOURCE_TOOL = "custom_read_mcp_resource";
 /** Match OpenCode's McpCatalog.sanitize for config server ids. */
 export function sanitizeMcpServerId(value) {
     return value.replace(/[^a-zA-Z0-9_-]/g, "_");
@@ -57,12 +59,13 @@ export function resolveToolServerIdentity(opencodeName, defaultServer = "opencod
 export function toolsToDescriptors(tools, providerIdentifier = "opencode", knownMcpServers = []) {
     return tools.map((t) => {
         const id = resolveToolServerIdentity(t.sourceName ?? t.name, providerIdentifier, knownMcpServers);
-        const collisionSafeWebAlias = t.name === CUSTOM_WEBSEARCH_TOOL || t.name === CUSTOM_WEBFETCH_TOOL;
+        const collisionSafeAlias = COLLISION_SAFE_ALIASES.has(t.name);
         return {
             // Keep the collision-safe public name exact. Prefixing it with the
             // synthetic default server weakens the distinction from Cursor-native
-            // web tools in the model-visible catalog.
-            name: collisionSafeWebAlias ? t.name : `${id.server}-${id.toolName}`,
+            // capabilities (web search/fetch, MCP resource list/read) in the
+            // model-visible catalog.
+            name: collisionSafeAlias ? t.name : `${id.server}-${id.toolName}`,
             description: t.description ?? "",
             input_schema: encodeJsonAsValue(normalizeInputSchema(t.inputSchema)),
             provider_identifier: id.server,
@@ -76,6 +79,10 @@ function normalizeInputSchema(schema) {
     }
     return { type: "object", properties: {} };
 }
+// Despite the name, these rules cover any advertised OpenCode tool whose bare
+// name collides with a Cursor-native capability, not only web search/fetch —
+// see the MCP resource entries below and
+// tasks/plans/fix-cursor-mcp-resource-exec.md Phase 0/2.
 const WEB_ALIAS_RULES = [
     {
         alias: CUSTOM_WEBSEARCH_TOOL,
@@ -87,7 +94,23 @@ const WEB_ALIAS_RULES = [
         exact: ["webfetch", "web_fetch"],
         suffixes: ["_web_fetch", "-web_fetch", "_webfetch", "-webfetch"],
     },
+    {
+        alias: CUSTOM_LIST_MCP_RESOURCES_TOOL,
+        exact: ["list_mcp_resources"],
+        suffixes: ["_list_mcp_resources", "-list_mcp_resources"],
+    },
+    {
+        alias: CUSTOM_READ_MCP_RESOURCE_TOOL,
+        exact: ["read_mcp_resource"],
+        suffixes: ["_read_mcp_resource", "-read_mcp_resource"],
+    },
 ];
+const COLLISION_SAFE_ALIASES = new Set([
+    CUSTOM_WEBSEARCH_TOOL,
+    CUSTOM_WEBFETCH_TOOL,
+    CUSTOM_LIST_MCP_RESOURCES_TOOL,
+    CUSTOM_READ_MCP_RESOURCE_TOOL,
+]);
 /**
  * Give collision-prone web capabilities names Cursor will not confuse with its
  * native UI-bound WebSearch/WebFetch interactions. Exact host tools win; a
@@ -1100,11 +1123,33 @@ function findOneOfVariant(msg, candidates) {
 function untildify(input) {
     return input.replace(/^~(?=$|\/|\\)/, os.homedir());
 }
+/**
+ * A read target addressed by URI scheme rather than by local filesystem path.
+ *
+ * Cursor's LocalReadExecutor only ever reads local files, so this provider
+ * mirrors its pre-execution validation. Host read tools are not so limited:
+ * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
+ * discoverable tool — including all MCP server tools — under `xd://<tool>`
+ * device URLs that are read for their schema and written to for execution
+ * (`tools.xdev`, on by default). Resolving those against the workspace root
+ * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
+ * as missing and gets refused as `file_not_found` — so the host's read tool is
+ * never called and every xd://-mounted MCP tool is unreachable through this
+ * provider. Such targets must be forwarded untouched and left to the host.
+ *
+ * Requires a scheme of two or more characters followed by `://`, so Windows
+ * drive letters (`C:\src`, `C:/src`) stay local paths.
+ */
+export function isUriReadTarget(requested) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]+:\/\//.test(requested);
+}
 /**
  * Resolve a read target the way Cursor's LocalReadExecutor does before it
  * stats the file: untildify, then resolve a relative path against the workspace
  * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
  * agent utils `resolvePath(path, workspaceRoot)`.
+ *
+ * Only meaningful for local paths; check {@link isUriReadTarget} first.
  */
 export function resolveReadTargetPath(requested, workspaceRoot) {
     const expanded = untildify(requested);
@@ -1916,6 +1961,35 @@ function mcpStateToolDefinition(serverIdentifier, descriptor, flatTools) {
         tool_name: toolName,
     };
 }
+/**
+ * Total fallback for Cursor's native MCP-resource exec channel (agent.v1
+ * fields #17/#18, tasks/plans/fix-cursor-mcp-resource-exec.md). Under Option B
+ * `list_mcp_resources`/`read_mcp_resource` execute through the ordinary
+ * field-11 MCP path via the alias rules above, so any 17/18 that still reaches
+ * this provider is Cursor emitting the native variant unsolicited (its own
+ * client owns both executors unconditionally — there is no descriptor to
+ * un-advertise). Cursor's executors are total; mirror that here rather than
+ * guessing a generic success, which risks an endless heartbeat loop.
+ */
+export function buildListMcpResourcesFallback(execId) {
+    return encodeMessage("AgentClientMessage", {
+        exec_client_message: {
+            id: execId,
+            list_mcp_resources_exec_result: { success: { resources: [] } },
+        },
+    });
+}
+/** See buildListMcpResourcesFallback. Always an `error`, even for `download_path`. */
+export function buildReadMcpResourceFallback(execId, server, uri) {
+    return encodeMessage("AgentClientMessage", {
+        exec_client_message: {
+            id: execId,
+            read_mcp_resource_exec_result: {
+                error: { uri, error: `Server "${server}" not found` },
+            },
+        },
+    });
+}
 function recordValue(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",