pi-cursor-sdk 0.1.17 → 0.1.19

package/src/cursor-provider-turn-coordinator.ts

@@ -2,24 +2,32 @@ import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-wo
 import type { InteractionUpdate } from "@cursor/sdk";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
-import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { resolveNativeReplayDisposition } from "./cursor-native-replay-routing.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { asRecord, getField, hasUsableText } from "./cursor-record-utils.js";
 import { scrubPiToolDisplay, scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { buildCursorPiToolDisplay, formatCursorToolTranscript, getCursorCreatePlanText, mergeCursorToolCalls } from "./cursor-tool-transcript.js";
-import { getString, getToolArgs, getToolName } from "./cursor-transcript-utils.js";
-
-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;
-}
+import {
+	recordDiscardedIncompleteStartedToolCall,
+	type CursorSdkEventDebugRecorder,
+	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+} from "./cursor-sdk-event-debug.js";
+import {
+	buildIncompleteCursorToolDisplay,
+	formatIncompleteCursorToolTrace,
+	type IncompleteCursorToolDiscardReason,
+} from "./cursor-incomplete-tool-visibility.js";
+import { getToolName, normalizeToolName } from "./cursor-transcript-utils.js";
+import {
+	CURSOR_TOOL_LIFECYCLE_DEFER_MS,
+	formatCursorToolLifecycleProgressText,
+	isCursorToolLifecycleEligible,
+} from "./cursor-tool-lifecycle.js";
 
 function formatCursorToolName(toolCall: unknown): string {
-	return truncateSingleLine(getToolName(toolCall), 80) || "unknown";
+	return truncateCursorDisplayLine(getToolName(toolCall), 80) || "unknown";
 }
 
 interface CursorShellOutputDelta {
@@ -37,17 +45,6 @@ function isCursorShellToolCall(toolCall: unknown): boolean {
 	return normalizedName === "shell" || normalizedName === "run_terminal_cmd" || normalizedName === "terminal" || normalizedName === "bash";
 }
 
-function isCursorTaskToolCall(toolCall: unknown): boolean {
-	return getToolName(toolCall).replace(/\s+/g, " ").trim().toLowerCase() === "task";
-}
-
-function extractCursorTaskProgressLabel(toolCall: unknown, apiKey?: string): string | undefined {
-	if (!isCursorTaskToolCall(toolCall)) return undefined;
-	const description = getString(getToolArgs(toolCall), "description");
-	if (!description?.trim()) return undefined;
-	return truncateSingleLine(scrubSensitiveText(description, apiKey));
-}
-
 function getCursorShellOutputDelta(update: InteractionUpdate): CursorShellOutputDelta | undefined {
 	if (update.type !== "shell-output-delta") return undefined;
 	const event = getField(update, "event");
@@ -90,13 +87,15 @@ function mergeShellOutputDeltasIntoCursorToolCall(toolCall: unknown, deltas: Cur
 	};
 }
 
+type CursorToolDisplaySource = "started" | "fallback" | "transcript";
+
 type ToolCompletionResolution =
 	| { action: "ignore-bridge"; identity?: string }
 	| {
 			action: "handle";
 			toolCall: unknown;
 			identity?: string;
-			source?: "started" | "fallback";
+			source?: CursorToolDisplaySource;
 			matchedStartedCallId?: string;
 	  };
 
@@ -107,8 +106,10 @@ export interface CursorSdkTurnCoordinatorOptions {
 	resolvedApiKey?: string;
 	liveRun?: CursorLiveRun;
 	useNativeToolReplay: boolean;
+	activeToolNames?: ReadonlySet<string>;
 	nativeReplayId: string;
 	textDeltas: string[];
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export class CursorSdkTurnCoordinator {
@@ -118,10 +119,12 @@ export class CursorSdkTurnCoordinator {
 	readonly resolvedApiKey?: string;
 	readonly liveRun?: CursorLiveRun;
 	readonly useNativeToolReplay: boolean;
+	readonly activeToolNames?: ReadonlySet<string>;
 	readonly nativeReplayId: string;
 	readonly textDeltas: string[];
 
 	private readonly contentEmitter: CursorPartialContentEmitter;
+	private readonly debugRecorder?: CursorSdkEventDebugRecorder;
 	private nativeToolDisplayCounter = 0;
 	private nativeToolReplayStarted = false;
 	private cursorPlanTextCandidate: string | undefined;
@@ -133,7 +136,8 @@ export class CursorSdkTurnCoordinator {
 	private readonly completedToolIdentities = new Set<string>();
 	private readonly completedStartedToolFingerprints = new Set<string>();
 	private readonly completedFallbackToolFingerprints = new Set<string>();
-	private readonly emittedTaskProgressCallIds = new Set<string>();
+	private readonly emittedLifecycleCallIds = new Set<string>();
+	private readonly lifecycleTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
 	constructor(options: CursorSdkTurnCoordinatorOptions) {
 		this.stream = options.stream;
@@ -142,8 +146,10 @@ export class CursorSdkTurnCoordinator {
 		this.resolvedApiKey = options.resolvedApiKey;
 		this.liveRun = options.liveRun;
 		this.useNativeToolReplay = options.useNativeToolReplay;
+		this.activeToolNames = options.activeToolNames;
 		this.nativeReplayId = options.nativeReplayId;
 		this.textDeltas = options.textDeltas;
+		this.debugRecorder = options.debugRecorder;
 		this.contentEmitter = new CursorPartialContentEmitter(options.stream, options.partial, undefined, false);
 	}
 
@@ -155,13 +161,26 @@ export class CursorSdkTurnCoordinator {
 		return this.nativeToolReplayStarted;
 	}
 
-	discardIncompleteStartedToolCalls(): void {
+	discardIncompleteStartedToolCalls(
+		reason: IncompleteCursorToolDiscardReason = DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+	): void {
+		for (const [callId, toolCall] of this.startedToolCalls) {
+			if (typeof callId !== "string") continue;
+			recordDiscardedIncompleteStartedToolCall(this.debugRecorder, process.env, {
+				toolName: normalizeToolName(getToolName(toolCall)),
+				callId,
+				reason,
+			});
+			this.emitIncompleteStartedToolCall(toolCall, reason);
+		}
 		this.startedToolCalls.clear();
 		this.bridgeStartedToolCallIds.clear();
 		this.activeShellCallIds.clear();
 		this.ambiguousShellOutputCallIds.clear();
 		this.shellOutputDeltasByCallId.clear();
-		this.emittedTaskProgressCallIds.clear();
+		this.emittedLifecycleCallIds.clear();
+		for (const timer of this.lifecycleTimers.values()) clearTimeout(timer);
+		this.lifecycleTimers.clear();
 	}
 
 	closeTraceBlock(): void {
@@ -199,14 +218,14 @@ export class CursorSdkTurnCoordinator {
 			return;
 		}
 		if (update.type === "partial-tool-call") {
-			this.maybeEmitCursorTaskProgress(update.callId, update.toolCall);
+			this.maybeScheduleCursorToolLifecycle(update.callId, update.toolCall);
 			return;
 		}
 		if (update.type === "tool-call-started") {
 			if (this.liveRun?.bridgeRun?.isBridgeMcpToolCall(update.toolCall)) {
 				if (typeof update.callId === "string") this.bridgeStartedToolCallIds.add(update.callId);
 			} else {
-				this.maybeEmitCursorTaskProgress(update.callId, update.toolCall);
+				this.maybeScheduleCursorToolLifecycle(update.callId, update.toolCall);
 				this.startedToolCalls.set(update.callId, update.toolCall);
 				if (isCursorShellToolCall(update.toolCall)) this.activeShellCallIds.add(update.callId);
 			}
@@ -219,7 +238,10 @@ export class CursorSdkTurnCoordinator {
 				toolCall: update.toolCall,
 				startedToolCall: this.startedToolCalls.get(update.callId),
 			});
-			if (resolution.action === "ignore-bridge") return;
+			if (resolution.action === "ignore-bridge") {
+				this.recordIgnoreBridgeDecision(resolution.identity, getToolName(update.toolCall), "delta");
+				return;
+			}
 			this.handleCompletedToolCall(resolution.toolCall, {
 				identity: resolution.identity,
 				source: resolution.source,
@@ -232,7 +254,7 @@ export class CursorSdkTurnCoordinator {
 			return;
 		}
 		if (update.type === "summary") {
-			const summary = `Cursor summary: ${truncateSingleLine(update.summary)}\n`;
+			const summary = `Cursor summary: ${truncateCursorDisplayLine(update.summary)}\n`;
 			if (this.liveRun) {
 				cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: summary });
 			} else {
@@ -255,7 +277,10 @@ export class CursorSdkTurnCoordinator {
 			callId: stepId,
 			toolCall,
 		});
-		if (resolution.action === "ignore-bridge") return;
+		if (resolution.action === "ignore-bridge") {
+			this.recordIgnoreBridgeDecision(resolution.identity, getToolName(toolCall), "step");
+			return;
+		}
 		this.handleCompletedToolCall(resolution.toolCall, {
 			identity: resolution.identity,
 			source: resolution.source,
@@ -323,20 +348,52 @@ export class CursorSdkTurnCoordinator {
 		};
 	}
 
+	handleTranscriptCompletedToolCalls(toolCalls: readonly { identity: string; toolCall: unknown }[]): void {
+		for (const { identity, toolCall } of toolCalls) {
+			this.handleCompletedToolCall(toolCall, { identity, source: "transcript" });
+		}
+	}
+
 	private handleCompletedToolCall(
 		toolCall: unknown,
-		options: { identity?: string; source?: "started" | "fallback" } = {},
+		options: { identity?: string; source?: CursorToolDisplaySource } = {},
 	): void {
 		const planText = getCursorCreatePlanText(toolCall);
 		if (planText) this.cursorPlanTextCandidate = scrubSensitiveText(planText, this.resolvedApiKey);
 
 		const transcript = scrubSensitiveText(formatCursorToolTranscript(toolCall, { cwd: this.cwd }), this.resolvedApiKey);
 		const display = buildCursorPiToolDisplay(toolCall, { cwd: this.cwd });
+		const toolName = display.toolName;
 		const fingerprint = this.getToolFingerprint({ toolName: display.toolName, args: display.args, result: display.result });
-		if (options.identity && this.completedToolIdentities.has(options.identity)) return;
+		if (options.identity && this.completedToolIdentities.has(options.identity)) {
+			this.recordDisplayDecision({
+				action: "skip-duplicate",
+				toolName,
+				identity: options.identity,
+				source: options.source,
+				reason: "identity-already-completed",
+			});
+			return;
+		}
 		if (options.source === "started") {
-			if (this.completedFallbackToolFingerprints.has(fingerprint)) return;
+			if (this.completedFallbackToolFingerprints.has(fingerprint)) {
+				this.recordDisplayDecision({
+					action: "skip-duplicate",
+					toolName,
+					identity: options.identity,
+					source: options.source,
+					reason: "fallback-fingerprint-already-completed",
+				});
+				return;
+			}
 		} else if (this.completedStartedToolFingerprints.has(fingerprint) || this.completedFallbackToolFingerprints.has(fingerprint)) {
+			this.recordDisplayDecision({
+				action: "skip-duplicate",
+				toolName,
+				identity: options.identity,
+				source: options.source,
+				reason: "fingerprint-already-completed",
+			});
 			return;
 		}
 		if (options.identity) this.completedToolIdentities.add(options.identity);
@@ -346,13 +403,26 @@ export class CursorSdkTurnCoordinator {
 			this.completedFallbackToolFingerprints.add(fingerprint);
 		}
 
-		const nativeRenderable = canRenderCursorToolNatively(display.toolName);
-		const route = this.useNativeToolReplay && nativeRenderable && this.liveRun ? "native_replay" : "trace";
+		const disposition = resolveNativeReplayDisposition({
+			toolName: display.toolName,
+			useNativeToolReplay: this.useNativeToolReplay,
+			activeToolNames: this.activeToolNames,
+			hasLiveRun: this.liveRun !== undefined,
+		});
 
-		if (route === "native_replay" && this.liveRun) {
+		if (disposition === "queue_replay" && this.liveRun) {
 			this.nativeToolReplayStarted = true;
 			const id = `${this.nativeReplayId}-tool-${++this.nativeToolDisplayCounter}`;
 			const scrubbedDisplay = scrubPiToolDisplay(display, this.resolvedApiKey);
+			this.recordDisplayDecision({
+				action: "queue_replay",
+				disposition,
+				toolName,
+				identity: options.identity,
+				source: options.source,
+				transcript,
+				replayToolId: id,
+			});
 			cursorLiveRuns.queueEvent(this.liveRun, {
 				type: "tool",
 				tool: { ...scrubbedDisplay, id },
@@ -360,7 +430,84 @@ export class CursorSdkTurnCoordinator {
 			return;
 		}
 
-		this.emitCursorToolTrace(transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`);
+		const traceText =
+			disposition === "inactive_trace"
+				? formatInactiveCursorReplayTrace(scrubPiToolDisplay(display, this.resolvedApiKey))
+				: transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`;
+		this.recordDisplayDecision({
+			action: "emit_trace",
+			disposition,
+			toolName,
+			identity: options.identity,
+			source: options.source,
+			transcript,
+			traceText,
+		});
+		this.emitCursorToolTrace(traceText);
+	}
+
+	private emitIncompleteStartedToolCall(toolCall: unknown, reason: IncompleteCursorToolDiscardReason): void {
+		const display = scrubPiToolDisplay(
+			buildIncompleteCursorToolDisplay(toolCall, reason, { apiKey: this.resolvedApiKey }),
+			this.resolvedApiKey,
+		);
+		const toolName = display.toolName;
+		const disposition = resolveNativeReplayDisposition({
+			toolName,
+			useNativeToolReplay: this.useNativeToolReplay,
+			activeToolNames: this.activeToolNames,
+			hasLiveRun: this.liveRun !== undefined,
+		});
+
+		// Aborted live runs emit trace visibility only; do not synthesize a toolUse replay turn.
+		if (disposition === "queue_replay" && this.liveRun && reason !== "abort") {
+			this.nativeToolReplayStarted = true;
+			const id = `${this.nativeReplayId}-tool-${++this.nativeToolDisplayCounter}`;
+			this.recordDisplayDecision({
+				action: "queue_replay",
+				disposition,
+				toolName,
+				source: "started",
+				reason: "incomplete-started-tool-call",
+				replayToolId: id,
+			});
+			cursorLiveRuns.queueEvent(this.liveRun, {
+				type: "tool",
+				tool: { ...display, id },
+			});
+			return;
+		}
+
+		const traceText =
+			disposition === "inactive_trace"
+				? formatInactiveCursorReplayTrace(display)
+				: formatIncompleteCursorToolTrace(display);
+		this.recordDisplayDecision({
+			action: "emit_trace",
+			disposition,
+			toolName,
+			source: "started",
+			reason: "incomplete-started-tool-call",
+			traceText,
+		});
+		this.emitCursorToolTrace(traceText);
+	}
+
+	private recordIgnoreBridgeDecision(
+		identity: string | undefined,
+		toolName: string,
+		source: "delta" | "step",
+	): void {
+		this.debugRecorder?.recordDisplayDecision({
+			action: "ignore-bridge",
+			toolName,
+			identity,
+			source,
+		});
+	}
+
+	private recordDisplayDecision(decision: Parameters<CursorSdkEventDebugRecorder["recordDisplayDecision"]>[0]): void {
+		this.debugRecorder?.recordDisplayDecision(decision);
 	}
 
 	private emitCursorToolTrace(text: string): void {
@@ -373,17 +520,39 @@ export class CursorSdkTurnCoordinator {
 		this.contentEmitter.appendThinkingBlock(traceText);
 	}
 
-	private maybeEmitCursorTaskProgress(callId: unknown, toolCall: unknown): void {
-		if (typeof callId !== "string" || this.emittedTaskProgressCallIds.has(callId)) return;
+	private maybeScheduleCursorToolLifecycle(callId: unknown, toolCall: unknown): void {
+		if (typeof callId !== "string" || this.emittedLifecycleCallIds.has(callId)) return;
 		if (this.liveRun?.bridgeRun?.isBridgeMcpToolCall(toolCall)) return;
-		const label = extractCursorTaskProgressLabel(toolCall, this.resolvedApiKey);
-		if (!label) return;
-		this.emittedTaskProgressCallIds.add(callId);
-		this.emitCursorTaskProgress(label);
+		if (!isCursorToolLifecycleEligible(toolCall)) return;
+
+		this.cancelCursorToolLifecycleTimer(callId);
+		const timer = setTimeout(() => {
+			this.lifecycleTimers.delete(callId);
+			if (!this.startedToolCalls.has(callId)) return;
+			if (this.emittedLifecycleCallIds.has(callId)) return;
+			this.emitCursorToolLifecycle(callId, toolCall);
+		}, CURSOR_TOOL_LIFECYCLE_DEFER_MS);
+		timer.unref?.();
+		this.lifecycleTimers.set(callId, timer);
 	}
 
-	private emitCursorTaskProgress(label: string): void {
-		const progressText = `Cursor task: ${label}\n`;
+	private cancelCursorToolLifecycleTimer(callId: string): void {
+		const timer = this.lifecycleTimers.get(callId);
+		if (!timer) return;
+		clearTimeout(timer);
+		this.lifecycleTimers.delete(callId);
+	}
+
+	private emitCursorToolLifecycle(callId: string, toolCall: unknown): void {
+		const progressText = formatCursorToolLifecycleProgressText(toolCall, this.resolvedApiKey);
+		if (!progressText) return;
+		this.emittedLifecycleCallIds.add(callId);
+		this.debugRecorder?.recordCoordinatorEvent("tool_lifecycle", {
+			callId,
+			toolName: normalizeToolName(getToolName(toolCall)),
+			progressText,
+			liveRun: this.liveRun !== undefined,
+		});
 		if (this.liveRun) {
 			cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: progressText });
 			return;
@@ -404,6 +573,7 @@ export class CursorSdkTurnCoordinator {
 	}
 
 	private clearStartedToolCall(callId: string): void {
+		this.cancelCursorToolLifecycleTimer(callId);
 		this.startedToolCalls.delete(callId);
 		this.bridgeStartedToolCallIds.delete(callId);
 		this.activeShellCallIds.delete(callId);