pi-cursor-sdk 0.4.0 → 0.5.0

package/src/cursor-native-tool-display-state.ts

@@ -1,5 +1,7 @@
+import type { ExtensionHandler, SessionShutdownEvent, SourceInfo } from "@earendil-works/pi-coding-agent";
 import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { parseOptionalEnvBoolean } from "./cursor-env-boolean.js";
+import { normalizeCursorToolName } from "./cursor-tool-presentation-registry.js";
 
 export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 	id: string;
@@ -9,11 +11,43 @@ export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 export const NATIVE_CURSOR_TOOL_DISPLAY_ENV = "PI_CURSOR_NATIVE_TOOL_DISPLAY";
 export const NATIVE_CURSOR_TOOL_REGISTRATION_ENV = "PI_CURSOR_REGISTER_NATIVE_TOOLS";
 
-export const registeredNativeToolNames = new Set<string>();
-export const skippedNativeToolNames = new Set<string>();
+export interface CursorNativeToolDisplayState {
+	registeredNativeToolSources: Map<string, SourceInfo>;
+	skippedNativeToolNames: Set<string>;
+	runtimeRequested: boolean;
+	resultIds: Set<string>;
+}
+
+function createDisplayState(): CursorNativeToolDisplayState {
+	return { registeredNativeToolSources: new Map(), skippedNativeToolNames: new Set(), runtimeRequested: false, resultIds: new Set() };
+}
+
+let lastDisplayState = createDisplayState();
+const displayStates = new Map<object, CursorNativeToolDisplayState>();
+// IDs index results; the owning display state and tool authorize consumption.
 export const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
+const resultStates = new Map<string, CursorNativeToolDisplayState>();
 
-let nativeToolDisplayRuntimeRequested = false;
+export function getCursorNativeToolDisplayState(pi?: object): CursorNativeToolDisplayState {
+	if (!pi) return lastDisplayState;
+	const state = displayStates.get(pi);
+	if (!state) throw new Error("Cursor native display binding is no longer active.");
+	return state;
+}
+
+export function registerCursorNativeToolDisplayState(pi: { on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void }): void {
+	const state = createDisplayState();
+	displayStates.set(pi, state);
+	lastDisplayState = state;
+	pi.on("session_shutdown", () => {
+		displayStates.delete(pi);
+		for (const id of state.resultIds) {
+			nativeToolResults.delete(id);
+			resultStates.delete(id);
+		}
+		state.resultIds.clear();
+	});
+}
 
 export function readBooleanEnv(name: string, env: Record<string, string | undefined> = process.env): boolean | undefined {
 	return parseOptionalEnvBoolean(env[name]);
@@ -30,39 +64,48 @@ export function isCursorNativeToolRegistrationRequested(mode?: string): boolean
 	return mode !== "print" && readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) !== false && isCursorNativeToolDisplayRequested(mode);
 }
 
