@emmaneugene/pi-cursor-sdk 0.4.0 → 0.4.2

package/src/cursor-provider-turn-prepare.ts

@@ -20,7 +20,6 @@ import {
 	abandonSessionCursorAgent,
 	createCursorNativeReplayId,
 	cursorLiveRuns,
-	getActiveCursorLiveRunForCurrentScope,
 	getPendingCursorLiveRun,
 } from "./cursor-provider-live-run-drain.js";
 import {
@@ -66,19 +65,22 @@ interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnPara
 	fastEnabled: boolean | undefined;
 }
 
-export function resolveCursorProviderTurnConfig(cwd: string) {
-	return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd: string, projectTrusted = getCursorSessionProjectTrusted()) {
+	return resolveEffectiveCursorConfig({ cwd, projectTrusted });
 }
 
 function buildLocalCursorProviderTurnLifecycle(
 	lease: SessionCursorAgentLease,
 	scopeKey: string,
+	disposeAgentAfterTurn: boolean,
 ): CursorProviderTurnLifecycle {
 	return {
 		trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
 		commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
 		abandon: () => abandonSessionCursorAgent(scopeKey),
-		dispose: async () => {},
+		dispose: async () => {
+			if (disposeAgentAfterTurn) await resetSessionCursorAgent(scopeKey);
+		},
 	};
 }
 
