pi-cursor-sdk 0.1.18 → 0.1.20

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

@@ -4,6 +4,7 @@ import { getLanguageFromPath, highlightCode, type ToolDefinition } from "@earend
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
+import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-transcript-utils.js";
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 	getCursorReplayDisplayLabel,
@@ -34,6 +35,7 @@ export interface CursorReplayToolDetails {
 	diff?: string;
 	firstChangedLine?: number;
 	expandedText?: string;
+	collapseDetailsByDefault?: boolean;
 }
 
 export function asCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
@@ -258,9 +260,27 @@ function getCursorReplayActivityTitle(toolName: CursorReplayToolName, args: Reco
 	return getCursorReplayToolLabel(toolName);
 }
 
+function formatReplayRecordingDurationMs(ms: number | undefined): string | undefined {
+	if (ms === undefined || !Number.isFinite(ms) || ms < 0) return undefined;
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1000;
+	return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}
+
+function formatReplaySemSearchQuery(args: Record<string, unknown> | undefined): string | undefined {
+	const query = typeof args?.query === "string" ? args.query.trim() : undefined;
+	if (!query) return undefined;
+	const targetDirectories = Array.isArray(args?.targetDirectories)
+		? args.targetDirectories.filter((entry): entry is string => typeof entry === "string")
+		: [];
+	const dirHint =
+		targetDirectories.length > 0 ? ` (${targetDirectories.length} dir${targetDirectories.length === 1 ? "" : "s"})` : "";
+	return `${query}${dirHint}`;
+}
+
 function getCursorReplayCallSummary(toolName: CursorReplayToolName, args: Record<string, unknown> | undefined): string | undefined {
 	const activitySummary = typeof args?.activitySummary === "string" && args.activitySummary.trim() ? args.activitySummary.trim() : undefined;
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME && activitySummary) return activitySummary;
+	if (activitySummary) return activitySummary;
 
 	const path = typeof args?.path === "string" ? args.path : undefined;
 	const description = typeof args?.description === "string" ? args.description : undefined;
@@ -271,19 +291,33 @@ function getCursorReplayCallSummary(toolName: CursorReplayToolName, args: Record
 
 	if (toolName === "cursor_edit" || toolName === "cursor_write" || toolName === "cursor_delete") return path ?? "unknown";
 	if (toolName === "cursor_read_lints") {
-		const target = paths.length > 0 ? paths.join(" ") : path;
-		if (target && diagnosticCount !== undefined) return `${target} · ${diagnosticCount} diagnostic${diagnosticCount === 1 ? "" : "s"}`;
+		const target = paths.length > 0 ? paths.join(", ") : path;
+		if (target && diagnosticCount !== undefined) {
+			return `${diagnosticCount} diagnostic${diagnosticCount === 1 ? "" : "s"} in ${target}`;
+		}
 		return target;
 	}
 	if (toolName === "cursor_update_todos" || toolName === "cursor_create_plan") {
 		return totalCount !== undefined ? `${totalCount} item${totalCount === 1 ? "" : "s"}` : undefined;
 	}
 	if (toolName === "cursor_task") return description;
-	if (toolName === "cursor_generate_image") return prompt;
+	if (toolName === "cursor_generate_image") return path ?? prompt;
 	if (toolName === "cursor_mcp") return typeof args?.toolName === "string" ? args.toolName : undefined;
+	if (toolName === "cursor_sem_search") return formatReplaySemSearchQuery(args);
+	if (toolName === "cursor_record_screen") {
+		const duration = formatReplayRecordingDurationMs(
+			typeof args?.recordingDurationMs === "number" ? args.recordingDurationMs : undefined,
+		);
+		if (path && duration) return `${path} · ${duration}`;
+		if (path) return path;
+		if (typeof args?.mode === "string") return args.mode;
+	}
+	if (toolName === "cursor_web_search") return typeof args?.query === "string" ? args.query : undefined;
+	if (toolName === "cursor_web_fetch") return typeof args?.url === "string" ? args.url : undefined;
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) {
-		if (typeof args?.path === "string") return args.path;
+		if (path) return path;
 		if (typeof args?.toolName === "string") return args.toolName;
+		return formatReplaySemSearchQuery(args);
 	}
 	return undefined;
 }
