cursor-opencode-provider 0.2.4 → 0.2.6

package/dist/protocol/tools.js

@@ -1,7 +1,9 @@
+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";
+import { BACKGROUND_SHELL_MARKER } 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.
@@ -133,8 +135,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 (original command; plugin wraps nohup)
+// 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",
@@ -207,7 +214,6 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
-const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -229,13 +235,16 @@ 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.
     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);
+            args.command = command;
         if (workingDirectory)
             args.workdir = workingDirectory;
         return {
@@ -244,7 +253,11 @@ export function parseExecServerMessage(msg) {
             toolName: "bash",
             args,
             resultField,
-            resultMetadata: { command: command ?? "", working_directory: workingDirectory },
+            resultMetadata: {
+                background_shell_spawn: true,
+                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
@@ -328,9 +341,16 @@ 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(msg[execVariant] ?? {})
-        : undefined;
+        ? 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") {
@@ -390,7 +410,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 {
@@ -522,20 +544,6 @@ function mapCursorSubagentTypeToOpenCode(subagentType) {
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/**
- * OpenCode's bash tool is foreground-only. Detach the requested command inside
- * that one foreground call 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.
- */
-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
@@ -646,7 +654,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, input.resultMetadata);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata, input.shellOutcome);
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -733,22 +741,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, resultMetadata) {
+export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome) {
     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 } };
@@ -809,6 +826,19 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             const workingDirectory = str(resultMetadata?.working_directory) ?? "";
             if (error)
                 return { error: { command, working_directory: workingDirectory, error } };
+            // Prefer the structured outcome captured by the plugin after-hook; markers
+            // are already stripped from the stored/rendered OpenCode output by then.
+            if (shellOutcome?.kind === "backgrounded") {
+                return {
+                    success: {
+                        shell_id: shellOutcome.shellId,
+                        command: shellOutcome.command || command,
+                        working_directory: shellOutcome.workingDirectory || workingDirectory,
+                        pid: shellOutcome.pid,
+                    },
+                };
+            }
+            // Fallback when no plugin hook ran: parse the private spawn marker inline.
             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) {
@@ -913,6 +943,93 @@ 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.

package/dist/session.d.ts

@@ -98,6 +98,8 @@ export type CursorSession = {
      * conversation_checkpoint_update (CLI parity).
     */
     conversationId: string;
+    /** Latest eligible checkpoint emitted by this Run attempt. */
+    resumeCheckpoint?: Uint8Array;
     /** OpenCode session whose own or descendant activity renews tool leases. */
     openCodeSessionId?: string;
     stream: BidiStream;

package/dist/shell-timeout.d.ts

@@ -1,12 +1,16 @@
 /** Cursor agent.v1 TimeoutBehavior enum values. */
 export declare const CURSOR_TIMEOUT_CANCEL = 1;
 export declare const CURSOR_TIMEOUT_BACKGROUND = 2;
+/** Private marker for Cursor `background_shell_spawn_args` detach wrappers. */
+export declare const BACKGROUND_SHELL_MARKER = "__CURSOR_BACKGROUND_SHELL__";
 export type CursorShellPolicy = {
     command: string;
     workingDirectory: string;
     timeoutMs: number;
     timeoutBehavior: number;
     hardTimeoutMs?: number;
+    /** Immediate nohup detach for Cursor `background_shell_spawn_args`. */
+    backgroundSpawn?: boolean;
 };
 export type CursorShellOutcome = {
     kind: "exit";
@@ -27,15 +31,60 @@ export declare function shellPolicyFromMetadata(metadata: Record<string, unknown
 /** Register a Cursor shell request before OpenCode executes its emitted tool call. */
 export declare function registerCursorShellCall(toolCallId: string, metadata: Record<string, unknown> | undefined): void;
 /**
+ * F11 / soft-background helper.
+ *
  * Run a Cursor soft-background command for its foreground window, then leave
- * it detached if still alive. The sentinel is removed by the after hook before
- * OpenCode stores/renders the result.
+ * it detached (`nohup`) if still alive. The sentinel is removed by the after
+ * hook before OpenCode stores/renders the result.
+ *
+ * This approximates Cursor's TIMEOUT_BACKGROUND semantics through OpenCode's
+ * foreground-only bash tool. Residual: after OpenCode returns, the child (and
+ * optional hard-timeout watchdog) may still be running; this provider does not
+ * reap leftover processes — cleanup is left to the user / OS.
  */
 export declare function buildSoftBackgroundCommand(policy: CursorShellPolicy): string;
-/** Mutate OpenCode Bash args before execution when Cursor requested soft backgrounding. */
+/**
+ * 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.
+ */
+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.
+ *
+ * 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.
+ */
 export declare function prepareCursorShellArgs(toolCallId: string, args: Record<string, unknown>): void;
 /** Restore the model-facing command in OpenCode's completed tool title. */
 export declare function cursorShellOriginalCommand(toolCallId: string): string | undefined;
+/** 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.
+ */
+export declare function cursorShellEnvForCall(toolCallId: string | undefined): Record<string, string> | undefined;
+/**
+ * Strip private wrapper sentinels / OpenCode timeout envelopes for display.
+ * Does not record outcomes — use {@link captureCursorShellResult} for that.
+ */
+export declare function sanitizeCursorShellDisplayOutput(output: string, policy?: CursorShellPolicy): string;
+/** Sanitize a secondary display string (e.g. Bash `metadata.output`) for a registered call. */
+export declare function sanitizeRegisteredCursorShellOutput(toolCallId: string, output: string): string;
 /**
  * Capture Bash completion in the classic plugin's after hook. Returns the
  * sanitized output that OpenCode should store and render.