pi-cursor-sdk 0.1.15 → 0.1.16

package/src/cursor-session-agent.ts

@@ -0,0 +1,372 @@
+import type {
+	ExtensionHandler,
+	SessionBeforeTreeEvent,
+	SessionCompactEvent,
+	SessionShutdownEvent,
+	SessionTreeEvent,
+} from "@earendil-works/pi-coding-agent";
+import { createHash } from "node:crypto";
+import { Agent } from "@cursor/sdk";
+import type { ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
+import type { Context } from "@earendil-works/pi-ai";
+import {
+	getRegisteredCursorPiToolBridge,
+	type CursorPiBridgeToolRequest,
+	type CursorPiToolBridgeRun,
+} from "./cursor-pi-tool-bridge.js";
+import { computeCursorContextFingerprint } from "./context.js";
+import { getCursorSessionScopeKey, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+
+export interface SessionCursorAgentSendState {
+	bootstrapped: boolean;
+	contextFingerprint: string;
+}
+
+export interface SessionCursorAgentLease {
+	scopeKey: string;
+	agent: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+	sendState: SessionCursorAgentSendState;
+	created: boolean;
+}
+
+interface SessionCursorAgentPoolEntry {
+	poolKey: string;
+	scopeKey: string;
+	agent?: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+	sendState: SessionCursorAgentSendState;
+	creating?: Promise<SessionCursorAgentPoolEntry>;
+	creationGeneration?: number;
+}
+
+class SessionCursorAgentCreationSupersededError extends Error {
+	constructor() {
+		super("Cursor session agent creation was superseded");
+		this.name = "SessionCursorAgentCreationSupersededError";
+	}
+}
+
+export class SessionCursorAgentScopeClosedError extends Error {
+	constructor() {
+		super("Cursor session agent scope is closed");
+		this.name = "SessionCursorAgentScopeClosedError";
+	}
+}
+
+function assertScopeAcceptsAcquire(scopeKey: string): void {
+	if (terminalDisposedScopeKeys.has(scopeKey)) {
+		throw new SessionCursorAgentScopeClosedError();
+	}
+}
+
+function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey: string, poolKey: string, error: unknown): void {
+	if (!(error instanceof SessionCursorAgentCreationSupersededError)) return;
+	const replacement = sessionAgentsByScope.get(scopeKey);
+	if (replacement && replacement.poolKey !== poolKey) {
+		throw error;
+	}
+}
+
+interface SessionCursorAgentCreateParams {
+	apiKey: string;
+	cwd: string;
+	modelSelection: ModelSelection;
+	settingSources?: SettingSource[];
+	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	createAgent?: typeof Agent.create;
+}
+
+interface CursorSessionAgentExtensionApi {
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "model_select", handler: ExtensionHandler<{ model: unknown }>): void;
+}
+
+const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
+const invalidatedScopeKeys = new Set<string>();
+const terminalDisposedScopeKeys = new Set<string>();
+const scopeCreationGenerations = new Map<string, number>();
+
+function getScopeCreationGeneration(scopeKey: string): number {
+	return scopeCreationGenerations.get(scopeKey) ?? 0;
+}
+
+function invalidateScopeCreations(scopeKey: string): void {
+	scopeCreationGenerations.set(scopeKey, getScopeCreationGeneration(scopeKey) + 1);
+}
+
+function buildModelPoolKey(modelSelection: ModelSelection): string {
+	return JSON.stringify(modelSelection);
+}
+
+function buildSettingSourcesPoolKey(settingSources?: SettingSource[]): string {
+	return settingSources?.join(",") ?? "";
+}
+
+function buildApiKeyPoolKeyFingerprint(apiKey: string): string {
+	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+
+function buildBridgePoolKeySuffix(): string {
+	const registeredBridge = getRegisteredCursorPiToolBridge();
+	if (!registeredBridge) return "bridge:absent";
+	return registeredBridge.getToolSurfaceSignature();
+}
+
+function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCreateParams): string {
+	return [
+		scopeKey,
+		params.cwd,
+		buildModelPoolKey(params.modelSelection),
+		buildSettingSourcesPoolKey(params.settingSources),
+		buildApiKeyPoolKeyFingerprint(params.apiKey),
+		buildBridgePoolKeySuffix(),
+	].join("\0");
+}
+
+async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<void> {
+	entry.bridgeRun?.cancel("Cursor session agent disposed");
+	try {
+		await entry.bridgeRun?.dispose();
+	} catch {
+		// disposal failure should not block session replacement
+	}
+	if (!entry.agent) return;
+	try {
+		await entry.agent[Symbol.asyncDispose]();
+	} catch {
+		// disposal failure should not block session replacement
+	}
+}
+
+async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?: boolean }): Promise<void> {
+	invalidateScopeCreations(scopeKey);
+	if (options?.terminal) {
+		terminalDisposedScopeKeys.add(scopeKey);
+	}
+	const entry = sessionAgentsByScope.get(scopeKey);
+	invalidatedScopeKeys.delete(scopeKey);
+	if (!entry) return;
+	sessionAgentsByScope.delete(scopeKey);
+	if (entry.creating || !entry.agent) return;
+	await disposePoolEntry(entry);
+}
+
+function createInitialSendState(): SessionCursorAgentSendState {
+	return { bootstrapped: false, contextFingerprint: "" };
+}
+
+function bindBridgeToolRequest(
+	entry: SessionCursorAgentPoolEntry,
+	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void,
+): void {
+	entry.bridgeRun?.setOnToolRequest(onBridgeToolRequest);
+}
+
+function leaseFromEntry(
+	entry: SessionCursorAgentPoolEntry,
+	scopeKey: string,
+	params: SessionCursorAgentCreateParams,
+	created: boolean,
+): SessionCursorAgentLease {
+	bindBridgeToolRequest(entry, params.onBridgeToolRequest);
+	return {
+		scopeKey,
+		agent: entry.agent!,
+		bridgeRun: entry.bridgeRun,
+		sendState: entry.sendState,
+		created,
+	};
+}
+
+async function createSessionAgentEntry(
+	scopeKey: string,
+	poolKey: string,
+	params: SessionCursorAgentCreateParams,
+): Promise<SessionCursorAgentPoolEntry> {
+	const registeredBridge = getRegisteredCursorPiToolBridge();
+	let bridgeRun: CursorPiToolBridgeRun | undefined;
+	if (registeredBridge) {
+		bridgeRun = await registeredBridge.createRun({
+			onToolRequest: params.onBridgeToolRequest,
+		});
+		if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
+			await bridgeRun.dispose();
+			bridgeRun = undefined;
+		}
+	}
+
+	const resolvedPoolKey = buildSessionAgentPoolKey(scopeKey, params);
+	const createAgent = params.createAgent ?? Agent.create;
+	let agent: SDKAgent;
+	try {
+		agent = await createAgent({
+			apiKey: params.apiKey,
+			model: params.modelSelection,
+			local: params.settingSources ? { cwd: params.cwd, settingSources: params.settingSources } : { cwd: params.cwd },
+			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+		});
+	} catch (error) {
+		if (bridgeRun) {
+			bridgeRun.cancel("Cursor session agent create failed");
+			try {
+				await bridgeRun.dispose();
+			} catch {
+				// bridge disposal failure should not mask agent create failure
+			}
+		}
+		throw error;
+	}
+
+	return {
+		poolKey: resolvedPoolKey,
+		scopeKey,
+		agent,
+		bridgeRun,
+		sendState: createInitialSendState(),
+	};
+}
+
+export { shouldBootstrapCursorSend } from "./context.js";
+
+export function commitSessionAgentSend(scopeKey: string, context: Context, bootstrapped: boolean): void {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!entry) return;
+	entry.sendState.bootstrapped = bootstrapped || entry.sendState.bootstrapped;
+	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
+}
+
+export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeKey()): void {
+	invalidatedScopeKeys.add(scopeKey);
+}
+
+export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
+	const scopeKey = getCursorSessionScopeKey();
+	assertScopeAcceptsAcquire(scopeKey);
+	if (invalidatedScopeKeys.has(scopeKey)) {
+		await disposePoolEntryForScope(scopeKey);
+	}
+
+	const poolKey = buildSessionAgentPoolKey(scopeKey, params);
+	const existing = sessionAgentsByScope.get(scopeKey);
+	if (existing?.poolKey === poolKey && !existing.creating) {
+		return leaseFromEntry(existing, scopeKey, params, false);
+	}
+
+	if (existing && existing.poolKey !== poolKey) {
+		await disposePoolEntryForScope(scopeKey);
+	}
+
+	let entry = sessionAgentsByScope.get(scopeKey);
+	if (entry?.creating) {
+		try {
+			await entry.creating;
+		} catch (error) {
+			if (error instanceof SessionCursorAgentCreationSupersededError) {
+				assertScopeAcceptsAcquire(scopeKey);
+				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+			} else {
+				throw error;
+			}
+		}
+		entry = sessionAgentsByScope.get(scopeKey);
+		if (entry && entry.poolKey === poolKey && entry.agent && !entry.creating) {
+			return leaseFromEntry(entry, scopeKey, params, false);
+		}
+	}
+
+	assertScopeAcceptsAcquire(scopeKey);
+	const creationGeneration = getScopeCreationGeneration(scopeKey);
+	const placeholder: SessionCursorAgentPoolEntry = {
+		poolKey,
+		scopeKey,
+		sendState: createInitialSendState(),
+		creationGeneration,
+	};
+	const creating = createSessionAgentEntry(scopeKey, poolKey, params).then(async (createdEntry) => {
+		const stillCurrent =
+			sessionAgentsByScope.get(scopeKey) === placeholder &&
+			getScopeCreationGeneration(scopeKey) === placeholder.creationGeneration;
+		if (!stillCurrent) {
+			await disposePoolEntry(createdEntry);
+			if (sessionAgentsByScope.get(scopeKey) === placeholder) {
+				sessionAgentsByScope.delete(scopeKey);
+			}
+			throw new SessionCursorAgentCreationSupersededError();
+		}
+		sessionAgentsByScope.set(scopeKey, createdEntry);
+		return createdEntry;
+	});
+	placeholder.creating = creating;
+	sessionAgentsByScope.set(scopeKey, placeholder);
+
+	try {
+		const createdEntry = await creating;
+		return leaseFromEntry(createdEntry, scopeKey, params, true);
+	} catch (error) {
+		if (sessionAgentsByScope.get(scopeKey) === placeholder) {
+			sessionAgentsByScope.delete(scopeKey);
+		}
+		if (error instanceof SessionCursorAgentCreationSupersededError) {
+			assertScopeAcceptsAcquire(scopeKey);
+			rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+			return acquireSessionCursorAgent(params);
+		}
+		throw error;
+	}
+}
+
+export async function resetSessionCursorAgent(scopeKey: string = getCursorSessionScopeKey()): Promise<void> {
+	await disposePoolEntryForScope(scopeKey);
+}
+
+export async function disposeSessionCursorAgent(scopeKey: string = getCursorSessionScopeKey()): Promise<void> {
+	await disposePoolEntryForScope(scopeKey, { terminal: true });
+}
+
+export async function disposeAllSessionCursorAgents(): Promise<void> {
+	const scopeKeys = [...new Set([...sessionAgentsByScope.keys(), ...terminalDisposedScopeKeys])];
+	await Promise.all(scopeKeys.map((scopeKey) => disposePoolEntryForScope(scopeKey, { terminal: true })));
+	invalidatedScopeKeys.clear();
+	terminalDisposedScopeKeys.clear();
+}
+
+export function registerCursorSessionAgent(_pi: CursorSessionAgentExtensionApi): void {
+	onCursorSessionScopeKeyChange((previousScopeKey) => {
+		void disposePoolEntryForScope(previousScopeKey, { terminal: true });
+	});
+	_pi.on("session_shutdown", async (event) => {
+		if (event.reason === "reload") {
+			await resetSessionCursorAgent();
+			return;
+		}
+		await disposeSessionCursorAgent();
+	});
+	_pi.on("session_compact", () => {
+		invalidateSessionAgent();
+	});
+	_pi.on("session_before_tree", () => {
+		invalidateSessionAgent();
+	});
+	_pi.on("session_tree", async () => {
+		await resetSessionCursorAgent();
+	});
+	_pi.on("model_select", () => {
+		invalidateSessionAgent();
+	});
+}
+
+export const __testUtils = {
+	sessionAgentsByScope,
+	invalidateSessionAgent,
+	disposeSessionCursorAgent,
+	resetSessionCursorAgent,
+	disposeAllSessionCursorAgents,
+	buildApiKeyPoolKeyFingerprint,
+	buildSessionAgentPoolKey,
+	SessionCursorAgentCreationSupersededError,
+	SessionCursorAgentScopeClosedError,
+};