@@ -373,7 +407,7 @@ function renderExpandableCursorReplayResult(
 	const summary = details?.summary ?? text.split("\n").find((line) => line.trim()) ?? "completed";
 	let rendered = `${theme.fg("toolTitle", theme.bold(title))} ${theme.fg(isError ? "error" : "success", summary)}`;
 	const expandedText = details?.expandedText ?? (text.includes("\n") ? text : undefined);
-	if (expandedText) {
+	if (expandedText && (options.expanded || !details?.collapseDetailsByDefault)) {
 		const preview = options.expanded ? formatMutedBlock(expandedText, theme) : formatCursorReplayPreview(expandedText, theme);
 		if (preview) rendered += `\n${preview}`;
 	}
@@ -440,6 +474,31 @@ export function renderCursorReplayResult(
 	return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
 }
 
+export function renderNativeLookingCursorReadReplayResult(
+	result: Parameters<CursorReplayRenderResult>[0],
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+	context: Parameters<CursorReplayRenderResult>[3],
+	renderBase: () => Component | undefined,
+): Component {
+	const base = renderBase?.() ?? new Text("", 0, 0);
+	const readArgs = context.args as Record<string, unknown> | undefined;
+	const replayDetails = result.details as Record<string, unknown> | undefined;
+	const usesLocalPreview =
+		readArgs?.localReadPreview === true ||
+		replayDetails?.localReadPreview === true ||
+		isLocalReadPreviewContent(firstContentText(result));
+	if (usesLocalPreview && !options.expanded && !context.isError) {
+		const noticeText = `\n${theme.fg("warning", LOCAL_READ_PREVIEW_NOTICE)}`;
+		if (base instanceof Text) {
+			base.setText(noticeText);
+			return base;
+		}
+		return new Text(noticeText, 0, 0);
+	}
+	return base;
+}
+
 export function createCursorReplayOnlyToolDefinition(toolName: CursorReplayToolName): ToolDefinition<typeof cursorReplayToolSchema, unknown> {
 	const cursorToolName = toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "activity" : getCursorReplaySourceToolName(toolName);
 	const sideEffectDescription = toolName === "cursor_edit" || toolName === "cursor_write" || toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "file mutations" : "real tool work";

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

@@ -21,6 +21,7 @@ import {
 	createCursorReplayOnlyToolDefinition,
 	renderCursorReplayResult,
 	renderNativeLookingCursorFileMutationCall,
+	renderNativeLookingCursorReadReplayResult,
 } from "./cursor-native-tool-display-replay.js";
 import {
 	consumeCursorNativeToolDisplay,
@@ -65,6 +66,20 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 			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);
 			}
@@ -76,6 +91,11 @@ export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 			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);
 		},

package/src/cursor-pi-tool-bridge-diagnostics.ts

@@ -1,5 +1,6 @@
 import { stableNameHash } from "./cursor-pi-tool-bridge-mcp.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export const CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_DEBUG";
 export const CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX = "[pi-cursor-sdk:bridge]";
@@ -169,7 +170,16 @@ export function serializeCursorPiToolBridgeDiagnostic(event: CursorPiToolBridgeD
 	return assertNeverDiagnosticEvent(event);
 }
 
-export function writeCursorPiToolBridgeDiagnostic(env: Record<string, string | undefined>, event: CursorPiToolBridgeDiagnosticEvent): void {
+export function writeCursorPiToolBridgeDiagnostic(
+	env: Record<string, string | undefined>,
+	event: CursorPiToolBridgeDiagnosticEvent,
+	debugRecorder?: CursorSdkEventDebugRecorder,
+): void {
+	try {
+		debugRecorder?.recordBridgeDiagnostic(event);
+	} catch {
+		// Diagnostics must never affect bridge execution.
+	}
 	if (!resolveCursorPiToolBridgeDebugEnabled(env)) return;
 	try {
 		process.stderr.write(`${CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX} ${JSON.stringify(serializeCursorPiToolBridgeDiagnostic(event))}\n`);

package/src/cursor-pi-tool-bridge-run.ts

@@ -67,6 +67,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	private readonly pendingByBridgeCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByCursorMcpCallId = new Map<string, PendingBridgeCall>();
 	private onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	private debugRecorder: CursorPiToolBridgeRunOptions["debugRecorder"];
 	private liveRunHandlerDetached = false;
 	private mcpServer?: McpProtocolServer;
 	private mcpTransport?: StreamableHTTPServerTransport;
@@ -85,6 +86,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.snapshot = snapshot;
 		this.enabled = enabled;
 		this.onToolRequest = options.onToolRequest;
+		this.debugRecorder = options.debugRecorder;
 		this.id = `cursor-pi-bridge-run-${randomUUID()}`;
 		this.endpointPath = `${MCP_ENDPOINT_ROOT}/${randomUUID()}/mcp`;
 		this.knownMcpToolNames = new Set(snapshot.tools.map((tool) => tool.mcpToolName));
@@ -146,6 +148,10 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		}
 	}
 
+	setDebugRecorder(recorder?: CursorPiToolBridgeRunOptions["debugRecorder"]): void {
+		this.debugRecorder = recorder;
+	}
+
 	resolveToolResults(toolResults: readonly ToolResultMessage[]): void {
 		for (const toolResult of toolResults) {
 			const pending = this.pendingByPiToolCallId.get(toolResult.toolCallId);
@@ -290,9 +296,11 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 				}
 				this.queuedRequests.push(request);
 				this.emitRequestQueuedDiagnostic(request);
+				this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
 				return;
 			}
 			this.emitRequestQueuedDiagnostic(request);
+			this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
 			this.dispatchPendingToolRequest(pending, this.onToolRequest);
 		});
 	}
@@ -321,6 +329,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestResolvedDiagnostic(pending.request, result.isError === true);
+		this.debugRecorder?.recordBridgeRaw({ kind: "resolved", request: pending.request, result });
 		pending.resolve(result);
 	}
 
