cursor-opencode-provider 0.4.0 → 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
@@ -48,7 +77,7 @@ Add the package to OpenCode config. OpenCode installs npm plugins with Bun at st
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.4.0"`.
+Pin a version if you want: `"cursor-opencode-provider@0.4.1"`.
 
 You can also install it yourself first:
 
@@ -118,7 +147,7 @@ browser login or an API key. `CURSOR_API_KEY` is also picked up automatically.
 }
 ```
 
-Pin a version if you want: `"cursor-opencode-provider@0.4.0/plugin/opencode2"`.
+Pin a version if you want: `"cursor-opencode-provider@0.4.1/plugin/opencode2"`.
 
 OpenCode 2.0 installs the published package into its host cache and loads the AI SDK
 entry from there (`aisdk:cursor-opencode-provider`). No extra env vars are required.
@@ -379,11 +408,17 @@ The provider adds OpenCode-specific system guidance to normal tool-capable conve
 
 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).
 
+### Cursor edit handshakes
+
+Cursor's legacy `edit_tool_call` is implemented internally as a correlated `read_args` followed by a whole-file `write_args`; the write is transport mechanics, not a new decision to replace OpenCode's `edit` tool. The provider retains that correlation and exposes an existing-file mutation as one unique, line-bounded OpenCode `edit`. It still returns Cursor's expected typed `write_result`. New-file creation remains a `write`, and an `apply_patch`-only catalog receives the same targeted change as an `*** Update File:` patch.
+
+The prerequisite native read also preserves an existing final LF/CRLF. OpenCode's numbered read envelope cannot represent that terminator, and dropping it made Cursor's exact edit matcher reject valid replacements, retry reads, and eventually rewrite the file. This restoration applies only to confirmed-complete, unbounded reads; paged and capped reads keep their existing truncation behavior.
+
 ### `apply_patch` models (GPT-5 and friends)
 
 OpenCode 1.x does not simply add `apply_patch` for GPT-series models — it **removes** `edit` and `write` from the tool catalog and advertises `apply_patch` in their place (`ToolRegistry.tools`; the model id must contain `gpt-` and neither `oss` nor `gpt-4`). Cursor keeps sending its native write/edit requests regardless, so without translation every file change on a `gpt-5*` model is refused as an unavailable tool.
 
-The provider translates transparently: a native write becomes an `*** Add File:` patch, and a Pi edit becomes a minimal `*** Update File:` chunk widened to whole lines. This is keyed purely off what the host advertises — it is inert whenever `edit`/`write` are offered normally, and inert again when the host offers neither those nor `apply_patch`. An edit that cannot be expressed faithfully (target unreadable, or the text to replace is absent or ambiguous) is refused with a specific message rather than applied to the wrong region.
+The provider translates transparently: an uncorrelated native write becomes an `*** Add File:` patch, while a correlated legacy edit or Pi edit becomes a minimal `*** Update File:` chunk widened to whole lines. This is keyed purely off what the host advertises — it is inert whenever `edit`/`write` are offered normally, and inert again when the host offers neither those nor `apply_patch`. An edit that cannot be expressed faithfully (target unreadable, or the text to replace is absent or ambiguous) is refused with a specific message rather than applied to the wrong region.
 
 OpenCode 2.0 does not perform this substitution, so the path is 1.x-only in practice. See [`src/protocol/apply-patch.ts`](src/protocol/apply-patch.ts) for the upstream references.
 
@@ -425,7 +460,8 @@ The package root intentionally stays plugin-safe for OpenCode's classic loader.
 | 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. |
-| Cache **write** tokens always show as `0` | Not a mapping bug in this provider. Cursor's `TurnEnded` protobuf includes `cache_write` (field 4) and this package forwards it as AI SDK `inputTokens.cacheWrite` / OpenCode `cache.write`. Real agent sessions send field 4 as `0` even when `cache_read` is large on later turns. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0` and `v3CacheWrite=0 source=turn_ended`. Cache **read** counts from the same message do populate correctly. |
+| OpenCode compacts immediately after a tool-heavy task | Upgrade to a version containing the cumulative-usage fix. Cursor's final `TurnEnded` counters cover the entire held multi-step Run; older provider versions exposed that aggregate as the final request's context size, which made OpenCode compact far too early. Fixed versions keep the raw counters in `providerMetadata.cursor` and report a request-local context estimate instead. |
+| Cache **write** tokens always show as `0` | Cursor's `TurnEnded` protobuf includes `cache_write` (field 4), but captured Runs set it to `0` even when `cache_read` is large. Single-step Runs expose those counters directly. For multi-step Runs they remain in `providerMetadata.cursor` because Cursor reports only a cumulative whole-Run total, which cannot safely be used as one OpenCode request's context usage. With debug logging, confirm `turn_ended raw wire fields: … f4:wt0=0`. |
 
 ## Security
 
