cursor-opencode-provider 0.4.2 → 0.5.0

package/dist/usage.js

@@ -5,63 +5,218 @@ export function turnEndedCounter(te, key) {
         ? Math.trunc(value)
         : 0;
 }
-/**
- * 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 function buildLanguageModelV3UsageFromTurnEnded(te) {
-    const input_tokens = turnEndedCounter(te, "input_tokens");
-    const output_tokens = turnEndedCounter(te, "output_tokens");
-    const cache_read = turnEndedCounter(te, "cache_read");
-    const cache_write = turnEndedCounter(te, "cache_write");
-    const reasoning_tokens = turnEndedCounter(te, "reasoning_tokens");
+export function cursorUsageCountersFromTurnEnded(te) {
     return {
-        inputTokens: {
-            total: input_tokens + cache_read + cache_write,
-            noCache: input_tokens,
-            cacheRead: cache_read,
-            cacheWrite: cache_write,
-        },
-        outputTokens: {
-            total: output_tokens + reasoning_tokens,
-            text: output_tokens,
-            reasoning: reasoning_tokens,
-        },
+        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"),
     };
 }
 /**
- * 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.
+ * Map Cursor counters to AI SDK V3. Cursor's `input_tokens` already includes
+ * cache reads/writes, and `output_tokens` already includes reasoning.
  */
