pi-cursor-sdk 0.1.19 → 0.1.21

package/src/cursor-provider-turn-display-router.ts

@@ -0,0 +1,216 @@
+import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { resolveNativeReplayDisposition, type NativeReplayDisposition } from "./cursor-native-replay-routing.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
+import {
+	buildIncompleteCursorToolDisplay,
+	formatIncompleteCursorToolTrace,
+	type IncompleteCursorToolDiscardReason,
+} from "./cursor-incomplete-tool-visibility.js";
+import { scrubPiToolDisplay, scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { buildCursorPiToolDisplay, formatCursorToolTranscript, getCursorCreatePlanText } from "./cursor-tool-transcript.js";
+import { getToolName } from "./cursor-transcript-utils.js";
+import type { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
+import type { CursorToolDisplaySource } from "./cursor-provider-turn-tool-ledger.js";
+
+function formatCursorToolName(toolCall: unknown): string {
+	return truncateCursorDisplayLine(getToolName(toolCall), 80) || "unknown";
+}
+
+export interface CursorTurnDisplayRouterOptions {
+	cwd: string;
+	resolvedApiKey?: string;
+	liveRun?: CursorLiveRun;
+	useNativeToolReplay: boolean;
+	activeToolNames?: ReadonlySet<string>;
+	nativeReplayId: string;
+	contentEmitter: CursorPartialContentEmitter;
+	debugRecorder?: CursorSdkEventDebugRecorder;
+}
+
+export type CursorTurnDisplayAction =
+	| { kind: "queue_replay"; tool: ReturnType<typeof scrubPiToolDisplay>; replayToolId: string; disposition: NativeReplayDisposition }
+	| { kind: "emit_trace"; traceText: string; disposition: NativeReplayDisposition };
+
+export class CursorTurnDisplayRouter {
+	private readonly cwd: string;
+	private readonly resolvedApiKey?: string;
+	private readonly liveRun?: CursorLiveRun;
+	private readonly useNativeToolReplay: boolean;
+	private readonly activeToolNames?: ReadonlySet<string>;
+	private readonly nativeReplayId: string;
+	private readonly contentEmitter: CursorPartialContentEmitter;
+	private readonly debugRecorder?: CursorSdkEventDebugRecorder;
+	private nativeToolDisplayCounter = 0;
+	nativeToolReplayStarted = false;
+	planTextCandidate: string | undefined;
+
+	constructor(options: CursorTurnDisplayRouterOptions) {
+		this.cwd = options.cwd;
+		this.resolvedApiKey = options.resolvedApiKey;
+		this.liveRun = options.liveRun;
+		this.useNativeToolReplay = options.useNativeToolReplay;
+		this.activeToolNames = options.activeToolNames;
+		this.nativeReplayId = options.nativeReplayId;
+		this.contentEmitter = options.contentEmitter;
+		this.debugRecorder = options.debugRecorder;
+	}
+
+	routeCompletedToolCall(
+		toolCall: unknown,
+		options: { identity?: string; source?: CursorToolDisplaySource } = {},
+	): CursorTurnDisplayAction | undefined {
+		const planText = getCursorCreatePlanText(toolCall);
+		if (planText) this.planTextCandidate = scrubSensitiveText(planText, this.resolvedApiKey);
+
+		const transcript = scrubSensitiveText(formatCursorToolTranscript(toolCall, { cwd: this.cwd }), this.resolvedApiKey);
+		const display = buildCursorPiToolDisplay(toolCall, { cwd: this.cwd });
+		const disposition = resolveNativeReplayDisposition({
+			toolName: display.toolName,
+			useNativeToolReplay: this.useNativeToolReplay,
+			activeToolNames: this.activeToolNames,
+			hasLiveRun: this.liveRun !== undefined,
+		});
+
+		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: display.toolName,
+				identity: options.identity,
+				source: options.source,
+				transcript,
+				replayToolId: id,
+			});
+			return { kind: "queue_replay", tool: scrubbedDisplay, replayToolId: id, disposition };
+		}
+
+		const traceText =
+			disposition === "inactive_trace"
+				? formatInactiveCursorReplayTrace(scrubPiToolDisplay(display, this.resolvedApiKey))
+				: transcript || `Cursor tool: ${formatCursorToolName(toolCall)} completed`;
+		this.recordDisplayDecision({
+			action: "emit_trace",
+			disposition,
+			toolName: display.toolName,
+			identity: options.identity,
+			source: options.source,
+			transcript,
+			traceText,
+		});
+		return { kind: "emit_trace", traceText, disposition };
+	}
+
+	routeIncompleteStartedToolCall(
+		toolCall: unknown,
+		reason: IncompleteCursorToolDiscardReason,
+	): CursorTurnDisplayAction | undefined {
+		const display = scrubPiToolDisplay(
+			buildIncompleteCursorToolDisplay(toolCall, reason, { apiKey: this.resolvedApiKey }),
+			this.resolvedApiKey,
+		);
+		const disposition = resolveNativeReplayDisposition({
+			toolName: display.toolName,
+			useNativeToolReplay: this.useNativeToolReplay,
+			activeToolNames: this.activeToolNames,
+			hasLiveRun: this.liveRun !== undefined,
+		});
+
+		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: display.toolName,
+				source: "started",
+				reason: "incomplete-started-tool-call",
+				replayToolId: id,
+			});
+			return { kind: "queue_replay", tool: display, replayToolId: id, disposition };
+		}
+
+		const traceText =
+			disposition === "inactive_trace"
+				? formatInactiveCursorReplayTrace(display)
+				: formatIncompleteCursorToolTrace(display);
+		this.recordDisplayDecision({
+			action: "emit_trace",
+			disposition,
+			toolName: display.toolName,
+			source: "started",
+			reason: "incomplete-started-tool-call",
+			traceText,
+		});
+		return { kind: "emit_trace", traceText, disposition };
+	}
+
+	emitDisplayAction(action: CursorTurnDisplayAction): void {
+		if (action.kind === "queue_replay") {
+			if (!this.liveRun) return;
+			cursorLiveRuns.queueEvent(this.liveRun, {
+				type: "tool",
+				tool: { ...action.tool, id: action.replayToolId },
+			});
+			return;
+		}
+		this.emitCursorToolTrace(action.traceText);
+	}
+
+	recordIgnoreBridgeDecision(
+		identity: string | undefined,
+		toolName: string,
+		source: "delta" | "step",
+	): void {
+		this.debugRecorder?.recordDisplayDecision({
+			action: "ignore-bridge",
+			toolName,
+			identity,
+			source,
+		});
+	}
+
+	recordDuplicateSkip(
+		toolName: string,
+		options: { identity?: string; source?: CursorToolDisplaySource; reason: string },
+	): void {
+		this.recordDisplayDecision({
+			action: "skip-duplicate",
+			toolName,
+			identity: options.identity,
+			source: options.source,
+			reason: options.reason,
+		});
+	}
+
+	recordIncompleteSkip(
+		toolName: string,
+		reason: string,
+	): void {
+		this.recordDisplayDecision({
+			action: "skip-incomplete-fast-local",
+			toolName,
+			source: "started",
+			reason,
+		});
+	}
+
+	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) {
+			cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: traceText });
+			cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-completed" });
+			return;
+		}
+		this.contentEmitter.appendThinkingBlock(traceText);
+	}
+}

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