@@ -86,7 +88,7 @@ async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<CursorProviderTurnPrepareResult> {
 	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
-	const { model, context, options } = params;
+	const { model, context, options, runtimeContext } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
 	let sessionAgentScopeKey: string | undefined;
@@ -113,6 +115,7 @@ async function prepareCursorLocalProviderTurn(
 		const queuedBridgeRequestsBeforeLiveRun: CursorPiBridgeToolRequest[] = [];
 		let liveRunForBridgeQueue: CursorLiveRun | undefined;
 		const bridgeExcludeToolNames = buildCursorBridgeExcludeToolNames(resolvedConfig);
+		const localResumeEnabled = runtimeContext?.localResume ?? resolvedConfig.local.resume.value;
 
 		const sessionAgentAcquireParams = {
 			apiKey: resolvedApiKey,
@@ -121,8 +124,12 @@ async function prepareCursorLocalProviderTurn(
 			modelSelection: selection,
 			settingSources,
 			localSafety,
-			localResume: resolvedConfig.local.resume.value,
+			localResume: localResumeEnabled,
 			useHttp1ForAgent,
+			runtimeScope: runtimeContext
+				? { scopeKey: runtimeContext.scopeKey, sessionFile: runtimeContext.sessionFile }
+				: undefined,
+			bridge: runtimeContext?.bridge,
 			bridgeExcludeToolNames,
 			debugRecorder: sdkEventDebug,
 			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
@@ -185,7 +192,7 @@ async function prepareCursorLocalProviderTurn(
 		};
 		const sessionBridgeRun = bridgeRun;
 		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-		const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+		const useNativeToolReplay = runtimeContext?.nativeToolReplay ?? isCursorNativeToolDisplayRuntimeEnabled();
 		const activeToolNames = getActiveContextToolNames(context);
 		sdkEventDebug?.recordProviderMeta({
 			model: {
@@ -203,7 +210,7 @@ async function prepareCursorLocalProviderTurn(
 			toolManifestEnabled: resolveCursorToolManifestEnabled(),
 			agentMode,
 			localForce: resolvedConfig.local.force.value,
-			localResume: resolvedConfig.local.resume.value,
+			localResume: localResumeEnabled,
 			resumedAgent: sessionAgentLease.resumed,
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
@@ -266,7 +273,11 @@ async function prepareCursorLocalProviderTurn(
 			sessionAgentLease,
 			localForce: resolvedConfig.local.force,
 			restoreCursorSdkOutputFilter,
-			lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey),
+			lifecycle: buildLocalCursorProviderTurnLifecycle(
+			sessionAgentLease,
+			sessionAgentScopeKey,
+			runtimeContext?.disposeAgentAfterTurn === true,
+		),
 			runtime: liveRun
 				? { kind: "live", liveRun, turnCoordinator }
 				: { kind: "direct", turnCoordinator },

package/src/cursor-provider-turn-runner.ts

@@ -62,7 +62,8 @@ export class CursorProviderTurnRunner {
 
 		try {
 			this.throwIfAborted();
-			const cwd = getCursorSessionCwd();
+			const runtimeContext = this.params.runtimeContext;
+			const cwd = runtimeContext?.cwd ?? getCursorSessionCwd();
 			this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
 				cwd,
 				modelId: model.id,
@@ -70,13 +71,21 @@ export class CursorProviderTurnRunner {
 			});
 			sdkEventDebugRef.current = this.sdkEventDebug;
 			this.sdkEventDebug?.recordContextSnapshot(context);
-			const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
-			const localScopeKey = getCursorSessionScopeKey();
+			const resolvedConfig = resolveCursorProviderTurnConfig(cwd, runtimeContext?.projectTrusted);
+			const localScopeKey = runtimeContext?.scopeKey ?? getCursorSessionScopeKey();
 			sdkProcessErrorGuard.containLocalTransportClosedPipe(() =>
 				invalidateSessionAgent(localScopeKey, { deadTransport: true }),
 			);
 			if (
-				(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+				(await drainExistingCursorLiveRunBeforeSend(
+					stream,
+					partial,
+					model,
+					context,
+					options?.signal,
+					this.sdkEventDebug,
+					localScopeKey,
+				)) ===
 				"stream_ended"
 			) {
 				return;

package/src/cursor-provider-turn-types.ts

@@ -15,6 +15,7 @@ import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinato
 import type { CursorPrompt } from "./context.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
 import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 
 export interface CursorProviderTurnRunnerParams {
 	model: Model<Api>;
@@ -22,6 +23,7 @@ export interface CursorProviderTurnRunnerParams {
 	stream: AssistantMessageEventStream;
 	partial: AssistantMessage;
 	options?: SimpleStreamOptions;
+	runtimeContext?: CursorProviderRuntimeContext;
 	sdkEventDebugRef: { current?: CursorSdkEventDebugSink };
 }
 

package/src/cursor-provider.ts

@@ -23,6 +23,7 @@ import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { CursorProviderTurnRunner } from "./cursor-provider-turn-runner.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { runExclusiveCursorSessionTurn, __testUtils as cursorSessionTurnQueueTestUtils } from "./cursor-session-turn-queue.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -48,6 +49,7 @@ export function streamCursor(
 	model: Model<Api>,
 	context: Context,
 	options?: SimpleStreamOptions,
+	runtimeContext?: CursorProviderRuntimeContext,
 ): AssistantMessageEventStream {
 	const stream = createAssistantMessageEventStream();
 	const sdkEventDebugRef: { current?: CursorSdkEventDebugSink } = {};
@@ -62,13 +64,14 @@ export function streamCursor(
 			stream,
 			partial,
 			options,
+			runtimeContext,
 			sdkEventDebugRef,
 		});
 
 		try {
 			stream.push({ type: "start", partial });
 			await runExclusiveCursorSessionTurn(
-				getCursorSessionScopeKey(),
+				runtimeContext?.scopeKey ?? getCursorSessionScopeKey(),
 				() => runner.run(installCursorSdkProcessErrorGuard()),
 				options?.signal,
 			);

package/src/cursor-session-agent.ts

@@ -4,6 +4,7 @@ import type { Context } from "@earendil-works/pi-ai";
 import {
 	getRegisteredCursorPiToolBridge,
 	type CursorPiBridgeToolRequest,
+	type CursorPiToolBridge,
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
@@ -136,6 +137,8 @@ interface SessionCursorAgentCreateParams {
 	bridgeExcludeToolNames?: ReadonlySet<string>;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
+	runtimeScope?: { scopeKey: string; sessionFile: string | undefined };
+	bridge?: CursorPiToolBridge;
 	localResume?: boolean;
 	forceCreate?: boolean;
 	createAgent?: CursorSdkModule["Agent"]["create"];
@@ -453,16 +456,17 @@ async function createSessionAgentEntry(
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	let sessionStore: OpenCursorSessionStore | undefined;
 	try {
-		const registeredBridge = getRegisteredCursorPiToolBridge();
+		const registeredBridge = params.bridge ?? getRegisteredCursorPiToolBridge();
 		if (registeredBridge) {
-			bridgeRun = await registeredBridge.createRun({
+			const createdBridgeRun = await registeredBridge.createRun({
 				onToolRequest: params.onBridgeToolRequest,
 				debugRecorder: params.debugRecorder,
 				excludeToolNames: params.bridgeExcludeToolNames,
 			});
-			if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
-				await bridgeRun.dispose();
-				bridgeRun = undefined;
+			if (!createdBridgeRun.enabled || !createdBridgeRun.mcpServers) {
+				await createdBridgeRun.dispose();
+			} else {
+				bridgeRun = createdBridgeRun;
 			}
 		}
 
@@ -559,8 +563,8 @@ export function invalidateSessionAgent(
 }
 
 export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
-	const scopeKey = getCursorSessionScopeKey();
-	const persistentStore = getCursorSessionFile() !== undefined;
+	const scopeKey = params.runtimeScope?.scopeKey ?? getCursorSessionScopeKey();
+	const persistentStore = params.runtimeScope ? params.runtimeScope.sessionFile !== undefined : getCursorSessionFile() !== undefined;
 	let forceCreate = params.forceCreate === true;
 
 	while (true) {

package/src/index.ts

@@ -1,8 +1,9 @@
+import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import { discoverModels, type CursorModelFallbackIssue } from "./model-discovery.js";
 import { registerCursorRuntimeControls } from "./cursor-state.js";
 import { registerCursorNativeToolDisplay } from "./cursor-native-tool-display-registration.js";
-import { registerCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { registerCursorPiToolBridge, registerNestedCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
 import { registerCursorQuestionTool } from "./cursor-question-tool.js";
 import { registerCursorSkillTool } from "./cursor-skill-tool.js";
 import { registerCursorSessionScope } from "./cursor-session-scope.js";
@@ -16,6 +17,14 @@ import { registerCursorAgentsContextDedup } from "./cursor-agents-context-regist
 import { registerCursorOverflowNormalization } from "./cursor-provider-overflow.js";
 import { registerCursorSdkSessionProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { prepareCursorSessionForCompaction } from "./cursor-session-compaction-prep.js";
+import { disposeSessionCursorAgent } from "./cursor-session-agent.js";
+import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import type { CursorProviderRuntimeContext } from "./cursor-provider-runtime-context.js";
+import {
+	claimCursorExtensionFactory,
+	registerCursorExtensionFactoryRelease,
+	releaseCursorExtensionFactory,
+} from "./cursor-extension-factory-guard.js";
 
 type CursorExtensionApi =
 	& Pick<ExtensionAPI, "registerProvider" | "registerCommand" | "on">
@@ -31,73 +40,136 @@ type CursorExtensionApi =
 	& Parameters<typeof registerCursorFallbackIssueWarning>[0]
 	& Parameters<typeof registerCursorAgentsContextDedup>[0]
 	& Parameters<typeof registerCursorOverflowNormalization>[0]
-	& Parameters<typeof registerCursorSdkSessionProcessErrorGuard>[0];
+	& Parameters<typeof registerCursorSdkSessionProcessErrorGuard>[0]
+	& Parameters<typeof registerCursorExtensionFactoryRelease>[0];
 
-function createCursorProviderConfig(models: ProviderModelConfig[]): ProviderConfig {
+let activeCursorProviderModels: ProviderModelConfig[] | undefined;
+
+function createCursorProviderConfig(
+	models: ProviderModelConfig[],
+	streamSimple: NonNullable<ProviderConfig["streamSimple"]> = streamCursorLazy,
+): ProviderConfig {
 	return {
 		name: "Cursor",
 		baseUrl: "https://cursor.com",
 		apiKey: CURSOR_API_KEY_CONFIG_VALUE,
 		api: "cursor-sdk",
 		models,
-		streamSimple: streamCursorLazy,
+		streamSimple,
 	};
 }
 
-function registerCursorProvider(pi: Pick<ExtensionAPI, "registerProvider">, models: ProviderModelConfig[]): void {
-	pi.registerProvider("cursor", createCursorProviderConfig(models));
+function registerCursorProvider(
+	pi: Pick<ExtensionAPI, "registerProvider">,
+	models: ProviderModelConfig[],
+	streamSimple?: NonNullable<ProviderConfig["streamSimple"]>,
+): void {
+	pi.registerProvider("cursor", createCursorProviderConfig(models, streamSimple));
 }
 
-export default async function (pi: CursorExtensionApi) {
-	// Session cwd must register before other session_start listeners that depend on it.
-	registerCursorSessionScope(pi);
-	registerCursorSessionAgentLineage(pi);
-	registerCursorSessionAgentLifecycle(pi);
-	registerCursorSessionAgentResume(pi);
-	pi.on("session_before_compact", async () => {
-		await prepareCursorSessionForCompaction();
+function registerNestedCursorProvider(pi: CursorExtensionApi, models: ProviderModelConfig[]): void {
+	const bridge = registerNestedCursorPiToolBridge(pi);
+	const nestedRuntimeId = randomUUID();
+	let runtimeContext: CursorProviderRuntimeContext = {
+		scopeKey: `__nested_cursor__:${nestedRuntimeId}`,
+		cwd: getCursorSessionCwd(),
+		sessionFile: undefined,
+		projectTrusted: getCursorSessionProjectTrusted(),
+		bridge,
+		localResume: false,
+		nativeToolReplay: false,
+		disposeAgentAfterTurn: true,
+	};
+	pi.on("session_start", (_event, ctx) => {
+		const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? undefined;
+		const sessionId = ctx.sessionManager?.getSessionId?.() ?? nestedRuntimeId;
+		runtimeContext = {
+			...runtimeContext,
+			scopeKey: sessionFile ?? `__nested_cursor__:${sessionId}`,
+			cwd: ctx.cwd,
+			sessionFile,
+			projectTrusted: ctx.isProjectTrusted?.() === true || runtimeContext.projectTrusted,
+		};
 	});
-	registerCursorRuntimeControls(pi);
-	registerCursorNativeToolDisplay(pi);
-	registerCursorQuestionTool(pi);
-	registerCursorSkillTool(pi);
-	registerCursorPiToolBridge(pi);
-	registerCursorAgentsContextDedup(pi);
-	registerCursorOverflowNormalization(pi);
-	let fallbackIssue: CursorModelFallbackIssue | undefined;
-	const models = await discoverModels({
-		onFallback: (issue) => {
-			fallbackIssue = issue;
-		},
+	pi.on("session_shutdown", async () => {
+		await disposeSessionCursorAgent(runtimeContext.scopeKey);
 	});
+	registerCursorProvider(pi, models, (model, context, options) =>
+		streamCursorLazy(model, context, options, runtimeContext));
+}
 
-	if (fallbackIssue) {
-		registerCursorFallbackIssueWarning(pi, fallbackIssue);
+export default async function (pi: CursorExtensionApi) {
+	const factoryClaim = claimCursorExtensionFactory();
+	if (factoryClaim.kind === "nested") {
+		if (!activeCursorProviderModels) {
+			throw new Error("Nested Cursor provider loaded before the owner model catalog was ready");
+		}
+		registerNestedCursorProvider(pi, activeCursorProviderModels);
+		return;
 	}
 
-	pi.registerCommand("cursor-refresh-models", {
-		description: "Refresh the live Cursor model catalog without restarting pi",
-		handler: async (_args, ctx) => {
-			let refreshFallbackIssue: CursorModelFallbackIssue | undefined;
-			const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
-			const refreshedModels = await discoverModels({
-				apiKey,
-				forceRefresh: true,
-				onFallback: (issue) => {
-					refreshFallbackIssue = issue;
-				},
-			});
-			registerCursorProvider(pi, refreshedModels);
-			if (!ctx.hasUI) return;
-			if (refreshFallbackIssue) {
-				ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
-			} else {
-				ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
-			}
-		},
-	});
+	try {
+		// Discover first. A discovery failure must not leave process-global
+		// registrars from a discarded extension load.
+		let fallbackIssue: CursorModelFallbackIssue | undefined;
+		const models = await discoverModels({
+			onFallback: (issue) => {
+				fallbackIssue = issue;
+			},
+		});
+		activeCursorProviderModels = models;
+
+		// Session cwd must register before other session_start listeners that depend on it.
+		registerCursorSessionScope(pi);
+		registerCursorSessionAgentLineage(pi);
+		registerCursorSessionAgentLifecycle(pi);
+		registerCursorSessionAgentResume(pi);
+		pi.on("session_before_compact", async () => {
+			await prepareCursorSessionForCompaction();
+		});
+		registerCursorRuntimeControls(pi);
+		registerCursorNativeToolDisplay(pi);
+		registerCursorQuestionTool(pi);
+		registerCursorSkillTool(pi);
+		registerCursorPiToolBridge(pi);
+		registerCursorAgentsContextDedup(pi);
+		registerCursorOverflowNormalization(pi);
+
+		if (fallbackIssue) {
+			registerCursorFallbackIssueWarning(pi, fallbackIssue);
+		}
 
-	registerCursorProvider(pi, models);
-	// Register last so session_shutdown cleanup remains protected until other Cursor handlers finish.
-	registerCursorSdkSessionProcessErrorGuard(pi);
+		pi.registerCommand("cursor-refresh-models", {
+			description: "Refresh the live Cursor model catalog without restarting pi",
+			handler: async (_args, ctx) => {
+				let refreshFallbackIssue: CursorModelFallbackIssue | undefined;
+				const apiKey = resolveCursorApiKey(await ctx.modelRegistry.getApiKeyForProvider("cursor"));
+				const refreshedModels = await discoverModels({
+					apiKey,
+					forceRefresh: true,
+					onFallback: (issue) => {
+						refreshFallbackIssue = issue;
+					},
+				});
+				registerCursorProvider(pi, refreshedModels);
+				if (!ctx.hasUI) return;
+				if (refreshFallbackIssue) {
+					ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
+				} else {
+					ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
+				}
+			},
+		});
+
+		registerCursorProvider(pi, models);
+		// Keep the process error guard near the end so earlier Cursor cleanup
+		// remains protected during session shutdown.
+		registerCursorSdkSessionProcessErrorGuard(pi);
+		// Register last so ownership remains protected until all other Cursor
+		// session_shutdown handlers finish.
+		registerCursorExtensionFactoryRelease(pi, factoryClaim);
+	} catch (error) {
+		releaseCursorExtensionFactory(factoryClaim.token);
+		throw error;
+	}
 }