pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-state.ts

@@ -24,10 +24,12 @@ import {
 	DEFAULT_CURSOR_SETTING_SOURCES,
 	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
 import { asRecord } from "./cursor-record-utils.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { cursorSettingsScopeForContext, getCursorSessionSettings, registerCursorSessionSettings, resetCursorSessionSettingsForTests } from "./cursor-session-settings.js";
 import { refreshSessionCursorAgentConfig } from "./cursor-session-agent.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 import {
@@ -36,6 +38,7 @@ import {
 	loadCursorSdkUserConfig,
 	mergeCursorSdkConfigForUpdate,
 	resolveCursorFastDefault,
+	resolveCursorLocalStoreRoot,
 	updateCursorSdkConfig,
 } from "./cursor-config.js";
 import {
@@ -58,6 +61,8 @@ export {
 	getCursorSessionConfig,
 } from "./cursor-runtime-state.js";
 
+export const CURSOR_FOOTER_ENV = "PI_CURSOR_FOOTER";
+
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const MODE_ENTRY_TYPE = "cursor-mode-state";
 
@@ -80,18 +85,8 @@ type CursorRuntimeControlsExtensionApi = Pick<
 	"appendEntry" | "getFlag" | "registerFlag" | "registerCommand" | "on" | "getActiveTools" | "getAllTools"
 > & CursorRuntimeStateExtensionApi;
 
-type CursorCliModeState =
-	| { kind: "unset" }
-	| { kind: "valid"; mode: AgentModeOption }
-	| { kind: "invalid"; raw: string; message: string };
-
-const sessionFastPreferences = new Map<string, boolean>();
 const authoritativeGlobalFastPreferenceIds = new Set<string>();
 let globalFastPreferences = new Map<string, boolean>();
-let cliForceFast = false;
-let cliForceNoFast = false;
-let sessionCursorAgentMode: AgentModeOption | undefined;
-let cliCursorModeState: CursorCliModeState = { kind: "unset" };
 const invalidCursorModeNotifiedSessionScopeKeys = new Set<string>();
 
 export function isCursorAgentMode(value: unknown): value is AgentModeOption {
@@ -152,7 +147,8 @@ function saveGlobalCursorHttp1Enabled(enabled: boolean): void {
 	);
 }
 
-function restoreSessionFastPreferences(branch: readonly SessionEntry[]): void {
+function restoreSessionFastPreferences(branch: readonly SessionEntry[], scopeKey?: string): void {
+	const sessionFastPreferences = getCursorSessionSettings(scopeKey).fast;
 	sessionFastPreferences.clear();
 	for (const entry of branch) {
 		if (entry.type !== "custom" || entry.customType !== FAST_ENTRY_TYPE) continue;
@@ -163,30 +159,32 @@ function restoreSessionFastPreferences(branch: readonly SessionEntry[]): void {
 	}
 }
 
-function restoreSessionCursorMode(branch: readonly SessionEntry[]): void {
-	sessionCursorAgentMode = undefined;
+function restoreSessionCursorMode(branch: readonly SessionEntry[], scopeKey?: string): void {
+	const state = getCursorSessionSettings(scopeKey);
+	state.mode = undefined;
 	for (const entry of branch) {
 		if (entry.type !== "custom" || entry.customType !== MODE_ENTRY_TYPE) continue;
 		if (isCursorModeEntryData(entry.data)) {
-			sessionCursorAgentMode = entry.data.mode;
+			state.mode = entry.data.mode;
 		}
 	}
 }
 
-function restoreSessionCursorPreferences(ctx: { sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch"> }): void {
+function restoreSessionCursorPreferences(ctx: Pick<ExtensionContext, "sessionManager">): void {
 	const branch = ctx.sessionManager.getBranch();
-	restoreSessionCursorRuntimeState(branch);
-	restoreSessionFastPreferences(branch);
-	restoreSessionCursorMode(branch);
-	restoreSessionCursorHttp1(branch);
+	const scopeKey = cursorSettingsScopeForContext(ctx);
+	restoreSessionCursorRuntimeState(branch, scopeKey);
+	restoreSessionFastPreferences(branch, scopeKey);
+	restoreSessionCursorMode(branch, scopeKey);
+	restoreSessionCursorHttp1(branch, scopeKey);
 }
 
-function restoreSessionCursorHttp1(branch: readonly SessionEntry[]): void {
-	setStoredCursorHttp1Enabled(undefined);
+function restoreSessionCursorHttp1(branch: readonly SessionEntry[], scopeKey?: string): void {
+	setStoredCursorHttp1Enabled(undefined, scopeKey);
 	for (const entry of branch) {
 		if (entry.type !== "custom" || entry.customType !== CURSOR_HTTP1_ENTRY_TYPE) continue;
 		if (isCursorHttp1EntryData(entry.data)) {
-			setStoredCursorHttp1Enabled(entry.data.enabled);
+			setStoredCursorHttp1Enabled(entry.data.enabled, scopeKey);
 		}
 	}
 }
@@ -207,7 +205,8 @@ function getMapFastPreference(
 	return map.get(preferenceModelId) ?? (preferenceModelId !== metadata.baseModelId ? map.get(metadata.baseModelId) : undefined);
 }
 
-function getEffectiveFast(modelId: string): boolean | undefined {
+function getEffectiveFast(modelId: string, scopeKey?: string): boolean | undefined {
+	const { forceNoFast: cliForceNoFast, forceFast: cliForceFast } = getCursorSessionSettings(scopeKey).cli;
 	const metadata = getCursorModelMetadata(modelId);
 	if (!metadata?.supportsFast) return undefined;
 	return resolveCursorFastDefault({
@@ -216,7 +215,7 @@ function getEffectiveFast(modelId: string): boolean | undefined {
 		aliasOverride: metadata.fastOverride,
 		sessionValue: authoritativeGlobalFastPreferenceIds.has(getFastPreferenceModelId(metadata))
 			? undefined
-			: getMapFastPreference(sessionFastPreferences, metadata),
+			: getMapFastPreference(getCursorSessionSettings(scopeKey).fast, metadata),
 		userValue: getMapFastPreference(globalFastPreferences, metadata),
 		modelDefault: metadata.defaultFast,
 	}).value;
@@ -230,44 +229,45 @@ export type CursorAgentModeResolution =
 	| { kind: "valid"; mode: AgentModeOption }
 	| { kind: "invalid"; raw: string; message: string };
 
-export function getStoredCursorAgentMode(): AgentModeOption {
-	return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+export function getStoredCursorAgentMode(scopeKey?: string): AgentModeOption {
+	return getCursorSessionSettings(scopeKey).mode ?? DEFAULT_CURSOR_AGENT_MODE;
 }
 
-export function resolveCursorAgentMode(): CursorAgentModeResolution {
+export function resolveCursorAgentMode(scopeKey?: string): CursorAgentModeResolution {
+	const cliCursorModeState = getCursorSessionSettings(scopeKey).cli.mode;
 	switch (cliCursorModeState.kind) {
 		case "valid":
 			return { kind: "valid", mode: cliCursorModeState.mode };
 		case "invalid":
 			return { kind: "invalid", raw: cliCursorModeState.raw, message: cliCursorModeState.message };
 		case "unset":
-			return { kind: "valid", mode: getStoredCursorAgentMode() };
+			return { kind: "valid", mode: getStoredCursorAgentMode(scopeKey) };
 	}
 }
 
-export function getCursorProviderAgentModeOrThrow(): AgentModeOption {
-	const resolution = resolveCursorAgentMode();
+export function getCursorProviderAgentModeOrThrow(scopeKey?: string): AgentModeOption {
+	const resolution = resolveCursorAgentMode(scopeKey);
 	if (resolution.kind === "invalid") throw new Error(resolution.message);
 	return resolution.mode;
 }
 
-type CursorStatusContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "isProjectTrusted">>;
+type CursorStatusContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "isProjectTrusted" | "sessionManager">>;
 
 function updateCursorStatus(ctx: CursorStatusContext & Pick<ExtensionContext, "model" | "ui">, model = ctx.model): void {
-	if (!model || !isCursorModel(model)) {
+	if (!model || !isCursorModel(model) || !parseEnvBoolean(process.env[CURSOR_FOOTER_ENV], true)) {
 		ctx.ui.setStatus("cursor", undefined);
 		return;
 	}
 	const metadata = getCursorModelMetadata(model.id);
 	const resolution = resolveCursorStatusRuntime(ctx);
-	const modeResolution = resolveCursorAgentMode();
+	const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
 	const mode = modeResolution.kind === "invalid" ? "invalid" : modeResolution.mode;
 	if (resolution.kind === "invalid") {
 		ctx.ui.setStatus("cursor", formatCursorStatus("invalid", undefined, mode));
 		return;
 	}
 	const runtime = resolution.runtime.value;
-	const fast = runtime === "cloud" ? undefined : metadata?.supportsFast ? getEffectiveFast(model.id) : undefined;
+	const fast = runtime === "cloud" ? undefined : metadata?.supportsFast ? getEffectiveFast(model.id, cursorSettingsScopeForContext(ctx)) : undefined;
 	ctx.ui.setStatus(
 		"cursor",
 		formatCursorStatus(runtime, fast, mode, resolution.useHttp1ForAgent.value),
@@ -292,7 +292,9 @@ function persistFastPreference(
 	pi: Pick<ExtensionAPI, "appendEntry">,
 	modelId: string,
 	fast: boolean,
+	scopeKey: string | undefined,
 ): unknown | undefined {
+	const sessionFastPreferences = getCursorSessionSettings(scopeKey).fast;
 	const previousSession = sessionFastPreferences.get(modelId);
 	const previousGlobal = globalFastPreferences.get(modelId);
 	sessionFastPreferences.set(modelId, fast);
@@ -314,13 +316,14 @@ function persistFastPreference(
 	}
 }
 
-function persistCursorModePreference(pi: Pick<ExtensionAPI, "appendEntry">, mode: AgentModeOption): void {
-	const previousMode = sessionCursorAgentMode;
-	sessionCursorAgentMode = mode;
+function persistCursorModePreference(pi: Pick<ExtensionAPI, "appendEntry">, mode: AgentModeOption, scopeKey: string | undefined): void {
+	const state = getCursorSessionSettings(scopeKey);
+	const previousMode = state.mode;
+	state.mode = mode;
 	try {
 		pi.appendEntry<CursorModeEntryData>(MODE_ENTRY_TYPE, { mode });
 	} catch (error) {
-		sessionCursorAgentMode = previousMode;
+		state.mode = previousMode;
 		throw error;
 	}
 }
@@ -328,13 +331,14 @@ function persistCursorModePreference(pi: Pick<ExtensionAPI, "appendEntry">, mode
 function persistCursorHttp1Preference(
 	pi: Pick<ExtensionAPI, "appendEntry">,
 	enabled: boolean,
+	scopeKey: string | undefined,
 ): unknown | undefined {
-	const previousSession = getStoredCursorHttp1Enabled();
-	setStoredCursorHttp1Enabled(enabled);
+	const previousSession = getStoredCursorHttp1Enabled(scopeKey);
+	setStoredCursorHttp1Enabled(enabled, scopeKey);
 	try {
 		saveGlobalCursorHttp1Enabled(enabled);
 	} catch (error) {
-		setStoredCursorHttp1Enabled(previousSession);
+		setStoredCursorHttp1Enabled(previousSession, scopeKey);
 		throw error;
 	}
 	try {
@@ -347,23 +351,24 @@ function persistCursorHttp1Preference(
 	}
 }
 
-function restoreCliCursorMode(raw: boolean | string | undefined): void {
-	cliCursorModeState = { kind: "unset" };
+function restoreCliCursorMode(raw: boolean | string | undefined, scopeKey?: string): void {
+	const cli = getCursorSessionSettings(scopeKey).cli;
+	cli.mode = { kind: "unset" };
 	if (raw === undefined || raw === "" || raw === false) return;
 	const parsed = parseCursorAgentMode(raw);
 	if (parsed) {
-		cliCursorModeState = { kind: "valid", mode: parsed };
+		cli.mode = { kind: "valid", mode: parsed };
 		return;
 	}
 	const rawText = String(raw);
 	const message = formatInvalidCursorMode(rawText);
-	cliCursorModeState = { kind: "invalid", raw: rawText, message };
+	cli.mode = { kind: "invalid", raw: rawText, message };
 }
 
-function notifyInvalidCursorModeIfCursorActive(ctx: Pick<ExtensionContext, "hasUI" | "mode" | "ui">): void {
-	const modeResolution = resolveCursorAgentMode();
+function notifyInvalidCursorModeIfCursorActive(ctx: Pick<ExtensionContext, "hasUI" | "mode" | "ui" | "sessionManager">): void {
+	const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
 	if (modeResolution.kind !== "invalid" || !ctx.hasUI || ctx.mode !== "tui") return;
-	const scopeKey = getCursorSessionScopeKey();
+	const scopeKey = cursorSettingsScopeForContext(ctx) ?? getCursorSessionScopeKey();
 	if (invalidCursorModeNotifiedSessionScopeKeys.has(scopeKey)) return;
 	invalidCursorModeNotifiedSessionScopeKeys.add(scopeKey);
 	ctx.ui.notify(modeResolution.message, "error");
@@ -414,11 +419,12 @@ function emitCursorToolsDebugReport(
 	console.log(report);
 }
 
-export function getEffectiveFastForModelId(modelId: string): boolean | undefined {
-	return getEffectiveFast(modelId);
+export function getEffectiveFastForModelId(modelId: string, scopeKey?: string): boolean | undefined {
+	return getEffectiveFast(modelId, scopeKey);
 }
 
 export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtensionApi): void {
+	registerCursorSessionSettings(pi);
 	registerCursorCloudRuntimeControls(pi, { refreshStatus: updateCursorStatus });
 
 	pi.registerFlag("cursor-fast", {
@@ -448,6 +454,7 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				ctx.ui.notify(`Fast mode not supported by ${modelName}`, "info");
 				return;
 			}
+			const { forceNoFast: cliForceNoFast, forceFast: cliForceFast } = getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).cli;
 			if (cliForceNoFast) {
 				ctx.ui.notify("Cursor fast is forced off by --cursor-no-fast", "info");
 				return;
@@ -466,11 +473,11 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			}
 
 			const preferenceModelId = getFastPreferenceModelId(metadata);
-			const current = getEffectiveFast(metadata.piModelId) ?? false;
+			const current = getEffectiveFast(metadata.piModelId, cursorSettingsScopeForContext(ctx)) ?? false;
 			const next = !current;
 			let appendError: unknown;
 			try {
-				appendError = persistFastPreference(pi, preferenceModelId, next);
+				appendError = persistFastPreference(pi, preferenceModelId, next, cursorSettingsScopeForContext(ctx));
 			} catch (error) {
 				updateCursorStatus(ctx);
 				ctx.ui.notify(`Failed to save Cursor fast preference: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -529,7 +536,7 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			}
 			let appendError: unknown;
 			try {
-				appendError = persistCursorHttp1Preference(pi, next);
+				appendError = persistCursorHttp1Preference(pi, next, cursorSettingsScopeForContext(ctx));
 			} catch (error) {
 				updateCursorStatus(ctx);
 				ctx.ui.notify(
@@ -556,7 +563,8 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 	pi.registerCommand("cursor-local-resume-cleanup", {
 		description: "Dry-run or delete recorded superseded local Cursor SDK agents",
 		handler: async (args, ctx) => {
-			await runCursorSessionAgentCleanupCommand(pi, args, ctx);
+			const storeRoot = resolveCursorLocalStoreRoot({ user: loadCursorSdkUserConfig() }).value;
+			await runCursorSessionAgentCleanupCommand(pi, args, ctx, storeRoot);
 		},
 	});
 
@@ -568,7 +576,7 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				return;
 			}
 			try {
-				const result = await refreshSessionCursorAgentConfig();
+				const result = await refreshSessionCursorAgentConfig(getCursorSessionScopeSnapshot(pi).scopeKey);
 				const messages: Record<typeof result, string> = {
 					reloaded: "Cursor SDK agent config refreshed.",
 					"no-agent": "No Cursor SDK agent exists yet; config will load on the next Cursor run.",
@@ -588,7 +596,7 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			const usage = "Usage: /cursor-mode agent|plan";
 			const mode = parseCursorAgentMode(args);
 			if (!args.trim()) {
-				const modeResolution = resolveCursorAgentMode();
+				const modeResolution = resolveCursorAgentMode(cursorSettingsScopeForContext(ctx));
 				if (modeResolution.kind === "invalid") {
 					ctx.ui.notify(`${modeResolution.message} ${usage}`, "error");
 				} else {
@@ -600,14 +608,16 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				ctx.ui.notify(`Invalid Cursor mode "${args.trim()}". ${usage}`, "error");
 				return;
 			}
+			const cli = getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).cli;
+			const cliCursorModeState = cli.mode;
 			if (cliCursorModeState.kind === "valid") {
 				ctx.ui.notify(`Cursor mode is forced to ${cliCursorModeState.mode} by --cursor-mode`, "info");
 				return;
 			}
 			const clearedInvalidCliMode = cliCursorModeState.kind === "invalid";
 			try {
-				persistCursorModePreference(pi, mode);
-				if (clearedInvalidCliMode) cliCursorModeState = { kind: "unset" };
+				persistCursorModePreference(pi, mode, cursorSettingsScopeForContext(ctx));
+				if (clearedInvalidCliMode) cli.mode = { kind: "unset" };
 			} catch (error) {
 				updateCursorStatus(ctx);
 				ctx.ui.notify(`Failed to save Cursor mode preference: ${error instanceof Error ? error.message : String(error)}`, "error");
@@ -633,11 +643,13 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			authoritativeGlobalFastPreferenceIds.clear();
 			setCursorHttp1GlobalPreferenceAuthoritative(false);
 			globalFastPreferences = loadGlobalFastPreferences();
-			cliForceFast = pi.getFlag("cursor-fast") === true;
-			cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
-			restoreCursorCliState(pi);
+			const scopeKey = cursorSettingsScopeForContext(ctx);
+			const cli = getCursorSessionSettings(scopeKey).cli;
+			cli.forceFast = pi.getFlag("cursor-fast") === true;
+			cli.forceNoFast = pi.getFlag("cursor-no-fast") === true;
+			restoreCursorCliState(pi, scopeKey);
 			restoreSessionCursorPreferences(ctx);
-			restoreCliCursorMode(pi.getFlag("cursor-mode"));
+			restoreCliCursorMode(pi.getFlag("cursor-mode"), scopeKey);
 		},
 		sync: (ctx) => {
 			if (isCursorModel(ctx.model)) notifyInvalidCursorModeIfCursorActive(ctx);
@@ -647,10 +659,10 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 }
 
 function resetCursorModeStateForTests(): void {
-	sessionCursorAgentMode = undefined;
+	resetCursorSessionSettingsForTests();
 	setCursorHttp1GlobalPreferenceAuthoritative(false);
 	setStoredCursorHttp1Enabled(undefined);
-	cliCursorModeState = { kind: "unset" };
+	getCursorSessionSettings().cli.mode = { kind: "unset" };
 	resetCursorRuntimeStateForTests();
 	invalidCursorModeNotifiedSessionScopeKeys.clear();
 	authoritativeGlobalFastPreferenceIds.clear();
@@ -664,9 +676,9 @@ export const __testUtils = {
 	DEFAULT_CURSOR_AGENT_MODE,
 	getConfigPath,
 	loadGlobalFastPreferences,
-	sessionFastPreferences,
-	getSessionCursorAgentMode: () => sessionCursorAgentMode,
-	getCliCursorAgentMode: () => (cliCursorModeState.kind === "valid" ? cliCursorModeState.mode : undefined),
-	getCliCursorModeState: () => cliCursorModeState,
+	get sessionFastPreferences() { return getCursorSessionSettings().fast; },
+	getSessionCursorAgentMode: () => getCursorSessionSettings().mode,
+	getCliCursorAgentMode: () => { const mode = getCursorSessionSettings().cli.mode; return mode.kind === "valid" ? mode.mode : undefined; },
+	getCliCursorModeState: () => getCursorSessionSettings().cli.mode,
 	resetCursorModeStateForTests,
 };

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.32 local-agent ToolType values; actual exposure can vary by run.
+ * Representative Cursor SDK 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

@@ -1,3 +1,4 @@
+import { calculateCost } from "@earendil-works/pi-ai";
 import type { Api, AssistantMessage, Context, Model } from "@earendil-works/pi-ai";
 import {
 	CURSOR_APPROX_CHARS_PER_TOKEN,
@@ -112,7 +113,7 @@ export function isCursorSdkUsageSafeForPiMessage(turnUsage: CursorSdkTurnUsage,
 export interface CursorSdkUsageApplyOptions {
 	runtime: CursorRuntime;
 	turn?: CursorSdkTurnUsage;
-	billed?: CursorSdkTurnUsage;
+	occupancyFloor?: number;
 }
 
 export function applyCursorSdkUsage(partial: AssistantMessage, turnUsage: CursorSdkTurnUsage): void {
@@ -121,84 +122,24 @@ export function applyCursorSdkUsage(partial: AssistantMessage, turnUsage: Cursor
 	partial.usage.output = turnUsage.outputTokens;
 	partial.usage.cacheRead = turnUsage.cacheReadTokens;
 	partial.usage.cacheWrite = turnUsage.cacheWriteTokens;
-	// totalTokens is context occupancy (full prompt + output), not the sum of spend components alone.
+	// Full prompt + output equals the sum of Pi's disjoint components.
 	partial.usage.totalTokens = turnUsage.inputTokens + turnUsage.outputTokens;
 }
 
-function isCompatibleCursorAssistantMeasurement(assistant: AssistantMessage, model: Model<Api>): boolean {
-	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;
-		if (assistant.stopReason === "aborted" || assistant.stopReason === "error" || !assistant.usage) continue;
-		if (!isCompatibleCursorAssistantMeasurement(assistant, model)) continue;
-		const { usage } = assistant;
-		const total =
-			usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
-		if (!Number.isFinite(total) || total <= 0 || total > model.contextWindow) continue;
-		if (boundary?.tokensBefore !== undefined && total >= boundary.tokensBefore) continue;
-		return total;
-	}
-	return 0;
-}
-
-export function applyCursorApproximateUsage(partial: AssistantMessage, model: Model<Api>, context: Context, sessionInputTokens: number): void {
+export function applyCursorApproximateUsage(partial: AssistantMessage, model: Model<Api>, context: Context, sessionInputTokens: number, occupancyFloor?: number): void {
 	const outputTokens = estimateCursorAssistantSessionOutputTokens(partial);
-	partial.usage.input = Math.max(0, sessionInputTokens);
+	const floor = occupancyFloor !== undefined && Number.isFinite(occupancyFloor) && occupancyFloor > 0 && occupancyFloor <= model.contextWindow ? occupancyFloor : 0;
+	const totalTokens = Math.max(
+		Math.max(0, sessionInputTokens) + outputTokens,
+		estimateCursorContextTotalTokens(partial, model, context),
+		floor,
+	);
+	// Estimated prompt components describe the same occupancy as totalTokens.
+	partial.usage.input = totalTokens - outputTokens;
 	partial.usage.output = outputTokens;
 	partial.usage.cacheRead = 0;
 	partial.usage.cacheWrite = 0;
-	// Never report less occupancy than the last compatible same-model in-window assistant measurement.
-	partial.usage.totalTokens = Math.max(
-		partial.usage.input + partial.usage.output,
-		estimateCursorContextTotalTokens(partial, model, context),
-		getLastAcceptedContextOccupancy(context, model),
-	);
-}
-
-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);
+	partial.usage.totalTokens = totalTokens;
 }
 
 export function applyCursorUsage(
@@ -208,18 +149,12 @@ export function applyCursorUsage(
 	sessionInputTokens: number,
 	sdkUsage?: CursorSdkUsageApplyOptions,
 ): void {
-	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)) {
+		// Fresh LOCAL occupancy supersedes any previous request-provenance floor.
 		applyCursorSdkUsage(partial, localTurn);
-		applyResolvedCursorOccupancy(partial, model, context, localTurn);
-		return;
+	} else {
+		applyCursorApproximateUsage(partial, model, context, sessionInputTokens, sdkUsage?.occupancyFloor);
 	}
-	applyCursorApproximateUsage(partial, model, context, sessionInputTokens);
+	calculateCost(model, partial.usage);
 }

package/src/cursor-usage-command.ts

@@ -0,0 +1,76 @@
+import { closeSync, constants, fsyncSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createRegularFileExclusive } from "./cursor-durable-fs.js";
+import { fetchCursorSdkAgentUsage } from "./cursor-sdk-billed-usage.js";
+import { resolveCursorApiKey } from "./cursor-api-key.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { readCursorUsageView, refreshCursorUsageView, type CursorUsageView } from "./cursor-usage-ledger.js";
+
+const HELP = [
+	"/cursor-usage — current branch telemetry (native footer unchanged)",
+	"/cursor-usage refresh — public getUsage only; up to 32 agents, 5 seconds each; no model sends or automatic polling",
+	"/cursor-usage export <new-file.json> — exclusive private JSON export; never overwrites a file",
+	"/cursor-usage help — this help",
+	"Storage ceiling: 16MiB per origin session. At the ceiling or after an incomplete trailing frame, new sends fail before spend. A torn tail is retained unchanged; view/export preserve validated prior frames and mark accounting incomplete. Malformed complete frames remain fail-closed.",
+	"Recovery: export readable facts and retain the original journal/session unchanged. Use Pi's native fork to preserve the conversation under a new session origin, or start a new native session. Never delete, truncate, or rewrite journals or native sessions to continue the old origin.",
+	"Other-branch facts have valid native claims elsewhere in this session; unclaimed facts have no surviving claim here and are not branch usage. Inherited records without a claim in this session retain unknown ownership; no sibling sessions are scanned. Fileless sessions are ephemeral.",
+].join("\n");
+export function renderCursorUsageView(view: CursorUsageView): string {
+	return [
+		`Cursor usage — ${view.durability}; persistence ${view.persistenceStatus}; current branch telemetry`,
+		view.nativeConfiguredEstimates,
+		`Recorded corrected LOCAL raw tokens: ${view.correctedRawTotal.totalTokens} (input ${view.correctedRawTotal.inputTokens}, cache read ${view.correctedRawTotal.cacheReadTokens}, cache write ${view.correctedRawTotal.cacheWriteTokens}, output ${view.correctedRawTotal.outputTokens}).`,
+		`Original telemetry: ${view.records.filter(record => record.kind === "raw").length} raw turns; normalization unavailable/invalid: ${view.records.filter(record => record.kind === "raw" && !record.corrected).length}; ${view.records.filter(record => record.kind === "terminal").length} terminal facts (not added to raw).`,
+		`Other-branch journal records: ${view.otherBranchRecords.length}; unclaimed records: ${view.unclaimedRecords.length}; inherited records with unknown claim ownership: ${view.inheritedUnclaimedRecords.length}; inherited journal gaps: ${view.lineageGaps.length}; incomplete trailing frames: ${view.incompleteJournals.length}. Export retains these facts without billing them to this branch.`,
+		...view.lineageGaps,
+		...view.agents.slice(0, 32).map(agent => {
+			const missing = agent.billingStatus === "ambiguous-shared-lineage" ? "ambiguous" : agent.billingStatus === "unavailable" ? "unavailable" : agent.billingStatus === "pending" ? "pending" : "unknown";
+			const remainder = agent.billingStatus === "ambiguous-shared-lineage" ? "ambiguous" : agent.observationsByOrigin.some(observation => observation.incompleteHistory) ? "unknown (incomplete run history)" : agent.aggregateOnly?.totalTokens ?? missing;
+			return [
+				`${agent.agentId}: ${agent.billingStatus}${agent.unknownHistory ? "; unknown historical baseline" : ""}`,
+				agent.sharedAcrossBranches ? "; shared lineage, not attributable to this branch" : "; whole-agent facts, no client-run billing join",
+				`. Latest known billed tokens: ${agent.latestAggregate?.usage.totalTokens ?? missing}; SDK charged cents: ${agent.latestAggregate ? agent.latestAggregate.cost?.chargedCents ?? "not reported" : missing}; aggregate-only tokens: ${remainder}.`,
+				...agent.observationsByOrigin.map(observation => {
+					const absent = observation.lastAttempt.status === "unavailable" ? "unavailable" : "unknown";
+					return ` Origin ${observation.origin.sessionId}: ${observation.lastAttempt.status}${observation.incompleteHistory ? "; incomplete run history" : ""}; latest known billed tokens ${observation.latestAggregate?.usage.totalTokens ?? absent}; charged cents ${observation.latestAggregate ? observation.latestAggregate.cost?.chargedCents ?? "not reported" : absent}.`;
+				}),
+			].join("");
+		}),
+		...(view.agents.length > 32 ? [`${view.agents.length - 32} further agents retained in export.`] : []),
+		"Snapshots are observations, not final invoices. Multiple origin journals have no qualified global revision ordering. Cloud raw normalization is unqualified.",
+		`Journal ceiling: ${view.journalLimit}. See /cursor-usage help for recovery. Export contains no prompts or tool content.`,
+	].join("\n");
+}
+export function registerCursorUsageCommand(pi: Pick<ExtensionAPI, "appendEntry" | "registerCommand">): void {
+	pi.registerCommand("cursor-usage", {
+		description: "View Cursor telemetry; refresh public billing or export to a new JSON file",
+		handler: async (args, ctx) => {
+			const show = (message: string, error = false) => {
+				if (ctx.hasUI) ctx.ui.notify(message, error ? "error" : "info");
+				else process.stderr.write(`${message}\n`); // Keep non-UI stdout/RPC framing untouched.
+			};
+			try {
+				const argument = args.trim();
+				if (["help", "-h", "--help"].includes(argument)) { show(HELP); return; }
+				if (argument && argument !== "refresh" && !argument.startsWith("export ")) { show(HELP, true); return; }
+				let view = readCursorUsageView(pi, ctx);
+				if (argument === "refresh") {
+					const { Agent } = await loadCursorSdk();
+					const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
+					view = await refreshCursorUsageView(pi, ctx, agentId => fetchCursorSdkAgentUsage({ getUsage: () => Agent.getUsage(agentId, { apiKey }) }));
+				} else if (argument.startsWith("export ")) {
+					const path = resolve(ctx.cwd, argument.slice(7).trim());
+					const fd = createRegularFileExclusive(path, constants.O_WRONLY, 0o600);
+					try { writeFileSync(fd, `${JSON.stringify(view, null, 2)}\n`); fsyncSync(fd); }
+					finally { closeSync(fd); }
+					show(`Cursor usage exported to ${path}.`);
+					return;
+				}
+				show(renderCursorUsageView(view));
+			} catch {
+				show("Cursor usage could not be read, persisted, refreshed, or exported. Existing files were not replaced; accounting may be incomplete. See /cursor-usage help for storage limits and recovery.", true);
+			}
+		},
+	});
+}