@@ -434,12 +470,13 @@ Project `instructions` may reference absolute or `~/` paths (OpenCode parity). S
 ## 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.
-- **`TurnEnded.cache_write` is unused by Cursor's agent** — usage comes from `interaction_update.turn_ended` (`input_tokens`, `output_tokens`, `cache_read`, `cache_write`, `reasoning_tokens`). The provider maps those 1:1 into AI SDK V3 nested usage. Captured live Runs consistently set `cache_write=0` on the wire while still reporting non-zero `cache_read` and `reasoning_tokens`; there is no alternate agent-stream field today that supplies write counts, so OpenCode/Kilo cannot show cache-write tokens for this provider until Cursor populates that counter.
+- **`TurnEnded` usage is whole-Run usage** — on a held multi-step Cursor Run, the final `interaction_update.turn_ended` counters aggregate every model invocation across tool boundaries. OpenCode usage is request-local and uses the latest assistant message to decide compaction, so publishing the aggregate there both double-counts earlier steps and causes premature compaction. The provider therefore uses a current-context estimate for multi-step AI SDK usage and preserves the exact cumulative counters in `providerMetadata.cursor`; single-step Runs still map the counters directly. Cursor also consistently sends `cache_write=0` in captured Runs, so no alternate write count is available.
 - **`request_context` from OpenCode** — each Run sends Cursor `RequestContext` built from OpenCode project context (workspace env, `AGENTS.md` / `instructions`, `.opencode` agents/skills/plugins, git, layout, plus `.claude`/`.agents` skill fallbacks). Its canonical root is also used by the [injected system guidance](#injected-system-guidance). Same discovery as OpenCode — including `.cursor/` paths only when listed in `instructions`. Cursor-only cloud/sandbox marketplace surfaces are omitted. `env.workspace_paths` / `process_working_directory` stay on the real git workspace; Cursor's metadata root (`project_folder`, MCP `workspace_project_dir`, terminals/transcripts) is advertised under `<host-cache>/projects/<slug>/` (default `~/.cache/opencode/projects/…`) so dumps like `agent-tools/` do not land in the repo. OpenCode remains the permission authority: its coarse allow/ask/deny configuration is not fabricated into Cursor's unrelated allow/block instruction-list messages.
 - **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.
 - **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/context/paths.d.ts

@@ -26,15 +26,32 @@ type CompatDetector = () => CompatDetectResult;
  */
 export declare function setHostCacheDirOverride(dir: string | undefined): void;
 export declare function getHostCacheDirOverride(): string | undefined;
+declare const HOST_CACHE_DIRS: readonly ["mimocode", "kilo", "opencode"];
+export type HostCacheDir = (typeof HOST_CACHE_DIRS)[number];
+/**
+ * Host cache-dir name inferred from the running binary (`argv[0]` /
+ * `process.execPath`). A source-checkout provider can't be located by install
+ * path, but the binary that loaded it is authoritative: when this process IS
+ * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
+ * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
+ * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
+ * not binary identity, and could otherwise cause false positives (e.g. an
+ * `--opencode-config=…` flag under a fork).
+ */
+export declare function hostCacheDirFromProcess(argv?: readonly string[], execPath?: string): HostCacheDir | undefined;
 /**
  * Resolve the host cache directory without an override.
  *
  * Explicit host environment wins. Otherwise, an installed provider inherits
- * the host-named cache containing its module. A source checkout or otherwise
- * unidentifiable install defaults to OpenCode. Merely having another host's
- * config directory installed is not evidence that it owns this process.
+ * the host-named cache containing its module; a source checkout is attributed
+ * by the running binary identity (see {@link hostCacheDirFromProcess}). Merely
+ * having another host's config directory installed is not evidence that it
+ * owns this process.
  */
-export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string): string;
+export declare function resolveHostCacheDir(env?: HostPathEnv, moduleUrl?: string, processIdentity?: {
+    argv?: readonly string[];
+    execPath?: string;
+}): string;
 /**
  * Best-effort: if `@opencode-compat/profile` is installed, adopt `detect().profile.paths.cacheDir`
  * when the host is supported. No-op when OCP is absent or detection fails.

package/dist/context/paths.js

@@ -48,15 +48,52 @@ export function setHostCacheDirOverride(dir) {
 export function getHostCacheDirOverride() {
     return hostCacheDirOverride;
 }
+const HOST_CACHE_DIRS = ["mimocode", "kilo", "opencode"];
+/**
+ * Host cache-dir name inferred from the running binary (`argv[0]` /
+ * `process.execPath`). A source-checkout provider can't be located by install
+ * path, but the binary that loaded it is authoritative: when this process IS
+ * `mimo` / `kilocode`, the cache root is that host's, not OpenCode's. Mirrors
+ * OCP `detect()` binaryHint semantics and tolerates the leading-dot Kilo binary
+ * (`.kilo`). Only `argv[0]` is inspected — later argv entries are arguments,
+ * not binary identity, and could otherwise cause false positives (e.g. an
+ * `--opencode-config=…` flag under a fork).
+ */
+export function hostCacheDirFromProcess(argv = process.argv, execPath = process.execPath) {
+    for (const raw of [argv[0], execPath]) {
+        if (!raw)
+            continue;
+        const name = path.basename(String(raw)).toLowerCase().replace(/^\.+/, "");
+        if (name === "mimo" ||
+            name === "mimocode" ||
+            name.startsWith("mimo-") ||
+            name.includes("mimocode")) {
+            return "mimocode";
+        }
+        if (name === "kilo" ||
+            name === "kilocode" ||
+            name.startsWith("kilo-") ||
+            name.includes("kilocode")) {
+            return "kilo";
+        }
+        if (name === "opencode" ||
+            name.startsWith("opencode-") ||
+            name.includes("opencode")) {
+            return "opencode";
+        }
+    }
+    return undefined;
+}
 /**
  * Resolve the host cache directory without an override.
  *
  * Explicit host environment wins. Otherwise, an installed provider inherits
- * the host-named cache containing its module. A source checkout or otherwise
- * unidentifiable install defaults to OpenCode. Merely having another host's
- * config directory installed is not evidence that it owns this process.
+ * the host-named cache containing its module; a source checkout is attributed
+ * by the running binary identity (see {@link hostCacheDirFromProcess}). Merely
+ * having another host's config directory installed is not evidence that it
+ * owns this process.
  */
