pi-cursor-sdk 0.1.17 → 0.1.19

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

@@ -21,6 +21,7 @@ import {
 	createCursorReplayOnlyToolDefinition,
 	renderCursorReplayResult,
 	renderNativeLookingCursorFileMutationCall,
+	renderNativeLookingCursorReadReplayResult,
 } from "./cursor-native-tool-display-replay.js";
 import {
 	consumeCursorNativeToolDisplay,
@@ -65,6 +66,20 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 			return getCurrentDefinition().execute(toolCallId, params, signal, onUpdate, ctx);
 		},
 		renderCall(args, theme, context) {
+			if (definition.name === "read" && isCursorReplayToolCallId(context.toolCallId)) {
+				const currentRenderCall = getCurrentDefinition().renderCall;
+				const rendered = currentRenderCall ? currentRenderCall(args, theme, context) : new Text("", 0, 0);
+				if ((args as Record<string, unknown>).localReadPreview === true && !context.expanded) {
+					const baseText = rendered.render(120).join("\n").trimEnd();
+					const labeled = `${baseText}${theme.fg("muted", " · local file preview")}`;
+					if (rendered instanceof Text) {
+						rendered.setText(labeled);
+						return rendered;
+					}
+					return new Text(labeled, 0, 0);
+				}
+				return rendered;
+			}
 			if (isCursorFileMutationToolName(definition.name) && isCursorReplayToolCallId(context.toolCallId)) {
 				return renderNativeLookingCursorFileMutationCall(definition.name, args as Record<string, unknown>, theme, context.isPartial);
 			}
@@ -76,6 +91,11 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 			if (isCursorFileMutationToolName(definition.name) && details?.cursorToolName === definition.name) {
 				return renderCursorReplayResult(result, options, theme, context, context.isError);
 			}
+			if (definition.name === "read" && isCursorReplayToolCallId(context.toolCallId)) {
+				return renderNativeLookingCursorReadReplayResult(result, options, theme, context, () =>
+					getCurrentDefinition().renderResult?.(result, options, theme, context),
+				);
+			}
 			const currentRenderResult = getCurrentDefinition().renderResult;
 			return currentRenderResult ? currentRenderResult(result, options, theme, context) : new Text("", 0, 0);
 		},

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

@@ -1,5 +1,6 @@
 import { stableNameHash } from "./cursor-pi-tool-bridge-mcp.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export const CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_DEBUG";
 export const CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX = "[pi-cursor-sdk:bridge]";
@@ -169,7 +170,16 @@ export function serializeCursorPiToolBridgeDiagnostic(event: CursorPiToolBridgeD
 	return assertNeverDiagnosticEvent(event);
 }
 
-export function writeCursorPiToolBridgeDiagnostic(env: Record<string, string | undefined>, event: CursorPiToolBridgeDiagnosticEvent): void {
+export function writeCursorPiToolBridgeDiagnostic(
+	env: Record<string, string | undefined>,
+	event: CursorPiToolBridgeDiagnosticEvent,
+	debugRecorder?: CursorSdkEventDebugRecorder,
+): void {
+	try {
+		debugRecorder?.recordBridgeDiagnostic(event);
+	} catch {
+		// Diagnostics must never affect bridge execution.
+	}
 	if (!resolveCursorPiToolBridgeDebugEnabled(env)) return;
 	try {
 		process.stderr.write(`${CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX} ${JSON.stringify(serializeCursorPiToolBridgeDiagnostic(event))}\n`);

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

@@ -67,6 +67,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	private readonly pendingByBridgeCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByCursorMcpCallId = new Map<string, PendingBridgeCall>();
 	private onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	private debugRecorder: CursorPiToolBridgeRunOptions["debugRecorder"];
 	private liveRunHandlerDetached = false;
 	private mcpServer?: McpProtocolServer;
 	private mcpTransport?: StreamableHTTPServerTransport;
@@ -85,6 +86,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.snapshot = snapshot;
 		this.enabled = enabled;
 		this.onToolRequest = options.onToolRequest;
+		this.debugRecorder = options.debugRecorder;
 		this.id = `cursor-pi-bridge-run-${randomUUID()}`;
 		this.endpointPath = `${MCP_ENDPOINT_ROOT}/${randomUUID()}/mcp`;
 		this.knownMcpToolNames = new Set(snapshot.tools.map((tool) => tool.mcpToolName));
@@ -146,6 +148,10 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		}
 	}
 
+	setDebugRecorder(recorder?: CursorPiToolBridgeRunOptions["debugRecorder"]): void {
+		this.debugRecorder = recorder;
+	}
+
 	resolveToolResults(toolResults: readonly ToolResultMessage[]): void {
 		for (const toolResult of toolResults) {
 			const pending = this.pendingByPiToolCallId.get(toolResult.toolCallId);
@@ -290,9 +296,11 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 				}
 				this.queuedRequests.push(request);
 				this.emitRequestQueuedDiagnostic(request);
+				this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
 				return;
 			}
 			this.emitRequestQueuedDiagnostic(request);
+			this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
 			this.dispatchPendingToolRequest(pending, this.onToolRequest);
 		});
 	}
