cursor-opencode-provider 0.4.2 → 0.5.0

package/dist/language-model.js

@@ -5,19 +5,22 @@ import { bidiRunStream, CursorRunInterruptedError, normalizeAgentRunOrigin, } fr
 import { trace, traceRequestContextPaths } from "./debug.js";
 import { buildRunRequest, buildHeartbeat } from "./protocol/request.js";
 import { decodeFramePayload } from "./protocol/framing.js";
-import { debugWalkTurnEnded, decodeMessage } from "./protocol/messages.js";
-import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } from "./protocol/tools.js";
+import { debugWalkTurnEnded, decodeMessage, encodeMessage } from "./protocol/messages.js";
+import { parseExecServerMessage, buildToolCallPart, buildExecClientMessages, buildReadRejectionMessages, classifyMissingReadTarget, isUriReadTarget, resolveReadTargetPath, parseExecIdFromToolCallId, detectExecVariantField, buildRequestContextResult, buildMcpStateResult, buildListMcpResourcesFallback, buildReadMcpResourceFallback, buildCustomWebToolAliases, extractHostSubagentCatalog, resolveCustomWebToolAlias, remapNativeSubagentForCatalog, remapCorrelatedEditWriteForCatalog, remapEditToolsForCatalog, buildCompleteEditReadMessages, rejectPartialReadMutation, CUSTOM_WEBFETCH_TOOL, CUSTOM_WEBSEARCH_TOOL, CUSTOM_LIST_MCP_RESOURCES_TOOL, CUSTOM_READ_MCP_RESOURCE_TOOL, } 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 } 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 { clearCheckpoint, getCheckpoint, setCheckpoint } from "./protocol/checkpoint.js";
+import { cursorContextUsageMetadata, decodeConversationTokenDetails, } from "./protocol/token-details.js";
+import { clearConversationBlobs, conversationBlobCount, inspectConversationBlobGraph, } from "./protocol/blob-store.js";
+import { bindConversationId, resolveConversationGroupId, } from "./protocol/conversation-bind.js";
+import { clearPersistedConversationState, hydrateConversationState, persistConversationState, } from "./protocol/conversation-state.js";
+import { initializeConversationPersistence } from "./protocol/conversation-persistence.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 { getOrBuildRequestContext } from "./context/frozen.js";
 import { workspaceRootFromRequestContext } from "./context/env.js";
 import { opencodeGlobalCacheDir, setHostCacheDirOverride } from "./context/paths.js";
 import { resolveAgentUrl } from "./agent-url.js";
@@ -29,7 +32,7 @@ import { resolveCursorModelSupportsImages } from "./model-metadata.js";
 import { consumeCursorShellResult, registerCursorShellCall, } from "./shell-timeout.js";
 import { analyzeReplayFrame, AttemptReplaySafety } from "./replay-safety.js";
 import { readAllFieldsStrict } from "./protocol/struct.js";
-import { buildLanguageModelV3UsageFromEstimate, buildLanguageModelV3UsageFromTurnEnded, turnEndedCounter, } from "./usage.js";
+import { buildLanguageModelV3UsageFromCounters, cursorUsageCountersFromTurnEnded, emptyLanguageModelV3Usage, formatCursorCacheDiagnostics, formatCursorTokenCategories, formatTurnUsageValidation, turnEndedCounter, } from "./usage.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.
@@ -56,6 +59,11 @@ const MAX_RETRY_DELAY_MS = 30_000;
 const RUN_REQUEST_DECODE_FAILED = "CURSOR_RUN_REQUEST_DECODE_FAILED";
 const RUN_REQUEST_UNSUPPORTED = "CURSOR_RUN_REQUEST_UNSUPPORTED";
 const RUN_REPLY_FAILED = "CURSOR_RUN_REPLY_FAILED";
