cursor-opencode-provider 0.2.7 → 0.2.9

package/dist/language-model.js

@@ -6,11 +6,11 @@ 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, buildReadRejectionMessages, classifyMissingReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, 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";
@@ -23,6 +23,8 @@ import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths
 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.
@@ -44,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) {
@@ -430,7 +454,16 @@ 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 discoveredSubagentCatalog = extractHostSubagentCatalog(cursorTools);
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
     const recovery = startOptions?.recovery;
     const resuming = recovery?.kind === "resume";
@@ -451,7 +484,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;
@@ -493,7 +526,24 @@ 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 });
+    const contextSubagents = Array.isArray(requestContext.custom_subagents)
+        ? requestContext.custom_subagents
+            .map((agent) => agent && typeof agent === "object" && typeof agent.name === "string"
+            ? {
+                name: agent.name,
+                description: typeof agent.description === "string"
+                    ? agent.description
+                    : undefined,
+            }
+            : undefined)
+            .filter((agent) => !!agent)
+        : [];
+    const subagentCatalog = {
+        ...discoveredSubagentCatalog,
+        agents: [...new Map([...discoveredSubagentCatalog.agents, ...contextSubagents]
+                .map((agent) => [agent.name, agent])).values()],
+    };
     // 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)
@@ -513,7 +563,7 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         conversationState,
         parameterValues,
         maxMode,
-        tools,
+        tools: cursorTools,
         toolDescriptors,
         requestContext,
         action: resuming ? "resume" : "user",
@@ -570,6 +620,8 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         nextBridgedExecId: 900_000,
         blobs: new Map(),
         toolDescriptors,
+        toolAliases: webToolAliases.aliases,
+        subagentCatalog,
         requestContext,
         allowTools,
         usageEstimate,
@@ -814,11 +866,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.
@@ -922,6 +980,49 @@ export async function pump(session, controller, ids, abortSignal) {
             return true;
         }
     };
+    /**
+     * A read of a path that does not exist would otherwise reach OpenCode as a
+     * real tool call and raise a permission prompt for a file the user never had.
+     * Cursor's own LocalReadExecutor instead resolves the target against the
+     * workspace, stats it, and returns a typed ReadResult (file_not_found /
+     * invalid_file) before execution. Mirror that here: reply on the held-open
+     * exec channel with the exact typed case so the model receives a structured
+     * observation and the host surfaces no prompt.
+     *
+     * Read-only by construction — write/edit targets are never checked, so
+     * legitimate file creation (path resolves, file absent) is never denied. Runs
+     * after recoverMissingEditRead, which has already converted the new-file edit
+     * handshake read into an empty-file success. EACCES/EPERM and other stat
+     * errors fall through to OpenCode so a genuine permission decision stands.
+     */
+    const rejectMissingReadTarget = (parsed) => {
+        if (parsed.toolName !== "read")
+            return false;
+        const requested = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        if (!requested)
+            return false;
+        const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
+        const absolutePath = resolveReadTargetPath(requested, workspaceRoot);
+        const readResult = classifyMissingReadTarget(absolutePath);
+        if (!readResult)
+            return false;
+        try {
+            for (const frame of buildReadRejectionMessages(parsed.id, readResult)) {
+                session.stream.write(frame);
+            }
+            const kind = Object.keys(readResult)[0];
+            trace(`exec: rejected missing read target id=${parsed.id} kind=${kind} ` +
+                `path=${JSON.stringify(absolutePath)}`);
+            return true;
+        }
+        catch (e) {
+            const error = new Error(`Failed to reject Cursor read of a missing path: ${e.message}`);
+            trace(`exec: missing read rejection FAILED ${error.message}`);
+            safeError(error);
+            sessionManager.close(session);
+            return true;
+        }
+    };
     /** AI SDK V3 requires text-end / reasoning-end before finish or tool-call. */
     const closeOpenSpans = () => {
         for (const part of spanEndParts({ textStarted, reasoningStarted, textId, reasoningId })) {
@@ -933,7 +1034,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 });
@@ -951,7 +1052,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;
@@ -1029,15 +1130,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) {
@@ -1049,14 +1148,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.
@@ -1065,6 +1165,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;
         }
