pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-pi-tool-bridge-types.ts

@@ -60,6 +60,9 @@ export interface CursorPiToolBridgeRun {
 	resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void>;
 	resolveToolResultsFromContext(context: Context): Promise<void>;
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
+	hasPendingToolCalls(): boolean;
+	/** Synchronous changes; observer errors cannot affect settlement. Returns an idempotent unsubscribe. */
+	onPendingToolCallsChanged(listener: () => void): () => void;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;
 	setDebugRecorder(recorder?: CursorSdkEventDebugRecorder): void;

package/src/cursor-pi-tool-bridge.ts

@@ -46,6 +46,8 @@ export {
 	buildCursorPiToolBridgeSurfaceSignature,
 } from "./cursor-pi-tool-bridge-snapshot.js";
 
+const bridges = new Map<object, CursorPiToolBridgeRegistry>();
+const activeCallsByPi = new Map<object, Set<string>>();
 let registeredCursorPiToolBridge: CursorPiToolBridgeRegistry | undefined;
 
 const WINDOWS_BRIDGE_ABORT_ENV = "PI_CURSOR_BRIDGE_TOOL_CALL_ID";
@@ -89,17 +91,25 @@ Get-CimInstance Win32_Process -Filter "Name = 'bash.exe' OR Name = 'sh.exe'" |
 }
 
 export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
-	bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
-	void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
+	const previous = bridges.get(pi);
+	if (previous) {
+		const reason = "Cursor pi tool bridge extension reloaded";
+		for (const id of activeCallsByPi.get(pi) ?? []) bridgeToolExecutionAbortTracker.abort(id, reason);
+		void previous.disposeAll(reason);
+	}
 	const bridge = new CursorPiToolBridgeRegistry(pi);
 	registeredCursorPiToolBridge = bridge;
+	bridges.set(pi, bridge);
+	const activeCalls = new Set<string>();
+	activeCallsByPi.set(pi, activeCalls);
 	pi.on("tool_call", (event, ctx) => {
-		if (registeredCursorPiToolBridge !== bridge) return undefined;
+		if (bridges.get(pi) !== bridge) return undefined;
 		if (!bridge.hasPendingPiToolCallId(event.toolCallId)) {
 			return isCursorPiBridgeToolCallId(event.toolCallId)
 				? { block: true, reason: "Cursor pi bridge tool call is no longer pending" }
 				: undefined;
 		}
+		activeCalls.add(event.toolCallId);
 		const windowsAbortMarker = installWindowsBridgeBashAbortMarker(event);
 		const trackingStarted = bridgeToolExecutionAbortTracker.track(event.toolCallId, {
 			signal: ctx.signal,
@@ -115,18 +125,23 @@ export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi):
 		return { block: true, reason: "Cursor pi bridge tool execution was aborted before it started" };
 	});
 	pi.on("tool_result", (event) => {
-		bridgeToolExecutionAbortTracker.finish(event.toolCallId);
+		if (activeCalls.delete(event.toolCallId)) bridgeToolExecutionAbortTracker.finish(event.toolCallId);
 	});
 	pi.on("session_shutdown", async (event) => {
+		if (bridges.get(pi) !== bridge) return;
 		const reason = `Cursor pi tool bridge session shutdown: ${event.reason}`;
-		bridgeToolExecutionAbortTracker.abortAll(reason);
+		for (const id of activeCalls) bridgeToolExecutionAbortTracker.abort(id, reason);
+		activeCalls.clear();
+		bridges.delete(pi);
+		activeCallsByPi.delete(pi);
+		if (registeredCursorPiToolBridge === bridge) registeredCursorPiToolBridge = [...bridges.values()].at(-1);
 		await bridge.disposeAll(reason);
 	});
 	return bridge;
 }
 
