cursor-opencode-provider 0.2.8 → 0.3.0

package/dist/protocol/tools.js

@@ -1,4 +1,6 @@
 import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { encodeMessage } from "./messages.js";
 import { encodeJsonAsValue, decodeStructEntriesToJson, readAllFields } from "./struct.js";
 import { buildEnv } from "../context/env.js";
@@ -280,6 +282,200 @@ export function mapExecServerToToolName(execField) {
 export function mapToolNameToExecField(toolName) {
     return opencodeToolToCursor[toolName];
 }
+const CURSOR_SUBAGENT_TYPE_TO_OPENCODE = {
+    generalPurpose: "general",
+    "general-purpose": "general",
+    general_purpose: "general",
+    general: "general",
+    unspecified: "general",
+    "cursor-guide": "explore",
+    cursor_guide: "explore",
+    "best-of-n-runner": "general",
+    best_of_n_runner: "general",
+    bash: "general",
+    shell: "general",
+    debug: "general",
+    computer_use: "general",
+    computerUse: "general",
+    browser_use: "general",
+    browserUse: "general",
+    media_review: "general",
+    mediaReview: "general",
+    watch_video: "general",
+    watchVideo: "general",
+    vm_setup_helper: "general",
+    vmSetupHelper: "general",
+    explore: "explore",
+    bugbot: "explore",
+    "security-review": "explore",
+    security_review: "explore",
+};
+const SUBAGENT_CATALOG_MARKER = "Available agent types and the tools they have access to:";
+function parseSubagentDescriptionCatalog(description) {
+    if (!description)
+        return { found: false, agents: [] };
+    const marker = description.indexOf(SUBAGENT_CATALOG_MARKER);
+    if (marker < 0)
+        return { found: false, agents: [] };
+    const agents = [];
+    const lines = description.slice(marker + SUBAGENT_CATALOG_MARKER.length).split(/\r?\n/);
+    let started = false;
+    for (const line of lines) {
+        const match = line.match(/^\s*-\s+([^:]+):\s*(.*)$/);
+        if (!match) {
+            if (started && line.trim())
+                break;
+            continue;
+        }
+        started = true;
+        const name = match[1].trim().replace(/^`|`$/g, "");
+        if (!name)
+            continue;
+        const agentDescription = match[2].trim();
+        agents.push({
+            name,
+            ...(agentDescription ? { description: agentDescription } : {}),
+        });
+    }
+    return { found: true, agents };
+}
+function subagentTypeEnumValues(schema) {
+    const out = new Set();
+    const seen = new Set();
+    const visit = (value, propertyName) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, propertyName);
+            return;
+        }
+        const record = value;
+        if (propertyName === "subagent_type" && Array.isArray(record.enum)) {
+            for (const item of record.enum) {
+                if (typeof item === "string" && item)
+                    out.add(item);
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            visit(child, key);
+    };
+    visit(schema);
+    return [...out];
+}
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export function extractHostSubagentCatalog(tools) {
+    const executorTool = tools.find((tool) => tool.name === "actor") ??
+        tools.find((tool) => tool.name === "task");
+    if (!executorTool)
+        return { agents: [], complete: true };
+    const described = parseSubagentDescriptionCatalog(executorTool.description);
+    const enumNames = subagentTypeEnumValues(executorTool.inputSchema);
+    const descriptions = new Map(described.agents.map((agent) => [agent.name, agent.description]));
+    // MiMo's Actor enum is stricter than its prose catalog (`mode: subagent`
+    // rather than every non-primary agent), so structured names are authoritative.
+    const names = new Set(enumNames.length > 0 ? enumNames : described.agents.map((agent) => agent.name));
+    return {
+        executor: executorTool.name,
+        agents: [...names].map((name) => ({
+            name,
+            ...(descriptions.get(name) ? { description: descriptions.get(name) } : {}),
+        })),
+        complete: enumNames.length > 0 || described.found,
+    };
+}
+const GENERIC_CURSOR_SUBAGENT_TYPES = new Set([
+    "generalPurpose",
+    "general-purpose",
+    "general_purpose",
+    "general",
+    "unspecified",
+]);
+function cursorSubagentCandidates(subagentType) {
+    if (GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType))
+        return ["general"];
+    if (subagentType === "cursor-guide" || subagentType === "cursor_guide") {
+        return ["scout", "explore", "general"];
+    }
+    if (subagentType === "explore" ||
+        subagentType === "bugbot" ||
+        subagentType === "security-review" ||
+        subagentType === "security_review") {
+        return ["explore", "general"];
+    }
+    return ["general"];
+}
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export function resolveCursorSubagentType(subagentType, catalog) {
+    const available = new Set(catalog?.agents.map((agent) => agent.name) ?? []);
+    // Explicit host/custom names win. `unspecified` and general aliases are
+    // intentionally excluded so they always select the host's generic agent.
+    if (!GENERIC_CURSOR_SUBAGENT_TYPES.has(subagentType) && available.has(subagentType)) {
+        return subagentType;
+    }
+    const candidates = cursorSubagentCandidates(subagentType);
+    for (const candidate of candidates) {
+        if (available.has(candidate))
+            return candidate;
+    }
+    if (catalog?.complete)
+        return undefined;
+    return candidates[0];
+}
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+export function mapCursorSubagentTypeToOpenCode(subagentType) {
+    return CURSOR_SUBAGENT_TYPE_TO_OPENCODE[subagentType] ?? subagentType;
+}
+/** Resolve a native Cursor subagent request to this turn's executor and catalog. */
+export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catalog) {
+    if (parsed.resultField !== "subagent_result" || parsed.toolName !== "task")
+        return;
+    const advertised = new Set(advertisedToolNames);
+    const executor = advertised.has("actor") ? "actor" : advertised.has("task") ? "task" : undefined;
+    if (!executor)
+        return;
+    const description = str(parsed.args.description) ?? "";
+    const prompt = str(parsed.args.prompt) ?? "";
+    const cursorSubagentType = str(parsed.resultMetadata?.cursor_subagent_type) ??
+        str(parsed.args.subagent_type) ?? "";
+    const subagentType = resolveCursorSubagentType(cursorSubagentType, catalog);
+    if (!subagentType) {
+        const available = catalog?.agents.map((agent) => agent.name).join(", ") || "none";
+        parsed.localError =
+            `Cursor subagent '${cursorSubagentType}' has no compatible host agent. ` +
+                `Available subagents: ${available}.`;
+        return;
+    }
+    const resumeAgentId = str(parsed.args.task_id);
+    parsed.toolName = executor;
+    if (executor === "task") {
+        parsed.args = {
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
+            ...(parsed.args.background === true ? { background: true } : {}),
+        };
+        return;
+    }
+    parsed.args = {
+        operation: {
+            action: parsed.args.background === true ? "spawn" : "run",
+            description,
+            prompt,
+            subagent_type: subagentType,
+            ...(resumeAgentId ? { actor_id: resumeAgentId } : {}),
+        },
+    };
+}
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -358,6 +554,9 @@ export function parseExecServerMessage(msg) {
             toolName: "task",
             args,
             resultField,
+            resultMetadata: cursorSubagentType
+                ? { cursor_subagent_type: cursorSubagentType }
+                : undefined,
             localError: prompt && cursorSubagentType
                 ? undefined
                 : "Cursor subagent request is missing a required prompt or subagent type.",
@@ -595,19 +794,6 @@ function describeSubagentTask(prompt, subagentType) {
         return words.join(" ");
     return `${subagentType || "Delegated"} task`;
 }
-function mapCursorSubagentTypeToOpenCode(subagentType) {
-    // Cursor's built-in general agent uses a camelCase protocol identifier, and
-    // its native Bugbot reviewer has no OpenCode-specific agent definition.
-    // OpenCode `general` is the general-purpose equivalent; `explore` preserves
-    // Bugbot's review-only/read-oriented semantics while retaining grep/read/bash.
-    // Preserve every other value so `explore` and configured custom agents keep
-    // their exact advertised names.
-    if (subagentType === "generalPurpose")
-        return "general";
-    if (subagentType === "bugbot")
-        return "explore";
-    return subagentType;
-}
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -667,6 +853,75 @@ function findOneOfVariant(msg, candidates) {
     }
     return undefined;
 }
