pi-cursor-sdk 0.1.18 → 0.1.20

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

@@ -9,7 +9,26 @@ 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";
+import {
+	recordDiscardedIncompleteStartedToolCall,
+	type CursorSdkEventDebugRecorder,
+	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+} from "./cursor-sdk-event-debug.js";
+import {
+	buildIncompleteCursorToolDisplay,
+	buildIncompleteCursorToolRunOutcome,
+	formatIncompleteCursorToolTrace,
+	resolveIncompleteCursorToolVisibility,
+	type IncompleteCursorToolRunOutcome,
+	type IncompleteCursorToolDiscardReason,
+} from "./cursor-incomplete-tool-visibility.js";
+import { getToolName } from "./cursor-transcript-utils.js";
+import {
+	CURSOR_TOOL_LIFECYCLE_DEFER_MS,
+	formatCursorToolLifecycleProgressText,
+	isCursorToolLifecycleEligible,
+} from "./cursor-tool-lifecycle.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
 
 function formatCursorToolName(toolCall: unknown): string {
 	return truncateCursorDisplayLine(getToolName(toolCall), 80) || "unknown";
@@ -25,20 +44,12 @@ interface CursorShellOutputDeltas {
 	stderr: string[];
 }
 
-function isCursorShellToolCall(toolCall: unknown): boolean {
-	const normalizedName = getToolName(toolCall).replace(/\s+/g, " ").trim().toLowerCase();
-	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 getNormalizedCursorToolName(toolCall: unknown): string {
+	return classifyCursorToolVisibility(toolCall).normalizedName;
 }
 
-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 truncateCursorDisplayLine(scrubSensitiveText(description, apiKey));
+function isCursorShellToolCall(toolCall: unknown): boolean {
+	return classifyCursorToolVisibility(toolCall).normalizedKey === "shell";
 }
 
 function getCursorShellOutputDelta(update: InteractionUpdate): CursorShellOutputDelta | undefined {
@@ -83,13 +94,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;
 	  };
 
@@ -103,6 +116,7 @@ export interface CursorSdkTurnCoordinatorOptions {
 	activeToolNames?: ReadonlySet<string>;
 	nativeReplayId: string;
 	textDeltas: string[];
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export class CursorSdkTurnCoordinator {
@@ -117,6 +131,7 @@ export class CursorSdkTurnCoordinator {
 	readonly textDeltas: string[];
 
 	private readonly contentEmitter: CursorPartialContentEmitter;
+	private readonly debugRecorder?: CursorSdkEventDebugRecorder;
 	private nativeToolDisplayCounter = 0;
 	private nativeToolReplayStarted = false;
 	private cursorPlanTextCandidate: string | undefined;
@@ -128,7 +143,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;
@@ -140,6 +156,7 @@ export class CursorSdkTurnCoordinator {
 		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);
 	}
 
@@ -151,13 +168,40 @@ export class CursorSdkTurnCoordinator {
 		return this.nativeToolReplayStarted;
 	}
 
-	discardIncompleteStartedToolCalls(): void {
+	discardIncompleteStartedToolCalls(
+		outcome: IncompleteCursorToolRunOutcome = buildIncompleteCursorToolRunOutcome(),
+	): void {
+		for (const [callId, toolCall] of this.startedToolCalls) {
+			if (typeof callId !== "string") continue;
+			const toolName = getNormalizedCursorToolName(toolCall);
+			recordDiscardedIncompleteStartedToolCall(this.debugRecorder, process.env, {
+				toolName,
+				callId,
+				reason: outcome.reason,
+			});
+			const visibilityDecision = resolveIncompleteCursorToolVisibility(toolCall, outcome);
+			if (visibilityDecision !== "emit") {
+				this.recordDisplayDecision({
+					action: "skip-incomplete-fast-local",
+					toolName,
+					source: "started",
+					reason:
+						visibilityDecision === "debugOnly" && outcome.assistantTextProduced
+							? "successful-run-text-produced"
+							: visibilityDecision,
+				});
+				continue;
+			}
+			this.emitIncompleteStartedToolCall(toolCall, outcome.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 {
@@ -195,14 +239,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);
 			}
@@ -215,7 +259,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,
@@ -251,7 +298,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,
@@ -319,20 +369,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);
@@ -353,6 +435,15 @@ export class CursorSdkTurnCoordinator {
 			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 },
@@ -362,11 +453,84 @@ export class CursorSdkTurnCoordinator {
 
 		const traceText =
 			disposition === "inactive_trace"
-				? formatInactiveCursorReplayTrace(display)
+				? 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 {
 		const traceText = text.endsWith("\n") ? text : `${text}\n`;
 		if (this.liveRun) {
@@ -377,17 +541,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: getNormalizedCursorToolName(toolCall),
+			progressText,
+			liveRun: this.liveRun !== undefined,
+		});
 		if (this.liveRun) {
 			cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: progressText });
 			return;
@@ -408,6 +594,7 @@ export class CursorSdkTurnCoordinator {
 	}
 
 	private clearStartedToolCall(callId: string): void {
+		this.cancelCursorToolLifecycleTimer(callId);
 		this.startedToolCalls.delete(callId);
 		this.bridgeStartedToolCallIds.delete(callId);
 		this.activeShellCallIds.delete(callId);