pi-cursor-sdk 0.1.19 → 0.1.21

package/src/cursor-session-agent.ts

@@ -7,7 +7,7 @@ import type {
 } 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 { AgentModeOption, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
 import {
 	getRegisteredCursorPiToolBridge,
@@ -26,22 +26,53 @@ export interface SessionCursorAgentSendState {
 
 export interface SessionCursorAgentLease {
 	scopeKey: string;
+	poolKey: string;
+	instanceId: number;
 	agent: SDKAgent;
 	bridgeRun?: CursorPiToolBridgeRun;
 	sendState: SessionCursorAgentSendState;
 	created: boolean;
+	commitSend(context: Context, bootstrapped: boolean): void;
+	trackRunCompletion(completion: Promise<unknown>): void;
 }
 
-interface SessionCursorAgentPoolEntry {
+interface SessionCursorAgentPoolEntryBase {
 	poolKey: string;
+	instanceId: number;
 	scopeKey: string;
-	agent?: SDKAgent;
-	bridgeRun?: CursorPiToolBridgeRun;
 	sendState: SessionCursorAgentSendState;
-	creating?: Promise<SessionCursorAgentPoolEntry>;
-	creationGeneration?: number;
 }
 
+interface SessionCursorAgentCreatingEntry extends SessionCursorAgentPoolEntryBase {
+	status: "creating";
+	creating: Promise<SessionCursorAgentReadyEntry>;
+	creationGeneration: number;
+}
+
+interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
+	status: "ready";
+	agent: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+}
+
+interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
+	status: "busy";
+	agent: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+	completionSettled: Promise<void>;
+	pendingCompletion: Promise<void>;
+	releaseBusyWait: () => void;
+	busyGeneration: number;
+}
+
+type SessionCursorAgentActiveEntry = SessionCursorAgentReadyEntry | SessionCursorAgentBusyEntry;
+type SessionCursorAgentPoolEntry =
+	| SessionCursorAgentCreatingEntry
+	| SessionCursorAgentReadyEntry
+	| SessionCursorAgentBusyEntry;
+
+type SessionCursorAgentPoolState = { status: "empty" } | SessionCursorAgentPoolEntry;
+
 class SessionCursorAgentCreationSupersededError extends Error {
 	constructor() {
 		super("Cursor session agent creation was superseded");
@@ -72,6 +103,7 @@ function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey: string, poolK
 
 interface SessionCursorAgentCreateParams {
 	apiKey: string;
+	agentMode: AgentModeOption;
 	cwd: string;
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
@@ -92,6 +124,20 @@ const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
 const invalidatedScopeKeys = new Set<string>();
 const terminalDisposedScopeKeys = new Set<string>();
 const scopeCreationGenerations = new Map<string, number>();
+const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
+let nextSessionAgentInstanceId = 1;
+
+function allocateSessionAgentInstanceId(): number {
+	return nextSessionAgentInstanceId++;
+}
+
+function getSessionCursorAgentPoolState(scopeKey: string): SessionCursorAgentPoolState {
+	return sessionAgentsByScope.get(scopeKey) ?? EMPTY_POOL_STATE;
+}
+
+function isActivePoolEntry(entry: SessionCursorAgentPoolEntry | undefined): entry is SessionCursorAgentActiveEntry {
+	return entry?.status === "ready" || entry?.status === "busy";
+}
 
 function getScopeCreationGeneration(scopeKey: string): number {
 	return scopeCreationGenerations.get(scopeKey) ?? 0;
@@ -131,13 +177,13 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 }
 
 async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<void> {
+	if (!isActivePoolEntry(entry)) return;
 	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 {
@@ -153,10 +199,12 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 	const entry = sessionAgentsByScope.get(scopeKey);
 	invalidatedScopeKeys.delete(scopeKey);
 	if (!entry) return;
-	const orphanedCreating = entry.creating;
 	sessionAgentsByScope.delete(scopeKey);
-	if (entry.creating || !entry.agent) {
-		orphanedCreating?.catch(() => {
+	if (entry.status === "busy") {
+		entry.releaseBusyWait();
+	}
+	if (entry.status === "creating") {
+		entry.creating.catch(() => {
 			// In-flight Agent.create was orphaned by scope disposal; active waiters surface errors elsewhere.
 		});
 		return;
@@ -169,14 +217,96 @@ function createInitialSendState(): SessionCursorAgentSendState {
 }
 
 function bindBridgeToolRequest(
-	entry: SessionCursorAgentPoolEntry,
+	entry: SessionCursorAgentActiveEntry,
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void,
 ): void {
 	entry.bridgeRun?.setOnToolRequest(onBridgeToolRequest);
 }
 
+function commitSessionAgentSendForLease(
+	scopeKey: string,
+	poolKey: string,
+	instanceId: number,
+	context: Context,
+	bootstrapped: boolean,
+): void {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!isActivePoolEntry(entry)) return;
+	if (entry.poolKey !== poolKey || entry.instanceId !== instanceId) return;
+	entry.sendState.bootstrapped = bootstrapped || entry.sendState.bootstrapped;
+	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
+	if (bootstrapped) {
+		entry.sendState.incrementalSendCount = 0;
+		return;
+	}
+	entry.sendState.incrementalSendCount += 1;
+}
+
+function normalizeRunCompletion(completion: Promise<unknown>): Promise<void> {
+	return Promise.resolve(completion).then(
+		() => undefined,
+		() => undefined,
+	);
+}
+
+function buildBusyPoolEntry(
+	entry: SessionCursorAgentActiveEntry,
+	completionSettled: Promise<void>,
+): SessionCursorAgentBusyEntry {
+	let releaseBusyWait = (): void => {};
+	const releaseSignal = new Promise<"released">((resolve) => {
+		releaseBusyWait = () => resolve("released");
+	});
+	const pendingCompletion = Promise.race([
+		completionSettled.then(() => "completed" as const),
+		releaseSignal,
+	]).then((outcome) => {
+		const current = sessionAgentsByScope.get(entry.scopeKey);
+		if (
+			outcome === "completed" &&
+			current?.status === "busy" &&
+			current.poolKey === entry.poolKey &&
+			current.instanceId === entry.instanceId &&
+			current.pendingCompletion === pendingCompletion
+		) {
+			sessionAgentsByScope.set(entry.scopeKey, { ...current, status: "ready" });
+		}
+	});
+
+	return {
+		...entry,
+		status: "busy",
+		completionSettled,
+		pendingCompletion,
+		releaseBusyWait,
+		busyGeneration: getScopeCreationGeneration(entry.scopeKey),
+	};
+}
+
+function trackSessionAgentRunCompletionForLease(
+	scopeKey: string,
+	poolKey: string,
+	instanceId: number,
+	completion: Promise<unknown>,
+): void {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!isActivePoolEntry(entry)) return;
+	if (entry.poolKey !== poolKey || entry.instanceId !== instanceId) return;
+
+	const completionToTrack = normalizeRunCompletion(completion);
+	const completionSettled = (entry.status === "busy"
+		? Promise.all([entry.completionSettled, completionToTrack]).then(() => undefined)
+		: completionToTrack
+	);
+	if (entry.status === "busy") {
+		entry.releaseBusyWait();
+	}
+
+	sessionAgentsByScope.set(scopeKey, buildBusyPoolEntry(entry, completionSettled));
+}
+
 function leaseFromEntry(
-	entry: SessionCursorAgentPoolEntry,
+	entry: SessionCursorAgentReadyEntry,
 	scopeKey: string,
 	params: SessionCursorAgentCreateParams,
 	created: boolean,
@@ -185,18 +315,54 @@ function leaseFromEntry(
 	entry.bridgeRun?.setDebugRecorder(params.debugRecorder);
 	return {
 		scopeKey,
-		agent: entry.agent!,
+		poolKey: entry.poolKey,
+		instanceId: entry.instanceId,
+		agent: entry.agent,
 		bridgeRun: entry.bridgeRun,
 		sendState: entry.sendState,
 		created,
+		commitSend: (context, bootstrapped) => {
+			commitSessionAgentSendForLease(scopeKey, entry.poolKey, entry.instanceId, context, bootstrapped);
+		},
+		trackRunCompletion: (completion) => {
+			trackSessionAgentRunCompletionForLease(scopeKey, entry.poolKey, entry.instanceId, completion);
+		},
 	};
 }
 
-async function createSessionAgentEntry(
+function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string): SessionCursorAgentReadyEntry | undefined {
+	const current = sessionAgentsByScope.get(scopeKey);
+	if (current?.status !== "ready") return undefined;
+	if (current.poolKey !== poolKey) return undefined;
+	return current;
+}
+
+async function tryLeaseReadyEntry(
+	entry: SessionCursorAgentActiveEntry,
 	scopeKey: string,
+	params: SessionCursorAgentCreateParams,
 	poolKey: string,
+	created: boolean,
+): Promise<SessionCursorAgentLease | undefined> {
+	if (entry.status === "busy") {
+		await entry.pendingCompletion;
+	}
+	assertScopeAcceptsAcquire(scopeKey);
+	if (invalidatedScopeKeys.has(scopeKey)) {
+		await disposePoolEntryForScope(scopeKey);
+		return undefined;
+	}
+	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey);
+	if (!readyEntry) return undefined;
+	return leaseFromEntry(readyEntry, scopeKey, params, created);
+}
+
+async function createSessionAgentEntry(
+	scopeKey: string,
+	instanceId: number,
+	sendState: SessionCursorAgentSendState,
 	params: SessionCursorAgentCreateParams,
-): Promise<SessionCursorAgentPoolEntry> {
+): Promise<SessionCursorAgentReadyEntry> {
 	const registeredBridge = getRegisteredCursorPiToolBridge();
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	if (registeredBridge) {
@@ -217,6 +383,7 @@ async function createSessionAgentEntry(
 		agent = await createAgent({
 			apiKey: params.apiKey,
 			model: params.modelSelection,
+			mode: params.agentMode,
 			local: params.settingSources ? { cwd: params.cwd, settingSources: params.settingSources } : { cwd: params.cwd },
 			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
 		});
@@ -233,11 +400,13 @@ async function createSessionAgentEntry(
 	}
 
 	return {
+		status: "ready",
 		poolKey: resolvedPoolKey,
+		instanceId,
 		scopeKey,
 		agent,
 		bridgeRun,
-		sendState: createInitialSendState(),
+		sendState,
 	};
 }
 
@@ -249,95 +418,102 @@ export {
 } from "./cursor-session-send-policy.js";
 export { shouldBootstrapCursorContext, 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);
-	if (bootstrapped) {
-		entry.sendState.incrementalSendCount = 0;
-		return;
-	}
-	entry.sendState.incrementalSendCount += 1;
-}
-
 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);
-	}
+	while (true) {
+		assertScopeAcceptsAcquire(scopeKey);
+		if (invalidatedScopeKeys.has(scopeKey)) {
+			await disposePoolEntryForScope(scopeKey);
+		}
 
-	if (existing && existing.poolKey !== poolKey) {
-		await disposePoolEntryForScope(scopeKey);
-	}
+		const poolKey = buildSessionAgentPoolKey(scopeKey, params);
+		const state = getSessionCursorAgentPoolState(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 {
+		if ((state.status === "ready" || state.status === "busy") && state.poolKey !== poolKey) {
+			await disposePoolEntryForScope(scopeKey);
+			continue;
+		}
+
+		if (state.status === "ready") {
+			return leaseFromEntry(state, scopeKey, params, false);
+		}
+
+		if (state.status === "busy") {
+			const busyGeneration = state.busyGeneration;
+			await state.pendingCompletion;
+			if (busyGeneration !== getScopeCreationGeneration(scopeKey)) continue;
+			continue;
+		}
+
+		if (state.status === "creating") {
+			if (state.poolKey !== poolKey) {
+				await disposePoolEntryForScope(scopeKey);
+				continue;
+			}
+			try {
+				await state.creating;
+			} catch (error) {
+				if (error instanceof SessionCursorAgentCreationSupersededError) {
+					assertScopeAcceptsAcquire(scopeKey);
+					rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+					continue;
+				}
 				throw error;
 			}
+			continue;
 		}
-		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);
+		assertScopeAcceptsAcquire(scopeKey);
+		const creationGeneration = getScopeCreationGeneration(scopeKey);
+		const instanceId = allocateSessionAgentInstanceId();
+		const sendState = createInitialSendState();
+		let placeholder: SessionCursorAgentCreatingEntry;
+		const creating = createSessionAgentEntry(scopeKey, instanceId, sendState, 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 = {
+			status: "creating",
+			poolKey,
+			instanceId,
+			scopeKey,
+			sendState,
+			creationGeneration,
+			creating,
+		};
+		sessionAgentsByScope.set(scopeKey, placeholder);
+
+		try {
+			const createdEntry = await creating;
+			const lease = await tryLeaseReadyEntry(createdEntry, scopeKey, params, poolKey, true);
+			if (lease) return lease;
+			continue;
+		} catch (error) {
 			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);
+			if (error instanceof SessionCursorAgentCreationSupersededError) {
+				assertScopeAcceptsAcquire(scopeKey);
+				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+				continue;
+			}
+			throw error;
 		}
-		throw error;
 	}
 }
 
@@ -383,6 +559,7 @@ export function registerCursorSessionAgent(_pi: CursorSessionAgentExtensionApi):
 
 export const __testUtils = {
 	sessionAgentsByScope,
+	getSessionCursorAgentPoolState,
 	invalidateSessionAgent,
 	disposeSessionCursorAgent,
 	resetSessionCursorAgent,

package/src/cursor-setting-sources.ts

@@ -1,17 +1,14 @@
 import type { SettingSource } from "@cursor/sdk";
+/** Provider-facing wrapper; canonical parsing lives in shared/cursor-setting-sources.mjs. */
+import {
+	CURSOR_SETTING_SOURCES_ENV as CURSOR_SETTING_SOURCES_ENV_JS,
+	resolveCursorSettingSources as resolveCursorSettingSourcesJs,
+} from "../shared/cursor-setting-sources.mjs";
 
-export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+export const CURSOR_SETTING_SOURCES_ENV = CURSOR_SETTING_SOURCES_ENV_JS;
 
 export function resolveCursorSettingSources(raw?: string): SettingSource[] | undefined {
-	const trimmed = raw?.trim();
-	if (!trimmed) return ["all"];
-	const normalized = trimmed.toLowerCase();
-	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
-	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
-	return trimmed
-		.split(",")
-		.map((entry) => entry.trim())
-		.filter((entry): entry is SettingSource => Boolean(entry));
+	return resolveCursorSettingSourcesJs(raw) as SettingSource[] | undefined;
 }
 
 export function getEffectiveCursorSettingSources(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): SettingSource[] | undefined {