pi-cursor-sdk 0.5.0 → 0.5.2

package/src/cursor-sdk-runtime.ts

@@ -1,19 +1,18 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { resolveCursorSdkPlatformPackageDirectory } from "./cursor-ripgrep-path.js";
+// Vendor env must initialize before the static @cursor/sdk import below so
+// tree-sitter natives resolve when Pi lives outside this package's node_modules.
+import "./cursor-sdk-vendor-env.js";
+import * as CursorSdk from "@cursor/sdk";
 
-export type CursorSdkModule = typeof import("@cursor/sdk");
+export type CursorSdkModule = typeof CursorSdk;
 
+/**
+ * Load the Cursor SDK module.
+ *
+ * Uses a static import so Pi's compiled-Bun extension graph includes @cursor/sdk
+ * (a runtime dynamic bare import is omitted from that graph; see #228).
+ * `loadCursorSdk` remains async for call-site compatibility and so vendor-env
+ * side effects (imported above) always run before callers receive the module.
+ */
 export async function loadCursorSdk(): Promise<CursorSdkModule> {
-	// The SDK searches launcher ancestors, which miss Pi's separately installed extension packages.
-	if (process.env.CURSOR_TREE_SITTER_VENDOR_DIR === undefined) {
-		const packageDirectory = resolveCursorSdkPlatformPackageDirectory();
-		if (packageDirectory) {
-			const vendor = join(packageDirectory, "vendor");
-			if (existsSync(join(vendor, "tree-sitter", "index.js")) && existsSync(join(vendor, "tree-sitter-bash", "index.js"))) {
-				process.env.CURSOR_TREE_SITTER_VENDOR_DIR = vendor;
-			}
-		}
-	}
-	return import("@cursor/sdk");
+	return CursorSdk;
 }

package/src/cursor-sdk-vendor-env.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCursorSdkPlatformPackageDirectory } from "./cursor-ripgrep-path.js";
+
+/**
+ * Ensure CURSOR_TREE_SITTER_VENDOR_DIR is set before @cursor/sdk first loads.
+ * Must run as a side effect of importing this module (before a static SDK import).
+ */
+export function ensureCursorTreeSitterVendorDir(): void {
+	if (process.env.CURSOR_TREE_SITTER_VENDOR_DIR !== undefined) return;
+	const packageDirectory = resolveCursorSdkPlatformPackageDirectory();
+	if (!packageDirectory) return;
+	const vendor = join(packageDirectory, "vendor");
+	if (
+		existsSync(join(vendor, "tree-sitter", "index.js")) &&
+		existsSync(join(vendor, "tree-sitter-bash", "index.js"))
+	) {
+		process.env.CURSOR_TREE_SITTER_VENDOR_DIR = vendor;
+	}
+}
+
+ensureCursorTreeSitterVendorDir();

package/src/cursor-session-agent-cleanup.ts

@@ -16,9 +16,9 @@ import {
 	type CursorSessionAgentResumeScope,
 } from "./cursor-session-agent-resume.js";
 import {
-	cursorSessionStoreIdentitiesEqual,
-	getCursorSessionStoreIdentities,
+	withCursorSessionStoreIdentities,
 	openCursorSessionStore,
+	resolveCursorSessionStoreIdentity,
 } from "./cursor-session-store.js";
 
 export const CURSOR_SESSION_AGENT_CLEANUP_ENTRY_TYPE = "cursor-sdk-agent-cleanup";
@@ -264,7 +264,7 @@ function appendDurableCleanupEntry(
 	return fsyncExistingRegularFile(sessionFile);
 }
 
-export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext): Promise<void> {
+export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext, storeRoot?: string): Promise<void> {
 	const usage = "Usage: /cursor-local-resume-cleanup [--dry-run|--yes]";
 	const tokens = args.trim().split(/\s+/).filter(Boolean);
 	const dryRun = tokens.length === 0 || (tokens.length === 1 && tokens[0] === "--dry-run");
@@ -299,7 +299,7 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 		return;
 	}
 
