cursor-opencode-provider 0.2.2 → 0.2.4

package/dist/session.js

@@ -1,34 +1,229 @@
 import { trace } from "./debug.js";
+import { CursorProtocolError } from "./errors.js";
+import { sessionActivity } from "./activity.js";
+export const DEFAULT_CONTINUATION_POLICY = {
+    semanticIdleMs: 120_000,
+    hardCapMs: 600_000,
+    heartbeatMs: 5_000,
+};
+const MAX_TIMER_MS = 2_147_483_647;
+const DEFAULT_TOMBSTONE_TTL_MS = 15 * 60_000;
+const DEFAULT_TOMBSTONE_LIMIT = 1_024;
+function positiveInteger(name, value, fallback) {
+    const resolved = value === undefined ? fallback : value;
+    if (typeof resolved !== "number" ||
+        !Number.isSafeInteger(resolved) ||
+        resolved <= 0 ||
+        resolved > MAX_TIMER_MS) {
+        throw new CursorProtocolError(`Cursor continuation ${name} must be a positive integer no greater than ${MAX_TIMER_MS}`);
+    }
+    return resolved;
+}
+export function resolveContinuationPolicy(options) {
+    if (options !== undefined && (options === null || typeof options !== "object" || Array.isArray(options))) {
+        throw new CursorProtocolError("Cursor continuation options must be an object");
+    }
+    for (const key of Object.keys(options ?? {})) {
+        if (!["heartbeatMs", "semanticIdleMs", "softHealthMs", "hardCapMs"].includes(key)) {
+            throw new CursorProtocolError(`Unknown Cursor continuation option: ${key}`);
+        }
+    }
+    if (options?.semanticIdleMs !== undefined &&
+        options.softHealthMs !== undefined &&
+        options.semanticIdleMs !== options.softHealthMs) {
+        throw new CursorProtocolError("Cursor continuation semanticIdleMs and deprecated softHealthMs must match when both are set");
+    }
+    const heartbeatMs = positiveInteger("heartbeatMs", options?.heartbeatMs, DEFAULT_CONTINUATION_POLICY.heartbeatMs);
+    const semanticIdleMs = positiveInteger("semanticIdleMs", options?.semanticIdleMs ?? options?.softHealthMs, DEFAULT_CONTINUATION_POLICY.semanticIdleMs);
+    const hardCapMs = positiveInteger("hardCapMs", options?.hardCapMs, DEFAULT_CONTINUATION_POLICY.hardCapMs);
+    if (heartbeatMs >= semanticIdleMs) {
+        throw new CursorProtocolError("Cursor continuation heartbeatMs must be less than semanticIdleMs");
+    }
+    if (semanticIdleMs > hardCapMs) {
+        throw new CursorProtocolError("Cursor continuation semanticIdleMs must be no greater than hardCapMs");
+    }
+    return { heartbeatMs, semanticIdleMs, hardCapMs };
+}
 export class SessionManager {
     // Composite key `${sessionId}:${execId}` → owning session. Composite keying
     // means two Run streams that both register an execId of 1 (Cursor resets
     // counters per stream) coexist instead of overwriting each other.
     byExecId = new Map();
-    idleTimeoutMs;
-    constructor(idleTimeoutMs = 300_000) {
-        this.idleTimeoutMs = idleTimeoutMs;
+    sessions = new Set();
+    tombstones = new Map();
+    now;
+    setTimer;
+    clearTimer;
+    activitySource;
+    tombstoneTtlMs;
+    tombstoneLimit;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer));
+        this.activitySource = options.activitySource ?? sessionActivity;
+        this.tombstoneTtlMs = positiveInteger("tombstoneTtlMs", options.tombstoneTtlMs, DEFAULT_TOMBSTONE_TTL_MS);
+        this.tombstoneLimit = positiveInteger("tombstoneLimit", options.tombstoneLimit, DEFAULT_TOMBSTONE_LIMIT);
     }
