pi-cursor-sdk 0.1.19 → 0.1.21

package/src/cursor-replay-activity-builders.ts

@@ -0,0 +1,276 @@
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import type {
+	CursorReplayGenerateImageSummaryArgs,
+	CursorReplayMcpSummaryArgs,
+	CursorReplayPathSummaryArgs,
+	CursorReplayPlanSummaryArgs,
+	CursorReplayReadLintsSummaryArgs,
+	CursorReplayRecordScreenSummaryArgs,
+	CursorReplaySemSearchSummaryArgs,
+	CursorReplayTaskSummaryArgs,
+	CursorReplayTodoSummaryArgs,
+	CursorReplayWebFetchSummaryArgs,
+	CursorReplayWebSearchSummaryArgs,
+} from "./cursor-replay-summary-args.js";
+import type { CursorReplayGenerateImageDetailFields } from "./cursor-replay-tool-details.js";
+import { asRecord } from "./cursor-record-utils.js";
+import {
+	firstNonEmptyLine,
+	formatDisplayPath,
+	getArray,
+	getNumber,
+	getRecord,
+	getString,
+	truncateArg,
+} from "./cursor-transcript-utils.js";
+import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
+
+export interface CursorReplayActivityBuildContext {
+	args: Record<string, unknown>;
+	result: { status: string | undefined; value: unknown; error: unknown };
+	options: { cwd?: string };
+}
+
+export function buildDeleteReplaySummaryArgs({ args, options }: CursorReplayActivityBuildContext): CursorReplayPathSummaryArgs {
+	const displayPath = typeof args.path === "string" ? formatDisplayPath(args.path, options.cwd) : undefined;
+	return displayPath ? { path: displayPath } : {};
+}
+
+export function buildDeleteReplayDetailFields({ args, result, options }: CursorReplayActivityBuildContext): {
+	path?: string;
+	fileSize?: number;
+} {
+	const displayPath = typeof args.path === "string" ? formatDisplayPath(args.path, options.cwd) : undefined;
+	const value = asRecord(result.value);
+	return {
+		path: displayPath,
+		fileSize: getNumber(value, "fileSize"),
+	};
+}
+
+export function buildEmptyReplayDetailFields(): Record<string, never> {
+	return {};
+}
+
+export function buildCollapsedReplayDetailFields(): { collapseDetailsByDefault: true } {
+	return { collapseDetailsByDefault: true };
+}
+
+export function buildReadLintsReplaySummaryArgs({
+	args,
+	result,
+	options,
+}: CursorReplayActivityBuildContext): CursorReplayReadLintsSummaryArgs {
+	const paths = getReadLintPaths(args, result, options);
+	const diagnosticCount = getReadLintDiagnostics(result, options).length;
+	return {
+		...(paths.length > 0 ? { paths } : {}),
+		...(paths.length === 1 ? { path: paths[0] } : {}),
+		...(paths.length > 0 ? { diagnosticCount } : {}),
+	};
+}
+
+export function buildTodoReplaySummaryArgs(
+	args: Record<string, unknown>,
+	result: CursorReplayActivityBuildContext["result"],
+): CursorReplayTodoSummaryArgs {
+	const todos = getTodoItems(args, result);
+	const totalCount = getNumber(asRecord(result.value), "totalCount") ?? getNumber(args, "totalCount") ?? todos.length;
+	const completedCount = todos.filter((todo) => todo.status === "completed").length;
+	const inProgressCount = todos.filter((todo) => todo.status === "inProgress").length;
+	const pendingCount = todos.filter((todo) => todo.status === "pending").length;
+	return todos.length > 0
+		? { totalCount, completedCount, inProgressCount, pendingCount }
+		: { totalCount };
+}
+
+export function buildCreatePlanReplaySummaryArgs({ args, result }: CursorReplayActivityBuildContext): CursorReplayPlanSummaryArgs {
+	const plan = getString(args, "plan") ?? getString(asRecord(result.value) ?? {}, "plan");
+	const planTitle = plan ? firstNonEmptyLine(plan) : undefined;
+	return {
+		...buildTodoReplaySummaryArgs(args, result),
+		...(planTitle ? { planTitle: truncateArg(planTitle) } : {}),
+	};
+}
+
+export function buildTaskReplaySummaryArgs({ args, result }: CursorReplayActivityBuildContext): CursorReplayTaskSummaryArgs {
+	const description = getString(args, "description") ?? getString(asRecord(result.value), "description") ?? "task";
+	const preview = firstNonEmptyLine(collectTaskText(result));
+	return {
+		description: truncateArg(description),
+		...(preview ? { preview: truncateArg(preview) } : {}),
+	};
+}
+
+export function buildGenerateImageReplaySummaryArgs({
+	args,
+	result,
+	options,
+}: CursorReplayActivityBuildContext): CursorReplayGenerateImageSummaryArgs {
+	const prompt = getString(args, "prompt") ?? getString(args, "description") ?? "image";
+	const imageDisplayPath = getGenerateImageDisplayPath(args, result, options);
+	return {
+		prompt: truncateArg(prompt),
+		...(imageDisplayPath ? { path: imageDisplayPath } : {}),
+	};
+}
+
+export function buildMcpReplaySummaryArgs({ args, result }: CursorReplayActivityBuildContext): CursorReplayMcpSummaryArgs {
+	const toolName = getString(args, "toolName") ?? "mcp";
+	const preview = getMcpResultPreview(result);
+	return {
+		toolName: truncateArg(toolName),
+		...(preview ? { preview } : {}),
+	};
+}
+
+export function buildSemSearchReplaySummaryArgs({ args }: CursorReplayActivityBuildContext): CursorReplaySemSearchSummaryArgs {
+	const query = getString(args, "query") ?? "semantic search";
+	const targetDirectories = (getArray(args, "targetDirectories") ?? []).filter((entry): entry is string => typeof entry === "string");
+	return {
+		query: truncateArg(query),
+		...(targetDirectories.length > 0 ? { targetDirectories } : {}),
+	};
+}
+
+export function buildRecordScreenReplaySummaryArgs({
+	args,
+	result,
+	options,
+}: CursorReplayActivityBuildContext): CursorReplayRecordScreenSummaryArgs {
+	const mode = getString(args, "mode");
+	const value = asRecord(result.value) ?? {};
+	const path = getString(value, "path");
+	const recordingDurationMs = getNumber(value, "recordingDurationMs");
+	return {
+		...(mode ? { mode } : {}),
+		...(path ? { path: formatDisplayPath(path, options.cwd) } : {}),
+		...(recordingDurationMs !== undefined ? { recordingDurationMs } : {}),
+	};
+}
+
+export function buildWebSearchReplaySummaryArgs({ args }: CursorReplayActivityBuildContext): CursorReplayWebSearchSummaryArgs {
+	const query = extractWebSearchQuery(args);
+	return query ? { query: truncateArg(query) } : {};
+}
+
+export function buildWebFetchReplaySummaryArgs({ args }: CursorReplayActivityBuildContext): CursorReplayWebFetchSummaryArgs {
+	const url = extractWebFetchTarget(args);
+	return url ? { url: truncateArg(url) } : {};
+}
+
+export function buildGenerateImageReplayDetailFields(
+	context: CursorReplayActivityBuildContext,
+	contentText: string,
+): CursorReplayGenerateImageDetailFields {
+	const { args, result, options } = context;
+	const imagePath = getGenerateImagePath(args, result);
+	const imageDisplayPath = getGenerateImageDisplayPath(args, result, options);
+	return {
+		imagePath,
+		imageDisplayPath,
+		imageMimeType: inferImageMimeType(imagePath),
+		expandedText: contentText,
+	};
+}
+
+function getReadLintPaths(args: Record<string, unknown>, result: CursorReplayActivityBuildContext["result"], options: CursorReplayActivityBuildContext["options"]): string[] {
+	const explicitPaths = Array.isArray(args.paths)
+		? args.paths.filter((entry): entry is string => typeof entry === "string")
+		: typeof args.path === "string"
+			? [args.path]
+			: [];
+	const resultPaths = (getArray(asRecord(result.value), "fileDiagnostics") ?? [])
+		.map((file) => getString(asRecord(file), "path"))
+		.filter((entry): entry is string => Boolean(entry));
+	return [...new Set([...explicitPaths, ...resultPaths].map((entry) => formatDisplayPath(entry, options.cwd)))];
+}
+
+function getReadLintDiagnostics(result: CursorReplayActivityBuildContext["result"], options: CursorReplayActivityBuildContext["options"]): string[] {
+	const value = asRecord(result.value);
+	const files = getArray(value, "fileDiagnostics") ?? [];
+	const lines: string[] = [];
+	for (const file of files) {
+		const fileRecord = asRecord(file);
+		const pathValue = getString(fileRecord, "path");
+		const path = pathValue ? formatDisplayPath(pathValue, options.cwd) : "unknown";
+		const diagnostics = getArray(fileRecord, "diagnostics") ?? [];
+		for (const diagnostic of diagnostics) {
+			const diagnosticRecord = asRecord(diagnostic);
+			const severity = getString(diagnosticRecord, "severity") ?? "diagnostic";
+			const message = getString(diagnosticRecord, "message") ?? "";
+			const source = getString(diagnosticRecord, "source");
+			lines.push(`${path}: ${severity}${source ? ` ${source}` : ""}: ${message}`);
+		}
+	}
+	return lines;
+}
+
+function getTodoItems(args: Record<string, unknown>, result: CursorReplayActivityBuildContext["result"]): Array<{ content: string; status?: string }> {
+	const value = asRecord(result.value);
+	const rawTodos = getArray(value, "todos") ?? getArray(args, "todos") ?? [];
+	const todos: Array<{ content: string; status?: string }> = [];
+	for (const todo of rawTodos) {
+		const record = asRecord(todo);
+		const content = getString(record, "content");
+		if (!content) continue;
+		const status = getString(record, "status");
+		todos.push(status ? { content, status } : { content });
+	}
+	return todos;
+}
+
+function collectTaskText(result: CursorReplayActivityBuildContext["result"]): string {
+	const value = asRecord(result.value);
+	const success = getRecord(getRecord(value, "result"), "success");
+	const command = getString(success, "command");
+	const stdout = getString(success, "stdout");
+	const interleavedOutput = getString(success, "interleavedOutput");
+	const assistantMessages = (getArray(value, "conversationSteps") ?? [])
+		.map((step) => getString(getRecord(asRecord(step), "assistantMessage"), "text"))
+		.filter((entry): entry is string => Boolean(entry));
+	const parts = [command ? `$ ${command}` : undefined, stdout || interleavedOutput, ...assistantMessages].filter((part): part is string => Boolean(part));
+	return parts.join("\n");
+}
+
+function getGenerateImagePath(args: Record<string, unknown>, result: CursorReplayActivityBuildContext["result"]): string | undefined {
+	const value = asRecord(result.value);
+	return getString(value, "filePath") ?? getString(args, "filePath") ?? getString(args, "path");
+}
+
+function getGenerateImageDisplayPath(args: Record<string, unknown>, result: CursorReplayActivityBuildContext["result"], options: CursorReplayActivityBuildContext["options"]): string | undefined {
+	const path = getGenerateImagePath(args, result);
+	return path ? formatDisplayPath(path, options.cwd) : undefined;
+}
+
+function inferImageMimeType(path: string | undefined): string | undefined {
+	const lower = path?.toLowerCase();
+	if (!lower) return undefined;
+	if (lower.endsWith(".png")) return "image/png";
+	if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+	if (lower.endsWith(".gif")) return "image/gif";
+	if (lower.endsWith(".webp")) return "image/webp";
+	return undefined;
+}
+
+function getMcpContentText(entry: unknown): string | undefined {
+	const record = asRecord(entry);
+	const directText = getString(record, "text");
+	if (directText) return directText;
+	const nestedText = getRecord(record, "text");
+	return getString(nestedText, "text");
+}
+
+function getMcpResultPreview(result: CursorReplayActivityBuildContext["result"]): string | undefined {
+	if (result.status === "error") return undefined;
+	const value = asRecord(result.value);
+	const content = getArray(value, "content") ?? [];
+	for (const entry of content) {
+		const text = getMcpContentText(entry);
+		if (text) {
+			const line = firstNonEmptyLine(text);
+			if (line) return truncateArg(scrubSensitiveText(line), 120);
+		}
+	}
+	return undefined;
+}

