cursor-opencode-provider 0.4.2 → 0.5.0

package/dist/protocol/request.js

@@ -76,6 +76,8 @@ export function buildRunRequest(input) {
         });
     const runRequest = {
         conversation_id: input.conversationId,
+        conversation_group_id: input.conversationGroupId ?? input.conversationId,
+        run_id: msgId,
         action,
         requested_model: {
             // The provider always selects a concrete model. Cursor's "default"

package/dist/protocol/token-details.d.ts

@@ -0,0 +1,33 @@
+export type CursorPromptTokenCategory = {
+    id: string;
+    label: string;
+    estimatedTokens: number;
+    characterCount?: number;
+};
+export type CursorPromptTokenBreakdown = {
+    totalUsedTokens: number;
+    maxTokens: number;
+    categories: CursorPromptTokenCategory[];
+};
+export type CursorConversationTokenDetails = {
+    usedTokens: number;
+    maxTokens: number;
+    breakdown?: CursorPromptTokenBreakdown;
+};
+export type CursorContextUsageSource = "checkpoint-current-run" | "checkpoint-previous-turn";
+/**
+ * Read field #5 (`ConversationTokenDetails`) from Cursor's opaque
+ * `ConversationStateStructure` checkpoint without decoding or re-encoding the
+ * rest of the state. Unknown checkpoint fields therefore remain byte-exact.
+ */
+export declare function decodeConversationTokenDetails(checkpoint: Uint8Array | undefined): CursorConversationTokenDetails | undefined;
+export declare function cursorContextUsageMetadata(details: CursorConversationTokenDetails, source?: CursorContextUsageSource): {
+    contextUsageVersion: number;
+    source: CursorContextUsageSource;
+    stale: boolean;
+    usedTokens: number;
+    maxTokens: number;
+    remainingTokens: number;
+    usedPercent?: number;
+    breakdown?: CursorPromptTokenBreakdown;
+};

package/dist/protocol/token-details.js

@@ -0,0 +1,155 @@
+import protobuf from "protobufjs";
+const MAX_BREAKDOWN_CATEGORIES = 128;
+function requireWireType(actual, expected, field) {
+    if (actual !== expected)
+        throw new Error(`invalid ${field} wire type`);
+}
+function decodeCategory(data) {
+    const reader = protobuf.Reader.create(data);
+    let id = "";
+    let label = "";
+    let estimatedTokens = 0;
+    let characterCount;
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const wireType = tag & 7;
+        switch (tag >>> 3) {
+            case 1:
+                requireWireType(wireType, 2, "category id");
+                id = reader.string();
+                break;
+            case 2:
+                requireWireType(wireType, 2, "category label");
+                label = reader.string();
+                break;
+            case 3:
+                requireWireType(wireType, 0, "category token count");
+                estimatedTokens = reader.uint32();
+                break;
+            case 4:
+                requireWireType(wireType, 0, "category character count");
+                characterCount = reader.uint32();
+                break;
+            default:
+                reader.skipType(wireType);
+        }
+    }
+    return {
+        id,
+        label,
+        estimatedTokens,
+        ...(characterCount === undefined ? {} : { characterCount }),
+    };
+}
+function decodeBreakdown(data) {
+    const reader = protobuf.Reader.create(data);
+    let totalUsedTokens = 0;
+    let maxTokens = 0;
+    const categories = [];
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const wireType = tag & 7;
+        switch (tag >>> 3) {
+            case 1:
+                requireWireType(wireType, 0, "breakdown used tokens");
+                totalUsedTokens = reader.uint32();
+                break;
+            case 2:
+                requireWireType(wireType, 0, "breakdown max tokens");
+                maxTokens = reader.uint32();
+                break;
+            case 3:
+                requireWireType(wireType, 2, "breakdown category");
+                if (categories.length < MAX_BREAKDOWN_CATEGORIES) {
+                    categories.push(decodeCategory(reader.bytes()));
+                }
+                else {
+                    reader.bytes();
+                }
+                break;
+            default:
+                reader.skipType(wireType);
+        }
+    }
+    return { totalUsedTokens, maxTokens, categories };
+}
+function decodeTokenDetails(data) {
+    const reader = protobuf.Reader.create(data);
+    let usedTokens = 0;
+    let maxTokens = 0;
+    let sawUsedTokens = false;
+    let sawMaxTokens = false;
+    let breakdown;
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const wireType = tag & 7;
+        switch (tag >>> 3) {
+            case 1:
+                requireWireType(wireType, 0, "used tokens");
+                usedTokens = reader.uint32();
+                sawUsedTokens = true;
+                break;
+            case 2:
+                requireWireType(wireType, 0, "max tokens");
+                maxTokens = reader.uint32();
+                sawMaxTokens = true;
+                break;
+            case 3:
+                requireWireType(wireType, 2, "token breakdown");
+                breakdown = decodeBreakdown(reader.bytes());
+                break;
+            default:
+                reader.skipType(wireType);
+        }
+    }
+    if (!sawUsedTokens && !sawMaxTokens && !breakdown)
+        return undefined;
+    return {
+        usedTokens,
+        maxTokens,
+        ...(breakdown ? { breakdown } : {}),
+    };
+}
+/**
+ * Read field #5 (`ConversationTokenDetails`) from Cursor's opaque
+ * `ConversationStateStructure` checkpoint without decoding or re-encoding the
+ * rest of the state. Unknown checkpoint fields therefore remain byte-exact.
+ */
+export function decodeConversationTokenDetails(checkpoint) {
+    if (!checkpoint?.length)
+        return undefined;
+    try {
+        const reader = protobuf.Reader.create(checkpoint);
+        let details;
+        while (reader.pos < reader.len) {
+            const tag = reader.uint32();
+            const wireType = tag & 7;
+            if ((tag >>> 3) === 5) {
+                requireWireType(wireType, 2, "conversation token details");
+                details = decodeTokenDetails(reader.bytes());
+            }
+            else {
+                reader.skipType(wireType);
+            }
+        }
+        return details;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function cursorContextUsageMetadata(details, source = "checkpoint-current-run") {
+    const usedPercent = details.maxTokens > 0
+        ? Math.max(0, Math.min(100, Math.round(details.usedTokens / details.maxTokens * 1_000) / 10))
+        : undefined;
+    return {
+        contextUsageVersion: 2,
+        source,
+        stale: source === "checkpoint-previous-turn",
+        usedTokens: details.usedTokens,
+        maxTokens: details.maxTokens,
+        remainingTokens: Math.max(0, details.maxTokens - details.usedTokens),
+        ...(usedPercent === undefined ? {} : { usedPercent }),
+        ...(details.breakdown ? { breakdown: details.breakdown } : {}),
+    };
+}

package/dist/protocol/tools.d.ts

@@ -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.

package/dist/protocol/tools.js

@@ -506,6 +506,45 @@ export function remapNativeSubagentForCatalog(parsed, advertisedToolNames, catal
 }
 /** 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)
@@ -709,6 +748,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)

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,34 +1,54 @@
 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;
+/**
+ * Map Cursor counters to AI SDK V3. Cursor's `input_tokens` already includes
+ * cache reads/writes, and `output_tokens` already includes reasoning.
+ */
+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;
+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;
 /** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
 export declare function kiloShapedUsageFromV3(usage: LanguageModelV3Usage): {
     inputTokens: number;