cursor-opencode-provider 0.2.7 → 0.2.9

package/dist/protocol/struct.js

@@ -82,6 +82,88 @@ export function readAllFields(b) {
     }
     return out;
 }
+const MAX_UINT32 = 0xffffffffn;
+const MAX_UINT64 = 0xffffffffffffffffn;
+const MAX_PROTOBUF_FIELD_NUMBER = 0x1fff_ffff;
+/**
+ * Decode one unsigned protobuf varint without JavaScript's 32-bit bitwise
+ * truncation. `maximum` also enforces the protocol width: tags and lengths are
+ * uint32, while wire-type 0 scalar values may use the full uint64 range.
+ */
+function readBoundedVarint(bytes, offset, maximum) {
+    let value = 0n;
+    let shift = 0n;
+    for (let index = offset; index < bytes.length && index < offset + 10; index++) {
+        const byte = bytes[index];
+        value |= BigInt(byte & 0x7f) << shift;
+        if (value > maximum)
+            return undefined;
+        if ((byte & 0x80) === 0)
+            return { value, nextOffset: index + 1 };
+        shift += 7n;
+    }
+    return undefined;
+}
+/**
+ * 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 function readAllFieldsStrict(bytes) {
+    let offset = 0;
+    const fields = [];
+    while (offset < bytes.length) {
+        const tag = readBoundedVarint(bytes, offset, MAX_UINT32);
+        if (!tag)
+            return undefined;
+        offset = tag.nextOffset;
+        const fieldNumber = Number(tag.value >> 3n);
+        const wireType = Number(tag.value & 7n);
+        if (fieldNumber === 0 || fieldNumber > MAX_PROTOBUF_FIELD_NUMBER)
+            return undefined;
+        if (wireType === 0) {
+            const scalar = readBoundedVarint(bytes, offset, MAX_UINT64);
+            if (!scalar)
+                return undefined;
+            fields.push({ fn: fieldNumber, wt: wireType, varint: scalar.value });
+            offset = scalar.nextOffset;
+            continue;
+        }
+        if (wireType === 1) {
+            if (offset + 8 > bytes.length)
+                return undefined;
+            fields.push({ fn: fieldNumber, wt: wireType, fixed64: bytes.subarray(offset, offset + 8) });
+            offset += 8;
+            continue;
+        }
+        if (wireType === 2) {
+            const encodedLength = readBoundedVarint(bytes, offset, MAX_UINT32);
+            if (!encodedLength)
+                return undefined;
+            offset = encodedLength.nextOffset;
+            const length = Number(encodedLength.value);
+            if (offset + length > bytes.length)
+                return undefined;
+            fields.push({ fn: fieldNumber, wt: wireType, bytes: bytes.subarray(offset, offset + length) });
+            offset += length;
+            continue;
+        }
+        if (wireType === 5) {
+            if (offset + 4 > bytes.length)
+                return undefined;
+            fields.push({ fn: fieldNumber, wt: wireType, fixed32: bytes.subarray(offset, offset + 4) });
+            offset += 4;
+            continue;
+        }
+        // Groups (3/4) are deprecated and recursive; no replay-safe frame uses them.
+        return undefined;
+    }
+    return fields;
+}
 function decodeStructBytes(b) {
     const obj = {};
     for (const f of readAllFields(b)) {

package/dist/protocol/tool-call-bridge.js

@@ -1,4 +1,4 @@
-import { mapCursorArgsToOpencode, mcpRealToolName } from "./tools.js";
+import { mapCursorArgsToOpencode, mapCursorSubagentTypeToOpenCode, mcpRealToolName } from "./tools.js";
 import { decodeStructEntriesToJson } from "./struct.js";
 const TODO_STATUS = {
     0: "pending",
@@ -334,7 +334,27 @@ function openCodeSubagentType(raw) {
     if (typeof custom?.name === "string" && custom.name.length > 0)
         return custom.name;
     if (subtype.explore != null)
-        return "explore";
+        return mapCursorSubagentTypeToOpenCode("explore");
+    if (subtype.cursor_guide != null)
+        return mapCursorSubagentTypeToOpenCode("cursor_guide");
+    if (subtype.bash != null)
+        return mapCursorSubagentTypeToOpenCode("bash");
+    if (subtype.shell != null)
+        return mapCursorSubagentTypeToOpenCode("shell");
+    if (subtype.debug != null)
+        return mapCursorSubagentTypeToOpenCode("debug");
+    if (subtype.computer_use != null)
+        return mapCursorSubagentTypeToOpenCode("computer_use");
+    if (subtype.browser_use != null)
+        return mapCursorSubagentTypeToOpenCode("browser_use");
+    if (subtype.media_review != null)
+        return mapCursorSubagentTypeToOpenCode("media_review");
+    if (subtype.watch_video != null)
+        return mapCursorSubagentTypeToOpenCode("watch_video");
+    if (subtype.vm_setup_helper != null)
+        return mapCursorSubagentTypeToOpenCode("vm_setup_helper");
+    if (subtype.unspecified != null)
+        return mapCursorSubagentTypeToOpenCode("unspecified");
     return undefined;
 }
 /** Advertised OpenCode tool ids from Cursor McpToolDefinition descriptors. */

