pi-cursor-sdk 0.4.0 → 0.5.0

package/src/cursor-skill-tool.ts

@@ -29,15 +29,13 @@ type CursorActivateSkillParams = {
 };
 
 interface CursorSkillActivationDetails {
-	name?: string;
-	filePath?: string;
-	baseDir?: string;
+	name: string;
+	filePath: string;
+	baseDir: string;
 	resources: string[];
 	availableSkillNames: string[];
 }
 
-let currentSkillsByName = new Map<string, Skill>();
-
 function escapeXml(value: string): string {
 	return value
 		.replace(/&/g, "&amp;")
@@ -51,14 +49,6 @@ function getVisibleSkills(skills: readonly Skill[] | undefined): Skill[] {
 	return (skills ?? []).filter((skill) => !skill.disableModelInvocation);
 }
 
-function setCurrentSkills(skills: readonly Skill[] | undefined): void {
-	currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
-}
-
-function getAvailableSkillNames(): string[] {
-	return [...currentSkillsByName.keys()].sort();
-}
-
 function resolveEffectiveRuntimeForSkillLifecycle(
 	cursorModel: boolean,
 	ctx: Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "isProjectTrusted">>,
@@ -66,27 +56,6 @@ function resolveEffectiveRuntimeForSkillLifecycle(
 	return cursorModel ? resolveEffectiveCursorConfigForContext(ctx).runtime.value : "local";
 }
 
-function shouldExposeSkillTool(model: ExtensionContext["model"], runtime: CursorRuntime): boolean {
-	return runtime === "local" && isCursorModel(model) && resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
-}
-
-function syncCursorSkillToolForModel(
-	pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">,
-	model: ExtensionContext["model"],
-	runtime: CursorRuntime,
-): void {
-	const activeToolNames = new Set(pi.getActiveTools());
-	const shouldBeActive = !arePiToolsDisabled(pi) && shouldExposeSkillTool(model, runtime);
-	const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	if (shouldBeActive === alreadyActive) return;
-	if (shouldBeActive) {
-		activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	} else {
-		activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	}
-	pi.setActiveTools([...activeToolNames]);
-}
-
 export function formatCursorSkillsForPrompt(skills: readonly Skill[]): string {
 	const visibleSkills = getVisibleSkills(skills);
 	if (visibleSkills.length === 0) return "";
@@ -157,16 +126,6 @@ async function listSkillResourcePaths(baseDir: string): Promise<string[]> {
 	return resources;
 }
 
-function buildActivationDetails(skill: Skill | undefined, resources: string[] = []): CursorSkillActivationDetails {
-	return {
-		name: skill?.name,
-		filePath: skill?.filePath,
-		baseDir: skill ? dirname(skill.filePath) : undefined,
-		resources,
-		availableSkillNames: getAvailableSkillNames(),
-	};
-}
-
 function formatSkillResources(resources: readonly string[]): string {
 	if (resources.length === 0) return "<skill_resources />";
 	return [
@@ -190,18 +149,37 @@ function wrapSkillContent(skill: Skill, content: string, resources: readonly str
 }
 
 export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
+	let currentSkillsByName = new Map<string, Skill>();
+
+	function setCurrentSkills(skills: readonly Skill[] | undefined): void {
+		currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
+	}
+
+	function getAvailableSkillNames(): string[] {
+		return [...currentSkillsByName.keys()].sort();
+	}
+
+	function syncCursorSkillToolForModel(model: ExtensionContext["model"], runtime: CursorRuntime): void {
+		const activeToolNames = new Set(pi.getActiveTools());
+		const shouldBeActive = !arePiToolsDisabled(pi) && runtime === "local" && isCursorModel(model)
+			&& resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
+		const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		if (shouldBeActive === alreadyActive) return;
+		if (shouldBeActive) {
+			activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		} else {
+			activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		}
+		pi.setActiveTools([...activeToolNames]);
+	}
+
 	pi.registerTool({
 		name: CURSOR_ACTIVATE_SKILL_TOOL_NAME,
 		label: "Cursor skill",
 		description: "Load full pi Agent Skill instructions for Cursor. Use with a skill name from the current <available_skills> catalog before applying that skill.",
-		promptSnippet: "Load full pi Agent Skill instructions for a listed skill before Cursor applies that skill",
 		parameters: Type.Object({
 			name: Type.String({ description: "Skill name from the current <available_skills> catalog" }),
 		}),
-		promptGuidelines: [
-			`Use ${CURSOR_ACTIVATE_SKILL_TOOL_NAME} only for skill names listed in the current <available_skills> catalog.`,
-			"After loading a skill, follow its instructions and resolve relative skill paths against the returned skill directory.",
-		],
 		async execute(_toolCallId, params) {
 			const requestedName = (params as CursorActivateSkillParams).name?.trim();
 			if (!requestedName) {
@@ -221,7 +199,13 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 				]);
 				return {
 					content: [{ type: "text" as const, text: wrapSkillContent(skill, content, resources) }],
-					details: buildActivationDetails(skill, resources),
+					details: {
+						name: skill.name,
+						filePath: skill.filePath,
+						baseDir: dirname(skill.filePath),
+						resources,
+						availableSkillNames: getAvailableSkillNames(),
+					} satisfies CursorSkillActivationDetails,
 				};
 			} catch (error) {
 				throw new Error(
@@ -233,7 +217,7 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 
 	const clearSkillsAndSync = (model: ExtensionContext["model"], runtime: CursorRuntime = "local"): void => {
 		setCurrentSkills([]);
-		syncCursorSkillToolForModel(pi, model, runtime);
+		syncCursorSkillToolForModel(model, runtime);
 	};
 
 	registerCursorModelLifecycle(pi, {
@@ -247,7 +231,7 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 			const cursorModel = isCursorModel(ctx.model);
 			const runtime = resolveEffectiveRuntimeForSkillLifecycle(cursorModel, ctx);
 			if (!cursorModel || runtime === "cloud") setCurrentSkills([]);
-			syncCursorSkillToolForModel(pi, ctx.model, runtime);
+			syncCursorSkillToolForModel(ctx.model, runtime);
 		},
 		beforeAgentStart: (event, ctx) => {
 			const cursorModel = isCursorModel(ctx.model);
@@ -257,18 +241,10 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 			} else {
 				setCurrentSkills([]);
 			}
-			syncCursorSkillToolForModel(pi, ctx.model, runtime);
+			syncCursorSkillToolForModel(ctx.model, runtime);
 			const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions, runtime);
 			if (resolved === event.systemPrompt) return undefined;
 			return { systemPrompt: resolved };
 		},
 	});
 }
-
-export const __testUtils = {
-	AVAILABLE_SKILLS_SECTION_PATTERN,
-	buildActivationDetails,
-	setCurrentSkills,
-	listSkillResourcePaths,
-	wrapSkillContent,
-};

package/src/cursor-state.ts

@@ -27,7 +27,8 @@ import {
 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 {
@@ -80,18 +81,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 +143,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 +155,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 +201,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 +211,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,28 +225,29 @@ 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)) {
@@ -260,14 +256,14 @@ function updateCursorStatus(ctx: CursorStatusContext & Pick<ExtensionContext, "m
 	}
 	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 +288,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 +312,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 +327,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 +347,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 +415,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 +450,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 +469,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 +532,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(
@@ -568,7 +571,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 +591,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 +603,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 +638,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 +654,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 +671,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-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);
 }