@@ -1072,39 +1173,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 ?? "-"} ` +
@@ -1229,12 +1337,8 @@ export async function pump(session, controller, ids, abortSignal) {
                         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) {
@@ -1249,16 +1353,21 @@ 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;
+                        }
+                        remapNativeSubagentForCatalog(parsed, advertisedToolNameSet, session.subagentCatalog);
+                    }
                     const displayCallId = extractExecDisplayCallId(esm);
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
                     if (parsed) {
@@ -1298,6 +1407,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         }
                         if (recoverMissingEditRead(parsed, displayCallId))
                             continue;
+                        if (rejectMissingReadTarget(parsed)) {
+                            if (displayCallId)
+                                session.displayToolCalls.delete(displayCallId);
+                            continue;
+                        }
                         if (displayCallId) {
                             session.displayToolCalls.delete(displayCallId);
                             trace(`exec: claimed display callId=${displayCallId}`);
@@ -1332,10 +1446,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) {
@@ -1343,20 +1454,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) {
@@ -1375,20 +1490,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
@@ -1499,6 +1618,7 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     if (names.size === 0)
         return undefined;
     const instructions = [];
+    const subagents = extractHostSubagentCatalog(tools);
     if (names.has("question")) {
         instructions.push("- When user input is required, call the OpenCode `question` tool; do not use Cursor's native AskQuestion interaction.");
     }
@@ -1511,8 +1631,22 @@ 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("task") || names.has("actor")) {
+        const target = names.has("actor") ? "`actor`" : "`task`";
+        const available = subagents.agents.map((agent) => `\`${agent.name}\``).join(", ");
+        instructions.push(`- Native Cursor Task/subagent requests are executed through OpenCode ${target}. ` +
+            "Advertised custom subagent names are used exactly; otherwise `unspecified` and `generalPurpose` select host `general`, " +
+            "`bugbot`, `security-review`, and `explore` select host `explore` (then `general`), and other specialized Cursor types fall back to `general`." +
+            (available ? ` Spawnable host agents this turn: ${available}.` : ""));
+        if (subagents.agents.some((agent) => agent.name === "scout")) {
+            instructions.push("- Host `scout` is available for external documentation and dependency-source research. Use Cursor `cursor-guide` for that use case; local repository discovery still uses `bugbot`/`explore`.");
+        }
     }
     if (names.has("write")) {
         instructions.push(names.has("edit")
@@ -1522,7 +1656,9 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
     return [
         `OpenCode exposes exactly these executable tools for this turn: ${[...names].map((name) => `\`${name}\``).join(", ")}.`,
         `Workspace root: ${JSON.stringify(workspaceRoot)}. Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them.`,
-        "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
+        subagents.executor
+            ? "Call only tools in that exact list. Cursor-native Task/subagent requests are permitted because a compatible host executor is listed; other unlisted Cursor-native tools remain unavailable."
+            : "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
         ...(instructions.length > 0
             ? ["Use these OpenCode tools instead of equivalent Cursor-native UI interactions:"]
             : []),

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.js

@@ -6,6 +6,7 @@ import { readStoredAuth } from "./context/auth-store.js";
 import { resolveAgentUrl } from "./agent-url.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,7 +195,7 @@ function cursorGetServerConfigTelemetryEnabled() {
         process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "true");
 }
 export async function CursorPlugin(input) {
-    // Prefer OCP HostProfile.cacheDir when the compat package is present; else XDG heuristic.
+    // Prefer strong OCP host identity when available; otherwise resolve from explicit host signals/install path.
     await adoptCompatHostCacheDir();
     const cacheDir = opencodeGlobalCacheDir();
     const apiBaseURL = cursorApiBaseURL();
@@ -315,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":

package/dist/protocol/client-version.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { FALLBACK_CLIENT_VERSION, MODEL_CACHE_TTL_MS, VERSION_CACHE_FILE, } from "../shared.js";
 import { opencodeGlobalCacheDir } from "../context/paths.js";
+import { withAbortDeadline } from "../deadline.js";
 const INSTALL_URL = "https://cursor.com/install";
 const REMOTE_TIMEOUT_MS = 5_000;
 const BUILD_RE = /^\d{4}\.\d{2}\.\d{2}-[0-9A-Za-z][0-9A-Za-z.-]*$/;
@@ -103,13 +104,13 @@ function isCacheFresh(cache, now = Date.now()) {
     return age >= 0 && age < MODEL_CACHE_TTL_MS;
 }
 async function fetchInstallerVersion() {
-    const response = await fetch(INSTALL_URL, {
-        signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS),
+    return withAbortDeadline(REMOTE_TIMEOUT_MS, () => new Error("Cursor installer version request timed out"), async (signal) => {
+        const response = await fetch(INSTALL_URL, { signal });
+        if (!response.ok)
+            return undefined;
+        const build = extractVersionFromInstaller(await response.text());
+        return build ? `cli-${build}` : undefined;
     });
-    if (!response.ok)
-        return undefined;
-    const build = extractVersionFromInstaller(await response.text());
-    return build ? `cli-${build}` : undefined;
 }
 async function refreshVersionCache() {
     const version = await fetchInstallerVersion();

package/dist/protocol/messages.js

@@ -366,10 +366,29 @@ export function createMessageTypes() {
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "error", type: "string" },
     ]);
+    // Cursor's LocalReadExecutor validates the target before execution and, for a
+    // missing / non-regular path, returns one of these typed ReadResult cases
+    // instead of running the tool. Mirroring the exact field ids/shapes lets this
+    // provider reply the same way so the model sees a structured file-not-found
+    // observation and the host never surfaces a permission prompt.
+    addType(root, "ReadFileNotFound", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadPermissionDenied", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadInvalidFile", [
+        { id: 1, name: "path", type: "string" },
+        { id: 2, name: "reason", type: "string" },
+    ]);
     addType(root, "ReadResult", [
         { id: 1, name: "success", type: "ReadSuccess" },
         { id: 2, name: "error", type: "ReadError" },
-    ], [{ name: "result", fields: ["success", "error"] }]);
+        { id: 4, name: "file_not_found", type: "ReadFileNotFound" },
+        { id: 5, name: "permission_denied", type: "ReadPermissionDenied" },
+        { id: 6, name: "invalid_file", type: "ReadInvalidFile" },
+    ], [
+        {
+            name: "result",
+            fields: ["success", "error", "file_not_found", "permission_denied", "invalid_file"],
+        },
+    ]);
     addType(root, "GrepArgs", [
         { id: 1, name: "pattern", type: "string" },
         { id: 2, name: "path", type: "string" },
@@ -724,8 +743,10 @@ export function createMessageTypes() {
         { id: 7, name: "tools", type: "McpToolDefinition", repeated: true },
         { id: 11, name: "git_repos", type: "GitRepoInfo", repeated: true },
         { id: 13, name: "project_layouts", type: "LsDirectoryTreeNode", repeated: true },
+        { id: 17, name: "web_search_enabled", type: "bool" },
         { id: 22, name: "custom_subagents", type: "CustomSubagent", repeated: true },
         { id: 23, name: "mcp_file_system_options", type: "McpFileSystemOptions" },
+        { id: 24, name: "web_fetch_enabled", type: "bool" },
         { id: 25, name: "hooks_additional_context", type: "string" },
         { id: 29, name: "agent_skills", type: "AgentSkill", repeated: true },
         { id: 33, name: "git_repo_info_complete", type: "bool" },
@@ -883,8 +904,10 @@ export function createMessageTypes() {
         { id: 7, name: "tools", type: "McpToolDefinition", repeated: true },
         { id: 11, name: "git_repos", type: "GitRepoInfo", repeated: true },
         { id: 13, name: "project_layouts", type: "LsDirectoryTreeNode", repeated: true },
+        { id: 17, name: "web_search_enabled", type: "bool" },
         { id: 22, name: "custom_subagents", type: "CustomSubagent", repeated: true },
         { id: 23, name: "mcp_file_system_options", type: "McpFileSystemOptions" },
+        { id: 24, name: "web_fetch_enabled", type: "bool" },
         { id: 25, name: "hooks_additional_context", type: "string" },
         { id: 29, name: "agent_skills", type: "AgentSkill", repeated: true },
         { id: 33, name: "git_repo_info_complete", type: "bool" },

package/dist/protocol/struct.d.ts

@@ -7,6 +7,24 @@ export type RawField = {
 };
 /** Walk a protobuf message's top-level fields off the raw wire bytes. */
 export declare function readAllFields(b: Uint8Array): RawField[];
+export type StrictRawField = {
+    fn: number;
+    wt: number;
+    varint?: bigint;
+    bytes?: Uint8Array;
+    fixed64?: Uint8Array;
+    fixed32?: Uint8Array;
+};
+/**
+ * Strictly walk a protobuf message for security/replay decisions.
+ *
+ * Unlike `readAllFields`, this parser consumes the complete input, preserves
+ * uint64 varints as bigint, represents fixed-width fields, and rejects invalid
+ * tags, truncation, overflow, groups, and unsupported wire types. It deliberately
+ * returns `undefined` instead of a partial result: callers must fail closed when
+ * deciding whether replay is safe.
+ */
+export declare function readAllFieldsStrict(bytes: Uint8Array): StrictRawField[] | undefined;
 /** Decode a google.protobuf.Value message (bytes) back into a JSON value. */
 export declare function decodeValueToJson(bytes: Uint8Array): unknown;
 /**