cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/todo-store.js

@@ -54,6 +54,25 @@ export function normalizeSessionTodos(value) {
     }
     return out;
 }
+/** Fill omitted defaults before validation without dropping malformed entries. */
+export function normalizeOpencodeTodoArgs(args) {
+    if (!Array.isArray(args.todos))
+        return args;
+    return {
+        ...args,
+        todos: args.todos.map((item, index) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return item;
+            const todo = item;
+            return {
+                ...todo,
+                ...(todo.id === undefined ? { id: String(index + 1) } : {}),
+                ...(todo.status === undefined ? { status: "pending" } : {}),
+                ...(todo.priority === undefined ? { priority: "medium" } : {}),
+            };
+        }),
+    };
+}
 export function getSessionTodos(sessionID) {
     return lists.get(sessionID)?.map((todo) => ({ ...todo })) ?? [];
 }

package/dist/transport/connect.d.ts

@@ -35,7 +35,12 @@ export declare function fetchAgentUrl(token: string, options?: {
 }): Promise<string>;
 export type BidiStream = {
     write(msg: Uint8Array): boolean | void;
-    waitForDrain?(timeoutMs: number): Promise<void>;
+    /**
+     * Resolves once a backpressured write has drained. There is no deadline, as
+     * in Cursor CLI's transport: a stream error or close (remote or local) settles
+     * it, and the read-idle watchdog bounds a stream that stops answering.
+     */
+    waitForDrain?(): Promise<void>;
     end(): void;
     frames(): AsyncIterable<{
         flags: number;
@@ -73,9 +78,13 @@ export declare function resolveAgentOrigin(baseURL: string): string;
 export declare function closeCachedHttp2SessionsForTests(): void;
 /** Node-runtime regression hook; production callers use getSession(). */
 export declare function installSessionInvalidationForTests(origin: string, session: http2.ClientHttp2Session): void;
+/** Node-runtime regression hook: cache a connected local session for `origin`. */
+export declare function cacheHttp2SessionForTests(origin: string, session: http2.ClientHttp2Session): void;
 export declare function getSession(baseURL: string, options?: {
     pingTimeoutMs?: number;
 }): Promise<http2.ClientHttp2Session>;
+export declare function frameArrival(frame: object): number | undefined;
+export declare function lastFrameArrival(): number;
 export declare function bidiRunStream(token: string, options: {
     signal?: AbortSignal;
     baseURL: string;

package/dist/transport/connect.js

@@ -194,6 +194,7 @@ export class CursorRunInterruptedError extends CursorTransportError {
             transient: true,
             replaySafe: true,
             cause: options?.cause,
+            code: options?.cause === undefined ? "CURSOR_STREAM_CLOSED_EARLY" : undefined,
         });
         this.name = "CursorRunInterruptedError";
     }
@@ -234,6 +235,12 @@ function cursorRunGrpcError(grpcStatus, headers, trailers) {
 const _http2Sessions = new Map();
 const _http2SessionCreatedAt = new WeakMap();
 const _http2SessionListenerCleanup = new WeakMap();
+// As in Cursor CLI's transport (@connectrpc/connect-node 1.6.1
+// Http2SessionManager), a cached session keeps the process alive only while a
+// Run stream or a reuse ping is live on it: unref'd once connected, ref'd while
+// it holds one. A Run held open on a pending exec keeps its stream, so it stays
+// ref'd; an idle session would otherwise stop a headless host from exiting.
+const _http2SessionHolds = new WeakMap();
 // Validation and connect work for the same origin shares one Promise.
 const _http2Connecting = new Map();
 // Bound the time we'll wait for the initial connect. Without this, a dead or
@@ -242,8 +249,16 @@ const _http2Connecting = new Map();
 const CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_SESSION_PING_TIMEOUT_MS = 5_000;
 const DEFAULT_READ_IDLE_MS = 120_000;
-const WRITE_DRAIN_TIMEOUT_CODE = "CURSOR_WRITE_DRAIN_TIMEOUT";
 export const HTTP2_SESSION_MAX_AGE_MS = 15 * 60_000;
+// Every Run shares one session per origin. Node and Bun count its unsent bytes
+// against maxSessionMemory (10 MB by default) and, once over it, fail every new
+// stream with ENHANCE_YOUR_CALM (Bun before sending it, Node by refusing its
+// response headers); Node also fails a single write over it while the uplink
+// holds the bytes back. Run requests and KV replies run to many megabytes, and
+// the provider holds those bytes anyway, so the limit only adds a failure.
+// 256 MB clears the 100 MiB checkpoint transfer budget with room to spare.
+// Cursor CLI's transport sets no maxSessionMemory, so it keeps the default (#76).
+const RUN_SESSION_OPTIONS = { maxSessionMemory: 256 };
 export function shouldReuseHttp2Session(state, createdAt, now = Date.now()) {
     return !state.destroyed && !state.closed && now - createdAt < HTTP2_SESSION_MAX_AGE_MS;
 }
@@ -259,6 +274,42 @@ function dropSession(origin, session) {
     if (_http2Sessions.get(origin) === session)
         _http2Sessions.delete(origin);
 }
+/**
+ * Stop offering `session` for new Runs and close it so in-flight streams can
+ * drain. Used by age rotation and a failed reuse ping — never
+ * `destroy()`, which would abort every sibling Run multiplexed on the session
+ * mid-output (those Runs cannot be replayed after visible activity).
+ */
+function retireCachedSession(origin, session) {
+    dropSession(origin, session);
+    try {
+        session.close();
+    }
+    catch { /* already closed */ }
+}
+function holdHttp2Session(session) {
+    const holds = _http2SessionHolds.get(session) ?? 0;
+    _http2SessionHolds.set(session, holds + 1);
+    if (holds === 0)
+        session.ref();
+}
+function releaseHttp2Session(session) {
+    const holds = (_http2SessionHolds.get(session) ?? 0) - 1;
+    if (holds > 0) {
+        _http2SessionHolds.set(session, holds);
+        return;
+    }
+    _http2SessionHolds.delete(session);
+    if (!session.destroyed)
+        session.unref();
+}
+/** Offer a connected session for new Runs; it stays unref'd until one holds it. */
+function cacheReadySession(origin, session) {
+    if (!_http2SessionHolds.has(session))
+        session.unref();
+    _http2SessionCreatedAt.set(session, Date.now());
+    _http2Sessions.set(origin, session);
+}
 /** Test cleanup for local HTTP/2 fixtures; production sessions stay process-cached. */
 export function closeCachedHttp2SessionsForTests() {
     for (const session of _http2Sessions.values()) {
@@ -354,6 +405,13 @@ function installSessionInvalidation(origin, session) {
 export function installSessionInvalidationForTests(origin, session) {
     installSessionInvalidation(origin, session);
 }
+/** Node-runtime regression hook: cache a connected local session for `origin`. */
+export function cacheHttp2SessionForTests(origin, session) {
+    // Tests re-cache one client per turn; replace its listeners rather than stack them.
+    _http2SessionListenerCleanup.get(session)?.();
+    installSessionInvalidation(origin, session);
+    cacheReadySession(origin, session);
+}
 function invalidateSession(origin, session) {
     dropSession(origin, session);
     _http2SessionListenerCleanup.get(session)?.();
@@ -467,8 +525,7 @@ function connectSession(origin) {
             }
             // The TLS socket (if any) is owned by the HTTP/2 session from here on.
             tunnelSocket = undefined;
-            _http2SessionCreatedAt.set(session, Date.now());
-            _http2Sessions.set(origin, session);
+            cacheReadySession(origin, session);
             trace(`h2 session connected: origin=${origin}`);
             resolve(session);
         };
@@ -499,11 +556,12 @@ function connectSession(origin) {
                     }
                     tunnelSocket = tlsSocket;
                     session = http2.connect(origin, {
+                        ...RUN_SESSION_OPTIONS,
                         createConnection: () => tlsSocket,
                     });
                 }
                 else {
-                    session = http2.connect(origin);
+                    session = http2.connect(origin, RUN_SESSION_OPTIONS);
                 }
                 if (settled) {
                     try {
@@ -535,23 +593,27 @@ export function getSession(baseURL, options = {}) {
             const createdAt = _http2SessionCreatedAt.get(existing) ?? 0;
             if (!shouldReuseHttp2Session(existing, createdAt)) {
                 trace(`h2 session rotate: origin=${origin} ageMs=${Math.max(0, Date.now() - createdAt)}`);
-                dropSession(origin, existing);
-                try {
-                    existing.close();
-                }
-                catch { /* already closed */ }
+                retireCachedSession(origin, existing);
             }
             else {
                 try {
-                    await validateCachedSession(existing, pingTimeoutMs);
+                    holdHttp2Session(existing);
+                    try {
+                        await validateCachedSession(existing, pingTimeoutMs);
+                    }
+                    finally {
+                        releaseHttp2Session(existing);
+                    }
                     if (_http2Sessions.get(origin) === existing && !existing.destroyed && !existing.closed) {
                         trace(`h2 cached session ping ok: origin=${origin}`);
                         return existing;
                     }
                 }
                 catch (error) {
+                    // Sibling Runs may still be streaming on this session; destroy() would
+                    // abort them mid-output, where they cannot be replayed.
                     trace(`h2 cached session ping failed: origin=${origin} err=${error.message}`);
-                    invalidateSession(origin, existing);
+                    retireCachedSession(origin, existing);
                 }
             }
         }
@@ -565,6 +627,15 @@ export function getSession(baseURL, options = {}) {
     promise.then(cleanup, cleanup);
     return promise;
 }
+/** Process-wide order in which Run frames came off the network, before any reader takes them. */
+const frameArrivals = new WeakMap();
+let lastArrival = 0;
+export function frameArrival(frame) {
+    return frameArrivals.get(frame);
+}
+export function lastFrameArrival() {
+    return lastArrival;
+}
 export async function bidiRunStream(token, options) {
     const origin = resolveAgentOrigin(options.baseURL);
     const readIdleMs = timeoutMs("Cursor provider readIdleMs", options.readIdleMs, DEFAULT_READ_IDLE_MS);
@@ -587,6 +658,7 @@ export async function bidiRunStream(token, options) {
     const stream = session.request(headers, {
         endStream: false,
     });
+    holdHttp2Session(session);
     let writable = true;
     let locallyClosed = false;
     let remotelyClosed = false;
@@ -626,6 +698,14 @@ export async function bidiRunStream(token, options) {
         }
         return undefined;
     };
+    const drainTerminalError = (event) => {
+        if (event.kind === "local-close") {
+            return new CursorLocalCancellationError("Cursor Run stream closed locally during drain");
+        }
+        if (event.kind === "remote-error")
+            return event.error;
+        return observedFailure() ?? new CursorRunInterruptedError("Cursor Run stream ended before drain");
+    };
     const settleTerminal = (event) => {
         if (terminalEvent)
             return;
@@ -751,8 +831,10 @@ export async function bidiRunStream(token, options) {
         pendingChunks.length = 0;
         if (consumed < merged.length)
             pendingChunks.push(merged.subarray(consumed));
-        for (const frame of parsed)
+        for (const frame of parsed) {
+            frameArrivals.set(frame, ++lastArrival);
             enqueueFrame(frame);
+        }
     };
     const startInboundReader = () => {
         if (inboundReaderStarted || locallyClosed || remotelyClosed || streamFailure)
@@ -795,6 +877,7 @@ export async function bidiRunStream(token, options) {
     });
     stream.on("close", () => {
         writable = false;
+        releaseHttp2Session(session);
         remotelyClosed = !locallyClosed;
         if (remotelyClosed) {
             dropSession(origin, session);
@@ -810,6 +893,16 @@ export async function bidiRunStream(token, options) {
             `err=${rawStreamError instanceof Error ? rawStreamError.message : "none"})`);
         scheduleTerminalSettlement();
     });
+    // Reset with CANCEL, as Cursor CLI's transport does for an aborted call
+    // (@connectrpc/connect-node 1.6.1). A plain close() leaves a stream whose
+    // request write is still buffered open for good, which also keeps its
+    // session held and the process alive.
+    const closeLocally = () => {
+        try {
+            stream.close(http2.constants.NGHTTP2_CANCEL);
+        }
+        catch { /* already closing */ }
+    };
     if (abortSignal) {
         abortHandler = () => {
             if (!locallyClosed) {
@@ -820,7 +913,7 @@ export async function bidiRunStream(token, options) {
                 finishInbound();
                 stopInboundReader();
                 settleTerminal({ kind: "local-close" });
-                stream.close();
+                closeLocally();
             }
         };
         abortSignal.addEventListener("abort", abortHandler, { once: true });
@@ -851,20 +944,21 @@ export async function bidiRunStream(token, options) {
                 throw streamFailure;
             }
         },
-        waitForDrain(timeout) {
+        waitForDrain() {
             if (!backpressured)
                 return Promise.resolve();
-            const drainTimeoutMs = timeoutMs("Cursor write drain timeout", timeout, timeout);
+            if (terminalEvent)
+                return Promise.reject(drainTerminalError(terminalEvent));
             return new Promise((resolve, reject) => {
                 let settled = false;
                 const finish = (error) => {
                     if (settled)
                         return;
                     settled = true;
-                    clearTimeout(timer);
                     stream.removeListener("drain", onDrain);
                     stream.removeListener("error", onError);
                     stream.removeListener("close", onClose);
+                    terminalListeners.delete(onTerminal);
                     if (error)
                         reject(error);
                     else
@@ -884,18 +978,14 @@ export async function bidiRunStream(token, options) {
                         ? new CursorLocalCancellationError("Cursor Run stream closed locally during drain")
                         : observedFailure() ?? new CursorRunInterruptedError("Cursor Run stream closed before drain"));
                 };
-                const timer = setTimeout(() => {
-                    streamFailure ??= new CursorTransportError(`Cursor Run stream backpressure did not drain after ${drainTimeoutMs}ms`, { transient: false, replaySafe: false, code: WRITE_DRAIN_TIMEOUT_CODE });
-                    finish(streamFailure);
-                    try {
-                        stream.destroy(streamFailure);
-                    }
-                    catch { /* already closing */ }
-                }, drainTimeoutMs);
-                timer.unref?.();
+                // The Run's end settles it too: Node holds back `close` while a write
+                // is buffered, and a response can end while the request is still
+                // blocked, after which the read-idle watchdog no longer runs.
+                const onTerminal = (event) => finish(drainTerminalError(event));
                 stream.once("drain", onDrain);
                 stream.once("error", onError);
                 stream.once("close", onClose);
+                terminalListeners.add(onTerminal);
             });
         },
         end() {
@@ -906,7 +996,12 @@ export async function bidiRunStream(token, options) {
             finishInbound();
             stopInboundReader();
             settleTerminal({ kind: "local-close" });
-            stream.end();
+            // A blocked write cannot finish gracefully; discard it rather than leave
+            // its stream and session referenced after the drain has been rejected.
+            if (backpressured)
+                closeLocally();
+            else
+                stream.end();
         },
         async *frames() {
             try {
@@ -948,8 +1043,10 @@ export async function bidiRunStream(token, options) {
                 finishInbound();
                 stopInboundReader();
                 settleTerminal({ kind: "local-close" });
-                stream.close();
             }
+            // end() may already have half-closed the request. destroy() must still
+            // reset the stream if the peer has left its response open.
+            closeLocally();
         },
         isClosed() {
             return remotelyClosed || locallyClosed || stream.closed || stream.destroyed;

package/dist/usage.d.ts

@@ -19,6 +19,8 @@ export type CursorCacheDiagnosticStats = {
     conversationGroupId?: string;
     modelId?: string;
     startedWithCheckpoint: boolean;
+    /** Why a Run started without a checkpoint: a reset reason, `ephemeral`, or `no-checkpoint`. */
+    coldReason?: string;
     requestContextReused: boolean;
     requestContextHash: string;
     systemPromptHash?: string;
@@ -51,31 +53,49 @@ export declare function formatCursorTokenCategories(details: CursorConversationT
  * does not expose per-model-call cache accounting on the Run stream.
  */
 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;
 /**
- * OpenCode TUI/GUI replace each assistant message's `tokens` (they do not sum
- * occupancy). The TUI footer picks the last assistant with `tokens.output > 0`.
- * Session cost, however, adds every step-finish. Checkpoint occupancy is
- * therefore sent as a snapshot with `output=1` so the footer accepts it, and
- * callers attach {@link OPENCODE_DISPLAY_ONLY_COST_METADATA} so getUsage
- * reports $0 instead of billing the snapshot as a new prompt.
+ * One-line proof that Cursor, AI SDK, and projected OpenCode totals agree.
+ * `counterKind` names what `counters` hold so the line labels them truthfully:
+ * Cursor's TurnEnded request counters (`raw*`) or the occupancy-shaped counters
+ * of {@link occupancyValidationCounters} (`occupancy*`).
  */
-export declare const OPENCODE_DISPLAY_ONLY_COST_METADATA: {
-    readonly copilot: {
-        readonly totalNanoAiu: 0;
+export declare function formatTurnUsageValidation(counters: CursorUsageCounters, usage: LanguageModelV3Usage, tokenDetails?: CursorConversationTokenDetails, contextSource?: CursorContextUsageSource, counterKind?: "turn-ended" | "occupancy"): string;
+/**
+ * The `finish:` trace. `v3*` is the usage sent to OpenCode. The second group is
+ * labelled by where its numbers come from: `raw*` are Cursor's TurnEnded
+ * request counters (whole Run), `occupancy*` the checkpoint snapshot a
+ * tool-call boundary sends (its cache split as billed: the previous step's
+ * context, see `src/billing.ts`), and
+ * `est*` the provider's char/4 estimate before any checkpoint arrived.
+ */
+export declare function formatFinishTrace(input: {
+    reason: string;
+    usage: LanguageModelV3Usage;
+    turnEnded?: CursorUsageCounters;
+    occupancy?: {
+        usedTokens: number;
+        priorUsedTokens: number;
     };
-};
+    estimate: CursorUsageCounters;
+    source: string;
+}): string;
+/**
+ * A warning when Cursor's checkpoint counts no rules although this Run sent the
+ * system-instructions rule: the host system context (AGENTS.md, skills,
+ * subagents) is then likely absent from the model's prompt. Undefined when the
+ * breakdown is missing or stale, or when rules were counted.
+ */
+export declare function missingRulesWarning(details: CursorConversationTokenDetails | undefined, sentRuleChars: number, conversationId: string): string | undefined;
+/** OpenCode requires a usage object at every step boundary. */
+export declare function emptyLanguageModelV3Usage(): LanguageModelV3Usage;
 /**
- * Counters that mirror {@link occupancyUsageFromTokenDetails} for
- * {@link formatTurnUsageValidation}. Always validate occupancy finishes —
+ * Occupancy-shaped counters for {@link formatTurnUsageValidation}: `usedTokens`
+ * with `prior.usedTokens` of it cached, the shape every step finish sends
+ * (`shapeStepUsage` in `src/billing.ts`). Always validate occupancy finishes —
  * including TurnEnded/stop — against these, not against aggregate TurnEnded
  * request counters. Request cache ratios stay on `finish:` / cache diagnosis.
  */
 export declare function occupancyValidationCounters(details: CursorConversationTokenDetails, prior?: CursorConversationTokenDetails): CursorUsageCounters;
-export declare function occupancyUsageFromTokenDetails(details: CursorConversationTokenDetails, prior?: CursorConversationTokenDetails): LanguageModelV3Usage;
 /** Project nested V3 usage into the common flat AI-SDK counter shape. */
 export declare function flatUsageFromV3(usage: LanguageModelV3Usage): {
     inputTokens: number;

package/dist/usage.js

@@ -1,3 +1,4 @@
+import { currentCursorTokenBreakdown } from "./protocol/token-details.js";
 /** Non-negative integer counter from a Cursor `turn_ended` field. */
 export function turnEndedCounter(te, key) {
     const value = te[key];
@@ -75,7 +76,7 @@ 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) => [
+    return new Map(currentCursorTokenBreakdown(details)?.categories.map((category) => [
         category.id || category.label || "(unnamed)",
         category.estimatedTokens,
     ]) ?? []);
@@ -97,7 +98,7 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
     const rawUncached = Math.max(0, rawInput - rawRead - rawWrite);
     const priorCategories = categoryTokens(prior);
     const currentCategories = categoryTokens(current);
-    const categoriesComparable = !!prior?.breakdown && !!current?.breakdown;
+    const categoriesComparable = !!currentCursorTokenBreakdown(prior) && !!currentCursorTokenBreakdown(current);
     const categoryDelta = {};
     let sameSizedCategoryTokens = 0;
     if (categoriesComparable) {
@@ -132,6 +133,13 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
             && toolsDelta !== 0
             ? "client-overlay-changed"
             : "none";
+    // Occupancy measures context size, not cache reuse. A zero counter on an
+    // interaction turn cannot distinguish omitted accounting from a cache miss.
+    const interactionZeroRead = stats.startedWithCheckpoint
+        && rawRead === 0
+        && typeof prior?.usedTokens === "number"
+        && prior.usedTokens > 0
+        && (stats.createPlanInTurn === true || stats.switchModeInTurn === true);
     return [
         "cache diagnosis:",
         `sessionKey=${stats.sessionKey ?? "-"}`,
@@ -139,6 +147,7 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
         `conversationGroupId=${stats.conversationGroupId ?? "-"}`,
         `model=${stats.modelId ?? "-"}`,
         `continuity=${continuity}`,
+        `coldReason=${continuity === "cold" ? stats.coldReason ?? "unknown" : "-"}`,
         `rawInput=${rawInput}`,
         `rawCacheRead=${rawRead}`,
         `rawCacheWrite=${rawWrite}`,
@@ -148,7 +157,9 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
         `priorContext=${prior?.usedTokens ?? "unavailable"}`,
         `currentContext=${current?.usedTokens ?? "unavailable"}`,
         `contextDelta=${contextDelta ?? "unavailable"}`,
-        `rawReadVsPriorContext=${prior ? usageRatio(rawRead, prior.usedTokens) : "n/a"}`,
+        // Several model calls in one Run each re-read the prefix, so this multiple
+        // routinely exceeds 1 and is not a percentage.
+        `rawReadVsPriorContext=${prior && prior.usedTokens > 0 ? `${(rawRead / prior.usedTokens).toFixed(2)}x` : "n/a"}`,
         `sameSizedCategoryTokens=${categoriesComparable ? sameSizedCategoryTokens : "unavailable"}`,
         `categoryDelta=${categoriesComparable && Object.keys(categoryDelta).length > 0 ? JSON.stringify(categoryDelta) : "unavailable"}`,
         `toolsCategoryChurn=${toolsCategoryChurn}`,
@@ -164,11 +175,23 @@ export function formatCursorCacheDiagnostics(counters, current, prior, stats) {
         `execRequests=${stats.execRequests}`,
         `createPlanInTurn=${stats.createPlanInTurn === true}`,
         `switchModeInTurn=${stats.switchModeInTurn === true}`,
+        ...(interactionZeroRead
+            ? [
+                "turnEndedCacheRead=zero-interaction",
+                "cacheReuseEvidence=unavailable",
+            ]
+            : []),
         "perModelCallCache=unavailable",
     ].join(" ");
 }
-/** One-line proof that Cursor, AI SDK, and projected OpenCode totals agree. */
-export function formatTurnUsageValidation(counters, usage, tokenDetails, contextSource) {
+/**
+ * One-line proof that Cursor, AI SDK, and projected OpenCode totals agree.
+ * `counterKind` names what `counters` hold so the line labels them truthfully:
+ * Cursor's TurnEnded request counters (`raw*`) or the occupancy-shaped counters
+ * of {@link occupancyValidationCounters} (`occupancy*`).
+ */
+export function formatTurnUsageValidation(counters, usage, tokenDetails, contextSource, counterKind = "turn-ended") {
+    const counterLabel = counterKind === "occupancy" ? "occupancy" : "raw";
     const input = usageCount(usage.inputTokens.total);
     const noCache = usageCount(usage.inputTokens.noCache);
     const cacheRead = usageCount(usage.inputTokens.cacheRead);
@@ -189,8 +212,9 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
     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
+        ? categorySum !== breakdown.totalUsedTokens
+            ? false
+            : currentCursorTokenBreakdown(tokenDetails) ? true : "stale"
         : undefined;
     const rawCached = counters.cacheRead + counters.cacheWrite;
     const sentCached = cacheRead + cacheWrite;
@@ -206,9 +230,10 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
     const status = input === inputParts &&
         output === outputParts &&
         projectedOpenCodeTotal === sentTotal &&
+        (counterKind !== "occupancy" || rawTotal === sentTotal) &&
         (cacheRatioMatch ?? true) &&
         (!tokenDetails || sentTotal === tokenDetails.usedTokens) &&
-        (breakdownMatch ?? true)
+        breakdownMatch !== false
         ? "ok"
         : "mismatch";
     return [
@@ -216,7 +241,7 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
         `status=${status}`,
         `source=${tokenDetails ? contextSource ?? "checkpoint-current-run" : "unavailable"}`,
         `cursor=${cursor}`,
-        `rawTotal=${rawTotal}`,
+        `${counterLabel}Total=${rawTotal}`,
         `sentTotal=${sentTotal}`,
         `totalMatch=${totalMatch}`,
         `input=${input}`,
@@ -230,11 +255,53 @@ export function formatTurnUsageValidation(counters, usage, tokenDetails, context
         `breakdownTotal=${breakdown?.totalUsedTokens ?? "unavailable"}`,
         `categorySum=${categorySum ?? "unavailable"}`,
         `breakdownMatch=${breakdownMatch ?? "unavailable"}`,
-        `rawCachedRatio=${usageRatio(rawCached, counters.inputTokens)}`,
+        `${counterLabel}CachedRatio=${usageRatio(rawCached, counters.inputTokens)}`,
         `sentCachedRatio=${usageRatio(sentCached, input)}`,
         `cacheRatioMatch=${cacheRatioMatch ?? "unavailable"}`,
     ].join(" ");
 }
+/**
+ * The `finish:` trace. `v3*` is the usage sent to OpenCode. The second group is
+ * labelled by where its numbers come from: `raw*` are Cursor's TurnEnded
+ * request counters (whole Run), `occupancy*` the checkpoint snapshot a
+ * tool-call boundary sends (its cache split as billed: the previous step's
+ * context, see `src/billing.ts`), and
+ * `est*` the provider's char/4 estimate before any checkpoint arrived.
+ */
+export function formatFinishTrace(input) {
+    const { usage, turnEnded, occupancy, estimate } = input;
+    const counters = turnEnded
+        ? `rawIn=${turnEnded.inputTokens} rawOut=${turnEnded.outputTokens} ` +
+            `rawCacheRead=${turnEnded.cacheRead} rawCacheWrite=${turnEnded.cacheWrite} ` +
+            (occupancy ? `occupancyPrefixCache=${occupancy.priorUsedTokens} ` : "")
+        : occupancy
+            ? `occupancyIn=${Math.max(0, occupancy.usedTokens - 1)} occupancyOut=${occupancy.usedTokens > 0 ? 1 : 0} ` +
+                `occupancyCacheRead=${usage.inputTokens?.cacheRead ?? 0} ` +
+                `occupancyCacheWrite=${usage.inputTokens?.cacheWrite ?? 0} `
+            : `estIn=${estimate.inputTokens} estOut=${estimate.outputTokens} ` +
+                `estCacheRead=${estimate.cacheRead} estCacheWrite=${estimate.cacheWrite} `;
+    return `finish: reason=${input.reason} ` +
+        `v3In=${usage.inputTokens?.total ?? 0} v3Out=${usage.outputTokens?.total ?? 0} ` +
+        `v3CacheRead=${usage.inputTokens?.cacheRead ?? 0} v3CacheWrite=${usage.inputTokens?.cacheWrite ?? 0} ` +
+        `v3Reasoning=${usage.outputTokens?.reasoning ?? 0} ` +
+        counters +
+        `source=${input.source}`;
+}
+/**
+ * A warning when Cursor's checkpoint counts no rules although this Run sent the
+ * system-instructions rule: the host system context (AGENTS.md, skills,
+ * subagents) is then likely absent from the model's prompt. Undefined when the
+ * breakdown is missing or stale, or when rules were counted.
+ */
+export function missingRulesWarning(details, sentRuleChars, conversationId) {
+    if (sentRuleChars <= 0)
+        return undefined;
+    const rules = currentCursorTokenBreakdown(details)?.categories.find((category) => category.id === "rules");
+    if (!rules || rules.estimatedTokens > 0)
+        return undefined;
+    return `context warning: Cursor counted rules=0 although this Run sent the ${sentRuleChars}-char ` +
+        `system-instructions rule conversationId=${conversationId} — host instructions may not reach the model`;
+}
 /** OpenCode requires a usage object at every step boundary. */
 export function emptyLanguageModelV3Usage() {
     return buildLanguageModelV3UsageFromCounters({
@@ -246,41 +313,25 @@ export function emptyLanguageModelV3Usage() {
     });
 }
 /**
- * OpenCode TUI/GUI replace each assistant message's `tokens` (they do not sum
- * occupancy). The TUI footer picks the last assistant with `tokens.output > 0`.
- * Session cost, however, adds every step-finish. Checkpoint occupancy is
- * therefore sent as a snapshot with `output=1` so the footer accepts it, and
- * callers attach {@link OPENCODE_DISPLAY_ONLY_COST_METADATA} so getUsage
- * reports $0 instead of billing the snapshot as a new prompt.
- */
-export const OPENCODE_DISPLAY_ONLY_COST_METADATA = {
-    copilot: { totalNanoAiu: 0 },
-};
-/**
- * Counters that mirror {@link occupancyUsageFromTokenDetails} for
- * {@link formatTurnUsageValidation}. Always validate occupancy finishes —
+ * Occupancy-shaped counters for {@link formatTurnUsageValidation}: `usedTokens`
+ * with `prior.usedTokens` of it cached, the shape every step finish sends
+ * (`shapeStepUsage` in `src/billing.ts`). Always validate occupancy finishes —
  * including TurnEnded/stop — against these, not against aggregate TurnEnded
  * request counters. Request cache ratios stay on `finish:` / cache diagnosis.
  */
 export function occupancyValidationCounters(details, prior) {
     const used = Math.max(0, Math.trunc(details.usedTokens));
+    const input = Math.max(0, used - 1);
     return {
-        inputTokens: used,
+        inputTokens: input,
         outputTokens: used > 0 ? 1 : 0,
-        cacheRead: Math.max(0, Math.trunc(prior?.usedTokens ?? 0)),
+        // Cursor can shrink the context between checkpoints; the prior prefix
+        // cannot be larger than what is in context now.
+        cacheRead: Math.min(input, Math.max(0, Math.trunc(prior?.usedTokens ?? 0))),
         cacheWrite: 0,
         reasoningTokens: 0,
     };
 }
-export function occupancyUsageFromTokenDetails(details, prior) {
-    const used = Math.max(0, Math.trunc(details.usedTokens));
-    if (used <= 0)
-        return emptyLanguageModelV3Usage();
-    return buildLanguageModelV3UsageFromCounters(occupancyValidationCounters(details, prior), {
-        contextTotalTokens: used,
-        priorContextTokens: prior?.usedTokens,
-    });
-}
 /** Project nested V3 usage into the common flat AI-SDK counter shape. */
 export function flatUsageFromV3(usage) {
     const input = usage.inputTokens;