-    touch(session) {
-        session.expiresAt = Date.now() + this.idleTimeoutMs;
+    registerSession(session) {
+        if (session.closed)
+            throw new CursorProtocolError("Cannot register a closed Cursor session");
+        if (this.sessions.has(session))
+            return;
+        session.closed ??= false;
+        session.closeError ??= null;
+        session.pumpOwner ??= null;
+        session.heartbeatCancel ??= null;
+        session.hardDeadlineTimer ??= null;
+        session.semanticDeadlineCancel ??= null;
+        session.terminalUnsubscribe ??= null;
+        session.deferredTerminalReason ??= null;
+        session.policy ??= { ...DEFAULT_CONTINUATION_POLICY };
+        session.createdAt ??= this.now();
+        session.lastInboundAt ??= this.now();
+        session.lastHeartbeatWriteAt ??= this.now();
+        session.semanticDeadlineAt ??= this.now() + session.policy.semanticIdleMs;
+        this.sessions.add(session);
+        const unsubscribe = session.stream.onTerminal?.((event) => this.onStreamTerminal(session, event)) ?? (() => { });
+        if (session.closed)
+            unsubscribe();
+        else
+            session.terminalUnsubscribe = unsubscribe;
+    }
+    recordSemanticProgress(session, at) {
+        if (session.closed)
+            return;
+        const now = at ?? this.now();
+        session.lastInboundAt = now;
+        session.semanticDeadlineAt = now + session.policy.semanticIdleMs;
+    }
+    recordHeartbeatWrite(session) {
+        if (!session.closed)
+            session.lastHeartbeatWriteAt = this.now();
     }
     /** Register that `session` is awaiting a result for `execId`. */
-    registerPending(execId, session, resultField, toolName, bridged = false) {
-        session.pending.set(execId, { resultField, toolName, bridged });
-        this.byExecId.set(this.key(session.sessionId, execId), session);
-        this.touch(session);
+    registerPending(execId, session, resultField, toolName, bridged = false, resultMetadata) {
+        this.registerSession(session);
+        if (session.closed)
+            throw new CursorProtocolError("Cannot register a pending exec on a closed Cursor session");
+        const now = this.now();
+        const key = this.key(session.sessionId, execId);
+        this.tombstones.delete(key);
+        session.pending.set(execId, {
+            resultField,
+            toolName,
+            bridged,
+            resultMetadata,
+            state: "pending",
+            registeredAt: now,
+            hardDeadlineAt: now + session.policy.hardCapMs,
+        });
+        this.byExecId.set(key, session);
+        this.scheduleHardDeadline(session);
     }
     /** The pending exec info for an id on a specific session, if still awaiting it. */
     pendingFor(sessionId, execId) {
         return this.byExecId.get(this.key(sessionId, execId))?.pending.get(execId);
     }
+    classify(sessionId, execId) {
+        const key = this.key(sessionId, execId);
+        const session = this.byExecId.get(key);
+        if (session) {
+            const pending = session.pending.get(execId);
+            const legacyExpiresAt = session.expiresAt;
+            if (!pending ||
+                session.closed ||
+                session.stream.isClosed() ||
+                (typeof legacyExpiresAt === "number" && this.now() >= legacyExpiresAt)) {
+                this.byExecId.delete(key);
+                if (!session.closed)
+                    this.close(session, "remote-clean-close");
+            }
+            else if (this.hardDeadlineExpired(session, pending)) {
+                this.close(session, "hard-cap-expired");
+            }
+            else if (pending.state === "pending") {
+                return { kind: "deliverable", session, pending };
+            }
+            else if (pending.state === "claimed") {
+                return { kind: "duplicate", reason: "in-flight" };
+            }
+            else {
+                return { kind: "duplicate", reason: "delivered" };
+            }
+        }
+        const tombstone = this.getTombstone(key);
+        if (!tombstone)
+            return { kind: "missing", reason: "missing-process-local-state" };
+        if (tombstone.reason === "delivered")
+            return { kind: "duplicate", reason: "delivered" };
+        return { kind: "terminal", reason: tombstone.reason };
+    }
+    claim(sessionId, execId) {
+        const classification = this.classify(sessionId, execId);
+        if (classification.kind !== "deliverable")
+            return classification;
+        classification.pending.state = "claimed";
+        return {
+            session: classification.session,
+            execId,
+            pending: classification.pending,
+        };
+    }
+    deliverClaim(claim, frames) {
+        const { session, execId, pending } = claim;
+        const key = this.key(session.sessionId, execId);
+        if (session.closed ||
+            this.byExecId.get(key) !== session ||
+            session.pending.get(execId) !== pending) {
+            const current = this.classify(session.sessionId, execId);
+            if (current.kind === "duplicate")
+                return { ...current, framesWritten: 0 };
+            if (current.kind === "terminal")
+                return { ...current, framesWritten: 0 };
+            return { kind: "missing", reason: "missing-process-local-state", framesWritten: 0 };
+        }
+        if (pending.state !== "claimed") {
+            return {
+                kind: "duplicate",
+                reason: pending.state === "delivered" ? "delivered" : "in-flight",
+                framesWritten: 0,
+            };
+        }
+        if (this.hardDeadlineExpired(session, pending)) {
+            this.close(session, "hard-cap-expired");
+            return { kind: "terminal", reason: "hard-cap-expired", framesWritten: 0 };
+        }
+        let framesWritten = 0;
+        try {
+            if (!pending.bridged && frames.length === 0) {
+                throw new CursorProtocolError("No result frames were produced");
+            }
+            for (const frame of frames) {
+                session.stream.write(frame);
+                framesWritten++;
+            }
+        }
+        catch {
+            const reason = framesWritten === 0 ? "result-write-failed" : "ambiguous-partial-write";
+            this.close(session, reason);
+            return { kind: "terminal", reason, framesWritten };
+        }
+        pending.state = "delivered";
+        this.putTombstone(key, "delivered");
+        session.pending.delete(execId);
+        this.byExecId.delete(key);
+        if (session.pending.size === 0)
+            this.recordSemanticProgress(session);
+        this.scheduleHardDeadline(session);
+        return { kind: "delivered", framesWritten };
+    }
     /** Find the live session awaiting one of the given exec ids. */
     findByExecIds(sessionId, execIds) {
         for (const id of execIds) {
-            const s = this.byExecId.get(this.key(sessionId, id));
-            if (s && Date.now() < s.expiresAt)
-                return s;
-            if (s)
-                this.close(s);
+            const classification = this.classify(sessionId, id);
+            if (classification.kind === "deliverable")
+                return classification.session;
         }
         return undefined;
     }
@@ -36,22 +231,74 @@ export class SessionManager {
     resolve(sessionId, execId) {
         const k = this.key(sessionId, execId);
         const s = this.byExecId.get(k);
-        if (s)
+        if (s) {
             s.pending.delete(execId);
+            this.putTombstone(k, "delivered");
+            this.scheduleHardDeadline(s);
+        }
         this.byExecId.delete(k);
     }
+    beginPump(session, owner) {
+        this.registerSession(session);
+        if (session.pumpOwner && session.pumpOwner !== owner) {
+            throw new CursorProtocolError("Cursor session already has an active pump");
+        }
+        session.pumpOwner = owner;
+        session.pumpActive = true;
+    }
+    isPumpOwner(session, owner) {
+        return !session.closed && session.pumpOwner === owner;
+    }
+    endPump(session, owner) {
+        if (session.pumpOwner !== owner)
+            return false;
+        session.pumpOwner = null;
+        session.pumpActive = false;
+        const deferred = session.deferredTerminalReason;
+        session.deferredTerminalReason = null;
+        if (deferred)
+            this.close(session, deferred);
+        return true;
+    }
     key(sessionId, execId) {
         return `${sessionId}:${execId}`;
     }
-    close(session) {
-        trace(`sessionManager.close: pending=[${[...session.pending.keys()].join(",")}] blobs=${session.blobs.size}`);
-        if (session.heartbeat)
+    close(session, reason = "ordinary-cleanup", error) {
+        if (session.closed)
+            return;
+        session.closed = true;
+        session.closeError = error ?? session.closeError ?? null;
+        trace(`sessionManager.close: reason=${reason} pendingCount=${session.pending.size} blobs=${session.blobs.size}`);
+        if (session.heartbeatCancel)
+            session.heartbeatCancel();
+        else if (session.heartbeat)
             clearInterval(session.heartbeat);
         session.heartbeat = null;
-        session.stream.destroy();
-        for (const id of session.pending.keys())
-            this.byExecId.delete(this.key(session.sessionId, id));
+        session.heartbeatCancel = null;
+        if (session.hardDeadlineTimer)
+            this.clearTimer(session.hardDeadlineTimer);
+        session.hardDeadlineTimer = null;
+        session.semanticDeadlineCancel?.();
+        session.semanticDeadlineCancel = null;
+        session.terminalUnsubscribe?.();
+        session.terminalUnsubscribe = null;
+        session.deferredTerminalReason = null;
+        for (const id of session.pending.keys()) {
+            const key = this.key(session.sessionId, id);
+            this.byExecId.delete(key);
+            if (this.isTerminalReason(reason))
+                this.putTombstone(key, reason);
+        }
         session.pending.clear();
+        session.pumpOwner = null;
+        session.pumpActive = false;
+        session.displayToolCalls?.clear();
+        session.blobs?.clear();
+        this.sessions.delete(session);
+        try {
+            session.stream.destroy();
+        }
+        catch { /* already closed */ }
     }
     /**
      * Close only if nothing is awaiting a tool result AND no pull() is actively
@@ -62,23 +309,107 @@ export class SessionManager {
      * Returns true if the session was closed.
      */
     closeUnlessPending(session) {
-        if (session.pending.size > 0 || session.pumpActive) {
-            trace(`sessionManager.closeUnlessPending: KEEP open pending=[${[...session.pending.keys()].join(",")}] pumpActive=${session.pumpActive}`);
+        if (session.closed)
+            return true;
+        const pumpActive = session.pumpOwner != null || session.pumpActive;
+        if (session.pending.size > 0 || pumpActive) {
+            trace(`sessionManager.closeUnlessPending: KEEP open pendingCount=${session.pending.size} pumpActive=${pumpActive}`);
             return false;
         }
-        this.close(session);
+        this.close(session, "ordinary-cleanup");
         return true;
     }
     dispose() {
-        const seen = new Set();
-        for (const s of this.byExecId.values()) {
-            if (seen.has(s))
-                continue;
-            seen.add(s);
-            this.close(s);
-        }
+        for (const session of [...this.sessions])
+            this.close(session, "process-disposed");
         this.byExecId.clear();
     }
+    sweepHardDeadlines() {
+        for (const session of [...this.sessions]) {
+            if (!session.closed &&
+                [...session.pending.values()].some((pending) => this.hardDeadlineExpired(session, pending))) {
+                this.close(session, "hard-cap-expired");
+            }
+        }
+    }
+    onStreamTerminal(session, event) {
+        if (event.kind === "local-close" || session.closed)
+            return;
+        const reason = event.kind === "remote-error" ? "remote-error" : "remote-clean-close";
+        if (event.kind === "remote-error")
+            session.closeError = event.error;
+        if (session.pumpOwner !== null) {
+            session.deferredTerminalReason = reason;
+            return;
+        }
+        this.close(session, reason, event.kind === "remote-error" ? event.error : undefined);
+    }
+    refreshHardDeadline(session, pending) {
+        if (!session.openCodeSessionId)
+            return pending.hardDeadlineAt;
+        const activityAt = this.activitySource.lastActivityAt(session.openCodeSessionId);
+        if (activityAt === undefined || activityAt <= pending.registeredAt)
+            return pending.hardDeadlineAt;
+        const renewedDeadline = activityAt + session.policy.hardCapMs;
+        if (renewedDeadline > pending.hardDeadlineAt) {
+            pending.hardDeadlineAt = renewedDeadline;
+            trace("continuation lease renewed from OpenCode session activity");
+        }
+        return pending.hardDeadlineAt;
+    }
+    hardDeadlineExpired(session, pending) {
+        return this.now() >= this.refreshHardDeadline(session, pending);
+    }
+    scheduleHardDeadline(session) {
+        if (session.hardDeadlineTimer)
+            this.clearTimer(session.hardDeadlineTimer);
+        session.hardDeadlineTimer = null;
+        if (session.closed || session.pending.size === 0)
+            return;
+        const earliest = Math.min(...[...session.pending.values()].map((pending) => this.refreshHardDeadline(session, pending)));
+        const delayMs = Math.max(0, earliest - this.now());
+        const timer = this.setTimer(() => {
+            session.hardDeadlineTimer = null;
+            if (session.closed)
+                return;
+            if ([...session.pending.values()].some((pending) => this.hardDeadlineExpired(session, pending))) {
+                this.close(session, "hard-cap-expired");
+            }
+            else {
+                this.scheduleHardDeadline(session);
+            }
+        }, delayMs);
+        session.hardDeadlineTimer = timer;
+        const unref = timer.unref;
+        if (typeof unref === "function")
+            unref.call(timer);
+    }
+    getTombstone(key) {
+        const tombstone = this.tombstones.get(key);
+        if (!tombstone)
+            return undefined;
+        if (this.now() >= tombstone.expiresAt) {
+            this.tombstones.delete(key);
+            return undefined;
+        }
+        return tombstone;
+    }
+    putTombstone(key, reason) {
+        this.tombstones.delete(key);
+        this.tombstones.set(key, {
+            reason,
+            expiresAt: this.now() + this.tombstoneTtlMs,
+        });
+        while (this.tombstones.size > this.tombstoneLimit) {
+            const oldest = this.tombstones.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.tombstones.delete(oldest);
+        }
+    }
+    isTerminalReason(reason) {
+        return !["ordinary-cleanup", "turn-ended", "initial-write-failed"].includes(reason);
+    }
 }
 export const sessionManager = new SessionManager();
 function installProcessCleanup() {

package/dist/shell-timeout.d.ts

@@ -0,0 +1,50 @@
+/** Cursor agent.v1 TimeoutBehavior enum values. */
+export declare const CURSOR_TIMEOUT_CANCEL = 1;
+export declare const CURSOR_TIMEOUT_BACKGROUND = 2;
+export type CursorShellPolicy = {
+    command: string;
+    workingDirectory: string;
+    timeoutMs: number;
+    timeoutBehavior: number;
+    hardTimeoutMs?: number;
+};
+export type CursorShellOutcome = {
+    kind: "exit";
+    code: number;
+} | {
+    kind: "timeout";
+    timeoutMs: number;
+} | {
+    kind: "backgrounded";
+    shellId: number;
+    pid: number;
+    command: string;
+    workingDirectory: string;
+    msToWait: number;
+    reason: 1;
+};
+export declare function shellPolicyFromMetadata(metadata: Record<string, unknown> | undefined): CursorShellPolicy | undefined;
+/** Register a Cursor shell request before OpenCode executes its emitted tool call. */
+export declare function registerCursorShellCall(toolCallId: string, metadata: Record<string, unknown> | undefined): void;
+/**
+ * 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.
+ */
+export declare function buildSoftBackgroundCommand(policy: CursorShellPolicy): string;
+/** Mutate OpenCode Bash args before execution when Cursor requested soft backgrounding. */
+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;
+/**
+ * Capture Bash completion in the classic plugin's after hook. Returns the
+ * sanitized output that OpenCode should store and render.
+ */
+export declare function captureCursorShellResult(toolCallId: string, output: string, metadata?: Record<string, unknown>): string;
+/** Consume the structured result, with an inline fallback when no plugin hook ran. */
+export declare function consumeCursorShellResult(toolCallId: string, output: string): {
+    output: string;
+    outcome?: CursorShellOutcome;
+};
+/** Test/process cleanup. */
+export declare function resetCursorShellCalls(): void;

package/dist/shell-timeout.js

@@ -0,0 +1,179 @@
+/** Cursor agent.v1 TimeoutBehavior enum values. */
+export const CURSOR_TIMEOUT_CANCEL = 1;
+export const CURSOR_TIMEOUT_BACKGROUND = 2;
+const MAX_TRACKED_SHELL_CALLS = 512;
+const OPENCODE_TIMEOUT_GRACE_MS = 15_000;
+const POLL_INTERVAL_MS = 100;
+const BACKGROUND_MARKER = "__CURSOR_SHELL_BACKGROUND__";
+const EXIT_MARKER = "__CURSOR_SHELL_EXIT__";
+const TIMEOUT_MARKER = "__CURSOR_SHELL_TIMEOUT__";
+const policies = new Map();
+const outcomes = new Map();
+function remember(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    while (map.size > MAX_TRACKED_SHELL_CALLS) {
+        const oldest = map.keys().next().value;
+        if (!oldest)
+            break;
+        map.delete(oldest);
+    }
+}
+function finiteNonNegative(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return undefined;
+    return Math.floor(n);
+}
+export function shellPolicyFromMetadata(metadata) {
+    if (!metadata || metadata.shell_stream !== true)
+        return undefined;
+    const timeoutMs = finiteNonNegative(metadata.timeout_ms) ?? 30_000;
+    const timeoutBehavior = finiteNonNegative(metadata.timeout_behavior) ?? 0;
+    const hardTimeoutMs = finiteNonNegative(metadata.hard_timeout_ms);
+    return {
+        command: typeof metadata.command === "string" ? metadata.command : "",
+        workingDirectory: typeof metadata.working_directory === "string" ? metadata.working_directory : "",
+        timeoutMs,
+        timeoutBehavior,
+        ...(hardTimeoutMs !== undefined && hardTimeoutMs > 0 ? { hardTimeoutMs } : {}),
+    };
+}
+/** Register a Cursor shell request before OpenCode executes its emitted tool call. */
+export function registerCursorShellCall(toolCallId, metadata) {
+    const policy = shellPolicyFromMetadata(metadata);
+    if (!policy || !toolCallId.startsWith("cursor_"))
+        return;
+    remember(policies, toolCallId, policy);
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * 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.
+ */
+export function buildSoftBackgroundCommand(policy) {
+    const polls = Math.ceil(policy.timeoutMs / POLL_INTERVAL_MS);
+    const hardPolls = policy.hardTimeoutMs !== undefined
+        ? Math.max(1, Math.ceil(policy.hardTimeoutMs / POLL_INTERVAL_MS))
+        : undefined;
+    const lines = [
+        'cursor_shell_log="$(mktemp "${TMPDIR:-/tmp}/cursor-opencode-shell.XXXXXX")" || exit 1',
+        `nohup sh -c ${shellQuote(policy.command)} >"$cursor_shell_log" 2>&1 </dev/null &`,
+        "cursor_shell_pid=$!",
+    ];
+    if (hardPolls !== undefined) {
+        lines.push('cursor_shell_status="$(mktemp "${TMPDIR:-/tmp}/cursor-opencode-shell-status.XXXXXX")" || exit 1', `nohup sh -c 'cursor_hard_poll=0; while [ "$cursor_hard_poll" -lt "$1" ] && kill -0 "$2" 2>/dev/null; do sleep ${POLL_INTERVAL_MS / 1000}; cursor_hard_poll=$((cursor_hard_poll + 1)); done; if kill -0 "$2" 2>/dev/null; then printf timeout >"$3"; kill -TERM "$2" 2>/dev/null; sleep 3; kill -KILL "$2" 2>/dev/null; fi' cursor-shell-watchdog ${hardPolls} "$cursor_shell_pid" "$cursor_shell_status" >/dev/null 2>&1 </dev/null &`, "cursor_shell_watchdog_pid=$!");
+    }
+    else {
+        lines.push('cursor_shell_status=""', 'cursor_shell_watchdog_pid=""');
+    }
+    lines.push("cursor_shell_poll=0", `while [ "$cursor_shell_poll" -lt ${polls} ] && kill -0 "$cursor_shell_pid" 2>/dev/null; do`, `  sleep ${POLL_INTERVAL_MS / 1000}`, "  cursor_shell_poll=$((cursor_shell_poll + 1))", "done", 'if kill -0 "$cursor_shell_pid" 2>/dev/null; then', '  cat "$cursor_shell_log"', `  printf '\n${BACKGROUND_MARKER}%s:%s\n' "$cursor_shell_pid" "$cursor_shell_log"`, "  exit 0", "fi", 'wait "$cursor_shell_pid"', "cursor_shell_code=$?", 'cat "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ] && [ "$(cat "$cursor_shell_status" 2>/dev/null)" = timeout ]; then', `  printf '\n${TIMEOUT_MARKER}%s\n' ${policy.hardTimeoutMs ?? policy.timeoutMs}`, "else", '  if [ -n "$cursor_shell_watchdog_pid" ]; then kill "$cursor_shell_watchdog_pid" 2>/dev/null || true; fi', `  printf '\n${EXIT_MARKER}%s\n' "$cursor_shell_code"`, "fi", 'rm -f -- "$cursor_shell_log"', 'if [ -n "$cursor_shell_status" ]; then rm -f -- "$cursor_shell_status"; fi');
+    return lines.join("\n");
+}
+/** Mutate OpenCode Bash args before execution when Cursor requested soft backgrounding. */
+export function prepareCursorShellArgs(toolCallId, args) {
+    const policy = policies.get(toolCallId);
+    if (!policy || policy.timeoutBehavior !== CURSOR_TIMEOUT_BACKGROUND)
+        return;
+    args.command = buildSoftBackgroundCommand(policy);
+    // The wrapper returns just after Cursor's foreground window. OpenCode's own
+    // timeout is only an outer safety net and must not win the race.
+    args.timeout = Math.max(OPENCODE_TIMEOUT_GRACE_MS, policy.timeoutMs + OPENCODE_TIMEOUT_GRACE_MS);
+}
+/** Restore the model-facing command in OpenCode's completed tool title. */
+export function cursorShellOriginalCommand(toolCallId) {
+    return policies.get(toolCallId)?.command || undefined;
+}
+function withoutMarker(output, index) {
+    let clean = output.slice(0, index).replace(/[\t ]+$/gm, "").replace(/\n{2,}$/, "\n");
+    if (clean.trim() === "" || clean.trim() === "(no output)")
+        clean = "";
+    return clean;
+}
+function parseOpenCodeTimeout(output) {
+    const re = /<shell_metadata>\r?\nshell tool terminated command after exceeding timeout (\d+) ms\.[\s\S]*?<\/shell_metadata>\s*$/;
+    const match = re.exec(output);
+    if (!match || match.index === undefined)
+        return undefined;
+    return { output: withoutMarker(output, match.index), timeoutMs: Number(match[1]) };
+}
+function parseWrapperOutcome(output, policy) {
+    const background = new RegExp(`${BACKGROUND_MARKER}(\\d+):([^\\r\\n]+)\\s*$`).exec(output);
+    if (background?.index !== undefined) {
+        const pid = Number(background[1]);
+        if (Number.isSafeInteger(pid) && pid > 0 && pid <= 0xffff_ffff) {
+            return {
+                output: withoutMarker(output, background.index),
+                outcome: {
+                    kind: "backgrounded",
+                    shellId: pid,
+                    pid,
+                    command: policy?.command ?? "",
+                    workingDirectory: policy?.workingDirectory ?? "",
+                    msToWait: policy?.timeoutMs ?? 0,
+                    reason: 1,
+                },
+            };
+        }
+    }
+    const timeout = new RegExp(`${TIMEOUT_MARKER}(\\d+)\\s*$`).exec(output);
+    if (timeout?.index !== undefined) {
+        return {
+            output: withoutMarker(output, timeout.index),
+            outcome: { kind: "timeout", timeoutMs: Number(timeout[1]) },
+        };
+    }
+    const exit = new RegExp(`${EXIT_MARKER}(-?\\d+)\\s*$`).exec(output);
+    if (exit?.index !== undefined) {
+        return {
+            output: withoutMarker(output, exit.index),
+            outcome: { kind: "exit", code: Number(exit[1]) },
+        };
+    }
+    return undefined;
+}
+/**
+ * Capture Bash completion in the classic plugin's after hook. Returns the
+ * sanitized output that OpenCode should store and render.
+ */
+export function captureCursorShellResult(toolCallId, output, metadata) {
+    if (!toolCallId.startsWith("cursor_"))
+        return output;
+    const policy = policies.get(toolCallId);
+    // Private wrapper sentinels are meaningful only for calls we transformed.
+    // A normal foreground command is allowed to print the same text verbatim.
+    const wrapper = policy?.timeoutBehavior === CURSOR_TIMEOUT_BACKGROUND
+        ? parseWrapperOutcome(output, policy)
+        : undefined;
+    if (wrapper) {
+        remember(outcomes, toolCallId, wrapper.outcome);
+        return wrapper.output;
+    }
+    const timeout = parseOpenCodeTimeout(output);
+    if (timeout) {
+        remember(outcomes, toolCallId, { kind: "timeout", timeoutMs: timeout.timeoutMs });
+        return timeout.output;
+    }
+    const exitCode = finiteNonNegative(metadata?.exit);
+    if (exitCode !== undefined)
+        remember(outcomes, toolCallId, { kind: "exit", code: exitCode });
+    return output;
+}
+/** Consume the structured result, with an inline fallback when no plugin hook ran. */
+export function consumeCursorShellResult(toolCallId, output) {
+    let clean = output;
+    if (!outcomes.has(toolCallId))
+        clean = captureCursorShellResult(toolCallId, output);
+    const outcome = outcomes.get(toolCallId);
+    outcomes.delete(toolCallId);
+    policies.delete(toolCallId);
+    return { output: clean, outcome };
+}
+/** Test/process cleanup. */
+export function resetCursorShellCalls() {
+    policies.clear();
+    outcomes.clear();
+}