package/src/cursor-session-cwd.ts

@@ -1,8 +1,13 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	getCursorSessionCwdFromScope,
+	registerCursorSessionScope,
+	__testUtils as cursorSessionScopeTestUtils,
+} from "./cursor-session-scope.js";
+import type { ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 
-const state = {
-	sessionCwd: process.cwd(),
-};
+interface CursorSessionCwdExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+}
 
 /**
  * Pi session cwd when known; falls back to process.cwd() before session_start.
@@ -10,24 +15,14 @@ const state = {
  * changes without a new session_start event are not reflected here.
  */
 export function getCursorSessionCwd(): string {
-	return state.sessionCwd;
-}
-
-function setCursorSessionCwd(cwd: string): void {
-	state.sessionCwd = cwd;
-}
-
-function resetCursorSessionCwd(): void {
-	state.sessionCwd = process.cwd();
+	return getCursorSessionCwdFromScope();
 }
 
-export function registerCursorSessionCwd(pi: ExtensionAPI): void {
-	pi.on("session_start", (_event, ctx) => {
-		setCursorSessionCwd(ctx.cwd);
-	});
+export function registerCursorSessionCwd(pi: CursorSessionCwdExtensionApi): void {
+	registerCursorSessionScope(pi);
 }
 
 export const __testUtils = {
-	set: setCursorSessionCwd,
-	reset: resetCursorSessionCwd,
+	set: cursorSessionScopeTestUtils.set,
+	reset: cursorSessionScopeTestUtils.reset,
 };

package/src/cursor-session-scope.ts

@@ -0,0 +1,65 @@
+import type { ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+
+interface CursorSessionScopeExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+}
+
+const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
+
+type CursorSessionScopeChangeHandler = (previousScopeKey: string) => void;
+
+const state = {
+	sessionCwd: process.cwd(),
+	sessionFile: undefined as string | undefined,
+};
+
+let scopeChangeHandler: CursorSessionScopeChangeHandler | undefined;
+
+/**
+ * Pi session file when known; used to scope reused Cursor SDK agents to one pi session.
+ */
+export function getCursorSessionFile(): string | undefined {
+	return state.sessionFile;
+}
+
+/**
+ * Stable scope key for session-agent pooling. Falls back to a process-local anonymous key
+ * before the first session_start (tests and early startup).
+ */
+export function getCursorSessionScopeKey(): string {
+	return state.sessionFile ?? ANONYMOUS_SESSION_SCOPE_KEY;
+}
+
+export function getCursorSessionCwdFromScope(): string {
+	return state.sessionCwd;
+}
+
+function setCursorSessionScope(cwd: string, sessionFile: string | undefined): void {
+	state.sessionCwd = cwd;
+	state.sessionFile = sessionFile;
+}
+
+function resetCursorSessionScope(): void {
+	state.sessionCwd = process.cwd();
+	state.sessionFile = undefined;
+}
+
+export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeHandler): void {
+	scopeChangeHandler = handler;
+}
+
+export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi): void {
+	pi.on("session_start", (_event, ctx) => {
+		const previousScopeKey = getCursorSessionScopeKey();
+		setCursorSessionScope(ctx.cwd, ctx.sessionManager?.getSessionFile?.() ?? undefined);
+		if (previousScopeKey !== getCursorSessionScopeKey()) {
+			scopeChangeHandler?.(previousScopeKey);
+		}
+	});
+}
+
+export const __testUtils = {
+	ANONYMOUS_SESSION_SCOPE_KEY,
+	set: setCursorSessionScope,
+	reset: resetCursorSessionScope,
+};

