pi-cursor-sdk 0.1.17 → 0.1.19

package/src/cursor-provider.ts

@@ -8,14 +8,15 @@ import {
 	type AssistantMessage,
 } from "@earendil-works/pi-ai";
 import { Agent, createAgentPlatform } from "@cursor/sdk";
-import type { SDKAgent, SettingSource } from "@cursor/sdk";
+import type { SDKAgent } from "@cursor/sdk";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
-import { buildCursorSendPrompt } from "./context.js";
 import {
 	acquireSessionCursorAgent,
+	buildCursorSessionSendPrompt,
 	commitSessionAgentSend,
 	disposeAllSessionCursorAgents,
+	planCursorSessionSend,
 	resetSessionCursorAgent,
 } from "./cursor-session-agent.js";
 import {
@@ -28,6 +29,7 @@ import {
 	getCursorPromptOptions,
 } from "./cursor-usage-accounting.js";
 import { getCursorSessionCwd } from "./cursor-session-cwd.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import { CursorLiveRunAbortError, type CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import {
 	abandonSessionCursorAgent,
@@ -35,9 +37,11 @@ import {
 	cursorLiveRuns,
 	drainCursorLiveRunTurn,
 	drainExistingCursorLiveRunBeforeSend,
+	flushPendingCursorLiveRunTraceEventsToStream,
 	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
 	getPendingCursorLiveRun,
 	hasTrailingUserMessagesAfterToolResults,
+	releaseAllPendingCursorLiveRunsForTests,
 	resetCursorNativeReplayIdleDisposeMs,
 	selectCursorFinalText,
 	setCursorNativeReplayIdleDisposeMs,
@@ -46,8 +50,27 @@ import {
 import { getEffectiveFastForModelId } from "./cursor-state.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
+import {
+	attachCursorSdkEventDebugPiStreamTap,
+	CursorSdkEventDebugSink,
+	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+} from "./cursor-sdk-event-debug.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { isCursorNativeToolDisplayRuntimeEnabled } from "./cursor-native-tool-display.js";
+import {
+	formatCursorSdkAbortMessage,
+	formatCursorSdkRunFailureDetail,
+	MISSING_CURSOR_API_KEY_MESSAGE,
+	resolveCursorSdkAbortCause,
+	sanitizeCursorProviderError,
+} from "./cursor-provider-errors.js";
+import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
+import { hasUsableText } from "./cursor-record-utils.js";
+import {
+	countCursorAgentMessages,
+	loadCursorTranscriptWebToolCallsAfterOffset,
+} from "./cursor-agent-message-web-tools.js";
+import { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -70,25 +93,6 @@ function makeInitialMessage(model: Model<Api>): AssistantMessage {
 }
 
 const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
-const MISSING_API_KEY_MESSAGE =
-	"Cursor SDK runs require a Cursor API key. 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 API key may be missing, invalid, or unauthorized. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
-const AUTH_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request failed because the API key may be invalid or unauthorized. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
-const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
-
-import { scrubSensitiveText } from "./cursor-sensitive-text.js";
-import { hasUsableText } from "./cursor-record-utils.js";
-
-function isGenericErrorMessage(message: string): boolean {
-	const normalized = message.trim().toLowerCase();
-	return normalized === "" || normalized === "error" || normalized === "unknown error";
-}
-
-function isLikelyAuthError(message: string): boolean {
-	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
-}
 
 function resolveCursorApiKey(apiKey?: string): string | undefined {
 	const trimmed = apiKey?.trim();
@@ -97,27 +101,6 @@ function resolveCursorApiKey(apiKey?: string): string | undefined {
 	return trimmed;
 }
 
-function resolveCursorSettingSources(): SettingSource[] | undefined {
-	const raw = process.env[CURSOR_SETTING_SOURCES_ENV]?.trim();
-	if (!raw) return ["all"];
-	const normalized = raw.toLowerCase();
-	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
-	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
-	return raw
-		.split(",")
-		.map((entry) => entry.trim())
-		.filter((entry): entry is SettingSource => Boolean(entry));
-}
-
-function sanitizeError(error: unknown, apiKey?: string): string {
-	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
-	if (message === MISSING_API_KEY_MESSAGE) return MISSING_API_KEY_MESSAGE;
-	const scrubbed = scrubSensitiveText(message, apiKey).trim();
-	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
-	if (isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
-	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
-}
-
 async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<void> {
 	try {
 		const platform = await createAgentPlatform();
@@ -135,6 +118,8 @@ export function streamCursor(
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
 	const stream = createAssistantMessageEventStream();
+	const sdkEventDebugRef: { current?: CursorSdkEventDebugSink } = {};
+	attachCursorSdkEventDebugPiStreamTap(stream, sdkEventDebugRef);
 
 	(async () => {
 		const partial = makeInitialMessage(model);
@@ -148,8 +133,51 @@ export function streamCursor(
 		let abortSignal: AbortSignal | undefined;
 		let abortListener: (() => void) | undefined;
 		let restoreCursorSdkOutputFilter: (() => void) | undefined;
+		let sdkEventDebug: CursorSdkEventDebugSink | undefined;
+		let deferSdkEventDebugFinalize = false;
+		const sdkAbortErrorSuppression = installCursorSdkAbortErrorSuppression();
+
+		const pushSanitizedStreamError = (error: unknown, reason: "error" | "aborted" = "error"): void => {
+			partial.stopReason = reason;
+			partial.errorMessage =
+				reason === "aborted"
+					? formatCursorSdkAbortMessage(resolveCursorSdkAbortCause({ signalAborted: options?.signal?.aborted }))
+					: sanitizeCursorProviderError(error, resolvedApiKey ?? options?.apiKey);
+			stream.push({ type: "error", reason, error: partial });
+		};
+
+		const getCursorAgentMessageOffset = async (agentId: string, cwd: string): Promise<number | undefined> => {
+			try {
+				return await countCursorAgentMessages(agentId, cwd);
+			} catch (error) {
+				sdkEventDebug?.recordError("cursor_agent_message_count", error);
+				return undefined;
+			}
+		};
+
+		const replayCursorTranscriptWebToolCalls = async (
+			agentId: string,
+			cwd: string,
+			messageOffset: number | undefined,
+			turnCoordinator: CursorSdkTurnCoordinator,
+		): Promise<void> => {
+			try {
+				const transcriptToolCalls = await loadCursorTranscriptWebToolCallsAfterOffset({ agentId, cwd, offset: messageOffset });
+				if (transcriptToolCalls.length === 0) return;
+				sdkEventDebug?.recordCoordinatorEvent("cursor-transcript-web-tools", {
+					agentId,
+					messageOffset,
+					count: transcriptToolCalls.length,
+				});
+				turnCoordinator.handleTranscriptCompletedToolCalls(transcriptToolCalls);
+			} catch (error) {
+				sdkEventDebug?.recordError("cursor_transcript_web_tools", error);
+			}
+		};
 
 		try {
+			let turnCoordinatorForCleanup: CursorSdkTurnCoordinator | undefined;
+			try {
 			const throwIfAborted = (): void => {
 				if (options?.signal?.aborted) throw new CursorLiveRunAbortError();
 			};
@@ -157,21 +185,29 @@ export function streamCursor(
 			stream.push({ type: "start", partial });
 			throwIfAborted();
 
-			if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal)) === "stream_ended") {
-				stream.end();
+			const cwd = getCursorSessionCwd();
+			sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
+				cwd,
+				modelId: model.id,
+				provider: model.provider,
+			});
+			sdkEventDebugRef.current = sdkEventDebug;
+			sdkEventDebug?.recordContextSnapshot(context);
+
+			if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, sdkEventDebug)) === "stream_ended") {
+				sdkEventDebug?.recordFinalPartial(partial);
+				await sdkEventDebug?.finalize();
+				sdkEventDebugRef.current = undefined;
 				return;
 			}
 
 			const apiKey = resolveCursorApiKey(options?.apiKey);
-			if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
+			if (!apiKey) throw new Error(MISSING_CURSOR_API_KEY_MESSAGE);
 			resolvedApiKey = apiKey;
 
-			// pi-ai Context/SimpleStreamOptions do not expose ExtensionContext.cwd; bridge via session_start
-			// until pi threads session cwd into streamSimple (cwd can change without a new session event).
-			const cwd = getCursorSessionCwd();
 			const fastEnabled = getEffectiveFastForModelId(model.id);
 			const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
-			const settingSources = resolveCursorSettingSources();
+			const settingSources = getEffectiveCursorSettingSources();
 
 			installCursorMcpToolTimeoutOverride();
 			restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
@@ -180,6 +216,7 @@ export function streamCursor(
 				cwd,
 				modelSelection: selection,
 				settingSources,
+				debugRecorder: sdkEventDebug,
 				onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
 					if (liveRunForBridgeQueue && !liveRunForBridgeQueue.disposed) {
 						cursorLiveRuns.queueEvent(liveRunForBridgeQueue, { type: "bridge-tool", request });
@@ -197,18 +234,39 @@ export function streamCursor(
 			throwIfAborted();
 
 			const promptOptions = getCursorPromptOptions(model);
-			let { prompt, bootstrap } = buildCursorSendPrompt(context, promptOptions, sessionAgentLease.sendState);
-			if (sessionAgentLease.sendState.bootstrapped && bootstrap) {
+			let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+			let prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
+			if (sendPlan.resetAgent) {
 				await resetSessionCursorAgent(sessionAgentLease.scopeKey);
 				sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
 				sessionAgentScopeKey = sessionAgentLease.scopeKey;
 				agent = sessionAgentLease.agent;
 				bridgeRun = sessionAgentLease.bridgeRun;
-				({ prompt, bootstrap } = buildCursorSendPrompt(context, promptOptions, sessionAgentLease.sendState));
+				sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+				prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
 			}
+			const bootstrap = sendPlan.mode === "bootstrap";
 			const sessionBridgeRun = sessionAgentLease.bridgeRun;
 			const promptInputTokens = estimateCursorPromptInputTokens(prompt, promptOptions);
 			const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+			const activeToolNames = getActiveContextToolNames(context);
+			sdkEventDebug?.recordProviderMeta({
+				model: {
+					id: model.id,
+					provider: model.provider,
+					api: model.api,
+					reasoning: options?.reasoning ?? "off",
+					fastEnabled,
+					selection,
+				},
+				settingSources: settingSources ?? null,
+				sendState: sessionAgentLease.sendState,
+				sendPlan,
+				promptOptions,
+				activeToolNames: activeToolNames ? [...activeToolNames] : [],
+				sessionAgentScopeKey,
+				bridgeRunId: bridgeRun?.id,
+			});
 			const nativeReplayId = createCursorNativeReplayId();
 			const textDeltas: string[] = [];
 			const useLiveRun = useNativeToolReplay || bridgeRun !== undefined;
@@ -221,6 +279,7 @@ export function streamCursor(
 						sessionAgentScopeKey,
 						promptInputTokens,
 						textDeltas,
+						debugRecorder: sdkEventDebug,
 					})
 				: undefined;
 			if (liveRun) {
@@ -237,13 +296,17 @@ export function streamCursor(
 				resolvedApiKey,
 				liveRun,
 				useNativeToolReplay,
+				activeToolNames,
 				nativeReplayId,
 				textDeltas,
+				debugRecorder: sdkEventDebug,
 			});
+			turnCoordinatorForCleanup = turnCoordinator;
 
 			// Handle abort signal
 			let run: Awaited<ReturnType<SDKAgent["send"]>> | null = null;
 			abortListener = () => {
+				sdkAbortErrorSuppression.suppressAbortErrors();
 				activeLiveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
 				if (run) {
 					run.cancel().catch(() => {});
@@ -253,25 +316,73 @@ export function streamCursor(
 			abortSignal?.addEventListener("abort", abortListener, { once: true });
 
 			throwIfAborted();
-			run = await agent.send(
-				{ text: prompt.text, images: prompt.images.length > 0 ? prompt.images : undefined },
-				{
-					onDelta: (args) => turnCoordinator.handleDelta(args.update),
-					onStep: (args) => turnCoordinator.handleStep(args.step),
+			sdkEventDebug?.recordSendMeta({
+				mode: sendPlan.mode,
+				reason: sendPlan.reason,
+				resetAgent: sendPlan.resetAgent,
+				bootstrap,
+				promptText: prompt.text,
+				imageCount: prompt.images.length,
+				useNativeToolReplay,
+				bridgeEnabled: bridgeRun !== undefined,
+				nativeReplayId,
+				promptInputTokens,
+			});
+			const sendPayload = {
+				text: prompt.text,
+				images: prompt.images.length > 0 ? prompt.images : undefined,
+			};
+			sdkEventDebug?.recordSendPayload(sendPayload);
+			const cursorAgentMessageOffset = await getCursorAgentMessageOffset(agent.agentId, cwd);
+			sdkEventDebug?.recordProviderEvent("agent_send_start", sendPayload);
+			run = await agent.send(sendPayload, {
+				onDelta: (args) => {
+					sdkEventDebug?.recordOnDelta(args.update);
+					turnCoordinator.handleDelta(args.update);
 				},
-			);
+				onStep: (args) => {
+					sdkEventDebug?.recordOnStep(args.step);
+					turnCoordinator.handleStep(args.step);
+				},
+			});
+			sdkEventDebug?.recordRunMeta({
+				runId: run.id,
+				agentId: run.agentId,
+				status: run.status,
+			});
+			sdkEventDebug?.attachRunStream(run);
+			sdkEventDebug?.recordProviderEvent("agent_send_returned", {
+				runId: run.id,
+				agentId: run.agentId,
+				status: run.status,
+			});
 			if (liveRun) cursorLiveRuns.attachSdkRun(liveRun, run);
 			if (options?.signal?.aborted) {
+				sdkAbortErrorSuppression.suppressAbortErrors();
+				liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
 				await run.cancel().catch(() => {});
 				throw new CursorLiveRunAbortError();
 			}
+			const activeRun = run;
 
 			if (liveRun) {
-				void run
+				deferSdkEventDebugFinalize = true;
+				const waitCompletion = run
 					.wait()
 					.then(async (result) => {
+						sdkEventDebug?.recordWaitResult(result);
+						if (result.status === "finished" && !options?.signal?.aborted) {
+							await replayCursorTranscriptWebToolCalls(activeRun.agentId, cwd, cursorAgentMessageOffset, turnCoordinator);
+						}
+						turnCoordinator.discardIncompleteStartedToolCalls(
+							result.status === "cancelled" || options?.signal?.aborted
+								? "abort"
+								: result.status === "error"
+									? "sdk-failure"
+									: DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+						);
+						await sdkEventDebug?.captureRunArtifacts(run);
 						if (liveRun.disposed) return;
-						turnCoordinator.discardIncompleteStartedToolCalls();
 						await cacheSdkContextWindow(liveRun.agent.agentId, model.id);
 						if (liveRun.disposed) return;
 						if (result.status === "finished" && !options?.signal?.aborted) {
@@ -281,14 +392,30 @@ export function streamCursor(
 								selectCursorFinalText(result.result, liveRun.textDeltas, liveRun.emittedText, turnCoordinator.planTextCandidate),
 							);
 						} else if (result.status === "cancelled" || options?.signal?.aborted) {
-							cursorLiveRuns.markCancelled(liveRun);
+							cursorLiveRuns.markCancelled(
+								liveRun,
+								formatCursorSdkAbortMessage(
+									resolveCursorSdkAbortCause({
+										signalAborted: options?.signal?.aborted,
+										sdkStatusCancelled: result.status === "cancelled",
+									}),
+								),
+							);
 						} else {
-							cursorLiveRuns.markError(liveRun, sanitizeError(result.result ?? "Cursor SDK run failed", resolvedApiKey ?? options?.apiKey));
+							const failureDetail = formatCursorSdkRunFailureDetail(result, run?.result);
+							cursorLiveRuns.markError(
+								liveRun,
+								sanitizeCursorProviderError(failureDetail, resolvedApiKey ?? options?.apiKey),
+							);
 						}
 					})
 					.catch(async (error: unknown) => {
+						sdkEventDebug?.recordWaitResult({ status: "error", error: String(error) });
+						sdkEventDebug?.recordError("run_wait", error);
+						turnCoordinatorForCleanup?.discardIncompleteStartedToolCalls("sdk-failure");
+						await sdkEventDebug?.captureRunArtifacts(run);
 						if (liveRun.disposed) return;
-						cursorLiveRuns.markError(liveRun, sanitizeError(error, resolvedApiKey ?? options?.apiKey));
+						cursorLiveRuns.markError(liveRun, sanitizeCursorProviderError(error, resolvedApiKey ?? options?.apiKey));
 					});
 
 				try {
@@ -296,18 +423,53 @@ export function streamCursor(
 						await cursorLiveRuns.waitForProgress(liveRun, options?.signal);
 						await settleCursorLiveToolBatch(liveRun);
 						turnCoordinator.closeTraceBlock();
-						await drainCursorLiveRunTurn(stream, partial, model, context, liveRun, 0, { mode: "emit", signal: options?.signal });
+						await drainCursorLiveRunTurn(stream, partial, model, context, liveRun, 0, {
+							mode: "emit",
+							signal: options?.signal,
+							debugRecorder: sdkEventDebug,
+						});
 					});
 				} catch (error) {
-					if (error instanceof CursorLiveRunAbortError) await cursorLiveRuns.release(liveRun);
+					if (error instanceof CursorLiveRunAbortError) {
+						sdkAbortErrorSuppression.suppressAbortErrors();
+						turnCoordinator.discardIncompleteStartedToolCalls("abort");
+						turnCoordinator.closeTraceBlock();
+						flushPendingCursorLiveRunTraceEventsToStream(stream, partial, liveRun, {
+							includeTracesBehindQueuedTools: true,
+						});
+						await cursorLiveRuns.release(liveRun);
+					}
 					throw error;
+				} finally {
+					sdkEventDebugRef.current = undefined;
+					void waitCompletion
+						.finally(async () => {
+							try {
+								sdkEventDebug?.recordFinalPartial(partial);
+								await sdkEventDebug?.finalize();
+							} finally {
+								sdkAbortErrorSuppression.dispose();
+							}
+						})
+						.catch(() => {});
 				}
 				agent = null;
 				return;
 			}
 
 			const result = await run.wait();
-			turnCoordinator.discardIncompleteStartedToolCalls();
+			sdkEventDebug?.recordWaitResult(result);
+			if (result.status === "finished" && !options?.signal?.aborted) {
+				await replayCursorTranscriptWebToolCalls(run.agentId, cwd, cursorAgentMessageOffset, turnCoordinator);
+			}
+			turnCoordinator.discardIncompleteStartedToolCalls(
+				result.status === "cancelled" || options?.signal?.aborted
+					? "abort"
+					: result.status === "error"
+						? "sdk-failure"
+						: DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+			);
+			await sdkEventDebug?.captureRunArtifacts(run);
 			await cacheSdkContextWindow(agent.agentId, model.id);
 
 			// Close any open thinking/activity trace, then use the final run result only when
@@ -317,11 +479,18 @@ export function streamCursor(
 			if (result.status === "cancelled") {
 				await abandonSessionCursorAgent(sessionAgentScopeKey);
 				partial.stopReason = "aborted";
+				partial.errorMessage = formatCursorSdkAbortMessage(
+					resolveCursorSdkAbortCause({
+						signalAborted: options?.signal?.aborted,
+						sdkStatusCancelled: true,
+					}),
+				);
 				stream.push({ type: "error", reason: "aborted", error: partial });
 			} else if (result.status === "error") {
 				await abandonSessionCursorAgent(sessionAgentScopeKey);
 				partial.stopReason = "error";
-				partial.errorMessage = sanitizeError(result.result ?? "Cursor SDK run failed", resolvedApiKey ?? options?.apiKey);
+				const failureDetail = formatCursorSdkRunFailureDetail(result, run.result);
+				partial.errorMessage = sanitizeCursorProviderError(failureDetail, resolvedApiKey ?? options?.apiKey);
 				stream.push({ type: "error", reason: "error", error: partial });
 			} else {
 				commitSessionAgentSend(sessionAgentScopeKey, context, bootstrap);
@@ -332,27 +501,49 @@ export function streamCursor(
 				applyCursorApproximateUsage(partial, model, context, promptInputTokens);
 				stream.push({ type: "done", reason: "stop", message: partial });
 			}
-		} catch (error) {
-			if (activeLiveRun && !activeLiveRun.disposed) await cursorLiveRuns.release(activeLiveRun);
-			else await abandonSessionCursorAgent(sessionAgentScopeKey);
-			if (error instanceof CursorLiveRunAbortError) {
-				partial.stopReason = "aborted";
-				stream.push({ type: "error", reason: "aborted", error: partial });
-			} else {
-				partial.stopReason = "error";
-				partial.errorMessage = sanitizeError(error, resolvedApiKey ?? options?.apiKey);
-				stream.push({ type: "error", reason: "error", error: partial });
-			}
-		} finally {
-			restoreCursorSdkOutputFilter?.();
+			} catch (error) {
+				sdkEventDebug?.recordError("provider_stream", error);
+				turnCoordinatorForCleanup?.discardIncompleteStartedToolCalls(
+					error instanceof CursorLiveRunAbortError ? "abort" : "sdk-failure",
+				);
+				if (activeLiveRun && !activeLiveRun.disposed) await cursorLiveRuns.release(activeLiveRun);
+				else await abandonSessionCursorAgent(sessionAgentScopeKey);
+				if (error instanceof CursorLiveRunAbortError) {
+					sdkAbortErrorSuppression.suppressAbortErrors();
+					pushSanitizedStreamError(error, "aborted");
+				} else {
+					pushSanitizedStreamError(error, "error");
+				}
+			} finally {
+				if (!deferSdkEventDebugFinalize) {
+					try {
+						sdkEventDebug?.recordFinalPartial(partial);
+						await sdkEventDebug?.finalize();
+					} finally {
+						sdkAbortErrorSuppression.dispose();
+					}
+				}
+				sdkEventDebugRef.current = undefined;
+				restoreCursorSdkOutputFilter?.();
 
-			if (abortSignal && abortListener) {
-				abortSignal.removeEventListener("abort", abortListener);
+				if (abortSignal && abortListener) {
+					abortSignal.removeEventListener("abort", abortListener);
+				}
 			}
+		} catch (error) {
+			if (activeLiveRun && !activeLiveRun.disposed) await cursorLiveRuns.release(activeLiveRun).catch(() => {});
+			else await abandonSessionCursorAgent(sessionAgentScopeKey).catch(() => {});
+			pushSanitizedStreamError(error, error instanceof CursorLiveRunAbortError ? "aborted" : "error");
 		}
 
 		stream.end();
-	})();
+	})().catch((error: unknown) => {
+		const partial = makeInitialMessage(model);
+		partial.stopReason = "error";
+		partial.errorMessage = sanitizeCursorProviderError(error, resolveCursorApiKey(options?.apiKey));
+		stream.push({ type: "error", reason: "error", error: partial });
+		stream.end();
+	});
 
 	return stream;
 }
@@ -365,5 +556,6 @@ export const __testUtils = {
 	hasTrailingUserMessagesAfterToolResults,
 	setCursorNativeReplayIdleDisposeMs,
 	resetCursorNativeReplayIdleDisposeMs,
+	releaseAllPendingCursorLiveRunsForTests,
 	resetSessionCursorAgents: () => disposeAllSessionCursorAgents(),
 };

package/src/cursor-question-tool.ts

@@ -1,6 +1,7 @@
-import type { ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { isCursorModel } from "./cursor-model.js";
 import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge.js";
 
 export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
@@ -36,6 +37,8 @@ interface CursorQuestionDetails {
 
 interface CursorQuestionToolExtensionApi extends Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> {
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
 	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
 }
 
@@ -81,10 +84,6 @@ const CursorAskQuestionParamsSchema = Type.Object({
 	questions: Type.Optional(Type.Array(QuestionSchema, { description: "Ask multiple questions sequentially" })),
 });
 
-function isCursorModel(model: ExtensionContext["model"]): boolean {
-	return model?.provider === "cursor" || model?.api === "cursor-sdk";
-}
-
 function normalizeOption(option: RawQuestionOption, index: number): CursorQuestionOption | undefined {
 	if (typeof option === "string") {
 		const trimmed = option.trim();
@@ -246,6 +245,12 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 	pi.on("session_start", (_event, ctx) => {
 		syncCursorQuestionToolForModel(pi, ctx.model);
 	});
+	pi.on("before_agent_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		syncCursorQuestionToolForModel(pi, ctx.model);
+	});
 	pi.on("model_select", (event) => {
 		syncCursorQuestionToolForModel(pi, event.model);
 	});