@@ -0,0 +1,59 @@
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import {
+	drainCursorLiveRunTurn,
+	flushPendingCursorLiveRunTraceEventsToStream,
+	settleCursorLiveToolBatch,
+} from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import {
+	buildIncompleteCursorToolRunOutcome,
+	type IncompleteCursorToolRunOutcomeInput,
+} from "./cursor-incomplete-tool-visibility.js";
+import type {
+	CursorProviderTurnPrepareResult,
+	CursorProviderTurnRunnerParams,
+} from "./cursor-provider-turn-types.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+
+export interface EmitCursorLiveTurnParams {
+	params: CursorProviderTurnRunnerParams;
+	prepared: CursorProviderTurnPrepareResult;
+	sdkEventDebug: CursorSdkEventDebugSink | undefined;
+	discardIncompleteTools: (outcome: IncompleteCursorToolRunOutcomeInput) => void;
+}
+
+export async function emitCursorLiveTurn(emitParams: EmitCursorLiveTurnParams): Promise<void> {
+	const { params, prepared, sdkEventDebug, discardIncompleteTools } = emitParams;
+	if (prepared.runtime.kind !== "live") throw new Error("emitCursorLiveTurn requires a live run");
+	const { liveRun, turnCoordinator } = prepared.runtime;
+
+	const { options, model } = params;
+	try {
+		await cursorLiveRuns.withRunLease(liveRun, options?.signal, async () => {
+			await cursorLiveRuns.waitForProgress(liveRun, options?.signal);
+			await settleCursorLiveToolBatch(liveRun);
+			turnCoordinator.closeTraceBlock();
+			await drainCursorLiveRunTurn(params.stream, params.partial, model, params.context, liveRun, 0, {
+				mode: "emit",
+				signal: options?.signal,
+				debugRecorder: sdkEventDebug,
+			});
+		});
+	} catch (caught) {
+		if (caught instanceof CursorLiveRunAbortError) {
+			discardIncompleteTools({ status: "cancelled", signalAborted: true });
+			turnCoordinator.closeTraceBlock();
+			flushPendingCursorLiveRunTraceEventsToStream(params.stream, params.partial, liveRun, {
+				includeTracesBehindQueuedTools: true,
+			});
+		}
+		throw caught;
+	}
+}
+
+export function discardIncompleteToolsFromPrepared(
+	prepared: CursorProviderTurnPrepareResult | undefined,
+	outcome: IncompleteCursorToolRunOutcomeInput,
+): void {
+	prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(buildIncompleteCursorToolRunOutcome(outcome));
+}

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