package/src/cursor-state.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getCursorModelMetadata } from "./model-discovery.js";
 
@@ -17,6 +17,26 @@ interface CursorGlobalConfig {
 	fastDefaults?: Record<string, boolean>;
 }
 
+type CursorFastControlsModel =
+	| Pick<NonNullable<ExtensionContext["model"]>, "id" | "provider" | "api">
+	| undefined;
+
+type CursorFastControlsContext = {
+	model: CursorFastControlsModel;
+	ui: Pick<ExtensionContext["ui"], "notify" | "setStatus">;
+	sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch">;
+};
+
+interface CursorFastControlsExtensionApi extends Pick<ExtensionAPI, "appendEntry" | "getFlag" | "registerFlag"> {
+	registerCommand(name: string, options: {
+		description?: string;
+		handler: (args: string, ctx: CursorFastControlsContext) => Promise<void> | void;
+	}): void;
+	on(event: "session_start", handler: (event: SessionStartEvent, ctx: CursorFastControlsContext) => Promise<void> | void): void;
+	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: CursorFastControlsContext) => Promise<void> | void): void;
+	on(event: "turn_start", handler: (event: unknown, ctx: CursorFastControlsContext) => Promise<void> | void): void;
+}
+
 const sessionFastPreferences = new Map<string, boolean>();
 let globalFastPreferences = new Map<string, boolean>();
 let cliForceFast = false;