-export function getRegisteredCursorPiToolBridge(): CursorPiToolBridge | undefined {
-	return registeredCursorPiToolBridge;
+export function getRegisteredCursorPiToolBridge(pi?: object): CursorPiToolBridge | undefined {
+	return pi ? bridges.get(pi) : registeredCursorPiToolBridge;
 }
 
 export const __testUtils = {
@@ -159,8 +174,10 @@ export const __testUtils = {
 	},
 	resetRegisteredBridgeForTests() {
 		bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge test reset");
-		const bridge = registeredCursorPiToolBridge;
+		const registered = [...bridges.values()];
+		bridges.clear();
+		activeCallsByPi.clear();
 		registeredCursorPiToolBridge = undefined;
-		return bridge?.disposeAll("Cursor pi tool bridge test reset") ?? Promise.resolve();
+		return Promise.all(registered.map((bridge) => bridge.disposeAll("Cursor pi tool bridge test reset")));
 	},
 };

package/src/cursor-provider-binding.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Model, Provider } from "@earendil-works/pi-ai";
+import { cursorApiKeyAuth, normalizeCursorApiKey, resolveCursorCredentialApiKey } from "./cursor-api-key.js";
+import { discoverModels, type CursorModelFallbackIssue } from "./model-discovery.js";
+import { clearModelListCache } from "./model-list-cache.js";
+import { captureCursorCloudLifecycleRecorder } from "./cursor-cloud-lifecycle.js";
+import { captureCursorUsageRecorder, type CursorUsageRecorder } from "./cursor-usage-ledger.js";
+import { getCursorNativeToolDisplayState } from "./cursor-native-tool-display-state.js";
+import { getRegisteredCursorPiToolBridge } from "./cursor-pi-tool-bridge.js";
+import { createCursorLazyStream } from "./cursor-provider-lazy.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
+import { captureCursorRequestProjection, resolveCursorRequestProvenance, type CursorRequestProjectionSnapshot, type CursorRequestProvenance } from "./cursor-request-provenance.js";
+import type { CursorSdkOutputNoticeHandler } from "./cursor-sdk-output-filter.js";
+
+export const CURSOR_PROVIDER_OWNERSHIP_ERROR = "Cursor provider ownership is unavailable: this request does not belong to the active Cursor registration. Reload this session's extensions to restore its Cursor registration; use independent ModelRuntime instances for sibling sessions.";
+interface ProviderBinding { active: boolean; closed: boolean }
+interface RequestReceipt {
+	binding: ProviderBinding;
+	scope: ReturnType<typeof getCursorSessionScopeSnapshot>;
+	projection: CursorRequestProjectionSnapshot;
+	usageRecorder: CursorUsageRecorder;
+	reportSdkNotice: CursorSdkOutputNoticeHandler;
+}
+const requestOwners = new WeakMap<object, RequestReceipt>();
+
+/** One closure per ExtensionAPI, including direct compaction/tree/bug-report streams. */
+export function registerCursorProviderBinding(
+	pi: Pick<ExtensionAPI, "on" | "registerProvider" | "appendEntry">,
+) {
+	const binding: ProviderBinding = { active: false, closed: false };
+	let registry: ExtensionContext["modelRegistry"] | undefined;
+	const operations = new WeakMap<AbortSignal, CursorRequestProvenance["purpose"]>();
+	pi.on("session_before_compact", (event) => { operations.set(event.signal, "compaction"); });
+	pi.on("session_before_tree", (event) => { operations.set(event.signal, "tree"); });
+	pi.on("before_provider_headers", (event, ctx) => {
+		const notices = new Set<string>();
+		// Pi's SDK supplies this session-owned callback for ordinary and auxiliary
+		// streams. ModelRuntime forwards the same real headers object to the provider.
+		requestOwners.set(event.headers, {
+			binding,
+			scope: getCursorSessionScopeSnapshot(pi),
+			projection: captureCursorRequestProjection(ctx.sessionManager),
+			usageRecorder: captureCursorUsageRecorder(pi, ctx),
+			reportSdkNotice: (kind, message) => {
+				if (!binding.active || binding.closed) return false;
+				if (notices.has(kind)) return;
+				pi.appendEntry("pi-cursor-sdk:capability-notice", { kind, message });
+				if (ctx.hasUI) ctx.ui.notify(message, "warning");
+				else console.warn(message);
+				notices.add(kind);
+			},
+		});
+	});
+	const stream = createCursorLazyStream((model, context, options) => {
+		const headers = options?.headers;
+		const owner = headers && requestOwners.get(headers);
+		if (headers) requestOwners.delete(headers);
+		if (!binding.active || binding.closed) throw new Error("Cursor provider binding is not active. Bind this session's extensions, or reload the session after shutdown.");
+		if (!owner) throw new Error("Cursor provider ownership is unavailable: this call has no native session request receipt. Bare modelRegistry.streamSimple calls are unsupported for Cursor; use the owning AgentSession's stream path or an independent child AgentSession.");
+		if (owner.binding !== binding) throw new Error(CURSOR_PROVIDER_OWNERSHIP_ERROR);
+		return {
+			request: resolveCursorRequestProvenance(owner.projection, model, context, options?.signal && operations.get(options.signal) || "normal"),
+			usageRecorder: owner.usageRecorder,
+			scope: owner.scope,
+			bridge: getRegisteredCursorPiToolBridge(pi),
+			nativeDisplay: getCursorNativeToolDisplayState(pi),
+			recordCloudLifecycle: captureCursorCloudLifecycleRecorder(pi),
+			reportSdkNotice: owner.reportSdkNotice,
+		};
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		if (binding.closed) return;
+		binding.active = true;
+		registry = ctx.modelRegistry;
+		// The genuine extension context supplies composed config auth; startup
+		// selection already has the known baseline, without reading a default store.
+		await registry.refresh({ providers: ["cursor"], allowNetwork: false });
+	});
+	pi.on("session_shutdown", () => { binding.active = false; binding.closed = true; registry = undefined; });
+	return (models: Awaited<ReturnType<typeof discoverModels>>, onCatalog: (issue?: CursorModelFallbackIssue) => void) => {
+		if (binding.closed) return;
+		const toNative = (definitions: typeof models): Model<"cursor-sdk">[] =>
+			definitions.map(({ compat: _compat, ...definition }) => ({
+				...definition, provider: "cursor", api: "cursor-sdk", baseUrl: "https://cursor.com",
+			}));
+		let current = toNative(models);
+		const provider: Provider<"cursor-sdk"> = {
+			id: "cursor", name: "Cursor", baseUrl: "https://cursor.com",
+			auth: { apiKey: cursorApiKeyAuth() },
+			getModels: () => current,
+			stream: stream,
+			streamSimple: stream,
+			async refreshModels(context) {
+				if (binding.closed) return;
+				const resolved = await registry?.getProviderAuth("cursor");
+				context.signal.throwIfAborted();
+				const credential = context.credential;
+				const apiKey = registry
+					? normalizeCursorApiKey(resolved?.auth.apiKey)
+					: credential && credential.type !== "api_key" ? undefined
+						: await resolveCursorCredentialApiKey(credential, async () => process.env.CURSOR_API_KEY);
+				let issue: CursorModelFallbackIssue | undefined;
+				await discoverModels({
+					apiKey, allowNetwork: context.allowNetwork, forceRefresh: context.force, signal: context.signal,
+					onFallback: (next) => { issue = next; },
+					publish: (definitions, update) => context.publish({
+						update: () => {
+							if (binding.closed) return;
+							update();
+							current = toNative(definitions);
+							// Do not infer logout before native composed auth is reachable.
+							if (registry && !apiKey) clearModelListCache();
+							onCatalog(issue);
+						},
+					}),
+				});
+			},
+		};
+		pi.registerProvider(provider);
+	};
+}