-	if (!appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
+	if (!scope.sessionFile || !appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
 		ctx.ui.notify("Cleanup intent could not be durably recorded. No agents were deleted.", "error");
 		return;
 	}
@@ -308,31 +308,32 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 	const failedAgentIds: CursorSessionAgentCleanupFailure[] = [];
 	const openedStores = new Map<string, Awaited<ReturnType<typeof openCursorSessionStore>>>();
 	try {
-		const operations = await getSdkOperations();
-		const identities = await getCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, scope.sessionFile !== undefined);
-		for (const candidate of plan.candidates) {
-			const { agentId } = candidate;
-			try {
-				const identity = candidate.storeIdentity ?? identities.defaultStore;
-				if (
-					!cursorSessionStoreIdentitiesEqual(identity, identities.defaultStore) &&
-					!cursorSessionStoreIdentitiesEqual(identity, identities.sessionStore)
-				) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
-				let openedStore = openedStores.get(identity.stateRoot);
-				if (!openedStore) {
-					openedStore = await openCursorSessionStore(ctx.cwd, identity);
-					openedStores.set(identity.stateRoot, openedStore);
+		await withCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, storeRoot, async (identities) => {
+			const operations = await getSdkOperations();
+			for (const candidate of plan.candidates) {
+				const { agentId } = candidate;
+				try {
+					const identity = await resolveCursorSessionStoreIdentity({
+						cwd: ctx.cwd, scopeKey: scope.scopeKey,
+						identities, recordedIdentity: candidate.storeIdentity, agentId,
+					});
+					if (!identity) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
+					let openedStore = openedStores.get(identity.stateRoot);
+					if (!openedStore) {
+						openedStore = await openCursorSessionStore(ctx.cwd, identity, identities.workspaceRoot, identities.storeRoot);
+						openedStores.set(identity.stateRoot, openedStore);
+					}
+					await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
+					deletedAgentIds.push(agentId);
+				} catch (error) {
+					failedAgentIds.push({
+						agentId,
+						error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
+						...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
+					});
 				}
-				await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
-				deletedAgentIds.push(agentId);
-			} catch (error) {
-				failedAgentIds.push({
-					agentId,
-					error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
-					...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
-				});
 			}
-		}
+		});
 	} catch (error) {
 		const message = scrubSensitiveText(getString(asRecord(error), "message") ?? String(error));
 		failedAgentIds.push(...plan.candidateAgentIds.map((agentId) => ({ agentId, error: message })));

package/src/cursor-session-agent.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import type { AgentModeOption, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
+import type { AgentModeOption, AgentOptions, LocalAgentOptions, LocalAgentStore, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
+import { normalizeCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiToolBridge,
@@ -47,6 +48,7 @@ export interface SessionCursorAgentLease {
 
 interface SessionCursorAgentPoolEntryBase {
 	poolKey: string;
+	storeRoot: string | undefined;
 	instanceId: number;
 	scopeKey: string;
 	sendState: SessionCursorAgentSendState;
@@ -113,10 +115,14 @@ function assertScopeAcceptsAcquire(scopeKey: string): void {
 	terminalDisposedScopeGenerations.delete(scopeKey);
 }
 
-function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey: string, poolKey: string, error: unknown): void {
+function samePoolIdentity(entry: SessionCursorAgentPoolEntryBase, poolKey: string, capturedStoreRoot: string | undefined): boolean {
+	return entry.poolKey === poolKey && entry.storeRoot === capturedStoreRoot;
+}
+
+function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey: string, poolKey: string, storeRoot: string | undefined, error: unknown): void {
 	if (!(error instanceof SessionCursorAgentCreationSupersededError)) return;
 	const replacement = sessionAgentsByScope.get(scopeKey);
-	if (replacement && replacement.poolKey !== poolKey) {
+	if (replacement && !samePoolIdentity(replacement, poolKey, storeRoot)) {
 		throw error;
 	}
 }
@@ -130,10 +136,12 @@ interface SessionCursorAgentCreateParams {
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
 	localSafety?: CursorLocalSafetyOptions;
+	agents?: AgentOptions["agents"];
 	useHttp1ForAgent?: boolean;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
 	localResume?: boolean;
+	storeRoot?: string;
 	forceCreate?: boolean;
 	createAgent?: CursorSdkModule["Agent"]["create"];
 	resumeAgent?: CursorSdkModule["Agent"]["resume"];
@@ -213,6 +221,21 @@ function buildBridgePoolKeySuffix(registeredBridge: CursorPiToolBridge | undefin
 	return registeredBridge.getToolSurfaceSignature();
 }
 
+function buildCustomSubagentPoolKeySuffix(agents: AgentOptions["agents"]): string[] {
+	const definitions = Object.entries(agents ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	if (!definitions.length) return [];
+	const content = definitions.map(([name, entry]) => [
+		name, entry.description, entry.prompt,
+		entry.model === undefined ? null : entry.model === "inherit" ? "inherit" : {
+			id: entry.model.id,
+			params: [...(entry.model.params ?? [])].sort((a, b) =>
+				a.id < b.id ? -1 : a.id > b.id ? 1 : a.value < b.value ? -1 : a.value > b.value ? 1 : 0)
+				.map(({ id, value }) => ({ id, value })),
+		},
+	]);
+	return [`subagents:${createHash("sha256").update(JSON.stringify(content)).digest("hex")}`];
+}
+
 function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCreateParams): string {
 	return [
 		scopeKey,
@@ -227,6 +250,7 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 				: "http1:off",
 		buildApiKeyPoolKeyFingerprint(params.apiKey),
 		buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
+		...buildCustomSubagentPoolKeySuffix(params.agents),
 	].join("\0");
 }
 
@@ -410,10 +434,10 @@ function leaseFromEntry(
 	};
 }
 
-function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string): SessionCursorAgentReadyEntry | undefined {
+function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string, storeRoot: string | undefined): SessionCursorAgentReadyEntry | undefined {
 	const current = sessionAgentsByScope.get(scopeKey);
 	if (current?.status !== "ready") return undefined;
-	if (current.poolKey !== poolKey) return undefined;
+	if (!samePoolIdentity(current, poolKey, storeRoot)) return undefined;
 	return current;
 }
 
@@ -432,7 +456,7 @@ async function tryLeaseReadyEntry(
 		await disposePoolEntryForScope(scopeKey);
 		return undefined;
 	}
-	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey);
+	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey, params.storeRoot);
 	if (!readyEntry) return undefined;
 	return leaseFromEntry(readyEntry, scopeKey, params, created);
 }
@@ -473,11 +497,10 @@ async function createSessionAgentEntry(
 			cwd: params.cwd,
 			scopeKey,
 			persistent: persistentStore,
-			hasResumeHandle: resumeHandle !== undefined,
-			resumeIdentity: resumeHandle?.storeIdentity,
+			storeRoot: params.storeRoot,
+			resume: resumeHandle ? { identity: resumeHandle.storeIdentity, agentId: resumeHandle.agentId } : undefined,
 		});
 		sessionStore = storeSelection.sessionStore;
-		const { identities } = storeSelection;
 		const resumeAttemptAllowed = storeSelection.resumeAttemptAllowed;
 		let resumeNotice = storeSelection.resumeFallback ? LOCAL_RESUME_FALLBACK_NOTICE : undefined;
 		const buildAgentOptions = () => ({
@@ -491,6 +514,7 @@ async function createSessionAgentEntry(
 				store: sessionStore!.store,
 			}),
 			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+			...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
 		});
 		let agent: SDKAgent | undefined;
 		let effectiveSendState = sendState;
@@ -502,9 +526,11 @@ async function createSessionAgentEntry(
 				resumed = true;
 			} catch {
 				if (persistentStore) resumeNotice = LOCAL_RESUME_FALLBACK_NOTICE;
-				if (!cursorSessionStoreIdentitiesEqual(sessionStore.identity, identities.sessionStore)) {
+				if (storeSelection.persistent && !cursorSessionStoreIdentitiesEqual(sessionStore.identity, storeSelection.identities.sessionStore)) {
+					const { identities } = storeSelection;
+					const replacement = await openCursorSessionStore(params.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
 					await sessionStore.dispose().catch(() => undefined);
-					sessionStore = await openCursorSessionStore(params.cwd, identities.sessionStore);
+					sessionStore = replacement;
 				}
 			}
 		}
@@ -515,6 +541,7 @@ async function createSessionAgentEntry(
 		return {
 			status: "ready",
 			poolKey: resolvedPoolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			agent,
@@ -552,6 +579,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 	const params = { ...input, bridge: "bridge" in input ? input.bridge : getRegisteredCursorPiToolBridge() };
 	const scopeKey = params.scope?.scopeKey ?? getCursorSessionScopeKey();
 	const persistentStore = (params.scope ? params.scope.sessionFile : getCursorSessionFile()) !== undefined;
+	params.storeRoot = persistentStore && params.storeRoot !== undefined ? normalizeCursorCustomStoreRoot(params.storeRoot) : undefined;
 
 	while (true) {
 		assertScopeAcceptsAcquire(scopeKey);
@@ -562,7 +590,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		const poolKey = buildSessionAgentPoolKey(scopeKey, params);
 		const state = getSessionCursorAgentPoolState(scopeKey);
 
-		if ((state.status === "ready" || state.status === "busy") && state.poolKey !== poolKey) {
+		if ((state.status === "ready" || state.status === "busy") && !samePoolIdentity(state, poolKey, params.storeRoot)) {
 			await disposePoolEntryForScope(scopeKey);
 			continue;
 		}
@@ -579,7 +607,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		}
 
 		if (state.status === "creating") {
-			if (state.poolKey !== poolKey) {
+			if (!samePoolIdentity(state, poolKey, params.storeRoot)) {
 				await disposePoolEntryForScope(scopeKey);
 				continue;
 			}
@@ -588,7 +616,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 			} catch (error) {
 				if (error instanceof SessionCursorAgentCreationSupersededError) {
 					assertScopeAcceptsAcquire(scopeKey);
-					rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+					rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 					continue;
 				}
 				throw error;
@@ -618,6 +646,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 		placeholder = {
 			status: "creating",
 			poolKey,
+			storeRoot: params.storeRoot,
 			instanceId,
 			scopeKey,
 			sendState,
@@ -637,7 +666,7 @@ export async function acquireSessionCursorAgent(input: SessionCursorAgentCreateP
 			}
 			if (error instanceof SessionCursorAgentCreationSupersededError) {
 				assertScopeAcceptsAcquire(scopeKey);
-				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+				rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey, params.storeRoot, error);
 				continue;
 			}
 			throw error;
@@ -680,8 +709,6 @@ export const __testUtils = {
 	resetSessionCursorAgent,
 	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
-	buildApiKeyPoolKeyFingerprint,
-	buildSessionAgentPoolKey,
 	setDeadTransportAgentDisposeTimeoutMs(ms: number): number {
 		const previous = deadTransportAgentDisposeTimeoutMs;
 		deadTransportAgentDisposeTimeoutMs = ms;

package/src/cursor-session-send-policy.ts

@@ -21,14 +21,14 @@ export interface CursorSessionSendPlan {
 	reason: CursorSessionSendReason;
 }
 
-export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context): CursorSessionSendPlan {
+export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context, nativeSourceRoles?: readonly string[]): CursorSessionSendPlan {
 	if (!sendState.bootstrapped) {
 		return { mode: "bootstrap", resetAgent: false, reason: "initial" };
 	}
 	if (sendState.incrementalSendCount >= MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP) {
 		return { mode: "bootstrap", resetAgent: true, reason: "incremental_threshold" };
 	}
-	if (shouldBootstrapCursorContext(sendState, context)) {
+	if (shouldBootstrapCursorContext(sendState, context, nativeSourceRoles)) {
 		return { mode: "bootstrap", resetAgent: true, reason: "context_divergence" };
 	}
 	return { mode: "incremental", resetAgent: false, reason: "incremental" };