pi-cursor-sdk 0.1.20 → 0.1.22

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

@@ -7,10 +7,47 @@ 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,
-	getCursorReplaySourceToolName,
+	getCursorReplayCallSummary,
+	getCursorReplaySideEffectDescription,
+	getCursorReplayOperationLabel,
+	getCursorReplayWrapperLabel,
 	type CursorReplayToolName,
-} from "./cursor-tool-names.js";
+} from "./cursor-tool-presentation-registry.js";
+import {
+	CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE,
+	type CursorReplayNativeEditDetails,
+	type CursorReplayGenerateImageDetails,
+	type CursorReplayActivityDetails,
+	type CursorReplayToolDetails,
+	type CursorReplayNativeWriteDetails,
+	isCursorReplayNativeEditDetails,
+	isCursorReplayGenerateImageDetails,
+	isCursorReplayActivityDetails,
+	parseCursorReplayToolDetails,
+} from "./cursor-replay-tool-details.js";
+
+export type {
+	CursorReplayNativeEditDetails,
+	CursorReplayEditDetails,
+	CursorReplayGenerateImageDetails,
+	CursorReplayGenericFallbackDetails,
+	CursorReplayActivityDetails,
+	CursorReplayTitledActivityDetails,
+	CursorReplayToolDetails,
+	CursorReplayNativeWriteDetails,
+	CursorReplayWriteDetails,
+} from "./cursor-replay-tool-details.js";
+export {
+	asCursorReplayToolDetails,
+	isCursorReplayNativeEditDetails,
+	isCursorReplayEditDetails,
+	isCursorReplayGenerateImageDetails,
+	isCursorReplayActivityDetails,
+	isCursorReplayTitledActivityDetails,
+	isCursorReplayNativeWriteDetails,
+	isCursorReplayWriteDetails,
+	parseCursorReplayToolDetails,
+} from "./cursor-replay-tool-details.js";
 
 export const CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES = 8;
 export const CURSOR_REPLAY_PREVIEW_MAX_CHARS = 4000;
@@ -18,30 +55,6 @@ export const CURSOR_REPLAY_PREVIEW_MAX_LINE_CHARS = 240;
 const CURSOR_REPLAY_HIGHLIGHT_MAX_CHARS = 12000;
 export const cursorReplayToolSchema = Type.Object({}, { additionalProperties: true });
 
-export interface CursorReplayToolDetails {
-	cursorToolName?: string;
-	title?: string;
-	summary?: string;
-	path?: string;
-	imagePath?: string;
-	imageDisplayPath?: string;
-	imageMimeType?: string;
-	linesAdded?: number;
-	linesRemoved?: number;
-	linesCreated?: number;
-	fileSize?: number;
-	fileContentAfterWrite?: string;
-	diffString?: string;
-	diff?: string;
-	firstChangedLine?: number;
-	expandedText?: string;
-	collapseDetailsByDefault?: boolean;
-}
-
-export function asCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	return value && typeof value === "object" ? (value as CursorReplayToolDetails) : undefined;
-}
-
 type CursorReplayRenderCall = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderCall"]>;
 type CursorReplayRenderResult = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderResult"]>;
 export type CursorReplayRenderTheme = Parameters<CursorReplayRenderCall>[1];
@@ -87,13 +100,10 @@ function buildImageReplayComponent(text: string, imageData: string, mimeType: st
 	};
 }
 
-function getCursorReplayToolLabel(toolName: CursorReplayToolName): string {
-	if (toolName === "cursor_edit") return "edit";
-	if (toolName === "cursor_write") return "write";
-	return getCursorReplayDisplayLabel(toolName);
-}
-
-export function getCursorReplayPath(args: Record<string, unknown> | undefined, details: CursorReplayToolDetails | undefined): string {
+export function getCursorReplayPath(
+	args: Record<string, unknown> | undefined,
+	details: Pick<CursorReplayNativeEditDetails, "path"> | Pick<CursorReplayNativeWriteDetails, "path"> | undefined,
+): string {
 	const argPath = args?.path;
 	return details?.path ?? (typeof argPath === "string" && argPath.trim() ? argPath : "unknown");
 }
@@ -212,6 +222,93 @@ function formatMutedBlock(text: string, theme: CursorReplayRenderTheme): string
 	return text.split("\n").map((line) => theme.fg("muted", line)).join("\n");
 }
 
