cursor-opencode-provider 0.2.3 → 0.2.5

package/dist/language-model.js

@@ -1,23 +1,27 @@
 import fs from "node:fs";
+import path from "node:path";
 import { createHash } from "node:crypto";
-import { bidiRunStream, normalizeAgentRunOrigin } from "./transport/connect.js";
+import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } from "./transport/connect.js";
 import { trace } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
 import { decodeMessage } from "./protocol/messages.js";
 import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, } from "./protocol/tools.js";
+import { describeCursorExecVariant } from "./protocol/exec-variants.js";
 import { advertisedToolNamesFromDescriptors, extractExecDisplayCallId, extractProtobufSubmessage, listProtobufFieldNumbers, parseDisplayToolCall, resolveBridgedOpenCodeToolCall, } from "./protocol/tool-call-bridge.js";
 import { handleKvServerMessage } from "./protocol/kv.js";
 import { handleInteractionQuery, inspectInteractionQueryWire } from "./protocol/interactions.js";
 import { getCheckpoint, setCheckpoint } from "./protocol/checkpoint.js";
 import { conversationBlobCount } from "./protocol/blob-store.js";
 import { bindConversationId, } from "./protocol/conversation-bind.js";
-import { sessionManager } from "./session.js";
+import { resolveContinuationPolicy, sessionManager, } from "./session.js";
+import { CursorAuthError, CursorLocalCancellationError, CursorProtocolError, CursorProviderError, CursorRetryExhaustedError, CursorServerError, CursorTransportError, isTransientGrpcStatus, retrySuppressedError, toCursorProviderError, } from "./errors.js";
 import { readCache, cacheFilePath, resolveVariantParameters, paramsImplyMaxMode, extractCursorVariantParameters, resolveCursorWireModelId } from "./models.js";
 import { buildRequestContext } from "./context/build.js";
 import { opencodeGlobalCacheDir } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { CURSOR_API_HOST, CURSOR_COMPACTION_OPTION } from "./shared.js";
+import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
 let _availableModels;
 // mtime of the cache file the last time we loaded it. Compared on each call
 // so discoverModels' background refresh is picked up without a process restart.
@@ -32,6 +36,173 @@ const toolCatalogBySession = new Map();
 // tool use instead of emitting exec requests. Rebase once on the next turn.
 const postCompactionRebaseBySession = new Set();
 export const MAX_TURN_STATE_SESSIONS = 256;