package/dist/protocol/tools.d.ts

@@ -4,6 +4,17 @@ export type OpencodeToolDef = {
     name: string;
     description?: string;
     inputSchema?: unknown;
+    /** Original flattened identity when `name` is a Cursor-facing alias. */
+    sourceName?: string;
+};
+export declare const CUSTOM_WEBSEARCH_TOOL = "custom_websearch";
+export declare const CUSTOM_WEBFETCH_TOOL = "custom_webfetch";
+/** Cursor-facing alias → exact host tool name accepted by the AI SDK call. */
+export type ToolAliasRegistry = ReadonlyMap<string, string>;
+export type AliasedToolCatalog = {
+    advertisedTools: OpencodeToolDef[];
+    aliases: ToolAliasRegistry;
+    ambiguous: ReadonlyMap<string, string[]>;
 };
 export type ToolServerIdentity = {
     /** Cursor MCP server id / provider_identifier (e.g. opencode, github). */
@@ -32,6 +43,13 @@ export declare function resolveToolServerIdentity(opencodeName: string, defaultS
  * reconstructed in `mcpRealToolName`.
  */
 export declare function toolsToDescriptors(tools: OpencodeToolDef[], providerIdentifier?: string, knownMcpServers?: Iterable<string>): Array<Record<string, unknown>>;
+/**
+ * Give collision-prone web capabilities names Cursor will not confuse with its
+ * native UI-bound WebSearch/WebFetch interactions. Exact host tools win; a
+ * flattened MCP suffix is accepted only when it identifies one unique tool.
+ */
+export declare function buildCustomWebToolAliases(tools: OpencodeToolDef[]): AliasedToolCatalog;
+export declare function resolveCustomWebToolAlias(toolName: string, aliases: ToolAliasRegistry | undefined): string;
 /**
  * Build the nested McpFileSystemOptions / McpMetaToolOptions shape used by
  * requestContext.#23 / #34. One `McpDescriptor` per resolved server (builtins
@@ -46,6 +64,29 @@ export declare function toolsToMcpDescriptors(tools: OpencodeToolDef[], provider
 export declare function buildLiveRequestContext(tools: OpencodeToolDef[], providerIdentifier?: string, knownMcpServers?: Iterable<string>): Record<string, unknown>;
 export declare function mapExecServerToToolName(execField: string): string | undefined;
 export declare function mapToolNameToExecField(toolName: string): string | undefined;
+export type HostSubagentDefinition = {
+    name: string;
+    description?: string;
+};
+export type HostSubagentCatalog = {
+    executor?: "task" | "actor";
+    agents: HostSubagentDefinition[];
+    /** True when the host tool supplied its complete, permission-filtered catalog. */
+    complete: boolean;
+};
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export declare function extractHostSubagentCatalog(tools: OpencodeToolDef[]): HostSubagentCatalog;
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export declare function resolveCursorSubagentType(subagentType: string, catalog?: HostSubagentCatalog): string | undefined;
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+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;
 export type ParsedExecRequest = {
     id: number;
     execId: string;
@@ -74,6 +115,32 @@ 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;
+/**
+ * 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)`.
+ */
+export declare function resolveReadTargetPath(requested: string, workspaceRoot: string): string;
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export declare function classifyMissingReadTarget(absolutePath: string): Record<string, unknown> | undefined;
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export declare function buildReadRejectionMessages(execId: number, readResult: Record<string, unknown>): Uint8Array[];
 export type ToolResultInput = {
     execId: number;
     /** ExecClientMessage result field (from ParsedExecRequest.resultField). */

package/dist/protocol/tools.js

@@ -1,4 +1,6 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { buildEnv } from "../context/env.js";
@@ -10,6 +12,8 @@ import { BACKGROUND_SHELL_MARKER, buildBackgroundShellCommand, } from "../shell-
 // probe (ExecServerMessage #10 → ExecClientMessage #10). request/result share a
 // field number for every exec variant, so this is also the result field.
 export const REQUEST_CONTEXT_RESULT_FIELD = 10;
+export const CUSTOM_WEBSEARCH_TOOL = "custom_websearch";
+export const CUSTOM_WEBFETCH_TOOL = "custom_webfetch";
 /** Match OpenCode's McpCatalog.sanitize for config server ids. */
 export function sanitizeMcpServerId(value) {
     return value.replace(/[^a-zA-Z0-9_-]/g, "_");
@@ -51,13 +55,17 @@ export function resolveToolServerIdentity(opencodeName, defaultServer = "opencod
  */
 export function toolsToDescriptors(tools, providerIdentifier = "opencode", knownMcpServers = []) {
     return tools.map((t) => {
-        const id = resolveToolServerIdentity(t.name, providerIdentifier, knownMcpServers);
+        const id = resolveToolServerIdentity(t.sourceName ?? t.name, providerIdentifier, knownMcpServers);
+        const collisionSafeWebAlias = t.name === CUSTOM_WEBSEARCH_TOOL || t.name === CUSTOM_WEBFETCH_TOOL;
         return {
-            name: `${id.server}-${id.toolName}`,
+            // 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}`,
             description: t.description ?? "",
             input_schema: encodeJsonAsValue(normalizeInputSchema(t.inputSchema)),
             provider_identifier: id.server,
-            tool_name: id.toolName,
+            tool_name: t.sourceName ? t.name : id.toolName,
         };
     });
 }
@@ -67,6 +75,67 @@ function normalizeInputSchema(schema) {
     }
     return { type: "object", properties: {} };
 }
+const WEB_ALIAS_RULES = [
+    {
+        alias: CUSTOM_WEBSEARCH_TOOL,
+        exact: ["websearch", "web_search"],
+        suffixes: ["_web_search", "-web_search", "_websearch", "-websearch"],
+    },
+    {
+        alias: CUSTOM_WEBFETCH_TOOL,
+        exact: ["webfetch", "web_fetch"],
+        suffixes: ["_web_fetch", "-web_fetch", "_webfetch", "-webfetch"],
+    },
+];
+/**
+ * Give collision-prone web capabilities names Cursor will not confuse with its
+ * native UI-bound WebSearch/WebFetch interactions. Exact host tools win; a
+ * flattened MCP suffix is accepted only when it identifies one unique tool.
+ */
+export function buildCustomWebToolAliases(tools) {
+    const aliases = new Map();
+    const ambiguous = new Map();
+    const replacements = new Map();
+    for (const rule of WEB_ALIAS_RULES) {
+        // A host/plugin may already expose the collision-safe public name. Keep it
+        // authoritative instead of hiding it behind a second mapping.
+        if (tools.some((tool) => tool.name === rule.alias))
+            continue;
+        const exact = tools.filter((tool) => rule.exact.includes(tool.name.toLowerCase()));
+        const candidates = exact.length > 0
+            ? exact
+            : tools.filter((tool) => {
+                const name = tool.name.toLowerCase();
+                return rule.suffixes.some((suffix) => name.endsWith(suffix));
+            });
+        if (candidates.length !== 1) {
+            if (candidates.length > 1)
+                ambiguous.set(rule.alias, candidates.map((tool) => tool.name));
+            continue;
+        }
+        const original = candidates[0].name;
+        aliases.set(rule.alias, original);
+        replacements.set(original, rule.alias);
+    }
+    return {
+        advertisedTools: tools.map((tool) => {
+            const alias = replacements.get(tool.name);
+            return alias ? { ...tool, name: alias, sourceName: tool.name } : { ...tool };
+        }),
+        aliases,
+        ambiguous,
+    };
+}
+export function resolveCustomWebToolAlias(toolName, aliases) {
+    const direct = aliases?.get(toolName);
+    if (direct)
+        return direct;
+    for (const [alias, original] of aliases ?? []) {
+        if (toolName.endsWith(`_${alias}`))
+            return original;
+    }
+    return toolName;
+}
 /**
  * Build the nested McpFileSystemOptions / McpMetaToolOptions shape used by
  * requestContext.#23 / #34. One `McpDescriptor` per resolved server (builtins
@@ -79,7 +148,7 @@ export function toolsToMcpDescriptors(tools, providerIdentifier = "opencode", kn
     const order = [];
     const byServer = new Map();
     for (const t of tools) {
-        const id = resolveToolServerIdentity(t.name, providerIdentifier, knownMcpServers);
+        const id = resolveToolServerIdentity(t.sourceName ?? t.name, providerIdentifier, knownMcpServers);
         let list = byServer.get(id.server);
         if (!list) {
             list = [];
@@ -87,7 +156,7 @@ export function toolsToMcpDescriptors(tools, providerIdentifier = "opencode", kn
             order.push(id.server);
         }
         list.push({
-            tool_name: id.toolName,
+            tool_name: t.sourceName ? t.name : id.toolName,
             description: t.description ?? "",
             input_schema: encodeJsonAsValue(normalizeInputSchema(t.inputSchema)),
         });
@@ -118,6 +187,8 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
             enabled: true,
             mcp_descriptors: nested,
         },
+        web_search_enabled: false,
+        web_fetch_enabled: false,
         rules_info_complete: true,
         env_info_complete: true,
         repository_info_complete: true,
@@ -211,6 +282,200 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
+const CURSOR_SUBAGENT_TYPE_TO_OPENCODE = {
+    generalPurpose: "general",
+    "general-purpose": "general",
+    general_purpose: "general",
+    general: "general",
+    unspecified: "general",
+    "cursor-guide": "explore",
+    cursor_guide: "explore",
+    "best-of-n-runner": "general",
+    best_of_n_runner: "general",
+    bash: "general",
+    shell: "general",
+    debug: "general",
+    computer_use: "general",
+    computerUse: "general",
+    browser_use: "general",
+    browserUse: "general",
+    media_review: "general",
+    mediaReview: "general",
+    watch_video: "general",
+    watchVideo: "general",
+    vm_setup_helper: "general",
+    vmSetupHelper: "general",
+    explore: "explore",
+    bugbot: "explore",
+    "security-review": "explore",
+    security_review: "explore",
+};
+const SUBAGENT_CATALOG_MARKER = "Available agent types and the tools they have access to:";
+function parseSubagentDescriptionCatalog(description) {
+    if (!description)
+        return { found: false, agents: [] };
+    const marker = description.indexOf(SUBAGENT_CATALOG_MARKER);
+    if (marker < 0)
+        return { found: false, agents: [] };
+    const agents = [];
+    const lines = description.slice(marker + SUBAGENT_CATALOG_MARKER.length).split(/\r?\n/);
+    let started = false;
+    for (const line of lines) {
+        const match = line.match(/^\s*-\s+([^:]+):\s*(.*)$/);
+        if (!match) {
+            if (started && line.trim())
+                break;
+            continue;
+        }
+        started = true;
+        const name = match[1].trim().replace(/^`|`$/g, "");
+        if (!name)
+            continue;
+        const agentDescription = match[2].trim();
+        agents.push({
+            name,
+            ...(agentDescription ? { description: agentDescription } : {}),
+        });
+    }
+    return { found: true, agents };
+}
+function subagentTypeEnumValues(schema) {
+    const out = new Set();
+    const seen = new Set();
+    const visit = (value, propertyName) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, propertyName);
+            return;
+        }
+        const record = value;
+        if (propertyName === "subagent_type" && Array.isArray(record.enum)) {
+            for (const item of record.enum) {
+                if (typeof item === "string" && item)
+                    out.add(item);
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            visit(child, key);
+    };
+    visit(schema);
+    return [...out];
+}
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export function extractHostSubagentCatalog(tools) {
+    const executorTool = tools.find((tool) => tool.name === "actor") ??
+        tools.find((tool) => tool.name === "task");
+    if (!executorTool)
+        return { agents: [], complete: true };
+    const described = parseSubagentDescriptionCatalog(executorTool.description);
+    const enumNames = subagentTypeEnumValues(executorTool.inputSchema);
+    const descriptions = new Map(described.agents.map((agent) => [agent.name, agent.description]));
+    // MiMo's Actor enum is stricter than its prose catalog (`mode: subagent`
+    // rather than every non-primary agent), so structured names are authoritative.
+    const names = new Set(enumNames.length > 0 ? enumNames : described.agents.map((agent) => agent.name));
+    return {
+        executor: executorTool.name,
+        agents: [...names].map((name) => ({
+            name,
+            ...(descriptions.get(name) ? { description: descriptions.get(name) } : {}),
+        })),
+        complete: enumNames.length > 0 || described.found,
+    };
+}
+const GENERIC_CURSOR_SUBAGENT_TYPES = new Set([
+    "generalPurpose",
+    "general-purpose",
+    "general_purpose",
+    "general",
+    "unspecified",
+]);
+function cursorSubagentCandidates(subagentType) {
+    if (GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType))
+        return ["general"];
+    if (subagentType === "cursor-guide" || subagentType === "cursor_guide") {
+        return ["scout", "explore", "general"];
+    }
+    if (subagentType === "explore" ||
+        subagentType === "bugbot" ||
+        subagentType === "security-review" ||
+        subagentType === "security_review") {
+        return ["explore", "general"];
+    }
+    return ["general"];
+}
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export function resolveCursorSubagentType(subagentType, catalog) {
+    const available = new Set(catalog?.agents.map((agent) => agent.name) ?? []);
+    // Explicit host/custom names win. `unspecified` and general aliases are
+    // intentionally excluded so they always select the host's generic agent.
+    if (!GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType) && available.has(subagentType)) {
+        return subagentType;
+    }
+    const candidates = cursorSubagentCandidates(subagentType);
+    for (const candidate of candidates) {
+        if (available.has(candidate))
+            return candidate;
+    }
+    if (catalog?.complete)
+        return undefined;
+    return candidates[0];
+}
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+export function mapCursorSubagentTypeToOpenCode(subagentType) {
+    return CURSOR_SUBAGENT_TYPE_TO_OPENCODE[subagentType] ?? subagentType;
+}
+/** Resolve a native Cursor subagent request to this turn's executor and catalog. */
+export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catalog) {
+    if (parsed.resultField !== "subagent_result" || parsed.toolName !== "task")
+        return;
+    const advertised = new Set(advertisedToolNames);
+    const executor = advertised.has("actor") ? "actor" : advertised.has("task") ? "task" : undefined;
+    if (!executor)
+        return;
+    const description = str(parsed.args.description) ?? "";
+    const prompt = str(parsed.args.prompt) ?? "";
+    const cursorSubagentType = str(parsed.resultMetadata?.cursor_subagent_type) ??
+        str(parsed.args.subagent_type) ?? "";
+    const subagentType = resolveCursorSubagentType(cursorSubagentType, catalog);
+    if (!subagentType) {
+        const available = catalog?.agents.map((agent) => agent.name).join(", ") || "none";
+        parsed.localError =
+            `Cursor subagent '${cursorSubagentType}' has no compatible host agent. ` +
+                `Available subagents: ${available}.`;
+        return;
+    }
+    const resumeAgentId = str(parsed.args.task_id);
+    parsed.toolName = executor;
+    if (executor === "task") {
+        parsed.args = {
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
+            ...(parsed.args.background === true ? { background: true } : {}),
+        };
+        return;
+    }
+    parsed.args = {
+        operation: {
+            action: parsed.args.background === true ? "spawn" : "run",
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { actor_id: resumeAgentId } : {}),
+        },
+    };
+}
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -289,6 +554,9 @@ export function parseExecServerMessage(msg) {
             toolName: "task",
             args,
             resultField,
+            resultMetadata: cursorSubagentType
+                ? { cursor_subagent_type: cursorSubagentType }
+                : undefined,
             localError: prompt && cursorSubagentType
                 ? undefined
                 : "Cursor subagent request is missing a required prompt or subagent type.",
@@ -526,19 +794,6 @@ function describeSubagentTask(prompt, subagentType) {
         return words.join(" ");
     return `${subagentType || "Delegated"} task`;
 }
-function mapCursorSubagentTypeToOpenCode(subagentType) {
-    // Cursor's built-in general agent uses a camelCase protocol identifier, and
-    // its native Bugbot reviewer has no OpenCode-specific agent definition.
-    // OpenCode `general` is the general-purpose equivalent; `explore` preserves
-    // Bugbot's review-only/read-oriented semantics while retaining grep/read/bash.
-    // Preserve every other value so `explore` and configured custom agents keep
-    // their exact advertised names.
-    if (subagentType === "generalPurpose")
-        return "general";
-    if (subagentType === "bugbot")
-        return "explore";
-    return subagentType;
-}
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -598,6 +853,75 @@ function findOneOfVariant(msg, candidates) {
     }
     return undefined;
 }
+// ── Pre-execution read validation (Cursor LocalReadExecutor parity) ──
+/** Expand a leading `~` to the home directory, matching Cursor's untildify. */
+function untildify(input) {
+    return input.replace(/^~(?=$|\/|\\)/, os.homedir());
+}
+/**
+ * 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)`.
+ */
+export function resolveReadTargetPath(requested, workspaceRoot) {
+    const expanded = untildify(requested);
+    if (workspaceRoot && !path.isAbsolute(expanded)) {
+        return path.resolve(workspaceRoot, expanded);
+    }
+    return path.resolve(expanded);
+}
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export function classifyMissingReadTarget(absolutePath) {
+    let stat;
+    try {
+        stat = fs.statSync(absolutePath);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { file_not_found: { path: absolutePath } };
+        }
+        return undefined;
+    }
+    if (stat.isDirectory()) {
+        return { invalid_file: { path: absolutePath, reason: "Path is a directory, not a file" } };
+    }
+    if (!stat.isFile()) {
+        return {
+            invalid_file: { path: absolutePath, reason: "Path is neither a file nor a directory" },
+        };
+    }
+    return undefined;
+}
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export function buildReadRejectionMessages(execId, readResult) {
+    return [
+        encodeMessage("AgentClientMessage", {
+            exec_client_message: {
+                id: execId,
+                local_execution_time_ms: 0,
+                read_result: readResult,
+            },
+        }),
+        buildExecStreamClose(execId),
+    ];
+}
 /**
  * Build one or more ExecClientMessage frames for a tool result.
  * Shell replies are a sequence of ShellStream oneofs under the same id —

package/dist/replay-safety.d.ts

@@ -0,0 +1,23 @@
+import type { CursorProviderError } from "./errors.js";
+export type ReplayBarrierReason = "visible-text" | "visible-reasoning" | "display-tool-lifecycle" | "non-control-exec" | "stateful-interaction" | "unknown-or-malformed-frame";
+export declare class AttemptReplaySafety {
+    private readonly sessionId;
+    private barrierReason;
+    constructor(sessionId: string);
+    markBarrier(reason: ReplayBarrierReason): void;
+    applyTo(failure: CursorProviderError): CursorProviderError;
+}
+export type DecodedReplayFrame = {
+    interactionUpdate?: Record<string, unknown>;
+    exec?: Record<string, unknown>;
+    kv?: Record<string, unknown>;
+    execControl?: Record<string, unknown>;
+    interactionQuery?: Record<string, unknown>;
+    checkpointBytes?: Uint8Array;
+};
+export type ReplayFrameAnalysis = {
+    semanticProgress: boolean;
+    barrier?: ReplayBarrierReason;
+};
+/** Classify one decoded server frame without performing any protocol side effects. */
+export declare function analyzeReplayFrame(payload: Uint8Array, decoded: DecodedReplayFrame): ReplayFrameAnalysis;