@@ -0,0 +1,119 @@
+import { createAgentPlatform } from "@cursor/sdk";
+import type { SDKAgent } from "@cursor/sdk";
+import { loadCursorTranscriptWebToolCallsAfterOffset } from "./cursor-agent-message-web-tools.js";
+import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
+import {
+	isCursorRunFinishedSuccessfully,
+	resolveCursorRunOutcome,
+	type CursorRunOutcome,
+} from "./cursor-provider-run-outcome.js";
+import type { CursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.js";
+
+export async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<void> {
+	try {
+		const platform = await createAgentPlatform();
+		const checkpoint = await platform.checkpointStore.loadLatest(agentId);
+		const contextWindow = getCheckpointContextWindow(checkpoint);
+		if (contextWindow) saveCachedContextWindow(modelId, contextWindow);
+	} catch {
+		// Context-window cache failures must not affect response streaming.
+	}
+}
+
+export interface BuildCursorRunOutcomeParams {
+	waitResult: Awaited<ReturnType<Awaited<ReturnType<SDKAgent["send"]>>["wait"]>>;
+	prepared: CursorProviderTurnPrepareResult;
+	signal?: AbortSignal;
+	runResultFallback?: string;
+	resolvedApiKey?: string;
+	optionsApiKey?: string;
+}
+
+export function buildCursorRunOutcomeFromWait(params: BuildCursorRunOutcomeParams): CursorRunOutcome {
+	const { waitResult, prepared } = params;
+	const { turnCoordinator, liveRun } = prepared.runtime;
+	const { textDeltas } = prepared;
+	return resolveCursorRunOutcome({
+		waitResult,
+		signalAborted: params.signal?.aborted,
+		textDeltas: liveRun?.textDeltas ?? textDeltas,
+		emittedText: liveRun?.emittedText ?? textDeltas.join(""),
+		planTextCandidate: turnCoordinator.planTextCandidate,
+		selectFinalTextOptions: liveRun ? undefined : { allowPartialPrefix: true },
+		runResultFallback: params.runResultFallback,
+		resolvedApiKey: params.resolvedApiKey,
+		optionsApiKey: params.optionsApiKey,
+	});
+}
+
+async function replayCursorTranscriptWebToolCalls(
+	agentId: string,
+	cwd: string,
+	messageOffset: number | undefined,
+	turnCoordinator: CursorSdkTurnCoordinator,
+	sdkEventDebug: CursorSdkEventDebugSink | undefined,
+): Promise<void> {
+	try {
+		const transcriptToolCalls = await loadCursorTranscriptWebToolCallsAfterOffset({
+			agentId,
+			cwd,
+			offset: messageOffset,
+		});
+		if (transcriptToolCalls.length === 0) return;
+		sdkEventDebug?.recordCoordinatorEvent("cursor-transcript-web-tools", {
+			agentId,
+			messageOffset,
+			count: transcriptToolCalls.length,
+		});
+		turnCoordinator.handleTranscriptCompletedToolCalls(transcriptToolCalls);
+	} catch (error) {
+		sdkEventDebug?.recordError("cursor_transcript_web_tools", error);
+	}
+}
+
+export interface AwaitFinalizeCursorRunOutcomeParams {
+	run: Awaited<ReturnType<SDKAgent["send"]>>;
+	prepared: CursorProviderTurnPrepareResult;
+	cursorAgentMessageOffset: number | undefined;
+	modelId: string;
+	signal?: AbortSignal;
+	runResultFallback?: string;
+	resolvedApiKey?: string;
+	optionsApiKey?: string;
+	sdkEventDebug?: CursorSdkEventDebugSink;
+	waitResult?: Awaited<ReturnType<Awaited<ReturnType<SDKAgent["send"]>>["wait"]>>;
+	cacheContextWindow?: boolean;
+	/** Session agent id for checkpoint cache; defaults to run.agentId when omitted. */
+	contextWindowAgentId?: string;
+}
+
+/** Single wait/finalize path for SDK runs: wait, debug capture, transcript replay, incomplete tools, artifacts, context cache. */
+export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorRunOutcomeParams): Promise<CursorRunOutcome> {
+	const waitResult = params.waitResult ?? (await params.run.wait());
+	params.sdkEventDebug?.recordWaitResult(waitResult);
+	const outcome = buildCursorRunOutcomeFromWait({
+		waitResult,
+		prepared: params.prepared,
+		signal: params.signal,
+		runResultFallback: params.runResultFallback,
+		resolvedApiKey: params.resolvedApiKey,
+		optionsApiKey: params.optionsApiKey,
+	});
+	if (isCursorRunFinishedSuccessfully(outcome)) {
+		await replayCursorTranscriptWebToolCalls(
+			params.run.agentId,
+			params.prepared.cwd,
+			params.cursorAgentMessageOffset,
+			params.prepared.runtime.turnCoordinator,
+			params.sdkEventDebug,
+		);
+	}
+	params.prepared.runtime.turnCoordinator.discardIncompleteStartedToolCalls(outcome.incompleteTools);
+	await params.sdkEventDebug?.captureRunArtifacts(params.run);
+	if (params.cacheContextWindow !== false) {
+		await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId);
+	}
+	return outcome;
+}

