cursor-opencode-provider 0.2.6 → 0.2.8

package/dist/deadline.js

@@ -0,0 +1,25 @@
+/**
+ * Bound a complete async operation, not only fetch(). Response body readers can
+ * ignore abort signals, so Promise.race remains the authoritative deadline.
+ *
+ * Rejects with `timeoutError()` before aborting so callers observe the domain
+ * timeout error rather than a generic AbortError.
+ */
+export async function withAbortDeadline(timeoutMs, timeoutError, run) {
+    const controller = new AbortController();
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(timeoutError());
+            controller.abort();
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([run(controller.signal), deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/debug.d.ts

@@ -1,3 +1,5 @@
+/** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
+export declare function isDebugEnabled(): boolean;
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export declare function resolveDebugLogPath(): string;
 /**
@@ -8,3 +10,8 @@ export declare function ensureSecureDebugLog(filePath: string, options?: {
     secureParent?: boolean;
 }): void;
 export declare function trace(msg: string): void;
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export declare function traceRequestContextPaths(label: string, requestContext: Record<string, unknown> | undefined): void;

package/dist/debug.js

@@ -10,6 +10,11 @@ const DEBUG_ENABLED = process.env.CURSOR_PROVIDER_DEBUG === "1" ||
 let _traceInitialized = false;
 let _debugFile;
 let _debugFileUsesManagedDirectory = false;
+let _announcedLogPath = false;
+/** Whether `CURSOR_PROVIDER_DEBUG` is enabled for this process. */
+export function isDebugEnabled() {
+    return DEBUG_ENABLED;
+}
 /** Resolve the debug log path (env override or per-uid tmpdir default). */
 export function resolveDebugLogPath() {
     if (process.env.CURSOR_PROVIDER_DEBUG_FILE) {
@@ -41,6 +46,18 @@ export function ensureSecureDebugLog(filePath, options = {}) {
     fs.writeFileSync(filePath, "", { mode: 0o600 });
     fs.chmodSync(filePath, 0o600);
 }
+function announceLogPath(filePath) {
+    if (_announcedLogPath)
+        return;
+    _announcedLogPath = true;
+    try {
+        // Visible in the OpenCode / terminal session so operators know where to look.
+        console.error(`[cursor-provider] CURSOR_PROVIDER_DEBUG logging to ${filePath}`);
+    }
+    catch {
+        /* ignore */
+    }
+}
 export function trace(msg) {
     if (!DEBUG_ENABLED)
         return;
@@ -53,6 +70,10 @@ export function trace(msg) {
             ensureSecureDebugLog(_debugFile, { secureParent: _debugFileUsesManagedDirectory });
             fs.writeFileSync(_debugFile, `--- cursor-provider debug (pid ${process.pid}) ${new Date().toISOString()} ---\n`, { mode: 0o600 });
             _traceInitialized = true;
+            announceLogPath(_debugFile);
+            fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] debug: enabled file=${_debugFile} ` +
+                `xdg_cache_home=${process.env.XDG_CACHE_HOME ?? "(unset)"} ` +
+                `cwd=${process.cwd()}\n`);
         }
         fs.appendFileSync(_debugFile, `[${new Date().toISOString()}] ${msg}\n`);
     }
@@ -60,3 +81,24 @@ export function trace(msg) {
         /* ignore */
     }
 }
+/**
+ * Compact path-advertising summary for RequestContext troubleshooting.
+ * Safe: no tokens / file contents — only workspace vs metadata roots.
+ */
+export function traceRequestContextPaths(label, requestContext) {
+    if (!DEBUG_ENABLED)
+        return;
+    const env = requestContext?.env && typeof requestContext.env === "object"
+        ? requestContext.env
+        : undefined;
+    const mcp = requestContext?.mcp_file_system_options &&
+        typeof requestContext.mcp_file_system_options === "object"
+        ? requestContext.mcp_file_system_options
+        : undefined;
+    trace(`${label}: workspace_paths=${JSON.stringify(env?.workspace_paths ?? null)} ` +
+        `process_working_directory=${JSON.stringify(env?.process_working_directory ?? null)} ` +
+        `project_folder=${JSON.stringify(env?.project_folder ?? null)} ` +
+        `terminals_folder=${JSON.stringify(env?.terminals_folder ?? null)} ` +
+        `agent_transcripts_folder=${JSON.stringify(env?.agent_transcripts_folder ?? null)} ` +
+        `workspace_project_dir=${JSON.stringify(mcp?.workspace_project_dir ?? null)}`);
+}

package/dist/index.d.ts

@@ -23,6 +23,12 @@ export type CreateCursorOptions = {
     telemetryEnabled?: boolean;
     /** OpenCode project / worktree directory for request_context collectors. */
     workspaceRoot?: string;
+    /**
+     * Host cache root for Cursor project metadata + model/version caches.
+     * Prefer the host's Path.cache (Effect v2) when available; otherwise the
+     * provider resolves OpenCode / MiMo / Kilo XDG cache dirs automatically.
+     */
+    cacheDir?: string;
     /** Held-stream policy. Defaults: heartbeat 5s, semantic idle 120s, tool inactivity 10m. */
     continuation?: CursorContinuationOptions;
     /** Fresh-turn retry policy. Defaults: 3 attempts, 500ms base, 8000ms cap. */

package/dist/language-model.js

@@ -2,15 +2,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } from "./transport/connect.js";
-import { trace } from "./debug.js";
+import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
 import { decodeMessage } from "./protocol/messages.js";
-import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, } from "./protocol/tools.js";
+import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, resolveCustomWebToolAlias, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_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";
-import { handleInteractionQuery, inspectInteractionQueryWire } from "./protocol/interactions.js";
+import { handleInteractionQuery } from "./protocol/interactions.js";
 import { getCheckpoint, setCheckpoint } from "./protocol/checkpoint.js";
 import { conversationBlobCount } from "./protocol/blob-store.js";
 import { bindConversationId, } from "./protocol/conversation-bind.js";
@@ -18,10 +18,13 @@ import { resolveContinuationPolicy, sessionManager, } from "./session.js";
 import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, CursorProviderError, CursorRetryExhaustedError, CursorServerError, CursorTransportError, isTransientGrpcStatus, retrySuppressedError, toCursorProviderError, } from "./errors.js";
 import { readCache, cacheFilePath, resolveVariantParameters, paramsImplyMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.js";
 import { buildRequestContext } from "./context/build.js";
-import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { workspaceRootFromRequestContext } from "./context/env.js";
+import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION } from "./shared.js";
 import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
+import { analyzeReplayFrame, AttemptReplaySafety } from "./replay-safety.js";
+import { readAllFieldsStrict } from "./protocol/struct.js";
 let _availableModels;
 // mtime of the cache file the last time we loaded it. Compared on each call
 // so discoverModels' background refresh is picked up without a process restart.
@@ -43,6 +46,28 @@ const DEFAULT_RETRY_POLICY = {
 };
 const MAX_RETRY_ATTEMPTS = 10;
 const MAX_RETRY_DELAY_MS = 30_000;
+const RUN_REQUEST_DECODE_FAILED = "CURSOR_RUN_REQUEST_DECODE_FAILED";
+const RUN_REQUEST_UNSUPPORTED = "CURSOR_RUN_REQUEST_UNSUPPORTED";
+const RUN_REPLY_FAILED = "CURSOR_RUN_REPLY_FAILED";
+const RESPONSE_REQUIRED_CHANNEL_BY_FIELD = new Map([
+    [2, "exec"],
+    [4, "kv"],
+    [7, "interaction"],
+]);
+function responseRequiredChannel(payload) {
+    const fields = readAllFieldsStrict(payload);
+    if (fields) {
+        const channels = fields
+            .map((field) => RESPONSE_REQUIRED_CHANNEL_BY_FIELD.get(field.fn))
+            .filter((channel) => !!channel);
+        if (channels.length > 1)
+            return "multiple";
+        return channels[0];
+    }
+    // Request tags are single-byte because all must-reply top-level fields are <16.
+    const tag = payload[0];
+    return tag !== undefined ? RESPONSE_REQUIRED_CHANNEL_BY_FIELD.get(tag >> 3) : undefined;
+}
 function retryInteger(name, value, fallback) {
     const resolved = value === undefined ? fallback : value;
     if (typeof resolved !== "number" || !Number.isSafeInteger(resolved) || resolved <= 0) {
@@ -224,6 +249,9 @@ function rememberPostCompactionRebase(sessionKey) {
     }
 }
 export function createCursorLanguageModel(modelId, providerId, options) {
+    // Host Path.cache / explicit override wins over XDG heuristics for this process.
+    if (options.cacheDir)
+        setHostCacheDirOverride(options.cacheDir);
     return {
         specificationVersion: "v3",
         provider: providerId,
@@ -426,6 +454,14 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         isCompaction,
     });
     const tools = toolState.advertisedTools;
+    const webToolAliases = buildCustomWebToolAliases(tools);
+    const cursorTools = webToolAliases.advertisedTools;
+    for (const [alias, candidates] of webToolAliases.ambiguous) {
+        trace(`web tool alias skipped: alias=${alias} ambiguous=[${candidates.join(",")}]`);
+    }
+    for (const [alias, original] of webToolAliases.aliases) {
+        trace(`web tool alias: ${alias} -> ${original}`);
+    }
     const allowTools = toolState.allowTools;
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
     const recovery = startOptions?.recovery;
@@ -447,7 +483,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         : (extractUserText([...prompt].reverse().find((m) => m.role === "user")) || ".");
     const workspaceRoot = path.resolve(options.workspaceRoot || process.cwd());
     const baseSystemPrompt = extractSystemPrompt(prompt);
-    const interactionGuidance = buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceRoot);
+    const interactionGuidance = buildOpenCodeInteractionGuidance(cursorTools, isCompaction, workspaceRoot);
     const systemPrompt = interactionGuidance
         ? [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n")
         : baseSystemPrompt;
@@ -489,7 +525,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         baseURL: agentBaseUrl,
         headers: options.headers,
     });
-    const requestContext = await buildRequestContext({ workspaceRoot, tools });
+    const requestContext = await buildRequestContext({ workspaceRoot, tools: cursorTools });
     // Resolve descriptors once from the merged OpenCode config so MCP identity is
     // consistent across AgentRunRequest and both request_context reply paths.
     const toolDescriptors = Array.isArray(requestContext.tools)
@@ -509,7 +545,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         conversationState,
         parameterValues,
         maxMode,
-        tools,
+        tools: cursorTools,
         toolDescriptors,
         requestContext,
         action: resuming ? "resume" : "user",
@@ -566,6 +602,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         nextBridgedExecId: 900_000,
         blobs: new Map(),
         toolDescriptors,
+        toolAliases: webToolAliases.aliases,
         requestContext,
         allowTools,
         usageEstimate,
@@ -810,11 +847,17 @@ export async function pump(session, controller, ids, abortSignal) {
     const { textId, reasoningId } = ids;
     const promptTokens = ids.promptTokens ?? 0;
     const advertisedToolNames = advertisedToolNamesFromDescriptors(session.toolDescriptors);
-    const advertisedToolNameSet = new Set(advertisedToolNames);
+    const advertisedToolNameSet = new Set(advertisedToolNames.map((name) => resolveCustomWebToolAlias(name, session.toolAliases)));
     let textStarted = false;
     let reasoningStarted = false;
     const requestUsage = ids.requestUsage ?? { outputChars: 0 };
-    let replaySafe = true;
+    const replaySafety = new AttemptReplaySafety(session.sessionId);
+    const failRunProtocol = (message, code) => {
+        replaySafety.markBarrier("unknown-or-malformed-frame");
+        const error = new CursorProtocolError(message, { code });
+        sessionManager.close(session, "remote-error", error);
+        throw error;
+    };
     // OpenCode cancels the ReadableStream between turns (see the cancel handler
     // in doStreamImpl). The frames iterator can still yield a final `done` after
     // the cancel lands — controller.enqueue on a cancelled controller throws.
@@ -889,9 +932,9 @@ export async function pump(session, controller, ids, abortSignal) {
         const editPath = typeof display.args.path === "string" ? display.args.path : "";
         if (!requestedPath || !editPath)
             return false;
-        const workspaceRoot = typeof session.requestContext.workspace_project_dir === "string"
-            ? session.requestContext.workspace_project_dir
-            : process.cwd();
+        // Prefer env.workspace_paths — project_folder / workspace_project_dir are
+        // Cursor metadata roots under <host-cache>/projects/, not the git tree.
+        const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
         const resolvePath = (value) => path.resolve(workspaceRoot, value);
         const absolutePath = resolvePath(requestedPath);
         if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
@@ -929,7 +972,7 @@ export async function pump(session, controller, ids, abortSignal) {
     const emitText = (text) => {
         if (!text)
             return;
-        replaySafe = false;
+        replaySafety.markBarrier("visible-text");
         // Close reasoning before text (hosts expect reasoning-end before text-start).
         if (reasoningStarted && !textStarted) {
             safeEnqueue({ type: "reasoning-end", id: reasoningId });
@@ -947,7 +990,7 @@ export async function pump(session, controller, ids, abortSignal) {
     const emitReasoning = (text) => {
         if (!text)
             return;
-        replaySafe = false;
+        replaySafety.markBarrier("visible-reasoning");
         if (!reasoningStarted) {
             safeEnqueue({ type: "reasoning-start", id: reasoningId });
             reasoningStarted = true;
@@ -1025,15 +1068,13 @@ export async function pump(session, controller, ids, abortSignal) {
             const failure = error instanceof CursorProviderError
                 ? error
                 : new CursorRunInterruptedError(`Cursor Run frame stream interrupted: ${error.message}`, { cause: error });
-            failure.replaySafe = replaySafe && failure.replaySafe;
-            throw failure;
+            throw replaySafety.applyTo(failure);
         }
         if (next.done) {
             closeOpenSpans();
             trace("pump: frames iterator ended before turn_ended");
             const failure = new CursorRunInterruptedError();
-            failure.replaySafe = replaySafe;
-            throw failure;
+            throw replaySafety.applyTo(failure);
         }
         const frame = next.value;
         if (frame.flags & 0x02) {
@@ -1045,14 +1086,15 @@ export async function pump(session, controller, ids, abortSignal) {
                 try {
                     payload = new TextDecoder().decode(decodeFramePayload(frame));
                 }
-                catch { /* not decodable */ }
+                catch {
+                    replaySafety.markBarrier("unknown-or-malformed-frame");
+                }
             }
             closeOpenSpans();
             const failure = payload
                 ? connectFrameError(payload)
                 : new CursorRunInterruptedError();
-            failure.replaySafe = replaySafe && failure.replaySafe;
-            throw failure;
+            throw replaySafety.applyTo(failure);
         }
         // decodeFramePayload can throw on a corrupt gzip payload (gunzipSync).
         // Skip the frame rather than abort the whole turn.
@@ -1061,6 +1103,7 @@ export async function pump(session, controller, ids, abortSignal) {
             payload = decodeFramePayload(frame);
         }
         catch (e) {
+            replaySafety.markBarrier("unknown-or-malformed-frame");
             trace(`gunzip FAILED (skipping frame): flags=0x${frame.flags.toString(16)} len=${frame.payload.length} err=${e.message}`);
             continue;
         }
@@ -1068,39 +1111,46 @@ export async function pump(session, controller, ids, abortSignal) {
         try {
             asm = decodeMessage("AgentServerMessage", payload);
         }
-        catch (e) {
+        catch {
             // A single malformed/truncated frame must not abort the whole turn
             // (protobufjs throws "index out of range: …" on length overruns). Log it
             // and keep pumping.
-            replaySafe = false;
-            const preview = Array.from(payload.subarray(0, 32))
-                .map((x) => x.toString(16).padStart(2, "0"))
-                .join("");
-            trace(`decode FAILED (skipping): flags=0x${frame.flags.toString(16)} len=${payload.length} ` +
-                `topField=${payload.length ? payload[0] >> 3 : "-"} err=${e.message} hex=${preview}`);
+            replaySafety.markBarrier("unknown-or-malformed-frame");
+            const channel = responseRequiredChannel(payload);
+            if (channel) {
+                failRunProtocol(`Cursor ${channel} request could not be decoded`, RUN_REQUEST_DECODE_FAILED);
+            }
+            trace(`decode FAILED (skipping non-request frame): flags=0x${frame.flags.toString(16)} len=${payload.length}`);
             continue;
         }
         const iu = asm.interaction_update;
         const esm = asm.exec_server_message;
         const kv = asm.kv_server_message;
+        const execControl = asm.exec_server_control_message;
         const interactionQuery = asm.interaction_query;
         const checkpointRaw = asm.conversation_checkpoint_update;
         const topField = payload.length > 0 ? payload[0] >> 3 : 0;
-        const textProgress = iu?.text_delta?.text;
-        const thinkingProgress = iu?.thinking_delta?.text;
         const checkpointProgress = normalizeCheckpointBytes(checkpointRaw);
-        if ((typeof textProgress === "string" && textProgress.length > 0) ||
-            (typeof thinkingProgress === "string" && thinkingProgress.length > 0) ||
-            !!iu?.turn_ended ||
-            !!iu?.tool_call_started ||
-            !!iu?.tool_call_completed ||
-            !!esm ||
-            !!kv ||
-            !!interactionQuery ||
-            !!checkpointProgress?.length) {
-            replaySafe = false;
+        const requiredChannel = responseRequiredChannel(payload);
+        if (requiredChannel === "multiple" ||
+            (requiredChannel === "exec" && !esm) ||
+            (requiredChannel === "kv" && !kv) ||
+            (requiredChannel === "interaction" && !interactionQuery)) {
+            failRunProtocol("Cursor response-requiring request could not be decoded", RUN_REQUEST_DECODE_FAILED);
+        }
+        const replayFrame = analyzeReplayFrame(payload, {
+            interactionUpdate: iu,
+            exec: esm,
+            kv,
+            execControl,
+            interactionQuery,
+            checkpointBytes: checkpointProgress,
+        });
+        if (replayFrame.semanticProgress) {
             sessionManager.recordSemanticProgress(session);
         }
+        if (replayFrame.barrier)
+            replaySafety.markBarrier(replayFrame.barrier);
         {
             const iuKind = iu ? Object.keys(iu).find((k) => iu[k]) : undefined;
             trace(`pump frame: topField=${topField} interaction_update=${iuKind ?? "-"} ` +
@@ -1221,15 +1271,12 @@ export async function pump(session, controller, ids, abortSignal) {
                             trace(`exec request_context hooks_additional_context: ${hooks}`);
                     }
                     try {
+                        traceRequestContextPaths(`exec request_context reply id=${esmId}`, session.requestContext);
                         session.stream.write(buildRequestContextResult(esmId, session.requestContext));
                         trace(`exec request_context: replied`);
                     }
-                    catch (e) {
-                        const error = new Error(`Failed to answer Cursor request_context probe: ${e.message}`);
-                        trace(`exec request_context: write FAILED ${error.message}`);
-                        safeError(error);
-                        sessionManager.close(session);
-                        return;
+                    catch {
+                        failRunProtocol("Cursor request-context reply failed", RUN_REPLY_FAILED);
                     }
                 }
                 else if (esm.mcp_state_exec_args) {
@@ -1244,16 +1291,20 @@ export async function pump(session, controller, ids, abortSignal) {
                         session.stream.write(buildMcpStateResult(esmId, stateArgs, session.requestContext));
                         trace(`exec mcp_state: replied id=${esmId} requested=[${requested}]`);
                     }
-                    catch (e) {
-                        const error = new Error(`Failed to answer Cursor MCP state probe: ${e.message}`);
-                        trace(`exec mcp_state: write FAILED ${error.message}`);
-                        safeError(error);
-                        sessionManager.close(session);
-                        return;
+                    catch {
+                        failRunProtocol("Cursor MCP-state reply failed", RUN_REPLY_FAILED);
                     }
                 }
                 else {
+                    replaySafety.markBarrier("non-control-exec");
                     const parsed = parseExecServerMessage(esm);
+                    if (parsed) {
+                        const executableToolName = resolveCustomWebToolAlias(parsed.toolName, session.toolAliases);
+                        if (executableToolName !== parsed.toolName) {
+                            trace(`web tool alias resolved: ${parsed.toolName} -> ${executableToolName}`);
+                            parsed.toolName = executableToolName;
+                        }
+                    }
                     const displayCallId = extractExecDisplayCallId(esm);
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
                     if (parsed) {
@@ -1327,10 +1378,7 @@ export async function pump(session, controller, ids, abortSignal) {
                         .map((x) => x.toString(16).padStart(2, "0"))
                         .join("");
                     trace(`exec UNMAPPED: id=${esmId} variant=${variantDescription} keys=[${Object.keys(esm).join(",")}] hex=${hex}`);
-                    const err = new Error(`Unsupported Cursor exec variant ${variantDescription} (id=${esmId})`);
-                    safeError(err);
-                    sessionManager.close(session);
-                    return;
+                    failRunProtocol(`Unsupported Cursor exec variant ${variantDescription} (id=${esmId})`, RUN_REQUEST_UNSUPPORTED);
                 }
             }
             else if (interactionQuery) {
@@ -1338,20 +1386,24 @@ export async function pump(session, controller, ids, abortSignal) {
                 // SDK has no Cursor-specific UI callback, so answer immediately with the
                 // conservative headless policy from protocol/interactions.ts (including
                 // F14 create_plan auto-ack / empty plan_uri for CLI headless parity).
+                const handled = (() => {
+                    try {
+                        return handleInteractionQuery(interactionQuery, payload);
+                    }
+                    catch {
+                        return failRunProtocol("Cursor interaction request could not be handled", RUN_REQUEST_UNSUPPORTED);
+                    }
+                })();
                 try {
-                    const handled = handleInteractionQuery(interactionQuery, payload);
+                    if (handled.outcome === "acknowledged") {
+                        replaySafety.markBarrier("stateful-interaction");
+                    }
                     session.stream.write(handled.reply);
                     trace(`interaction_query: replied id=${handled.id} variant=${handled.variantName} ` +
                         `field=${handled.variantField} outcome=${handled.outcome}`);
                 }
-                catch (e) {
-                    const info = inspectInteractionQueryWire(payload);
-                    const err = e instanceof Error ? e : new Error(String(e));
-                    trace(`interaction_query: FAILED id=${info.id ?? "?"} ` +
-                        `variantField=${info.variantField ?? "?"} err=${err.message}`);
-                    safeError(err);
-                    sessionManager.close(session);
-                    return;
+                catch {
+                    failRunProtocol("Cursor interaction reply failed", RUN_REPLY_FAILED);
                 }
             }
             else if (kv) {
@@ -1370,20 +1422,24 @@ export async function pump(session, controller, ids, abortSignal) {
                             `found=${handled.found} echoed=${!!handled.echoed} ` +
                             `sessionBlobs=${session.blobs.size} convBlobs=${conversationBlobCount(session.conversationId)}`);
                     }
-                    catch (e) {
-                        const error = new Error(`Failed to answer Cursor KV blob request: ${e.message}`);
-                        trace(`kv: write FAILED ${error.message}`);
-                        safeError(error);
-                        sessionManager.close(session);
-                        return;
+                    catch {
+                        failRunProtocol("Cursor KV reply failed", RUN_REPLY_FAILED);
                     }
                 }
+                else {
+                    failRunProtocol("Cursor KV request could not be handled", RUN_REQUEST_UNSUPPORTED);
+                }
             }
         }
         catch (e) {
+            if (e instanceof CursorProtocolError)
+                throw e;
+            if (requiredChannel) {
+                failRunProtocol(`Cursor ${requiredChannel} request could not be handled`, RUN_REQUEST_UNSUPPORTED);
+            }
             // Any per-frame dispatch throw (e.g. protobufjs length overrun in
             // exec/args decode) must not abort the whole turn — log and skip.
-            trace(`frame dispatch FAILED (skipping): topField=${topField} err=${e.message}`);
+            trace(`frame dispatch FAILED (skipping): topField=${topField}`);
         }
         // heartbeat / step / partial_tool_call → ignore (partial args are
         // display-only; the exec channel is authoritative. Checkpoints and
@@ -1506,8 +1562,11 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.has("plan_exit")) {
         instructions.push("- To leave plan mode, call the OpenCode `plan_exit` tool.");
     }
-    if (names.has("webfetch")) {
-        instructions.push("- To fetch a known URL, call the OpenCode `webfetch` tool; do not use Cursor's native WebFetch interaction.");
+    if (names.has(CUSTOM_WEBSEARCH_TOOL)) {
+        instructions.push(`- For web searches, call \`${CUSTOM_WEBSEARCH_TOOL}\`; do not use Cursor's native WebSearch interaction.`);
+    }
+    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("write")) {
         instructions.push(names.has("edit")

package/dist/models.d.ts

@@ -73,9 +73,11 @@ export declare function resolveVariantParameters(model: ModelInfo | undefined, o
 export declare function fetchModels(token: string, options?: {
     baseURL?: string;
     headers?: Record<string, string>;
+    timeoutMs?: number;
 }): Promise<ModelInfo[]>;
 export declare function refreshModelCache(cacheDir: string, fetcher: () => Promise<ModelInfo[]>): Promise<ModelInfo[]>;
 export declare function discoverModels(token: string, cacheDir: string, options?: {
     baseURL?: string;
     headers?: Record<string, string>;
+    timeoutMs?: number;
 }): Promise<ModelInfo[]>;

package/dist/plugin-v2.js

@@ -1,6 +1,7 @@
 import { define } from "@opencode-ai/plugin/v2/promise";
 import { CURSOR_PROVIDER_ID } from "./shared.js";
 import { createCursorLanguageModel } from "./language-model.js";
+import { adoptCompatHostCacheDir } from "./context/paths.js";
 /**
  * OpenCode Effect / Promise v2 plugin.
  *
@@ -25,6 +26,9 @@ function createSdk(options) {
 export default define({
     id: "cursor.provider",
     setup: async (ctx) => {
+        // Prefer OCP HostProfile.cacheDir when present; else XDG host heuristic.
+        // Explicit createCursor({ cacheDir }) / event.options.cacheDir still wins via LM.
+        await adoptCompatHostCacheDir();
         await ctx.aisdk.sdk((event) => {
             if (event.sdk)
                 return;

package/dist/plugin.js

@@ -1,11 +1,12 @@
 import { CURSOR_COMPACTION_OPTION, CURSOR_PROVIDER_ID, CURSOR_WEBSITE_HOST, CURSOR_API_HOST } from "./shared.js";
 import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtExpiryMs } from "./auth.js";
 import { CURSOR_VARIANT_PARAMETERS_KEY, CURSOR_WIRE_MODEL_ID_KEY, readCache, discoverModels, isCacheFresh, parseCursorContextLimit } from "./models.js";
-import { opencodeGlobalCacheDir } from "./context/paths.js";
+import { adoptCompatHostCacheDir, opencodeGlobalCacheDir } from "./context/paths.js";
 import { readStoredAuth } from "./context/auth-store.js";
 import { resolveAgentUrl } from "./agent-url.js";
-import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, } from "./shell-timeout.js";
+import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, setCursorShellPath, } from "./shell-timeout.js";
 import { sessionActivity } from "./activity.js";
+import { openCodeWebSearchTool } from "./web-tools.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
 /**
  * Strip characters and markup that break rendering in the OpenCode TUI/GUI from
@@ -194,6 +195,8 @@ function cursorGetServerConfigTelemetryEnabled() {
         process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "true");
 }
 export async function CursorPlugin(input) {
+    // Prefer strong OCP host identity when available; otherwise resolve from explicit host signals/install path.
+    await adoptCompatHostCacheDir();
     const cacheDir = opencodeGlobalCacheDir();
     const apiBaseURL = cursorApiBaseURL();
     // Last access token successfully resolved in this plugin instance. Config's
@@ -313,6 +316,12 @@ export async function CursorPlugin(input) {
         return cached?.models.length ? modelsToConfig(cached.models) : {};
     }
     return {
+        tool: {
+            // `websearch` is a reserved OpenCode id and is filtered for third-party
+            // providers after plugin tools are merged. Use the collision-safe id
+            // Cursor already sees so this host-side fallback survives that filter.
+            custom_websearch: openCodeWebSearchTool,
+        },
         async event({ event }) {
             switch (event.type) {
                 case "session.created":
@@ -336,9 +345,9 @@ export async function CursorPlugin(input) {
         async "tool.execute.before"(hookInput, output) {
             if (hookInput.tool !== "bash")
                 return;
-            // Keep args.command as the original display/permission command. Wrapping
-            // happens via shell.env (BASH_ENV / ZDOTDIR) so OpenCode's bash UI never
-            // stores or renders the private wrapper script.
+            // bash/zsh retain the original display/permission command and wrap via
+            // shell.env. sh/dash need a short wrapper-file command because their
+            // non-interactive `-c` path ignores BASH_ENV / ZDOTDIR.
             prepareCursorShellArgs(hookInput.callID, output.args);
         },
         async "shell.env"(hookInput, output) {
@@ -377,6 +386,7 @@ export async function CursorPlugin(input) {
             }
         },
         async config(cfg) {
+            setCursorShellPath(cfg.shell);
             cfg.provider ??= {};
             const models = await loadModels();
             const existing = cfg.provider[CURSOR_PROVIDER_ID];
@@ -486,6 +496,7 @@ export async function CursorPlugin(input) {
                 return {
                     ...(accessToken ? { accessToken } : {}),
                     workspaceRoot: input.directory,
+                    cacheDir,
                 };
             },
         },