+// ── Pre-execution read validation (Cursor LocalReadExecutor parity) ──
+/** Expand a leading `~` to the home directory, matching Cursor's untildify. */
+function untildify(input) {
+    return input.replace(/^~(?=$|\/|\\)/, os.homedir());
+}
+/**
+ * Resolve a read target the way Cursor's LocalReadExecutor does before it
+ * stats the file: untildify, then resolve a relative path against the workspace
+ * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
+ * agent utils `resolvePath(path, workspaceRoot)`.
+ */
+export function resolveReadTargetPath(requested, workspaceRoot) {
+    const expanded = untildify(requested);
+    if (workspaceRoot && !path.isAbsolute(expanded)) {
+        return path.resolve(workspaceRoot, expanded);
+    }
+    return path.resolve(expanded);
+}
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export function classifyMissingReadTarget(absolutePath) {
+    let stat;
+    try {
+        stat = fs.statSync(absolutePath);
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            return { file_not_found: { path: absolutePath } };
+        }
+        return undefined;
+    }
+    if (stat.isDirectory()) {
+        return { invalid_file: { path: absolutePath, reason: "Path is a directory, not a file" } };
+    }
+    if (!stat.isFile()) {
+        return {
+            invalid_file: { path: absolutePath, reason: "Path is neither a file nor a directory" },
+        };
+    }
+    return undefined;
+}
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export function buildReadRejectionMessages(execId, readResult) {
+    return [
+        encodeMessage("AgentClientMessage", {
+            exec_client_message: {
+                id: execId,
+                local_execution_time_ms: 0,
+                read_result: readResult,
+            },
+        }),
+        buildExecStreamClose(execId),
+    ];
+}
 /**
  * Build one or more ExecClientMessage frames for a tool result.
  * Shell replies are a sequence of ShellStream oneofs under the same id —
@@ -721,7 +976,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,
         }));
@@ -808,7 +1063,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) ?? "";
@@ -839,7 +1099,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: "",
@@ -929,7 +1189,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: {

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

@@ -1,7 +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";
+import type { HostSubagentCatalog, ToolAliasRegistry } from "./protocol/tools.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -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;
@@ -120,6 +120,8 @@ export type CursorSession = {
     toolDescriptors: Array<Record<string, unknown>>;
     /** Cursor-facing web alias → exact executable host tool for this Run. */
     toolAliases?: ToolAliasRegistry;