package/src/cursor-replay-source-names.ts

@@ -0,0 +1,33 @@
+export const CURSOR_REPLAY_SOURCE_TOOL_NAMES = [
+	"read",
+	"grep",
+	"glob",
+	"ls",
+	"shell",
+	"edit",
+	"write",
+	"delete",
+	"readLints",
+	"updateTodos",
+	"createPlan",
+	"task",
+	"generateImage",
+	"mcp",
+	"semSearch",
+	"recordScreen",
+	"webSearch",
+	"webFetch",
+] as const;
+
+export type CursorReplaySourceToolName = (typeof CURSOR_REPLAY_SOURCE_TOOL_NAMES)[number];
+export type CursorReplayActivitySourceName = Exclude<CursorReplaySourceToolName, "generateImage">;
+
+const CURSOR_REPLAY_SOURCE_TOOL_NAME_SET: ReadonlySet<string> = new Set(CURSOR_REPLAY_SOURCE_TOOL_NAMES);
+
+export function isCursorReplaySourceToolName(name: string): name is CursorReplaySourceToolName {
+	return CURSOR_REPLAY_SOURCE_TOOL_NAME_SET.has(name);
+}
+
+export function isCursorReplayActivitySourceName(name: string): name is CursorReplayActivitySourceName {
+	return name !== "generateImage" && isCursorReplaySourceToolName(name);
+}

