cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/protocol/tools.d.ts

@@ -71,9 +71,9 @@ export type HostSubagentDefinition = {
     description?: string;
 };
 export type HostSubagentCatalog = {
-    executor?: "task" | "actor";
+    executor?: "task";
     agents: HostSubagentDefinition[];
-    /** True when the host tool supplied its complete, permission-filtered catalog. */
+    /** True when the OpenCode task tool supplied its complete, permission-filtered catalog. */
     complete: boolean;
 };
 /** Extract the current host's permission-filtered Task/Actor recipient catalog. */
@@ -89,6 +89,16 @@ export declare function resolveCursorSubagentType(subagentType: string, catalog?
 export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
 /** Resolve a native Cursor subagent request to this turn's executor and catalog. */
 export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
+/**
+ * Complete the private read inside Cursor's legacy edit transaction without
+ * routing it through OpenCode's user-facing `read` tool. The latter caps every
+ * result at 50 KB, while Cursor's editor needs the complete file to calculate
+ * the correlated whole-file `write_args` that follows.
+ *
+ * The caller is responsible for proving that `filePath` is the same regular
+ * file named by an active `edit_tool_call` and is contained by the workspace.
+ */
+export declare function buildCompleteEditReadMessages(execId: number, sourcePath: string, resultPath?: string): Uint8Array[] | undefined;
 /**
  * Preserve a legacy Cursor edit's intent when its internal executor follows
  * `edit_tool_call` with a whole-file `write_args` request.
@@ -125,6 +135,13 @@ export type ParsedExecRequest = {
     /** Original request values needed by typed Cursor result messages. */
     resultMetadata?: Record<string, unknown>;
 };
