pi-cursor-sdk 0.2.0 → 0.3.6

package/src/cursor-live-run-coordinator.ts

@@ -43,6 +43,7 @@ export interface CursorLiveRun {
 	sdkRun?: CursorLiveSdkRun;
 	ignoreFutureSdkTurnUsage?: boolean;
 	accounting: CursorLiveRunAccountingState;
+	billedTurnUsage?: CursorSdkTurnUsage;
 	pendingEvents: CursorLiveQueuedEvent[];
 	textDeltas: string[];
 	emittedText: string;

package/src/cursor-native-tool-display-registration.ts

@@ -18,6 +18,7 @@ import {
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
+import { registerNativeCursorTool } from "./cursor-native-tool-display-tools.js";
 
 export const CURSOR_CORE_PI_REPLAY_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
 const CORE_PI_TOOL_NAMES = new Set<string>(CURSOR_CORE_PI_REPLAY_TOOL_NAMES);
@@ -40,12 +41,11 @@ type NativeRegistrationContext = Pick<ExtensionContext, "mode" | "model"> & {
 	ui: Pick<ExtensionContext["ui"], "notify">;
 };
 
-async function registerNativeCursorToolsFromSet(
+function registerNativeCursorToolsFromSet(
 	pi: CursorNativeToolRegistryApi,
 	toolNames: readonly NativeCursorToolName[],
-): Promise<NativeCursorToolName[]> {
+): NativeCursorToolName[] {
 	const newlySkippedToolNames: NativeCursorToolName[] = [];
-	let registerNativeCursorTool: ((pi: CursorNativeToolRegistryApi, toolName: NativeCursorToolName) => void) | undefined;
 	for (const toolName of toolNames) {
 		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
 		if (hasNonBuiltinTool(pi, toolName)) {
@@ -53,7 +53,6 @@ async function registerNativeCursorToolsFromSet(
 			newlySkippedToolNames.push(toolName);
 			continue;
 		}
-		registerNativeCursorTool ??= (await import("./cursor-native-tool-display-tools.js")).registerNativeCursorTool;
 		registerNativeCursorTool(pi, toolName);
 		registeredNativeToolNames.add(toolName);
 	}
@@ -105,31 +104,31 @@ export function syncRegisteredNativeCursorToolsForModel(
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
+function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
-		...(await registerNativeCursorToolsFromSet(pi, nonCoreToolNames)),
-		...(await registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES)),
+		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
+		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
 	];
 	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
 }
 
-async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
+function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	const requested = isCursorNativeToolRegistrationRequested(ctx.mode);
 	setCursorNativeToolDisplayRuntimeRequested(requested);
 	if (!requested) {
 		removeRegisteredNonCoreNativeCursorTools(pi);
 		return;
 	}
-	await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+	ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
-	registerCursorModelLifecycle(pi, async (ctx) => {
-		await ensureThenSyncNativeCursorToolsForModel(pi, ctx);
+	registerCursorModelLifecycle(pi, (ctx) => {
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 }
 

package/src/cursor-provider-errors.ts

@@ -166,7 +166,7 @@ function isCursorSdkStallAbortNetworkError(code: unknown, evidence: string, stac
 }
 
 /**
- * @cursor/sdk@1.0.23 throws internal RetriableError (name/kind "RetriableError") with message
+ * @cursor/sdk@1.0.27 throws internal RetriableError (name/kind "RetriableError") with message
  * "Connection stalled" or "Connection stalled repeatedly" after fetchWithRetry exhausts stalls.
  * The ConnectError is only the cause; the top-level error is not a ConnectError.
  */

package/src/cursor-provider-lazy.ts

@@ -7,8 +7,10 @@ import {
 	type Model,
 	type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
+import { streamCursor } from "./cursor-provider.js";
+import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 
-function makeProviderLoadErrorMessage(model: Model<Api>, error: unknown): AssistantMessage {
+function makeProviderRuntimeErrorMessage(model: Model<Api>, error: unknown, apiKey?: string): AssistantMessage {
 	return {
 		role: "assistant",
 		content: [],
@@ -25,7 +27,7 @@ function makeProviderLoadErrorMessage(model: Model<Api>, error: unknown): Assist
 		},
 		stopReason: "error",
 		timestamp: Date.now(),
-		errorMessage: `Failed to load Cursor provider runtime: ${error instanceof Error ? error.message : String(error)}`,
+		errorMessage: `Cursor provider runtime failed: ${sanitizeCursorProviderError(error, apiKey)}`,
 	};
 }
 
@@ -37,12 +39,11 @@ export function streamCursorLazy(
 	const outer = createAssistantMessageEventStream();
 	queueMicrotask(async () => {
 		try {
-			const { streamCursor } = await import("./cursor-provider.js");
 			for await (const event of streamCursor(model, context, options)) {
 				outer.push(event);
 			}
 		} catch (error) {
-			const message = makeProviderLoadErrorMessage(model, error);
+			const message = makeProviderRuntimeErrorMessage(model, error, options?.apiKey);
 			outer.push({ type: "error", reason: "error", error: message });
 			outer.end(message);
 		}

package/src/cursor-provider-live-run-drain.ts

@@ -383,6 +383,7 @@ export async function drainCursorLiveRunTurn(
 				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 					runtime: "local",
 					turn: cursorLiveRuns.takeSdkTurnUsage(run),
+					billed: run.billedTurnUsage,
 				});
 				if (run.resumeNotice) {
 					emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);

package/src/cursor-provider-run-finalizer.ts

@@ -186,6 +186,7 @@ export class CursorRunFinalizer {
 				applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
 					runtime: prepared.runtimeTarget,
 					turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
+					billed: prepared.runtime.billedTurnUsage,
 				});
 				if (prepared.meta.resumeNotice) emitDisplayOnlyTraceBlock(stream, partial, prepared.meta.resumeNotice);
 				if (displayOnlyTraceBlock) emitDisplayOnlyTraceBlock(stream, partial, displayOnlyTraceBlock);

package/src/cursor-provider-turn-finalize.ts

@@ -17,6 +17,7 @@ import {
 } from "./cursor-provider-run-outcome.js";
 import type { CursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { attachCursorSdkBilledTurnUsage } from "./cursor-sdk-billed-usage.js";
 
 export async function cacheSdkContextWindow(
 	agentId: string,
@@ -149,6 +150,16 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 		resolvedApiKey: params.resolvedApiKey,
 		optionsApiKey: params.optionsApiKey,
 	});
+	const billed = await attachCursorSdkBilledTurnUsage({
+		agent: params.prepared.agent,
+		agentId: params.run.agentId,
+		runtime: params.prepared.runtimeTarget,
+		runId: params.run.id,
+	});
+	params.prepared.runtime.billedTurnUsage = billed.turn;
+	if (params.prepared.runtime.liveRun) {
+		params.prepared.runtime.liveRun.billedTurnUsage = billed.turn;
+	}
 	let displayOnlyTraceBlock: string | undefined;
 	if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
 		let report: CursorCloudRunReport = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
@@ -158,6 +169,7 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 				run: params.run,
 				waitResult,
 				apiKey,
+				agentUsage: billed.agentUsage,
 			});
 		} catch (error) {
 			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);

package/src/cursor-provider-turn-types.ts

@@ -14,6 +14,7 @@ import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import type { CursorPrompt } from "./context.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
+import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
 
 export interface CursorProviderTurnRunnerParams {
 	model: Model<Api>;
@@ -44,6 +45,7 @@ export interface CursorProviderTurnSendMeta {
 
 interface CursorProviderTurnRuntimeBase {
 	turnCoordinator: CursorSdkTurnCoordinator;
+	billedTurnUsage?: CursorSdkTurnUsage;
 }
 
 /**

package/src/cursor-sdk-billed-usage.ts

@@ -0,0 +1,107 @@
+import type { SDKAgent } from "@cursor/sdk";
+import type { CursorRuntime } from "./cursor-config.js";
+import { asRecord, getArray, getString } from "./cursor-record-utils.js";
+import { readCursorSdkTurnUsage, type CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
+
+const BILLED_USAGE_TIMEOUT_MS = 5000;
+
+// ponytail: process-lifetime watermark of billed usage UUIDs per agentId; reset on process exit.
+// Upgrade to session-scoped storage if multi-day processes retain enough agent IDs to matter.
+const seenBilledRunIdsByAgent = new Map<string, Set<string>>();
+
+export function isCursorSdkClientMintedRunId(runId: string): boolean {
+	return runId.startsWith("run-");
+}
+
+export function sumCursorSdkTurnUsage(usages: readonly CursorSdkTurnUsage[]): CursorSdkTurnUsage | undefined {
+	if (usages.length === 0) return undefined;
+	return usages.reduce(
+		(total, usage) => ({
+			inputTokens: total.inputTokens + usage.inputTokens,
+			outputTokens: total.outputTokens + usage.outputTokens,
+			cacheReadTokens: total.cacheReadTokens + usage.cacheReadTokens,
+			cacheWriteTokens: total.cacheWriteTokens + usage.cacheWriteTokens,
+		}),
+	);
+}
+
+export function peekCursorBilledUsageRunIds(agentId: string): ReadonlySet<string> {
+	return seenBilledRunIdsByAgent.get(agentId) ?? new Set();
+}
+
+export function rememberCursorBilledUsageRunIds(agentId: string, runIds: readonly string[]): void {
+	if (runIds.length === 0) return;
+	let seen = seenBilledRunIdsByAgent.get(agentId);
+	if (!seen) {
+		seen = new Set();
+		seenBilledRunIdsByAgent.set(agentId, seen);
+	}
+	for (const runId of runIds) seen.add(runId);
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs = BILLED_USAGE_TIMEOUT_MS): Promise<T | undefined> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<undefined>((resolve) => {
+		timer = setTimeout(() => resolve(undefined), timeoutMs);
+		timer.unref?.();
+	});
+	return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+export function selectCursorBilledTurnUsage(
+	agentUsage: unknown,
+	options: { runtime: CursorRuntime; runId?: string; seenRunIds?: ReadonlySet<string> },
+): { turn?: CursorSdkTurnUsage; runIds: string[] } {
+	const runs = (getArray(asRecord(agentUsage), "runs") ?? []).flatMap((item) => {
+		const record = asRecord(item);
+		const runId = getString(record, "runId");
+		const usage = readCursorSdkTurnUsage(record?.usage);
+		return runId && usage ? [{ runId, usage }] : [];
+	});
+	if (options.runtime === "cloud" && options.runId) {
+		const match = runs.find((run) => run.runId === options.runId);
+		return match ? { turn: match.usage, runIds: [match.runId] } : { runIds: [] };
+	}
+	const unseen = runs.filter((run) => !options.seenRunIds?.has(run.runId));
+	return { turn: sumCursorSdkTurnUsage(unseen.map((run) => run.usage)), runIds: unseen.map((run) => run.runId) };
+}
+
+export async function fetchCursorSdkAgentUsage(
+	agent: SDKAgent,
+	options: { runtime: CursorRuntime; runId?: string },
+): Promise<unknown | undefined> {
+	if (typeof agent.getUsage !== "function") return undefined;
+	const query =
+		options.runtime === "cloud" && options.runId && isCursorSdkClientMintedRunId(options.runId)
+			? { runId: options.runId }
+			: undefined;
+	return withTimeout(Promise.resolve(agent.getUsage(query)));
+}
+
+export async function attachCursorSdkBilledTurnUsage(options: {
+	agent: SDKAgent;
+	agentId: string;
+	runtime: CursorRuntime;
+	runId?: string;
+}): Promise<{ agentUsage?: unknown; turn?: CursorSdkTurnUsage }> {
+	const agentUsage = await fetchCursorSdkAgentUsage(options.agent, {
+		runtime: options.runtime,
+		runId: options.runId,
+	});
+	if (!agentUsage) return {};
+	const selected = selectCursorBilledTurnUsage(agentUsage, {
+		runtime: options.runtime,
+		runId: options.runtime === "cloud" ? options.runId : undefined,
+		seenRunIds: peekCursorBilledUsageRunIds(options.agentId),
+	});
+	rememberCursorBilledUsageRunIds(options.agentId, selected.runIds);
+	return { agentUsage, turn: selected.turn };
+}
+
+export const __testUtils = {
+	reset(): void {
+		seenBilledRunIdsByAgent.clear();
+	},
+};

package/src/cursor-sdk-process-error-guard.ts

@@ -75,10 +75,12 @@ function isCursorSdkAbortError(error: unknown): boolean {
 // The exact observed incident: the Cursor SDK 1.0.23 local shell executor writes a
 // spawned child's stdin without a stream 'error' listener, so a child exiting while
 // a write is in flight surfaces a raw `write EPIPE` uncaught exception whose stack
-// is exactly the single async pipe-write completion frame. Pi's own piped-stdout or
-// dead-terminal EPIPE normally surfaces through the synchronous write-dispatch path
-// with multiple frames (afterWriteDispatched/Socket._writeGeneric) and must stay
-// fatal per Unix convention, so anything beyond this one-frame contract is rejected.
+// is exactly the single async pipe-write completion frame. Installed 1.0.27 attaches
+// a no-op `error` listener before that write; keep this guard as defense in depth.
+// Pi's own piped-stdout or dead-terminal EPIPE normally surfaces through the
+// synchronous write-dispatch path with multiple frames (afterWriteDispatched /
+// Socket._writeGeneric) and must stay fatal per Unix convention, so anything beyond
+// this one-frame contract is rejected.
 const OBSERVED_CLOSED_PIPE_STACK_FRAME =
 	/^\s+at WriteWrap\.onWriteComplete \[as oncomplete\] \(node:internal\/stream_base_commons:\d+:\d+\)$/;
 

package/src/cursor-session-agent-lifecycle.ts

@@ -7,6 +7,11 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { clearCursorSdkHttp1 } from "./cursor-http1.js";
 import { onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import {
+	disposeSessionCursorAgent,
+	invalidateSessionAgent,
+	resetSessionCursorAgent,
+} from "./cursor-session-agent.js";
 
 export interface CursorSessionAgentLifecycleExtensionApi {
 	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
@@ -18,11 +23,9 @@ export interface CursorSessionAgentLifecycleExtensionApi {
 
 export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
 	onCursorSessionScopeKeyChange(async (previousScopeKey) => {
-		const { disposeSessionCursorAgent } = await import("./cursor-session-agent.js");
 		await disposeSessionCursorAgent(previousScopeKey);
 	});
 	pi.on("session_shutdown", async (event) => {
-		const { disposeSessionCursorAgent, resetSessionCursorAgent } = await import("./cursor-session-agent.js");
 		try {
 			if (event.reason === "reload") {
 				await resetSessionCursorAgent();
@@ -33,20 +36,16 @@ export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecy
 			clearCursorSdkHttp1();
 		}
 	});
-	pi.on("session_compact", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("session_compact", () => {
 		invalidateSessionAgent();
 	});
-	pi.on("session_before_tree", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("session_before_tree", () => {
 		invalidateSessionAgent();
 	});
 	pi.on("session_tree", async () => {
-		const { resetSessionCursorAgent } = await import("./cursor-session-agent.js");
 		await resetSessionCursorAgent();
 	});
-	pi.on("model_select", async () => {
-		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+	pi.on("model_select", () => {
 		invalidateSessionAgent();
 	});
 }

package/src/cursor-session-agent-resume.ts

@@ -81,6 +81,19 @@ const state: CursorSessionResumeState = {
 	unownedUserEntryIds: new Set(),
 };
 
+// Compaction summarizer sends commit a one-message resume handle. Drop it so the
+// next normal turn_end cannot persist that lineage (#223).
+let resumeHandlePersistSuppressed = false;
+
+export function suppressCursorSessionAgentResumeHandlePersist(): void {
+	resumeHandlePersistSuppressed = true;
+	state.pendingHandle = undefined;
+}
+
+export function allowCursorSessionAgentResumeHandlePersist(): void {
+	resumeHandlePersistSuppressed = false;
+}
+
 function hashParts(parts: readonly string[]): string {
 	const hash = createHash("sha256");
 	for (const part of parts) {
@@ -360,6 +373,7 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey: string): Curs
 }
 
 export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle): void {
+	if (resumeHandlePersistSuppressed) return;
 	if (!isCursorLocalAgentId(input.agentId)) return;
 	state.pendingHandle = {
 		runtime: input.runtime,
@@ -371,6 +385,11 @@ export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessio
 }
 
 function flushPendingCursorSessionAgentResumeHandle(branch: readonly SessionEntry[]): void {
+	if (resumeHandlePersistSuppressed) {
+		state.pendingHandle = undefined;
+		restoreFromBranch(branch);
+		return;
+	}
 	restoreFromBranch(branch);
 	const pending = state.pendingHandle;
 	state.pendingHandle = undefined;
@@ -442,6 +461,8 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		restoreFromSessionManager(ctx.sessionManager);
 	});
 	pi.on("session_compact", (event, ctx) => {
+		state.pendingHandle = undefined;
+		resumeHandlePersistSuppressed = false;
 		const branch = ctx.sessionManager.getBranch();
 		if (branch.length > 0) {
 			restoreFromSessionManager(ctx.sessionManager);
@@ -471,6 +492,7 @@ function resetStateForTests(): void {
 	state.lastBranchHandle = undefined;
 	state.pendingHandle = undefined;
 	state.unownedUserEntryIds = new Set();
+	resumeHandlePersistSuppressed = false;
 }
 
 export const __testUtils = {
@@ -479,4 +501,5 @@ export const __testUtils = {
 	reset: resetStateForTests,
 	set: setStateForTests,
 	state,
+	isResumeHandlePersistSuppressed: () => resumeHandlePersistSuppressed,
 };

package/src/cursor-session-compaction-prep.ts

@@ -1,15 +1,19 @@
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
+import { suppressCursorSessionAgentResumeHandlePersist } from "./cursor-session-agent-resume.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 
 /**
  * Prepare the pooled Cursor session agent for pi compaction summarization.
  * Releases any scoped live-run drain state still tied to the pooled agent, then
  * disposes the pool entry so summarization acquires a clean SDK agent.
+ * Suppresses local-resume handle persist so the summarizer send cannot leak
+ * a one-message handle into the next normal turn (#223).
  */
 export async function prepareCursorSessionForCompaction(
 	scopeKey: string = getCursorSessionScopeKey(),
 ): Promise<void> {
+	suppressCursorSessionAgentResumeHandlePersist();
 	while (true) {
 		const run = cursorLiveRuns.getActiveForScope(scopeKey);
 		if (!run || run.disposed) break;

package/src/cursor-tool-manifest.ts

@@ -4,7 +4,7 @@ import type { CursorPiToolBridgeSnapshot } from "./cursor-pi-tool-bridge-types.j
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 
 /**
- * Representative @cursor/sdk@1.0.23 local-agent ToolType values; actual exposure can vary by run.
+ * Representative @cursor/sdk@1.0.27 local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY =

package/src/cursor-usage-accounting.ts

@@ -91,18 +91,30 @@ function getCursorSdkUncachedInputTokens(turnUsage: CursorSdkTurnUsage): number
 	return turnUsage.inputTokens - turnUsage.cacheReadTokens - turnUsage.cacheWriteTokens;
 }
 
-export function isCursorSdkUsageSafeForPiMessage(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
+export function isCursorSdkUsagePartitionSafe(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
 	const counts = [turnUsage.inputTokens, turnUsage.outputTokens, turnUsage.cacheReadTokens, turnUsage.cacheWriteTokens];
 	const uncachedInput = getCursorSdkUncachedInputTokens(turnUsage);
 	return (
 		counts.every((count) => Number.isFinite(count) && count >= 0) &&
 		Number.isFinite(uncachedInput) &&
 		uncachedInput >= 0 &&
-		turnUsage.outputTokens <= model.maxTokens &&
+		turnUsage.outputTokens <= model.maxTokens
+	);
+}
+
+export function isCursorSdkUsageSafeForPiMessage(turnUsage: CursorSdkTurnUsage, model: Model<Api>): boolean {
+	return (
+		isCursorSdkUsagePartitionSafe(turnUsage, model) &&
 		turnUsage.inputTokens + turnUsage.outputTokens <= model.contextWindow
 	);
 }
 
+export interface CursorSdkUsageApplyOptions {
+	runtime: CursorRuntime;
+	turn?: CursorSdkTurnUsage;
+	billed?: CursorSdkTurnUsage;
+}
+
 export function applyCursorSdkUsage(partial: AssistantMessage, turnUsage: CursorSdkTurnUsage): void {
 	// Pi treats input/cacheRead/cacheWrite as disjoint additive prompt components.
 	partial.usage.input = getCursorSdkUncachedInputTokens(turnUsage);
@@ -117,8 +129,23 @@ function isCompatibleCursorAssistantMeasurement(assistant: AssistantMessage, mod
 	return assistant.api === model.api && assistant.provider === model.provider && assistant.model === model.id;
 }
 
+function getLatestCompactionBoundary(context: Context): { index: number; tokensBefore?: number } | undefined {
+	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+		const message = context.messages[index] as { role?: string; tokensBefore?: number };
+		if (message.role !== "compactionSummary") continue;
+		const tokensBefore = message.tokensBefore;
+		return {
+			index,
+			tokensBefore: Number.isFinite(tokensBefore) && tokensBefore !== undefined && tokensBefore > 0 ? Math.floor(tokensBefore) : undefined,
+		};
+	}
+	return undefined;
+}
+
 function getLastAcceptedContextOccupancy(context: Context, model: Model<Api>): number {
+	const boundary = getLatestCompactionBoundary(context);
 	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+		if (boundary && index < boundary.index) break;
 		const message = context.messages[index];
 		if (message.role !== "assistant" || !("usage" in message)) continue;
 		const assistant = message as AssistantMessage;
@@ -127,7 +154,9 @@ function getLastAcceptedContextOccupancy(context: Context, model: Model<Api>): n
 		const { usage } = assistant;
 		const total =
 			usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-		if (Number.isFinite(total) && total > 0 && total <= model.contextWindow) return total;
+		if (!Number.isFinite(total) || total <= 0 || total > model.contextWindow) continue;
+		if (boundary?.tokensBefore !== undefined && total >= boundary.tokensBefore) continue;
+		return total;
 	}
 	return 0;
 }
@@ -146,18 +175,50 @@ export function applyCursorApproximateUsage(partial: AssistantMessage, model: Mo
 	);
 }
 
+function applyCursorOccupancyEstimate(partial: AssistantMessage, model: Model<Api>, context: Context): void {
+	partial.usage.totalTokens = Math.max(
+		estimateCursorContextTotalTokens(partial, model, context),
+		getLastAcceptedContextOccupancy(context, model),
+	);
+}
+
+function isCurrentLocalOccupancy(turn: CursorSdkTurnUsage, model: Model<Api>, context: Context): boolean {
+	if (!isCursorSdkUsageSafeForPiMessage(turn, model)) return false;
+	const tokensBefore = getLatestCompactionBoundary(context)?.tokensBefore;
+	return tokensBefore === undefined || turn.inputTokens + turn.outputTokens < tokensBefore;
+}
+
+function applyResolvedCursorOccupancy(
+	partial: AssistantMessage,
+	model: Model<Api>,
+	context: Context,
+	localTurn: CursorSdkTurnUsage | undefined,
+): void {
+	if (localTurn && isCurrentLocalOccupancy(localTurn, model, context)) {
+		partial.usage.totalTokens = localTurn.inputTokens + localTurn.outputTokens;
+		return;
+	}
+	applyCursorOccupancyEstimate(partial, model, context);
+}
+
 export function applyCursorUsage(
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
 	sessionInputTokens: number,
-	sdkUsage?: { runtime: CursorRuntime; turn?: CursorSdkTurnUsage },
+	sdkUsage?: CursorSdkUsageApplyOptions,
 ): void {
-	// Only local raw turn-ended usage has a captured full-prompt/cache-partition contract.
-	// Cloud raw usage remains display-only until its field semantics are independently observed.
-	const usage = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
-	if (usage && isCursorSdkUsageSafeForPiMessage(usage, model)) {
-		applyCursorSdkUsage(partial, usage);
+	const billed = sdkUsage?.billed;
+	const localTurn = sdkUsage?.runtime === "local" ? sdkUsage.turn : undefined;
+	if (billed && isCursorSdkUsagePartitionSafe(billed, model)) {
+		applyCursorSdkUsage(partial, billed);
+		applyResolvedCursorOccupancy(partial, model, context, localTurn);
+		return;
+	}
+	// Only local raw turn-ended usage has a captured full-prompt/cache-partition occupancy contract.
+	if (localTurn && isCursorSdkUsageSafeForPiMessage(localTurn, model)) {
+		applyCursorSdkUsage(partial, localTurn);
+		applyResolvedCursorOccupancy(partial, model, context, localTurn);
 		return;
 	}
 	applyCursorApproximateUsage(partial, model, context, sessionInputTokens);

package/src/index.ts

@@ -15,6 +15,7 @@ import { registerCursorFallbackIssueWarning } from "./cursor-fallback-warning.js
 import { registerCursorAgentsContextDedup } from "./cursor-agents-context-registration.js";
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
+import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
 
 type CursorExtensionApi =
 	& Pick<ExtensionAPI, "registerProvider" | "registerCommand" | "on">
@@ -54,7 +55,6 @@ export default async function (pi: CursorExtensionApi) {
 	registerCursorSessionAgentLifecycle(pi);
 	registerCursorSessionAgentResume(pi);
 	pi.on("session_before_compact", async () => {
-		const { prepareCursorSessionForCompaction } = await import("./cursor-session-compaction-prep.js");
 		await prepareCursorSessionForCompaction();
 	});
 	registerCursorRuntimeControls(pi);

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"declaration": false,
+		"sourceMap": false
+	}
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "noEmit": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}