-export function buildLanguageModelV3UsageFromEstimate(est, promptTokens, outputChars, estimateCharsToTokens) {
-    const outputText = estimateCharsToTokens(outputChars);
-    const priorOutput = Math.max(0, est.outputTokens - outputText);
-    const inputNoCache = Math.max(promptTokens, est.inputTokens + priorOutput);
+export function buildLanguageModelV3UsageFromCounters(counters, options = {}) {
+    const rawInput = Math.max(0, Math.trunc(counters.inputTokens));
+    const rawOutput = Math.max(0, Math.trunc(counters.outputTokens));
+    const rawCacheRead = Math.min(Math.max(0, Math.trunc(counters.cacheRead)), rawInput);
+    const rawCacheWrite = Math.min(Math.max(0, Math.trunc(counters.cacheWrite)), rawInput - rawCacheRead);
+    const rawReasoning = Math.min(Math.max(0, Math.trunc(counters.reasoningTokens)), rawOutput);
+    const contextTotal = options.contextTotalTokens;
+    const hasContextTotal = typeof contextTotal === "number" && Number.isFinite(contextTotal) && contextTotal >= 0;
+    const total = hasContextTotal ? Math.trunc(contextTotal) : rawInput + rawOutput;
+    const output = Math.min(rawOutput, total);
+    const input = Math.max(0, total - output);
+    // TurnEnded can aggregate several internal model calls, so its absolute input
+    // and cache counts can exceed the final checkpoint occupancy. Preserve the
+    // cache proportions while normalizing the partition to Cursor's context total.
+    const cacheRead = rawInput > 0
+        ? Math.min(input, Math.round(input * rawCacheRead / rawInput))
+        : 0;
+    const cacheWrite = rawInput > 0
+        ? Math.min(input - cacheRead, Math.round(input * rawCacheWrite / rawInput))
+        : 0;
+    const reasoning = rawOutput > 0
+        ? Math.min(output, Math.round(output * rawReasoning / rawOutput))
+        : 0;
     return {
         inputTokens: {
-            total: inputNoCache,
-            noCache: inputNoCache,
-            cacheRead: 0,
-            cacheWrite: 0,
+            total: input,
+            noCache: Math.max(input - cacheRead - cacheWrite, 0),
+            cacheRead,
+            cacheWrite,
         },
         outputTokens: {
-            total: outputText,
-            text: outputText,
-            reasoning: undefined,
+            total: output,
+            text: Math.max(output - reasoning, 0),
+            reasoning,
         },
     };
 }
+export function buildLanguageModelV3UsageFromTurnEnded(te, options = {}) {
+    return buildLanguageModelV3UsageFromCounters(cursorUsageCountersFromTurnEnded(te), options);
+}
+function usageCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.trunc(value)
+        : 0;
+}
+function usageRatio(part, total) {
+    return total > 0 ? `${(part / total * 100).toFixed(1)}%` : "n/a";
+}
+function categoryTokens(details) {
+    return new Map(details?.breakdown?.categories.map((category) => [
+        category.id || category.label || "(unnamed)",
+        category.estimatedTokens,
+    ]) ?? []);
+}
+/** Compact, parseable category snapshot for checkpoint-by-checkpoint traces. */
+export function formatCursorTokenCategories(details) {
+    const categories = Object.fromEntries(categoryTokens(details));
+    return Object.keys(categories).length > 0 ? JSON.stringify(categories) : "unavailable";
+}
+/**
+ * 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 function formatCursorCacheDiagnostics(counters, current, prior, stats) {
+    const rawInput = Math.max(0, Math.trunc(counters.inputTokens));
+    const rawRead = Math.min(rawInput, Math.max(0, Math.trunc(counters.cacheRead)));
+    const rawWrite = Math.min(rawInput - rawRead, Math.max(0, Math.trunc(counters.cacheWrite)));
+    const rawUncached = Math.max(0, rawInput - rawRead - rawWrite);
+    const priorCategories = categoryTokens(prior);
+    const currentCategories = categoryTokens(current);
+    const categoriesComparable = !!prior?.breakdown && !!current?.breakdown;
+    const categoryDelta = {};
+    let sameSizedCategoryTokens = 0;
+    if (categoriesComparable) {
+        for (const id of new Set([...priorCategories.keys(), ...currentCategories.keys()])) {
+            const before = priorCategories.get(id);
+            const after = currentCategories.get(id);
+            if (before === undefined)
+                categoryDelta[id] = "new";
+            else if (after === undefined)
+                categoryDelta[id] = "removed";
+            else {
+                categoryDelta[id] = after - before;
+                if (after === before)
+                    sameSizedCategoryTokens += after;
+            }
+        }
+    }
+    const continuity = stats.startedWithCheckpoint
+        ? prior ? "warm" : "checkpoint-without-token-details"
+        : "cold";
+    const contextDelta = current && prior ? current.usedTokens - prior.usedTokens : undefined;
+    return [
+        "cache diagnosis:",
+        `sessionKey=${stats.sessionKey ?? "-"}`,
+        `conversationId=${stats.conversationId}`,
+        `conversationGroupId=${stats.conversationGroupId ?? "-"}`,
+        `model=${stats.modelId ?? "-"}`,
+        `continuity=${continuity}`,
+        `rawInput=${rawInput}`,
+        `rawCacheRead=${rawRead}`,
+        `rawCacheWrite=${rawWrite}`,
+        `rawUncached=${rawUncached}`,
+        `rawReadRatio=${usageRatio(rawRead, rawInput)}`,
+        `rawWriteRatio=${usageRatio(rawWrite, rawInput)}`,
+        `priorContext=${prior?.usedTokens ?? "unavailable"}`,
+        `currentContext=${current?.usedTokens ?? "unavailable"}`,
+        `contextDelta=${contextDelta ?? "unavailable"}`,
+        `rawReadVsPriorContext=${prior ? usageRatio(rawRead, prior.usedTokens) : "n/a"}`,
+        `sameSizedCategoryTokens=${categoriesComparable ? sameSizedCategoryTokens : "unavailable"}`,
+        `categoryDelta=${categoriesComparable && Object.keys(categoryDelta).length > 0 ? JSON.stringify(categoryDelta) : "unavailable"}`,
+        `requestContext=${stats.requestContextReused ? "reused" : "built"}`,
+        `requestContextHash=${stats.requestContextHash.slice(0, 16)}`,
+        `systemPromptHash=${stats.systemPromptHash?.slice(0, 16) ?? "none"}`,
+        `systemPromptSent=${!stats.startedWithCheckpoint}`,
+        `checkpointUpdates=${stats.checkpointUpdates}`,
+        `tokenDetailUpdates=${stats.tokenDetailUpdates}`,
+        `pumpPasses=${stats.pumpPasses}`,
+        `steps=${stats.stepStarts}/${stats.stepCompletes}`,
+        `displayToolCalls=${stats.displayToolCalls}`,
+        `execRequests=${stats.execRequests}`,
+        "perModelCallCache=unavailable",
+    ].join(" ");
+}
+/** One-line proof that Cursor, AI SDK, and projected OpenCode totals agree. */
+export function formatTurnUsageValidation(counters, usage, tokenDetails, contextSource) {
+    const input = usageCount(usage.inputTokens.total);
+    const noCache = usageCount(usage.inputTokens.noCache);
+    const cacheRead = usageCount(usage.inputTokens.cacheRead);
+    const cacheWrite = usageCount(usage.inputTokens.cacheWrite);
+    const inputParts = noCache + cacheRead + cacheWrite;
+    const output = usageCount(usage.outputTokens.total);
+    const text = usageCount(usage.outputTokens.text);
+    const reasoning = usageCount(usage.outputTokens.reasoning);
+    const outputParts = text + reasoning;
+    const sentTotal = input + output;
+    const projectedOpenCodeTotal = inputParts + outputParts;
+    const rawTotal = counters.inputTokens + counters.outputTokens;
+    const cursor = tokenDetails
+        ? `${tokenDetails.usedTokens}/${tokenDetails.maxTokens}` +
+            `(${usageRatio(tokenDetails.usedTokens, tokenDetails.maxTokens)})`
+        : "unavailable";
+    const totalMatch = tokenDetails ? String(sentTotal === tokenDetails.usedTokens) : "unavailable";
+    const breakdown = tokenDetails?.breakdown;
+    const categorySum = breakdown?.categories.reduce((sum, category) => sum + category.estimatedTokens, 0);
+    const breakdownMatch = breakdown && categorySum !== undefined
+        ? breakdown.totalUsedTokens === tokenDetails.usedTokens &&
+            categorySum === breakdown.totalUsedTokens
+        : undefined;
+    const rawCached = counters.cacheRead + counters.cacheWrite;
+    const sentCached = cacheRead + cacheWrite;
+    const cacheRatioMatch = tokenDetails
+        ? counters.inputTokens > 0 && input > 0
+            ? Math.abs(rawCached / counters.inputTokens - sentCached / input) <= 1 / input
+            : rawCached === 0 && sentCached === 0
+        : undefined;
+    const status = input === inputParts &&
+        output === outputParts &&
+        projectedOpenCodeTotal === sentTotal &&
+        (cacheRatioMatch ?? true) &&
+        (!tokenDetails || sentTotal === tokenDetails.usedTokens) &&
+        (breakdownMatch ?? true)
+        ? "ok"
+        : "mismatch";
+    return [
+        "turn usage validation:",
+        `status=${status}`,
+        `source=${tokenDetails ? contextSource ?? "checkpoint-current-run" : "unavailable"}`,
+        `cursor=${cursor}`,
+        `rawTotal=${rawTotal}`,
+        `sentTotal=${sentTotal}`,
+        `totalMatch=${totalMatch}`,
+        `input=${input}`,
+        `inputParts=${inputParts}`,
+        `inputMatch=${input === inputParts}`,
+        `output=${output}`,
+        `outputParts=${outputParts}`,
+        `outputMatch=${output === outputParts}`,
+        `opencodeProjectedTotal=${projectedOpenCodeTotal}`,
+        `opencodeMatch=${projectedOpenCodeTotal === sentTotal}`,
+        `breakdownTotal=${breakdown?.totalUsedTokens ?? "unavailable"}`,
+        `categorySum=${categorySum ?? "unavailable"}`,
+        `breakdownMatch=${breakdownMatch ?? "unavailable"}`,
+        `rawCachedRatio=${usageRatio(rawCached, counters.inputTokens)}`,
+        `sentCachedRatio=${usageRatio(sentCached, input)}`,
+        `cacheRatioMatch=${cacheRatioMatch ?? "unavailable"}`,
+    ].join(" ");
+}
+/** OpenCode requires a usage object at every step boundary. */
+export function emptyLanguageModelV3Usage() {
+    return buildLanguageModelV3UsageFromCounters({
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        reasoningTokens: 0,
+    });
+}
 /** Mirror Kilo `Session.getUsage` / AI SDK flat fields from V3 nested usage. */
 export function kiloShapedUsageFromV3(usage) {
     const input = usage.inputTokens;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -92,6 +92,7 @@
     "@opencode-ai/plugin": "^1.18.16",
     "@opencode-ai/plugin-next": "npm:@opencode-ai/plugin@0.0.0-next-17155",
     "@tsconfig/node22": "^22.0.5",
+    "@types/bun": "^1.3.0",
     "@types/node": "^22.20.1",
     "typescript": "^5.9.3"
   }