-export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.url) {
+export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.url, processIdentity = {}) {
     const mimoHome = env.MIMOCODE_HOME;
     if (mimoHome && mimoHome.length > 0) {
         return path.join(mimoHome, "cache");
@@ -74,12 +111,17 @@ export function resolveHostCacheDir(env = process.env, moduleUrl = import.meta.u
         modulePath = undefined;
     }
     if (modulePath) {
-        for (const host of ["mimocode", "kilo", "opencode"]) {
+        for (const host of HOST_CACHE_DIRS) {
             const root = path.resolve(cacheHome, host);
             if (modulePath === root || modulePath.startsWith(`${root}${path.sep}`))
                 return root;
         }
     }
+    // Source checkout: the module path can't name the host, but the binary that
+    // loaded us can (running as `mimo` / `kilocode` / `opencode`).
+    const host = hostCacheDirFromProcess(processIdentity.argv ?? process.argv, processIdentity.execPath ?? process.execPath);
+    if (host)
+        return path.join(cacheHome, host);
     return path.join(cacheHome, "opencode");
 }
 /**

package/dist/language-model.d.ts

@@ -85,7 +85,7 @@ export declare function buildOpenCodeInteractionGuidance(tools: OpencodeToolDef[
 export declare function estimateTokens(chars: number): number;
 /** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
 export declare function estimatePromptTokens(prompt: LanguageModelV3CallOptions["prompt"]): number;
-/** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+/** Preserve exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
 export declare function cursorTurnEndedProviderMetadata(te: Record<string, unknown>): {
     cursor: {
         usageVersion: number;

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, 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";
@@ -464,13 +464,19 @@ export async function pumpWithRecovery(input) {
             const delayMs = retryDelayMs(failure, attempt + 1, retryPolicy);
             trace(`Run retry backoff: attempt=${attempt + 1}/${maxRecoveries} delayMs=${delayMs}`);
             await sleepForRetry(delayMs, input.abortSignal);
-            session = await input.recover(checkpoint
+            const recovery = checkpoint
                 ? {
                     kind: "resume",
                     conversationId: pumpedSession.conversationId,
                     checkpoint: Uint8Array.from(checkpoint),
                 }
-                : { kind: "rebase" });
+                : { kind: "rebase" };
+            session = await input.recover(recovery);
+            if (recovery.kind === "resume") {
+                session.hadToolCallBoundary = pumpedSession.hadToolCallBoundary;
+                session.usageEstimate = { ...pumpedSession.usageEstimate };
+                session.editToolCalls = new Map(pumpedSession.editToolCalls);
+            }
             input.onSession?.(session);
         }
         finally {
@@ -693,6 +699,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         frames: stream.frames()[Symbol.asyncIterator](),
         pending: new Map(),
         displayToolCalls: new Map(),
+        editToolCalls: new Map(),
         nextBridgedExecId: 900_000,
         blobs: new Map(),
         toolDescriptors,
@@ -1082,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);
@@ -1145,8 +1160,12 @@ export async function pump(session, controller, ids, abortSignal) {
     };
     const emitFinish = (te, reason) => {
         closeOpenSpans();
-        if (te) {
-            // Authoritative TurnEnded counts — replace the running estimate.
+        // TurnEnded is request-local only when this Run did not previously stop at
+        // a tool boundary. On a held multi-step Run Cursor aggregates every model
+        // invocation into these counters; treating that billed total as the final
+        // request's prompt size makes OpenCode compact after ordinary tasks.
+        const cumulativeTurnEnded = !!te && session.hadToolCallBoundary === true;
+        if (te && !cumulativeTurnEnded) {
             session.usageEstimate = {
                 inputTokens: turnEndedCounter(te, "input_tokens"),
                 outputTokens: turnEndedCounter(te, "output_tokens"),
@@ -1156,9 +1175,11 @@ export async function pump(session, controller, ids, abortSignal) {
             };
         }
         const est = session.usageEstimate;
-        const usage = te
+        const usage = te && !cumulativeTurnEnded
             ? buildLanguageModelV3UsageFromTurnEnded(te)
             : buildLanguageModelV3UsageFromEstimate(est, promptTokens, requestUsage.outputChars, estimateTokens);
+        if (!te)
+            session.hadToolCallBoundary = true;
         const providerMetadata = te ? cursorTurnEndedProviderMetadata(te) : undefined;
         const reasonLabel = typeof reason === "object" && reason && "unified" in reason
             ? String(reason.unified ?? "unknown")
@@ -1169,9 +1190,11 @@ export async function pump(session, controller, ids, abortSignal) {
             `v3In=${inTotal} v3Out=${outTotal} ` +
             `v3CacheRead=${usage.inputTokens?.cacheRead ?? 0} v3CacheWrite=${usage.inputTokens?.cacheWrite ?? 0} ` +
             `v3Reasoning=${usage.outputTokens?.reasoning ?? 0} ` +
-            `rawIn=${est.inputTokens} rawOut=${est.outputTokens} ` +
-            `rawCacheRead=${est.cacheRead} rawCacheWrite=${est.cacheWrite} ` +
-            `source=${te ? "turn_ended" : "estimate"}`);
+            `rawIn=${te ? turnEndedCounter(te, "input_tokens") : est.inputTokens} ` +
+            `rawOut=${te ? turnEndedCounter(te, "output_tokens") : est.outputTokens} ` +
+            `rawCacheRead=${te ? turnEndedCounter(te, "cache_read") : est.cacheRead} ` +
+            `rawCacheWrite=${te ? turnEndedCounter(te, "cache_write") : est.cacheWrite} ` +
+            `source=${te ? (cumulativeTurnEnded ? "estimate-cumulative-turn-ended" : "turn_ended") : "estimate"}`);
         safeEnqueue({
             type: "finish",
             usage,
@@ -1327,6 +1350,15 @@ export async function pump(session, controller, ids, abortSignal) {
                 if (callId && toolCall) {
                     session.displayToolCalls.set(callId, toolCall);
                     const variant = Object.keys(toolCall).find((k) => k.endsWith("_tool_call")) ?? "?";
+                    const display = parseDisplayToolCall(callId, toolCall);
+                    const editPath = display?.variant === "edit_tool_call"
+                        && typeof display.args.path === "string"
+                        ? display.args.path
+                        : undefined;
+                    if (editPath) {
+                        const editToolCalls = session.editToolCalls ?? (session.editToolCalls = new Map());
+                        editToolCalls.set(callId, { path: editPath });
+                    }
                     const callIdLog = callId.replace(/\r?\n/g, "\\n");
                     let wireFields = "";
                     if (variant === "?") {
@@ -1341,6 +1373,8 @@ export async function pump(session, controller, ids, abortSignal) {
             else if (iu?.tool_call_completed) {
                 const completed = iu.tool_call_completed;
                 const callId = typeof completed.call_id === "string" ? completed.call_id : "";
+                if (callId)
+                    session.editToolCalls?.delete(callId);
                 // If exec already claimed this call_id, display map entry is gone — skip.
                 if (!callId || !session.displayToolCalls.has(callId)) {
                     if (callId) {
@@ -1434,8 +1468,36 @@ 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);
                     const parsed = parseExecServerMessage(esm);
                     if (parsed) {
                         const executableToolName = resolveCustomWebToolAlias(parsed.toolName, session.toolAliases);
@@ -1444,12 +1506,24 @@ export async function pump(session, controller, ids, abortSignal) {
                             parsed.toolName = executableToolName;
                         }
                         remapNativeSubagentForCatalog(parsed, advertisedToolNameSet, session.subagentCatalog);
+                        const editCall = displayCallId
+                            ? session.editToolCalls?.get(displayCallId)
+                            : undefined;
+                        if (editCall) {
+                            const remapped = remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNameSet, editCall.path, workspaceRootFromRequestContext(session.requestContext));
+                            if (parsed.resultField === "write_result" && displayCallId) {
+                                session.editToolCalls?.delete(displayCallId);
+                            }
+                            if (remapped) {
+                                trace(`exec: preserved edit intent callId=${displayCallId} ` +
+                                    `path=${JSON.stringify(editCall.path)}`);
+                            }
+                        }
                         // Hosts that advertise `apply_patch` in place of `edit`/`write` (see
                         // protocol/apply-patch.ts) still receive Cursor's native write/edit
                         // exec requests. Translate before the unavailable-tool check below.
                         remapEditToolsForCatalog(parsed, advertisedToolNameSet, workspaceRootFromRequestContext(session.requestContext));
                     }
-                    const displayCallId = extractExecDisplayCallId(esm);
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
                     if (parsed) {
                         if (parsed.localError) {
@@ -1720,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(", ");
@@ -1770,7 +1850,7 @@ export function estimatePromptTokens(prompt) {
         .join("\n");
     return estimateTokens(serializedContent.length);
 }
-/** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+/** Preserve exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
 export function cursorTurnEndedProviderMetadata(te) {
     return {
         cursor: {

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 = {
@@ -87,6 +89,14 @@ export declare function resolveCursorSubagentType(subagentType: string, catalog?
 export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
 /** Resolve a native Cursor subagent request to this turn's executor and catalog. */
 export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
+/**
+ * Preserve a legacy Cursor edit's intent when its internal executor follows
+ * `edit_tool_call` with a whole-file `write_args` request.
+ *
+ * The result field intentionally remains `write_result`: that is the response
+ * Cursor is awaiting even though OpenCode executes the mutation via `edit`.
+ */
+export declare function remapCorrelatedEditWriteForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, editPath: string, workspaceRoot?: string): boolean;
 /**
  * Express a native Cursor write/edit as `apply_patch` when the host swapped the
  * edit-tool family out from under us.
@@ -131,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;
 /**
@@ -245,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
@@ -483,6 +506,125 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
 }
 /** Matches Cursor's own pre-write read threshold (`local-exec` 52428800). */
 const MAX_EDIT_SOURCE_BYTES = 50 * 1024 * 1024;
+/** Return the number of non-overlapping occurrences, stopping after ambiguity. */
+function replacementOccurrenceCount(source, needle) {
+    if (!needle)
+        return 0;
+    const first = source.indexOf(needle);
+    if (first === -1)
+        return 0;
+    return source.indexOf(needle, first + needle.length) === -1 ? 1 : 2;
+}
+function previousLineStart(source, start) {
+    if (start <= 0)
+        return 0;
+    const before = source[start - 1] === "\n" ? start - 2 : start - 1;
+    return source.lastIndexOf("\n", before) + 1;
+}
+function followingLineEnd(source, end) {
+    if (end >= source.length)
+        return source.length;
+    const newline = source.indexOf("\n", end);
+    return newline === -1 ? source.length : newline + 1;
+}
+/**
+ * Collapse a whole-file replacement into one unique, line-bounded substring
+ * edit. Cursor's legacy edit executor computes a complete new file internally;
+ * OpenCode's `edit` tool instead wants old/new substrings.
+ */
+function planWholeFileEdit(source, target) {
+    if (!source || source === target)
+        return undefined;
+    let prefix = 0;
+    const shared = Math.min(source.length, target.length);
+    while (prefix < shared && source[prefix] === target[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < source.length - prefix
+        && suffix < target.length - prefix
+        && source[source.length - suffix - 1] === target[target.length - suffix - 1])
+        suffix++;
+    const sourceChangeEnd = source.length - suffix;
+    const targetChangeEnd = target.length - suffix;
+    let start = prefix === 0 ? 0 : source.lastIndexOf("\n", prefix - 1) + 1;
+    let end = sourceChangeEnd >= source.length
+        ? source.length
+        : followingLineEnd(source, sourceChangeEnd);
+    // A pure insertion can initially select no source text. Include an adjacent
+    // line because OpenCode edit deliberately rejects an empty oldString.
+    if (start === end) {
+        if (start > 0)
+            start = previousLineStart(source, start);
+        else
+            end = followingLineEnd(source, end);
+    }
+    const replacement = () => ({
+        oldString: source.slice(start, end),
+        newString: source.slice(start, prefix)
+            + target.slice(prefix, targetChangeEnd)
+            + source.slice(sourceChangeEnd, end),
+    });
+    let result = replacement();
+    while (replacementOccurrenceCount(source, result.oldString) !== 1) {
+        const priorStart = start;
+        const priorEnd = end;
+        if (start > 0)
+            start = previousLineStart(source, start);
+        if (end < source.length)
+            end = followingLineEnd(source, end);
+        if (start === priorStart && end === priorEnd)
+            return undefined;
+        result = replacement();
+    }
+    return result;
+}
+/**
+ * Preserve a legacy Cursor edit's intent when its internal executor follows
+ * `edit_tool_call` with a whole-file `write_args` request.
+ *
+ * The result field intentionally remains `write_result`: that is the response
+ * Cursor is awaiting even though OpenCode executes the mutation via `edit`.
+ */
+export function remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNames, editPath, workspaceRoot) {
+    if (parsed.resultField !== "write_result" || parsed.toolName !== "write")
+        return false;
+    const advertised = new Set(advertisedToolNames);
+    if (!advertised.has("edit") && !advertised.has(APPLY_PATCH_TOOL))
+        return false;
+    const filePath = str(parsed.args.filePath);
+    const content = stringValue(parsed.args.content);
+    if (!filePath || content === undefined || !editPath)
+        return false;
+    const root = workspaceRoot ?? process.cwd();
+    const absolute = path.resolve(root, filePath);
+    if (absolute !== path.resolve(root, editPath))
+        return false;
+    let source;
+    try {
+        const stat = fs.statSync(absolute);
+        if (!stat.isFile() || stat.size > MAX_EDIT_SOURCE_BYTES)
+            return false;
+        if (Buffer.byteLength(content, "utf8") > MAX_EDIT_SOURCE_BYTES)
+            return false;
+        source = fs.readFileSync(absolute, "utf8");
+    }
+    catch {
+        // Missing targets are creations and must stay writes. Other read failures
+        // also fall back to the original host permission path without guessing.
+        return false;
+    }
+    const replacement = planWholeFileEdit(source, content);
+    if (!replacement)
+        return false;
+    parsed.toolName = "edit";
+    parsed.args = {
+        filePath,
+        oldString: replacement.oldString,
+        newString: replacement.newString,
+    };
+    parsed.resultMetadata = { ...parsed.resultMetadata, path: filePath };
+    return true;
+}
 /**
  * Express a native Cursor write/edit as `apply_patch` when the host swapped the
  * edit-tool family out from under us.
@@ -981,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);
@@ -1202,9 +1366,9 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             // Cursor's native read_args lands here; `mcp_args` reads land in
             // mcp_result. Live captures show gpt-5.4-mini and grok-4.5 both use the
             // native channel, so this is the path that matters in practice.
-            const content = unwrapReadOutput(output);
             const statPath = extractPathTag(output) ?? readPath;
             const outputMetadata = parseOpenCodeReadMetadata(output);
+            const content = restoreCompleteReadTerminator(unwrapReadOutput(output), statPath, outputMetadata, resultMetadata, resultRoot);
             const totalLines = outputMetadata.totalLines ?? readFileLineCount(statPath) ?? countLines(content);
             const rangeApplied = readRangeApplied(resultMetadata, totalLines);
             // `truncated` alone is not enough: it is set here, and models still assert
@@ -1452,6 +1616,53 @@ function parseOpenCodeReadMetadata(output) {
         return { totalLines: Number(complete[1]) };
     return {};
 }
+/**
+ * OpenCode's numbered read envelope cannot represent the terminator after the
+ * final line. Cursor's legacy edit executor performs exact replacement against
+ * this content, so dropping a real LF/CRLF makes otherwise-valid edits fail and
+ * encourages a whole-file rewrite. Restore only that final terminator for an
+ * unbounded, confirmed-complete read; paged/capped reads stay untouched.
+ */
+function restoreCompleteReadTerminator(content, readPath, metadata, resultMetadata, workspaceRoot) {
+    if (!readPath
+        || metadata.totalLines === undefined
+        || metadata.startLine !== undefined
+        || metadata.endLine !== undefined
+        || num(resultMetadata?.offset) !== undefined
+        || num(resultMetadata?.limit) !== undefined
+        || content.endsWith("\n"))
+        return content;
+    const absolute = path.isAbsolute(readPath)
+        ? readPath
+        : path.resolve(workspaceRoot ?? process.cwd(), readPath);
+    let fd;
+    try {
+        fd = fs.openSync(absolute, "r");
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return content;
+        const tail = Buffer.alloc(Math.min(2, size));
+        fs.readSync(fd, tail, 0, tail.length, size - tail.length);
+        if (tail.length >= 2 && tail[tail.length - 2] === 0x0d && tail[tail.length - 1] === 0x0a) {
+            return `${content}\r\n`;
+        }
+        if (tail[tail.length - 1] === 0x0a)
+            return `${content}\n`;
+    }
+    catch {
+        // The host read result remains authoritative when the local path cannot be
+        // inspected (deleted/raced/permission changed after the tool completed).
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already closed */ }
+        }
+    }
+    return content;
+}
 /**
  * OpenCode's `read` caps output at 50 KB (`tool/read.ts` MAX_BYTES = 50 * 1024)
  * and cuts on a whole-line boundary, then appends
@@ -1750,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/dist/session.d.ts

@@ -112,6 +112,14 @@ export type CursorSession = {
      * or when we bridge the completed display call into an OpenCode tool-call.
      */
     displayToolCalls: Map<string, Record<string, unknown>>;
