pi-cursor-sdk 0.1.14 → 0.1.16

package/src/cursor-question-tool.ts

@@ -0,0 +1,252 @@
+import type { ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge.js";
+
+export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
+
+interface CursorQuestionOption {
+	label: string;
+	value: string;
+	description?: string;
+}
+
+interface CursorQuestion {
+	id: string;
+	question: string;
+	options: CursorQuestionOption[];
+	allowCustom: boolean;
+}
+
+interface CursorQuestionAnswer {
+	id: string;
+	question: string;
+	answer: string | null;
+	value?: string;
+	wasCustom: boolean;
+	cancelled: boolean;
+}
+
+interface CursorQuestionDetails {
+	questions: CursorQuestion[];
+	answers: CursorQuestionAnswer[];
+	uiAvailable: boolean;
+	cancelled: boolean;
+}
+
+interface CursorQuestionToolExtensionApi extends Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
+}
+
+type RawQuestionOption = string | { label?: string; value?: string; description?: string };
+
+type RawQuestion = {
+	id?: string;
+	question?: string;
+	prompt?: string;
+	options?: RawQuestionOption[];
+	choices?: RawQuestionOption[];
+	allowCustom?: boolean;
+};
+
+type CursorAskQuestionParams = RawQuestion & {
+	questions?: RawQuestion[];
+};
+
+const QuestionOptionSchema = Type.Union([
+	Type.String(),
+	Type.Object({
+		label: Type.String({ description: "User-facing option label" }),
+		value: Type.Optional(Type.String({ description: "Optional value returned to Cursor; defaults to label" })),
+		description: Type.Optional(Type.String({ description: "Optional helper text shown by compatible pi UIs" })),
+	}),
+]);
+
+const QuestionSchema = Type.Object({
+	id: Type.Optional(Type.String({ description: "Stable question identifier" })),
+	question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+	prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+	options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+	choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+	allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+});
+
+const CursorAskQuestionParamsSchema = Type.Object({
+	question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+	prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+	options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+	choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+	allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+	questions: Type.Optional(Type.Array(QuestionSchema, { description: "Ask multiple questions sequentially" })),
+});
+
+function isCursorModel(model: ExtensionContext["model"]): boolean {
+	return model?.provider === "cursor" || model?.api === "cursor-sdk";
+}
+
+function normalizeOption(option: RawQuestionOption, index: number): CursorQuestionOption | undefined {
+	if (typeof option === "string") {
+		const trimmed = option.trim();
+		return trimmed ? { label: trimmed, value: trimmed } : undefined;
+	}
+	const label = option.label?.trim() || option.value?.trim() || `Option ${index + 1}`;
+	return {
+		label,
+		value: option.value?.trim() || label,
+		...(option.description?.trim() ? { description: option.description.trim() } : {}),
+	};
+}
+
+function normalizeOptions(options: RawQuestionOption[] | undefined): CursorQuestionOption[] {
+	return (options ?? []).map(normalizeOption).filter((option): option is CursorQuestionOption => option !== undefined);
+}
+
+function normalizeQuestion(raw: RawQuestion, index: number): CursorQuestion | undefined {
+	const question = raw.question?.trim() || raw.prompt?.trim();
+	if (!question) return undefined;
+	return {
+		id: raw.id?.trim() || `question_${index + 1}`,
+		question,
+		options: normalizeOptions(raw.options ?? raw.choices),
+		allowCustom: raw.allowCustom !== false,
+	};
+}
+
+function normalizeQuestions(params: CursorAskQuestionParams): CursorQuestion[] {
+	const rawQuestions = Array.isArray(params.questions) && params.questions.length > 0 ? params.questions : [params];
+	return rawQuestions.map(normalizeQuestion).filter((question): question is CursorQuestion => question !== undefined);
+}
+
+function summarizeAnswers(answers: CursorQuestionAnswer[]): string {
+	if (answers.length === 0) return "No answer was collected.";
+	if (answers.length === 1) {
+		const [answer] = answers;
+		return answer.cancelled || answer.answer === null ? "User cancelled the question." : `User answered: ${answer.answer}`;
+	}
+	return [
+		"User answered:",
+		...answers.map((answer) => {
+			const value = answer.cancelled || answer.answer === null ? "cancelled" : answer.answer;
+			return `- ${answer.id}: ${value}`;
+		}),
+	].join("\n");
+}
+
+function buildDetails(questions: CursorQuestion[], answers: CursorQuestionAnswer[], uiAvailable: boolean): CursorQuestionDetails {
+	return {
+		questions,
+		answers,
+		uiAvailable,
+		cancelled: answers.some((answer) => answer.cancelled),
+	};
+}
+
+async function askOneQuestion(question: CursorQuestion, ctx: { ui: ExtensionContext["ui"] }): Promise<CursorQuestionAnswer> {
+	if (question.options.length > 0) {
+		const labels = question.options.map((option) => option.description ? `${option.label} — ${option.description}` : option.label);
+		const customLabel = "Type a custom answer";
+		const choices = question.allowCustom ? [...labels, customLabel] : labels;
+		const selected = await ctx.ui.select(question.question, choices);
+		if (!selected) {
+			return { id: question.id, question: question.question, answer: null, wasCustom: false, cancelled: true };
+		}
+		if (selected === customLabel) {
+			const customAnswer = await ctx.ui.input(question.question, "Type your answer");
+			const trimmed = customAnswer?.trim();
+			return trimmed
+				? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+				: { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+		}
+		const selectedIndex = labels.indexOf(selected);
+		const selectedOption = selectedIndex >= 0 ? question.options[selectedIndex] : undefined;
+		const answer = selectedOption?.label ?? selected;
+		return {
+			id: question.id,
+			question: question.question,
+			answer,
+			value: selectedOption?.value ?? answer,
+			wasCustom: false,
+			cancelled: false,
+		};
+	}
+
+	const answer = await ctx.ui.input(question.question, "Type your answer");
+	const trimmed = answer?.trim();
+	return trimmed
+		? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+		: { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+}
+
+function syncCursorQuestionToolForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+	const activeToolNames = new Set(pi.getActiveTools());
+	const shouldBeActive = isCursorModel(model) && resolveCursorPiToolBridgeEnabled();
+	const alreadyActive = activeToolNames.has(CURSOR_ASK_QUESTION_TOOL_NAME);
+	if (shouldBeActive === alreadyActive) return;
+	if (shouldBeActive) {
+		activeToolNames.add(CURSOR_ASK_QUESTION_TOOL_NAME);
+	} else {
+		activeToolNames.delete(CURSOR_ASK_QUESTION_TOOL_NAME);
+	}
+	pi.setActiveTools([...activeToolNames]);
+}
+
+export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi): void {
+	pi.registerTool({
+		name: CURSOR_ASK_QUESTION_TOOL_NAME,
+		label: "Cursor question",
+		description:
+			"Ask the user a clarifying question from Cursor. Use when user preferences materially affect the next step; provide options when possible.",
+		parameters: CursorAskQuestionParamsSchema,
+		promptGuidelines: [
+			"Use cursor_ask_question only when running a Cursor model and user input would materially change the plan, scope, platform, or implementation path.",
+			"Prefer cursor_ask_question with 2-4 concrete options instead of guessing when Cursor plan mode needs user choices.",
+		],
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const questions = normalizeQuestions(params as CursorAskQuestionParams);
+			if (questions.length === 0) {
+				return {
+					content: [{ type: "text" as const, text: "No valid question was provided." }],
+					details: buildDetails([], [], ctx.hasUI),
+					isError: true,
+				};
+			}
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Cannot ask the user because pi UI is unavailable. Make a reasonable default choice and state the assumption before proceeding.",
+						},
+					],
+					details: buildDetails(questions, [], false),
+					isError: true,
+				};
+			}
+
+			const answers: CursorQuestionAnswer[] = [];
+			for (const question of questions) {
+				const answer = await askOneQuestion(question, ctx);
+				answers.push(answer);
+				if (answer.cancelled) break;
+			}
+
+			return {
+				content: [{ type: "text" as const, text: summarizeAnswers(answers) }],
+				details: buildDetails(questions, answers, true),
+			};
+		},
+		renderCall(args, theme) {
+			const questions = normalizeQuestions(args as CursorAskQuestionParams);
+			const label = questions[0]?.question ?? "Ask the user";
+			return new Text(theme.fg("toolTitle", theme.bold("cursor question ")) + theme.fg("muted", label), 0, 0);
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
+	pi.on("model_select", (event) => {
+		syncCursorQuestionToolForModel(pi, event.model);
+	});
+}

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

@@ -0,0 +1,28 @@
+import {
+	getCursorSessionCwdFromScope,
+	registerCursorSessionScope,
+	__testUtils as cursorSessionScopeTestUtils,
+} from "./cursor-session-scope.js";
+import type { ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+
+interface CursorSessionCwdExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+}
+
+/**
+ * Pi session cwd when known; falls back to process.cwd() before session_start.
+ * Updated on session_start only until pi threads cwd into streamSimple—mid-session cwd
+ * changes without a new session_start event are not reflected here.
+ */
+export function getCursorSessionCwd(): string {
+	return getCursorSessionCwdFromScope();
+}
+
+export function registerCursorSessionCwd(pi: CursorSessionCwdExtensionApi): void {
+	registerCursorSessionScope(pi);
+}
+
+export const __testUtils = {
+	set: cursorSessionScopeTestUtils.set,
+	reset: cursorSessionScopeTestUtils.reset,
+};