package/src/cursor-provider-errors.ts

@@ -6,14 +6,14 @@ import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 export const MISSING_CURSOR_API_KEY_MESSAGE =
 	"Cursor SDK runs require a Cursor SDK API key. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, set CURSOR_API_KEY before starting pi, or restart pi with --api-key.";
 const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request failed. The Cursor SDK API key may be missing, invalid, or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
+	"Cursor SDK request failed without further error details.";
 const AUTH_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request failed because the Cursor SDK API key may be invalid or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const CLOUD_AUTH_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor Cloud Agents request failed because Cloud API authentication rejected the API key. Use a user API key from Cursor Dashboard -> API Keys or a service account API key from Team settings; Team Admin API keys are not supported as Cursor Cloud Agents credentials. Configure the key with /login -> Use an API key -> Cursor, CURSOR_API_KEY, or --api-key, then retry.";
 // Keep "Network error" aligned with pi's agent-level retry classifier.
 const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
-	"Network error: Cursor SDK request failed during network or service I/O. Check your connection; pi will retry automatically when auto-retry is enabled.";
+	"Network error: Cursor SDK request failed during network or service I/O. Check your connection.";
 
 // Keep this phrase aligned with pi's agent-level retry classifier (`provider.?returned.?error`).
 const RETRYABLE_CURSOR_RUN_FAILURE_PREFIX = "Provider returned error: Cursor SDK run failed";
