cursor-opencode-provider 0.2.6 → 0.2.8

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

@@ -653,8 +653,10 @@ export function createMessageTypes() {
         { id: 2, name: "workspace_paths", type: "string", repeated: true },
         { id: 3, name: "shell", type: "string" },
         { id: 5, name: "sandbox_enabled", type: "bool" },
+        { id: 7, name: "terminals_folder", type: "string" },
         { id: 10, name: "time_zone", type: "string" },
         { id: 11, name: "project_folder", type: "string" },
+        { id: 12, name: "agent_transcripts_folder", type: "string" },
         { id: 14, name: "sandbox_supported", type: "bool" },
         { id: 20, name: "is_working_dir_home_dir", type: "bool" },
         { id: 21, name: "process_working_directory", type: "string" },
@@ -722,8 +724,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" },
@@ -881,8 +885,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;
 /**

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/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

package/dist/protocol/tools.js

@@ -1,13 +1,17 @@
 import fs from "node:fs";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
-import { trace } from "../debug.js";
+import { buildEnv } from "../context/env.js";
+import { ensureOpencodeProjectDir } from "../context/paths.js";
+import { trace, traceRequestContextPaths } from "../debug.js";
 import { cursorExecVariantByRequestName } from "./exec-variants.js";
-import { BACKGROUND_SHELL_MARKER } from "../shell-timeout.js";
+import { BACKGROUND_SHELL_MARKER, buildBackgroundShellCommand, } from "../shell-timeout.js";
 // Exec variant field number whose reply is the server-initiated request_context
 // 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, "_");
@@ -49,13 +53,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,
         };
     });
 }
@@ -65,6 +73,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
@@ -77,7 +146,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 = [];
@@ -85,7 +154,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)),
         });
@@ -104,31 +173,28 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
     const flat = toolsToDescriptors(tools, providerIdentifier, knownMcpServers);
     const nested = toolsToMcpDescriptors(tools, providerIdentifier, knownMcpServers);
     const cwd = process.cwd();
-    return {
-        env: {
-            os_version: process.platform,
-            workspace_paths: [cwd],
-            shell: process.env.SHELL || "/bin/bash",
-            time_zone: "UTC",
-            project_folder: cwd,
-            process_working_directory: cwd,
-        },
+    const ctx = {
+        env: buildEnv(cwd),
         tools: flat,
         mcp_file_system_options: {
             enabled: true,
-            workspace_project_dir: cwd,
+            workspace_project_dir: ensureOpencodeProjectDir(cwd),
             mcp_descriptors: nested,
         },
         mcp_meta_tool_options: {
             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,
         mcp_file_system_info_complete: true,
         git_status_info_complete: true,
     };
+    traceRequestContextPaths("buildLiveRequestContext", ctx);
+    return ctx;
 }
 // ── Cursor exec-variant → opencode tool name ──
 // Native ExecServerMessage variants only (agent.v1). There is no edit_args or
@@ -235,16 +301,17 @@ export function parseExecServerMessage(msg) {
     if (!resultField)
         return undefined;
     const execId = msg.exec_id ?? "";
-    // F11: Cursor native background shell → OpenCode bash. Emit the original
-    // command for UI/storage; the classic plugin before-hook wraps with nohup.
-    // Residual: the child can keep running after this tool call completes.
+    // F11: Cursor native background shell → OpenCode bash. Keep the wrapper
+    // self-contained so direct provider / hosts without shell.env still detach
+    // and return a PID. The classic plugin replaces this with its display-safe
+    // env or wrapper-file path before execution.
     if (execVariant === "background_shell_spawn_args") {
         const raw = msg.background_shell_spawn_args ?? {};
         const command = str(raw.command);
         const workingDirectory = str(raw.working_directory) ?? "";
         const args = {};
         if (command)
-            args.command = command;
+            args.command = buildBackgroundShellCommand(command);
         if (workingDirectory)
             args.workdir = workingDirectory;
         return {
@@ -1112,6 +1179,7 @@ export function detectExecVariantField(agentServerPayload) {
  * Encode exec #10 request_context_result from a prebuilt RequestContext payload.
  */
 export function buildRequestContextResult(execId, requestContext) {
+    traceRequestContextPaths(`buildRequestContextResult id=${execId}`, requestContext);
     return encodeMessage("AgentClientMessage", {
         exec_client_message: {
             id: execId,

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;

package/dist/replay-safety.js

@@ -0,0 +1,126 @@
+import { trace } from "./debug.js";
+import { readAllFieldsStrict } from "./protocol/struct.js";
+export class AttemptReplaySafety {
+    sessionId;
+    barrierReason;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    markBarrier(reason) {
+        if (this.barrierReason)
+            return;
+        this.barrierReason = reason;
+        trace(`replay barrier: reason=${reason} sessionId=${this.sessionId}`);
+    }
+    applyTo(failure) {
+        failure.replaySafe = this.barrierReason === undefined && failure.replaySafe;
+        if (this.barrierReason) {
+            trace(`replay suppressed: reason=${this.barrierReason} sessionId=${this.sessionId}`);
+        }
+        return failure;
+    }
+}
+const INTERACTION_UPDATE_FIELDS = new Set([1, 2, 3, 4, 7, 13, 14, 16, 17]);
+const INTERACTION_QUERY_FIELDS = new Set([2, 3, 4, 7, 8, 9, 10, 11, 12, 13, 14]);
+const TOP_LEVEL_FIELDS = new Set([1, 2, 3, 4, 5, 7]);
+function nestedFields(topLevel, field) {
+    if (topLevel?.fn !== field || topLevel.wt !== 2 || !topLevel.bytes)
+        return [];
+    return readAllFieldsStrict(topLevel.bytes) ?? [];
+}
+function analyzeExecWire(topLevel) {
+    const variants = nestedFields(topLevel, 2)
+        .filter((field) => ![1, 15, 19].includes(field.fn));
+    const exactVariant = (field) => variants.length === 1 && variants[0].fn === field && variants[0].wt === 2;
+    return {
+        exactRequestContext: exactVariant(10),
+        exactMcpState: exactVariant(36),
+    };
+}
+function validKvWire(topLevel) {
+    const variants = nestedFields(topLevel, 4).filter((field) => field.fn !== 1);
+    const variant = variants.length === 1 ? variants[0] : undefined;
+    const args = variant?.wt === 2 && variant.bytes
+        ? (readAllFieldsStrict(variant.bytes) ?? [])
+        : [];
+    const blobIds = args.filter((field) => field.fn === 1 && field.wt === 2 && (field.bytes?.length ?? 0) > 0);
+    return !!variant
+        && [2, 3].includes(variant.fn)
+        && variant.wt === 2
+        && blobIds.length === 1
+        && args.every((field) => field.wt === 2 && (field.fn === 1 || (variant.fn === 3 && field.fn === 2)));
+}
+function validInteractionUpdateWire(topLevel, decoded) {
+    if (!decoded)
+        return true;
+    const fields = nestedFields(topLevel, 1);
+    const update = fields.length === 1 ? fields[0] : undefined;
+    if (!update || update.wt !== 2 || !INTERACTION_UPDATE_FIELDS.has(update.fn))
+        return false;
+    if (![1, 4].includes(update.fn))
+        return true;
+    const delta = update.bytes ? (readAllFieldsStrict(update.bytes) ?? []) : [];
+    return delta.length === 1 && delta[0].fn === 1 && delta[0].wt === 2;
+}
+function validInteractionQueryWire(topLevel, decoded) {
+    if (!decoded)
+        return true;
+    const fields = nestedFields(topLevel, 7);
+    const ids = fields.filter((field) => field.fn === 1);
+    const variants = fields.filter((field) => field.fn !== 1);
+    return ids.length <= 1
+        && ids.every((field) => field.wt === 0)
+        && variants.length === 1
+        && variants[0].wt === 2
+        && INTERACTION_QUERY_FIELDS.has(variants[0].fn);
+}
+function decodedMatchesWire(topLevel, decoded) {
+    return !((topLevel?.fn === 1 && !decoded.interactionUpdate)
+        || (topLevel?.fn === 2 && !decoded.exec)
+        || (topLevel?.fn === 4 && !decoded.kv)
+        || (topLevel?.fn === 5 && !decoded.execControl)
+        || (topLevel?.fn === 7 && !decoded.interactionQuery));
+}
+function hasSemanticProgress(decoded) {
+    const update = decoded.interactionUpdate;
+    const text = update?.text_delta?.text;
+    const thinking = update?.thinking_delta?.text;
+    return (typeof text === "string" && text.length > 0)
+        || (typeof thinking === "string" && thinking.length > 0)
+        || !!update?.turn_ended
+        || !!update?.tool_call_started
+        || !!update?.tool_call_completed
+        || !!decoded.exec
+        || !!decoded.kv
+        || !!decoded.execControl
+        || !!decoded.interactionQuery
+        || !!decoded.checkpointBytes?.length;
+}
+/** Classify one decoded server frame without performing any protocol side effects. */
+export function analyzeReplayFrame(payload, decoded) {
+    const topLevelFields = readAllFieldsStrict(payload) ?? [];
+    const topLevel = topLevelFields.length === 1 ? topLevelFields[0] : undefined;
+    const exec = analyzeExecWire(topLevel);
+    const validKv = validKvWire(topLevel);
+    const malformed = !topLevel
+        || topLevel.wt !== 2
+        || !TOP_LEVEL_FIELDS.has(topLevel.fn)
+        || !validInteractionUpdateWire(topLevel, decoded.interactionUpdate)
+        || !validInteractionQueryWire(topLevel, decoded.interactionQuery)
+        || !decodedMatchesWire(topLevel, decoded)
+        || !!decoded.execControl;
+    let barrier;
+    if (decoded.interactionUpdate?.tool_call_started || decoded.interactionUpdate?.tool_call_completed) {
+        barrier = "display-tool-lifecycle";
+    }
+    else if (malformed || (topLevel.fn === 4 && !validKv)) {
+        barrier = "unknown-or-malformed-frame";
+    }
+    else if (topLevel.fn === 2 && !exec.exactRequestContext && !exec.exactMcpState) {
+        barrier = "non-control-exec";
+    }
+    return {
+        semanticProgress: hasSemanticProgress(decoded),
+        barrier,
+    };
+}

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import type { BidiStream } from "./transport/connect.js";
 import { type CursorProviderError } from "./errors.js";
 import { type SessionActivitySource } from "./activity.js";
+import type { ToolAliasRegistry } from "./protocol/tools.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -117,6 +118,8 @@ export type CursorSession = {
     blobs: Map<string, Uint8Array>;
     /** McpToolDefinition list advertised this turn — echoed into the request_context reply. */
     toolDescriptors: Array<Record<string, unknown>>;
+    /** Cursor-facing web alias → exact executable host tool for this Run. */
+    toolAliases?: ToolAliasRegistry;
     /** Full RequestContext for exec #10 replies. */
     requestContext: Record<string, unknown>;
     /**

package/dist/shell-timeout.d.ts

@@ -27,6 +27,13 @@ export type CursorShellOutcome = {
     msToWait: number;
     reason: 1;
 };
+/** Track OpenCode's configured shell from the classic config hook. */
+export declare function setCursorShellPath(shell: string | undefined): void;
+/**
+ * Mirror the relevant part of OpenCode Shell.acceptable(): fish/nu are denied,
+ * then POSIX falls back to bash when installed and `/bin/sh` otherwise.
+ */
+export declare function resolveCursorShellKind(shell?: string | undefined): "bash" | "zsh" | "sh" | "dash" | "other";
 export declare function shellPolicyFromMetadata(metadata: Record<string, unknown> | undefined): CursorShellPolicy | undefined;
 /** Register a Cursor shell request before OpenCode executes its emitted tool call. */
 export declare function registerCursorShellCall(toolCallId: string, metadata: Record<string, unknown> | undefined): void;
@@ -58,15 +65,13 @@ export declare function buildBackgroundShellCommand(command: string): string;
 /**
  * Prepare OpenCode Bash args before execution when Cursor requested wrapping.
  *
- * Important: do **not** replace `args.command` with the wrapper script.
- * OpenCode's bash UI renders `state.input.command`, and `ctx.metadata()`
- * persists the execute-time `args` object into that field. Mutating
- * `args.command` therefore leaks the private wrapper into the TUI/GUI.
+ * bash/zsh source the shell.env injector, so the original command remains in
+ * OpenCode's permission/UI state. sh/dash ignore those startup variables; for
+ * them, use a short `exec wrapper.sh` command that contains no user payload.
  *
- * Wrapping is applied later via {@link cursorShellEnvForCall} (`shell.env`),
- * which uses BASH_ENV / ZDOTDIR injectors so bash/zsh `-c <original>` is
- * replaced with the wrapper while the stored/displayed command stays original.
- * Permissions also keep analyzing the real user command.
+ * background_shell_spawn may already contain the inline non-plugin fallback.
+ * The classic hook replaces it with the original command (bash/zsh) or the
+ * shorter wrapper-file command (sh/dash), avoiding duplicate execution.
  */
 export declare function prepareCursorShellArgs(toolCallId: string, args: Record<string, unknown>): void;
 /** Restore the model-facing command in OpenCode's completed tool title. */
@@ -74,8 +79,8 @@ export declare function cursorShellOriginalCommand(toolCallId: string): string |
 /** Drop injector temp files for a finished/abandoned Cursor shell call. */
 export declare function releaseCursorShellEnv(toolCallId: string): void;
 /**
- * Env vars for OpenCode's `shell.env` hook so bash/zsh execute the Cursor
- * wrapper while `args.command` (and therefore the bash UI) stay original.
+ * Env vars for OpenCode's shell.env hook. bash/zsh execute the injector; the
+ * same materialized wrapper backs the direct-command sh/dash fallback.
  */
 export declare function cursorShellEnvForCall(toolCallId: string | undefined): Record<string, string> | undefined;
 /**