+    /** Spawnable host agents extracted from this turn's Task/Actor definition. */
+    subagentCatalog?: HostSubagentCatalog;
     /** Full RequestContext for exec #10 replies. */
     requestContext: Record<string, unknown>;
     /**
@@ -138,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.
@@ -169,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;
@@ -180,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. */

package/dist/shell-timeout.js

@@ -213,7 +213,7 @@ function ensureShellEnvWrap(toolCallId, policy) {
  * The classic hook replaces it with the original command (bash/zsh) or the
  * shorter wrapper-file command (sh/dash), avoiding duplicate execution.
  */
-export function prepareCursorShellArgs(toolCallId, args) {
+export function prepareCursorShellArgs(toolCallId, args, options = {}) {
     const policy = policies.get(toolCallId);
     if (!policy)
         return;
@@ -226,7 +226,11 @@ export function prepareCursorShellArgs(toolCallId, args) {
         args.timeout = Math.max(OPENCODE_TIMEOUT_GRACE_MS, policy.timeoutMs + OPENCODE_TIMEOUT_GRACE_MS);
     }
     const shellKind = resolveCursorShellKind();
-    if (process.platform === "win32" || shellKind === "bash" || shellKind === "zsh") {
+    // OpenCode 2.0 has no `shell.env` hook, so bash/zsh cannot be wrapped by
+    // sourcing an injector. Callers there opt into the wrapper-file command —
+    // the same mechanism sh/dash already use — which needs no env injection.
+    const envInjectable = !options.preferWrapperCommand && (shellKind === "bash" || shellKind === "zsh");
+    if (process.platform === "win32" || envInjectable) {
         // Native Windows PowerShell/cmd wrapping remains unsupported; do not emit
         // a POSIX /bin/sh command there. Git Bash still uses the env path above.
         args.command = policy.command;

package/dist/usage.d.ts

@@ -0,0 +1,30 @@
+import type { LanguageModelV3Usage } from "@ai-sdk/provider";
+/** Non-negative integer counter from a Cursor `turn_ended` field. */
+export declare function turnEndedCounter(te: Record<string, unknown>, key: string): number;
+/**
+ * Map authoritative Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
+ * flatten via input total = noCache + cacheRead + cacheWrite).
+ *
+ * Contract: `input_tokens` is non-cached input; cache fields are separate.
+ * Cursor's agent wire currently sends `cache_write=0` even when later turns
+ * report large `cache_read`; we still forward the counter when non-zero.
+ * If production semantics differ (input_tokens already total), adjust here.
+ */
+export declare function buildLanguageModelV3UsageFromTurnEnded(te: Record<string, unknown>): LanguageModelV3Usage;
+export type CursorUsageEstimate = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    reasoningTokens: number;
+};
+/** Mid-turn finish (e.g. tool-calls) before `turn_ended` — keep non-zero estimates. */
+export declare function buildLanguageModelV3UsageFromEstimate(est: CursorUsageEstimate, promptTokens: number, outputChars: number, estimateCharsToTokens: (chars: number) => number): LanguageModelV3Usage;
+/** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
+export declare function kiloShapedUsageFromV3(usage: LanguageModelV3Usage): {
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheReadInputTokens: number;
+    cacheWriteInputTokens: number;
+};