+    /**
+     * Legacy edit calls whose authoritative exec path is still in progress.
+     * Cursor implements these as read -> whole-file write; retaining the path
+     * lets the pump expose the final mutation to OpenCode as a targeted edit.
+     */
+    editToolCalls?: Map<string, {
+        path: string;
+    }>;
     /** Monotonic synthetic exec ids for bridged (display-only) OpenCode tool calls. */
     nextBridgedExecId: number;
     /** KV blob store: blob_id (hex) → data, for Cursor's out-of-band payload channel. */
@@ -132,8 +140,8 @@ export type CursorSession = {
     allowTools: boolean;
     /**
      * Best-effort token usage for this held-open Run. Updated from text/tool
-     * activity and replaced by TurnEnded when the turn completes. Emitted on
-     * tool-calls finishes so OpenCode does not store all-zero usage mid-loop.
+     * activity and replaced by TurnEnded only for a single-step Run. Emitted on
+     * tool-call finishes so OpenCode does not store all-zero usage mid-loop.
      */
     usageEstimate: {
         inputTokens: number;
@@ -142,6 +150,13 @@ export type CursorSession = {
         cacheWrite: number;
         reasoningTokens: number;
     };
+    /**
+     * True after this held Run has already crossed an OpenCode tool-call
+     * boundary. Cursor's eventual TurnEnded counters then cover the whole Run,
+     * not only the final doStream request, so they cannot be used as that
+     * request's context usage.
+     */
+    hadToolCallBoundary?: boolean;
     /**
      * True while a doStream pull() is actively reading this session's frames.
      * Prevents a late cancel/abort from a prior ReadableStream from destroying

package/dist/usage.d.ts

@@ -2,8 +2,9 @@ import type { LanguageModelV3Usage } from "@ai-sdk/provider";
 /** Non-negative integer counter from a Cursor `turn_ended` field. */
 export declare function turnEndedCounter(te: Record<string, unknown>, key: string): number;
 /**
- * Map authoritative Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
- * flatten via input total = noCache + cacheRead + cacheWrite).
+ * Map request-local Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
+ * flatten via input total = noCache + cacheRead + cacheWrite). Only use this
+ * for a Run with no prior tool boundary; multi-step TurnEnded is cumulative.
  *
  * Contract: `input_tokens` is non-cached input; cache fields are separate.
  * Cursor's agent wire currently sends `cache_write=0` even when later turns
@@ -18,7 +19,15 @@ export type CursorUsageEstimate = {
     cacheWrite: number;
     reasoningTokens: number;
 };
-/** Mid-turn finish (e.g. tool-calls) before `turn_ended` — keep non-zero estimates. */
+/**
+ * Request-local usage for a held Cursor Run.
+ *
+ * `est.inputTokens` tracks the seed plus delivered tool results, while
+ * `est.outputTokens` accumulates model output across earlier tool boundaries.
+ * Move prior output into the current input estimate and report only this
+ * doStream request's output. Cache counters are intentionally absent: the
+ * only counters Cursor exposes at TurnEnded are cumulative for the whole Run.
+ */
 export declare function buildLanguageModelV3UsageFromEstimate(est: CursorUsageEstimate, promptTokens: number, outputChars: number, estimateCharsToTokens: (chars: number) => number): LanguageModelV3Usage;
 /** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
 export declare function kiloShapedUsageFromV3(usage: LanguageModelV3Usage): {

package/dist/usage.js

@@ -6,8 +6,9 @@ export function turnEndedCounter(te, key) {
         : 0;
 }
 /**
- * Map authoritative Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
- * flatten via input total = noCache + cacheRead + cacheWrite).
+ * Map request-local Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
+ * flatten via input total = noCache + cacheRead + cacheWrite). Only use this
+ * for a Run with no prior tool boundary; multi-step TurnEnded is cumulative.
  *
  * Contract: `input_tokens` is non-cached input; cache fields are separate.
  * Cursor's agent wire currently sends `cache_write=0` even when later turns
@@ -34,27 +35,30 @@ export function buildLanguageModelV3UsageFromTurnEnded(te) {
         },
     };
 }
-/** Mid-turn finish (e.g. tool-calls) before `turn_ended` — keep non-zero estimates. */
+/**
+ * Request-local usage for a held Cursor Run.
+ *
+ * `est.inputTokens` tracks the seed plus delivered tool results, while
+ * `est.outputTokens` accumulates model output across earlier tool boundaries.
+ * Move prior output into the current input estimate and report only this
+ * doStream request's output. Cache counters are intentionally absent: the
+ * only counters Cursor exposes at TurnEnded are cumulative for the whole Run.
+ */
 export function buildLanguageModelV3UsageFromEstimate(est, promptTokens, outputChars, estimateCharsToTokens) {
-    const hasInputBreakdown = est.cacheRead > 0 || est.cacheWrite > 0 || est.inputTokens > 0;
-    const inputNoCache = hasInputBreakdown ? est.inputTokens : promptTokens;
-    const cacheRead = est.cacheRead;
-    const cacheWrite = est.cacheWrite;
-    const outputFromChars = estimateCharsToTokens(outputChars);
-    const outputText = est.outputTokens > 0 ? est.outputTokens : outputFromChars;
-    const reasoning = est.reasoningTokens;
-    const outputTotal = outputText + reasoning;
+    const outputText = estimateCharsToTokens(outputChars);
+    const priorOutput = Math.max(0, est.outputTokens - outputText);
+    const inputNoCache = Math.max(promptTokens, est.inputTokens + priorOutput);
     return {
         inputTokens: {
-            total: inputNoCache + cacheRead + cacheWrite,
+            total: inputNoCache,
             noCache: inputNoCache,
-            cacheRead,
-            cacheWrite,
+            cacheRead: 0,
+            cacheWrite: 0,
         },
         outputTokens: {
-            total: outputTotal,
+            total: outputText,
             text: outputText,
-            reasoning: reasoning > 0 ? reasoning : undefined,
+            reasoning: undefined,
         },
     };
 }

package/package.json

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