pi-cursor-sdk 0.1.20 → 0.1.21

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

@@ -17,22 +17,147 @@ import {
 	isCursorReplayToolName,
 } from "./cursor-tool-names.js";
 import {
-	asCursorReplayToolDetails,
 	createCursorReplayOnlyToolDefinition,
+	isCursorReplayNativeEditDetails,
+	isCursorReplayNativeWriteDetails,
+	parseCursorReplayToolDetails,
 	renderCursorReplayResult,
 	renderNativeLookingCursorFileMutationCall,
 	renderNativeLookingCursorReadReplayResult,
 } from "./cursor-native-tool-display-replay.js";
 import {
 	consumeCursorNativeToolDisplay,
-	isCursorFileMutationToolName,
 	isCursorReplayToolCallId,
 } from "./cursor-native-tool-display-state.js";
 
 const CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
 const CURSOR_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME, ...CURSOR_REPLAY_LEGACY_TOOL_NAMES] as const;
-export const NATIVE_CURSOR_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls", ...CURSOR_REPLAY_TOOL_NAMES] as const;
-export type NativeCursorToolName = (typeof NATIVE_CURSOR_TOOL_NAMES)[number];
+
+type AnyToolDefinition = ToolDefinition<TSchema, unknown, unknown>;
+type RenderCall = NonNullable<AnyToolDefinition["renderCall"]>;
+type RenderResult = NonNullable<AnyToolDefinition["renderResult"]>;
+
+type NativeReplayStrategy = {
+	createDefinition: (cwd: string) => AnyToolDefinition;
+	missingReplayPolicy?: "block-file-mutation";
+	renderReplayCall?: (
+		args: Parameters<RenderCall>[0],
+		theme: Parameters<RenderCall>[1],
+		context: Parameters<RenderCall>[2],
+		renderBase: () => ReturnType<RenderCall>,
+	) => ReturnType<RenderCall>;
+	renderReplayResult?: (
+		result: Parameters<RenderResult>[0],
+		options: Parameters<RenderResult>[1],
+		theme: Parameters<RenderResult>[2],
+		context: Parameters<RenderResult>[3],
+		renderBase: () => ReturnType<RenderResult>,
+	) => ReturnType<RenderResult>;
+};
+
+function emptyText(): Text {
+	return new Text("", 0, 0);
+}
+
+function renderReadReplayCall(
+	args: Parameters<RenderCall>[0],
+	theme: Parameters<RenderCall>[1],
+	context: Parameters<RenderCall>[2],
+	renderBase: () => ReturnType<RenderCall>,
+): ReturnType<RenderCall> {
+	const rendered = renderBase();
+	if ((args as Record<string, unknown>).localReadPreview !== true || context.expanded) return rendered;
+	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);
+}
+
+function renderReadReplayResult(
+	result: Parameters<RenderResult>[0],
+	options: Parameters<RenderResult>[1],
+	theme: Parameters<RenderResult>[2],
+	context: Parameters<RenderResult>[3],
+	renderBase: () => ReturnType<RenderResult>,
+): ReturnType<RenderResult> {
+	return renderNativeLookingCursorReadReplayResult(
+		result,
+		options,
+		theme,
+		context as Parameters<typeof renderNativeLookingCursorReadReplayResult>[3],
+		renderBase,
+	);
+}
+
+function renderEditReplayResult(
+	result: Parameters<RenderResult>[0],
+	options: Parameters<RenderResult>[1],
+	theme: Parameters<RenderResult>[2],
+	context: Parameters<RenderResult>[3],
+	renderBase: () => ReturnType<RenderResult>,
+): ReturnType<RenderResult> {
+	const details = parseCursorReplayToolDetails(result.details);
+	return details && isCursorReplayNativeEditDetails(details)
+		? renderCursorReplayResult(result, options, theme, context as Parameters<typeof renderCursorReplayResult>[3], context.isError)
+		: renderBase();
+}
+
+function renderWriteReplayResult(
+	result: Parameters<RenderResult>[0],
+	options: Parameters<RenderResult>[1],
+	theme: Parameters<RenderResult>[2],
+	context: Parameters<RenderResult>[3],
+	renderBase: () => ReturnType<RenderResult>,
+): ReturnType<RenderResult> {
+	const details = parseCursorReplayToolDetails(result.details);
+	return details && isCursorReplayNativeWriteDetails(details)
+		? renderCursorReplayResult(result, options, theme, context as Parameters<typeof renderCursorReplayResult>[3], context.isError)
+		: renderBase();
+}
+
+type BuiltinNativeCursorToolName = "read" | "bash" | "edit" | "write" | "grep" | "find" | "ls";
+
+const NATIVE_CURSOR_TOOL_STRATEGIES: Record<BuiltinNativeCursorToolName, NativeReplayStrategy> = {
+	read: {
+		createDefinition: (cwd) => createReadToolDefinition(cwd) as AnyToolDefinition,
+		renderReplayCall: renderReadReplayCall,
+		renderReplayResult: renderReadReplayResult,
+	},
+	bash: { createDefinition: (cwd) => createBashToolDefinition(cwd) as AnyToolDefinition },
+	edit: {
+		createDefinition: (cwd) => createEditToolDefinition(cwd) as AnyToolDefinition,
+		missingReplayPolicy: "block-file-mutation",
+		renderReplayCall: (args, theme, context) =>
+			renderNativeLookingCursorFileMutationCall("edit", args as Record<string, unknown>, theme, context.isPartial),
+		renderReplayResult: renderEditReplayResult,
+	},
+	write: {
+		createDefinition: (cwd) => createWriteToolDefinition(cwd) as AnyToolDefinition,
+		missingReplayPolicy: "block-file-mutation",
+		renderReplayCall: (args, theme, context) =>
+			renderNativeLookingCursorFileMutationCall("write", args as Record<string, unknown>, theme, context.isPartial),
+		renderReplayResult: renderWriteReplayResult,
+	},
+	grep: { createDefinition: (cwd) => createGrepToolDefinition(cwd) as AnyToolDefinition },
+	find: { createDefinition: (cwd) => createFindToolDefinition(cwd) as AnyToolDefinition },
+	ls: { createDefinition: (cwd) => createLsToolDefinition(cwd) as AnyToolDefinition },
+};
+
+const BUILTIN_NATIVE_CURSOR_TOOL_NAMES = Object.keys(NATIVE_CURSOR_TOOL_STRATEGIES) as BuiltinNativeCursorToolName[];
+export const NATIVE_CURSOR_TOOL_NAMES = [
+	...BUILTIN_NATIVE_CURSOR_TOOL_NAMES,
+	...CURSOR_REPLAY_TOOL_NAMES,
+] as readonly NativeCursorToolName[];
+export type NativeCursorToolName = BuiltinNativeCursorToolName | typeof CURSOR_REPLAY_TOOL_NAMES[number];
+
+function getNativeReplayStrategy(toolName: string): NativeReplayStrategy | undefined {
+	return Object.hasOwn(NATIVE_CURSOR_TOOL_STRATEGIES, toolName)
+		? NATIVE_CURSOR_TOOL_STRATEGIES[toolName as BuiltinNativeCursorToolName]
+		: undefined;
+}
 
 export function isNativeCursorToolName(toolName: string): toolName is NativeCursorToolName {
 	return NATIVE_CURSOR_TOOL_NAMES.some((nativeToolName) => nativeToolName === toolName);
@@ -42,6 +167,7 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 	definition: ToolDefinition<TParams, TDetails, TState>,
 	getCurrentDefinition: () => ToolDefinition<TParams, TDetails, TState>,
 ): ToolDefinition<TParams, TDetails, TState> {
+	const strategy = getNativeReplayStrategy(definition.name);
 	return {
 		...definition,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -60,61 +186,43 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 					terminate: cursorDisplay.terminate ?? true,
 				};
 			}
