cursor-opencode-provider 0.2.3 → 0.2.5

package/dist/protocol/tools.js

@@ -1,6 +1,8 @@
+import fs from "node:fs";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { trace } from "../debug.js";
+import { cursorExecVariantByRequestName } from "./exec-variants.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.
@@ -132,8 +134,13 @@ export function buildLiveRequestContext(tools, providerIdentifier = "opencode",
 // glob_args on the exec channel — Cursor's EditToolCall is display-only, and
 // glob/edit from opencode are advertised as MCP tools and arrive as mcp_args.
 //
-// OpenCode has no `ls` / `delete` builtins: ls → read (dirs are readable),
-// delete → bash `rm`. Arg key remapping happens in mapCursorArgsToOpencode.
+// Design note (F11): Cursor has native delete / background-shell tools; OpenCode
+// does not. This provider intentionally remaps:
+//   - delete_args → bash `rm -f -- <quoted-path>`
+//   - background_shell_spawn_args → bash + nohup detach wrapper
+// Permissions still flow through OpenCode's advertised `bash` tool. Soft-
+// background / detached children can outlive the OpenCode tool call; leftover
+// process cleanup is left to the user / OS. Arg key remapping happens below.
 const cursorToolToOpencode = {
     read_args: "read",
     write_args: "write",
@@ -148,6 +155,8 @@ const cursorToolToOpencode = {
     ls_args: "read",
     delete_args: "bash",
     shell_stream_args: "bash",
+    background_shell_spawn_args: "bash",
+    subagent_args: "task",
     mcp_args: "mcp",
 };
 const opencodeToolToCursor = {
@@ -155,6 +164,7 @@ const opencodeToolToCursor = {
     write: "write_args",
     grep: "grep_args",
     bash: "shell_stream_args",
+    task: "subagent_args",
     mcp: "mcp_args",
 };
 /** Cursor-only fields that must not be forwarded as OpenCode tool input. */
@@ -203,26 +213,7 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
-// Cursor exec-request variant → the ExecClientMessage result field the client
-// must reply with. This is keyed off the REQUEST variant, not the opencode tool
-// name, because an MCP call must always answer with `mcp_result` even though the
-// resolved tool name (e.g. "read") looks like a built-in.
-const execVariantToResultField = {
-    read_args: "read_result",
-    write_args: "write_result",
-    pi_read_args: "pi_read_result",
-    pi_bash_args: "pi_bash_result",
-    pi_edit_args: "pi_edit_result",
-    pi_write_args: "pi_write_result",
-    pi_grep_args: "pi_grep_result",
-    pi_find_args: "pi_find_result",
-    pi_ls_args: "pi_ls_result",
-    grep_args: "grep_result",
-    ls_args: "ls_result",
-    delete_args: "delete_result",
-    shell_stream_args: "shell_stream",
-    mcp_args: "mcp_result",
-};
+const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -233,12 +224,74 @@ export function parseExecServerMessage(msg) {
         "pi_read_args", "pi_bash_args", "pi_edit_args", "pi_write_args",
         "pi_grep_args", "pi_find_args", "pi_ls_args",
         "grep_args", "ls_args",
-        "delete_args", "shell_stream_args", "mcp_args",
+        "delete_args", "shell_stream_args", "background_shell_spawn_args", "mcp_args",
+        "subagent_args",
     ]);
     if (!execVariant)
         return undefined;
-    const resultField = execVariantToResultField[execVariant];
+    // Use the complete canonical request/result table. In particular, Pi request
+    // fields #45..#51 pair with result fields #46..#52 rather than matching ids.
+    const resultField = cursorExecVariantByRequestName(execVariant)?.resultName;
+    if (!resultField)
+        return undefined;
     const execId = msg.exec_id ?? "";
+    // F11: Cursor native background shell → OpenCode bash. The wrapper detaches
+    // via nohup immediately; OpenCode only sees the spawn marker (pid + log path).
+    // Residual: the child can keep running after this tool call completes.
+    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 = buildBackgroundShellCommand(command);
+        if (workingDirectory)
+            args.workdir = workingDirectory;
+        return {
+            id,
+            execId,
+            toolName: "bash",
+            args,
+            resultField,
+            resultMetadata: { command: command ?? "", working_directory: workingDirectory },
+            localError: raw.enable_write_shell_stdin_tool === true
+                ? "Interactive background shells are not available through OpenCode's bash tool."
+                : command
+                    ? undefined
+                    : "Cursor background shell request is missing a command.",
+        };
+    }
+    if (execVariant === "subagent_args") {
+        const raw = msg.subagent_args ?? {};
+        const prompt = str(raw.prompt);
+        const cursorSubagentType = str(raw.subagent_type);
+        const subagentType = cursorSubagentType
+            ? mapCursorSubagentTypeToOpenCode(cursorSubagentType)
+            : undefined;
+        const args = {
+            description: describeSubagentTask(prompt, subagentType),
+            prompt: prompt ?? "",
+            subagent_type: subagentType ?? "",
+        };
+        const resumeAgentId = str(raw.resume_agent_id);
+        if (resumeAgentId)
+            args.task_id = resumeAgentId;
+        // protobufjs materializes an absent proto3 optional bool as false in this
+        // reflection schema. OpenCode's foreground default is already false, so
+        // only forward the meaningful opt-in value.
+        if (raw.run_in_background === true)
+            args.background = true;
+        return {
+            id,
+            execId,
+            toolName: "task",
+            args,
+            resultField,
+            localError: prompt && cursorSubagentType
+                ? undefined
+                : "Cursor subagent request is missing a required prompt or subagent type.",
+        };
+    }
     if (execVariant === "mcp_args") {
         // An MCP call to one of the tools we advertised. Resolve the real opencode
         // tool name (Cursor's model may have shortened "opencode-read" → "read") and
@@ -284,12 +337,50 @@ export function parseExecServerMessage(msg) {
     if (!toolName)
         return undefined;
     const mapped = mapCursorArgsToOpencode(toolName, msg[execVariant] ?? {}, execVariant);
+    const rawArgs = msg[execVariant] ?? {};
+    const resultMetadata = execVariant === "shell_stream_args"
+        ? shellStreamResultMetadata(rawArgs)
+        : execVariant === "read_args"
+            ? {
+                path: str(rawArgs.path) ?? str(rawArgs.file_path) ?? "",
+                ...(typeof mapped.args.offset === "number" ? { offset: mapped.args.offset } : {}),
+                ...(typeof mapped.args.limit === "number" ? { limit: mapped.args.limit } : {}),
+            }
+            : undefined;
+    if (resultMetadata
+        && resultMetadata.timeout_behavior !== 2
+        && typeof resultMetadata.timeout_ms === "number") {
+        // Cursor's protobuf default (timeout=0) means 30 seconds for an ordinary
+        // foreground shell. OpenCode instead treats zero literally, so pass the
+        // effective native value rather than the raw protobuf default.
+        mapped.args.timeout = resultMetadata.timeout_ms;
+    }
     return {
         id,
         execId,
         toolName: mapped.toolName,
         args: mapped.args,
         resultField,
+        ...(resultMetadata ? { resultMetadata } : {}),
+    };
+}
+function shellStreamResultMetadata(raw) {
+    const timeout = num(raw.timeout) ?? 0;
+    const timeoutBehavior = num(raw.timeout_behavior) ?? 0;
+    const hardTimeout = num(raw.hard_timeout);
+    // Cursor CLI: a nonzero timeout is used verbatim. A zero foreground timeout
+    // defaults to 30s; zero with background/hard-timeout semantics means an
+    // immediate soft handoff governed by the separate hard deadline.
+    const effectiveTimeout = timeout !== 0
+        ? timeout
+        : (timeoutBehavior === 2 || (hardTimeout !== undefined && hardTimeout > 0) ? 0 : 30_000);
+    return {
+        shell_stream: true,
+        command: str(raw.command) ?? "",
+        working_directory: str(raw.working_directory) ?? "",
+        timeout_ms: effectiveTimeout,
+        timeout_behavior: timeoutBehavior,
+        ...(hardTimeout !== undefined && hardTimeout > 0 ? { hard_timeout_ms: hardTimeout } : {}),
     };
 }
 /**
@@ -315,7 +406,9 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant) {
         const filePath = str(cleaned.path) ?? str(cleaned.filePath);
         return { toolName: "read", args: filePath ? { filePath } : {} };
     }
-    // Native delete_args → bash rm (OpenCode has no delete builtin).
+    // F11: Cursor native delete_args → OpenCode bash. No delete builtin exists, so
+    // we emulate with `rm -f -- <path>` (shell-quoted). Same permission boundary
+    // as any other bash tool call.
     if (execVariant === "delete_args") {
         const target = str(cleaned.path) ?? str(cleaned.filePath);
         return {
@@ -425,9 +518,47 @@ function num(v) {
         return Number(v);
     return undefined;
 }
+function describeSubagentTask(prompt, subagentType) {
+    const words = prompt?.replace(/\s+/g, " ").trim().split(" ").filter(Boolean).slice(0, 5);
+    if (words?.length)
+        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, `'\\''`)}'`;
 }
+/**
+ * F11 / background_shell_spawn_args helper.
+ *
+ * OpenCode's bash tool is foreground-only. Detach the requested command inside
+ * that one foreground call (`nohup … &`) and print a private marker containing
+ * the spawned PID and log path. With stdin and all output redirected, the host
+ * shell can return immediately instead of retaining OpenCode's tool pipe.
+ *
+ * Residual: the detached child is not reaped by this provider after OpenCode
+ * completes the tool call; cleanup is left to the user / OS.
+ */
+function buildBackgroundShellCommand(command) {
+    return [
+        'bg_log="$(mktemp "${TMPDIR:-/tmp}/cursor-opencode-bg.XXXXXX")" || exit 1',
+        `nohup sh -c ${shellQuote(command)} >"$bg_log" 2>&1 </dev/null &`,
+        "bg_pid=$!",
+        `printf '${BACKGROUND_SHELL_MARKER}%s:%s\\n' "$bg_pid" "$bg_log"`,
+    ].join("\n");
+}
 /**
  * Map Cursor McpArgs back to the OpenCode tool id.
  * Prefers provider_identifier + bare tool_name (github + create_pull_request
@@ -505,9 +636,32 @@ export function buildExecClientMessages(input) {
             if (input.output) {
                 frames.push(encodeShellStream(input.execId, undefined, { stdout: { data: input.output } }));
             }
-            frames.push(encodeShellStream(input.execId, input.executionTimeMs, {
-                exit: { code: 0, aborted: false },
-            }));
+            if (input.shellOutcome?.kind === "backgrounded") {
+                frames.push(encodeShellStream(input.execId, input.executionTimeMs, {
+                    backgrounded: {
+                        shell_id: input.shellOutcome.shellId,
+                        command: input.shellOutcome.command,
+                        working_directory: input.shellOutcome.workingDirectory,
+                        pid: input.shellOutcome.pid,
+                        ms_to_wait: input.shellOutcome.msToWait,
+                        reason: input.shellOutcome.reason,
+                    },
+                }));
+            }
+            else if (input.shellOutcome?.kind === "timeout") {
+                frames.push(encodeShellStream(input.execId, input.executionTimeMs, {
+                    // Native CLI represents timeout structurally. ShellAbortReason.TIMEOUT=2.
+                    exit: { code: 0, aborted: true, abort_reason: 2 },
+                }));
+            }
+            else {
+                const exitCode = input.shellOutcome?.kind === "exit"
+                    ? Math.max(0, Math.min(0xffff_ffff, input.shellOutcome.code))
+                    : 0;
+                frames.push(encodeShellStream(input.execId, input.executionTimeMs, {
+                    exit: { code: exitCode, aborted: false },
+                }));
+            }
         }
     }
     else {
@@ -515,7 +669,7 @@ export function buildExecClientMessages(input) {
             id: input.execId,
             local_execution_time_ms: input.executionTimeMs ?? 0,
         };
-        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata);
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -602,22 +756,31 @@ export function unwrapReadOutput(output) {
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export function buildTypedExecResult(resultField, output, error, toolName) {
+export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata) {
     switch (resultField) {
-        case "read_result":
+        case "read_result": {
+            const readPath = str(resultMetadata?.path) ?? extractPathTag(output) ?? "";
             if (error)
-                return { error: { path: "", error } };
+                return { error: { path: readPath, error } };
             // Strip opencode's <path>/<content> envelope so Cursor's model receives
             // raw file content and can't echo the wrapper into subsequent writes.
             // reads route here only for native read_args; most arrive via mcp_result.
             const content = unwrapReadOutput(output);
+            const statPath = extractPathTag(output) ?? readPath;
+            const outputMetadata = parseOpenCodeReadMetadata(output);
+            const totalLines = outputMetadata.totalLines ?? readFileLineCount(statPath) ?? countLines(content);
+            const rangeApplied = readRangeApplied(resultMetadata, totalLines);
             return {
                 success: {
-                    path: extractPathTag(output) ?? "",
+                    path: readPath,
                     content,
-                    total_lines: countLines(content),
+                    total_lines: totalLines,
+                    file_size: readFileSize(statPath),
+                    truncated: readOutputTruncated(resultMetadata, outputMetadata, totalLines),
+                    range_applied: rangeApplied,
                 },
             };
+        }
         case "grep_result": {
             if (error)
                 return { error: { error } };
@@ -673,6 +836,31 @@ export function buildTypedExecResult(resultField, output, error, toolName) {
             if (error)
                 return { error: { path: "", error } };
             return { success: { path: "", deleted_file: "" } };
+        case "background_shell_spawn_result": {
+            const command = str(resultMetadata?.command) ?? "";
+            const workingDirectory = str(resultMetadata?.working_directory) ?? "";
+            if (error)
+                return { error: { command, working_directory: workingDirectory, error } };
+            const match = new RegExp(`${BACKGROUND_SHELL_MARKER}(\\d+):([^\\r\\n]+)`).exec(output);
+            const pid = match ? Number(match[1]) : 0;
+            if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0xffff_ffff) {
+                return {
+                    error: {
+                        command,
+                        working_directory: workingDirectory,
+                        error: "OpenCode did not return a valid background shell process id.",
+                    },
+                };
+            }
+            return {
+                success: {
+                    shell_id: pid,
+                    command,
+                    working_directory: workingDirectory,
+                    pid,
+                },
+            };
+        }
         case "ls_result": {
             if (error)
                 return { error: { path: "", error } };
@@ -706,6 +894,27 @@ export function buildTypedExecResult(resultField, output, error, toolName) {
                     is_error: false,
                 },
             };
+        case "subagent_result": {
+            const task = parseOpenCodeTaskOutput(output);
+            if (error || task.state === "error") {
+                return {
+                    error: {
+                        ...(task.agentId ? { agent_id: task.agentId } : {}),
+                        error: error ?? task.message ?? output,
+                    },
+                };
+            }
+            return {
+                success: {
+                    agent_id: task.agentId ?? "",
+                    ...(task.message !== undefined ? { final_message: task.message } : {}),
+                    tool_call_count: 0,
+                    // OpenCode marks an asynchronous launch as state="running". Cursor's
+                    // canonical USER_REQUEST enum value is 2; foreground/default is 0.
+                    background_reason: task.state === "running" ? 2 : 0,
+                },
+            };
+        }
         default:
             // Unknown variant: best-effort success wrapper so the server sees a oneof.
             if (error)
@@ -713,10 +922,116 @@ export function buildTypedExecResult(resultField, output, error, toolName) {
             return { success: { content: output } };
     }
 }
+function parseOpenCodeTaskOutput(output) {
+    // Attribute order is not guaranteed; accept id/state in either order and
+    // ignore additional attributes OpenCode may emit on the <task> open tag.
+    const open = /<task\b([^>]*)>/i.exec(output);
+    if (!open)
+        return { message: output };
+    const attrs = open[1];
+    const agentId = /\bid="([^"]+)"/i.exec(attrs)?.[1];
+    const state = /\bstate="(running|completed|error)"/i.exec(attrs)?.[1];
+    if (!agentId || !state)
+        return { message: output };
+    const tag = state === "error" ? "task_error" : "task_result";
+    const body = new RegExp(`<${tag}>\\n?([\\s\\S]*?)\\n?</${tag}>`, "i").exec(output);
+    return {
+        agentId,
+        state,
+        message: body?.[1] ?? output,
+    };
+}
 function extractPathTag(output) {
     const m = output.match(/<path>([^<]+)<\/path>/);
     return m?.[1];
 }
+/** Recover full-file metadata before unwrapReadOutput removes OpenCode's footer. */
+function parseOpenCodeReadMetadata(output) {
+    const showing = /Showing lines (\d+)-(\d+)(?: of (\d+))?\./.exec(output);
+    if (showing) {
+        return {
+            startLine: Number(showing[1]),
+            endLine: Number(showing[2]),
+            ...(showing[3] ? { totalLines: Number(showing[3]) } : {}),
+            outputCapped: output.includes("(Output capped at "),
+        };
+    }
+    const complete = /\(End of file - total (\d+) lines?\)/.exec(output);
+    if (complete)
+        return { totalLines: Number(complete[1]) };
+    return {};
+}
+function readRangeApplied(resultMetadata, totalLines) {
+    const offset = num(resultMetadata?.offset);
+    const limit = num(resultMetadata?.limit);
+    if (offset === undefined && limit === undefined)
+        return false;
+    if (totalLines === 0)
+        return false;
+    const startLine = offset ?? 1;
+    return startLine < 0 || startLine <= totalLines;
+}
+function readOutputTruncated(resultMetadata, outputMetadata, totalLines) {
+    if (outputMetadata.outputCapped)
+        return true;
+    const returnedEnd = outputMetadata.endLine;
+    if (returnedEnd === undefined || totalLines === 0)
+        return false;
+    const offset = num(resultMetadata?.offset);
+    const limit = num(resultMetadata?.limit);
+    const startLine = offset ?? 1;
+    if (startLine < 0)
+        return false;
+    const expectedEnd = limit === undefined
+        ? totalLines
+        : Math.min(totalLines, Math.max(1, startLine) + limit - 1);
+    return returnedEnd < expectedEnd;
+}
+function readFileSize(filePath) {
+    if (!filePath)
+        return 0;
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function readFileLineCount(filePath) {
+    if (!filePath)
+        return undefined;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let totalBytes = 0;
+        let lines = 1;
+        while (true) {
+            const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            totalBytes += bytesRead;
+            for (let index = 0; index < bytesRead; index++) {
+                if (buffer[index] === 0x0a)
+                    lines++;
+            }
+        }
+        return totalBytes === 0 ? 0 : lines;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+}
 function extractPathLines(output) {
     const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
     // Prefer absolute / relative path-looking lines; fall back to all non-empty.
@@ -824,16 +1139,28 @@ export function buildMcpStateResult(execId, args, requestContext) {
         ? fsOptions.mcp_descriptors.map(recordValue).filter((d) => !!d)
         : [];
     const descriptors = nested.length > 0 ? nested : descriptorsFromFlatTools(requestContext.tools);
+    const flatTools = Array.isArray(requestContext.tools)
+        ? requestContext.tools.map(recordValue).filter((tool) => !!tool)
+        : [];
     const servers = descriptors
         .filter((descriptor) => {
         const id = stringValue(descriptor.server_identifier);
         return requested.size === 0 || (id !== undefined && requested.has(id));
     })
-        .map((descriptor) => ({
-        server_name: stringValue(descriptor.server_name) ?? stringValue(descriptor.server_identifier) ?? "",
-        server_identifier: stringValue(descriptor.server_identifier) ?? stringValue(descriptor.server_name) ?? "",
-        tools: Array.isArray(descriptor.tools) ? descriptor.tools : [],
-    }));
+        .map((descriptor) => {
+        const serverIdentifier = stringValue(descriptor.server_identifier) ?? stringValue(descriptor.server_name) ?? "";
+        const tools = Array.isArray(descriptor.tools)
+            ? descriptor.tools
+                .map(recordValue)
+                .filter((tool) => !!tool)
+                .map((tool) => mcpStateToolDefinition(serverIdentifier, tool, flatTools))
+            : [];
+        return {
+            server_name: stringValue(descriptor.server_name) ?? serverIdentifier,
+            server_identifier: serverIdentifier,
+            tools,
+        };
+    });
     return encodeMessage("AgentClientMessage", {
         exec_client_message: {
             id: execId,
@@ -841,6 +1168,24 @@ export function buildMcpStateResult(execId, args, requestContext) {
         },
     });
 }
+/**
+ * Exec #36 uses McpToolDefinition, not the narrower McpToolDescriptor used by
+ * RequestContext's filesystem/meta-tool catalogs. Rehydrate the full identity
+ * from RequestContext.tools so Cursor's native get_mcp_tools can correlate the
+ * discovered definition with the later provider_identifier/tool_name request.
+ */
+function mcpStateToolDefinition(serverIdentifier, descriptor, flatTools) {
+    const toolName = stringValue(descriptor.tool_name) ?? "";
+    const advertised = flatTools.find((tool) => stringValue(tool.provider_identifier) === serverIdentifier
+        && stringValue(tool.tool_name) === toolName);
+    return {
+        name: stringValue(advertised?.name) ?? `${serverIdentifier}-${toolName}`,
+        description: stringValue(advertised?.description) ?? stringValue(descriptor.description) ?? "",
+        input_schema: advertised?.input_schema ?? descriptor.input_schema,
+        provider_identifier: serverIdentifier,
+        tool_name: toolName,
+    };
+}
 function recordValue(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value