pi-cursor-sdk 0.1.15 → 0.1.17

package/src/cursor-question-tool.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+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";
@@ -34,6 +34,11 @@ interface CursorQuestionDetails {
 	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 = {
@@ -186,7 +191,7 @@ function syncCursorQuestionToolForModel(pi: Pick<ExtensionAPI, "getActiveTools"
 	pi.setActiveTools([...activeToolNames]);
 }
 
-export function registerCursorQuestionTool(pi: ExtensionAPI): void {
+export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi): void {
 	pi.registerTool({
 		name: CURSOR_ASK_QUESTION_TOOL_NAME,
 		label: "Cursor question",

package/src/cursor-record-utils.ts

@@ -0,0 +1,26 @@
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+export function getField(value: unknown, field: string): unknown {
+	return asRecord(value)?.[field];
+}
+
+export function hasUsableText(value: string | undefined): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+export function getFirstStringByKeys(
+	record: Record<string, unknown> | undefined,
+	keys: readonly string[],
+	options?: { nonEmpty?: boolean },
+): string | undefined {
+	if (!record) return undefined;
+	for (const key of keys) {
+		const value = record[key];
+		if (typeof value !== "string") continue;
+		if (options?.nonEmpty && !value) continue;
+		return value;
+	}
+	return undefined;
+}

package/src/cursor-sdk-output-filter.ts

@@ -0,0 +1,100 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const cursorSdkOutputSuppression = new AsyncLocalStorage<boolean>();
+
+export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
+	"[hooks]",
+	"managed_skills.",
+	"CursorPluginsAgentSkillsService load completed",
+	"LocalCursorRulesService load completed",
+	"AgentSkillsCursorRulesService load completed",
+	"Error initializing ignore mapping for",
+	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
+] as const;
+
+export function isCursorSdkOutputSuppressed(): boolean {
+	return cursorSdkOutputSuppression.getStore() === true;
+}
+
+export function suppressCursorSdkOutput<T>(operation: () => Promise<T>): Promise<T> {
+	return cursorSdkOutputSuppression.run(true, operation);
+}
+
+export function isCursorSdkStartupNoise(text: string): boolean {
+	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function createFilteredProcessWrite<TWrite extends typeof process.stdout.write>(write: TWrite, stream: NodeJS.WriteStream): TWrite {
+	return ((
+		chunk: string | Uint8Array,
+		encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+		callback?: (error?: Error | null) => void,
+	): boolean => {
+		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
+			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+			done?.();
+			return true;
+		}
+		return write.call(stream, chunk as string, encodingOrCallback as BufferEncoding, callback);
+	}) as TWrite;
+}
+
+function createFilteredConsoleMethod<TMethod extends typeof console.log>(method: TMethod): TMethod {
+	return ((...args: Parameters<TMethod>): void => {
+		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
+		method(...args);
+	}) as TMethod;
+}
+
+interface CursorSdkOutputFilterOriginals {
+	stdoutWrite: typeof process.stdout.write;
+	stderrWrite: typeof process.stderr.write;
+	consoleLog: typeof console.log;
+	consoleInfo: typeof console.info;
+	consoleWarn: typeof console.warn;
+	consoleError: typeof console.error;
+	consoleDebug: typeof console.debug;
+}
+
+let activeOutputFilterInstalls = 0;
+let outputFilterOriginals: CursorSdkOutputFilterOriginals | undefined;
+
+export function installCursorSdkOutputFilter(): () => void {
+	if (activeOutputFilterInstalls === 0) {
+		outputFilterOriginals = {
+			stdoutWrite: process.stdout.write,
+			stderrWrite: process.stderr.write,
+			consoleLog: console.log,
+			consoleInfo: console.info,
+			consoleWarn: console.warn,
+			consoleError: console.error,
+			consoleDebug: console.debug,
+		};
+		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
+		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr) as typeof process.stderr.write;
+		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
+		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
+		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
+		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
+		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
+	}
+	activeOutputFilterInstalls += 1;
+
+	let restored = false;
+	return () => {
+		if (restored) return;
+		restored = true;
+		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
+		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
+		process.stdout.write = outputFilterOriginals.stdoutWrite;
+		process.stderr.write = outputFilterOriginals.stderrWrite;
+		console.log = outputFilterOriginals.consoleLog;
+		console.info = outputFilterOriginals.consoleInfo;
+		console.warn = outputFilterOriginals.consoleWarn;
+		console.error = outputFilterOriginals.consoleError;
+		console.debug = outputFilterOriginals.consoleDebug;
+		outputFilterOriginals = undefined;
+	};
+}

package/src/cursor-sensitive-text.ts

@@ -0,0 +1,37 @@
+import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function scrubSensitiveText(text: string, apiKey?: string): string {
+	let scrubbed = text;
+	const trimmedKey = apiKey?.trim();
+	if (trimmedKey) {
+		scrubbed = scrubbed.replace(new RegExp(escapeRegExp(trimmedKey), "g"), "[redacted]");
+	}
+	return scrubbed
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+		.replace(/((?:^|[\s,{])cookie["']?\s*[:=]\s*["']?)[^\n]+/gi, "$1[redacted]")
+		.replace(
+			/((?:authorization|api[_-]?key|apiKey|token|session(?:[_-]?id)?)["']?\s*[:=]\s*["']?)[^"'\s,;}]+/gi,
+			"$1[redacted]",
+		);
+}
+
+function scrubDisplayValue(value: unknown, apiKey?: string): unknown {
+	if (typeof value === "string") return scrubSensitiveText(value, apiKey);
+	if (Array.isArray(value)) return value.map((entry) => scrubDisplayValue(entry, apiKey));
+	if (value && typeof value === "object") {
+		return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
+	}
+	return value;
+}
+
+export function scrubPiToolDisplay(display: CursorPiToolDisplay, apiKey?: string): CursorPiToolDisplay {
+	return {
+		...display,
+		args: scrubDisplayValue(display.args, apiKey) as Record<string, unknown>,
+		result: scrubDisplayValue(display.result, apiKey) as CursorPiToolDisplay["result"],
+	};
+}

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,
+};