@@ -321,6 +329,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestResolvedDiagnostic(pending.request, result.isError === true);
+		this.debugRecorder?.recordBridgeRaw({ kind: "resolved", request: pending.request, result });
 		pending.resolve(result);
 	}
 
@@ -329,6 +338,12 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestRejectedDiagnostic(pending.request, kind);
+		this.debugRecorder?.recordBridgeRaw({
+			kind: "rejected",
+			request: pending.request,
+			error: error.message,
+			rejectionKind: kind,
+		});
 		pending.reject(error);
 	}
 
@@ -366,7 +381,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	}
 
 	private emitDiagnostic(event: CursorPiToolBridgeDiagnosticEvent): void {
-		writeCursorPiToolBridgeDiagnostic(this.env, event);
+		writeCursorPiToolBridgeDiagnostic(this.env, event, this.debugRecorder);
 	}
 
 	private pendingCount(): number {

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

@@ -1,5 +1,6 @@
 import type { McpServerConfig } from "@cursor/sdk";
 import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 import type {
 	ExtensionAPI,
 	ExtensionHandler,
@@ -64,6 +65,7 @@ export interface CursorPiToolBridgeRun {
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;
+	setDebugRecorder(recorder?: CursorSdkEventDebugRecorder): void;
 	cancel(reason: string): void;
 	dispose(): Promise<void>;
 }
@@ -77,4 +79,5 @@ export interface CursorPiToolBridge {
 
 export interface CursorPiToolBridgeRunOptions {
 	onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }

package/src/cursor-provider-errors.ts

@@ -0,0 +1,96 @@
+import type { RunResult } from "@cursor/sdk";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+
+export const MISSING_CURSOR_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 NETWORK_CURSOR_SDK_ERROR_MESSAGE =
+	"Cursor SDK request timed out during network I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
+
+const GENERIC_CURSOR_RUN_FAILURE_TEXT = "cursor sdk run failed";
+
+export type CursorSdkRunFailureSource = Pick<RunResult, "id" | "status" | "durationMs" | "model" | "result">;
+
+function isGenericErrorMessage(message: string): boolean {
+	const normalized = message.trim().toLowerCase();
+	return normalized === "" || normalized === "error" || normalized === "unknown error";
+}
+
+function isKnownGenericRunFailureText(message: string): boolean {
+	const normalized = message.trim().toLowerCase();
+	return normalized === "" || normalized === GENERIC_CURSOR_RUN_FAILURE_TEXT || isGenericErrorMessage(normalized);
+}
+
+function isLikelyAuthError(message: string): boolean {
+	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
+}
+
+function isLikelyNetworkTimeout(message: string): boolean {
+	return (
+		/\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAI_AGAIN)\b/i.test(message) ||
+		/\bConnectError\b.*\b(unavailable|deadline|timeout|timed out)\b/i.test(message) ||
+		/\bread ETIMEDOUT\b/i.test(message)
+	);
+}
+
+function shortRunId(runId: string): string {
+	const trimmed = runId.trim();
+	if (trimmed.length <= 12) return trimmed;
+	return `${trimmed.slice(0, 8)}…`;
+}
+
+export function formatCursorSdkRunFailureDetail(result: CursorSdkRunFailureSource, runResult?: string): string {
+	const fromWait = result.result?.trim();
+	if (fromWait && !isKnownGenericRunFailureText(fromWait)) {
+		return fromWait;
+	}
+	const fromRun = runResult?.trim();
+	if (fromRun && !isKnownGenericRunFailureText(fromRun)) {
+		return fromRun;
+	}
+
+	const parts = ["Cursor SDK run failed"];
+	if (result.model?.id) parts.push(`model ${result.model.id}`);
+	parts.push(`run ${shortRunId(result.id)}`);
+	if (typeof result.durationMs === "number") parts.push(`${result.durationMs}ms`);
+	return parts.join(" · ");
+}
+
+export type CursorSdkAbortCause = "user_interrupt" | "sdk_cancelled" | "live_run_disposed" | "unknown";
+
+export function formatCursorSdkAbortMessage(cause: CursorSdkAbortCause): string {
+	switch (cause) {
+		case "user_interrupt":
+			return "Cancelled: prompt interrupted.";
+		case "sdk_cancelled":
+			return "Cancelled: Cursor SDK run was cancelled.";
+		case "live_run_disposed":
+			return "Cancelled: Cursor SDK live run ended before completion.";
+		case "unknown":
+			return "Cancelled: Cursor SDK run aborted.";
+	}
+}
+
+export function resolveCursorSdkAbortCause(options: {
+	signalAborted?: boolean;
+	sdkStatusCancelled?: boolean;
+	liveRunDisposed?: boolean;
+}): CursorSdkAbortCause {
+	if (options.signalAborted) return "user_interrupt";
+	if (options.sdkStatusCancelled) return "sdk_cancelled";
+	if (options.liveRunDisposed) return "live_run_disposed";
+	return "unknown";
+}
+
+export function sanitizeCursorProviderError(error: unknown, apiKey?: string): string {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_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;
+	if (isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
+	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
+}

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

@@ -23,6 +23,10 @@ import { resetSessionCursorAgent } from "./cursor-session-agent.js";
 import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
 import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { hasUsableText } from "./cursor-record-utils.js";
+import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
 const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
@@ -101,6 +105,37 @@ export async function settleCursorLiveToolBatch(run: CursorLiveRun): Promise<voi
 	await scheduler.wait(75);
 }
 
+export function flushPendingCursorLiveRunTraceEventsToStream(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+	run: CursorLiveRun,
+	options?: { includeTracesBehindQueuedTools?: boolean },
+): void {
+	if (run.disposed) return;
+	const turn: CursorLiveTurnState = {
+		emitter: new CursorPartialContentEmitter(stream, partial, -1, true),
+		emittedText: "",
+	};
+	while (true) {
+		const event = cursorLiveRuns.peekEvent(run);
+		if (!event || event.type === "tool" || event.type === "bridge-tool") break;
+		cursorLiveRuns.shiftEvent(run);
+		emitCursorLiveQueuedEvent(turn, event, run);
+	}
+	if (options?.includeTracesBehindQueuedTools && run.pendingEvents.length > 0) {
+		const preserved: CursorLiveQueuedEvent[] = [];
+		for (const event of run.pendingEvents) {
+			if (event.type === "tool" || event.type === "bridge-tool") {
+				preserved.push(event);
+				continue;
+			}
+			emitCursorLiveQueuedEvent(turn, event, run);
+		}
+		run.pendingEvents = preserved;
+	}
+	turn.emitter.closeAll();
+}
+
 function emitCursorLiveQueuedEvent(
 	turn: CursorLiveTurnState,
 	event: Exclude<CursorLiveQueuedEvent, { type: "tool" } | { type: "bridge-tool" }>,
@@ -176,6 +211,7 @@ function emitCursorNativeToolUseTurn(
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
 	tools: CursorNativeToolDisplayItem[],
+	debugRecorder?: CursorSdkEventDebugRecorder,
 ): void {
 	const shouldTerminate = run.done && !run.finalText?.trim() && !cursorLiveRuns.peekEvent(run);
 	for (const tool of tools) {
@@ -192,6 +228,11 @@ function emitCursorNativeToolUseTurn(
 		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
 		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate })) {
 			run.recordedToolDisplayIds.push(tool.id);
+			debugRecorder?.recordDrainEvent("native_tool_display_recorded", {
+				toolId: tool.id,
+				toolName: tool.toolName,
+				terminate: shouldTerminate,
+			});
 		}
 	}
 	applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
@@ -200,6 +241,23 @@ function emitCursorNativeToolUseTurn(
 	cursorLiveRuns.requestIdleDispose(run);
 }
 
+function emitInactiveCursorReplayTrace(
+	turn: CursorLiveTurnState,
+	tools: CursorNativeToolDisplayItem[],
+	debugRecorder?: CursorSdkEventDebugRecorder,
+): void {
+	if (tools.length === 0) return;
+	for (const tool of tools) {
+		const traceText = formatInactiveCursorReplayTrace(tool);
+		debugRecorder?.recordDrainEvent("inactive_replay_trace", {
+			toolId: tool.id,
+			toolName: tool.toolName,
+			traceText,
+		});
+		turn.emitter.appendThinkingBlock(traceText);
+	}
+}
+
 function emitCursorBridgeToolUseTurn(
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
@@ -229,24 +287,31 @@ function emitCursorBridgeToolUseTurn(
 }
 
 async function emitCursorLiveRunPendingToolUseTurn(
+	turn: CursorLiveTurnState,
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	signal?: AbortSignal,
-	beforeEmit?: () => void,
-): Promise<"tool_use" | undefined> {
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder },
+): Promise<"tool_use" | "handled" | undefined> {
+	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	const eventType = cursorLiveRuns.peekEvent(run)?.type;
 	if (eventType !== "tool" && eventType !== "bridge-tool") return undefined;
 	await settleCursorLiveToolBatch(run);
-	if (signal?.aborted) throw new CursorLiveRunAbortError();
-	beforeEmit?.();
+	if (options.signal?.aborted) throw new CursorLiveRunAbortError();
 	if (eventType === "tool") {
-		const tools = cursorLiveRuns.collectNativeToolBatch(run);
-		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, tools);
+		const { active, inactive } = partitionNativeToolsByActiveContext(context, cursorLiveRuns.collectNativeToolBatch(run));
+		if (options.mode === "emit") emitInactiveCursorReplayTrace(turn, inactive, debugRecorder);
+		if (active.length === 0) {
+			// Inactive-only batch: trace was emitted above; do not emit toolUse.
+			return "handled";
+		}
+		if (options.mode === "emit") turn.emitter.closeAll();
+		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, debugRecorder);
 	} else {
+		if (options.mode === "emit") turn.emitter.closeAll();
 		const requests = cursorLiveRuns.collectBridgeToolBatch(run);
 		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests);
 	}