+function hasUnifiedDiffHunk(text: string): boolean {
+	return text.split("\n").some((line) => Boolean(parseUnifiedDiffHunkHeader(line)));
+}
+
+/** First unified-diff marker (`---`/`+++`/`@@`) so collapsed previews budget diff lines, not transcript preamble. */
+function extractUnifiedDiffSection(text: string): string | undefined {
+	const lines = text.split("\n");
+	const markerIndex = lines.findIndex((line) => line.startsWith("--- ") || line.startsWith("+++ "));
+	const hunkIndex = lines.findIndex((line) => Boolean(parseUnifiedDiffHunkHeader(line)));
+	const start = markerIndex >= 0 ? markerIndex : hunkIndex;
+	if (start < 0) return undefined;
+	return lines.slice(start).join("\n");
+}
+
+function formatCursorReplayActivityDiffPreview(
+	text: string,
+	theme: CursorReplayRenderTheme,
+	maxLines: number,
+	stripHeader: boolean,
+): string | undefined {
+	const body = (stripHeader ? stripCursorReplayHeader(text) : text).trimEnd();
+	const diffSection = body ? extractUnifiedDiffSection(body) : undefined;
+	if (!diffSection || !hasUnifiedDiffHunk(diffSection)) return undefined;
+	// Legacy-only shim (old JSONL with no diffString on the activity details).
+	// All actual diff coloring now lives in the single `formatCursorReplayDiff` renderer.
+	// This path exists solely so pre-structured sessions still get colored diffs via the same
+	// high-quality implementation used for nativeEdit and new structured activity cases.
+	return formatCursorReplayDiff(diffSection, theme, maxLines);
+}
+
+function formatCursorReplayActivityEditPreview(
+	details: CursorReplayExpandableResultDetails,
+	text: string,
+	theme: CursorReplayRenderTheme,
+	maxLines: number,
+	stripHeader: boolean,
+): string | undefined {
+	const structuredDiff = details.diffString ?? details.diff;
+	if (structuredDiff) {
+		return formatCursorReplayDiff(structuredDiff, theme, maxLines);
+	}
+	const diffPreview = formatCursorReplayActivityDiffPreview(text, theme, maxLines, stripHeader);
+	if (diffPreview) return diffPreview;
+	return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
+}
+
+function formatCursorReplayActivityWritePreview(
+	details: CursorReplayExpandableResultDetails,
+	text: string,
+	theme: CursorReplayRenderTheme,
+	maxLines: number,
+	stripHeader: boolean,
+): string | undefined {
+	const structuredDiff = details.diffString ?? details.diff;
+	if (structuredDiff) {
+		return formatCursorReplayDiff(structuredDiff, theme, maxLines);
+	}
+	if (details.fileContentAfterWrite) {
+		return formatCursorReplayFilePreview(
+			details.fileContentAfterWrite,
+			details.path,
+			theme,
+			maxLines,
+			false,
+		);
+	}
+	const diffPreview = formatCursorReplayActivityDiffPreview(text, theme, maxLines, stripHeader);
+	if (diffPreview) return diffPreview;
+	return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
+}
+
+function formatCursorReplayActivityPreview(
+	details: CursorReplayExpandableResultDetails,
+	text: string,
+	theme: CursorReplayRenderTheme,
+	maxLines: number,
+	stripHeader: boolean,
+): string | undefined {
+	if (details.sourceToolName === "edit") {
+		return formatCursorReplayActivityEditPreview(details, text, theme, maxLines, stripHeader);
+	}
+	if (details.sourceToolName === "write") {
+		return formatCursorReplayActivityWritePreview(details, text, theme, maxLines, stripHeader);
+	}
+	return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
+}
+
 export function formatCursorReplayPreview(
 	text: string,
 	theme: CursorReplayRenderTheme,
@@ -257,69 +354,7 @@ function getCursorReplayActivityTitle(toolName: CursorReplayToolName, args: Reco
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME && typeof args?.activityTitle === "string" && args.activityTitle.trim()) {
 		return args.activityTitle.trim();
 	}
-	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 (activitySummary) return activitySummary;
-
-	const path = typeof args?.path === "string" ? args.path : undefined;
-	const description = typeof args?.description === "string" ? args.description : undefined;
-	const prompt = typeof args?.prompt === "string" ? args.prompt : undefined;
-	const totalCount = typeof args?.totalCount === "number" ? args.totalCount : undefined;
-	const diagnosticCount = typeof args?.diagnosticCount === "number" ? args.diagnosticCount : undefined;
-	const paths = Array.isArray(args?.paths) ? args.paths.filter((entry): entry is string => typeof entry === "string") : [];
-
-	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 `${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 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 (path) return path;
-		if (typeof args?.toolName === "string") return args.toolName;
-		return formatReplaySemSearchQuery(args);
-	}
-	return undefined;
+	return getCursorReplayWrapperLabel(toolName);
 }
 
 export function renderCursorReplayCall(
@@ -361,15 +396,15 @@ function pluralize(count: number, noun: string): string {
 	return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 
-function getCursorEditDiff(details: CursorReplayToolDetails): string | undefined {
+function getCursorEditDiff(details: CursorReplayNativeEditDetails): string | undefined {
 	return resolveCursorEditDiff(details);
 }
 
-function hasCursorEditChanges(details: CursorReplayToolDetails): boolean {
+function hasCursorEditChanges(details: CursorReplayNativeEditDetails): boolean {
 	return Boolean(getCursorEditDiff(details)) || Boolean(details.linesAdded) || Boolean(details.linesRemoved);
 }
 
-function classifyCursorEditOperation(details: CursorReplayToolDetails): "created" | "deleted" | "updated" | "unchanged" {
+function classifyCursorEditOperation(details: CursorReplayNativeEditDetails): "created" | "deleted" | "updated" | "unchanged" {
 	if (!hasCursorEditChanges(details)) return "unchanged";
 	const diff = getCursorEditDiff(details);
 	if (diff?.startsWith("--- /dev/null")) return "created";
@@ -377,7 +412,7 @@ function classifyCursorEditOperation(details: CursorReplayToolDetails): "created
 	return "updated";
 }
 
-function formatCursorEditSummary(details: CursorReplayToolDetails): string {
+function formatCursorEditSummary(details: CursorReplayNativeEditDetails): string {
 	const operation = classifyCursorEditOperation(details);
 	if (operation === "unchanged") return "no changes needed";
 	if (operation === "created" && details.linesAdded !== undefined) return `created ${pluralize(details.linesAdded, "line")}`;
@@ -394,24 +429,52 @@ function firstContentText(result: Parameters<CursorReplayRenderResult>[0]): stri
 	return content?.type === "text" ? content.text : "";
 }
 
+type CursorReplayExpandableResultDetails = {
+	summary?: string;
+	expandedText?: string;
+	collapseDetailsByDefault?: boolean;
+	imagePath?: string;
+	imageMimeType?: string;
+	sourceToolName?: CursorReplayActivityDetails["sourceToolName"];
+	path?: string;
+	/** Structured diff fields populated on activity edit/write details for canonical coloring (primary over text parse). */
+	diffString?: string;
+	diff?: string;
+	linesAdded?: number;
+	linesRemoved?: number;
+	/** Structured post-write content for activity write fallbacks; drives canonical file preview (mirrors nativeWrite). */
+	fileContentAfterWrite?: string;
+};
+
+function hasCursorReplayDisplayTitle(details: CursorReplayToolDetails | undefined): boolean {
+	if (!details) return false;
+	return isCursorReplayActivityDetails(details) || isCursorReplayGenerateImageDetails(details);
+}
+
 function renderExpandableCursorReplayResult(
 	title: string,
+	details: CursorReplayExpandableResultDetails,
 	result: Parameters<CursorReplayRenderResult>[0],
 	options: Parameters<CursorReplayRenderResult>[1],
 	theme: Parameters<CursorReplayRenderResult>[2],
 	context: Parameters<CursorReplayRenderResult>[3],
 	isError: boolean,
 ): Component {
-	const details = asCursorReplayToolDetails(result.details);
 	const text = firstContentText(result);
-	const summary = details?.summary ?? text.split("\n").find((line) => line.trim()) ?? "completed";
+	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 && (options.expanded || !details?.collapseDetailsByDefault)) {
-		const preview = options.expanded ? formatMutedBlock(expandedText, theme) : formatCursorReplayPreview(expandedText, theme);
+	const expandedText = details.expandedText ?? (text.includes("\n") ? text : undefined);
+	if (expandedText && (options.expanded || !details.collapseDetailsByDefault)) {
+		const preview = formatCursorReplayActivityPreview(
+			details,
+			expandedText,
+			theme,
+			options.expanded ? Number.POSITIVE_INFINITY : CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES,
+			!options.expanded,
+		);
 		if (preview) rendered += `\n${preview}`;
 	}
-	if (details?.cursorToolName === "generateImage" && !isError && context.showImages) {
+	if (details.imagePath && !isError && context.showImages) {
 		const imageData = readImageFileForReplay(details.imagePath);
 		const mimeType = details.imageMimeType ?? inferImageMimeTypeFromPath(details.imagePath);
 		if (imageData && mimeType) return buildImageReplayComponent(rendered, imageData, mimeType, basename(details.imagePath ?? "generated-image"), theme);
@@ -419,14 +482,81 @@ function renderExpandableCursorReplayResult(
 	return new Text(rendered, 0, 0);
 }
 
+function renderCursorReplayEditResult(
+	details: CursorReplayNativeEditDetails,
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+): Component {
+	const summary = formatCursorEditSummary(details);
+	let rendered = `${theme.fg("toolTitle", theme.bold("edit"))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`;
+	const diff = getCursorEditDiff(details);
+	if (diff) rendered += `\n${formatCursorReplayDiff(diff, theme, options.expanded ? 40 : CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES)}`;
+	return new Text(rendered, 0, 0);
+}
+
+function renderCursorReplayWriteResult(
+	details: CursorReplayNativeWriteDetails,
+	result: Parameters<CursorReplayRenderResult>[0],
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+): Component {
+	const text = firstContentText(result);
+	const parts = [
+		details.linesCreated !== undefined ? `${details.linesCreated} line${details.linesCreated === 1 ? "" : "s"}` : undefined,
+		details.fileSize !== undefined ? `${details.fileSize} bytes` : undefined,
+	].filter(Boolean);
+	const summary = parts.length > 0 ? parts.join(", ") : "written";
+	let rendered = `${theme.fg("toolTitle", theme.bold("write"))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`;
+	const previewSource = details.fileContentAfterWrite ?? details.expandedText ?? text;
+	const preview = formatCursorReplayFilePreview(
+		previewSource,
+		getCursorReplayPath(undefined, details),
+		theme,
+		CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES,
+		details.fileContentAfterWrite === undefined,
+	);
+	if (preview) rendered += `\n${preview}`;
+	return new Text(rendered, 0, 0);
+}
+
 function renderCursorGenerateImageResult(
+	details: CursorReplayGenerateImageDetails,
+	result: Parameters<CursorReplayRenderResult>[0],
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+	context: Parameters<CursorReplayRenderResult>[3],
+	isError: boolean,
+): Component {
+	const title = CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE;
+	return renderExpandableCursorReplayResult(title, details, result, options, theme, context, isError);
+}
+
+function renderCursorReplayDetails(
+	details: CursorReplayToolDetails,
 	result: Parameters<CursorReplayRenderResult>[0],
 	options: Parameters<CursorReplayRenderResult>[1],
 	theme: Parameters<CursorReplayRenderResult>[2],
 	context: Parameters<CursorReplayRenderResult>[3],
 	isError: boolean,
+	text: string,
 ): Component {
-	return renderExpandableCursorReplayResult("Cursor generateImage", result, options, theme, context, isError);
+	switch (details.variant) {
+		case "nativeEdit":
+			return renderCursorReplayEditResult(details, options, theme);
+		case "nativeWrite":
+			return renderCursorReplayWriteResult(details, result, options, theme);
+		case "generateImage":
+			return renderCursorGenerateImageResult(details, result, options, theme, context, isError);
+		case "activity":
+			return renderExpandableCursorReplayResult(details.title, details, result, options, theme, context, isError);
+		case "genericFallback":
+			break;
+		default: {
+			const _exhaustive: never = details;
+			return _exhaustive;
+		}
+	}
+	return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
 }
 
 export function renderCursorReplayResult(
@@ -437,41 +567,13 @@ export function renderCursorReplayResult(
 	isError: boolean,
 ): Component {
 	if (options.isPartial) return new Text(theme.fg("warning", "Replaying Cursor tool result..."), 0, 0);
-	const details = asCursorReplayToolDetails(result.details);
+	const details = parseCursorReplayToolDetails(result.details);
 	const text = firstContentText(result);
-	if (isError && !details?.title) return new Text(theme.fg("error", text.split("\n")[0] || "Cursor replay failed"), 0, 0);
-
-	if (details?.cursorToolName === "edit" && hasCursorEditChanges(details)) {
-		const summary = formatCursorEditSummary(details);
-		const title = details.title ?? "edit";
-		let rendered = `${theme.fg("toolTitle", theme.bold(title))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`;
-		const diff = getCursorEditDiff(details);
-		if (diff) rendered += `\n${formatCursorReplayDiff(diff, theme, options.expanded ? 40 : CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES)}`;
-		return new Text(rendered, 0, 0);
+	if (isError && !hasCursorReplayDisplayTitle(details)) {
+		return new Text(theme.fg("error", text.split("\n")[0] || "Cursor replay failed"), 0, 0);
 	}
-
-	if (details?.cursorToolName === "write") {
-		const parts = [
-			details.linesCreated !== undefined ? `${details.linesCreated} line${details.linesCreated === 1 ? "" : "s"}` : undefined,
-			details.fileSize !== undefined ? `${details.fileSize} bytes` : undefined,
-		].filter(Boolean);
-		const summary = parts.length > 0 ? parts.join(", ") : "written";
-		let rendered = `${theme.fg("toolTitle", theme.bold("write"))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`;
-		const previewSource = details.fileContentAfterWrite ?? details.expandedText ?? text;
-		const preview = formatCursorReplayFilePreview(
-			previewSource,
-			getCursorReplayPath(undefined, details),
-			theme,
-			CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES,
-			details.fileContentAfterWrite === undefined,
-		);
-		if (preview) rendered += `\n${preview}`;
-		return new Text(rendered, 0, 0);
-	}
-
-	if (details?.cursorToolName === "generateImage") return renderCursorGenerateImageResult(result, options, theme, context, isError);
-	if (details?.title) return renderExpandableCursorReplayResult(details.title, result, options, theme, context, isError);
-	return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
+	if (!details) return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
+	return renderCursorReplayDetails(details, result, options, theme, context, isError, text);
 }
 
 export function renderNativeLookingCursorReadReplayResult(
@@ -500,11 +602,11 @@ export function renderNativeLookingCursorReadReplayResult(
 }
 
 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";
+	const cursorToolName = toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "activity" : getCursorReplayOperationLabel(toolName);
+	const sideEffectDescription = getCursorReplaySideEffectDescription(toolName);
 	return {
 		name: toolName,
-		label: getCursorReplayToolLabel(toolName),
+		label: getCursorReplayWrapperLabel(toolName),
 		description: `Replay display for a Cursor SDK ${cursorToolName} operation. This tool only returns recorded Cursor results and never executes ${sideEffectDescription} directly.`,
 		promptSnippet: `Render a recorded Cursor SDK ${cursorToolName} operation without executing ${sideEffectDescription}.`,
 		promptGuidelines: [

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

@@ -10,6 +10,7 @@ export const NATIVE_CURSOR_TOOL_DISPLAY_ENV = "PI_CURSOR_NATIVE_TOOL_DISPLAY";
 export const NATIVE_CURSOR_TOOL_REGISTRATION_ENV = "PI_CURSOR_REGISTER_NATIVE_TOOLS";
 
 export const registeredNativeToolNames = new Set<string>();
+export const skippedNativeToolNames = new Set<string>();
 export const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
 
 export function readBooleanEnv(name: string, env: Record<string, string | undefined> = process.env): boolean | undefined {
@@ -73,6 +74,7 @@ export const __testUtils = {
 	},
 	reset(): void {
 		registeredNativeToolNames.clear();
+		skippedNativeToolNames.clear();
 		nativeToolResults.clear();
 	},
 };