-export function setCursorNativeToolDisplayRuntimeRequested(requested: boolean): void {
-	nativeToolDisplayRuntimeRequested = requested;
+export function setCursorNativeToolDisplayRuntimeRequested(requested: boolean, pi?: object): void {
+	getCursorNativeToolDisplayState(pi).runtimeRequested = requested;
 }
 
 export function isCursorNativeToolDisplayEnabled(): boolean {
-	return registeredNativeToolNames.size > 0;
+	return getCursorNativeToolDisplayState().registeredNativeToolSources.size > 0;
 }
 
-export function isCursorNativeToolDisplayRuntimeEnabled(): boolean {
-	return nativeToolDisplayRuntimeRequested && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== false && registeredNativeToolNames.size > 0;
+export function isCursorNativeToolDisplayRuntimeEnabled(state = getCursorNativeToolDisplayState()): boolean {
+	return state.runtimeRequested && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== false && state.registeredNativeToolSources.size > 0;
 }
 
 export function canRenderCursorToolNatively(toolName: string): boolean {
-	return registeredNativeToolNames.has(toolName);
+	return getCursorNativeToolDisplayState().registeredNativeToolSources.has(toolName);
 }
 
-export function isRegisteredCursorNativeToolName(toolName: string): boolean {
-	return registeredNativeToolNames.has(toolName);
+export function isRegisteredCursorNativeToolName(toolName: string, pi?: object): boolean {
+	return (pi ? displayStates.get(pi) : lastDisplayState)?.registeredNativeToolSources.has(toolName) === true;
 }
 
-export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): boolean {
-	if (!canRenderCursorToolNatively(item.toolName)) return false;
+export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem, state = getCursorNativeToolDisplayState()): boolean {
+	if (!state.registeredNativeToolSources.has(item.toolName)) return false;
 	nativeToolResults.set(item.id, item);
+	resultStates.set(item.id, state);
+	state.resultIds.add(item.id);
 	return true;
 }
 
 export function deleteCursorNativeToolDisplay(id: string): void {
 	nativeToolResults.delete(id);
+	resultStates.get(id)?.resultIds.delete(id);
+	resultStates.delete(id);
 }
 
-export function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem | undefined {
+export function consumeCursorNativeToolDisplay(id: string, state: CursorNativeToolDisplayState, toolName: string): CursorNativeToolDisplayItem | undefined {
 	const item = nativeToolResults.get(id);
-	if (item) nativeToolResults.delete(id);
+	if (item) {
+		if (resultStates.get(id) !== state || normalizeCursorToolName(item.toolName) !== normalizeCursorToolName(toolName)) {
+			throw new Error(`No owned Cursor ${toolName} result was available. This replay-only call does not execute work.`);
+		}
+		deleteCursorNativeToolDisplay(id);
+	}
 	return item;
 }
 
@@ -76,14 +119,15 @@ export function isCursorFileMutationToolName(toolName: string): toolName is "edi
 
 export const __testUtils = {
 	nativeToolResultCount: () => nativeToolResults.size,
-	registerNativeToolNameForTests(toolName: string): void {
-		nativeToolDisplayRuntimeRequested = true;
-		registeredNativeToolNames.add(toolName);
+	registerNativeToolNameForTests(toolName: string, pi?: object): void {
+		const state = getCursorNativeToolDisplayState(pi);
+		state.runtimeRequested = true;
+		state.registeredNativeToolSources.set(toolName, { path: "test", source: "inline", scope: "temporary", origin: "top-level" });
 	},
 	reset(): void {
-		nativeToolDisplayRuntimeRequested = false;
-		registeredNativeToolNames.clear();
-		skippedNativeToolNames.clear();
+		lastDisplayState = createDisplayState();
+		displayStates.clear();
 		nativeToolResults.clear();
+		resultStates.clear();
 	},
 };

package/src/cursor-native-tool-display-tools.ts

@@ -10,7 +10,6 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
-import { getCursorSessionCwd } from "./cursor-session-scope.js";
 import {
 	BUILTIN_NATIVE_CURSOR_TOOL_NAMES,
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
@@ -33,6 +32,7 @@ import {
 import {
 	consumeCursorNativeToolDisplay,
 	isCursorReplayToolCallId,
+	type CursorNativeToolDisplayState,
 } from "./cursor-native-tool-display-state.js";
 
 
@@ -155,12 +155,13 @@ function getNativeReplayStrategy(toolName: string): NativeReplayStrategy | undef
 export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 	definition: ToolDefinition<TParams, TDetails, TState>,
 	getCurrentDefinition: () => ToolDefinition<TParams, TDetails, TState>,
+	state: CursorNativeToolDisplayState,
 ): ToolDefinition<TParams, TDetails, TState> {
 	const strategy = getNativeReplayStrategy(definition.name);
 	return {
 		...definition,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const cursorDisplay = consumeCursorNativeToolDisplay(toolCallId);
+			const cursorDisplay = consumeCursorNativeToolDisplay(toolCallId, state, definition.name);
 			if (cursorDisplay) {
 				if (cursorDisplay.isError) {
 					const text = cursorDisplay.result.content
@@ -211,9 +212,11 @@ export function createNativeCursorToolDefinition(toolName: NativeCursorToolName,
 export function registerNativeCursorTool(
 	pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerTool">,
 	toolName: NativeCursorToolName,
+	getCwd: () => string,
+	state: CursorNativeToolDisplayState,
 ): void {
-	const definition = createNativeCursorToolDefinition(toolName, getCursorSessionCwd());
-	pi.registerTool(wrapNativeCursorTool(definition, () => createNativeCursorToolDefinition(toolName, getCursorSessionCwd())));
+	const definition = createNativeCursorToolDefinition(toolName, getCwd());
+	pi.registerTool(wrapNativeCursorTool(definition, () => createNativeCursorToolDefinition(toolName, getCwd()), state));
 }
 
 export { CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES, CURSOR_REPLAY_TOOL_NAMES };

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

@@ -1,8 +1,33 @@
 export const MCP_SERVER_NAME = "pi_tools";
 export const MCP_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
+export const CURSOR_PI_BRIDGE_TOOL_CALL_ID_MAX_LENGTH = 64;
 
-const CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN = /^cursor-pi-bridge-run-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}-tool-\d+$/i;
+const CURSOR_PI_BRIDGE_RUN_UUID_PATTERN = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
+const CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN = /^cursor-pi-bridge-[0-9a-f]{32}-t\d+$/i;
+const LEGACY_CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN =
+	/^cursor-pi-bridge-run-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}-tool-\d+$/i;
+
+/**
+ * Build the provider-facing bridge ID while enforcing the 64-character
+ * call_id limit used by OpenAI-compatible Responses backends.
+ */
+export function buildCursorPiBridgeToolCallId(runUuid: string, counter: number): string {
+	if (!CURSOR_PI_BRIDGE_RUN_UUID_PATTERN.test(runUuid)) {
+		throw new Error("Cursor pi bridge run UUID must be canonical");
+	}
+	if (!Number.isSafeInteger(counter) || counter <= 0) {
+		throw new Error("Cursor pi bridge tool call counter must be a positive safe integer");
+	}
+	const toolCallId = `cursor-pi-bridge-${runUuid.replaceAll("-", "")}-t${counter}`;
+	if (toolCallId.length > CURSOR_PI_BRIDGE_TOOL_CALL_ID_MAX_LENGTH) {
+		throw new Error("Cursor pi bridge tool call ID limit exceeded");
+	}
+	return toolCallId;
+}
 
 export function isCursorPiBridgeToolCallId(toolCallId: string): boolean {
-	return CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN.test(toolCallId);
+	return (
+		(toolCallId.length <= CURSOR_PI_BRIDGE_TOOL_CALL_ID_MAX_LENGTH && CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN.test(toolCallId)) ||
+		LEGACY_CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN.test(toolCallId)
+	);
 }

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

@@ -7,7 +7,11 @@ import {
 	WebStandardStreamableHTTPServerTransport,
 } from "@modelcontextprotocol/server";
 import { bridgeToolExecutionAbortTracker } from "./cursor-pi-tool-bridge-abort.js";
-import { MCP_ENDPOINT_ROOT, MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
+import {
+	buildCursorPiBridgeToolCallId,
+	MCP_ENDPOINT_ROOT,
+	MCP_SERVER_NAME,
+} from "./cursor-pi-tool-bridge-constants.js";
 import {
 	type CursorPiToolBridgeDiagnosticEvent,
 	type CursorPiToolBridgeLifecycleDiagnosticFields,
@@ -58,6 +62,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	private readonly registry: CursorPiToolBridgeRunHost;
 	private readonly env: Record<string, string | undefined>;
 	private readonly endpointPath: string;
+	private readonly runUuid: string;
 	private readonly callTimeoutMs: number;
 	private readonly knownMcpToolNames: ReadonlySet<string>;
 	private readonly knownCursorMcpCallIds = new Set<string>();
@@ -86,7 +91,9 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.enabled = enabled;
 		this.onToolRequest = options.onToolRequest;
 		this.debugRecorder = options.debugRecorder;
-		this.id = `cursor-pi-bridge-run-${randomUUID()}`;
+		const runUuid = randomUUID();
+		this.runUuid = runUuid;
+		this.id = `cursor-pi-bridge-run-${runUuid}`;
 		this.endpointPath = `${MCP_ENDPOINT_ROOT}/${randomUUID()}/mcp`;
 		this.callTimeoutMs = resolveCursorPiToolBridgeCallTimeoutMs(env);
 		this.knownMcpToolNames = new Set(snapshot.tools.map((tool) => tool.mcpToolName));
@@ -277,11 +284,12 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 
 		this.toolCallCounter += 1;
 		const bridgeCallId = `${this.id}-bridge-${this.toolCallCounter}`;
+		const piToolCallId = buildCursorPiBridgeToolCallId(this.runUuid, this.toolCallCounter);
 		const request: CursorPiBridgeToolRequest = {
 			runId: this.id,
 			bridgeCallId,
 			cursorMcpCallId,
-			piToolCallId: `${this.id}-tool-${this.toolCallCounter}`,
+			piToolCallId,
 			piToolName,
 			mcpToolName,
 			args: normalizeMcpArgs(argsValue),

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

@@ -63,7 +63,7 @@ export function buildCursorPiToolBridgeSnapshot(
 
 	for (const tool of allTools) {
 		if (!activeToolNames.has(tool.name)) continue;
-		if (isExcludedFromCursorBridgeExposure(tool.name) && isRegisteredCursorNativeToolName(tool.name)) continue;
+		if (isExcludedFromCursorBridgeExposure(tool.name) && isRegisteredCursorNativeToolName(tool.name, pi)) continue;
 		if (!exposeOverlappingBuiltins && isOverlappingCursorNativePiToolName(tool.name)) continue;
 
 		const mcpToolName = createMcpToolName(tool.name, usedMcpToolNames);

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,62 @@
+import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+import { CURSOR_API_KEY_CONFIG_VALUE } from "./cursor-api-key.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";
+
+export const CURSOR_PROVIDER_OWNERSHIP_ERROR = "Cursor provider ownership is unavailable: this request does not belong to the active Cursor registration. Bind this session's extensions and refresh Cursor models/reload it; 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;
+}
+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 };
+	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) => {
+		// 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),
+		});
+	});
+	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),
+		};
+	});
+	pi.on("session_start", () => { if (!binding.closed) binding.active = true; });
+	pi.on("session_shutdown", () => { binding.active = false; binding.closed = true; });
+	return (models: ProviderModelConfig[]) => {
+		if (binding.closed) return;
+		pi.registerProvider("cursor", {
+			name: "Cursor", baseUrl: "https://cursor.com", apiKey: CURSOR_API_KEY_CONFIG_VALUE,
+			api: "cursor-sdk", models, streamSimple: stream,
+		});
+	};
+}

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";
@@ -349,27 +349,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;
+	};
 }