@@ -143,7 +143,10 @@ function collectConnectErrorStacks(error: unknown, record: Record<string, unknow
 
 function isConnectError(error: unknown, record: Record<string, unknown> | undefined): boolean {
 	const name = error instanceof Error ? error.name : getErrorStringField(record, "name");
-	return name === "ConnectError";
+	if (name === "ConnectError") return true;
+	// @cursor/sdk convertConnectError re-wraps backend ConnectErrors (name -> NetworkError,
+	// code -> "unavailable") and leaves the original ConnectError on `.cause` without outer details.
+	return getErrorStringField(asRecord(record?.cause), "name") === "ConnectError";
 }
 
 function isUnauthenticatedConnectCode(code: unknown): boolean {
@@ -160,13 +163,12 @@ function isCursorSdkStallAbortNetworkError(code: unknown, evidence: string, stac
 		/(?:operation was aborted|canceled)/i.test(evidence) &&
 		/(?:AbortError|operation was aborted)/i.test(`${evidence}\n${stackEvidence}`) &&
 		stackEvidence.includes("@cursor/sdk") &&
-		stackEvidence.includes("@connectrpc/connect-node") &&
 		/\b(?:onStall|reportStall|StallDetected)\b/i.test(stackEvidence)
 	);
 }
 
 /**
- * @cursor/sdk@1.0.32 throws internal RetriableError (name/kind "RetriableError") with message
+ * @cursor/sdk@1.0.36 throws internal RetriableError (name/kind "RetriableError") with message
  * "Connection stalled" or "Connection stalled repeatedly" after fetchWithRetry exhausts stalls.
  * The ConnectError is only the cause; the top-level error is not a ConnectError.
  */
@@ -181,30 +183,26 @@ export function isCursorSdkConnectionStalledError(error: unknown): boolean {
 	return /(?:^|[\\/])node_modules[\\/]@cursor[\\/]sdk[\\/]dist[\\/]/.test(stack) || stack.includes("@cursor/sdk");
 }
 
-function isCursorExtensionConnectStack(stack: string): boolean {
-	// pi runs Cursor SDK in Node, where the SDK dynamically imports connect-node.
-	// connect-web is the SDK's Bun/Deno path and is intentionally not classified for supported pi runs.
-	return stack.includes("@connectrpc/connect-node") && /(?:^|[\\/])pi-cursor-sdk(?:[\\/]|$)/.test(stack);
-}
-
 function getCursorConnectSource(error: unknown, record: Record<string, unknown> | undefined): CursorConnectErrorSource {
-	const stack = getErrorStack(error, record);
+	const stack = collectConnectErrorStacks(error, record);
+	// Node/Bun use the SDK's vendored transport; Deno uses connect-web.
 	if (stack.includes("@cursor/sdk")) return "cursor-sdk-stack";
-	if (isCursorExtensionConnectStack(stack)) return "cursor-extension-connect-stack";
-	const details = Array.isArray(record?.details) ? record.details : [];
-	const hasCursorBackendDetails = details.some((detail) => {
-		const type = getErrorStringField(asRecord(detail), "type");
-		return typeof type === "string" && type.startsWith("aiserver.");
-	});
-	if (hasCursorBackendDetails) return "cursor-backend-details";
-	return stack.includes("@connectrpc/connect-node") ? "connect-node-stack" : "generic-connect";
+	let current = record;
+	for (let depth = 0; depth < 3 && current; depth += 1) {
+		const details = Array.isArray(current.details) ? current.details : [];
+		const hasCursorBackendDetails = details.some((detail) => {
+			const type = getErrorStringField(asRecord(detail), "type");
+			return typeof type === "string" && type.startsWith("aiserver.");
+		});
+		if (hasCursorBackendDetails) return "cursor-backend-details";
+		current = asRecord(current.cause);
+	}
+	return "generic-connect";
 }
 
 export type CursorConnectErrorSource =
 	| "cursor-sdk-stack"
-	| "cursor-extension-connect-stack"
 	| "cursor-backend-details"
-	| "connect-node-stack"
 	| "generic-connect";
 
 export type CursorConnectErrorClassification =
@@ -225,20 +223,26 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 	const evidence = collectConnectErrorEvidence(error, record);
 	const stackEvidence = collectConnectErrorStacks(error, record);
 
+	if (isCursorSdkStallAbortNetworkError(code, evidence, stackEvidence)) {
+		return { kind: "network", source: getCursorConnectSource(error, record) };
+	}
+
+	const directAbort = (code === 1 || code === "canceled") &&
+		(causeName === "AbortError" || /AbortError/.test(stack));
+	// The vendored 1.0.36 transport wraps a canceled ConnectError as Unknown.
+	// Require the observed canceled -> AbortError cause chain, not generic text.
+	const wrappedAbort = (code === 2 || code === "unknown") &&
+		causeName === "ConnectError" &&
+		(cause?.code === 1 || cause?.code === "canceled") &&
+		asRecord(cause?.cause)?.name === "AbortError";
 	if (
-		(code === 1 || code === "canceled") &&
+		(directAbort || wrappedAbort) &&
 		Boolean(rawMessage && /(?:operation was aborted|canceled)/i.test(rawMessage)) &&
-		(causeName === "AbortError" || /AbortError/.test(stack)) &&
-		stack.includes("@cursor/sdk") &&
-		stack.includes("@connectrpc/connect-node")
+		stack.includes("@cursor/sdk")
 	) {
 		return { kind: "abort", source: "cursor-sdk-stack" };
 	}
 
-	if (isCursorSdkStallAbortNetworkError(code, evidence, stackEvidence)) {
-		return { kind: "network", source: getCursorConnectSource(error, record) };
-	}
-
 	if (isUnauthenticatedConnectCode(code) || isLikelyAuthError(evidence)) {
 		return { kind: "unauthenticated", source: getCursorConnectSource(error, record) };
 	}
@@ -349,27 +353,47 @@ export function resolveCursorSdkAbortCause(options: {
 	return "unknown";
 }
 
+function formatErrorDetail(error: unknown, apiKey: string | undefined, depth = 0): string {
+	if (depth >= 3) return "";
+	const record = asRecord(error);
+	const message = typeof error === "string" ? error : getErrorStringField(record, "message") ?? "";
+	const name = getErrorStringField(record, "name");
+	const code = getErrorEvidenceField(error, record, "code");
+	const scrub = (text: string, limit: number) => scrubSensitiveText(text, apiKey).trim().slice(0, limit);
+	const scrubbed = [
+		name && name !== "Error" ? `${scrub(name, 120)}:` : "",
+		code ? `(code: ${scrub(code, 120)})` : "",
+		scrub(message, 1600),
+	].filter(Boolean).join(" ");
+	const cause = record?.cause === undefined ? "" : formatErrorDetail(record.cause, apiKey, depth + 1);
+	return cause ? `${scrubbed}\nCaused by: ${cause}` : scrubbed;
+}
+
 export function sanitizeCursorProviderError(
 	error: unknown,
 	apiKey?: string,
 	runtimeTarget?: CursorRuntime,
 ): string {
 	const record = asRecord(error);
-	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	const message = typeof error === "string" ? error : getErrorStringField(record, "message") ?? "";
 	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_API_KEY_MESSAGE;
-	const scrubbed = scrubSensitiveText(message, apiKey).trim();
+	const scrubbed = formatErrorDetail(error, apiKey);
+	// A loader failure is not an auth rejection, even inside an authentication wrapper.
+	if (/\b(?:ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND|ResolveMessage)\b|Cannot find (?:module|package)|does not provide an export named/i.test(scrubbed)) return scrubbed;
 	const integrationMessage = runtimeTarget === "cloud"
-		? formatIntegrationNotConnectedError(error, record, scrubbed, apiKey)
+		? formatIntegrationNotConnectedError(error, record, scrubSensitiveText(message, apiKey).trim(), apiKey)
 		: undefined;
 	if (integrationMessage) return integrationMessage;
 	const connectClassification = classifyCursorConnectError(error);
 	if (
 		(runtimeTarget === "cloud" && getErrorName(error, record) === "AuthenticationError") ||
-		connectClassification?.kind === "unauthenticated" ||
-		isLikelyAuthError(scrubbed)
+		/\b(?:invalid|revoked|expired|missing) (?:user )?api key\b|\bapi key (?:is )?(?:invalid|revoked|expired|missing)\b/i.test(scrubbed)
 	) {
 		return runtimeTarget === "cloud" ? CLOUD_AUTH_CURSOR_SDK_ERROR_MESSAGE : AUTH_CURSOR_SDK_ERROR_MESSAGE;
 	}
+	if (connectClassification?.kind === "unauthenticated" || isLikelyAuthError(scrubbed)) {
+		return `Cursor SDK authentication failed. ${scrubbed}`;
+	}
 	if (connectClassification?.kind === "network" || isCursorSdkConnectionStalledError(error) || isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	if (isGenericCursorRunFailureMessage(scrubbed)) return RETRYABLE_CURSOR_RUN_FAILURE_PREFIX;
 	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;

package/src/cursor-provider-lazy.ts

@@ -7,7 +7,7 @@ import {
 	type Model,
 	type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
-import { streamCursor } from "./cursor-provider.js";
+import { streamCursor, type CursorProviderOwnership } from "./cursor-provider.js";
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 
 function makeProviderRuntimeErrorMessage(model: Model<Api>, error: unknown, apiKey?: string): AssistantMessage {
@@ -31,22 +31,28 @@ function makeProviderRuntimeErrorMessage(model: Model<Api>, error: unknown, apiK
 	};
 }
 
-export function streamCursorLazy(
-	model: Model<Api>,
-	context: Context,
-	options?: SimpleStreamOptions,
-): AssistantMessageEventStream {
-	const outer = createAssistantMessageEventStream();
-	queueMicrotask(async () => {
-		try {
-			for await (const event of streamCursor(model, context, options)) {
-				outer.push(event);
-			}
-		} catch (error) {
+export function createCursorLazyStream(capture: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => CursorProviderOwnership) {
+	return (model: Model<Api>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream => {
+		const outer = createAssistantMessageEventStream();
+		const fail = (error: unknown) => {
 			const message = makeProviderRuntimeErrorMessage(model, error, options?.apiKey);
 			outer.push({ type: "error", reason: "error", error: message });
 			outer.end(message);
+		};
+		let ownership: CursorProviderOwnership;
+		try {
+			ownership = capture(model, context, options);
+		} catch (error) {
+			fail(error);
+			return outer;
 		}
-	});
-	return outer;
+		queueMicrotask(async () => {
+			try {
+				for await (const event of streamCursor(model, context, options, ownership)) outer.push(event);
+			} catch (error) {
+				fail(error);
+			}
+		});
+		return outer;
+	};
 }

package/src/cursor-provider-live-run-drain.ts

@@ -30,13 +30,18 @@ import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-rout
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
+function parseCursorNativeReplayIdleDisposeMs(raw: string | undefined): number {
+	if (!raw || /[^0-9]/.test(raw)) return DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+	const value = Number(raw);
+	return value >= 1 && value <= 2147483647 ? value : DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+}
 const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
 
 interface CursorLiveTurnState {
 	emitter: CursorPartialContentEmitter;
 	emittedText: string;
 }
-let cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+let cursorNativeReplayIdleDisposeMsOverride: number | undefined;
 
 type CursorLiveRunDrainMode = "emit" | "chain_user_input";
 type CursorLiveRunDrainOutcome = "tool_use" | "stop" | "error" | "aborted" | "chain_user_input";
@@ -50,7 +55,7 @@ export async function abandonSessionCursorAgent(scopeKey: string | undefined): P
 }
 
 export const cursorLiveRuns = createCursorLiveRunCoordinator({
-	getIdleDisposeMs: () => cursorNativeReplayIdleDisposeMs,
+	getIdleDisposeMs: () => cursorNativeReplayIdleDisposeMsOverride ?? parseCursorNativeReplayIdleDisposeMs(process.env.PI_CURSOR_LIVE_RUN_IDLE_DISPOSE_MS),
 	deleteNativeToolDisplay: deleteCursorNativeToolDisplay,
 	abandonSessionAgent: (scopeKey) => abandonSessionCursorAgent(scopeKey),
 });
@@ -64,12 +69,12 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId: string): string | und
 	return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
 }
 
-export function getPendingCursorLiveRun(context: Context): CursorLiveRun | undefined {
-	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
+export function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
+	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId, scopeKey);
 }
 
-export function getActiveCursorLiveRunForCurrentScope(): CursorLiveRun | undefined {
-	return cursorLiveRuns.getActiveForScope();
+export function getActiveCursorLiveRunForCurrentScope(scopeKey?: string): CursorLiveRun | undefined {
+	return cursorLiveRuns.getActiveForScope(scopeKey);
 }
 
 function splitTextIntoReplayDeltas(text: string): string[] {
@@ -176,6 +181,7 @@ function emitCursorNativeToolUseTurn(
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
 	tools: CursorNativeToolDisplayItem[],
+	occupancyFloor: number | undefined,
 	debugRecorder?: CursorSdkEventDebugRecorder,
 ): void {
 	const shouldTerminate = run.done && !run.finalText?.trim() && !cursorLiveRuns.peekEvent(run);
@@ -193,7 +199,7 @@ function emitCursorNativeToolUseTurn(
 		stream.push({ type: "toolcall_delta", contentIndex, delta: serializedArgs, partial });
 		const block = partial.content[contentIndex];
 		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
-		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate })) {
+		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate }, run.nativeDisplay)) {
 			run.recordedToolDisplayIds.push(tool.id);
 			debugRecorder?.recordDrainEvent("native_tool_display_recorded", {
 				toolId: tool.id,
@@ -205,6 +211,7 @@ function emitCursorNativeToolUseTurn(
 	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 		runtime: "local",
 		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+		occupancyFloor,
 	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
@@ -236,6 +243,7 @@ function emitCursorBridgeToolUseTurn(
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
 	requests: CursorPiBridgeToolRequest[],
+	occupancyFloor: number | undefined,
 ): void {
 	for (const request of requests) {
 		const contentIndex = partial.content.length;
@@ -254,6 +262,7 @@ function emitCursorBridgeToolUseTurn(
 	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 		runtime: "local",
 		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+		occupancyFloor,
 	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
@@ -268,7 +277,7 @@ async function emitCursorLiveRunPendingToolUseTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; occupancyFloor?: number },
 ): Promise<"tool_use" | "handled" | undefined> {
 	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	const eventType = cursorLiveRuns.peekEvent(run)?.type;
@@ -285,13 +294,13 @@ async function emitCursorLiveRunPendingToolUseTurn(
 		}
 		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
-		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, debugRecorder);
+		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, options.occupancyFloor, debugRecorder);
 	} else {
 		const requests = cursorLiveRuns.collectBridgeToolBatch(run);
 		if (requests.length === 0) return "handled";
 		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
-		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests);
+		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests, options.occupancyFloor);
 	}
 	return "tool_use";
 }
@@ -303,7 +312,7 @@ export async function drainCursorLiveRunTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; emitter?: CursorPartialContentEmitter },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; emitter?: CursorPartialContentEmitter; occupancyFloor?: number },
 ): Promise<CursorLiveRunDrainOutcome> {
 	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	debugRecorder?.recordDrainEvent("turn_start", {
@@ -390,7 +399,7 @@ export async function drainCursorLiveRunTurn(
 				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 					runtime: "local",
 					turn: cursorLiveRuns.takeSdkTurnUsage(run),
-					billed: run.billedTurnUsage,
+					occupancyFloor: options.occupancyFloor,
 				});
 				if (run.resumeNotice) {
 					emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);
@@ -436,12 +445,14 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
-	signal?: AbortSignal,
-	turnDebugRecorder?: CursorSdkEventDebugRecorder,
+	signal: AbortSignal | undefined,
+	turnDebugRecorder: CursorSdkEventDebugRecorder | undefined,
+	scopeKey: string,
+	occupancyFloor?: number,
 ): Promise<LiveRunPreSendOutcome> {
 	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
-		const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+		const run = getPendingCursorLiveRun(context, scopeKey) ?? getActiveCursorLiveRunForCurrentScope(scopeKey);
 		if (!run || run.disposed) {
 			turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
 			return "continue_send";
@@ -462,6 +473,7 @@ export async function drainExistingCursorLiveRunBeforeSend(
 					mode: shouldChainUserInput ? "chain_user_input" : "emit",
 					signal,
 					debugRecorder: turnDebugRecorder,
+					occupancyFloor,
 				});
 				const mapped = drainOutcome === "chain_user_input" ? "continue_send" : "stream_ended";
 				turnDebugRecorder?.recordDrainEvent("pre_send_iteration", {
@@ -490,11 +502,11 @@ export async function drainExistingCursorLiveRunBeforeSend(
 }
 
 export function setCursorNativeReplayIdleDisposeMs(value: number): void {
-	cursorNativeReplayIdleDisposeMs = value;
+	cursorNativeReplayIdleDisposeMsOverride = value;
 }
 
 export function resetCursorNativeReplayIdleDisposeMs(): void {
-	cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+	cursorNativeReplayIdleDisposeMsOverride = undefined;
 }
 
 export async function releaseAllPendingCursorLiveRunsForTests(): Promise<void> {