@@ -260,72 +325,123 @@ export async function drainCursorLiveRunTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder },
 ): Promise<CursorLiveRunDrainOutcome> {
+	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
+	debugRecorder?.recordDrainEvent("turn_start", {
+		mode: options.mode,
+		runId: run.id,
+		pendingEventCount: run.pendingEvents.length,
+		done: run.done,
+	});
+	let outcome: CursorLiveRunDrainOutcome | undefined;
+	let outcomeDetails: Record<string, unknown> = {};
 	const turn: CursorLiveTurnState = {
 		emitter: new CursorPartialContentEmitter(stream, partial, -1, true),
 		emittedText: "",
 	};
 
-	while (true) {
-		if (options.mode === "chain_user_input" && cursorLiveRuns.isReady(run)) {
-			await cursorLiveRuns.release(run);
-			return "chain_user_input";
-		}
+	try {
+		while (true) {
+			if (options.mode === "chain_user_input" && cursorLiveRuns.isReady(run)) {
+				await cursorLiveRuns.release(run);
+				outcome = "chain_user_input";
+				return outcome;
+			}
 
-		while (cursorLiveRuns.peekEvent(run)) {
-			const toolUse = await emitCursorLiveRunPendingToolUseTurn(
-				stream,
-				partial,
-				model,
-				context,
-				run,
-				toolResultInputTokens,
-				options.signal,
-				options.mode === "emit" ? () => turn.emitter.closeAll() : undefined,
-			);
-			if (toolUse) return toolUse;
-			const event = cursorLiveRuns.shiftEvent(run);
-			if (!event || event.type === "tool" || event.type === "bridge-tool") continue;
-			if (options.mode === "emit") emitCursorLiveQueuedEvent(turn, event, run);
-		}
+			while (cursorLiveRuns.peekEvent(run)) {
+				const toolUse = await emitCursorLiveRunPendingToolUseTurn(
+					turn,
+					stream,
+					partial,
+					model,
+					context,
+					run,
+					toolResultInputTokens,
+					options,
+				);
+				if (toolUse === "tool_use") {
+					outcome = "tool_use";
+					return outcome;
+				}
+				if (toolUse === "handled") continue;
+				const event = cursorLiveRuns.shiftEvent(run);
+				if (!event || event.type === "tool" || event.type === "bridge-tool") continue;
+				if (options.mode === "emit") emitCursorLiveQueuedEvent(turn, event, run);
+			}
 
-		if (run.disposed) {
-			partial.stopReason = "aborted";
-			stream.push({ type: "error", reason: "aborted", error: partial });
-			return "aborted";
-		}
-		if (run.cancelled) {
-			partial.stopReason = "aborted";
-			stream.push({ type: "error", reason: "aborted", error: partial });
-			await cursorLiveRuns.release(run);
-			return "aborted";
-		}
-		if (run.errorMessage) {
-			partial.stopReason = "error";
-			partial.errorMessage = run.errorMessage;
-			stream.push({ type: "error", reason: "error", error: partial });
-			await cursorLiveRuns.release(run);
-			return "error";
-		}
-		if (run.done) {
-			if (options.mode === "chain_user_input") {
+			if (run.disposed) {
+				partial.stopReason = "aborted";
+				partial.errorMessage = formatCursorSdkAbortMessage(
+					resolveCursorSdkAbortCause({ liveRunDisposed: true }),
+				);
+				stream.push({ type: "error", reason: "aborted", error: partial });
+				outcome = "aborted";
+				outcomeDetails = { reason: "disposed" };
+				return outcome;
+			}
+			if (run.cancelled) {
+				partial.stopReason = "aborted";
+				if (run.abortMessage) partial.errorMessage = run.abortMessage;
+				stream.push({ type: "error", reason: "aborted", error: partial });
 				await cursorLiveRuns.release(run);
-				return "chain_user_input";
+				outcome = "aborted";
+				outcomeDetails = { reason: "cancelled" };
+				return outcome;
 			}
-			turn.emitter.closeAll();
-			const finalText = trimCurrentTurnAlreadyEmittedCursorText(run.finalText ?? run.textDeltas.join(""), turn.emittedText, run.emittedText);
-			if (finalText) {
-				await emitTextDeltas(stream, partial, splitTextIntoReplayDeltas(finalText));
+			if (run.errorMessage) {
+				partial.stopReason = "error";
+				partial.errorMessage = run.errorMessage;
+				stream.push({ type: "error", reason: "error", error: partial });
+				await cursorLiveRuns.release(run);
+				outcome = "error";
+				return outcome;
+			}
+			if (run.done) {
+				if (options.mode === "chain_user_input") {
+					await cursorLiveRuns.release(run);
+					outcome = "chain_user_input";
+					outcomeDetails = { reason: "run_done" };
+					return outcome;
+				}
+				turn.emitter.closeAll();
+				const finalText = trimCurrentTurnAlreadyEmittedCursorText(run.finalText ?? run.textDeltas.join(""), turn.emittedText, run.emittedText);
+				if (finalText) {
+					await emitTextDeltas(stream, partial, splitTextIntoReplayDeltas(finalText));
+				}
+				applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
+				partial.stopReason = "stop";
+				stream.push({ type: "done", reason: "stop", message: partial });
+				await cursorLiveRuns.release(run);
+				outcome = "stop";
+				outcomeDetails = { finalTextLength: finalText.length };
+				return outcome;
 			}
-			applyCursorApproximateUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens));
-			partial.stopReason = "stop";
-			stream.push({ type: "done", reason: "stop", message: partial });
-			await cursorLiveRuns.release(run);
-			return "stop";
-		}
 
-		await cursorLiveRuns.waitForProgress(run, options.signal);
+			await cursorLiveRuns.waitForProgress(run, options.signal);
+		}
+	} catch (error) {
+		if (!outcome) {
+			if (error instanceof CursorLiveRunAbortError) {
+				outcome = "aborted";
+				outcomeDetails = { reason: "signal_aborted" };
+			} else {
+				outcome = "error";
+				outcomeDetails = {
+					reason: "drain_error",
+					errorMessage: error instanceof Error ? error.message : String(error),
+				};
+			}
+		}
+		throw error;
+	} finally {
+		debugRecorder?.recordDrainEvent("turn_end", {
+			outcome: outcome ?? "error",
+			runId: run.id,
+			pendingEventCount: run.pendingEvents.length,
+			done: run.done,
+			...outcomeDetails,
+		});
 	}
 }
 
@@ -335,10 +451,15 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	model: Model<Api>,
 	context: Context,
 	signal?: AbortSignal,
+	turnDebugRecorder?: CursorSdkEventDebugRecorder,
 ): Promise<LiveRunPreSendOutcome> {
+	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
 		const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
-		if (!run || run.disposed) return "continue_send";
+		if (!run || run.disposed) {
+			turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
+			return "continue_send";
+		}
 
 		try {
 			const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
@@ -354,14 +475,28 @@ export async function drainExistingCursorLiveRunBeforeSend(
 				const drainOutcome = await drainCursorLiveRunTurn(stream, partial, model, context, run, consumed.toolResultInputTokens, {
 					mode: shouldChainUserInput ? "chain_user_input" : "emit",
 					signal,
+					debugRecorder: turnDebugRecorder,
+				});
+				const mapped = drainOutcome === "chain_user_input" ? "continue_send" : "stream_ended";
+				turnDebugRecorder?.recordDrainEvent("pre_send_iteration", {
+					runId: run.id,
+					drainOutcome,
+					outcome: mapped,
+					shouldChainUserInput,
 				});
-				return drainOutcome === "chain_user_input" ? "continue_send" : "stream_ended";
+				return mapped;
 			});
 			if (outcome === "continue_send" && !run.disposed && cursorLiveRuns.getActiveForScope(run.sessionAgentScopeKey) === run) {
 				continue;
 			}
+			turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome, runId: run.id });
 			return outcome;
 		} catch (error) {
+			turnDebugRecorder?.recordDrainEvent("pre_send_end", {
+				outcome: error instanceof CursorLiveRunAbortError ? "aborted" : "error",
+				runId: run.id,
+				reason: error instanceof CursorLiveRunAbortError ? "signal_aborted" : "drain_error",
+			});
 			if (error instanceof CursorLiveRunAbortError) await cursorLiveRuns.release(run);
 			throw error;
 		}
@@ -376,4 +511,14 @@ export function resetCursorNativeReplayIdleDisposeMs(): void {
 	cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
 }
 
+export async function releaseAllPendingCursorLiveRunsForTests(): Promise<void> {
+	while (cursorLiveRuns.count() > 0) {
+		const run = cursorLiveRuns.getActiveForScope();
+		if (!run) break;
+		const before = cursorLiveRuns.count();
+		await cursorLiveRuns.release(run);
+		if (cursorLiveRuns.count() >= before) break;
+	}
+}
+
 export { hasTrailingUserMessagesAfterToolResults };