-			if (isCursorFileMutationToolName(definition.name) && isCursorReplayToolCallId(toolCallId)) {
+			if (strategy?.missingReplayPolicy === "block-file-mutation" && isCursorReplayToolCallId(toolCallId)) {
 				throw new Error(`No recorded Cursor ${definition.name} result was available. This replay-only call does not execute file mutations.`);
 			}
 			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);
-			}
 			const currentRenderCall = getCurrentDefinition().renderCall;
-			return currentRenderCall ? currentRenderCall(args, theme, context) : new Text("", 0, 0);
+			const renderBase = () => currentRenderCall?.(args, theme, context) ?? emptyText();
+			const isReplayCall = typeof context.toolCallId === "string" && isCursorReplayToolCallId(context.toolCallId);
+			if (isReplayCall && strategy?.renderReplayCall) {
+				return strategy.renderReplayCall(args, theme, context, renderBase) as ReturnType<NonNullable<ToolDefinition<TParams, TDetails, TState>["renderCall"]>>;
+			}
+			return renderBase();
 		},
 		renderResult(result, options, theme, context) {
-			const details = asCursorReplayToolDetails(result.details);
-			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);
+			const renderBase = () => currentRenderResult?.(result, options, theme, context) ?? emptyText();
+			const isReplayCall = typeof context.toolCallId === "string" && isCursorReplayToolCallId(context.toolCallId);
+			if (isReplayCall && strategy?.renderReplayResult) {
+				return strategy.renderReplayResult(result, options, theme, context, renderBase) as ReturnType<NonNullable<ToolDefinition<TParams, TDetails, TState>["renderResult"]>>;
+			}
+			return renderBase();
 		},
 	};
 }
 
 export function createNativeCursorToolDefinition(toolName: NativeCursorToolName, cwd: string): ToolDefinition<TSchema, unknown, unknown> {
-	if (toolName === "read") return createReadToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "bash") return createBashToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "edit") return createEditToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "write") return createWriteToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "grep") return createGrepToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "find") return createFindToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
-	if (toolName === "ls") return createLsToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
+	const strategy = getNativeReplayStrategy(toolName);
+	if (strategy) return strategy.createDefinition(cwd);
 	if (isCursorReplayToolName(toolName)) return createCursorReplayOnlyToolDefinition(toolName) as ToolDefinition<TSchema, unknown, unknown>;
 	throw new Error(`Unsupported Cursor native replay tool: ${toolName}`);
 }
 