package/src/cursor-replay-summary-args.ts

@@ -0,0 +1,191 @@
+/**
+ * Typed replay summary argument payloads shared by the presentation registry
+ * and transcript replay builders.
+ */
+
+export interface CursorReplayActivitySummaryOverride {
+	activitySummary?: string;
+}
+
+export interface CursorReplayPathSummaryArgs extends CursorReplayActivitySummaryOverride {
+	path?: string;
+}
+
+export interface CursorReplayReadLintsSummaryArgs extends CursorReplayActivitySummaryOverride {
+	paths?: string[];
+	path?: string;
+	diagnosticCount?: number;
+}
+
+export interface CursorReplayTodoSummaryArgs extends CursorReplayActivitySummaryOverride {
+	totalCount?: number;
+	completedCount?: number;
+	inProgressCount?: number;
+	pendingCount?: number;
+}
+
+export interface CursorReplayPlanSummaryArgs extends CursorReplayTodoSummaryArgs {
+	planTitle?: string;
+}
+
+export interface CursorReplayTaskSummaryArgs extends CursorReplayActivitySummaryOverride {
+	description?: string;
+	preview?: string;
+}
+
+export interface CursorReplayGenerateImageSummaryArgs extends CursorReplayActivitySummaryOverride {
+	path?: string;
+	prompt?: string;
+}
+
+export interface CursorReplayMcpSummaryArgs extends CursorReplayActivitySummaryOverride {
+	toolName?: string;
+	preview?: string;
+}
+
+export interface CursorReplaySemSearchSummaryArgs extends CursorReplayActivitySummaryOverride {
+	query?: string;
+	targetDirectories?: string[];
+}
+
+export interface CursorReplayRecordScreenSummaryArgs extends CursorReplayActivitySummaryOverride {
+	mode?: string;
+	path?: string;
+	recordingDurationMs?: number;
+}
+
+export interface CursorReplayWebSearchSummaryArgs extends CursorReplayActivitySummaryOverride {
+	query?: string;
+}
+
+export interface CursorReplayWebFetchSummaryArgs extends CursorReplayActivitySummaryOverride {
+	url?: string;
+}
+
+export interface CursorReplayNeutralActivitySummaryArgs extends CursorReplayActivitySummaryOverride {
+	path?: string;
+	toolName?: string;
+	query?: string;
+	targetDirectories?: string[];
+}
+
+export type CursorReplaySummaryArgs =
+	| CursorReplayPathSummaryArgs
+	| CursorReplayReadLintsSummaryArgs
+	| CursorReplayTodoSummaryArgs
+	| CursorReplayPlanSummaryArgs
+	| CursorReplayTaskSummaryArgs
+	| CursorReplayGenerateImageSummaryArgs
+	| CursorReplayMcpSummaryArgs
+	| CursorReplaySemSearchSummaryArgs
+	| CursorReplayRecordScreenSummaryArgs
+	| CursorReplayWebSearchSummaryArgs
+	| CursorReplayWebFetchSummaryArgs
+	| CursorReplayNeutralActivitySummaryArgs;
+
+export function readCursorReplaySummaryString(
+	args: CursorReplaySummaryArgs | undefined,
+	key: string,
+): string | undefined {
+	const value = args?.[key as keyof CursorReplaySummaryArgs];
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function readCursorReplaySummaryNumber(
+	args: CursorReplaySummaryArgs | undefined,
+	key: string,
+): number | undefined {
+	const value = args?.[key as keyof CursorReplaySummaryArgs];
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function readCursorReplaySummaryStringArray(
+	args: CursorReplaySummaryArgs | undefined,
+	key: string,
+): string[] {
+	const value = args?.[key as keyof CursorReplaySummaryArgs];
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+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`;
+}
+
+export function summarizeReplayPath(args: CursorReplayPathSummaryArgs | undefined): string | undefined {
+	return readCursorReplaySummaryString(args, "path") ?? "unknown";
+}
+
+export function summarizeReplayReadLints(args: CursorReplayReadLintsSummaryArgs | undefined): string | undefined {
+	const paths = readCursorReplaySummaryStringArray(args, "paths");
+	const path = readCursorReplaySummaryString(args, "path");
+	const diagnosticCount = readCursorReplaySummaryNumber(args, "diagnosticCount");
+	const target = paths.length > 0 ? paths.join(", ") : path;
+	if (target && diagnosticCount !== undefined) {
+		return `${diagnosticCount} diagnostic${diagnosticCount === 1 ? "" : "s"} in ${target}`;
+	}
+	return target;
+}
+
+export function summarizeReplayTodoCount(args: CursorReplayTodoSummaryArgs | undefined): string | undefined {
+	const totalCount = readCursorReplaySummaryNumber(args, "totalCount");
+	const completedCount = readCursorReplaySummaryNumber(args, "completedCount");
+	const inProgressCount = readCursorReplaySummaryNumber(args, "inProgressCount");
+	const pendingCount = readCursorReplaySummaryNumber(args, "pendingCount");
+	if (totalCount !== undefined && completedCount !== undefined) {
+		const parts = [`${completedCount}/${totalCount} completed`];
+		if (inProgressCount && inProgressCount > 0) parts.push(`${inProgressCount} in progress`);
+		if (pendingCount && pendingCount > 0) parts.push(`${pendingCount} pending`);
+		return parts.join(", ");
+	}
+	return totalCount !== undefined ? `${totalCount} item${totalCount === 1 ? "" : "s"}` : undefined;
+}
+
+export function summarizeReplayPlan(args: CursorReplayPlanSummaryArgs | undefined): string | undefined {
+	return readCursorReplaySummaryString(args, "planTitle") ?? summarizeReplayTodoCount(args);
+}
+
+export function summarizeReplayTask(args: CursorReplayTaskSummaryArgs | undefined): string | undefined {
+	const description = readCursorReplaySummaryString(args, "description");
+	const preview = readCursorReplaySummaryString(args, "preview");
+	if (description && preview && preview !== description) return `${description}: ${preview}`;
+	return description ?? preview;
+}
+
+export function summarizeReplayMcp(args: CursorReplayMcpSummaryArgs | undefined): string | undefined {
+	const toolName = readCursorReplaySummaryString(args, "toolName") ?? "mcp";
+	const preview = readCursorReplaySummaryString(args, "preview");
+	return preview && preview !== toolName ? `${toolName} · ${preview}` : toolName;
+}
+
+export function summarizeReplayRecordScreen(args: CursorReplayRecordScreenSummaryArgs | undefined): string | undefined {
+	const path = readCursorReplaySummaryString(args, "path");
+	const duration = formatReplayRecordingDurationMs(readCursorReplaySummaryNumber(args, "recordingDurationMs"));
+	if (path && duration) return `${path} · ${duration}`;
+	return path ?? readCursorReplaySummaryString(args, "mode");
+}
+
+export function formatReplaySemSearchQuery(args: CursorReplaySemSearchSummaryArgs | undefined): string | undefined {
+	const query = readCursorReplaySummaryString(args, "query");
+	if (!query) return undefined;
+	const targetDirectories = readCursorReplaySummaryStringArray(args, "targetDirectories");
+	const dirHint =
+		targetDirectories.length > 0 ? ` (${targetDirectories.length} dir${targetDirectories.length === 1 ? "" : "s"})` : "";
+	return `${query}${dirHint}`;
+}
+
+export function summarizeReplayGenericActivity(args: CursorReplayNeutralActivitySummaryArgs | undefined): string | undefined {
+	return (
+		readCursorReplaySummaryString(args, "path")
+		?? readCursorReplaySummaryString(args, "toolName")
+		?? formatReplaySemSearchQuery(args)
+	);
+}
+
+export function withActivitySummaryFallback<T extends CursorReplayActivitySummaryOverride>(
+	buildSummary: (args: T | undefined) => string | undefined,
+): (args: T | undefined) => string | undefined {
+	return (args) => readCursorReplaySummaryString(args, "activitySummary") ?? buildSummary(args);
+}