pi-cursor-sdk 0.1.3 → 0.1.5

package/src/cursor-provider.ts

@@ -9,10 +9,17 @@ import {
 } from "@earendil-works/pi-ai";
 import { Agent, createAgentPlatform } from "@cursor/sdk";
 import type { InteractionUpdate, SDKAgent } from "@cursor/sdk";
-import { buildCursorPrompt } from "./context.js";
+import { buildCursorPrompt, type CursorPrompt } from "./context.js";
 import { getEffectiveFastForModelId } from "./cursor-state.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
+import { buildCursorPiToolDisplay, formatCursorToolTranscript, mergeCursorToolCalls } from "./cursor-tool-transcript.js";
+import {
+	canRenderCursorToolNatively,
+	isCursorNativeToolDisplayRuntimeEnabled,
+	recordCursorNativeToolDisplay,
+	type CursorNativeToolDisplayItem,
+} from "./cursor-native-tool-display.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {
@@ -43,11 +50,44 @@ class CursorAbortError extends Error {
 
 const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
 const MISSING_API_KEY_MESSAGE =
-	"Cursor SDK runs require CURSOR_API_KEY or pi --api-key. Set CURSOR_API_KEY before starting pi, or restart pi with --api-key.";
+	"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. Verify CURSOR_API_KEY or pass --api-key, then retry.";
+	"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. Verify CURSOR_API_KEY or pass --api-key, then retry.";
+	"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 APPROX_CHARS_PER_TOKEN = 4;
+const IMAGE_TOKEN_ESTIMATE = 1200;
+const CURSOR_ACTIVITY_TRACE_MAX_CHARS = 50000;
+const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
+
+type CursorNativeQueuedEvent =
+	| { type: "thinking-delta"; text: string }
+	| { type: "thinking-completed" }
+	| { type: "text-delta"; text: string }
+	| { type: "tool"; tool: CursorNativeToolDisplayItem };
+
+interface CursorNativeLiveRun {
+	id: string;
+	agent: SDKAgent;
+	promptInputTokens: number;
+	pendingEvents: CursorNativeQueuedEvent[];
+	textDeltas: string[];
+	finalText?: string;
+	done: boolean;
+	cancelled: boolean;
+	errorMessage?: string;
+	waiters: Set<() => void>;
+}
+
+interface CursorNativeTurnState {
+	stream: AssistantMessageEventStream;
+	partial: AssistantMessage;
+	thinkingContentIndex: number;
+	textContentIndex: number;
+}
+
+let cursorNativeReplayCounter = 0;
+const pendingCursorNativeRuns = new Map<string, CursorNativeLiveRun>();
 
 function escapeRegExp(value: string): string {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -77,12 +117,11 @@ function isLikelyAuthError(message: string): boolean {
 	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
 }
 
-function hasEnvCursorApiKey(): boolean {
-	return Boolean(process.env.CURSOR_API_KEY?.trim());
-}
-
-function isMissingCursorApiKey(apiKey?: string): boolean {
-	return !apiKey || (apiKey === CURSOR_API_KEY_ENV_VAR && !hasEnvCursorApiKey());
+function resolveCursorApiKey(apiKey?: string): string | undefined {
+	const trimmed = apiKey?.trim();
+	if (!trimmed) return undefined;
+	if (trimmed === CURSOR_API_KEY_ENV_VAR) return process.env.CURSOR_API_KEY?.trim();
+	return trimmed;
 }
 
 function sanitizeError(error: unknown, apiKey?: string): string {
@@ -107,10 +146,6 @@ function getCursorToolName(toolCall: unknown): string {
 	return "unknown";
 }
 
-function getCursorToolResult(toolCall: unknown): unknown {
-	return getObjectField(toolCall, "result");
-}
-
 async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<void> {
 	try {
 		const platform = await createAgentPlatform();
@@ -122,15 +157,327 @@ async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<
 	}
 }
 
-function summarizeCursorToolResult(result: unknown): string {
-	if (result === undefined) return "";
-	const parts: string[] = [];
-	const status = getObjectField(result, "status");
-	if (typeof status === "string") parts.push(status);
-	const value = getObjectField(result, "value");
-	const exitCode = getObjectField(value, "exitCode") ?? getObjectField(result, "exitCode");
-	if (typeof exitCode === "number") parts.push(`exit ${exitCode}`);
-	return parts.length > 0 ? `: ${parts.join(", ")}` : "";
+function estimateTextTokens(text: string): number {
+	return Math.ceil(text.length / APPROX_CHARS_PER_TOKEN);
+}
+
+function estimatePromptInputTokens(prompt: CursorPrompt): number {
+	return estimateTextTokens(prompt.text) + prompt.images.length * IMAGE_TOKEN_ESTIMATE;
+}
+
+function setApproximateUsage(partial: AssistantMessage, promptInputTokens: number, outputText: string): void {
+	partial.usage.input = promptInputTokens;
+	partial.usage.output = estimateTextTokens(outputText);
+	partial.usage.cacheRead = 0;
+	partial.usage.cacheWrite = 0;
+	partial.usage.totalTokens = partial.usage.input + partial.usage.output;
+}
+
+function sanitizeSingleLine(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+function truncateSingleLine(value: string, maxLength = 240): string {
+	const sanitized = sanitizeSingleLine(value);
+	return sanitized.length > maxLength ? `${sanitized.slice(0, maxLength - 1)}…` : sanitized;
+}
+
+function formatCursorToolName(toolCall: unknown): string {
+	return truncateSingleLine(getCursorToolName(toolCall), 80) || "unknown";
+}
+
+function hasUsableText(value: string | undefined): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function scrubDisplayValue(value: unknown, apiKey?: string): unknown {
+	if (typeof value === "string") return scrubSensitiveText(value, apiKey);
+	if (Array.isArray(value)) return value.map((entry) => scrubDisplayValue(entry, apiKey));
+	if (value && typeof value === "object") {
+		return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
+	}
+	return value;
+}
+
+function createCursorNativeReplayId(): string {
+	cursorNativeReplayCounter += 1;
+	return `cursor-replay-${Date.now()}-${cursorNativeReplayCounter}`;
+}
+
+function getCursorNativeReplayIdFromToolCallId(toolCallId: string): string | undefined {
+	return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
+}
+
+function getPendingCursorNativeReplayId(context: Context): string | undefined {
+	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
+		const message = context.messages[index];
+		if (message.role !== "toolResult") break;
+		const replayId = getCursorNativeReplayIdFromToolCallId(message.toolCallId);
+		if (replayId && pendingCursorNativeRuns.has(replayId)) return replayId;
+	}
+	return undefined;
+}
+
+function splitTextIntoReplayDeltas(text: string): string[] {
+	const deltas: string[] = [];
+	let remaining = text;
+	while (remaining.length > 0) {
+		if (remaining.length <= 96) {
+			deltas.push(remaining);
+			break;
+		}
+		const boundary = Math.max(48, remaining.lastIndexOf(" ", 96));
+		deltas.push(remaining.slice(0, boundary));
+		remaining = remaining.slice(boundary);
+	}
+	return deltas;
+}
+
+async function emitTextDeltas(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+	deltas: string[],
+): Promise<string> {
+	if (deltas.length === 0) return "";
+	const contentIndex = partial.content.length;
+	partial.content.push({ type: "text", text: "" });
+	stream.push({ type: "text_start", contentIndex, partial });
+	const block = partial.content[contentIndex];
+	if (block.type !== "text") return "";
+	for (const delta of deltas) {
+		block.text += delta;
+		stream.push({ type: "text_delta", contentIndex, delta, partial });
+		await Promise.resolve();
+	}
+	stream.push({ type: "text_end", contentIndex, content: block.text, partial });
+	return block.text;
+}
+
+function notifyCursorNativeRun(run: CursorNativeLiveRun): void {
+	for (const waiter of run.waiters) waiter();
+	run.waiters.clear();
+}
+
+function queueCursorNativeEvent(run: CursorNativeLiveRun, event: CursorNativeQueuedEvent): void {
+	run.pendingEvents.push(event);
+	notifyCursorNativeRun(run);
+}
+
+function isCursorNativeRunReady(run: CursorNativeLiveRun): boolean {
+	return run.pendingEvents.length > 0 || run.done || run.cancelled || run.errorMessage !== undefined;
+}
+
+async function waitForCursorNativeRunProgress(run: CursorNativeLiveRun, signal?: AbortSignal): Promise<void> {
+	if (isCursorNativeRunReady(run)) return;
+	await new Promise<void>((resolve, reject) => {
+		let waiter: (() => void) | undefined;
+		const cleanup = (): void => {
+			if (waiter) run.waiters.delete(waiter);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const onAbort = (): void => {
+			cleanup();
+			reject(new CursorAbortError());
+		};
+		waiter = (): void => {
+			cleanup();
+			resolve();
+		};
+		run.waiters.add(waiter);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+async function settleCursorNativeToolBatch(run: CursorNativeLiveRun): Promise<void> {
+	if (run.pendingEvents[0]?.type !== "tool") return;
+	await new Promise((resolve) => setTimeout(resolve, 75));
+}
+
+function closeCursorNativeThinkingBlock(turn: CursorNativeTurnState): void {
+	if (turn.thinkingContentIndex < 0) return;
+	const block = turn.partial.content[turn.thinkingContentIndex];
+	if (block.type === "thinking") {
+		turn.stream.push({
+			type: "thinking_end",
+			contentIndex: turn.thinkingContentIndex,
+			content: block.thinking,
+			partial: turn.partial,
+		});
+	}
+	turn.thinkingContentIndex = -1;
+}
+
+function closeCursorNativeTextBlock(turn: CursorNativeTurnState): string {
+	if (turn.textContentIndex < 0) return "";
+	const block = turn.partial.content[turn.textContentIndex];
+	turn.textContentIndex = -1;
+	if (block.type !== "text") return "";
+	turn.stream.push({
+		type: "text_end",
+		contentIndex: turn.partial.content.indexOf(block),
+		content: block.text,
+		partial: turn.partial,
+	});
+	return block.text;
+}
+
+function closeCursorNativeTurnBlocks(turn: CursorNativeTurnState): string {
+	closeCursorNativeThinkingBlock(turn);
+	return closeCursorNativeTextBlock(turn);
+}
+
+function emitCursorNativeThinkingDelta(turn: CursorNativeTurnState, delta: string): void {
+	closeCursorNativeTextBlock(turn);
+	if (turn.thinkingContentIndex < 0) {
+		turn.thinkingContentIndex = turn.partial.content.length;
+		turn.partial.content.push({ type: "thinking", thinking: "" });
+		turn.stream.push({ type: "thinking_start", contentIndex: turn.thinkingContentIndex, partial: turn.partial });
+	}
+	const block = turn.partial.content[turn.thinkingContentIndex];
+	if (block.type !== "thinking") return;
+	block.thinking += delta;
+	turn.stream.push({ type: "thinking_delta", contentIndex: turn.thinkingContentIndex, delta, partial: turn.partial });
+}
+
+function emitCursorNativeTextDelta(turn: CursorNativeTurnState, delta: string): void {
+	closeCursorNativeThinkingBlock(turn);
+	if (turn.textContentIndex < 0) {
+		turn.textContentIndex = turn.partial.content.length;
+		turn.partial.content.push({ type: "text", text: "" });
+		turn.stream.push({ type: "text_start", contentIndex: turn.textContentIndex, partial: turn.partial });
+	}
+	const block = turn.partial.content[turn.textContentIndex];
+	if (block.type !== "text") return;
+	block.text += delta;
+	turn.stream.push({ type: "text_delta", contentIndex: turn.textContentIndex, delta, partial: turn.partial });
+}
+
+function emitCursorNativeQueuedEvent(
+	turn: CursorNativeTurnState,
+	event: Exclude<CursorNativeQueuedEvent, { type: "tool" }>,
+): void {
+	if (event.type === "thinking-delta") {
+		emitCursorNativeThinkingDelta(turn, event.text);
+	} else if (event.type === "thinking-completed") {
+		closeCursorNativeThinkingBlock(turn);
+	} else if (event.type === "text-delta") {
+		emitCursorNativeTextDelta(turn, event.text);
+	}
+}
+
+function collectCursorNativeToolBatch(run: CursorNativeLiveRun): CursorNativeToolDisplayItem[] {
+	const tools: CursorNativeToolDisplayItem[] = [];
+	while (run.pendingEvents[0]?.type === "tool") {
+		const event = run.pendingEvents.shift();
+		if (event?.type === "tool") tools.push(event.tool);
+	}
+	return tools;
+}
+
+function emitCursorNativeToolUseTurn(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+	run: CursorNativeLiveRun,
+	tools: CursorNativeToolDisplayItem[],
+	outputText: string,
+): void {
+	const shouldTerminate = run.done && !run.finalText?.trim() && run.pendingEvents.length === 0;
+	for (const tool of tools) {
+		const contentIndex = partial.content.length;
+		partial.content.push({
+			type: "toolCall",
+			id: tool.id,
+			name: tool.toolName,
+			arguments: tool.args,
+		});
+		stream.push({ type: "toolcall_start", contentIndex, partial });
+		stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(tool.args), partial });
+		const block = partial.content[contentIndex];
+		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
+		recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate });
+	}
+	setApproximateUsage(partial, run.promptInputTokens, outputText);
+	partial.stopReason = "toolUse";
+	stream.push({ type: "done", reason: "toolUse", message: partial });
+}
+
+async function disposeCursorNativeRun(run: CursorNativeLiveRun): Promise<void> {
+	pendingCursorNativeRuns.delete(run.id);
+	try {
+		await run.agent[Symbol.asyncDispose]();
+	} catch {
+		// disposal failure should not mask the provider result
+	}
+}
+
+async function emitCursorNativeRunNextTurn(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+	run: CursorNativeLiveRun,
+	signal?: AbortSignal,
+): Promise<void> {
+	const turn: CursorNativeTurnState = {
+		stream,
+		partial,
+		thinkingContentIndex: -1,
+		textContentIndex: -1,
+	};
+
+	while (true) {
+		while (run.pendingEvents.length > 0) {
+			const event = run.pendingEvents[0];
+			if (event.type === "tool") {
+				await settleCursorNativeToolBatch(run);
+				const outputText = closeCursorNativeTurnBlocks(turn);
+				const tools = collectCursorNativeToolBatch(run);
+				emitCursorNativeToolUseTurn(stream, partial, run, tools, outputText);
+				return;
+			}
+			run.pendingEvents.shift();
+			emitCursorNativeQueuedEvent(turn, event);
+		}
+
+		if (run.cancelled) {
+			partial.stopReason = "aborted";
+			stream.push({ type: "error", reason: "aborted", error: partial });
+			await disposeCursorNativeRun(run);
+			return;
+		}
+		if (run.errorMessage) {
+			partial.stopReason = "error";
+			partial.errorMessage = run.errorMessage;
+			stream.push({ type: "error", reason: "error", error: partial });
+			await disposeCursorNativeRun(run);
+			return;
+		}
+		if (run.done) {
+			let outputText = closeCursorNativeTurnBlocks(turn);
+			if (!outputText) {
+				outputText += await emitTextDeltas(stream, partial, splitTextIntoReplayDeltas(run.finalText ?? run.textDeltas.join("")));
+			}
+			setApproximateUsage(partial, run.promptInputTokens, outputText);
+			partial.stopReason = "stop";
+			stream.push({ type: "done", reason: "stop", message: partial });
+			await disposeCursorNativeRun(run);
+			return;
+		}
+
+		await waitForCursorNativeRunProgress(run, signal);
+	}
+}
+
+async function replayPendingCursorNativeRun(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+	context: Context,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	const replayId = getPendingCursorNativeReplayId(context);
+	if (!replayId) return false;
+	const run = pendingCursorNativeRuns.get(replayId);
+	if (!run) return false;
+	await emitCursorNativeRunNextTurn(stream, partial, run, signal);
+	return true;
 }
 
 export function streamCursor(
@@ -143,6 +490,7 @@ export function streamCursor(
 	(async () => {
 		const partial = makeInitialMessage(model);
 		let agent: SDKAgent | null = null;
+		let resolvedApiKey: string | undefined;
 		let abortSignal: AbortSignal | undefined;
 		let abortListener: (() => void) | undefined;
 
@@ -154,8 +502,14 @@ export function streamCursor(
 			stream.push({ type: "start", partial });
 			throwIfAborted();
 
-			const apiKey = options?.apiKey;
-			if (isMissingCursorApiKey(apiKey)) throw new Error(MISSING_API_KEY_MESSAGE);
+			if (await replayPendingCursorNativeRun(stream, partial, context, options?.signal)) {
+				stream.end();
+				return;
+			}
+
+			const apiKey = resolveCursorApiKey(options?.apiKey);
+			if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
+			resolvedApiKey = apiKey;
 
 			const cwd = process.cwd();
 			const fastEnabled = getEffectiveFastForModelId(model.id);
@@ -171,15 +525,60 @@ export function streamCursor(
 			throwIfAborted();
 
 			const prompt = buildCursorPrompt(context);
-			let textContentIndex = -1;
+			const promptInputTokens = estimatePromptInputTokens(prompt);
 			let thinkingContentIndex = -1;
+			let activityTraceChars = 0;
+			let activityTraceTruncated = false;
+			let nativeToolDisplayCounter = 0;
+			let textContentIndex = -1;
+			const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+			const nativeReplayId = createCursorNativeReplayId();
 			const textDeltas: string[] = [];
-
-			const appendBufferedTextDelta = (text: string): void => {
-				textDeltas.push(text);
+			let liveStreamClosed = false;
+			const liveRun: CursorNativeLiveRun | undefined = useNativeToolReplay
+				? {
+						id: nativeReplayId,
+						agent,
+						promptInputTokens,
+						pendingEvents: [],
+						textDeltas,
+						done: false,
+						cancelled: false,
+						waiters: new Set(),
+					}
+				: undefined;
+			if (liveRun) pendingCursorNativeRuns.set(liveRun.id, liveRun);
+			const startedToolCalls = new Map<string, unknown>();
+			const completedToolFingerprints = new Set<string>();
+
+			const appendLiveTextDelta = (text: string): void => {
+				if (textContentIndex < 0) {
+					textContentIndex = partial.content.length;
+					partial.content.push({ type: "text", text: "" });
+					stream.push({ type: "text_start", contentIndex: textContentIndex, partial });
+				}
+				const block = partial.content[textContentIndex];
+				if (block.type !== "text") return;
+				block.text += text;
+				stream.push({
+					type: "text_delta",
+					contentIndex: textContentIndex,
+					delta: text,
+					partial,
+				});
 			};
 
 			const appendTraceDelta = (text: string): void => {
+				if (activityTraceTruncated) return;
+
+				let delta = text;
+				if (activityTraceChars + delta.length > CURSOR_ACTIVITY_TRACE_MAX_CHARS) {
+					const remainingChars = Math.max(CURSOR_ACTIVITY_TRACE_MAX_CHARS - activityTraceChars, 0);
+					delta = `${delta.slice(0, remainingChars)}\n[Cursor activity trace truncated]\n`;
+					activityTraceTruncated = true;
+				}
+				if (!delta) return;
+
 				if (thinkingContentIndex < 0) {
 					thinkingContentIndex = partial.content.length;
 					partial.content.push({ type: "thinking", thinking: "" });
@@ -187,84 +586,136 @@ export function streamCursor(
 				}
 				const block = partial.content[thinkingContentIndex];
 				if (block.type === "thinking") {
-					block.thinking += text;
+					block.thinking += delta;
+					activityTraceChars += delta.length;
 					stream.push({
 						type: "thinking_delta",
 						contentIndex: thinkingContentIndex,
-						delta: text,
+						delta,
 						partial,
 					});
 				}
 			};
 
-			const appendCursorToolStatus = (text: string): void => {
+			const appendTraceLine = (text: string): void => {
 				appendTraceDelta(`${text}\n`);
 			};
 
-			const flushBufferedText = (fallbackText?: string): void => {
-				const deltas = textDeltas.length > 0 ? textDeltas : fallbackText ? [fallbackText] : [];
-				if (deltas.length === 0) return;
-				textContentIndex = partial.content.length;
-				partial.content.push({ type: "text", text: "" });
-				stream.push({ type: "text_start", contentIndex: textContentIndex, partial });
-				const block = partial.content[textContentIndex];
-				if (block.type !== "text") return;
-				for (const delta of deltas) {
-					block.text += delta;
+			const appendTraceBlock = (text: string): void => {
+				closeTraceBlock();
+				appendTraceDelta(text.endsWith("\n") ? text : `${text}\n`);
+				closeTraceBlock();
+			};
+
+			const closeTraceBlock = (): void => {
+				if (thinkingContentIndex < 0) return;
+				const block = partial.content[thinkingContentIndex];
+				if (block.type === "thinking") {
 					stream.push({
-						type: "text_delta",
-						contentIndex: textContentIndex,
-						delta,
+						type: "thinking_end",
+						contentIndex: thinkingContentIndex,
+						content: block.thinking,
 						partial,
 					});
 				}
+				thinkingContentIndex = -1;
+			};
+
+			const flushText = (deltas: string[]): string => {
+				for (const delta of deltas) appendLiveTextDelta(delta);
+				if (textContentIndex < 0) return "";
+				const block = partial.content[textContentIndex];
+				if (block.type !== "text") return "";
 				stream.push({
 					type: "text_end",
 					contentIndex: textContentIndex,
 					content: block.text,
 					partial,
 				});
+				return block.text;
+			};
+
+			const getToolFingerprint = (value: unknown): string => {
+				try {
+					return JSON.stringify(value);
+				} catch {
+					return String(value);
+				}
+			};
+
+			const handleCompletedToolCall = (toolCall: unknown): void => {
+				const transcript = scrubSensitiveText(formatCursorToolTranscript(toolCall, { cwd }), resolvedApiKey);
+				const display = buildCursorPiToolDisplay(toolCall, { cwd });
+				const fingerprint = getToolFingerprint({ toolName: display.toolName, args: display.args, result: display.result });
+				if (completedToolFingerprints.has(fingerprint)) return;
+				completedToolFingerprints.add(fingerprint);
+
+				if (useNativeToolReplay && canRenderCursorToolNatively(display.toolName) && liveRun) {
+					const id = `${nativeReplayId}-tool-${++nativeToolDisplayCounter}`;
+					queueCursorNativeEvent(liveRun, {
+						type: "tool",
+						tool: {
+							...display,
+							id,
+							args: scrubDisplayValue(display.args, resolvedApiKey) as Record<string, unknown>,
+							result: scrubDisplayValue(display.result, resolvedApiKey) as typeof display.result,
+						},
+					});
+					return;
+				}
+
+				appendTraceBlock(transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`);
 			};
 
 			const onDelta = (args: { update: InteractionUpdate }): void => {
 				const update = args.update;
 
 				if (update.type === "text-delta") {
-					appendBufferedTextDelta(update.text);
+					textDeltas.push(update.text);
+					if (liveRun && liveStreamClosed) {
+						queueCursorNativeEvent(liveRun, { type: "text-delta", text: update.text });
+					} else if (!useNativeToolReplay) {
+						appendLiveTextDelta(update.text);
+					}
 				} else if (update.type === "thinking-delta") {
-					appendTraceDelta(update.text);
+					if (liveRun && liveStreamClosed) {
+						queueCursorNativeEvent(liveRun, { type: "thinking-delta", text: update.text });
+					} else {
+						appendTraceDelta(update.text);
+					}
 				} else if (update.type === "thinking-completed") {
-					if (thinkingContentIndex >= 0) {
-						const block = partial.content[thinkingContentIndex];
-						if (block.type === "thinking") {
-							stream.push({
-								type: "thinking_end",
-								contentIndex: thinkingContentIndex,
-								content: block.thinking,
-								partial,
-							});
-						}
-						thinkingContentIndex = -1;
+					if (liveRun && liveStreamClosed) {
+						queueCursorNativeEvent(liveRun, { type: "thinking-completed" });
+					} else {
+						closeTraceBlock();
 					}
 				} else if (update.type === "tool-call-started") {
-					appendCursorToolStatus(`Cursor tool started (${getCursorToolName(update.toolCall)}, call ${update.callId})`);
+					startedToolCalls.set(update.callId, update.toolCall);
 				} else if (update.type === "tool-call-completed") {
-					const suffix = summarizeCursorToolResult(getCursorToolResult(update.toolCall));
-					appendCursorToolStatus(`Cursor tool completed (${getCursorToolName(update.toolCall)}, call ${update.callId})${suffix}`);
+					const mergedToolCall = mergeCursorToolCalls(startedToolCalls.get(update.callId), update.toolCall);
+					startedToolCalls.delete(update.callId);
+					handleCompletedToolCall(mergedToolCall);
 				} else if (update.type === "summary") {
-					appendCursorToolStatus(`Cursor summary: ${update.summary}`);
-				} else if (update.type === "turn-ended" && update.usage) {
-					partial.usage.input = update.usage.inputTokens;
-					partial.usage.output = update.usage.outputTokens;
-					partial.usage.cacheRead = update.usage.cacheReadTokens;
-					partial.usage.cacheWrite = update.usage.cacheWriteTokens;
-					partial.usage.totalTokens =
-						update.usage.inputTokens + update.usage.outputTokens + update.usage.cacheReadTokens + update.usage.cacheWriteTokens;
+					const summary = `Cursor summary: ${truncateSingleLine(update.summary)}\n`;
+					if (liveRun && liveStreamClosed) {
+						queueCursorNativeEvent(liveRun, { type: "thinking-delta", text: summary });
+					} else {
+						appendTraceDelta(summary);
+					}
 				}
-				// partial-tool-call, summary-started, summary-completed,
+				// Cursor turn-ended usage is intentionally not copied into pi usage: the SDK reports
+				// cumulative internal agent/tool/cache tokens, not the replayable pi prompt context.
+				// partial-tool-call, summary-started, summary-completed, turn-ended,
 				// shell-output-delta, token-delta, step-* are intentionally not surfaced.
 			};
 
+			const onStep = (args: { step: unknown }): void => {
+				const step = getObjectField(args.step, "message") ? args.step : undefined;
+				if (getObjectField(args.step, "type") !== "toolCall") return;
+				const toolCall = getObjectField(step, "message");
+				if (toolCall) handleCompletedToolCall(toolCall);
+			};
+
 			// Handle abort signal
 			let run: Awaited<ReturnType<SDKAgent["send"]>> | null = null;
 			abortListener = () => {
@@ -278,37 +729,50 @@ export function streamCursor(
 			throwIfAborted();
 			run = await agent.send(
 				{ text: prompt.text, images: prompt.images.length > 0 ? prompt.images : undefined },
-				{ onDelta },
+				{ onDelta, onStep },
 			);
 			if (options?.signal?.aborted) {
 				await run.cancel().catch(() => {});
 				throw new CursorAbortError();
 			}
 
-			const result = await run.wait();
-			await cacheSdkContextWindow(agent.agentId, model.id);
-
-			// Close open thinking/trace before flushing final assistant text so saved
-			// message content is trace first, final answer second.
-			if (thinkingContentIndex >= 0) {
-				const block = partial.content[thinkingContentIndex];
-				if (block.type === "thinking") {
-					stream.push({
-						type: "thinking_end",
-						contentIndex: thinkingContentIndex,
-						content: block.thinking,
-						partial,
+			if (useNativeToolReplay && liveRun) {
+				void run
+					.wait()
+					.then(async (result) => {
+						await cacheSdkContextWindow(liveRun.agent.agentId, model.id);
+						liveRun.cancelled = result.status === "cancelled";
+						liveRun.finalText = hasUsableText(result.result) ? result.result : liveRun.textDeltas.join("");
+						liveRun.done = true;
+						notifyCursorNativeRun(liveRun);
+					})
+					.catch((error: unknown) => {
+						liveRun.errorMessage = sanitizeError(error, resolvedApiKey ?? options?.apiKey);
+						notifyCursorNativeRun(liveRun);
 					});
-				}
-				thinkingContentIndex = -1;
+
+				await waitForCursorNativeRunProgress(liveRun, options?.signal);
+				await settleCursorNativeToolBatch(liveRun);
+				closeTraceBlock();
+				liveStreamClosed = true;
+				await emitCursorNativeRunNextTurn(stream, partial, liveRun, options?.signal);
+				agent = null;
+				return;
 			}
 
-			flushBufferedText(result.result);
+			const result = await run.wait();
+			await cacheSdkContextWindow(agent.agentId, model.id);
+
+			// Close any open thinking/activity trace, then use the final run result only when
+			// Cursor did not stream text deltas.
+			closeTraceBlock();
 
 			if (result.status === "cancelled") {
 				partial.stopReason = "aborted";
 				stream.push({ type: "error", reason: "aborted", error: partial });
 			} else {
+				const finalText = flushText(textDeltas.length === 0 && hasUsableText(result.result) ? [result.result] : []);
+				setApproximateUsage(partial, promptInputTokens, finalText);
 				stream.push({ type: "done", reason: "stop", message: partial });
 			}
 		} catch (error) {
@@ -317,7 +781,7 @@ export function streamCursor(
 				stream.push({ type: "error", reason: "aborted", error: partial });
 			} else {
 				partial.stopReason = "error";
-				partial.errorMessage = sanitizeError(error, options?.apiKey);
+				partial.errorMessage = sanitizeError(error, resolvedApiKey ?? options?.apiKey);
 				stream.push({ type: "error", reason: "error", error: partial });
 			}
 		} finally {