@@ -329,6 +338,12 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestRejectedDiagnostic(pending.request, kind);
+		this.debugRecorder?.recordBridgeRaw({
+			kind: "rejected",
+			request: pending.request,
+			error: error.message,
+			rejectionKind: kind,
+		});
 		pending.reject(error);
 	}
 
@@ -366,7 +381,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	}
 
 	private emitDiagnostic(event: CursorPiToolBridgeDiagnosticEvent): void {
-		writeCursorPiToolBridgeDiagnostic(this.env, event);
+		writeCursorPiToolBridgeDiagnostic(this.env, event, this.debugRecorder);
 	}
 
 	private pendingCount(): number {

package/src/cursor-pi-tool-bridge-types.ts

@@ -1,5 +1,6 @@
 import type { McpServerConfig } from "@cursor/sdk";
 import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 import type {
 	ExtensionAPI,
 	ExtensionHandler,
@@ -64,6 +65,7 @@ export interface CursorPiToolBridgeRun {
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;
+	setDebugRecorder(recorder?: CursorSdkEventDebugRecorder): void;
 	cancel(reason: string): void;
 	dispose(): Promise<void>;
 }
@@ -77,4 +79,5 @@ export interface CursorPiToolBridge {
 
 export interface CursorPiToolBridgeRunOptions {
 	onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }

package/src/cursor-provider-errors.ts

@@ -0,0 +1,96 @@
+import type { RunResult } from "@cursor/sdk";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+
+export const MISSING_CURSOR_API_KEY_MESSAGE =
+	"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. 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. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
+const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
+	"Cursor SDK request timed out during network I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
+
+const GENERIC_CURSOR_RUN_FAILURE_TEXT = "cursor sdk run failed";
+
+export type CursorSdkRunFailureSource = Pick<RunResult, "id" | "status" | "durationMs" | "model" | "result">;
+
+function isGenericErrorMessage(message: string): boolean {
+	const normalized = message.trim().toLowerCase();
+	return normalized === "" || normalized === "error" || normalized === "unknown error";
+}
+
+function isKnownGenericRunFailureText(message: string): boolean {
+	const normalized = message.trim().toLowerCase();
+	return normalized === "" || normalized === GENERIC_CURSOR_RUN_FAILURE_TEXT || isGenericErrorMessage(normalized);
+}
+
+function isLikelyAuthError(message: string): boolean {
+	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
+}
+
+function isLikelyNetworkTimeout(message: string): boolean {
+	return (
+		/\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAI_AGAIN)\b/i.test(message) ||
+		/\bConnectError\b.*\b(unavailable|deadline|timeout|timed out)\b/i.test(message) ||
+		/\bread ETIMEDOUT\b/i.test(message)
+	);
+}
+
+function shortRunId(runId: string): string {
+	const trimmed = runId.trim();
+	if (trimmed.length <= 12) return trimmed;
+	return `${trimmed.slice(0, 8)}…`;
+}
+
+export function formatCursorSdkRunFailureDetail(result: CursorSdkRunFailureSource, runResult?: string): string {
+	const fromWait = result.result?.trim();
+	if (fromWait && !isKnownGenericRunFailureText(fromWait)) {
+		return fromWait;
+	}
+	const fromRun = runResult?.trim();
+	if (fromRun && !isKnownGenericRunFailureText(fromRun)) {
+		return fromRun;
+	}
+
+	const parts = ["Cursor SDK run failed"];
+	if (result.model?.id) parts.push(`model ${result.model.id}`);
+	parts.push(`run ${shortRunId(result.id)}`);
+	if (typeof result.durationMs === "number") parts.push(`${result.durationMs}ms`);
+	return parts.join(" · ");
+}
+
+export type CursorSdkAbortCause = "user_interrupt" | "sdk_cancelled" | "live_run_disposed" | "unknown";
+
+export function formatCursorSdkAbortMessage(cause: CursorSdkAbortCause): string {
+	switch (cause) {
+		case "user_interrupt":
+			return "Cancelled: prompt interrupted.";
+		case "sdk_cancelled":
+			return "Cancelled: Cursor SDK run was cancelled.";
+		case "live_run_disposed":
+			return "Cancelled: Cursor SDK live run ended before completion.";
+		case "unknown":
+			return "Cancelled: Cursor SDK run aborted.";
+	}
+}
+
+export function resolveCursorSdkAbortCause(options: {
+	signalAborted?: boolean;
+	sdkStatusCancelled?: boolean;
+	liveRunDisposed?: boolean;
+}): CursorSdkAbortCause {
+	if (options.signalAborted) return "user_interrupt";
+	if (options.sdkStatusCancelled) return "sdk_cancelled";
+	if (options.liveRunDisposed) return "live_run_disposed";
+	return "unknown";
+}
+
+export function sanitizeCursorProviderError(error: unknown, apiKey?: string): string {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_API_KEY_MESSAGE;
+	const scrubbed = scrubSensitiveText(message, apiKey).trim();
+	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
+	if (isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	if (isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
+	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
+}