@@ -56,7 +76,7 @@ function saveGlobalFastPreferences(): void {
 	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
 }
 
-function restoreSessionFastPreferences(ctx: ExtensionContext): void {
+function restoreSessionFastPreferences(ctx: { sessionManager: Pick<ExtensionContext["sessionManager"], "getBranch"> }): void {
 	sessionFastPreferences.clear();
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type !== "custom" || entry.customType !== FAST_ENTRY_TYPE) continue;
@@ -74,23 +94,27 @@ function getEffectiveFast(baseModelId: string, modelId: string): boolean | undef
 	return sessionFastPreferences.get(baseModelId) ?? globalFastPreferences.get(baseModelId) ?? metadata.defaultFast;
 }
 
-function updateCursorStatus(ctx: ExtensionContext, model = ctx.model): void {
-	if (model?.provider !== CURSOR_PROVIDER) {
+function isCursorModel(model: CursorFastControlsModel): boolean {
+	return model?.provider === CURSOR_PROVIDER || model?.api === "cursor-sdk";
+}
+
+function updateCursorStatus(ctx: { model: CursorFastControlsModel; ui: Pick<ExtensionContext["ui"], "setStatus"> }, model = ctx.model): void {
+	if (!model || !isCursorModel(model)) {
 		ctx.ui.setStatus("cursor", undefined);
 		return;
 	}
 	const metadata = getCursorModelMetadata(model.id);
-	if (!metadata) {
+	if (!metadata?.supportsFast) {
 		ctx.ui.setStatus("cursor", undefined);
 		return;
 	}
 	const fast = getEffectiveFast(metadata.baseModelId, model.id);
-	ctx.ui.setStatus("cursor", fast ? "cursor fast" : undefined);
+	ctx.ui.setStatus("cursor", fast === true ? "cursor fast" : undefined);
 }
 
-function getCurrentCursorMetadata(ctx: ExtensionContext) {
+function getCurrentCursorMetadata(ctx: { model: CursorFastControlsModel }) {
 	const model = ctx.model;
-	if (model?.provider !== CURSOR_PROVIDER) return undefined;
+	if (!model || !isCursorModel(model)) return undefined;
 	return getCursorModelMetadata(model.id);
 }
 
@@ -102,7 +126,7 @@ function restoreMapValue(map: Map<string, boolean>, key: string, previous: boole
 	}
 }
 
-function persistFastPreference(pi: ExtensionAPI, baseModelId: string, fast: boolean): void {
+function persistFastPreference(pi: Pick<ExtensionAPI, "appendEntry">, baseModelId: string, fast: boolean): void {
 	const previousSession = sessionFastPreferences.get(baseModelId);
 	const previousGlobal = globalFastPreferences.get(baseModelId);
 	let savedGlobal = false;
@@ -132,7 +156,7 @@ export function getEffectiveFastForModelId(modelId: string): boolean | undefined
 	return getEffectiveFast(metadata.baseModelId, modelId);
 }
 
-export function registerCursorFastControls(pi: ExtensionAPI): void {
+export function registerCursorFastControls(pi: CursorFastControlsExtensionApi): void {
 	pi.registerFlag("cursor-fast", {
 		description: "Force Cursor fast mode for this run when the selected Cursor model supports it",
 		type: "boolean",
@@ -188,6 +212,10 @@ export function registerCursorFastControls(pi: ExtensionAPI): void {
 	pi.on("model_select", async (event, ctx) => {
 		updateCursorStatus(ctx, event.model);
 	});
+
+	pi.on("turn_start", async (_event, ctx) => {
+		updateCursorStatus(ctx);
+	});
 }
 
 export const __testUtils = {

package/src/cursor-usage-accounting.ts

@@ -0,0 +1,71 @@
+import type { Api, AssistantMessage, Context, Model } from "@earendil-works/pi-ai";
+import {
+	CURSOR_APPROX_CHARS_PER_TOKEN,
+	CURSOR_IMAGE_TOKEN_ESTIMATE,
+	estimateCursorContextTokens,
+	estimateCursorPromptTokens,
+	estimateCursorTextTokens,
+	type CursorPrompt,
+	type CursorPromptOptions,
+} from "./context.js";
+
+export interface CursorUsagePromptOptions extends CursorPromptOptions {
+	maxInputTokens: number;
+	charsPerToken: number;
+	imageTokenEstimate: number;
+}
+
+function getPromptInputTokenBudget(model: Model<Api>): number {
+	const outputReserveTokens = Math.min(model.maxTokens, Math.max(1, Math.floor(model.contextWindow * 0.2)));
+	return Math.max(1, model.contextWindow - outputReserveTokens);
+}
+
+export function getCursorPromptOptions(model: Model<Api>): CursorUsagePromptOptions {
+	return {
+		maxInputTokens: getPromptInputTokenBudget(model),
+		charsPerToken: CURSOR_APPROX_CHARS_PER_TOKEN,
+		imageTokenEstimate: CURSOR_IMAGE_TOKEN_ESTIMATE,
+	};
+}
+
+export function estimateCursorPromptInputTokens(prompt: CursorPrompt, options: Pick<CursorPromptOptions, "charsPerToken" | "imageTokenEstimate">): number {
+	return estimateCursorPromptTokens(prompt, options);
+}
+
+function stringifyUsageValue(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? "";
+	} catch {
+		return String(value);
+	}
+}
+
+export function estimateCursorAssistantSessionOutputTokens(message: AssistantMessage): number {
+	const parts = message.content
+		.map((block) => {
+			if (block.type === "text") return block.text;
+			if (block.type === "thinking") return block.thinking;
+			if (block.type === "toolCall") {
+				return `Tool call (${block.name}, call ${block.id}): ${stringifyUsageValue(block.arguments)}`;
+			}
+			return "";
+		})
+		.filter(Boolean);
+	return estimateCursorTextTokens(parts.join("\n"), { charsPerToken: CURSOR_APPROX_CHARS_PER_TOKEN });
+}
+
+function withAssistantMessage(context: Context, partial: AssistantMessage): Context {
+	return { ...context, messages: [...context.messages, partial] };
+}
+
+export function estimateCursorContextTotalTokens(partial: AssistantMessage, model: Model<Api>, context: Context): number {
+	return estimateCursorContextTokens(withAssistantMessage(context, partial), getCursorPromptOptions(model));
+}
+
+export function applyCursorApproximateUsage(partial: AssistantMessage, model: Model<Api>, context: Context, sessionInputTokens: number): void {
+	partial.usage.input = sessionInputTokens;
+	partial.usage.output = estimateCursorAssistantSessionOutputTokens(partial);
+	partial.usage.cacheRead = 0;
+	partial.usage.cacheWrite = 0;
+	partial.usage.totalTokens = estimateCursorContextTotalTokens(partial, model, context);
+}