cursor-opencode-provider 0.4.3 → 0.6.0

package/dist/usage.js

@@ -5,89 +5,220 @@ export function turnEndedCounter(te, key) {
         ? Math.trunc(value)
         : 0;
 }
+export function cursorUsageCountersFromTurnEnded(te) {
+    return {
+        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"),
+    };
+}
 /**
- * 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.
+ * Map Cursor counters to AI SDK V3. Cursor's `input_tokens` already includes
+ * cache reads/writes, and `output_tokens` already includes reasoning.
  */
-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 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: input_tokens + cache_read + cache_write,
-            noCache: input_tokens,
-            cacheRead: cache_read,
-            cacheWrite: cache_write,
+            total: input,
+            noCache: Math.max(input - cacheRead - cacheWrite, 0),
+            cacheRead,
+            cacheWrite,
         },
         outputTokens: {
-            total: output_tokens + reasoning_tokens,
-            text: output_tokens,
-            reasoning: reasoning_tokens,
+            total: output,
+            text: Math.max(output - reasoning, 0),
+            reasoning,
         },
     };
 }
-/**
- * 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).
- */
-export const CUMULATIVE_TURN_ENDED_RATIO = 3;
-export const MIN_TRUSTED_TURN_ENDED_TOTAL = 1024;
-export function exceedsRequestLocalBudget(te, budget) {
-    const total = turnEndedCounter(te, "input_tokens") +
-        turnEndedCounter(te, "cache_read") +
-        turnEndedCounter(te, "cache_write");
-    const requestLocal = budget.inputTokens + budget.outputTokens;
-    // Skip when the request-local seed is unknown; otherwise compare against
-    // max(ratio × request-local, absolute floor) so tiny prompts still reject
-    // multi-million-token conversation cache totals.
-    if (requestLocal <= 0)
-        return false;
-    const trustCeiling = Math.max(requestLocal * CUMULATIVE_TURN_ENDED_RATIO, MIN_TRUSTED_TURN_ENDED_TOTAL);
-    return total > trustCeiling;
+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";
 }
 /**
- * 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 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);
-    return {
-        inputTokens: {
-            total: inputNoCache,
-            noCache: inputNoCache,
-            cacheRead: 0,
-            cacheWrite: 0,
-        },
-        outputTokens: {
-            total: outputText,
-            text: outputText,
-            reasoning: undefined,
-        },
-    };
+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) {
+/** Project nested V3 usage into the common flat AI-SDK counter shape. */
+export function flatUsageFromV3(usage) {
     const input = usage.inputTokens;
     const output = usage.outputTokens;
     const noCache = input.noCache ?? 0;

package/dist/web-search-tool.d.ts

@@ -1,33 +1,29 @@
+import { executeOpenCodeWebSearch } from "./web-tools.js";
+type ToolFactory = {
+    tool: (input: Record<string, unknown>) => Record<string, unknown>;
+    schema: {
+        string: () => any;
+        number: () => any;
+        enum: (values: readonly string[]) => any;
+    };
+};
+/** Build the classic OpenCode web-search tool with the host's own Zod helper. */
+export declare function createOpenCodeWebSearchTool(factory: ToolFactory): Record<string, unknown>;
 /**
- * Classic-plugin web search tool registration.
- *
- * Kept apart from `./web-tools.ts` on purpose: this is a *value* import from
- * `@opencode-ai/plugin`, and the OpenCode 2.0 entrypoint shares the search
- * implementation in that module. 2.0's package root exports no `tool`, so
- * importing it from a module on the 2.0 graph would throw during plugin load.
- * Only `plugin.ts` (classic hooks) may import this file.
+ * Host-neutral JSON-schema fallback when the classic helper is unavailable.
+ * OpenCode's legacy schema adapter marks every listed property required, so
+ * expose only the genuinely required query rather than turning four optional
+ * tuning fields into mandatory inputs.
  */
 export declare const openCodeWebSearchTool: {
     description: string;
     args: {
-        query: import("zod").ZodString;
-        numResults: import("zod").ZodOptional<import("zod").ZodNumber>;
-        livecrawl: import("zod").ZodOptional<import("zod").ZodEnum<{
-            fallback: "fallback";
-            preferred: "preferred";
-        }>>;
-        type: import("zod").ZodOptional<import("zod").ZodEnum<{
-            fast: "fast";
-            auto: "auto";
-            deep: "deep";
-        }>>;
-        contextMaxCharacters: import("zod").ZodOptional<import("zod").ZodNumber>;
+        query: {
+            type: string;
+            description: string;
+        };
     };
-    execute(args: {
-        query: string;
-        numResults?: number | undefined;
-        livecrawl?: "fallback" | "preferred" | undefined;
-        type?: "fast" | "auto" | "deep" | undefined;
-        contextMaxCharacters?: number | undefined;
-    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+    execute: typeof executeOpenCodeWebSearch;
 };
+export type { ToolFactory as OpenCodeToolFactory };
+export declare function createOpenCodeWebSearchToolFromPlugin(pluginModule: any): Record<string, unknown>;

package/dist/web-search-tool.js

@@ -1,22 +1,32 @@
-import { tool } from "@opencode-ai/plugin";
 import { executeOpenCodeWebSearch } from "./web-tools.js";
+/** Build the classic OpenCode web-search tool with the host's own Zod helper. */
+export function createOpenCodeWebSearchTool(factory) {
+    const schema = factory.schema;
+    return factory.tool({
+        description: "Search the web for current information using OpenCode's web search backend.",
+        args: {
+            query: schema.string().describe("Web search query"),
+            numResults: schema.number().int().min(1).max(20).optional(),
+            livecrawl: schema.enum(["fallback", "preferred"]).optional(),
+            type: schema.enum(["auto", "fast", "deep"]).optional(),
+            contextMaxCharacters: schema.number().int().positive().optional(),
+        },
+        execute: executeOpenCodeWebSearch,
+    });
+}
 /**
- * Classic-plugin web search tool registration.
- *
- * Kept apart from `./web-tools.ts` on purpose: this is a *value* import from
- * `@opencode-ai/plugin`, and the OpenCode 2.0 entrypoint shares the search
- * implementation in that module. 2.0's package root exports no `tool`, so
- * importing it from a module on the 2.0 graph would throw during plugin load.
- * Only `plugin.ts` (classic hooks) may import this file.
+ * Host-neutral JSON-schema fallback when the classic helper is unavailable.
+ * OpenCode's legacy schema adapter marks every listed property required, so
+ * expose only the genuinely required query rather than turning four optional
+ * tuning fields into mandatory inputs.
  */
-export const openCodeWebSearchTool = tool({
+export const openCodeWebSearchTool = {
     description: "Search the web for current information using OpenCode's web search backend.",
     args: {
-        query: tool.schema.string().describe("Web search query"),
-        numResults: tool.schema.number().int().min(1).max(20).optional(),
-        livecrawl: tool.schema.enum(["fallback", "preferred"]).optional(),
-        type: tool.schema.enum(["auto", "fast", "deep"]).optional(),
-        contextMaxCharacters: tool.schema.number().int().positive().optional(),
+        query: { type: "string", description: "Web search query" },
     },
     execute: executeOpenCodeWebSearch,
-});
+};
+export function createOpenCodeWebSearchToolFromPlugin(pluginModule) {
+    return createOpenCodeWebSearchTool({ tool: pluginModule.tool, schema: pluginModule.tool.schema });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-opencode-provider",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "Use Cursor subscription models from OpenCode via Cursor's Connect-RPC agent protocol",
   "type": "module",
   "license": "MIT",
@@ -55,6 +55,10 @@
     "./auth": {
       "types": "./dist/auth.d.ts",
       "import": "./dist/auth.js"
+    },
+    "./image-save": {
+      "types": "./dist/image-save.d.ts",
+      "import": "./dist/image-save.js"
     }
   },
   "files": [
@@ -80,11 +84,10 @@
     "protobufjs": "^7.6.5"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.17.13",
-    "@opencode-compat/profile": ">=0.1.0"
+    "@opencode-ai/plugin": "^1.17.13"
   },
   "peerDependenciesMeta": {
-    "@opencode-compat/profile": {
+    "@opencode-ai/plugin": {
       "optional": true
     }
   },