+const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 8_000,
+};
+const MAX_RETRY_ATTEMPTS = 10;
+const MAX_RETRY_DELAY_MS = 30_000;
+function retryInteger(name, value, fallback) {
+    const resolved = value === undefined ? fallback : value;
+    if (typeof resolved !== "number" || !Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new CursorProtocolError(`Cursor retry ${name} must be a positive integer`);
+    }
+    return resolved;
+}
+export function resolveRetryPolicy(options) {
+    if (options !== undefined && (options === null || typeof options !== "object" || Array.isArray(options))) {
+        throw new CursorProtocolError("Cursor retry options must be an object");
+    }
+    for (const key of Object.keys(options ?? {})) {
+        if (!["maxAttempts", "baseDelayMs", "maxDelayMs"].includes(key)) {
+            throw new CursorProtocolError(`Unknown Cursor retry option: ${key}`);
+        }
+    }
+    const maxAttempts = retryInteger("maxAttempts", options?.maxAttempts, DEFAULT_RETRY_POLICY.maxAttempts);
+    const baseDelayMs = retryInteger("baseDelayMs", options?.baseDelayMs, DEFAULT_RETRY_POLICY.baseDelayMs);
+    const maxDelayMs = retryInteger("maxDelayMs", options?.maxDelayMs, DEFAULT_RETRY_POLICY.maxDelayMs);
+    if (maxAttempts > MAX_RETRY_ATTEMPTS) {
+        throw new CursorProtocolError(`Cursor retry maxAttempts must be no greater than ${MAX_RETRY_ATTEMPTS}`);
+    }
+    if (baseDelayMs > MAX_RETRY_DELAY_MS || maxDelayMs > MAX_RETRY_DELAY_MS) {
+        throw new CursorProtocolError(`Cursor retry delays must be no greater than ${MAX_RETRY_DELAY_MS}ms`);
+    }
+    if (baseDelayMs > maxDelayMs) {
+        throw new CursorProtocolError("Cursor retry baseDelayMs must be no greater than maxDelayMs");
+    }
+    return { maxAttempts, baseDelayMs, maxDelayMs };
+}
+function retryDelayMs(error, attempt, policy) {
+    if (error.retryAfterMs !== undefined)
+        return Math.min(MAX_RETRY_DELAY_MS, error.retryAfterMs);
+    const ceiling = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** Math.max(0, attempt - 1));
+    return Math.floor(Math.random() * ceiling);
+}
+function sleepForRetry(delayMs, signal) {
+    if (signal?.aborted)
+        return Promise.reject(new CursorLocalCancellationError("Cursor retry cancelled"));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(finish, delayMs);
+        const onAbort = () => finish(new CursorLocalCancellationError("Cursor retry cancelled"));
+        function finish(error) {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function retryDelayFromValue(value) {
+    if (typeof value === "string") {
+        const seconds = /^(\d+(?:\.\d+)?)s$/.exec(value.trim());
+        if (seconds)
+            return Math.ceil(Number(seconds[1]) * 1_000);
+        const protobufDelay = retryInfoProtobufDelayMs(value.trim());
+        if (protobufDelay !== undefined)
+            return protobufDelay;
+    }
+    if (!value || typeof value !== "object")
+        return undefined;
+    const duration = value;
+    const seconds = Number(duration.seconds ?? 0);
+    const nanos = Number(duration.nanos ?? 0);
+    if (!Number.isFinite(seconds) || !Number.isFinite(nanos) || seconds < 0 || nanos < 0)
+        return undefined;
+    return Math.ceil(seconds * 1_000 + nanos / 1_000_000);
+}
+/** Decode google.rpc.RetryInfo.value without adding another protobuf schema. */
+function retryInfoProtobufDelayMs(encoded) {
+    if (!encoded || encoded.length > 512 || !/^[A-Za-z0-9+/_-]+={0,2}$/.test(encoded)) {
+        return undefined;
+    }
+    let bytes;
+    try {
+        bytes = Buffer.from(encoded.replaceAll("-", "+").replaceAll("_", "/"), "base64");
+    }
+    catch {
+        return undefined;
+    }
+    const readVarint = (input, start) => {
+        let value = 0n;
+        let shift = 0n;
+        for (let offset = start; offset < input.length && offset < start + 10; offset++) {
+            const byte = input[offset];
+            value |= BigInt(byte & 0x7f) << shift;
+            if ((byte & 0x80) === 0)
+                return [value, offset + 1];
+            shift += 7n;
+        }
+        return undefined;
+    };
+    const outerKey = readVarint(bytes, 0);
+    if (!outerKey || outerKey[0] !== 0x0an)
+        return undefined;
+    const outerLength = readVarint(bytes, outerKey[1]);
+    if (!outerLength || outerLength[0] > BigInt(bytes.length - outerLength[1]))
+        return undefined;
+    const duration = bytes.subarray(outerLength[1], outerLength[1] + Number(outerLength[0]));
+    let offset = 0;
+    let seconds = 0n;
+    let nanos = 0n;
+    while (offset < duration.length) {
+        const key = readVarint(duration, offset);
+        if (!key)
+            return undefined;
+        offset = key[1];
+        const field = Number(key[0] >> 3n);
+        if (Number(key[0] & 7n) !== 0)
+            return undefined;
+        const item = readVarint(duration, offset);
+        if (!item)
+            return undefined;
+        offset = item[1];
+        if (field === 1)
+            seconds = item[0];
+        else if (field === 2)
+            nanos = item[0];
+    }
+    if (seconds > BigInt(Number.MAX_SAFE_INTEGER) || nanos > 999999999n)
+        return undefined;
+    return Math.ceil(Number(seconds) * 1_000 + Number(nanos) / 1_000_000);
+}
+export function connectFrameError(payload) {
+    try {
+        const envelope = JSON.parse(payload);
+        const code = typeof envelope.error?.code === "string" ? envelope.error.code : "unknown";
+        if (code === "unauthenticated" || code === "permission_denied") {
+            return new CursorAuthError(`Cursor authentication failed (${code}); reauthenticate with Cursor`, { code });
+        }
+        let retryAfterMs = retryDelayFromValue(envelope.error?.retryAfter ?? envelope.error?.retry_after);
+        let hasRetryInfo = false;
+        if (Array.isArray(envelope.error?.details)) {
+            for (const detail of envelope.error.details) {
+                if (!detail || typeof detail !== "object")
+                    continue;
+                const record = detail;
+                const type = record.type;
+                if (type === "google.rpc.RetryInfo" || (typeof type === "string" && type.endsWith("/google.rpc.RetryInfo"))) {
+                    hasRetryInfo = true;
+                    retryAfterMs ??= retryDelayFromValue(record.retryDelay ?? record.retry_delay ?? record.value);
+                }
+            }
+        }
+        return new CursorServerError(`Cursor API error (code=${code})`, {
+            transient: isTransientGrpcStatus(code) || hasRetryInfo,
+            replaySafe: true,
+            code,
+            retryAfterMs: retryAfterMs === undefined
+                ? undefined
+                : Math.min(MAX_RETRY_DELAY_MS, retryAfterMs),
+        });
+    }
+    catch {
+        return new CursorProtocolError("Cursor returned a malformed Connect error envelope");
+    }
+}
 function rememberToolCatalog(sessionKey, tools) {
     toolCatalogBySession.delete(sessionKey);
     toolCatalogBySession.set(sessionKey, tools);
@@ -88,6 +259,12 @@ async function doStreamImpl(modelId, options, callOptions) {
         baseUrl: resolveApiBaseURL(options),
     });
     const prompt = callOptions.prompt;
+    const promptTokens = estimatePromptTokens(prompt);
+    const retryPolicy = resolveRetryPolicy(options.retry);
+    // pumpWithRecovery owns the complete per-turn attempt budget.  Opening a
+    // replacement session here must be a single attempt; otherwise setup retry
+    // loops nest inside recovery and `maxAttempts` no longer caps total Runs.
+    const openSession = (startOptions) => startSession(modelId, token, callOptions, options, startOptions);
     // ── Continuation vs fresh turn ──
     // OpenCode embeds *all* historical tool results in every prompt. Only the
     // trailing tool-message suffix (after the last assistant/user message) is a
@@ -97,65 +274,33 @@ async function doStreamImpl(modelId, options, callOptions) {
     const trailingToolResults = extractTrailingToolResults(prompt);
     let session = findContinuationSession(trailingToolResults);
     if (session) {
-        // Deliver only results that this live session is still awaiting.
-        const pendingResults = trailingToolResults.filter((r) => r.sessionId === session.sessionId && session.pending.has(r.execId));
-        trace(`continuation: ${trailingToolResults.length} trailing tool result(s), ` +
-            `${pendingResults.length} pending for sessionId=${session.sessionId} ` +
-            `pending={${[...session.pending.keys()].join(",")}}`);
-        for (const r of pendingResults) {
-            const pending = session.pending.get(r.execId);
-            if (!pending)
-                continue;
-            if (pending.bridged) {
-                // Display-only Cursor tool — OpenCode already ran it; nothing to write
-                // back on the Run stream.
-                session.usageEstimate.inputTokens += estimateTokens(r.output.length);
-                trace(`continuation: bridged tool result execId=${r.execId} toolName=${pending.toolName ?? r.toolName} outLen=${r.output.length}`);
-                sessionManager.resolve(session.sessionId, r.execId);
-                continue;
-            }
-            try {
-                for (const frame of buildExecClientMessages({
-                    execId: r.execId,
-                    resultField: pending.resultField,
-                    output: r.output,
-                    error: r.error,
-                    toolName: pending.toolName ?? r.toolName,
-                })) {
-                    session.stream.write(frame);
-                }
-                // Tool results enlarge Cursor's context for the rest of this Run.
-                session.usageEstimate.inputTokens += estimateTokens(r.output.length);
-                trace(`continuation: wrote exec result execId=${r.execId} field=${pending.resultField} outLen=${r.output.length}`);
-                // Only resolve after the write succeeded — if it threw, the server never
-                // got the result and would block on heartbeats forever otherwise.
-                sessionManager.resolve(session.sessionId, r.execId);
-            }
-            catch (e) {
-                trace(`continuation: write FAILED execId=${r.execId} err=${e.message} — leaving pending`);
-            }
-        }
-        sessionManager.touch(session);
+        // Write pending results onto the held-open Run. A dead stream closes the
+        // session and returns undefined so we fall through to history rebase
+        // instead of pumping a connection that can no longer accept writes.
+        session = deliverContinuationResults(session, trailingToolResults);
     }
-    else if (trailingToolResults.length > 0) {
-        // True continuation (prompt ends with tool results) but the Cursor Run is
-        // gone. Soft-stop instead of re-prompting (doom loop) or hard-erroring.
-        const ids = trailingToolResults.map((r) => `${r.sessionId}:${r.execId}`).join(",");
-        trace(`continuation: ${trailingToolResults.length} orphaned trailing tool result(s) [${ids}] — soft-stop`);
-        return orphanedToolResultsStream(ids);
-    }
-    else {
-        // Fresh turn (prompt ends with user/assistant text). Historical tool
-        // results may exist mid-prompt; they are not live exec replies.
-        const historical = extractToolResults(prompt).length;
-        if (historical > 0) {
-            trace(`fresh turn: ignoring ${historical} historical tool result(s) (not trailing)`);
+    if (!session) {
+        if (trailingToolResults.length > 0) {
+            // True continuation (prompt ends with tool results) but the held-open Run
+            // is gone (or its write path just failed). Rebase the complete OpenCode
+            // prompt onto a fresh conversation: its seed history includes the
+            // completed tool result, so no result or advertised tool is lost and
+            // Cursor can continue instead of deadlocking.
+            const ids = trailingToolResults.map((r) => `${r.sessionId}:${r.execId}`).join(",");
+            trace(`continuation: ${trailingToolResults.length} interrupted trailing tool result(s) [${ids}] — rebasing fresh Run`);
+            session = await openSession({ recovery: true });
+        }
+        else {
+            // Fresh turn (prompt ends with user/assistant text). Historical tool
+            // results may exist mid-prompt; they are not live exec replies.
+            const historical = extractToolResults(prompt).length;
+            if (historical > 0) {
+                trace(`fresh turn: ignoring ${historical} historical tool result(s) (not trailing)`);
+            }
+            session = await openSession();
         }
-        session = await startSession(modelId, token, callOptions, options);
     }
-    const boundSession = session;
-    const textId = crypto.randomUUID();
-    const reasoningId = crypto.randomUUID();
+    let activeSession = session;
     return {
         stream: new ReadableStream({
             async pull(controller) {
@@ -172,13 +317,15 @@ async function doStreamImpl(modelId, options, callOptions) {
                         trace(`pull: stream-start enqueue failed (cancelled) err=${e.message}`);
                         return;
                     }
-                    boundSession.pumpActive = true;
-                    try {
-                        await pump(boundSession, controller, { textId, reasoningId }, callOptions.abortSignal);
-                    }
-                    finally {
-                        boundSession.pumpActive = false;
-                    }
+                    activeSession = await pumpWithRecovery({
+                        initialSession: activeSession,
+                        controller,
+                        abortSignal: callOptions.abortSignal,
+                        promptTokens,
+                        retryPolicy,
+                        recover: () => openSession({ recovery: true }),
+                        onSession: (next) => { activeSession = next; },
+                    });
                     try {
                         controller.close();
                     }
@@ -187,9 +334,9 @@ async function doStreamImpl(modelId, options, callOptions) {
                     }
                 }
                 catch (e) {
-                    boundSession.pumpActive = false;
+                    activeSession.pumpActive = false;
                     trace(`pull: pump threw (cleaning up): ${e.message}`);
-                    sessionManager.closeUnlessPending(boundSession);
+                    sessionManager.close(activeSession);
                     try {
                         controller.error(e instanceof Error ? e : new Error(String(e)));
                     }
@@ -202,12 +349,60 @@ async function doStreamImpl(modelId, options, callOptions) {
                 // OpenCode cancels the ReadableStream after "tool-calls"; keep the
                 // Cursor Run stream alive so the next doStream can write results.
                 trace("ReadableStream cancel() → closeUnlessPending");
-                sessionManager.closeUnlessPending(boundSession);
+                sessionManager.closeUnlessPending(activeSession);
             },
         }),
     };
 }
-async function startSession(modelId, token, callOptions, options) {
+export async function pumpWithRecovery(input) {
+    let session = input.initialSession;
+    const retryPolicy = input.retryPolicy ?? {
+        ...DEFAULT_RETRY_POLICY,
+        maxAttempts: (input.maxRecoveries ?? 1) + 1,
+    };
+    const maxRecoveries = retryPolicy.maxAttempts - 1;
+    input.onSession?.(session);
+    for (let attempt = 0;; attempt++) {
+        const pumpedSession = session;
+        const pumpOwner = Symbol("cursor-pump");
+        sessionManager.beginPump(pumpedSession, pumpOwner);
+        try {
+            await pump(pumpedSession, input.controller, {
+                textId: crypto.randomUUID(),
+                reasoningId: crypto.randomUUID(),
+                promptTokens: input.promptTokens ?? 0,
+            }, input.abortSignal);
+            return session;
+        }
+        catch (error) {
+            const failure = toCursorProviderError(error, {
+                replaySafe: error instanceof CursorProviderError ? error.replaySafe : false,
+                fallback: "Cursor Run interrupted",
+            });
+            if (!failure.transient)
+                throw failure;
+            if (!failure.replaySafe) {
+                throw retrySuppressedError(failure, "after visible output or stateful server activity", attempt + 1, maxRecoveries + 1);
+            }
+            if (attempt >= maxRecoveries) {
+                throw new CursorRetryExhaustedError(attempt + 1, failure);
+            }
+            trace(`Run interrupted: sessionId=${pumpedSession.sessionId} attempt=${attempt + 1}/${maxRecoveries} ` +
+                `err=${failure.message} — rebasing fresh Run`);
+            sessionManager.close(pumpedSession, "remote-error", failure);
+            const delayMs = retryDelayMs(failure, attempt + 1, retryPolicy);
+            trace(`Run retry backoff: attempt=${attempt + 1}/${maxRecoveries} delayMs=${delayMs}`);
+            await sleepForRetry(delayMs, input.abortSignal);
+            session = await input.recover();
+            input.onSession?.(session);
+        }
+        finally {
+            sessionManager.endPump(pumpedSession, pumpOwner);
+        }
+    }
+}
+async function startSession(modelId, token, callOptions, options, startOptions) {
+    const continuationPolicy = resolveContinuationPolicy(options.continuation);
     const prompt = callOptions.prompt;
     const incomingTools = extractTools(callOptions);
     const sessionKey = opencodeSessionKey(callOptions);
@@ -224,23 +419,30 @@ async function startSession(modelId, token, callOptions, options) {
     const tools = toolState.advertisedTools;
     const allowTools = toolState.allowTools;
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
+    const recovery = startOptions?.recovery === true;
     // Compaction must not reuse the prior conversation; its first normal turn
     // must also rebase so the summary-agent checkpoint cannot replace the normal
     // system prompt and OpenCode's newly compacted history.
-    const bound = bindConversationId(sessionKey, { reset: resetState.reset });
+    const bound = bindConversationId(sessionKey, { reset: resetState.reset || recovery });
     const conversationId = bound.conversationId;
     if (bound.reset) {
-        trace(`conversation reset: reason=${resetState.reason ?? "unknown"} ` +
+        trace(`conversation reset: reason=${recovery ? "interrupted-run" : (resetState.reason ?? "unknown")} ` +
             `sessionKey=${sessionKey ?? "(none)"} ` +
             `previousId=${bound.previousId ?? "-"} → conversationId=${conversationId}`);
     }
-    const userText = extractUserText([...prompt].reverse().find((m) => m.role === "user")) || ".";
+    const userText = recovery
+        ? "Continue the interrupted turn from the conversation history above. Do not repeat completed work."
+        : (extractUserText([...prompt].reverse().find((m) => m.role === "user")) || ".");
+    const workspaceRoot = path.resolve(options.workspaceRoot || process.cwd());
     const baseSystemPrompt = extractSystemPrompt(prompt);
-    const interactionGuidance = buildOpenCodeInteractionGuidance(tools, isCompaction);
+    const interactionGuidance = buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceRoot);
     const systemPrompt = interactionGuidance
         ? [baseSystemPrompt, interactionGuidance].filter(Boolean).join("\n\n")
         : baseSystemPrompt;
-    const history = extractPromptHistory(prompt);
+    const history = extractPromptHistory(prompt, {
+        preserveTrailingUser: recovery,
+        toolResults: isCompaction ? "all" : (recovery ? "trailing" : "omit"),
+    });
     await loadAvailableModels();
     // Resolve the region-specific Run stream origin once per process (memoized
     // in agent-url.ts). Explicit agent host overrides skip GetServerConfig but
@@ -275,7 +477,6 @@ async function startSession(modelId, token, callOptions, options) {
         baseURL: agentBaseUrl,
         headers: options.headers,
     });
-    const workspaceRoot = options.workspaceRoot || process.cwd();
     const requestContext = await buildRequestContext({ workspaceRoot, tools });
     // Resolve descriptors once from the merged OpenCode config so MCP identity is
     // consistent across AgentRunRequest and both request_context reply paths.
@@ -294,7 +495,6 @@ async function startSession(modelId, token, callOptions, options) {
         conversationState,
         parameterValues,
         maxMode,
-        availableModels: _availableModels,
         tools,
         toolDescriptors,
         requestContext,
@@ -331,10 +531,17 @@ async function startSession(modelId, token, callOptions, options) {
         trace(`hash systemPrompt sha256=${sha(systemPrompt)}`);
     if (conversationState)
         trace(`hash checkpoint sha256=${sha(conversationState)}`);
-    stream.write(reqBytes);
+    try {
+        await writeWithBackpressure(stream, reqBytes, "initial Run request");
+    }
+    catch (error) {
+        stream.destroy();
+        throw error;
+    }
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
+        openCodeSessionId: sessionKey,
         stream,
         frames: stream.frames()[Symbol.asyncIterator](),
         pending: new Map(),
@@ -346,15 +553,50 @@ async function startSession(modelId, token, callOptions, options) {
         allowTools,
         usageEstimate,
         pumpActive: false,
+        pumpOwner: null,
         heartbeat: null,
-        expiresAt: Date.now() + 300_000,
+        heartbeatCancel: null,
+        hardDeadlineTimer: null,
+        semanticDeadlineCancel: null,
+        terminalUnsubscribe: null,
+        deferredTerminalReason: null,
+        policy: continuationPolicy,
+        createdAt: Date.now(),
+        lastInboundAt: Date.now(),
+        lastHeartbeatWriteAt: Date.now(),
+        semanticDeadlineAt: Date.now() + continuationPolicy.semanticIdleMs,
+        closeError: null,
+        closed: false,
     };
+    sessionManager.registerSession(session);
+    let heartbeatWritePending = false;
     session.heartbeat = setInterval(() => {
-        try {
-            stream.write(buildHeartbeat());
+        if (session.closed)
+            return;
+        if (heartbeatWritePending) {
+            sessionManager.close(session, "heartbeat-write-failed", new CursorTransportError("Cursor heartbeat write remained backpressured", {
+                transient: false,
+                replaySafe: false,
+                code: "CURSOR_HEARTBEAT_BACKPRESSURE",
+            }));
+            return;
         }
-        catch { /* closed */ }
-    }, 5000);
+        heartbeatWritePending = true;
+        void writeWithBackpressure(stream, buildHeartbeat(), "heartbeat")
+            .then(() => sessionManager.recordHeartbeatWrite(session))
+            .catch((cause) => {
+            sessionManager.close(session, "heartbeat-write-failed", toCursorProviderError(cause, {
+                replaySafe: false,
+                fallback: "Cursor heartbeat write failed",
+            }));
+        })
+            .finally(() => { heartbeatWritePending = false; });
+    }, continuationPolicy.heartbeatMs);
+    session.heartbeat.unref?.();
+    session.heartbeatCancel = () => {
+        if (session.heartbeat)
+            clearInterval(session.heartbeat);
+    };
     callOptions.abortSignal?.addEventListener("abort", () => {
         // Abort after tool-calls is normal — preserve pending sessions.
         trace("abortSignal aborted → closeUnlessPending");
@@ -362,37 +604,6 @@ async function startSession(modelId, token, callOptions, options) {
     }, { once: true });
     return session;
 }
-/** Emit a soft-stop stream when trailing tool results have no live Cursor Run. */
-function orphanedToolResultsStream(ids) {
-    const textId = crypto.randomUUID();
-    const message = `The Cursor agent stream ended before tool results could be delivered ` +
-        `(${ids.split(",").length} result(s)). Please retry your request.`;
-    trace(`orphanedToolResultsStream: soft-stop for [${ids}]`);
-    return {
-        stream: new ReadableStream({
-            pull(controller) {
-                try {
-                    controller.enqueue({ type: "stream-start", warnings: [] });
-                    controller.enqueue({ type: "text-start", id: textId });
-                    controller.enqueue({ type: "text-delta", id: textId, delta: message });
-                    controller.enqueue({ type: "text-end", id: textId });
-                    controller.enqueue({
-                        type: "finish",
-                        finishReason: { unified: "stop", raw: undefined },
-                        usage: {
-                            inputTokens: { total: 0, noCache: undefined, cacheRead: 0, cacheWrite: 0 },
-                            outputTokens: { total: 0, text: undefined, reasoning: undefined },
-                        },
-                    });
-                    controller.close();
-                }
-                catch (e) {
-                    trace(`orphanedToolResultsStream: enqueue failed err=${e.message}`);
-                }
-            },
-        }),
-    };
-}
 /**
  * OpenCode re-sends the full tool-result history on every continuation. Prefer
  * the newest result that still has a live pending exec on its tagged session.
@@ -406,6 +617,70 @@ export function findContinuationSession(toolResults) {
     }
     return undefined;
 }
+/**
+ * Deliver trailing tool results onto a live continuation session.
+ * Returns the same session when writes succeed (or only bridged results were
+ * cleared). Returns undefined after closing the session when a write fails, so
+ * the caller can rebase onto a fresh Run instead of pumping a dead stream.
+ */
+export function deliverContinuationResults(session, trailingToolResults) {
+    const pendingResults = trailingToolResults.filter((r) => r.sessionId === session.sessionId && session.pending.has(r.execId));
+    trace(`continuation: ${trailingToolResults.length} trailing tool result(s), ` +
+        `${pendingResults.length} pending for sessionId=${session.sessionId} ` +
+        `pending={${[...session.pending.keys()].join(",")}}`);
+    for (const r of pendingResults) {
+        const claim = sessionManager.claim(session.sessionId, r.execId);
+        if ("kind" in claim) {
+            if (claim.kind === "deliverable") {
+                throw new CursorProtocolError("Cursor continuation claim remained unclaimed");
+            }
+            if (claim.kind === "duplicate") {
+                trace(`continuation: skipped duplicate execId=${r.execId} reason=${claim.reason}`);
+                continue;
+            }
+            trace(`continuation: unavailable execId=${r.execId} reason=${claim.reason}`);
+            return undefined;
+        }
+        const pending = claim.pending;
+        let frames = [];
+        if (!pending.bridged) {
+            try {
+                const shellResult = pending.resultField === "shell_stream"
+                    ? consumeCursorShellResult(r.toolCallId, r.output)
+                    : undefined;
+                frames = buildExecClientMessages({
+                    execId: r.execId,
+                    resultField: pending.resultField,
+                    output: shellResult?.output ?? r.output,
+                    error: r.error,
+                    toolName: pending.toolName ?? r.toolName,
+                    resultMetadata: pending.resultMetadata,
+                    shellOutcome: shellResult?.outcome,
+                });
+            }
+            catch (error) {
+                trace(`continuation: result encode FAILED execId=${r.execId} err=${error.message}`);
+                sessionManager.close(session, "result-write-failed");
+                return undefined;
+            }
+        }
+        const outcome = sessionManager.deliverClaim(claim, frames);
+        if (outcome.kind !== "delivered") {
+            trace(`continuation: delivery stopped execId=${r.execId} reason=${outcome.reason}`);
+            if (outcome.kind === "duplicate")
+                continue;
+            return undefined;
+        }
+        session.usageEstimate.inputTokens += estimateTokens(r.output.length);
+        if (pending.bridged) {
+            trace(`continuation: completed bridged result execId=${r.execId} toolName=${pending.toolName ?? r.toolName} outLen=${r.output.length}`);
+            continue;
+        }
+        trace(`continuation: wrote exec result execId=${r.execId} field=${pending.resultField} ` +
+            `frames=${outcome.framesWritten} outLen=${r.output.length}`);
+    }
+    return session;
+}
 async function loadAvailableModels() {
     const cacheDir = opencodeGlobalCacheDir();
     try {
@@ -439,23 +714,89 @@ function resolveExplicitAgentBaseURL(options) {
         return undefined;
     const normalized = normalizeAgentRunOrigin(raw);
     if (!normalized) {
-        throw new Error("Invalid Cursor agent base URL override: expected https://*.cursor.sh");
+        throw new CursorProtocolError("Invalid Cursor agent base URL override: expected https://*.cursor.sh");
     }
     return normalized;
 }
 function isTruthyEnv(value) {
     return value === "1" || value === "true";
 }
+async function writeWithBackpressure(stream, message, operation) {
+    let accepted;
+    try {
+        accepted = stream.write(message);
+    }
+    catch (cause) {
+        throw toCursorProviderError(cause, {
+            replaySafe: false,
+            fallback: `Cursor ${operation} write failed`,
+        });
+    }
+    if (accepted !== false)
+        return;
+    if (!stream.waitForDrain) {
+        throw new CursorTransportError(`Cursor ${operation} write was backpressured`, {
+            transient: false,
+            replaySafe: false,
+            code: "CURSOR_WRITE_BACKPRESSURE",
+        });
+    }
+    try {
+        await stream.waitForDrain(5_000);
+    }
+    catch (cause) {
+        throw toCursorProviderError(cause, {
+            replaySafe: false,
+            fallback: `Cursor ${operation} backpressure drain failed`,
+        });
+    }
+}
+async function nextFrameWithSemanticDeadline(session) {
+    const remainingMs = session.semanticDeadlineAt - Date.now();
+    if (remainingMs <= 0) {
+        throw new CursorTransportError(`Cursor semantic-progress timeout after ${session.policy.semanticIdleMs}ms`, { transient: true, replaySafe: true, code: "CURSOR_SEMANTIC_IDLE_TIMEOUT" });
+    }
+    let timer;
+    let rejectCancelled;
+    const deadline = new Promise((_, reject) => {
+        rejectCancelled = reject;
+        timer = setTimeout(() => {
+            reject(new CursorTransportError(`Cursor semantic-progress timeout after ${session.policy.semanticIdleMs}ms`, { transient: true, replaySafe: true, code: "CURSOR_SEMANTIC_IDLE_TIMEOUT" }));
+        }, remainingMs);
+        timer.unref?.();
+    });
+    session.semanticDeadlineCancel = () => {
+        rejectCancelled?.(session.closeError ?? new CursorTransportError("Cursor semantic wait cancelled locally", {
+            transient: false,
+            replaySafe: false,
+        }));
+    };
+    try {
+        return await Promise.race([session.frames.next(), deadline]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        session.semanticDeadlineCancel = null;
+    }
+}
 /**
  * Read the held-open stream, emitting stream parts, until the turn boundary:
  *  - a tool call (exec_server_message) → emit tool-call, finish "tool-calls",
  *    and KEEP the session open for the result on the next doStream call;
- *  - turn_ended / stream end → finish "stop" and close the session.
+ *  - turn_ended → finish "stop" and close the session;
+ *  - transport EOF before turn_ended → throw for one fresh-Run recovery.
  */
 export async function pump(session, controller, ids, abortSignal) {
+    sessionManager.registerSession(session);
     const { textId, reasoningId } = ids;
+    const promptTokens = ids.promptTokens ?? 0;
+    const advertisedToolNames = advertisedToolNamesFromDescriptors(session.toolDescriptors);
+    const advertisedToolNameSet = new Set(advertisedToolNames);
     let textStarted = false;
     let reasoningStarted = false;
+    let emittedOutputChars = 0;
+    let replaySafe = true;
     // OpenCode cancels the ReadableStream between turns (see the cancel handler
     // in doStreamImpl). The frames iterator can still yield a final `done` after
     // the cancel lands — controller.enqueue on a cancelled controller throws.
@@ -485,6 +826,80 @@ export async function pump(session, controller, ids, abortSignal) {
         }
         streamClosed = true;
     };
+    /** Reply on Cursor's correlated exec channel without exposing a host tool call. */
+    const rejectExec = (parsed, reason, label) => {
+        try {
+            for (const frame of buildExecClientMessages({
+                execId: parsed.id,
+                resultField: parsed.resultField,
+                output: "",
+                error: reason,
+                toolName: parsed.toolName,
+                resultMetadata: parsed.resultMetadata,
+            })) {
+                session.stream.write(frame);
+            }
+            trace(`exec: REFUSED ${label} toolName=${parsed.toolName} id=${parsed.id}`);
+            return true;
+        }
+        catch (e) {
+            const error = new Error(`Failed to reject Cursor tool request (${label}): ${e.message}`);
+            trace(`exec: REFUSED reply FAILED ${error.message}`);
+            safeError(error);
+            sessionManager.close(session);
+            return false;
+        }
+    };
+    /**
+     * Cursor's streamed edit handshake reads the target before it sends the
+     * replacement through write_args. For a new file that read naturally fails,
+     * which makes the model abandon the edit and fall back to a shell heredoc.
+     * Treat only a missing target correlated to an edit_tool_call as an empty
+     * file, allowing Cursor to continue to the ordinary OpenCode write call.
+     */
+    const recoverMissingEditRead = (parsed, displayCallId) => {
+        if (!displayCallId ||
+            parsed.resultField !== "read_result" ||
+            parsed.toolName !== "read" ||
+            !advertisedToolNameSet.has("write"))
+            return false;
+        const stored = session.displayToolCalls.get(displayCallId);
+        const display = parseDisplayToolCall(displayCallId, stored);
+        if (display?.variant !== "edit_tool_call" || display.bridgeable === false)
+            return false;
+        const requestedPath = typeof parsed.args.filePath === "string" ? parsed.args.filePath : "";
+        const editPath = typeof display.args.path === "string" ? display.args.path : "";
+        if (!requestedPath || !editPath)
+            return false;
+        const workspaceRoot = typeof session.requestContext.workspace_project_dir === "string"
+            ? session.requestContext.workspace_project_dir
+            : process.cwd();
+        const resolvePath = (value) => path.resolve(workspaceRoot, value);
+        const absolutePath = resolvePath(requestedPath);
+        if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
+            return false;
+        try {
+            for (const frame of buildExecClientMessages({
+                execId: parsed.id,
+                resultField: parsed.resultField,
+                output: "",
+                toolName: parsed.toolName,
+                resultMetadata: { path: requestedPath },
+            })) {
+                session.stream.write(frame);
+            }
+            trace(`exec: missing edit target treated as empty file id=${parsed.id} ` +
+                `path=${JSON.stringify(requestedPath)}; awaiting write_args`);
+            return true;
+        }
+        catch (e) {
+            const error = new Error(`Failed to recover Cursor edit read for a new file: ${e.message}`);
+            trace(`exec: edit read recovery FAILED ${error.message}`);
+            safeError(error);
+            sessionManager.close(session);
+            return true;
+        }
+    };
     /** AI SDK V3 requires text-end / reasoning-end before finish or tool-call. */
     const closeOpenSpans = () => {
         for (const part of spanEndParts({ textStarted, reasoningStarted, textId, reasoningId })) {
@@ -496,6 +911,7 @@ export async function pump(session, controller, ids, abortSignal) {
     const emitText = (text) => {
         if (!text)
             return;
+        replaySafe = false;
         // Close reasoning before text (hosts expect reasoning-end before text-start).
         if (reasoningStarted && !textStarted) {
             safeEnqueue({ type: "reasoning-end", id: reasoningId });
@@ -506,17 +922,22 @@ export async function pump(session, controller, ids, abortSignal) {
             textStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        safeEnqueue({ type: "text-delta", id: textId, delta: text });
+        if (safeEnqueue({ type: "text-delta", id: textId, delta: text })) {
+            emittedOutputChars += text.length;
+        }
     };
     const emitReasoning = (text) => {
         if (!text)
             return;
+        replaySafe = false;
         if (!reasoningStarted) {
             safeEnqueue({ type: "reasoning-start", id: reasoningId });
             reasoningStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text });
+        if (safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text })) {
+            emittedOutputChars += text.length;
+        }
     };
     const emitFinish = (te, reason) => {
         closeOpenSpans();
@@ -532,25 +953,32 @@ export async function pump(session, controller, ids, abortSignal) {
         const est = session.usageEstimate;
         const usage = {
             inputTokens: {
-                total: est.inputTokens,
+                total: promptTokens,
                 noCache: undefined,
-                cacheRead: est.cacheRead,
-                cacheWrite: est.cacheWrite,
+                cacheRead: 0,
+                cacheWrite: 0,
             },
             outputTokens: {
-                total: est.outputTokens,
+                total: estimateTokens(emittedOutputChars),
                 text: undefined,
                 reasoning: undefined,
             },
         };
+        const providerMetadata = te ? cursorTurnEndedProviderMetadata(te) : undefined;
         const reasonLabel = typeof reason === "object" && reason && "unified" in reason
             ? String(reason.unified ?? "unknown")
             : String(reason);
         trace(`finish: reason=${reasonLabel} ` +
-            `in=${est.inputTokens} out=${est.outputTokens} ` +
-            `cacheRead=${est.cacheRead} cacheWrite=${est.cacheWrite} ` +
+            `requestIn=${usage.inputTokens.total} requestOut=${usage.outputTokens.total} ` +
+            `rawIn=${est.inputTokens} rawOut=${est.outputTokens} ` +
+            `rawCacheRead=${est.cacheRead} rawCacheWrite=${est.cacheWrite} ` +
             `source=${te ? "turn_ended" : "estimate"}`);
-        safeEnqueue({ type: "finish", usage, finishReason: reason });
+        safeEnqueue({
+            type: "finish",
+            usage,
+            finishReason: reason,
+            ...(providerMetadata ? { providerMetadata } : {}),
+        });
     };
     while (true) {
         // Consumer cancelled / closed the ReadableStream. Stop reading Cursor
@@ -568,31 +996,45 @@ export async function pump(session, controller, ids, abortSignal) {
             sessionManager.closeUnlessPending(session);
             return;
         }
-        const next = await session.frames.next();
+        let next;
+        try {
+            next = session.pending.size === 0
+                ? await nextFrameWithSemanticDeadline(session)
+                : await session.frames.next();
+        }
+        catch (error) {
+            closeOpenSpans();
+            const failure = error instanceof CursorProviderError
+                ? error
+                : new CursorRunInterruptedError(`Cursor Run frame stream interrupted: ${error.message}`, { cause: error });
+            failure.replaySafe = replaySafe && failure.replaySafe;
+            throw failure;
+        }
         if (next.done) {
-            trace("pump: frames iterator ended with NO frames received (silent end)");
-            emitFinish(undefined, { unified: "stop", raw: undefined });
-            sessionManager.close(session);
-            return;
+            closeOpenSpans();
+            trace("pump: frames iterator ended before turn_ended");
+            const failure = new CursorRunInterruptedError();
+            failure.replaySafe = replaySafe;
+            throw failure;
         }
         const frame = next.value;
         if (frame.flags & 0x02) {
-            // End-stream: the real server half-closes without a trailer, but surface
-            // any Connect error payload if present.
+            // A successful agent turn has an explicit turn_ended update before the
+            // Connect envelope closes. Reaching end-stream here means the Run was
+            // interrupted, even if the HTTP status itself was 200.
+            let payload = "";
             if (frame.payload.length > 0) {
                 try {
-                    const text = new TextDecoder().decode(decodeFramePayload(frame));
-                    if (text.includes('"error"')) {
-                        safeError(new Error(`Cursor API error: ${text.slice(0, 500)}`));
-                        sessionManager.close(session);
-                        return;
-                    }
+                    payload = new TextDecoder().decode(decodeFramePayload(frame));
                 }
                 catch { /* not decodable */ }
             }
-            emitFinish(undefined, { unified: "stop", raw: undefined });
-            sessionManager.close(session);
-            return;
+            closeOpenSpans();
+            const failure = payload
+                ? connectFrameError(payload)
+                : new CursorRunInterruptedError();
+            failure.replaySafe = replaySafe && failure.replaySafe;
+            throw failure;
         }
         // decodeFramePayload can throw on a corrupt gzip payload (gunzipSync).
         // Skip the frame rather than abort the whole turn.
@@ -612,6 +1054,7 @@ export async function pump(session, controller, ids, abortSignal) {
             // A single malformed/truncated frame must not abort the whole turn
             // (protobufjs throws "index out of range: …" on length overruns). Log it
             // and keep pumping.
+            replaySafe = false;
             const preview = Array.from(payload.subarray(0, 32))
                 .map((x) => x.toString(16).padStart(2, "0"))
                 .join("");
@@ -625,6 +1068,21 @@ export async function pump(session, controller, ids, abortSignal) {
         const interactionQuery = asm.interaction_query;
         const checkpointRaw = asm.conversation_checkpoint_update;
         const topField = payload.length > 0 ? payload[0] >> 3 : 0;
+        const textProgress = iu?.text_delta?.text;
+        const thinkingProgress = iu?.thinking_delta?.text;
+        const checkpointProgress = normalizeCheckpointBytes(checkpointRaw);
+        if ((typeof textProgress === "string" && textProgress.length > 0) ||
+            (typeof thinkingProgress === "string" && thinkingProgress.length > 0) ||
+            !!iu?.turn_ended ||
+            !!iu?.tool_call_started ||
+            !!iu?.tool_call_completed ||
+            !!esm ||
+            !!kv ||
+            !!interactionQuery ||
+            !!checkpointProgress?.length) {
+            replaySafe = false;
+            sessionManager.recordSemanticProgress(session);
+        }
         {
             const iuKind = iu ? Object.keys(iu).find((k) => iu[k]) : undefined;
             trace(`pump frame: topField=${topField} interaction_update=${iuKind ?? "-"} ` +
@@ -748,7 +1206,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         trace(`exec request_context: replied`);
                     }
                     catch (e) {
-                        trace(`exec request_context: write FAILED ${e.message}`);
+                        const error = new Error(`Failed to answer Cursor request_context probe: ${e.message}`);
+                        trace(`exec request_context: write FAILED ${error.message}`);
+                        safeError(error);
+                        sessionManager.close(session);
+                        return;
                     }
                 }
                 else if (esm.mcp_state_exec_args) {
@@ -774,32 +1236,11 @@ export async function pump(session, controller, ids, abortSignal) {
                 else {
                     const parsed = parseExecServerMessage(esm);
                     const displayCallId = extractExecDisplayCallId(esm);
-                    if (displayCallId) {
-                        session.displayToolCalls.delete(displayCallId);
-                        trace(`exec: claimed display callId=${displayCallId}`);
-                    }
                     trace(`exec: id=${parsed?.id} variant=${parsed ? Object.keys(parsed).join(",") : "none"} toolName=${parsed?.toolName} resultField=${parsed?.resultField}`);
                     if (parsed) {
                         if (parsed.localError) {
-                            trace(`exec: REFUSED invalid mapping toolName=${parsed.toolName} error=${parsed.localError}`);
-                            try {
-                                for (const frame of buildExecClientMessages({
-                                    execId: parsed.id,
-                                    resultField: parsed.resultField,
-                                    output: "",
-                                    error: parsed.localError,
-                                    toolName: parsed.toolName,
-                                })) {
-                                    session.stream.write(frame);
-                                }
-                            }
-                            catch (e) {
-                                const error = new Error(`Failed to reject unsupported Cursor tool request: ${e.message}`);
-                                trace(`exec: invalid-mapping reply FAILED ${error.message}`);
-                                safeError(error);
-                                sessionManager.close(session);
+                            if (!rejectExec(parsed, parsed.localError, "invalid mapping"))
                                 return;
-                            }
                             continue;
                         }
                         // OpenCode throws "Tool call not allowed while generating summary"
@@ -808,26 +1249,41 @@ export async function pump(session, controller, ids, abortSignal) {
                         // pumping for text / turn_ended instead of emitting tool-call.
                         if (!session.allowTools) {
                             const reason = "Tool calls are not available during this turn (summary/compaction).";
-                            trace(`exec: REFUSED (allowTools=false) toolName=${parsed.toolName} — auto-replying`);
-                            try {
-                                for (const frame of buildExecClientMessages({
-                                    execId: parsed.id,
-                                    resultField: parsed.resultField,
-                                    output: "",
-                                    error: reason,
-                                    toolName: parsed.toolName,
-                                })) {
-                                    session.stream.write(frame);
-                                }
-                            }
-                            catch (e) {
-                                trace(`exec: REFUSED write FAILED ${e.message}`);
-                            }
+                            if (!rejectExec(parsed, reason, "allowTools=false"))
+                                return;
+                            continue;
+                        }
+                        // Cursor has native capabilities (Task, filesystem, shell, etc.) in
+                        // addition to the MCP descriptors sent by this provider. The model
+                        // can request one even when the current OpenCode agent omitted its
+                        // corresponding host tool. Emitting that request makes OpenCode
+                        // manufacture an `invalid` tool result. Refuse it on the held-open
+                        // Cursor exec channel instead, using the request's exact typed result.
+                        if (!advertisedToolNameSet.has(parsed.toolName)) {
+                            const available = advertisedToolNames.length > 0
+                                ? advertisedToolNames.join(", ")
+                                : "none";
+                            const reason = `OpenCode tool '${parsed.toolName}' is unavailable for the current agent. ` +
+                                `Available tools: ${available}. Continue using only available tools; do not retry ` +
+                                `'${parsed.toolName}'.`;
+                            trace(`exec: unavailable catalog target toolName=${parsed.toolName} ` +
+                                `advertised=[${advertisedToolNames.join(",")}]`);
+                            if (!rejectExec(parsed, reason, "unavailable tool"))
+                                return;
                             continue;
                         }
+                        if (recoverMissingEditRead(parsed, displayCallId))
+                            continue;
+                        if (displayCallId) {
+                            session.displayToolCalls.delete(displayCallId);
+                            trace(`exec: claimed display callId=${displayCallId}`);
+                        }
                         const tc = buildToolCallPart(parsed, session.sessionId);
+                        if (parsed.resultField === "shell_stream") {
+                            registerCursorShellCall(tc.toolCallId, parsed.resultMetadata);
+                        }
                         // Keep the stream open; the result arrives on the next doStream call.
-                        sessionManager.registerPending(parsed.id, session, parsed.resultField, parsed.toolName);
+                        sessionManager.registerPending(parsed.id, session, parsed.resultField, parsed.toolName, false, parsed.resultMetadata);
                         // tc.input is already a JSON string (LanguageModelV3ToolCall.input).
                         trace(`exec: EMITTED tool-call toolCallId=${tc.toolCallId} toolName=${tc.toolName} inputLen=${tc.input.length}`);
                         // Close open text/reasoning spans before tool-call (required by AI SDK V3).
@@ -846,11 +1302,12 @@ export async function pump(session, controller, ids, abortSignal) {
                     // wrong reply recreates the heartbeat-only deadlock. Fail promptly so
                     // schema drift is actionable.
                     const variantField = detectExecVariantField(payload);
+                    const variantDescription = describeCursorExecVariant(variantField);
                     const hex = Array.from(payload.subarray(0, 48))
                         .map((x) => x.toString(16).padStart(2, "0"))
                         .join("");
-                    trace(`exec UNMAPPED: id=${esmId} variantField=${variantField} keys=[${Object.keys(esm).join(",")}] hex=${hex}`);
-                    const err = new Error(`Unsupported Cursor exec variant field #${variantField ?? "unknown"} (id=${esmId})`);
+                    trace(`exec UNMAPPED: id=${esmId} variant=${variantDescription} keys=[${Object.keys(esm).join(",")}] hex=${hex}`);
+                    const err = new Error(`Unsupported Cursor exec variant ${variantDescription} (id=${esmId})`);
                     safeError(err);
                     sessionManager.close(session);
                     return;
@@ -859,7 +1316,8 @@ export async function pump(session, controller, ids, abortSignal) {
             else if (interactionQuery) {
                 // InteractionQuery is a must-reply channel, just like exec and KV. AI
                 // SDK has no Cursor-specific UI callback, so answer immediately with the
-                // conservative headless policy from protocol/interactions.ts.
+                // conservative headless policy from protocol/interactions.ts (including
+                // F14 create_plan auto-ack / empty plan_uri for CLI headless parity).
                 try {
                     const handled = handleInteractionQuery(interactionQuery, payload);
                     session.stream.write(handled.reply);
@@ -892,7 +1350,13 @@ export async function pump(session, controller, ids, abortSignal) {
                             `found=${handled.found} echoed=${!!handled.echoed} ` +
                             `sessionBlobs=${session.blobs.size} convBlobs=${conversationBlobCount(session.conversationId)}`);
                     }
-                    catch { /* stream closed; pump will surface end */ }
+                    catch (e) {
+                        const error = new Error(`Failed to answer Cursor KV blob request: ${e.message}`);
+                        trace(`kv: write FAILED ${error.message}`);
+                        safeError(error);
+                        sessionManager.close(session);
+                        return;
+                    }
                 }
             }
         }
@@ -931,11 +1395,13 @@ function extractToolResults(prompt) {
             const p = part;
             if (p.type !== "tool-result")
                 continue;
-            const parsed = parseExecIdFromToolCallId(p.toolCallId ?? "");
+            const toolCallId = p.toolCallId ?? "";
+            const parsed = parseExecIdFromToolCallId(toolCallId);
             if (!parsed)
                 continue;
             const { text, isError } = toolResultOutputToText(p.output);
             out.push({
+                toolCallId,
                 sessionId: parsed.sessionId,
                 execId: parsed.execId,
                 toolName: p.toolName ?? "mcp",
@@ -1001,10 +1467,12 @@ function extractSystemPrompt(prompt) {
  * Redirect only to OpenCode tools that are genuinely advertised this turn;
  * compaction keeps its dedicated summary prompt unchanged.
  */
-export function buildOpenCodeInteractionGuidance(tools, isCompaction) {
+export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceRoot) {
     if (isCompaction)
         return undefined;
     const names = new Set(tools.map((tool) => tool.name));
+    if (names.size === 0)
+        return undefined;
     const instructions = [];
     if (names.has("question")) {
         instructions.push("- When user input is required, call the OpenCode `question` tool; do not use Cursor's native AskQuestion interaction.");
@@ -1021,10 +1489,18 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction) {
     if (names.has("webfetch")) {
         instructions.push("- To fetch a known URL, call the OpenCode `webfetch` tool; do not use Cursor's native WebFetch interaction.");
     }
-    if (instructions.length === 0)
-        return undefined;
+    if (names.has("write")) {
+        instructions.push(names.has("edit")
+            ? "- For file changes, use OpenCode `edit` for targeted changes to existing files and `write` to create files or intentionally replace complete contents; do not use shell, Python, or heredocs to change file content while these tools are available."
+            : "- Use OpenCode `write` for file-content changes; do not use shell, Python, or heredocs to change file content while it is available.");
+    }
     return [
-        "OpenCode owns interactive workflows and tool execution for this session. Use the advertised OpenCode tools below instead of equivalent Cursor-native UI interactions:",
+        `OpenCode exposes exactly these executable tools for this turn: ${[...names].map((name) => `\`${name}\``).join(", ")}.`,
+        `Workspace root: ${JSON.stringify(workspaceRoot)}. Resolve workspace paths against exactly this root; never invent an absolute prefix, and verify uncertain paths with an available tool before using them.`,
+        "Call only tools in that exact list. Cursor-native tools that are not listed—including Task/subagents—are unavailable; do not invoke them. If a capability is absent, complete the work directly with the listed tools or explain the limitation.",
+        ...(instructions.length > 0
+            ? ["Use these OpenCode tools instead of equivalent Cursor-native UI interactions:"]
+            : []),
         ...instructions,
         "Emit the actual tool call and wait for its result; never merely claim or summarize that a tool was used.",
     ].join("\n");
@@ -1035,14 +1511,53 @@ export function estimateTokens(chars) {
         return 0;
     return Math.ceil(chars / 4);
 }
+/** Estimate current-request prompt tokens from the complete serialized V3 prompt. */
+export function estimatePromptTokens(prompt) {
+    const serializedContent = prompt
+        .map((message) => typeof message.content === "string"
+        ? message.content
+        : (JSON.stringify(message.content) ?? ""))
+        .join("\n");
+    return estimateTokens(serializedContent.length);
+}
+/** Preserve cumulative Cursor counters as diagnostics, never as AI SDK request usage. */
+export function cursorTurnEndedProviderMetadata(te) {
+    const counter = (key) => {
+        const value = te[key];
+        return typeof value === "number" && Number.isFinite(value) && value >= 0
+            ? Math.trunc(value)
+            : 0;
+    };
+    return {
+        cursor: {
+            usageVersion: 2,
+            inputTokensRaw: counter("input_tokens"),
+            outputTokensRaw: counter("output_tokens"),
+            cacheReadRaw: counter("cache_read"),
+            cacheWriteRaw: counter("cache_write"),
+            reasoningTokensRaw: counter("reasoning_tokens"),
+        },
+    };
+}
 /**
- * Prior prompt turns for a seed ConversationStateStructure after compaction
- * reset. Drops the trailing user message (live action), but preserves tool
- * result payloads as labeled assistant observations for Cursor's text history.
+ * Prior prompt turns for a seed ConversationStateStructure. Tool results must
+ * never be replayed as assistant-authored prose: that teaches the model to
+ * counterfeit `Tool result (...)` text instead of emitting a real tool call.
+ * Normal rebases omit old results; compaction can retain all results and
+ * interrupted continuations retain only the trailing live result suffix as
+ * explicit OpenCode-host observations.
  */
-export function extractPromptHistory(prompt) {
+export function extractPromptHistory(prompt, options) {
     const out = [];
-    for (const m of prompt) {
+    const toolResults = options?.toolResults ?? "omit";
+    let trailingToolStart = prompt.length;
+    if (toolResults === "trailing") {
+        while (trailingToolStart > 0 && prompt[trailingToolStart - 1]?.role === "tool") {
+            trailingToolStart--;
+        }
+    }
+    for (let messageIndex = 0; messageIndex < prompt.length; messageIndex++) {
+        const m = prompt[messageIndex];
         if (m.role === "system") {
             if (typeof m.content === "string" && m.content.length > 0) {
                 out.push({ role: "system", content: m.content });
@@ -1062,25 +1577,43 @@ export function extractPromptHistory(prompt) {
             continue;
         }
         if (m.role === "tool" && Array.isArray(m.content)) {
+            if (toolResults === "omit" ||
+                (toolResults === "trailing" && messageIndex < trailingToolStart))
+                continue;
             const results = [];
             for (const part of m.content) {
                 const p = part;
                 if (p.type !== "tool-result")
                     continue;
                 const toolName = typeof p.toolName === "string" && p.toolName ? p.toolName : "tool";
+                const toolCallId = typeof p.toolCallId === "string" ? p.toolCallId : "";
                 const result = toolResultOutputToText(p.output);
-                const label = result.isError ? "Tool error" : "Tool result";
-                results.push(`${label} (${toolName}):\n${result.text}`);
+                results.push(formatSeedToolObservation({
+                    toolName,
+                    toolCallId,
+                    output: result.text,
+                    isError: result.isError,
+                }));
             }
             if (results.length > 0)
-                appendSeedHistory(out, "assistant", results.join("\n\n"));
+                appendSeedHistory(out, "user", results.join("\n\n"));
         }
     }
     // Live user message is the Run action, not seed history.
-    if (out.length > 0 && out[out.length - 1].role === "user")
+    if (!options?.preserveTrailingUser && out.length > 0 && out[out.length - 1].role === "user") {
         out.pop();
+    }
     return out;
 }
+function formatSeedToolObservation(input) {
+    const metadata = JSON.stringify({
+        source: "opencode-tool",
+        tool: input.toolName,
+        callId: input.toolCallId,
+        status: input.isError ? "error" : "completed",
+    });
+    return `OpenCode host observation ${metadata}:\n${input.output}`;
+}
 function extractAssistantHistoryText(msg) {
     const content = msg.content;
     if (typeof content === "string")