+/** Cursor's own conversation export path treats state above 100 MiB as large. */
+export const MAX_CHECKPOINT_BLOB_GRAPH_BYTES = 100 * 1024 * 1024;
+export function checkpointBlobGraphRequiresRebase(stats, maxBytes = MAX_CHECKPOINT_BLOB_GRAPH_BYTES) {
+    return !stats.complete || stats.bytes > maxBytes;
+}
 const RESPONSE_REQUIRED_CHANNEL_BY_FIELD = new Map([
     [2, "exec"],
     [4, "kv"],
@@ -237,7 +245,7 @@ export function connectFrameError(payload) {
 }
 function rememberToolCatalog(sessionKey, tools) {
     toolCatalogBySession.delete(sessionKey);
-    toolCatalogBySession.set(sessionKey, tools);
+    toolCatalogBySession.set(sessionKey, structuredClone(tools));
     while (toolCatalogBySession.size > MAX_TURN_STATE_SESSIONS) {
         const oldest = toolCatalogBySession.keys().next().value;
         if (!oldest)
@@ -245,6 +253,17 @@ function rememberToolCatalog(sessionKey, tools) {
         toolCatalogBySession.delete(oldest);
     }
 }
+/** Restore the last real catalog solely for lifecycle turns such as compaction. */
+export function restoreTurnToolCatalog(sessionKey, tools) {
+    if (!sessionKey || tools.length === 0)
+        return;
+    rememberToolCatalog(sessionKey, tools);
+}
+function snapshotToolCatalog(sessionKey) {
+    if (!sessionKey)
+        return [];
+    return structuredClone(toolCatalogBySession.get(sessionKey) ?? []);
+}
 function rememberPostCompactionRebase(sessionKey) {
     postCompactionRebaseBySession.delete(sessionKey);
     postCompactionRebaseBySession.add(sessionKey);
@@ -292,6 +311,11 @@ export function createCursorLanguageModel(modelId, providerId, options) {
     // Host Path.cache / explicit override wins over XDG heuristics for this process.
     if (options.cacheDir)
         setHostCacheDirOverride(options.cacheDir);
+    // Start loading and pruning restart state as soon as the provider is built.
+    // startSession awaits this same per-cache-root initialization before binding.
+    void initializeConversationPersistence(opencodeGlobalCacheDir()).catch((error) => {
+        trace(`conversation persistence: startup load failed: ${String(error)}`);
+    });
     return {
         specificationVersion: "v3",
         provider: providerId,
@@ -327,7 +351,6 @@ 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
@@ -389,7 +412,6 @@ async function doStreamImpl(modelId, options, callOptions) {
                         initialSession: activeSession,
                         controller,
                         abortSignal: callOptions.abortSignal,
-                        promptTokens,
                         retryPolicy,
                         recover: (recovery) => openSession({ recovery }),
                         onSession: (next) => { activeSession = next; },
@@ -429,7 +451,6 @@ export async function pumpWithRecovery(input) {
         maxAttempts: (input.maxRecoveries ?? 1) + 1,
     };
     const maxRecoveries = retryPolicy.maxAttempts - 1;
-    const requestUsage = { outputChars: 0 };
     input.onSession?.(session);
     for (let attempt = 0;; attempt++) {
         const pumpedSession = session;
@@ -439,8 +460,6 @@ export async function pumpWithRecovery(input) {
             await pump(pumpedSession, input.controller, {
                 textId: crypto.randomUUID(),
                 reasoningId: crypto.randomUUID(),
-                promptTokens: input.promptTokens ?? 0,
-                requestUsage,
             }, input.abortSignal);
             return session;
         }
@@ -473,7 +492,6 @@ export async function pumpWithRecovery(input) {
                 : { kind: "rebase" };
             session = await input.recover(recovery);
             if (recovery.kind === "resume") {
-                session.hadToolCallBoundary = pumpedSession.hadToolCallBoundary;
                 session.usageEstimate = { ...pumpedSession.usageEstimate };
                 session.editToolCalls = new Map(pumpedSession.editToolCalls);
             }
@@ -489,6 +507,17 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const prompt = callOptions.prompt;
     const incomingTools = extractTools(callOptions);
     const sessionKey = opencodeSessionKey(callOptions);
+    const cacheDir = opencodeGlobalCacheDir();
+    if (sessionKey) {
+        const restored = await hydrateConversationState(cacheDir, sessionKey).catch((error) => {
+            trace(`conversation persistence: restore failed sessionKey=${sessionKey}: ${String(error)}`);
+            return undefined;
+        });
+        if (restored?.postCompactionRebase)
+            rememberPostCompactionRebase(sessionKey);
+        if (restored?.toolCatalog.length)
+            restoreTurnToolCatalog(sessionKey, restored.toolCatalog);
+    }
     const providerOptions = callOptions.providerOptions?.cursor;
     // The classic plugin marks OpenCode's agent="compaction" through chat.params.
     // OpenCode 2.0 removed that hook, so its plugin records the same fact against
@@ -513,17 +542,55 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const allowTools = toolState.allowTools;
     const discoveredSubagentCatalog = extractHostSubagentCatalog(cursorTools);
     const resetState = resolveTurnConversationReset({ sessionKey, isCompaction });
-    const recovery = startOptions?.recovery;
-    const resuming = recovery?.kind === "resume";
+    let recovery = startOptions?.recovery;
+    let resumeRecovery = recovery?.kind === "resume" ? recovery : undefined;
+    let resuming = !!resumeRecovery;
     // 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 = resuming
-        ? { conversationId: recovery.conversationId, reset: false, previousId: undefined }
+    let bound = resuming
+        ? { conversationId: resumeRecovery.conversationId, reset: false, previousId: undefined }
         : bindConversationId(sessionKey, { reset: resetState.reset || recovery?.kind === "rebase" });
+    let conversationState = resuming
+        ? resumeRecovery.checkpoint
+        : (bound.reset ? undefined : getCheckpoint(bound.conversationId));
+    let checkpointGraph = conversationState
+        ? inspectConversationBlobGraph(bound.conversationId, conversationState)
+        : { count: 0, bytes: 0, complete: true };
+    let forcedResetReason;
+    if (conversationState && checkpointBlobGraphRequiresRebase(checkpointGraph)) {
+        const previousConversationId = bound.conversationId;
+        forcedResetReason = checkpointGraph.complete
+            ? "oversized-checkpoint-graph"
+            : "incomplete-checkpoint-graph";
+        trace(`checkpoint state rejected: reason=${forcedResetReason} ` +
+            `conversationId=${previousConversationId} checkpointBytes=${conversationState.length} ` +
+            `blobCount=${checkpointGraph.count} blobBytes=${checkpointGraph.bytes} ` +
+            `limitBytes=${MAX_CHECKPOINT_BLOB_GRAPH_BYTES} ` +
+            `detail=${checkpointGraph.fallbackReason ?? "-"} action=rebase`);
+        // A recovery resume must become a history rebase so the interrupted user
+        // request remains in the seed. An ordinary turn keeps its normal user text.
+        if (recovery?.kind === "resume")
+            recovery = { kind: "rebase" };
+        resumeRecovery = undefined;
+        resuming = false;
+        if (!sessionKey) {
+            clearCheckpoint(previousConversationId);
+            clearConversationBlobs(previousConversationId);
+        }
+        bound = bindConversationId(sessionKey, { reset: true });
+        conversationState = undefined;
+        checkpointGraph = { count: 0, bytes: 0, complete: true };
+    }
     const conversationId = bound.conversationId;
+    const conversationGroupId = resolveConversationGroupId(sessionKey, conversationId);
     if (bound.reset) {
-        trace(`conversation reset: reason=${recovery?.kind === "rebase" ? "interrupted-run" : (resetState.reason ?? "unknown")} ` +
+        if (sessionKey) {
+            await clearPersistedConversationState(cacheDir, sessionKey, bound.previousId).catch((error) => {
+                trace(`conversation persistence: reset cleanup failed sessionKey=${sessionKey}: ${String(error)}`);
+            });
+        }
+        trace(`conversation reset: reason=${forcedResetReason ?? (recovery?.kind === "rebase" ? "interrupted-run" : (resetState.reason ?? "unknown"))} ` +
             `sessionKey=${sessionKey ?? "(none)"} ` +
             `previousId=${bound.previousId ?? "-"} → conversationId=${conversationId}`);
     }
@@ -604,7 +671,9 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         baseURL: agentBaseUrl,
         headers: options.headers,
     });
-    const requestContext = await buildRequestContext({ workspaceRoot, tools: cursorTools });
+    // Freeze RequestContext per conversation_id (CLI parity). Rebuilding every
+    // Run mutates volatile slices (git porcelain, layout) and breaks prompt cache.
+    const { context: requestContext, reused: requestContextReused } = await getOrBuildRequestContext(conversationId, { workspaceRoot, tools: cursorTools });
     const contextSubagents = Array.isArray(requestContext.custom_subagents)
         ? requestContext.custom_subagents
             .map((agent) => agent && typeof agent === "object" && typeof agent.name === "string"
@@ -628,15 +697,14 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? requestContext.tools
         : [];
     // CLI parity: echo the last conversation_checkpoint_update as conversation_state.
-    // After compaction reset there is no checkpoint — seed from OpenCode history.
-    const conversationState = resuming
-        ? recovery.checkpoint
-        : (bound.reset ? undefined : getCheckpoint(conversationId));
+    // After compaction or an unsafe checkpoint reset there is no checkpoint —
+    // seed a new Cursor conversation from OpenCode's authoritative history.
     const reqBytes = buildRunRequest({
         text: userText,
         images,
         modelId: cursorModelId,
         conversationId,
+        conversationGroupId,
         systemPrompt: conversationState ? undefined : systemPrompt,
         history: conversationState ? undefined : history,
         conversationState,
@@ -657,14 +725,31 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         ? requestContext.hooks_additional_context
         : "";
     const historyChars = history.reduce((n, m) => n + m.content.length, 0);
+    const seedChars = conversationState
+        ? 0
+        : (systemPrompt?.length ?? 0) + userText.length + historyChars;
+    const seedEstimateIn = estimateTokens(seedChars);
+    const checkpointEnvelopeEstimateIn = conversationState
+        ? estimateTokens(userText.length + conversationState.length)
+        : 0;
+    const runRequestWireEstimateIn = estimateTokens(reqBytes.length);
+    const encodedRequestContext = encodeMessage("RequestContext", requestContext);
+    const priorTokenDetails = decodeConversationTokenDetails(conversationState);
+    const requestContextHash = sha(encodedRequestContext);
+    const systemPromptHash = systemPrompt ? sha(systemPrompt) : undefined;
     const usageEstimate = {
-        inputTokens: estimateTokens((systemPrompt?.length ?? 0) + userText.length + historyChars + (conversationState?.length ?? 0)),
+        // This is used only before Cursor supplies authoritative TurnEnded usage.
+        // Estimate the actual protobuf request, not history/system text omitted by
+        // checkpoint Runs. The opaque remote interpretation of KV blobs is logged
+        // separately and deliberately is not mislabeled as a token count.
+        inputTokens: runRequestWireEstimateIn,
         outputTokens: 0,
         cacheRead: 0,
         cacheWrite: 0,
         reasoningTokens: 0,
     };
-    trace(`outbound Run: model=${cursorModelId} opencodeModel=${modelId} conversationId=${conversationId} ` +
+    trace(`outbound Run: model=${cursorModelId} opencodeModel=${modelId} ` +
+        `conversationId=${conversationId} conversationGroupId=${conversationGroupId} ` +
         `params=${JSON.stringify(parameterValues ?? [])} ` +
         `maxMode=${maxMode} systemPromptLen=${systemPrompt?.length ?? 0} ` +
         `tools=${tools.length} incomingTools=${incomingTools.length} compaction=${isCompaction} ` +
@@ -672,14 +757,20 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         `availableModels=${_availableModels?.length ?? 0} userTextLen=${userText.length} ` +
         `images=${images.length} imageBytes=${images.reduce((total, image) => total + image.data.length, 0)} ` +
         `historyMsgs=${history.length} historyChars=${historyChars} ` +
-        `checkpointLen=${conversationState?.length ?? 0} reset=${bound.reset} ` +
-        `resume=${resuming} ` +
-        `usageEstimateIn=${usageEstimate.inputTokens} runRequestBytes=${reqBytes.length}`);
+        `checkpointLen=${conversationState?.length ?? 0} checkpointBlobCount=${checkpointGraph.count} ` +
+        `checkpointBlobBytes=${checkpointGraph.bytes} checkpointGraphComplete=${checkpointGraph.complete} ` +
+        `seedChars=${seedChars} seedEstimateIn=${seedEstimateIn} ` +
+        `checkpointEnvelopeEstimateIn=${checkpointEnvelopeEstimateIn} ` +
+        `reset=${bound.reset} ` +
+        `resume=${resuming} requestContextReused=${requestContextReused} ` +
+        `usageEstimateMode=run-request-wire usageEstimateIn=${usageEstimate.inputTokens} ` +
+        `runRequestBytes=${reqBytes.length} requestContextBytes=${encodedRequestContext.length}`);
     if (hooksCtx)
         trace(`outbound Run hooks_additional_context: ${hooksCtx}`);
     trace(`hash run_request sha256=${sha(reqBytes)}`);
     if (systemPrompt)
         trace(`hash systemPrompt sha256=${sha(systemPrompt)}`);
+    trace(`hash requestContext sha256=${requestContextHash}`);
     if (conversationState)
         trace(`hash checkpoint sha256=${sha(conversationState)}`);
     try {
@@ -693,8 +784,31 @@ async function startSession(modelId, token, callOptions, options, startOptions)
     const session = {
         sessionId: crypto.randomUUID(),
         conversationId,
+        cacheDir,
         resumeCheckpoint: undefined,
+        tokenDetails: priorTokenDetails,
+        tokenDetailsFresh: false,
+        cacheDiagnostics: {
+            sessionKey,
+            conversationId,
+            conversationGroupId,
+            modelId: cursorModelId,
+            priorTokenDetails,
+            startedWithCheckpoint: !!conversationState,
+            requestContextReused,
+            requestContextHash,
+            systemPromptHash,
+            checkpointUpdates: 0,
+            tokenDetailUpdates: 0,
+            pumpPasses: 0,
+            stepStarts: 0,
+            stepCompletes: 0,
+            displayToolCalls: 0,
+            execRequests: 0,
+        },
         openCodeSessionId: sessionKey,
+        postCompactionRebase: isCompaction,
+        toolCatalog: snapshotToolCatalog(sessionKey),
         stream,
         frames: stream.frames()[Symbol.asyncIterator](),
         pending: new Map(),
@@ -730,11 +844,10 @@ async function startSession(modelId, token, callOptions, options, startOptions)
         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",
-            }));
+            // The pending write has its own bounded drain wait and will close the
+            // session with the actual failing operation. Do not race it with another
+            // heartbeat or misattribute an existing KV backlog to the heartbeat.
+            trace(`heartbeat skipped: prior heartbeat write is still pending sessionId=${session.sessionId}`);
             return;
         }
         heartbeatWritePending = true;
@@ -805,16 +918,39 @@ export function deliverContinuationResults(session, trailingToolResults) {
                     || pending.resultField === "background_shell_spawn_result"
                     ? 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,
-                    workspaceRoot: workspaceRootFromRequestContext(session.requestContext),
-                });
+                const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
+                const correlatedEditCallId = pending.resultMetadata?.correlatedEditCallId;
+                const requestedPath = pending.resultMetadata?.path;
+                const correlatedEdit = !r.error
+                    && pending.resultField === "read_result"
+                    && pending.toolName === "read"
+                    && typeof correlatedEditCallId === "string"
+                    && typeof requestedPath === "string"
+                    ? session.editToolCalls?.get(correlatedEditCallId)
+                    : undefined;
+                if (correlatedEdit) {
+                    const absolutePath = path.resolve(workspaceRoot, requestedPath);
+                    if (absolutePath === path.resolve(workspaceRoot, correlatedEdit.path)) {
+                        frames = buildCompleteEditReadMessages(r.execId, absolutePath, requestedPath) ?? [];
+                        if (frames.length > 0) {
+                            correlatedEdit.completeRead = true;
+                            trace(`continuation: upgraded authorized correlated edit read execId=${r.execId} ` +
+                                `path=${JSON.stringify(requestedPath)}`);
+                        }
+                    }
+                }
+                if (frames.length === 0) {
+                    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,
+                        workspaceRoot,
+                    });
+                }
             }
             catch (error) {
                 trace(`continuation: result encode FAILED execId=${r.execId} err=${error.message}`);
@@ -879,7 +1015,27 @@ function resolveExplicitAgentBaseURL(options) {
 function isTruthyEnv(value) {
     return value === "1" || value === "true";
 }
+const streamWriteChains = new WeakMap();
+/**
+ * Keep awaited protocol writes ordered per Run stream. In particular, a large
+ * KV get_blob reply must drain before another KV reply or heartbeat is queued;
+ * otherwise one heartbeat observes the backlog created by dozens of ignored
+ * false write() results and reports the wrong operation as the failure.
+ */
 async function writeWithBackpressure(stream, message, operation) {
+    const previous = streamWriteChains.get(stream);
+    const current = (previous ? previous.catch(() => undefined) : Promise.resolve())
+        .then(() => writeWithBackpressureNow(stream, message, operation));
+    streamWriteChains.set(stream, current);
+    try {
+        await current;
+    }
+    finally {
+        if (streamWriteChains.get(stream) === current)
+            streamWriteChains.delete(stream);
+    }
+}
+async function writeWithBackpressureNow(stream, message, operation) {
     let accepted;
     try {
         accepted = stream.write(message);
@@ -892,6 +1048,7 @@ async function writeWithBackpressure(stream, message, operation) {
     }
     if (accepted !== false)
         return;
+    trace(`stream write backpressured: operation=${operation} bytes=${message.length}`);
     if (!stream.waitForDrain) {
         throw new CursorTransportError(`Cursor ${operation} write was backpressured`, {
             transient: false,
@@ -901,6 +1058,7 @@ async function writeWithBackpressure(stream, message, operation) {
     }
     try {
         await stream.waitForDrain(5_000);
+        trace(`stream write drained: operation=${operation} bytes=${message.length}`);
     }
     catch (cause) {
         throw toCursorProviderError(cause, {
@@ -947,13 +1105,27 @@ async function nextFrameWithSemanticDeadline(session) {
  */
 export async function pump(session, controller, ids, abortSignal) {
     sessionManager.registerSession(session);
+    const cacheDiagnostics = session.cacheDiagnostics ??= {
+        sessionKey: session.openCodeSessionId,
+        conversationId: session.conversationId,
+        priorTokenDetails: session.tokenDetails,
+        startedWithCheckpoint: !!session.tokenDetails,
+        requestContextReused: false,
+        requestContextHash: "unavailable",
+        checkpointUpdates: 0,
+        tokenDetailUpdates: 0,
+        pumpPasses: 0,
+        stepStarts: 0,
+        stepCompletes: 0,
+        displayToolCalls: 0,
+        execRequests: 0,
+    };
+    cacheDiagnostics.pumpPasses++;
     const { textId, reasoningId } = ids;
-    const promptTokens = ids.promptTokens ?? 0;
     const advertisedToolNames = advertisedToolNamesFromDescriptors(session.toolDescriptors);
     const advertisedToolNameSet = new Set(advertisedToolNames.map((name) => resolveCustomWebToolAlias(name, session.toolAliases)));
     let textStarted = false;
     let reasoningStarted = false;
-    const requestUsage = ids.requestUsage ?? { outputChars: 0 };
     const replaySafety = new AttemptReplaySafety(session.sessionId);
     const failRunProtocol = (message, code) => {
         replaySafety.markBarrier("unknown-or-malformed-frame");
@@ -961,6 +1133,10 @@ export async function pump(session, controller, ids, abortSignal) {
         sessionManager.close(session, "remote-error", error);
         throw error;
     };
+    const rethrowTransportWriteFailure = (error) => {
+        if (error instanceof CursorProviderError && error.origin !== "protocol")
+            throw error;
+    };
     // 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.
@@ -1016,13 +1192,17 @@ export async function pump(session, controller, ids, abortSignal) {
         }
     };
     /**
-     * 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.
+     * Cursor's streamed edit handshake needs the complete target before it sends
+     * the replacement through write_args. OpenCode's ordinary read tool caps at
+     * 50 KB, so forwarding this private prerequisite read teaches Cursor's editor
+     * that a large file ends at the cap and produces a destructive replacement.
+     *
+     * Answer a correlated workspace-file read directly up to Cursor's own 50 MB
+     * edit limit. Missing targets remain empty-file successes so creation can
+     * continue. External and otherwise ineligible reads retain OpenCode's normal
+     * permission-aware path.
      */
-    const recoverMissingEditRead = (parsed, displayCallId) => {
+    const recoverCorrelatedEditRead = (parsed, displayCallId) => {
         if (!displayCallId ||
             parsed.resultField !== "read_result" ||
             parsed.toolName !== "read" ||
@@ -1043,8 +1223,54 @@ export async function pump(session, controller, ids, abortSignal) {
         const workspaceRoot = workspaceRootFromRequestContext(session.requestContext);
         const resolvePath = (value) => path.resolve(workspaceRoot, value);
         const absolutePath = resolvePath(requestedPath);
-        if (absolutePath !== resolvePath(editPath) || fs.existsSync(absolutePath))
+        if (absolutePath !== resolvePath(editPath))
             return false;
+        let exists = true;
+        try {
+            fs.lstatSync(absolutePath);
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            if (code !== "ENOENT")
+                return false;
+            exists = false;
+        }
+        if (exists) {
+            // Do not bypass OpenCode's external-directory permission boundary, even
+            // through a symlink rooted in the workspace.
+            try {
+                const realRoot = fs.realpathSync(workspaceRoot);
+                const realTarget = fs.realpathSync(absolutePath);
+                const relative = path.relative(realRoot, realTarget);
+                if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                    parsed.resultMetadata = {
+                        ...parsed.resultMetadata,
+                        correlatedEditCallId: displayCallId,
+                    };
+                    return false;
+                }
+                const frames = buildCompleteEditReadMessages(parsed.id, absolutePath, requestedPath);
+                if (!frames)
+                    return false;
+                for (const frame of frames)
+                    session.stream.write(frame);
+                const editCall = session.editToolCalls?.get(displayCallId);
+                if (editCall)
+                    editCall.completeRead = true;
+                trace(`exec: correlated edit read completed directly id=${parsed.id} ` +
+                    `path=${JSON.stringify(requestedPath)}; awaiting write_args`);
+                return true;
+            }
+            catch {
+                parsed.resultMetadata = {
+                    ...parsed.resultMetadata,
+                    correlatedEditCallId: displayCallId,
+                };
+                return false;
+            }
+        }
         try {
             for (const frame of buildExecClientMessages({
                 execId: parsed.id,
@@ -1061,7 +1287,7 @@ export async function pump(session, controller, ids, abortSignal) {
             return true;
         }
         catch (e) {
-            const error = new Error(`Failed to recover Cursor edit read for a new file: ${e.message}`);
+            const error = new Error(`Failed to recover Cursor edit read: ${e.message}`);
             trace(`exec: edit read recovery FAILED ${error.message}`);
             safeError(error);
             sessionManager.close(session);
@@ -1079,7 +1305,7 @@ export async function pump(session, controller, ids, abortSignal) {
      *
      * Read-only by construction — write/edit targets are never checked, so
      * legitimate file creation (path resolves, file absent) is never denied. Runs
-     * after recoverMissingEditRead, which has already converted the new-file edit
+     * after recoverCorrelatedEditRead, which has already converted the edit
      * handshake read into an empty-file success. EACCES/EPERM and other stat
      * errors fall through to OpenCode so a genuine permission decision stands.
      */
@@ -1141,9 +1367,7 @@ export async function pump(session, controller, ids, abortSignal) {
             textStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        if (safeEnqueue({ type: "text-delta", id: textId, delta: text })) {
-            requestUsage.outputChars += text.length;
-        }
+        safeEnqueue({ type: "text-delta", id: textId, delta: text });
     };
     const emitReasoning = (text) => {
         if (!text)
@@ -1154,33 +1378,32 @@ export async function pump(session, controller, ids, abortSignal) {
             reasoningStarted = true;
         }
         session.usageEstimate.outputTokens += estimateTokens(text.length);
-        if (safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text })) {
-            requestUsage.outputChars += text.length;
-        }
+        safeEnqueue({ type: "reasoning-delta", id: reasoningId, delta: text });
     };
-    const emitFinish = (te, reason) => {
+    const emitFinish = (te, reason, settledUsage, settledSource) => {
         closeOpenSpans();
-        // TurnEnded is request-local only when this Run did not previously stop at
-        // a tool boundary. On a held multi-step Run Cursor aggregates every model
-        // invocation into these counters; treating that billed total as the final
-        // request's prompt size makes OpenCode compact after ordinary tasks.
-        const cumulativeTurnEnded = !!te && session.hadToolCallBoundary === true;
-        if (te && !cumulativeTurnEnded) {
-            session.usageEstimate = {
-                inputTokens: turnEndedCounter(te, "input_tokens"),
-                outputTokens: turnEndedCounter(te, "output_tokens"),
-                cacheRead: turnEndedCounter(te, "cache_read"),
-                cacheWrite: turnEndedCounter(te, "cache_write"),
-                reasoningTokens: turnEndedCounter(te, "reasoning_tokens"),
-            };
-        }
         const est = session.usageEstimate;
-        const usage = te && !cumulativeTurnEnded
-            ? buildLanguageModelV3UsageFromTurnEnded(te)
-            : buildLanguageModelV3UsageFromEstimate(est, promptTokens, requestUsage.outputChars, estimateTokens);
-        if (!te)
-            session.hadToolCallBoundary = true;
-        const providerMetadata = te ? cursorTurnEndedProviderMetadata(te) : undefined;
+        // OpenCode persists and sums every AI SDK finish. Cursor does not expose a
+        // final context total at tool boundaries, so charging the growing estimate
+        // there multiplies one held Run across all of its steps. Emit zero at
+        // intermediate boundaries, then prefer checkpoint tokenDetails exactly once
+        // when TurnEnded closes the held Run. Cursor CLI keeps context occupancy in
+        // agentStore tokenDetails; it does not reinterpret TurnEnded as occupancy.
+        const tokenDetails = te ? session.tokenDetails : undefined;
+        const contextSource = tokenDetails
+            ? session.tokenDetailsFresh
+                ? "checkpoint-current-run"
+                : "checkpoint-previous-turn"
+            : undefined;
+        const counters = te ? cursorUsageCountersFromTurnEnded(te) : undefined;
+        const usage = settledUsage ?? (te
+            ? tokenDetails
+                ? buildLanguageModelV3UsageFromCounters(counters, { contextTotalTokens: tokenDetails.usedTokens })
+                : emptyLanguageModelV3Usage()
+            : emptyLanguageModelV3Usage());
+        const providerMetadata = te
+            ? cursorTurnEndedProviderMetadata(te, tokenDetails, contextSource)
+            : undefined;
         const reasonLabel = typeof reason === "object" && reason && "unified" in reason
             ? String(reason.unified ?? "unknown")
             : String(reason);
@@ -1194,7 +1417,13 @@ export async function pump(session, controller, ids, abortSignal) {
             `rawOut=${te ? turnEndedCounter(te, "output_tokens") : est.outputTokens} ` +
             `rawCacheRead=${te ? turnEndedCounter(te, "cache_read") : est.cacheRead} ` +
             `rawCacheWrite=${te ? turnEndedCounter(te, "cache_write") : est.cacheWrite} ` +
-            `source=${te ? (cumulativeTurnEnded ? "estimate-cumulative-turn-ended" : "turn_ended") : "estimate"}`);
+            `source=${te
+                ? settledSource ?? (contextSource ?? "unavailable")
+                : "intermediate-zero"}`);
+        if (counters) {
+            trace(formatTurnUsageValidation(counters, usage, tokenDetails, contextSource));
+            trace(formatCursorCacheDiagnostics(counters, tokenDetails, cacheDiagnostics.priorTokenDetails, cacheDiagnostics));
+        }
         safeEnqueue({
             type: "finish",
             usage,
@@ -1325,9 +1554,20 @@ export async function pump(session, controller, ids, abortSignal) {
             if (checkpointRaw != null) {
                 const bytes = normalizeCheckpointBytes(checkpointRaw);
                 if (bytes && bytes.length > 0) {
+                    cacheDiagnostics.checkpointUpdates++;
                     setCheckpoint(session.conversationId, bytes);
                     session.resumeCheckpoint = Uint8Array.from(bytes);
-                    trace(`checkpoint: stored ${bytes.length}B for conversationId=${session.conversationId}`);
+                    const tokenDetails = decodeConversationTokenDetails(bytes);
+                    if (tokenDetails) {
+                        cacheDiagnostics.tokenDetailUpdates++;
+                        session.tokenDetails = tokenDetails;
+                        session.tokenDetailsFresh = true;
+                    }
+                    const context = tokenDetails
+                        ? ` context=${tokenDetails.usedTokens}/${tokenDetails.maxTokens} ` +
+                            `categories=${formatCursorTokenCategories(tokenDetails)}`
+                        : " context=unavailable";
+                    trace(`checkpoint: stored ${bytes.length}B for conversationId=${session.conversationId}${context}`);
                 }
             }
             if (iu?.text_delta) {
@@ -1338,11 +1578,25 @@ export async function pump(session, controller, ids, abortSignal) {
             }
             else if (iu?.turn_ended) {
                 trace(`turn_ended raw wire fields: ${debugWalkTurnEnded(payload)}`);
-                emitFinish(iu.turn_ended, { unified: "stop", raw: undefined });
+                const turnEnded = iu.turn_ended;
+                if (session.openCodeSessionId) {
+                    await persistConversationState(session.cacheDir ?? opencodeGlobalCacheDir(), {
+                        sessionKey: session.openCodeSessionId,
+                        conversationId: session.conversationId,
+                        requestContext: session.requestContext,
+                        toolCatalog: session.toolCatalog ?? [],
+                        postCompactionRebase: session.postCompactionRebase,
+                    }).catch((error) => {
+                        trace(`conversation persistence: TurnEnded save failed ` +
+                            `sessionKey=${session.openCodeSessionId}: ${String(error)}`);
+                    });
+                }
+                emitFinish(turnEnded, { unified: "stop", raw: undefined });
                 sessionManager.close(session);
                 return;
             }
             else if (iu?.tool_call_started) {
+                cacheDiagnostics.displayToolCalls++;
                 // Stash Cursor display ToolCall until exec claims it, or completed bridges it.
                 const started = iu.tool_call_started;
                 const callId = typeof started.call_id === "string" ? started.call_id : "";
@@ -1429,7 +1683,14 @@ export async function pump(session, controller, ids, abortSignal) {
                     }
                 }
             }
+            else if (iu?.step_started) {
+                cacheDiagnostics.stepStarts++;
+            }
+            else if (iu?.step_completed) {
+                cacheDiagnostics.stepCompletes++;
+            }
             else if (esm) {
+                cacheDiagnostics.execRequests++;
                 const esmId = esm.id ?? 0;
                 if (esm.request_context_args) {
                     // Server turn-setup probe (#10). Reply with full OpenCode-sourced context.
@@ -1445,10 +1706,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     }
                     try {
                         traceRequestContextPaths(`exec request_context reply id=${esmId}`, session.requestContext);
-                        session.stream.write(buildRequestContextResult(esmId, session.requestContext));
+                        await writeWithBackpressure(session.stream, buildRequestContextResult(esmId, session.requestContext), `request-context reply id=${esmId}`);
                         trace(`exec request_context: replied`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor request-context reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1461,10 +1723,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         ? stateArgs.server_identifiers.join(",")
                         : "";
                     try {
-                        session.stream.write(buildMcpStateResult(esmId, stateArgs, session.requestContext));
+                        await writeWithBackpressure(session.stream, buildMcpStateResult(esmId, stateArgs, session.requestContext), `MCP-state reply id=${esmId}`);
                         trace(`exec mcp_state: replied id=${esmId} requested=[${requested}]`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor MCP-state reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1475,10 +1738,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     const args = esm.list_mcp_resources_exec_args;
                     const server = typeof args.server === "string" ? args.server : "";
                     try {
-                        session.stream.write(buildListMcpResourcesFallback(esmId));
+                        await writeWithBackpressure(session.stream, buildListMcpResourcesFallback(esmId), `list-MCP-resources reply id=${esmId}`);
                         trace(`exec list_mcp_resources: replied id=${esmId} server=${server || "(all)"} success{resources:[]}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor list_mcp_resources reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1488,10 +1752,11 @@ export async function pump(session, controller, ids, abortSignal) {
                     const server = typeof args.server === "string" ? args.server : "";
                     const uri = typeof args.uri === "string" ? args.uri : "";
                     try {
-                        session.stream.write(buildReadMcpResourceFallback(esmId, server, uri));
+                        await writeWithBackpressure(session.stream, buildReadMcpResourceFallback(esmId, server, uri), `read-MCP-resource reply id=${esmId}`);
                         trace(`exec read_mcp_resource: replied id=${esmId} server=${server} uri=${uri} error{server not found}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor read_mcp_resource reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1509,6 +1774,11 @@ export async function pump(session, controller, ids, abortSignal) {
                         const editCall = displayCallId
                             ? session.editToolCalls?.get(displayCallId)
                             : undefined;
+                        // A complete correlated edit read is trusted provenance: unlike an
+                        // ordinary capped read it cannot have appended our warning marker,
+                        // and the source itself may legitimately contain the marker text.
+                        if (!editCall?.completeRead)
+                            rejectPartialReadMutation(parsed);
                         if (editCall) {
                             const remapped = remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNameSet, editCall.path, workspaceRootFromRequestContext(session.requestContext));
                             if (parsed.resultField === "write_result" && displayCallId) {
@@ -1560,7 +1830,7 @@ export async function pump(session, controller, ids, abortSignal) {
                                 return;
                             continue;
                         }
-                        if (recoverMissingEditRead(parsed, displayCallId))
+                        if (recoverCorrelatedEditRead(parsed, displayCallId))
                             continue;
                         if (rejectMissingReadTarget(parsed)) {
                             if (displayCallId)
@@ -1621,11 +1891,12 @@ export async function pump(session, controller, ids, abortSignal) {
                     if (handled.outcome === "acknowledged") {
                         replaySafety.markBarrier("stateful-interaction");
                     }
-                    session.stream.write(handled.reply);
+                    await writeWithBackpressure(session.stream, handled.reply, `interaction reply id=${handled.id}`);
                     trace(`interaction_query: replied id=${handled.id} variant=${handled.variantName} ` +
                         `field=${handled.variantField} outcome=${handled.outcome}`);
                 }
-                catch {
+                catch (error) {
+                    rethrowTransportWriteFailure(error);
                     failRunProtocol("Cursor interaction reply failed", RUN_REPLY_FAILED);
                 }
             }
@@ -1640,12 +1911,14 @@ export async function pump(session, controller, ids, abortSignal) {
                 const handled = handleKvServerMessage(kv, session);
                 if (handled) {
                     try {
-                        session.stream.write(handled.reply);
+                        await writeWithBackpressure(session.stream, handled.reply, `KV ${handled.kind}_blob reply id=${handled.id}`);
                         trace(`kv replied: kind=${handled.kind} id=${handled.id} blobId=${handled.blobIdHex.slice(0, 16)}… ` +
                             `found=${handled.found} echoed=${!!handled.echoed} ` +
+                            `replyBytes=${handled.reply.length} replyBlobBytes=${handled.replyBlobBytes} ` +
                             `sessionBlobs=${session.blobs.size} convBlobs=${conversationBlobCount(session.conversationId)}`);
                     }
-                    catch {
+                    catch (error) {
+                        rethrowTransportWriteFailure(error);
                         failRunProtocol("Cursor KV reply failed", RUN_REPLY_FAILED);
                     }
                 }
@@ -1655,7 +1928,7 @@ export async function pump(session, controller, ids, abortSignal) {
             }
         }
         catch (e) {
-            if (e instanceof CursorProtocolError)
+            if (e instanceof CursorProviderError)
                 throw e;
             if (requiredChannel) {
                 failRunProtocol(`Cursor ${requiredChannel} request could not be handled`, RUN_REQUEST_UNSUPPORTED);
@@ -1822,6 +2095,9 @@ export function buildOpenCodeInteractionGuidance(tools, isCompaction, workspaceR
         // leaving the turn with no file-editing guidance at all.
         instructions.push("- Use OpenCode `apply_patch` for file-content changes; do not use shell, Python, or heredocs to change file content while it is available. Cursor-native write and edit requests are accepted and converted to `apply_patch` automatically.");
     }
+    if (names.has("edit") || names.has("write") || names.has("apply_patch")) {
+        instructions.push("- Never use a read result as complete file content when it says the output is capped, partial, or requires another offset. Read the remaining ranges first, or make a targeted edit/patch from complete context; do not pass a partial read back as a whole-file replacement.");
+    }
     return [
         `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.`,
@@ -1841,25 +2117,19 @@ 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 exact Cursor counters as diagnostics when they are cumulative across a multi-step Run. */
-export function cursorTurnEndedProviderMetadata(te) {
+/** Preserve exact request-local Cursor counters as diagnostics. */
+export function cursorTurnEndedProviderMetadata(te, tokenDetails, contextSource) {
     return {
         cursor: {
-            usageVersion: 2,
+            usageVersion: 3,
             inputTokensRaw: turnEndedCounter(te, "input_tokens"),
             outputTokensRaw: turnEndedCounter(te, "output_tokens"),
             cacheReadRaw: turnEndedCounter(te, "cache_read"),
             cacheWriteRaw: turnEndedCounter(te, "cache_write"),
             reasoningTokensRaw: turnEndedCounter(te, "reasoning_tokens"),
+            ...(tokenDetails
+                ? { context: cursorContextUsageMetadata(tokenDetails, contextSource) }
+                : {}),
         },
     };
 }
@@ -2072,6 +2342,7 @@ function foldStreamParts(parts) {
     let reasoning = "";
     const content = [];
     let finishReason = { unified: "stop", raw: undefined };
+    let providerMetadata;
     let usage = {
         inputTokens: { total: undefined, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
         outputTokens: { total: undefined, text: undefined, reasoning: undefined },
@@ -2092,11 +2363,18 @@ function foldStreamParts(parts) {
         else if (part.type === "finish") {
             finishReason = part.finishReason;
             usage = part.usage;
+            providerMetadata = part.providerMetadata;
         }
     }
     if (reasoning)
         content.unshift({ type: "reasoning", text: reasoning });
     if (text)
         content.unshift({ type: "text", text });
-    return { content, finishReason, usage, warnings: [] };
+    return {
+        content,
+        finishReason,
+        usage,
+        warnings: [],
+        ...(providerMetadata ? { providerMetadata } : {}),
+    };
 }