package/src/cursor-provider-turn-lifecycle-emitter.ts

@@ -0,0 +1,97 @@
+import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai";
+import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
+import {
+	CURSOR_TOOL_LIFECYCLE_DEFER_MS,
+	formatCursorToolLifecycleProgressText,
+	isCursorToolLifecycleEligible,
+} from "./cursor-tool-lifecycle.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
+
+function getNormalizedCursorToolName(toolCall: unknown): string {
+	return classifyCursorToolVisibility(toolCall).normalizedName;
+}
+
+export interface CursorToolLifecycleEmitterOptions {
+	liveRun?: CursorLiveRun;
+	resolvedApiKey?: string;
+	contentEmitter: CursorPartialContentEmitter;
+	debugRecorder?: CursorSdkEventDebugRecorder;
+	hasStartedToolCall: (callId: string) => boolean;
+	isBridgeMcpToolCall: (toolCall: unknown) => boolean;
+}
+
+export class CursorToolLifecycleEmitter {
+	private readonly liveRun?: CursorLiveRun;
+	private readonly resolvedApiKey?: string;
+	private readonly contentEmitter: CursorPartialContentEmitter;
+	private readonly debugRecorder?: CursorSdkEventDebugRecorder;
+	private readonly hasStartedToolCall: (callId: string) => boolean;
+	private readonly isBridgeMcpToolCall: (toolCall: unknown) => boolean;
+	private readonly emittedLifecycleCallIds = new Set<string>();
+	private readonly lifecycleTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+	constructor(options: CursorToolLifecycleEmitterOptions) {
+		this.liveRun = options.liveRun;
+		this.resolvedApiKey = options.resolvedApiKey;
+		this.contentEmitter = options.contentEmitter;
+		this.debugRecorder = options.debugRecorder;
+		this.hasStartedToolCall = options.hasStartedToolCall;
+		this.isBridgeMcpToolCall = options.isBridgeMcpToolCall;
+	}
+
+	maybeSchedule(callId: unknown, toolCall: unknown): void {
+		if (typeof callId !== "string" || this.emittedLifecycleCallIds.has(callId)) return;
+		if (this.isBridgeMcpToolCall(toolCall)) return;
+		if (!isCursorToolLifecycleEligible(toolCall)) return;
+
+		this.cancel(callId);
+		const timer = setTimeout(() => {
+			this.lifecycleTimers.delete(callId);
+			if (!this.hasStartedToolCall(callId)) return;
+			if (this.emittedLifecycleCallIds.has(callId)) return;
+			this.emit(callId, toolCall);
+		}, CURSOR_TOOL_LIFECYCLE_DEFER_MS);
+		timer.unref?.();
+		this.lifecycleTimers.set(callId, timer);
+	}
+
+	cancel(callId: string): void {
+		const timer = this.lifecycleTimers.get(callId);
+		if (!timer) return;
+		clearTimeout(timer);
+		this.lifecycleTimers.delete(callId);
+	}
+
+	clear(): void {
+		this.emittedLifecycleCallIds.clear();
+		for (const timer of this.lifecycleTimers.values()) clearTimeout(timer);
+		this.lifecycleTimers.clear();
+	}
+
+	private emit(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;
+		}
+		this.contentEmitter.appendThinkingDelta(progressText);
+	}
+}
+
+export function createTurnCoordinatorContentEmitter(
+	stream: AssistantMessageEventStream,
+	partial: AssistantMessage,
+): CursorPartialContentEmitter {
+	return new CursorPartialContentEmitter(stream, partial, undefined, false);
+}

package/src/cursor-provider-turn-message-offset.ts

@@ -0,0 +1,15 @@
+import { countCursorAgentMessages } from "./cursor-agent-message-web-tools.js";
+import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+
+export async function getCursorAgentMessageOffset(
+	agentId: string,
+	cwd: string,
+	sdkEventDebug: CursorSdkEventDebugSink | undefined,
+): Promise<number | undefined> {
+	try {
+		return await countCursorAgentMessages(agentId, cwd);
+	} catch (error) {
+		sdkEventDebug?.recordError("cursor_agent_message_count", error);
+		return undefined;
+	}
+}