+/**
+ * A partial-read notice is for Cursor's model, never for a file. Refuse only
+ * whole-file mutation forms that echo it. A targeted edit or Update File patch
+ * cannot truncate an unseen tail, and may legitimately edit source that quotes
+ * this provider's warning text.
+ */
+export declare function rejectPartialReadMutation(parsed: ParsedExecRequest): void;
 export declare function parseExecServerMessage(msg: Record<string, unknown>): ParsedExecRequest | undefined;
 /**
  * Remap Cursor exec / MCP arg shapes onto OpenCode's Effect Schema keys.
@@ -134,7 +151,28 @@ export declare function parseExecServerMessage(msg: Record<string, unknown>): Pa
 export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<string, unknown>, execVariant?: string): {
     toolName: string;
     args: Record<string, unknown>;
+    binaryBytes?: Uint8Array;
 };
+/**
+ * Decode `WriteArgs.file_bytes`. `encoding_hint` names the file's original
+ * encoding; OpenCode's `write` takes a string, so an unknown encoding label
+ * falls back to UTF-8 rather than dropping the write.
+ *
+ * Returns undefined when the bytes are not text in that encoding. A non-fatal
+ * decode would replace every undecodable sequence with U+FFFD and hand the host
+ * a corrupted file that still reports success, so binary content must take the
+ * byte-preserving path instead (see `isBinaryWriteRequest`).
+ */
+export declare function decodeWriteBytes(bytes: Uint8Array, encodingHint?: string): string | undefined;
+/**
+ * True when a parsed `write` request carries bytes that are not text. Such a
+ * request cannot go to OpenCode's `write` tool at all — it takes a string, and
+ * additionally BOM-splits, diffs, and runs `Format.file()` on what it writes.
+ */
+export declare function binaryWritePayload(parsed: ParsedExecRequest): {
+    path: string;
+    data: Uint8Array;
+} | undefined;
 /**
  * Map Cursor McpArgs back to the OpenCode tool id.
  * Prefers provider_identifier + bare tool_name (github + create_pull_request
@@ -145,15 +183,10 @@ export declare function mcpRealToolName(mcpArgs: Record<string, unknown>, defaul
  * A read target addressed by URI scheme rather than by local filesystem path.
  *
  * Cursor's LocalReadExecutor only ever reads local files, so this provider
- * mirrors its pre-execution validation. Host read tools are not so limited:
- * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
- * discoverable tool — including all MCP server tools — under `xd://<tool>`
- * device URLs that are read for their schema and written to for execution
- * (`tools.xdev`, on by default). Resolving those against the workspace root
- * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
- * as missing and gets refused as `file_not_found` — so the host's read tool is
- * never called and every xd://-mounted MCP tool is unreachable through this
- * provider. Such targets must be forwarded untouched and left to the host.
+ * mirrors its pre-execution validation. An advertised host read tool may also
+ * accept URLs or internal URI schemes. Resolving those against the workspace
+ * root mangles the URI and produces a false `file_not_found`, so URI targets
+ * are forwarded untouched and left to the advertised executor.
  *
  * Requires a scheme of two or more characters followed by `://`, so Windows
  * drive letters (`C:\src`, `C:/src`) stay local paths.

package/dist/protocol/tools.js

@@ -299,6 +299,10 @@ const PRESERVE_EMPTY_STRING_KEYS = new Set([
     "file_text",
     "fileText",
     "stream_content",
+    // Some advertised edit schemas use a single textual `input` payload. Preserve
+    // an empty value so the executor reports the real edit error rather than a
+    // misleading missing-property error.
+    "input",
     "oldString",
     "old_string",
     "newString",
@@ -396,18 +400,16 @@ function subagentTypeEnumValues(schema) {
 }
 /** Extract the current host's permission-filtered Task/Actor recipient catalog. */
 export function extractHostSubagentCatalog(tools) {
-    const executorTool = tools.find((tool) => tool.name === "actor") ??
-        tools.find((tool) => tool.name === "task");
+    const executorTool = tools.find((tool) => tool.name === "task");
     if (!executorTool)
         return { agents: [], complete: true };
     const described = parseSubagentDescriptionCatalog(executorTool.description);
     const enumNames = subagentTypeEnumValues(executorTool.inputSchema);
     const descriptions = new Map(described.agents.map((agent) => [agent.name, agent.description]));
-    // MiMo's Actor enum is stricter than its prose catalog (`mode: subagent`
-    // rather than every non-primary agent), so structured names are authoritative.
+    // A structured subagent_type enum is stricter than prose, so it is authoritative.
     const names = new Set(enumNames.length > 0 ? enumNames : described.agents.map((agent) => agent.name));
     return {
-        executor: executorTool.name,
+        executor: "task",
         agents: [...names].map((name) => ({
             name,
             ...(descriptions.get(name) ? { description: descriptions.get(name) } : {}),
@@ -467,9 +469,9 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
     if (parsed.resultField !== "subagent_result" || parsed.toolName !== "task")
         return;
     const advertised = new Set(advertisedToolNames);
-    const executor = advertised.has("actor") ? "actor" : advertised.has("task") ? "task" : undefined;
-    if (!executor)
+    if (!advertised.has("task"))
         return;
+    const executor = "task";
     const description = str(parsed.args.description) ?? "";
     const prompt = str(parsed.args.prompt) ?? "";
     const cursorSubagentType = str(parsed.resultMetadata?.cursor_subagent_type) ??
@@ -484,28 +486,55 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
     }
     const resumeAgentId = str(parsed.args.task_id);
     parsed.toolName = executor;
-    if (executor === "task") {
-        parsed.args = {
-            description,
-            prompt,
-            subagent_type: subagentType,
-            ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
-            ...(parsed.args.background === true ? { background: true } : {}),
-        };
-        return;
-    }
     parsed.args = {
-        operation: {
-            action: parsed.args.background === true ? "spawn" : "run",
-            description,
-            prompt,
-            subagent_type: subagentType,
-            ...(resumeAgentId ? { actor_id: resumeAgentId } : {}),
-        },
+        description,
+        prompt,
+        subagent_type: subagentType,
+        ...(resumeAgentId ? { task_id: resumeAgentId } : {}),
+        ...(parsed.args.background === true ? { background: true } : {}),
     };
 }
 /** Matches Cursor's own pre-write read threshold (`local-exec` 52428800). */
 const MAX_EDIT_SOURCE_BYTES = 50 * 1024 * 1024;
+/**
+ * Complete the private read inside Cursor's legacy edit transaction without
+ * routing it through OpenCode's user-facing `read` tool. The latter caps every
+ * result at 50 KB, while Cursor's editor needs the complete file to calculate
+ * the correlated whole-file `write_args` that follows.
+ *
+ * The caller is responsible for proving that `filePath` is the same regular
+ * file named by an active `edit_tool_call` and is contained by the workspace.
+ */
+export function buildCompleteEditReadMessages(execId, sourcePath, resultPath = sourcePath) {
+    try {
+        const stat = fs.statSync(sourcePath);
+        if (!stat.isFile() || stat.size > MAX_EDIT_SOURCE_BYTES)
+            return undefined;
+        const content = fs.readFileSync(sourcePath, "utf8");
+        return [
+            encodeMessage("AgentClientMessage", {
+                exec_client_message: {
+                    id: execId,
+                    local_execution_time_ms: 0,
+                    read_result: {
+                        success: {
+                            path: resultPath,
+                            content,
+                            total_lines: countLines(content),
+                            file_size: stat.size,
+                            truncated: false,
+                            range_applied: false,
+                        },
+                    },
+                },
+            }),
+            buildExecStreamClose(execId),
+        ];
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Return the number of non-overlapping occurrences, stopping after ambiguity. */
 function replacementOccurrenceCount(source, needle) {
     if (!needle)
@@ -643,6 +672,12 @@ export function remapCorrelatedEditWriteForCatalog(parsed, advertisedToolNames,
 export function remapEditToolsForCatalog(parsed, advertisedToolNames, workspaceRoot) {
     if (parsed.toolName !== "write" && parsed.toolName !== "edit")
         return;
+    // `apply_patch` envelopes are text. A binary write has no patch form at all,
+    // so it must stay a write and reach the byte-preserving path — converting it
+    // here would drop the bytes and report a patch-translation failure instead of
+    // the image Cursor asked to save.
+    if (binaryWritePayload(parsed))
+        return;
     const advertised = new Set(advertisedToolNames);
     if (advertised.has(parsed.toolName) || !advertised.has(APPLY_PATCH_TOOL))
         return;
@@ -709,6 +744,43 @@ export function remapEditToolsForCatalog(parsed, advertisedToolNames, workspaceR
     // the requested path for the typed Cursor result.
     parsed.resultMetadata = { ...parsed.resultMetadata, path: filePath };
 }
+/**
+ * A partial-read notice is for Cursor's model, never for a file. Refuse only
+ * whole-file mutation forms that echo it. A targeted edit or Update File patch
+ * cannot truncate an unseen tail, and may legitimately edit source that quotes
+ * this provider's warning text.
+ */
+export function rejectPartialReadMutation(parsed) {
+    if (parsed.localError)
+        return;
+    let content;
+    if (parsed.toolName === "write") {
+        content = parsed.args.content;
+    }
+    else if (parsed.toolName === APPLY_PATCH_TOOL) {
+        const patchText = parsed.args.patchText;
+        if (typeof patchText !== "string" || !patchText.includes("*** Add File:"))
+            return;
+        content = patchText;
+    }
+    else {
+        return;
+    }
+    if (typeof content !== "string"
+        || !content.includes("[Partial read:")
+        || !content.includes("It is NOT the complete file."))
+        return;
+    const filePath = typeof parsed.args.filePath === "string"
+        ? parsed.args.filePath
+        : "the target file";
+    const nextOffset = /Continue with offset=(\d+)/.exec(content)?.[1];
+    parsed.localError =
+        `NO FILE CHANGE WAS MADE. Refusing a whole-file mutation of ${JSON.stringify(filePath)} ` +
+            "because it contains the provider's partial-read notice. Do not retry the same mutation. " +
+            (nextOffset
+                ? `Read the file from offset=${nextOffset}, then use a targeted edit or Update File patch.`
+                : "Read the remaining file ranges, then use a targeted edit or Update File patch.");
+}
 export function parseExecServerMessage(msg) {
     const id = msg.id;
     if (id === undefined)
@@ -864,7 +936,19 @@ export function parseExecServerMessage(msg) {
         toolName: mapped.toolName,
         args: mapped.args,
         resultField,
-        ...(resultMetadata ? { resultMetadata } : {}),
+        ...(resultMetadata || mapped.binaryBytes
+            ? {
+                resultMetadata: {
+                    ...resultMetadata,
+                    ...(mapped.binaryBytes
+                        ? {
+                            binaryWriteBytes: mapped.binaryBytes,
+                            path: str(rawArgs.path) ?? str(rawArgs.file_path) ?? "",
+                        }
+                        : {}),
+                },
+            }
+            : {}),
     };
 }
 function shellStreamResultMetadata(raw) {
@@ -944,14 +1028,31 @@ export function mapCursorArgsToOpencode(toolName, raw, execVariant) {
             // non-empty and only falls back to `file_text`; mirror that order so a
             // byte-encoded write is not silently seen as empty content.
             const bytes = bytesValue(cleaned.file_bytes) ?? bytesValue(cleaned.fileBytes);
-            const content = bytes !== undefined
-                ? decodeWriteBytes(bytes, str(cleaned.encoding_hint) ?? str(cleaned.encodingHint))
-                : stringValue(cleaned.content) ?? stringValue(cleaned.file_text) ?? stringValue(cleaned.fileText);
+            let content;
+            if (bytes !== undefined) {
+                content = decodeWriteBytes(bytes, str(cleaned.encoding_hint) ?? str(cleaned.encodingHint));
+                if (content === undefined) {
+                    // Binary. Surface the raw bytes to the caller instead of a lossy
+                    // decode; `binaryWritePayload` picks them up after parsing.
+                    return { toolName: "write", args, binaryBytes: bytes };
+                }
+            }
+            else {
+                content = stringValue(cleaned.content)
+                    ?? stringValue(cleaned.file_text)
+                    ?? stringValue(cleaned.fileText);
+            }
             if (content !== undefined)
                 args.content = content;
             return { toolName: "write", args };
         }
         case "edit": {
+            // Preserve an opaque textual edit payload when the advertised executor
+            // accepts that generic shape; rebuilding only OpenCode's targeted fields
+            // would silently turn a valid call into `{}`.
+            if (typeof cleaned.input === "string") {
+                return { toolName: "edit", args: { input: cleaned.input } };
+            }
             const args = {};
             const filePath = str(cleaned.filePath) ?? str(cleaned.path) ?? str(cleaned.file_path);
             if (filePath)
@@ -1029,22 +1130,56 @@ function bytesValue(v) {
     }
     return undefined;
 }
+/** UTF-16/32 embed NUL bytes in ordinary text; 8-bit encodings do not. */
+const WIDE_TEXT_ENCODING = /^utf-?(16|32)/;
 /**
  * Decode `WriteArgs.file_bytes`. `encoding_hint` names the file's original
- * encoding; OpenCode's `write` takes a string, so anything Node cannot decode
+ * encoding; OpenCode's `write` takes a string, so an unknown encoding label
  * falls back to UTF-8 rather than dropping the write.
+ *
+ * Returns undefined when the bytes are not text in that encoding. A non-fatal
+ * decode would replace every undecodable sequence with U+FFFD and hand the host
+ * a corrupted file that still reports success, so binary content must take the
+ * byte-preserving path instead (see `isBinaryWriteRequest`).
  */
-function decodeWriteBytes(bytes, encodingHint) {
+export function decodeWriteBytes(bytes, encodingHint) {
     const encoding = encodingHint?.trim().toLowerCase().replace(/[_ ]/g, "-");
+    let decoder;
+    let label = "utf-8";
     if (encoding && encoding !== "utf-8" && encoding !== "utf8") {
         try {
-            return new TextDecoder(encoding, { fatal: false }).decode(bytes);
+            decoder = new TextDecoder(encoding, { fatal: true });
+            label = encoding;
         }
         catch {
             trace(`write: unsupported encoding_hint ${JSON.stringify(encodingHint)} — decoding as utf-8`);
         }
     }
-    return new TextDecoder("utf-8").decode(bytes);
+    if (!decoder)
+        decoder = new TextDecoder("utf-8", { fatal: true });
+    // Single-byte encodings decode any byte sequence without error, so a decode
+    // that cannot fail is not on its own evidence of text.
+    if (!WIDE_TEXT_ENCODING.test(label) && bytes.includes(0))
+        return undefined;
+    try {
+        return decoder.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when a parsed `write` request carries bytes that are not text. Such a
+ * request cannot go to OpenCode's `write` tool at all — it takes a string, and
+ * additionally BOM-splits, diffs, and runs `Format.file()` on what it writes.
+ */
+export function binaryWritePayload(parsed) {
+    if (parsed.toolName !== "write")
+        return undefined;
+    const data = parsed.resultMetadata?.binaryWriteBytes;
+    if (!(data instanceof Uint8Array))
+        return undefined;
+    return { path: str(parsed.resultMetadata?.path) ?? "", data };
 }
 function num(v) {
     if (typeof v === "number" && Number.isFinite(v))
@@ -1127,15 +1262,10 @@ function untildify(input) {
  * A read target addressed by URI scheme rather than by local filesystem path.
  *
  * Cursor's LocalReadExecutor only ever reads local files, so this provider
- * mirrors its pre-execution validation. Host read tools are not so limited:
- * oh-my-pi's `read` accepts "a path, URL, or internal URI", and mounts every
- * discoverable tool — including all MCP server tools — under `xd://<tool>`
- * device URLs that are read for their schema and written to for execution
- * (`tools.xdev`, on by default). Resolving those against the workspace root
- * mangles `xd://everything_echo` into `<root>/xd:/everything_echo`, which stats
- * as missing and gets refused as `file_not_found` — so the host's read tool is
- * never called and every xd://-mounted MCP tool is unreachable through this
- * provider. Such targets must be forwarded untouched and left to the host.
+ * mirrors its pre-execution validation. An advertised host read tool may also
+ * accept URLs or internal URI schemes. Resolving those against the workspace
+ * root mangles the URI and produces a false `file_not_found`, so URI targets
+ * are forwarded untouched and left to the advertised executor.
  *
  * Requires a scheme of two or more characters followed by `://`, so Windows
  * drive letters (`C:\src`, `C:/src`) stay local paths.

package/dist/session.d.ts

@@ -1,7 +1,8 @@
 import type { BidiStream } from "./transport/connect.js";
 import { type CursorProviderError } from "./errors.js";
 import { type SessionActivitySource } from "./activity.js";
-import type { HostSubagentCatalog, ToolAliasRegistry } from "./protocol/tools.js";
+import type { HostSubagentCatalog, OpencodeToolDef, ToolAliasRegistry } from "./protocol/tools.js";
+import type { CursorConversationTokenDetails } from "./protocol/token-details.js";
 export type Frame = {
     flags: number;
     payload: Uint8Array;
@@ -99,10 +100,44 @@ export type CursorSession = {
      * conversation_checkpoint_update (CLI parity).
     */
     conversationId: string;
+    /** Cache root owning this conversation's durable restart state. */
+    cacheDir?: string;
     /** Latest eligible checkpoint emitted by this Run attempt. */
     resumeCheckpoint?: Uint8Array;
+    /** Last checkpoint-derived context snapshot, independent of retry eligibility. */
+    tokenDetails?: CursorConversationTokenDetails;
+    /** True only after this Run receives a checkpoint containing token details. */
+    tokenDetailsFresh?: boolean;
+    /**
+     * Run-lifetime cache evidence. Cursor exposes only aggregate cache counters at
+     * TurnEnded, so retain the inputs and protocol activity needed to explain
+     * whether a low ratio came from a cold/rebased prefix, context growth, or a
+     * multi-step agent Run.
+     */
+    cacheDiagnostics?: {
+        sessionKey?: string;
+        conversationId: string;
+        conversationGroupId?: string;
+        modelId?: string;
+        priorTokenDetails?: CursorConversationTokenDetails;
+        startedWithCheckpoint: boolean;
+        requestContextReused: boolean;
+        requestContextHash: string;
+        systemPromptHash?: string;
+        checkpointUpdates: number;
+        tokenDetailUpdates: number;
+        pumpPasses: number;
+        stepStarts: number;
+        stepCompletes: number;
+        displayToolCalls: number;
+        execRequests: number;
+    };
     /** OpenCode session whose own or descendant activity renews tool leases. */
     openCodeSessionId?: string;
+    /** Completed compaction must rebase once before resuming a normal agent. */
+    postCompactionRebase?: boolean;
+    /** Last real host catalog, retained only as a lifecycle-turn fallback. */
+    toolCatalog?: OpencodeToolDef[];
     stream: BidiStream;
     frames: AsyncIterator<Frame>;
     pending: Map<number, PendingExec>;
@@ -119,6 +154,7 @@ export type CursorSession = {
      */
     editToolCalls?: Map<string, {
         path: string;
+        completeRead?: boolean;
     }>;
     /** Monotonic synthetic exec ids for bridged (display-only) OpenCode tool calls. */
     nextBridgedExecId: number;
@@ -139,9 +175,8 @@ export type CursorSession = {
      */
     allowTools: boolean;
     /**
-     * Best-effort token usage for this held-open Run. Updated from text/tool
-     * activity and replaced by TurnEnded only for a single-step Run. Emitted on
-     * tool-call finishes so OpenCode does not store all-zero usage mid-loop.
+     * Best-effort held-Run activity counters used only for diagnostics. AI SDK
+     * accounting comes from the request-local final TurnEnded, never this estimate.
      */
     usageEstimate: {
         inputTokens: number;
@@ -150,13 +185,6 @@ export type CursorSession = {
         cacheWrite: number;
         reasoningTokens: number;
     };
-    /**
-     * True after this held Run has already crossed an OpenCode tool-call
-     * boundary. Cursor's eventual TurnEnded counters then cover the whole Run,
-     * not only the final doStream request, so they cannot be used as that
-     * request's context usage.
-     */
-    hadToolCallBoundary?: boolean;
     /**
      * True while a doStream pull() is actively reading this session's frames.
      * Prevents a late cancel/abort from a prior ReadableStream from destroying

package/dist/shared.d.ts

@@ -12,6 +12,9 @@ export declare const MODEL_CACHE_FILE = "cursor-models.json";
 /** Bumped when the on-disk model cache shape/semantics change (forces refetch). */
 export declare const MODEL_CACHE_SCHEMA_VERSION = 3;
 export declare const MODEL_CACHE_TTL_MS = 86400000;
+export declare const CONVERSATION_CACHE_DIR = "cursor-conversations";
+export declare const CONVERSATION_CACHE_SCHEMA_VERSION = 3;
+export declare const CONVERSATION_CACHE_TTL_MS = 86400000;
 export declare const VERSION_CACHE_FILE = "cursor-client-version.json";
 export declare const CONTENT_TYPE_CONNECT_PROTO = "application/connect+proto";
 export declare const CONNECT_PROTOCOL_VERSION = "1";

package/dist/shared.js

@@ -12,6 +12,9 @@ export const MODEL_CACHE_FILE = "cursor-models.json";
 /** Bumped when the on-disk model cache shape/semantics change (forces refetch). */
 export const MODEL_CACHE_SCHEMA_VERSION = 3;
 export const MODEL_CACHE_TTL_MS = 86_400_000;
+export const CONVERSATION_CACHE_DIR = "cursor-conversations";
+export const CONVERSATION_CACHE_SCHEMA_VERSION = 3;
+export const CONVERSATION_CACHE_TTL_MS = 86_400_000;
 export const VERSION_CACHE_FILE = "cursor-client-version.json";
 export const CONTENT_TYPE_CONNECT_PROTO = "application/connect+proto";
 export const CONNECT_PROTOCOL_VERSION = "1";

package/dist/usage.d.ts

@@ -1,51 +1,56 @@
 import type { LanguageModelV3Usage } from "@ai-sdk/provider";
-/** Non-negative integer counter from a Cursor `turn_ended` field. */
-export declare function turnEndedCounter(te: Record<string, unknown>, key: string): number;
-/**
- * Map request-local Cursor TurnEnded counters to AI SDK V3 usage (Kilo/OpenCode
- * flatten via input total = noCache + cacheRead + cacheWrite). Only use this
- * for a Run with no prior tool boundary; multi-step TurnEnded is cumulative.
- *
- * Contract: `input_tokens` is non-cached input; cache fields are separate.
- * Cursor's agent wire currently sends `cache_write=0` even when later turns
- * report large `cache_read`; we still forward the counter when non-zero.
- * If production semantics differ (input_tokens already total), adjust here.
- */
-export declare function buildLanguageModelV3UsageFromTurnEnded(te: Record<string, unknown>): LanguageModelV3Usage;
-export type CursorUsageEstimate = {
+import type { CursorContextUsageSource, CursorConversationTokenDetails } from "./protocol/token-details.js";
+export type CursorUsageCounters = {
     inputTokens: number;
     outputTokens: number;
     cacheRead: number;
     cacheWrite: number;
     reasoningTokens: number;
 };
+export type CursorUsageOptions = {
+    /** Cursor checkpoint occupancy, including the current turn's output. */
+    contextTotalTokens?: number;
+};
+export type CursorCacheDiagnosticStats = {
+    sessionKey?: string;
+    conversationId: string;
+    conversationGroupId?: string;
+    modelId?: string;
+    startedWithCheckpoint: boolean;
+    requestContextReused: boolean;
+    requestContextHash: string;
+    systemPromptHash?: string;
+    checkpointUpdates: number;
+    tokenDetailUpdates: number;
+    pumpPasses: number;
+    stepStarts: number;
+    stepCompletes: number;
+    displayToolCalls: number;
+    execRequests: number;
+};
+/** Non-negative integer counter from a Cursor `turn_ended` field. */
+export declare function turnEndedCounter(te: Record<string, unknown>, key: string): number;
+export declare function cursorUsageCountersFromTurnEnded(te: Record<string, unknown>): CursorUsageCounters;
 /**
- * A single-step trust path for TurnEnded counters is only safe when the
- * totals are close to the request-local budget. Cursor reports cumulative
- * conversation/Run totals even on Runs that never crossed an OpenCode tool
- * boundary: single-step follow-up turns and parallel no-tools side calls
- * carry the whole conversation's `cache_read`. Treating those totals as
- * request-local inflates OpenCode's context usage and triggers premature
- * compaction (issue #20).
+ * Map Cursor counters to AI SDK V3. Cursor's `input_tokens` already includes
+ * cache reads/writes, and `output_tokens` already includes reasoning.
  */
-export declare const CUMULATIVE_TURN_ENDED_RATIO = 3;
-export declare const MIN_TRUSTED_TURN_ENDED_TOTAL = 1024;
-export declare function exceedsRequestLocalBudget(te: Record<string, unknown>, budget: {
-    inputTokens: number;
-    outputTokens: number;
-}): boolean;
+export declare function buildLanguageModelV3UsageFromCounters(counters: CursorUsageCounters, options?: CursorUsageOptions): LanguageModelV3Usage;
+export declare function buildLanguageModelV3UsageFromTurnEnded(te: Record<string, unknown>, options?: CursorUsageOptions): LanguageModelV3Usage;
+/** Compact, parseable category snapshot for checkpoint-by-checkpoint traces. */
+export declare function formatCursorTokenCategories(details: CursorConversationTokenDetails | undefined): string;
 /**
- * Request-local usage for a held Cursor Run.
- *
- * `est.inputTokens` tracks the seed plus delivered tool results, while
- * `est.outputTokens` accumulates model output across earlier tool boundaries.
- * Move prior output into the current input estimate and report only this
- * doStream request's output. Cache counters are intentionally absent: the
- * only counters Cursor exposes at TurnEnded are cumulative for the whole Run.
+ * Explain Cursor's aggregate cache counters using the state visible to this
+ * client. `stepStarts` is deliberately not called a model-call count: Cursor
+ * does not expose per-model-call cache accounting on the Run stream.
  */
-export declare function buildLanguageModelV3UsageFromEstimate(est: CursorUsageEstimate, promptTokens: number, outputChars: number, estimateCharsToTokens: (chars: number) => number): LanguageModelV3Usage;
-/** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
-export declare function kiloShapedUsageFromV3(usage: LanguageModelV3Usage): {
+export declare function formatCursorCacheDiagnostics(counters: CursorUsageCounters, current: CursorConversationTokenDetails | undefined, prior: CursorConversationTokenDetails | undefined, stats: CursorCacheDiagnosticStats): string;
+/** One-line proof that Cursor, AI SDK, and projected OpenCode totals agree. */
+export declare function formatTurnUsageValidation(counters: CursorUsageCounters, usage: LanguageModelV3Usage, tokenDetails?: CursorConversationTokenDetails, contextSource?: CursorContextUsageSource): string;
+/** OpenCode requires a usage object at every step boundary. */
+export declare function emptyLanguageModelV3Usage(): LanguageModelV3Usage;
+/** Project nested V3 usage into the common flat AI-SDK counter shape. */
+export declare function flatUsageFromV3(usage: LanguageModelV3Usage): {
     inputTokens: number;
     outputTokens: number;
     reasoningTokens: number;