-export function registerNativeCursorTool(pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerTool">, toolName: NativeCursorToolName): void {
+export function registerNativeCursorTool(
+	pi: Pick<import("@earendil-works/pi-coding-agent").ExtensionAPI, "registerTool">,
+	toolName: NativeCursorToolName,
+): void {
 	const definition = createNativeCursorToolDefinition(toolName, getCursorSessionCwd());
 	pi.registerTool(wrapNativeCursorTool(definition, () => createNativeCursorToolDefinition(toolName, getCursorSessionCwd())));
 }

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

@@ -22,7 +22,7 @@ import { type CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
 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 { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text.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";
@@ -152,57 +152,6 @@ function emitCursorLiveQueuedEvent(
 	}
 }
 
-function isCursorTextBoundary(text: string, index: number): boolean {
-	if (index <= 0 || index >= text.length) return true;
-	const before = text[index - 1];
-	const after = text[index];
-	return !/[\p{L}\p{N}_]/u.test(before) || !/[\p{L}\p{N}_]/u.test(after);
-}
-
-function trimAlreadyEmittedCursorText(text: string, emittedText: string, options?: { allowPartialPrefix?: boolean }): string {
-	if (!text || !emittedText) return text;
-	if (text === emittedText) return "";
-	if (text.startsWith(emittedText) && (options?.allowPartialPrefix || isCursorTextBoundary(text, emittedText.length))) {
-		return text.slice(emittedText.length);
-	}
-	if (emittedText.endsWith(text) && isCursorTextBoundary(emittedText, emittedText.length - text.length)) return "";
-	const trimmedText = text.trim();
-	const trimmedEmittedText = emittedText.trim();
-	if (trimmedText === trimmedEmittedText) return "";
-	if (trimmedText && trimmedEmittedText.endsWith(trimmedText)) {
-		const suffixStart = trimmedEmittedText.length - trimmedText.length;
-		if (isCursorTextBoundary(trimmedEmittedText, suffixStart)) return "";
-	}
-	return text;
-}
-
-function trimCurrentTurnAlreadyEmittedCursorText(text: string, currentTurnEmittedText: string, emittedText = currentTurnEmittedText): string {
-	if (!currentTurnEmittedText) return trimAlreadyEmittedCursorText(text, emittedText);
-	const currentTurnTrimmedText = trimAlreadyEmittedCursorText(text, currentTurnEmittedText, { allowPartialPrefix: true });
-	if (currentTurnTrimmedText !== text) return currentTurnTrimmedText;
-	if (emittedText.endsWith(currentTurnEmittedText)) {
-		const emittedTextTrimmedText = trimAlreadyEmittedCursorText(text, emittedText, { allowPartialPrefix: true });
-		if (emittedTextTrimmedText !== text) return emittedTextTrimmedText;
-	}
-	return trimAlreadyEmittedCursorText(text, emittedText);
-}
-
-export function selectCursorFinalText(
-	resultText: unknown,
-	textDeltas: readonly string[],
-	emittedText: string,
-	fallbackText?: string,
-	options?: { allowPartialPrefix?: boolean },
-): string {
-	const candidates = [typeof resultText === "string" ? resultText : undefined, fallbackText, textDeltas.join("")];
-	for (const candidate of candidates) {
-		if (!hasUsableText(candidate)) continue;
-		const trimmedCandidate = trimAlreadyEmittedCursorText(candidate, emittedText, options);
-		if (hasUsableText(trimmedCandidate)) return trimmedCandidate;
-	}
-	return "";
-}
-
 function emitCursorNativeToolUseTurn(
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,

package/src/cursor-provider-run-finalizer.ts

@@ -0,0 +1,235 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { abandonSessionCursorAgent } from "./cursor-provider-live-run-drain.js";
+import {
+	classifyCursorRunEmission,
+	getCursorRunAbortMessage,
+	type CursorRunOutcome,
+} from "./cursor-provider-run-outcome.js";
+import {
+	formatCursorSdkAbortMessage,
+	resolveCursorSdkAbortCause,
+	sanitizeCursorProviderError,
+} from "./cursor-provider-errors.js";
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import type { IncompleteCursorToolRunOutcomeInput } from "./cursor-incomplete-tool-visibility.js";
+import type { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
+import type {
+	CursorProviderTurnPrepareResult,
+	CursorProviderTurnRunnerParams,
+	CursorProviderTurnSend,
+	CursorProviderTurnSendResult,
+} from "./cursor-provider-turn-types.js";
+import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
+import { hasUsableText } from "./cursor-record-utils.js";
+import { buildIncompleteCursorToolRunOutcome } from "./cursor-incomplete-tool-visibility.js";
+
+export type CursorTurnTerminalEvent =
+	| {
+			kind: "direct";
+			prepared: CursorProviderTurnPrepareResult;
+			outcome: CursorRunOutcome;
+	  }
+	| { kind: "error"; prepared: CursorProviderTurnPrepareResult | undefined; error: unknown };
+
+function applyLiveRunOutcome(
+	outcome: CursorRunOutcome,
+	prepared: CursorProviderTurnPrepareResult,
+	context: CursorProviderTurnRunnerParams["context"],
+): void {
+	if (prepared.runtime.kind !== "live" || prepared.runtime.liveRun.disposed) return;
+	const { liveRun } = prepared.runtime;
+	switch (classifyCursorRunEmission(outcome)) {
+		case "finished":
+			prepared.sessionAgentLease.commitSend(context, prepared.meta.bootstrap);
+			cursorLiveRuns.markFinished(liveRun, outcome.kind === "finished" ? outcome.finalText : "");
+			break;
+		case "cancelled":
+			cursorLiveRuns.markCancelled(liveRun, getCursorRunAbortMessage(outcome));
+			break;
+		case "failed":
+			cursorLiveRuns.markError(liveRun, outcome.kind === "error" ? outcome.errorMessage : "Cursor SDK run failed.");
+			break;
+	}
+}
+
+export interface CursorLiveRunCompletion {
+	waitCompletion: Promise<void>;
+	prepared: CursorProviderTurnPrepareResult;
+}
+
+export interface CursorRunFinalizerParams {
+	runnerParams: CursorProviderTurnRunnerParams;
+	sdkEventDebug: () => CursorSdkEventDebugSink | undefined;
+	sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>;
+	resolvedApiKey: () => string | undefined;
+}
+
+export interface StartCursorLiveRunCompletionParams {
+	send: CursorProviderTurnSend;
+	prepared: CursorProviderTurnPrepareResult;
+	modelId: string;
+	discardIncompleteTools: (outcome: IncompleteCursorToolRunOutcomeInput) => void;
+}
+
+export class CursorRunFinalizer {
+	private terminalApplied = false;
+
+	constructor(private readonly params: CursorRunFinalizerParams) {}
+
+	startLiveRunCompletion(startParams: StartCursorLiveRunCompletionParams): CursorLiveRunCompletion {
+		const { runnerParams } = this.params;
+		const sdkEventDebug = this.params.sdkEventDebug();
+		const { send, prepared, modelId, discardIncompleteTools } = startParams;
+		const { run, cursorAgentMessageOffset } = send;
+		if (prepared.runtime.kind !== "live") throw new Error("startLiveRunCompletion requires a live run");
+		const { liveRun } = prepared.runtime;
+		const waitCompletion = awaitFinalizeCursorRunOutcome({
+			run,
+			prepared,
+			cursorAgentMessageOffset,
+			modelId,
+			signal: runnerParams.options?.signal,
+			runResultFallback: run.result,
+			resolvedApiKey: this.params.resolvedApiKey(),
+			optionsApiKey: runnerParams.options?.apiKey,
+			sdkEventDebug,
+			cacheContextWindow: true,
+			contextWindowAgentId: liveRun.agent.agentId,
+		})
+			.then(async (outcome) => {
+				applyLiveRunOutcome(outcome, prepared, runnerParams.context);
+			})
+			.catch(async (error: unknown) => {
+				sdkEventDebug?.recordWaitResult({ status: "error", error: String(error) });
+				sdkEventDebug?.recordError("run_wait", error);
+				discardIncompleteTools({ status: "error" });
+				await sdkEventDebug?.captureRunArtifacts(run);
+				if (liveRun.disposed) return;
+				cursorLiveRuns.markError(
+					liveRun,
+					sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? runnerParams.options?.apiKey),
+				);
+			});
+		return { waitCompletion, prepared };
+	}
+
+	async applyTerminalEvent(event: CursorTurnTerminalEvent): Promise<void> {
+		if (this.terminalApplied) return;
+		if (event.kind === "direct") {
+			await this.applyDirectOutcome(event.prepared, event.outcome);
+			this.terminalApplied = true;
+			return;
+		}
+		await this.applyErrorOutcome(event.prepared, event.error);
+		this.terminalApplied = true;
+	}
+
+	async cleanup(
+		prepared: CursorProviderTurnPrepareResult | undefined,
+		sendResult: CursorProviderTurnSendResult | undefined,
+		liveCompletion: CursorLiveRunCompletion | undefined,
+	): Promise<void> {
+		this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
+		const abortRegistration = sendResult?.abortRegistration;
+		if (abortRegistration) {
+			this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
+		}
+		this.params.runnerParams.sdkEventDebugRef.current = undefined;
+		if (liveCompletion) {
+			this.safeCleanup(() => liveCompletion.prepared.sessionAgentLease.trackRunCompletion(liveCompletion.waitCompletion));
+			void liveCompletion.waitCompletion
+				.finally(async () => {
+					await this.finalizeSdkEventDebugBestEffort();
+					this.safeCleanup(() => this.params.sdkAbortErrorSuppression.dispose());
+				})
+				.catch(() => {});
+			return;
+		}
+		await this.finalizeSdkEventDebugBestEffort();
+		this.safeCleanup(() => this.params.sdkAbortErrorSuppression.dispose());
+	}
+
+	private async applyDirectOutcome(
+		prepared: CursorProviderTurnPrepareResult,
+		outcome: CursorRunOutcome,
+	): Promise<void> {
+		const { stream, partial, model, context } = this.params.runnerParams;
+		prepared.runtime.turnCoordinator.closeTraceBlock();
+		switch (classifyCursorRunEmission(outcome)) {
+			case "cancelled":
+				await abandonSessionCursorAgent(prepared.sessionAgentScopeKey);
+				this.pushTerminalError(partial, "aborted", getCursorRunAbortMessage(outcome));
+				break;
+			case "failed":
+				await abandonSessionCursorAgent(prepared.sessionAgentScopeKey);
+				this.pushTerminalError(partial, "error", outcome.kind === "error" ? outcome.errorMessage : "Cursor SDK run failed.");
+				break;
+			case "finished":
+				prepared.sessionAgentLease.commitSend(context, prepared.meta.bootstrap);
+				prepared.runtime.turnCoordinator.flushText(
+					outcome.kind === "finished" && hasUsableText(outcome.finalText) ? [outcome.finalText] : [],
+				);
+				applyCursorApproximateUsage(partial, model, context, prepared.meta.promptInputTokens);
+				stream.push({ type: "done", reason: "stop", message: partial });
+				break;
+		}
+	}
+
+	private async applyErrorOutcome(prepared: CursorProviderTurnPrepareResult | undefined, error: unknown): Promise<void> {
+		this.params.sdkEventDebug()?.recordError("provider_stream", error);
+		prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(
+			buildIncompleteCursorToolRunOutcome({
+				status: error instanceof CursorLiveRunAbortError ? "cancelled" : "error",
+				signalAborted: error instanceof CursorLiveRunAbortError,
+			}),
+		);
+		const activeLiveRun = prepared?.runtime.liveRun;
+		if (activeLiveRun && !activeLiveRun.disposed) {
+			await cursorLiveRuns.release(activeLiveRun);
+		} else {
+			await abandonSessionCursorAgent(prepared?.sessionAgentScopeKey);
+		}
+		if (error instanceof CursorLiveRunAbortError) {
+			this.params.sdkAbortErrorSuppression.suppressAbortErrors();
+			this.pushTerminalError(this.params.runnerParams.partial, "aborted", this.abortMessage());
+		} else {
+			this.pushTerminalError(
+				this.params.runnerParams.partial,
+				"error",
+				sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? this.params.runnerParams.options?.apiKey),
+			);
+		}
+	}
+
+	private pushTerminalError(partial: AssistantMessage, reason: "error" | "aborted", message: string): void {
+		partial.stopReason = reason;
+		partial.errorMessage = message;
+		this.params.runnerParams.stream.push({ type: "error", reason, error: partial });
+	}
+
+	private abortMessage(): string {
+		return formatCursorSdkAbortMessage(
+			resolveCursorSdkAbortCause({ signalAborted: this.params.runnerParams.options?.signal?.aborted }),
+		);
+	}
+
+	private safeCleanup(cleanup: () => void): void {
+		try {
+			cleanup();
+		} catch {
+			// Cleanup must not reclassify an already-emitted provider turn.
+		}
+	}
+
+	private async finalizeSdkEventDebugBestEffort(): Promise<void> {
+		try {
+			this.params.sdkEventDebug()?.recordFinalPartial(this.params.runnerParams.partial);
+			await this.params.sdkEventDebug()?.finalize();
+		} catch {
+			// Debug artifact IO is best-effort and must not emit a second terminal event.
+		}
+	}
+}

package/src/cursor-provider-run-outcome.ts

@@ -0,0 +1,149 @@
+import type { RunResult } from "@cursor/sdk";
+import { selectCursorFinalText } from "./cursor-run-final-text.js";
+import {
+	formatCursorSdkAbortMessage,
+	formatCursorSdkRunFailureDetail,
+	resolveCursorSdkAbortCause,
+	sanitizeCursorProviderError,
+} from "./cursor-provider-errors.js";
+import { hasUsableText } from "./cursor-record-utils.js";
+import {
+	buildIncompleteCursorToolRunOutcome,
+	type IncompleteCursorToolRunOutcome,
+	type IncompleteCursorToolRunOutcomeInput,
+} from "./cursor-incomplete-tool-visibility.js";
+
+/** Unified SDK wait() facts consumed by live and direct emission strategies. */
+export type CursorRunOutcome =
+	| {
+			kind: "finished";
+			waitResult: RunResult;
+			finalText: string;
+			incompleteTools: IncompleteCursorToolRunOutcome;
+			assistantTextProduced: boolean;
+	  }
+	| {
+			kind: "cancelled";
+			waitResult: RunResult;
+			incompleteTools: IncompleteCursorToolRunOutcome;
+			abortMessage: string;
+	  }
+	| {
+			kind: "error";
+			waitResult: RunResult;
+			incompleteTools: IncompleteCursorToolRunOutcome;
+			errorMessage: string;
+	  };
+
+export interface ResolveCursorRunOutcomeParams {
+	waitResult: RunResult;
+	signalAborted?: boolean;
+	textDeltas: readonly string[];
+	emittedText: string;
+	planTextCandidate?: string;
+	selectFinalTextOptions?: { allowPartialPrefix?: boolean };
+	runResultFallback?: string;
+	resolvedApiKey?: string;
+	optionsApiKey?: string;
+}
+
+function hasCursorAssistantText(
+	resultText: unknown,
+	textDeltas: readonly string[],
+	fallbackText?: string,
+): boolean {
+	return (
+		hasUsableText(typeof resultText === "string" ? resultText : undefined) ||
+		hasUsableText(textDeltas.join("")) ||
+		hasUsableText(fallbackText)
+	);
+}
+
+export function isCursorRunFinishedSuccessfully(outcome: CursorRunOutcome): boolean {
+	return outcome.kind === "finished";
+}
+
+function buildCursorRunAbortMessage(signalAborted: boolean | undefined, sdkStatusCancelled: boolean): string {
+	return formatCursorSdkAbortMessage(
+		resolveCursorSdkAbortCause({
+			signalAborted,
+			sdkStatusCancelled,
+		}),
+	);
+}
+
+export function resolveCursorRunOutcome(params: ResolveCursorRunOutcomeParams): CursorRunOutcome {
+	const { waitResult, signalAborted } = params;
+	const sdkCancelled = waitResult.status === "cancelled";
+	const callerAborted = signalAborted === true;
+
+	if (callerAborted || sdkCancelled) {
+		const incompleteTools = buildIncompleteCursorToolRunOutcome({
+			status: "cancelled",
+			signalAborted: callerAborted,
+			assistantTextProduced: false,
+		});
+		return {
+			kind: "cancelled",
+			waitResult,
+			incompleteTools,
+			abortMessage: buildCursorRunAbortMessage(callerAborted, sdkCancelled),
+		};
+	}
+
+	if (waitResult.status === "error") {
+		const failureDetail = formatCursorSdkRunFailureDetail(waitResult, params.runResultFallback);
+		return {
+			kind: "error",
+			waitResult,
+			incompleteTools: buildIncompleteCursorToolRunOutcome({
+				status: "error",
+				assistantTextProduced: false,
+			}),
+			errorMessage: sanitizeCursorProviderError(failureDetail, params.resolvedApiKey ?? params.optionsApiKey),
+		};
+	}
+
+	const assistantTextProduced = hasCursorAssistantText(
+		waitResult.result,
+		params.textDeltas,
+		params.planTextCandidate,
+	);
+	const incompleteTools = buildIncompleteCursorToolRunOutcome({
+		status: waitResult.status,
+		assistantTextProduced,
+	});
+	const finalText = selectCursorFinalText(
+		waitResult.result,
+		params.textDeltas,
+		params.emittedText,
+		params.planTextCandidate,
+		params.selectFinalTextOptions,
+	);
+
+	return {
+		kind: "finished",
+		waitResult,
+		finalText,
+		incompleteTools,
+		assistantTextProduced,
+	};
+}
+
+export type CursorRunEmission = "finished" | "cancelled" | "failed";
+
+export function classifyCursorRunEmission(outcome: CursorRunOutcome): CursorRunEmission {
+	switch (outcome.kind) {
+		case "finished":
+			return "finished";
+		case "cancelled":
+			return "cancelled";
+		case "error":
+			return "failed";
+	}
+}
+
+export function getCursorRunAbortMessage(outcome: CursorRunOutcome): string {
+	if (outcome.kind === "cancelled") return outcome.abortMessage;
+	return buildCursorRunAbortMessage(false, outcome.waitResult.status === "cancelled");
+}