cursor-opencode-provider 0.2.9 → 0.3.1

package/dist/protocol/tools.js

@@ -7,6 +7,7 @@ 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 { APPLY_PATCH_TOOL, buildAddFilePatch, buildUpdateFilePatch, planSubstringEdit, } from "./apply-patch.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
@@ -260,11 +261,15 @@ const CURSOR_INTERNAL_KEYS = new Set([
     "close_stdin",
     "output_notification",
     "file_output_threshold_bytes",
+    // WriteArgs #4. A request for WriteSuccess.file_content_after_write, which we
+    // do not populate; harmless to omit, but it is not tool input.
     "return_file_content_after_write",
-    "file_bytes",
-    "encoding_hint",
     "ignore",
 ]);
+// WriteArgs #5/#6 are deliberately NOT internal: `file_bytes` carries the file
+// content itself whenever Cursor sends it instead of `file_text` (its own
+// LocalWriteExecutor prefers bytes when non-empty), and `encoding_hint` is how
+// that payload is decoded. The `write` mapping consumes both explicitly.
 /** Required content fields where an empty string is meaningful (for example, truncating a file). */
 const PRESERVE_EMPTY_STRING_KEYS = new Set([
     "content",
@@ -476,6 +481,92 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
         },
     };
 }
+/** Matches Cursor's own pre-write read threshold (`local-exec` 52428800). */
+const MAX_EDIT_SOURCE_BYTES = 50 * 1024 * 1024;
+/**
+ * Express a native Cursor write/edit as `apply_patch` when the host swapped the
+ * edit-tool family out from under us.
+ *
+ * OpenCode 1.x removes `edit` and `write` from the catalog for GPT models and
+ * advertises `apply_patch` in their place — see the module comment in
+ * `./apply-patch.ts` for the upstream reasoning and citations. Cursor keeps
+ * using its native write/edit exec channel regardless, so without this the
+ * request is refused as an unavailable tool and the model loses the ability to
+ * change files at all.
+ *
+ * Keyed purely off the advertised set: this is inert whenever the host offers
+ * `write`/`edit` normally, and equally inert when it offers neither those nor
+ * `apply_patch` (the caller's unavailable-tool rejection still applies).
+ */
+export function remapEditToolsForCatalog(parsed, advertisedToolNames, workspaceRoot) {
+    if (parsed.toolName !== "write" && parsed.toolName !== "edit")
+        return;
+    const advertised = new Set(advertisedToolNames);
+    if (advertised.has(parsed.toolName) || !advertised.has(APPLY_PATCH_TOOL))
+        return;
+    const requested = parsed.toolName;
+    const filePath = str(parsed.args.filePath);
+    const refuse = (reason) => {
+        parsed.toolName = APPLY_PATCH_TOOL;
+        parsed.args = {};
+        parsed.localError =
+            `Cursor ${requested} request cannot be expressed as an apply_patch call: ${reason}. ` +
+                "The host advertises `apply_patch` instead of `edit`/`write` for this model.";
+    };
+    if (!filePath) {
+        refuse("no target path was provided");
+        return;
+    }
+    let patchText;
+    if (requested === "write") {
+        const content = stringValue(parsed.args.content);
+        if (content === undefined) {
+            refuse("no file content was provided");
+            return;
+        }
+        // `*** Add File:` overwrites an existing target, so a whole-file write maps
+        // directly without reading the current contents or diffing.
+        patchText = buildAddFilePatch(filePath, content);
+    }
+    else {
+        const oldString = stringValue(parsed.args.oldString);
+        const newString = stringValue(parsed.args.newString);
+        if (oldString === undefined || newString === undefined) {
+            refuse("the replacement is missing its old or new text");
+            return;
+        }
+        // apply_patch matches whole lines, so a substring edit has to be widened to
+        // the lines it touches — which requires the file the model is editing.
+        const absolute = path.resolve(workspaceRoot ?? process.cwd(), filePath);
+        let source;
+        try {
+            // Bounded because this read is synchronous on the Run pump. Cursor's own
+            // executor uses the same 50 MB threshold before reading a file it is
+            // about to write.
+            const size = fs.statSync(absolute).size;
+            if (size > MAX_EDIT_SOURCE_BYTES) {
+                refuse(`the target file is ${Math.round(size / 1024 / 1024)} MB, too large to patch`);
+                return;
+            }
+            source = fs.readFileSync(absolute, "utf8");
+        }
+        catch (e) {
+            refuse(`the target file could not be read (${e.message})`);
+            return;
+        }
+        const plan = planSubstringEdit(source, oldString, newString, parsed.args.replaceAll === true);
+        if (!plan.ok) {
+            refuse(plan.reason);
+            return;
+        }
+        patchText = buildUpdateFilePatch(filePath, plan.chunks);
+    }
+    parsed.toolName = APPLY_PATCH_TOOL;
+    parsed.args = { patchText };
+    // apply_patch's output does not carry opencode `write`'s <path> tag, so keep
+    // the requested path for the typed Cursor result.
+    parsed.resultMetadata = { ...parsed.resultMetadata, path: filePath };
+}
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -707,7 +798,13 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant) {
             const filePath = str(cleaned.filePath) ?? str(cleaned.path) ?? str(cleaned.file_path);
             if (filePath)
                 args.filePath = filePath;
-            const content = stringValue(cleaned.content) ?? stringValue(cleaned.file_text) ?? stringValue(cleaned.fileText);
+            // Cursor's LocalWriteExecutor prefers `file_bytes` whenever it is
+            // non-empty and only falls back to `file_text`; mirror that order so a
+            // byte-encoded write is not silently seen as empty content.
+            const bytes = bytesValue(cleaned.file_bytes) ?? bytesValue(cleaned.fileBytes);
+            const content = bytes !== undefined
+                ? decodeWriteBytes(bytes, str(cleaned.encoding_hint) ?? str(cleaned.encodingHint))
+                : stringValue(cleaned.content) ?? stringValue(cleaned.file_text) ?? stringValue(cleaned.fileText);
             if (content !== undefined)
                 args.content = content;
             return { toolName: "write", args };
@@ -781,6 +878,32 @@ function str(v) {
 function stringValue(v) {
     return typeof v === "string" ? v : undefined;
 }
+/** A non-empty protobuf `bytes` field, or undefined when absent/empty. */
+function bytesValue(v) {
+    if (v instanceof Uint8Array)
+        return v.length > 0 ? v : undefined;
+    if (Array.isArray(v) && v.every((b) => typeof b === "number")) {
+        return v.length > 0 ? Uint8Array.from(v) : undefined;
+    }
+    return undefined;
+}
+/**
+ * Decode `WriteArgs.file_bytes`. `encoding_hint` names the file's original
+ * encoding; OpenCode's `write` takes a string, so anything Node cannot decode
+ * falls back to UTF-8 rather than dropping the write.
+ */
+function decodeWriteBytes(bytes, encodingHint) {
+    const encoding = encodingHint?.trim().toLowerCase().replace(/[_ ]/g, "-");
+    if (encoding && encoding !== "utf-8" && encoding !== "utf8") {
+        try {
+            return new TextDecoder(encoding, { fatal: false }).decode(bytes);
+        }
+        catch {
+            trace(`write: unsupported encoding_hint ${JSON.stringify(encodingHint)} — decoding as utf-8`);
+        }
+    }
+    return new TextDecoder("utf-8").decode(bytes);
+}
 function num(v) {
     if (typeof v === "number" && Number.isFinite(v))
         return v;
@@ -976,7 +1099,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, input.shellOutcome);
+        clientMsg[resultField] = buildTypedExecResult(resultField, input.output, input.error, input.toolName, input.resultMetadata, input.shellOutcome, input.workspaceRoot);
         frames.push(encodeMessage("AgentClientMessage", {
             exec_client_message: clientMsg,
         }));
@@ -1063,7 +1186,12 @@ 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, shellOutcome) {
+export function buildTypedExecResult(resultField, output, error, toolName, resultMetadata, shellOutcome, workspaceRoot) {
+    // Prefer the session workspace; never advertise the host process cwd (daemon
+    // often starts in $HOME) as the path Cursor shows the model for glob/ls.
+    const resultRoot = typeof workspaceRoot === "string" && workspaceRoot.trim()
+        ? path.resolve(workspaceRoot)
+        : undefined;
     switch (resultField) {
         case "read_result": {
             const readPath = str(resultMetadata?.path) ?? extractPathTag(output) ?? "";
@@ -1071,16 +1199,22 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                 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.
+            // Cursor's native read_args lands here; `mcp_args` reads land in
+            // mcp_result. Live captures show gpt-5.4-mini and grok-4.5 both use the
+            // native channel, so this is the path that matters in practice.
             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);
+            // `truncated` alone is not enough: it is set here, and models still assert
+            // the partial content is the whole file. Cursor's own executor puts the
+            // limit marker in the output text for the same reason, so append one.
+            const notice = readTruncationNotice(output, resultMetadata);
             return {
                 success: {
                     path: readPath,
-                    content,
+                    content: notice ? `${content}\n\n${notice}` : content,
                     total_lines: totalLines,
                     file_size: readFileSize(statPath),
                     truncated: readOutputTruncated(resultMetadata, outputMetadata, totalLines),
@@ -1094,7 +1228,7 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
             // Prefer files_with_matches: OpenCode glob/grep often returns path lists.
             // Content-mode GrepSuccess also works but needs GrepFileMatch nesting.
             const files = extractPathLines(output);
-            const cwd = process.cwd();
+            const cwd = resultRoot ?? "";
             return {
                 success: {
                     pattern: "",
@@ -1112,25 +1246,34 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                 },
             };
         }
-        case "write_result":
+        case "write_result": {
+            // `apply_patch` output carries no <path> tag, so prefer the path recorded
+            // when the request was remapped away from `write`.
+            const remappedPath = str(resultMetadata?.path);
             if (error)
-                return { error: { path: "", error } };
+                return { error: { path: remappedPath ?? "", error } };
             return {
                 success: {
-                    path: extractPathTag(output) ?? "",
+                    path: remappedPath ?? extractPathTag(output) ?? "",
                     lines_created: countLines(output),
                     file_size: output.length,
                 },
             };
+        }
         case "pi_write_result":
             // PiWriteExecSuccess is just { output }; error is { error }.
             if (error)
                 return { error: { error } };
             return { success: { output: output || "Wrote file successfully." } };
-        case "pi_read_result":
+        case "pi_read_result": {
             if (error)
                 return { error: { error } };
-            return { success: { output: unwrapReadOutput(output) } };
+            // Pi results carry truncation structurally (PiReadExecSuccess field 2),
+            // which is how Cursor's own executors report a capped payload.
+            const content = unwrapReadOutput(output);
+            const truncation = readTruncationMessage(output, content);
+            return { success: { output: content, ...(truncation ? { truncation } : {}) } };
+        }
         case "pi_bash_result":
         case "pi_edit_result":
         case "pi_grep_result":
@@ -1184,7 +1327,7 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
         case "ls_result": {
             if (error)
                 return { error: { path: "", error } };
-            const rootPath = process.cwd();
+            const rootPath = resultRoot ?? "";
             const entries = extractPathLines(output);
             return {
                 success: {
@@ -1199,21 +1342,29 @@ export function buildTypedExecResult(resultField, output, error, toolName, resul
                 },
             };
         }
-        case "mcp_result":
+        case "mcp_result": {
             if (error)
                 return { error: { error } };
             // opencode built-ins (read/write/grep/…) are advertised as MCP tools, so
             // a read call returns through mcp_result. Scope the unwrap to toolName
             // "read" so a non-read MCP tool whose output merely contains a
             // "<content>"-like block is never rewritten.
+            if (toolName !== "read") {
+                return { success: { content: [{ text: { text: output } }], is_error: false } };
+            }
+            // Carry the truncation notice as its own content item: the file content
+            // item stays byte-exact, so it can still never be echoed into a write.
+            const notice = readTruncationNotice(output);
             return {
                 success: {
                     content: [
-                        { text: { text: toolName === "read" ? unwrapReadOutput(output) : output } },
+                        { text: { text: unwrapReadOutput(output) } },
+                        ...(notice ? [{ text: { text: notice } }] : []),
                     ],
                     is_error: false,
                 },
             };
+        }
         case "subagent_result": {
             const task = parseOpenCodeTaskOutput(output);
             if (error || task.state === "error") {
@@ -1265,22 +1416,114 @@ function extractPathTag(output) {
     const m = output.match(/<path>([^<]+)<\/path>/);
     return m?.[1];
 }
+/**
+ * Isolate opencode's read footer: the last blank-line-separated block before
+ * the closing `</content>`. Scanning the whole envelope would let a file that
+ * merely *quotes* a footer (this repository's own docs and tests do) pass for a
+ * truncated read. The body can never contain a blank line — every source line
+ * is rendered as `N: …`, so even an empty line keeps its `N: ` prefix.
+ *
+ * Falls back to the full string when the envelope is absent, preserving
+ * behavior for non-standard read output.
+ */
+function readEnvelopeFooter(output) {
+    const close = output.lastIndexOf("\n</content>");
+    if (close === -1)
+        return output;
+    const start = output.lastIndexOf("\n\n", close);
+    if (start === -1)
+        return output;
+    return output.slice(start + 2, close);
+}
 /** Recover full-file metadata before unwrapReadOutput removes OpenCode's footer. */
 function parseOpenCodeReadMetadata(output) {
-    const showing = /Showing lines (\d+)-(\d+)(?: of (\d+))?\./.exec(output);
+    const footer = readEnvelopeFooter(output);
+    const showing = /Showing lines (\d+)-(\d+)(?: of (\d+))?\./.exec(footer);
     if (showing) {
         return {
             startLine: Number(showing[1]),
             endLine: Number(showing[2]),
             ...(showing[3] ? { totalLines: Number(showing[3]) } : {}),
-            outputCapped: output.includes("(Output capped at "),
+            outputCapped: footer.includes("(Output capped at "),
         };
     }
-    const complete = /\(End of file - total (\d+) lines?\)/.exec(output);
+    const complete = /\(End of file - total (\d+) lines?\)/.exec(footer);
     if (complete)
         return { totalLines: Number(complete[1]) };
     return {};
 }
+/**
+ * OpenCode's `read` caps output at 50 KB (`tool/read.ts` MAX_BYTES = 50 * 1024)
+ * and cuts on a whole-line boundary, then appends
+ * "(Output capped at 50 KB. Showing lines X-Y. Use offset=N to continue.)".
+ *
+ * `unwrapReadOutput` strips that footer along with the envelope, deliberately:
+ * Cursor's model echoes whatever it is handed straight back into the next
+ * write, so anything left in the content stream can end up written into the
+ * file. But dropping the notice with no replacement is worse — the model then
+ * believes a capped read is the complete file, rewrites it from what it has,
+ * and everything past the cap is destroyed.
+ *
+ * Cursor's own CLI never truncates silently. Its local executor annotates every
+ * capped payload ("50KB limit reached", "[Showing last …KB of line N (50KB
+ * limit). Full output: …]") and returns structured truncation metadata. Mirror
+ * that, keeping the signal out of the file content itself so it still cannot be
+ * echoed into a write.
+ */
+function readTruncationSummary(output) {
+    const meta = parseOpenCodeReadMetadata(output);
+    if (meta.startLine === undefined || meta.endLine === undefined)
+        return undefined;
+    // A complete read reports "(End of file …)" and never reaches this shape.
+    if (meta.totalLines !== undefined && meta.endLine >= meta.totalLines && !meta.outputCapped)
+        return undefined;
+    return {
+        startLine: meta.startLine,
+        endLine: meta.endLine,
+        nextOffset: meta.endLine + 1,
+        capped: meta.outputCapped === true,
+        ...(meta.totalLines !== undefined ? { totalLines: meta.totalLines } : {}),
+    };
+}
+/**
+ * Model-visible replacement for the stripped footer.
+ *
+ * Only for reads the model did not ask to bound. A caller that passed an
+ * explicit offset/limit already knows it asked for a slice — warning there
+ * would cry wolf on every deliberate paged read.
+ */
+function readTruncationNotice(output, resultMetadata) {
+    const summary = readTruncationSummary(output);
+    if (!summary)
+        return undefined;
+    const rangeRequested = num(resultMetadata?.offset) !== undefined || num(resultMetadata?.limit) !== undefined;
+    if (rangeRequested && !summary.capped)
+        return undefined;
+    const range = summary.totalLines !== undefined
+        ? `lines ${summary.startLine}-${summary.endLine} of ${summary.totalLines}`
+        : `lines ${summary.startLine}-${summary.endLine}`;
+    return (`[Partial read: the content above is ${range}` +
+        (summary.capped ? ", capped at the host's 50 KB output limit" : "") +
+        `. It is NOT the complete file. Continue with offset=${summary.nextOffset} before ` +
+        `acting on the whole file; writing the content above back would delete everything ` +
+        `after line ${summary.endLine}.]`);
+}
+/** agent.v1.PiTruncation for a capped OpenCode read. */
+function readTruncationMessage(output, content) {
+    const summary = readTruncationSummary(output);
+    if (!summary)
+        return undefined;
+    return {
+        truncated: true,
+        truncated_by: summary.capped ? "bytes" : "lines",
+        ...(summary.totalLines !== undefined ? { total_lines: summary.totalLines } : {}),
+        output_lines: Math.max(0, summary.endLine - summary.startLine + 1),
+        output_bytes: Buffer.byteLength(content, "utf8"),
+        ...(summary.capped ? { max_bytes: OPENCODE_READ_MAX_BYTES } : {}),
+    };
+}
+/** `tool/read.ts` MAX_BYTES — mirrored only to report the cap, never to apply it. */
+const OPENCODE_READ_MAX_BYTES = 50 * 1024;
 function readRangeApplied(resultMetadata, totalLines) {
     const offset = num(resultMetadata?.offset);
     const limit = num(resultMetadata?.limit);

package/dist/session-directory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Session-scoped workspace directory for the OpenCode 2.0 plugin.
+ *
+ * The classic plugin learns the project directory from `input.directory`,
+ * supplied once per invocation by the 1.x host. OpenCode 2.0 runs a single
+ * daemon across many projects, so `process.cwd()` captured at sdk-creation
+ * time is wrong for any session but the one open when the daemon started.
+ * The only place the 2.0 runtime names a session's actual directory is
+ * `SessionInfo.location.directory`, reachable from `session.hook("context")`'s
+ * `sessionID` via `ctx.session.get()`. Record it there and let the provider
+ * read it back by session id, same mechanism as `compaction-marker.ts`.
+ *
+ * Bounded so a long-lived server cannot accumulate ids for dead sessions.
+ */
+export declare function markSessionDirectory(sessionID: string, directory: string | undefined): void;
+export declare function getSessionDirectory(sessionID: string | undefined): string | undefined;
+export declare function clearSessionDirectories(): void;

package/dist/session-directory.js

@@ -0,0 +1,35 @@
+/**
+ * Session-scoped workspace directory for the OpenCode 2.0 plugin.
+ *
+ * The classic plugin learns the project directory from `input.directory`,
+ * supplied once per invocation by the 1.x host. OpenCode 2.0 runs a single
+ * daemon across many projects, so `process.cwd()` captured at sdk-creation
+ * time is wrong for any session but the one open when the daemon started.
+ * The only place the 2.0 runtime names a session's actual directory is
+ * `SessionInfo.location.directory`, reachable from `session.hook("context")`'s
+ * `sessionID` via `ctx.session.get()`. Record it there and let the provider
+ * read it back by session id, same mechanism as `compaction-marker.ts`.
+ *
+ * Bounded so a long-lived server cannot accumulate ids for dead sessions.
+ */
+const MAX_TRACKED_SESSIONS = 256;
+const sessionDirectories = new Map();
+export function markSessionDirectory(sessionID, directory) {
+    if (!sessionID || !directory)
+        return;
+    // Re-insert to keep insertion order meaningful for the eviction below.
+    sessionDirectories.delete(sessionID);
+    sessionDirectories.set(sessionID, directory);
+    while (sessionDirectories.size > MAX_TRACKED_SESSIONS) {
+        const oldest = sessionDirectories.keys().next().value;
+        if (oldest === undefined)
+            break;
+        sessionDirectories.delete(oldest);
+    }
+}
+export function getSessionDirectory(sessionID) {
+    return typeof sessionID === "string" ? sessionDirectories.get(sessionID) : undefined;
+}
+export function clearSessionDirectories() {
+    sessionDirectories.clear();
+}

package/dist/session.d.ts

@@ -50,7 +50,7 @@ export type PendingExec = {
      */
     bridged?: boolean;
 };
-export type ContinuationTerminalReason = "hard-cap-expired" | "remote-clean-close" | "remote-error" | "result-write-failed" | "ambiguous-partial-write" | "heartbeat-write-failed" | "reply-write-failed" | "process-disposed";
+export type ContinuationTerminalReason = "hard-cap-expired" | "remote-clean-close" | "remote-error" | "result-write-failed" | "ambiguous-partial-write" | "heartbeat-write-failed" | "reply-write-failed" | "process-disposed" | "superseded-by-new-run" | "open-session-cap-exceeded";
 export type SessionCloseReason = ContinuationTerminalReason | "ordinary-cleanup" | "turn-ended" | "initial-write-failed";
 export type ContinuationClaim = {
     session: CursorSession;
@@ -140,6 +140,7 @@ export type CursorSession = {
         outputTokens: number;
         cacheRead: number;
         cacheWrite: number;
+        reasoningTokens: number;
     };
     /**
      * True while a doStream pull() is actively reading this session's frames.
@@ -171,10 +172,12 @@ type SessionManagerOptions = {
     activitySource?: SessionActivitySource;
     tombstoneTtlMs?: number;
     tombstoneLimit?: number;
+    maxOpenSessions?: number;
 };
 export declare class SessionManager {
     private byExecId;
     private sessions;
+    private byOpenCodeSessionId;
     private tombstones;
     private readonly now;
     private readonly setTimer;
@@ -182,8 +185,17 @@ export declare class SessionManager {
     private readonly activitySource;
     private readonly tombstoneTtlMs;
     private readonly tombstoneLimit;
+    private readonly maxOpenSessions;
     constructor(options?: SessionManagerOptions);
     registerSession(session: CursorSession): void;
+    private isPumping;
+    /**
+     * Force-close the oldest idle open session(s) once registration exceeds the
+     * cap. Never closes a session with a live pull() mid-await (see the same
+     * guard in the supersede check above) — an unclosable backlog of genuinely
+     * active sessions just means the cap can't be enforced until one finishes.
+     */
+    private enforceOpenSessionCap;
     recordSemanticProgress(session: CursorSession, at?: number): void;
     recordHeartbeatWrite(session: CursorSession): void;
     /** Register that `session` is awaiting a result for `execId`. */

package/dist/session.js

@@ -9,6 +9,11 @@ export const DEFAULT_CONTINUATION_POLICY = {
 const MAX_TIMER_MS = 2_147_483_647;
 const DEFAULT_TOMBSTONE_TTL_MS = 15 * 60_000;
 const DEFAULT_TOMBSTONE_LIMIT = 1_024;
+// Well below Cursor's server-side concurrent-Run ceiling per HTTP/2 connection,
+// so a caller that keeps abandoning Runs instead of delivering continuations
+// gets corrected here instead of piling up open streams until Cursor's server
+// force-closes the whole shared connection.
+const DEFAULT_MAX_OPEN_SESSIONS = 24;
 function positiveInteger(name, value, fallback) {
     const resolved = value === undefined ? fallback : value;
     if (typeof resolved !== "number" ||
@@ -50,6 +55,10 @@ export class SessionManager {
     // counters per stream) coexist instead of overwriting each other.
     byExecId = new Map();
     sessions = new Set();
+    // Most recently registered open session per OpenCode session id. A second
+    // registration for the same id means the caller started a fresh Run instead
+    // of continuing the held-open one — the prior entry is stale and superseded.
+    byOpenCodeSessionId = new Map();
     tombstones = new Map();
     now;
     setTimer;
@@ -57,6 +66,7 @@ export class SessionManager {
     activitySource;
     tombstoneTtlMs;
     tombstoneLimit;
+    maxOpenSessions;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
         this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
@@ -64,6 +74,7 @@ export class SessionManager {
         this.activitySource = options.activitySource ?? sessionActivity;
         this.tombstoneTtlMs = positiveInteger("tombstoneTtlMs", options.tombstoneTtlMs, DEFAULT_TOMBSTONE_TTL_MS);
         this.tombstoneLimit = positiveInteger("tombstoneLimit", options.tombstoneLimit, DEFAULT_TOMBSTONE_LIMIT);
+        this.maxOpenSessions = positiveInteger("maxOpenSessions", options.maxOpenSessions, DEFAULT_MAX_OPEN_SESSIONS);
     }
     registerSession(session) {
         if (session.closed)
@@ -84,12 +95,66 @@ export class SessionManager {
         session.lastHeartbeatWriteAt ??= this.now();
         session.semanticDeadlineAt ??= this.now() + session.policy.semanticIdleMs;
         this.sessions.add(session);
+        if (session.openCodeSessionId) {
+            const prior = this.byOpenCodeSessionId.get(session.openCodeSessionId);
+            if (prior && prior !== session && !prior.closed) {
+                if (this.isPumping(prior)) {
+                    // A live pull() is mid-await on this stream (nextFrameWithSemanticDeadline
+                    // or the raw frame iterator). Forcing close() here would reject that await
+                    // and propagate a real error to whatever still holds the ReadableStream —
+                    // exactly the kind of self-inflicted failure this cap is meant to prevent.
+                    // Let it finish or expire on its own (hard deadline / heartbeat failure).
+                    trace(`sessionManager.registerSession: openCodeSessionId=${session.openCodeSessionId} ` +
+                        `has a still-pumping prior session ${prior.sessionId} (pending=${prior.pending.size}) ` +
+                        `— leaving it to finish or expire naturally instead of interrupting it`);
+                }
+                else {
+                    trace(`sessionManager.registerSession: superseding stale session ${prior.sessionId} ` +
+                        `(openCodeSessionId=${session.openCodeSessionId}, pending=${prior.pending.size}) ` +
+                        `with new session ${session.sessionId}`);
+                    this.close(prior, "superseded-by-new-run");
+                }
+            }
+            this.byOpenCodeSessionId.set(session.openCodeSessionId, session);
+        }
+        this.enforceOpenSessionCap(session);
         const unsubscribe = session.stream.onTerminal?.((event) => this.onStreamTerminal(session, event)) ?? (() => { });
         if (session.closed)
             unsubscribe();
         else
             session.terminalUnsubscribe = unsubscribe;
     }
+    isPumping(session) {
+        return session.pumpOwner != null || session.pumpActive;
+    }
+    /**
+     * Force-close the oldest idle open session(s) once registration exceeds the
+     * cap. Never closes a session with a live pull() mid-await (see the same
+     * guard in the supersede check above) — an unclosable backlog of genuinely
+     * active sessions just means the cap can't be enforced until one finishes.
+     */
+    enforceOpenSessionCap(justRegistered) {
+        while (this.sessions.size > this.maxOpenSessions) {
+            let oldest;
+            for (const candidate of this.sessions) {
+                if (candidate === justRegistered || this.isPumping(candidate))
+                    continue;
+                if (!oldest || candidate.createdAt < oldest.createdAt)
+                    oldest = candidate;
+            }
+            if (!oldest) {
+                trace(`sessionManager.registerSession: open session cap exceeded ` +
+                    `(${this.sessions.size} > ${this.maxOpenSessions}) but no idle session is ` +
+                    `available to close — all remaining sessions are actively pumping`);
+                return;
+            }
+            trace(`sessionManager.registerSession: open session cap exceeded ` +
+                `(${this.sessions.size} > ${this.maxOpenSessions}), force-closing oldest idle session ` +
+                `${oldest.sessionId} (openCodeSessionId=${oldest.openCodeSessionId ?? "-"}, ` +
+                `ageMs=${this.now() - oldest.createdAt}, pending=${oldest.pending.size})`);
+            this.close(oldest, "open-session-cap-exceeded");
+        }
+    }
     recordSemanticProgress(session, at) {
         if (session.closed)
             return;
@@ -295,6 +360,10 @@ export class SessionManager {
         session.displayToolCalls?.clear();
         session.blobs?.clear();
         this.sessions.delete(session);
+        if (session.openCodeSessionId &&
+            this.byOpenCodeSessionId.get(session.openCodeSessionId) === session) {
+            this.byOpenCodeSessionId.delete(session.openCodeSessionId);
+        }
         try {
             session.stream.destroy();
         }
@@ -311,7 +380,7 @@ export class SessionManager {
     closeUnlessPending(session) {
         if (session.closed)
             return true;
-        const pumpActive = session.pumpOwner != null || session.pumpActive;
+        const pumpActive = this.isPumping(session);
         if (session.pending.size > 0 || pumpActive) {
             trace(`sessionManager.closeUnlessPending: KEEP open pendingCount=${session.pending.size} pumpActive=${pumpActive}`);
             return false;

package/dist/shell-timeout.d.ts

@@ -73,7 +73,9 @@ export declare function buildBackgroundShellCommand(command: string): string;
  * 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;
+export declare function prepareCursorShellArgs(toolCallId: string, args: Record<string, unknown>, options?: {
+    preferWrapperCommand?: boolean;
+}): 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. */