pi-cursor-sdk 0.1.62 → 0.3.6

package/dist/cursor-question-tool.js

@@ -0,0 +1,194 @@
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { arePiToolsDisabled } from "./cursor-active-tools.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
+export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
+export const CURSOR_ASK_QUESTION_ENV = "PI_CURSOR_ASK_QUESTION";
+export function resolveCursorAskQuestionEnabled(env = process.env) {
+    return parseEnvBoolean(env[CURSOR_ASK_QUESTION_ENV], true);
+}
+/** Package-namespaced event while `cursor_ask_question` awaits pi UI input. */
+export const CURSOR_ASK_QUESTION_BLOCKED_EVENT = "pi-cursor-sdk:ask-question:blocked";
+const QuestionOptionSchema = Type.Union([
+    Type.String(),
+    Type.Object({
+        label: Type.String({ description: "User-facing option label" }),
+        value: Type.Optional(Type.String({ description: "Optional value returned to Cursor; defaults to label" })),
+        description: Type.Optional(Type.String({ description: "Optional helper text shown by compatible pi UIs" })),
+    }),
+]);
+const QuestionSchema = Type.Object({
+    id: Type.Optional(Type.String({ description: "Stable question identifier" })),
+    question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+    prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+    options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+    choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+    allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+});
+const CursorAskQuestionParamsSchema = Type.Object({
+    question: Type.Optional(Type.String({ description: "Question to ask the user" })),
+    prompt: Type.Optional(Type.String({ description: "Alias for question" })),
+    options: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Choices the user can select" })),
+    choices: Type.Optional(Type.Array(QuestionOptionSchema, { description: "Alias for options" })),
+    allowCustom: Type.Optional(Type.Boolean({ description: "Allow a typed answer in addition to listed options; defaults to true" })),
+    questions: Type.Optional(Type.Array(QuestionSchema, { description: "Ask multiple questions sequentially" })),
+});
+function normalizeOption(option, index) {
+    if (typeof option === "string") {
+        const trimmed = option.trim();
+        return trimmed ? { label: trimmed, value: trimmed } : undefined;
+    }
+    const label = option.label?.trim() || option.value?.trim() || `Option ${index + 1}`;
+    return {
+        label,
+        value: option.value?.trim() || label,
+        ...(option.description?.trim() ? { description: option.description.trim() } : {}),
+    };
+}
+function normalizeOptions(options) {
+    return (options ?? []).map(normalizeOption).filter((option) => option !== undefined);
+}
+function normalizeQuestion(raw, index) {
+    const question = raw.question?.trim() || raw.prompt?.trim();
+    if (!question)
+        return undefined;
+    return {
+        id: raw.id?.trim() || `question_${index + 1}`,
+        question,
+        options: normalizeOptions(raw.options ?? raw.choices),
+        allowCustom: raw.allowCustom !== false,
+    };
+}
+function normalizeQuestions(params) {
+    const rawQuestions = Array.isArray(params.questions) && params.questions.length > 0 ? params.questions : [params];
+    return rawQuestions.map(normalizeQuestion).filter((question) => question !== undefined);
+}
+function summarizeAnswers(answers) {
+    if (answers.length === 0)
+        return "No answer was collected.";
+    if (answers.length === 1) {
+        const [answer] = answers;
+        return answer.cancelled || answer.answer === null ? "User cancelled the question." : `User answered: ${answer.answer}`;
+    }
+    return [
+        "User answered:",
+        ...answers.map((answer) => {
+            const value = answer.cancelled || answer.answer === null ? "cancelled" : answer.answer;
+            return `- ${answer.id}: ${value}`;
+        }),
+    ].join("\n");
+}
+function buildDetails(questions, answers, uiAvailable) {
+    return {
+        questions,
+        answers,
+        uiAvailable,
+        cancelled: answers.some((answer) => answer.cancelled),
+    };
+}
+async function askOneQuestion(question, ctx) {
+    if (question.options.length > 0) {
+        const labels = question.options.map((option) => option.description ? `${option.label} — ${option.description}` : option.label);
+        const customLabel = "Type a custom answer";
+        const choices = question.allowCustom ? [...labels, customLabel] : labels;
+        const selected = await ctx.ui.select(question.question, choices);
+        if (!selected) {
+            return { id: question.id, question: question.question, answer: null, wasCustom: false, cancelled: true };
+        }
+        if (selected === customLabel) {
+            const customAnswer = await ctx.ui.input(question.question, "Type your answer");
+            const trimmed = customAnswer?.trim();
+            return trimmed
+                ? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+                : { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+        }
+        const selectedIndex = labels.indexOf(selected);
+        const selectedOption = selectedIndex >= 0 ? question.options[selectedIndex] : undefined;
+        const answer = selectedOption?.label ?? selected;
+        return {
+            id: question.id,
+            question: question.question,
+            answer,
+            value: selectedOption?.value ?? answer,
+            wasCustom: false,
+            cancelled: false,
+        };
+    }
+    const answer = await ctx.ui.input(question.question, "Type your answer");
+    const trimmed = answer?.trim();
+    return trimmed
+        ? { id: question.id, question: question.question, answer: trimmed, value: trimmed, wasCustom: true, cancelled: false }
+        : { id: question.id, question: question.question, answer: null, wasCustom: true, cancelled: true };
+}
+function syncCursorQuestionToolForModel(pi, model) {
+    const activeToolNames = new Set(pi.getActiveTools());
+    const shouldBeActive = !arePiToolsDisabled(pi) && isCursorModel(model) && resolveCursorPiToolBridgeEnabled();
+    const alreadyActive = activeToolNames.has(CURSOR_ASK_QUESTION_TOOL_NAME);
+    if (shouldBeActive === alreadyActive)
+        return;
+    if (shouldBeActive) {
+        activeToolNames.add(CURSOR_ASK_QUESTION_TOOL_NAME);
+    }
+    else {
+        activeToolNames.delete(CURSOR_ASK_QUESTION_TOOL_NAME);
+    }
+    pi.setActiveTools([...activeToolNames]);
+}
+function emitCursorAskQuestionBlockedEvent(pi, payload) {
+    pi.events.emit(CURSOR_ASK_QUESTION_BLOCKED_EVENT, payload);
+}
+export function registerCursorQuestionTool(pi) {
+    if (!resolveCursorAskQuestionEnabled())
+        return;
+    pi.registerTool({
+        name: CURSOR_ASK_QUESTION_TOOL_NAME,
+        label: "Cursor question",
+        description: "Ask the user a clarifying question from Cursor. Use when user preferences materially affect the next step; provide options when possible.",
+        promptSnippet: "Ask the user a clarifying question through pi UI when material choices affect Cursor's next step",
+        executionMode: "sequential",
+        parameters: CursorAskQuestionParamsSchema,
+        promptGuidelines: [
+            "Use cursor_ask_question only when running a Cursor model and user input would materially change the plan, scope, platform, or implementation path.",
+            "Prefer cursor_ask_question with 2-4 concrete options instead of guessing when Cursor plan mode needs user choices.",
+        ],
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const questions = normalizeQuestions(params);
+            if (questions.length === 0) {
+                throw new Error("No valid question was provided.");
+            }
+            if (!ctx.hasUI) {
+                throw new Error("Cannot ask the user because pi UI is unavailable. Make a reasonable default choice and state the assumption before proceeding.");
+            }
+            // Emit a package-namespaced blocked signal while the questionnaire
+            // awaits input so consumers (e.g. Herdr) can map it to blocked/working.
+            emitCursorAskQuestionBlockedEvent(pi, { active: true });
+            try {
+                const answers = [];
+                for (const question of questions) {
+                    const answer = await askOneQuestion(question, ctx);
+                    answers.push(answer);
+                    if (answer.cancelled)
+                        break;
+                }
+                return {
+                    content: [{ type: "text", text: summarizeAnswers(answers) }],
+                    details: buildDetails(questions, answers, true),
+                };
+            }
+            finally {
+                emitCursorAskQuestionBlockedEvent(pi, { active: false });
+            }
+        },
+        renderCall(args, theme) {
+            const questions = normalizeQuestions(args);
+            const label = questions[0]?.question ?? "Ask the user";
+            return new Text(theme.fg("toolTitle", theme.bold("cursor question ")) + theme.fg("muted", label), 0, 0);
+        },
+    });
+    registerCursorModelLifecycle(pi, (ctx) => {
+        syncCursorQuestionToolForModel(pi, ctx.model);
+    });
+}

package/dist/cursor-record-utils.js

@@ -0,0 +1,61 @@
+export function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+export function getField(value, field) {
+    return asRecord(value)?.[field];
+}
+export function hasUsableText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function getString(record, key) {
+    const value = record?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+export function getNumber(record, key) {
+    const value = record?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function getBoolean(record, key) {
+    const value = record?.[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+export function getRecord(record, key) {
+    return asRecord(record?.[key]);
+}
+export function getArray(record, key) {
+    const value = record?.[key];
+    return Array.isArray(value) ? value : undefined;
+}
+export function firstNonEmptyString(...values) {
+    for (const value of values) {
+        const trimmed = value?.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+export function stringifyUnknown(value, options = {}) {
+    if (value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value, null, options.pretty ? 2 : undefined) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function getFirstStringByKeys(record, keys, options) {
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value !== "string")
+            continue;
+        if (options?.nonEmpty && !value)
+            continue;
+        return value;
+    }
+    return undefined;
+}

package/dist/cursor-replay-activity-builders.js

@@ -0,0 +1,114 @@
+import { asRecord, getArray, getNumber, getString } from "./cursor-record-utils.js";
+import { firstNonEmptyLine, formatDisplayPath, truncateArg } from "./cursor-transcript-utils.js";
+import { collectTaskText, getGenerateImageDisplayPath, getGenerateImagePath, readMcpDisplayResult, getReadLintDiagnostics, getReadLintPaths, getTodoItems, getTodoTotalCount, inferImageMimeType, } from "./cursor-tool-result-display-readers.js";
+import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
+import { formatCursorTaskAgentId, formatCursorTaskKind, getCursorTaskDescription, getCursorTaskPresentationMode, readCursorTaskMetadata } from "./cursor-task-presentation.js";
+export function buildDeleteReplaySummaryArgs({ args, options }) {
+    const displayPath = typeof args.path === "string" ? formatDisplayPath(args.path, options.cwd) : undefined;
+    return displayPath ? { path: displayPath } : {};
+}
+export function buildDeleteReplayDetailFields({ args, result, options }) {
+    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 buildReadLintsReplaySummaryArgs({ args, result, options, }) {
+    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, result) {
+    const todos = getTodoItems(args, result);
+    const totalCount = getTodoTotalCount(args, result, todos);
+    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 }) {
+    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, options }) {
+    const description = getCursorTaskDescription(args, result.value);
+    const preview = firstNonEmptyLine(collectTaskText(result, options));
+    const metadata = readCursorTaskMetadata(args, result.value);
+    const displayAgentId = formatCursorTaskAgentId(metadata.agentId);
+    const includeMetadata = getCursorTaskPresentationMode() === "subagent-meta";
+    return {
+        description: truncateArg(description),
+        ...(preview ? { preview: truncateArg(preview) } : {}),
+        ...(includeMetadata && metadata.subagentName ? { subagentName: truncateArg(metadata.subagentName) } : {}),
+        ...(includeMetadata && metadata.subagentKind ? { subagentKind: truncateArg(formatCursorTaskKind(metadata.subagentKind) ?? metadata.subagentKind) } : {}),
+        ...(includeMetadata && metadata.model ? { model: truncateArg(metadata.model) } : {}),
+        ...(includeMetadata && displayAgentId ? { agentId: truncateArg(displayAgentId) } : {}),
+        ...(includeMetadata && metadata.isBackground === true ? { isBackground: true } : {}),
+    };
+}
+export function buildGenerateImageReplaySummaryArgs({ args, result, options, }) {
+    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 }) {
+    const toolName = getString(args, "toolName") ?? "mcp";
+    const preview = readMcpDisplayResult(result).preview;
+    return {
+        toolName: truncateArg(toolName),
+        ...(preview ? { preview } : {}),
+    };
+}
+export function buildSemSearchReplaySummaryArgs({ args }) {
+    const query = getString(args, "query") ?? "semantic search";
+    const targetDirectories = (getArray(args, "targetDirectories") ?? []).filter((entry) => typeof entry === "string");
+    return {
+        query: truncateArg(query),
+        ...(targetDirectories.length > 0 ? { targetDirectories } : {}),
+    };
+}
+export function buildRecordScreenReplaySummaryArgs({ args, result, options, }) {
+    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 }) {
+    const query = extractWebSearchQuery(args);
+    return query ? { query: truncateArg(query) } : {};
+}
+export function buildWebFetchReplaySummaryArgs({ args }) {
+    const url = extractWebFetchTarget(args);
+    return url ? { url: truncateArg(url) } : {};
+}
+export function buildGenerateImageReplayDetailFields(context, contentText) {
+    const { args, result, options } = context;
+    const imagePath = getGenerateImagePath(args, result);
+    const imageDisplayPath = getGenerateImageDisplayPath(args, result, options);
+    return {
+        imagePath,
+        imageDisplayPath,
+        imageMimeType: inferImageMimeType(imagePath),
+        expandedText: contentText,
+    };
+}

package/dist/cursor-replay-source-names.js

@@ -0,0 +1,27 @@
+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",
+];
+const CURSOR_REPLAY_SOURCE_TOOL_NAME_SET = new Set(CURSOR_REPLAY_SOURCE_TOOL_NAMES);
+export function isCursorReplaySourceToolName(name) {
+    return CURSOR_REPLAY_SOURCE_TOOL_NAME_SET.has(name);
+}
+export function isCursorReplayActivitySourceName(name) {
+    return name !== "generateImage" && isCursorReplaySourceToolName(name);
+}

package/dist/cursor-replay-summary-args.js

@@ -0,0 +1,105 @@
+/**
+ * Typed replay summary argument payloads shared by the presentation registry
+ * and transcript replay builders.
+ */
+export function readCursorReplaySummaryString(args, key) {
+    const value = args?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export function readCursorReplaySummaryNumber(args, key) {
+    const value = args?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function readCursorReplaySummaryStringArray(args, key) {
+    const value = args?.[key];
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function formatReplayRecordingDurationMs(ms) {
+    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) {
+    return readCursorReplaySummaryString(args, "path") ?? "unknown";
+}
+export function summarizeReplayReadLints(args) {
+    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) {
+    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) {
+    return readCursorReplaySummaryString(args, "planTitle") ?? summarizeReplayTodoCount(args);
+}
+export function summarizeReplayTask(args) {
+    const description = readCursorReplaySummaryString(args, "description");
+    const preview = readCursorReplaySummaryString(args, "preview");
+    const subagentName = readCursorReplaySummaryString(args, "subagentName");
+    const subagentKind = readCursorReplaySummaryString(args, "subagentKind");
+    const model = readCursorReplaySummaryString(args, "model");
+    const agentId = readCursorReplaySummaryString(args, "agentId");
+    const metadataParts = [
+        subagentKind,
+        model,
+        agentId ? `ID: ${agentId}` : undefined,
+        args?.isBackground === true ? "backgrounded" : undefined,
+    ].filter((part) => Boolean(part));
+    const subjectParts = [description].filter((part) => Boolean(part));
+    const subject = subjectParts.length > 0 ? subjectParts.join(" · ") : undefined;
+    const head = metadataParts.length > 0 ? [subject, ...metadataParts].filter(Boolean).join(" · ") : subject;
+    if (metadataParts.length > 0)
+        return head;
+    if (head && preview && preview !== description && preview !== subagentName)
+        return `${head}: ${preview}`;
+    return head ?? preview;
+}
+export function summarizeReplayMcp(args) {
+    const toolName = readCursorReplaySummaryString(args, "toolName") ?? "mcp";
+    const preview = readCursorReplaySummaryString(args, "preview");
+    return preview && preview !== toolName ? `${toolName} · ${preview}` : toolName;
+}
+export function summarizeReplayRecordScreen(args) {
+    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) {
+    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) {
+    return (readCursorReplaySummaryString(args, "path")
+        ?? readCursorReplaySummaryString(args, "toolName")
+        ?? formatReplaySemSearchQuery(args));
+}
+export function withActivitySummaryFallback(buildSummary) {
+    return (args) => readCursorReplaySummaryString(args, "activitySummary") ?? buildSummary(args);
+}

package/dist/cursor-replay-tool-details.js

@@ -0,0 +1,167 @@
+import { asRecord, getBoolean, getNumber, getString } from "./cursor-record-utils.js";
+import { isCursorReplayActivitySourceName } from "./cursor-replay-source-names.js";
+/**
+ * Sentinel source tool name for activity cards whose SDK name is not a known registry entry.
+ * Display identity lives in `title` and replay args.
+ */
+export const CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME = "unregisteredActivity";
+function readSourceToolName(record) {
+    const sourceToolName = getString(record, "sourceToolName");
+    return sourceToolName?.trim() ? sourceToolName.trim() : undefined;
+}
+function readVariant(record) {
+    const variant = getString(record, "variant");
+    return variant?.trim() ? variant.trim() : undefined;
+}
+function parseCursorReplayNativeEditDetails(record) {
+    return {
+        variant: "nativeEdit",
+        path: getString(record, "path"),
+        linesAdded: getNumber(record, "linesAdded"),
+        linesRemoved: getNumber(record, "linesRemoved"),
+        diffString: getString(record, "diffString"),
+        diff: getString(record, "diff"),
+        firstChangedLine: getNumber(record, "firstChangedLine"),
+        summary: getString(record, "summary"),
+        expandedText: getString(record, "expandedText"),
+    };
+}
+function parseCursorReplayNativeWriteDetails(record) {
+    return {
+        variant: "nativeWrite",
+        path: getString(record, "path"),
+        linesCreated: getNumber(record, "linesCreated"),
+        fileSize: getNumber(record, "fileSize"),
+        fileContentAfterWrite: getString(record, "fileContentAfterWrite"),
+        expandedText: getString(record, "expandedText"),
+        summary: getString(record, "summary"),
+    };
+}
+function parseCursorReplayGenerateImageDetails(record) {
+    const collapseDetailsByDefault = getBoolean(record, "collapseDetailsByDefault");
+    return {
+        variant: "generateImage",
+        imagePath: getString(record, "imagePath"),
+        imageDisplayPath: getString(record, "imageDisplayPath"),
+        imageMimeType: getString(record, "imageMimeType"),
+        summary: getString(record, "summary"),
+        expandedText: getString(record, "expandedText"),
+        ...(collapseDetailsByDefault !== undefined ? { collapseDetailsByDefault } : {}),
+    };
+}
+function parseCursorReplayActivityDetails(record, sourceToolName, title) {
+    return {
+        variant: "activity",
+        sourceToolName,
+        title,
+        summary: getString(record, "summary"),
+        expandedText: getString(record, "expandedText"),
+        collapseDetailsByDefault: getBoolean(record, "collapseDetailsByDefault"),
+        path: getString(record, "path"),
+        fileSize: getNumber(record, "fileSize"),
+        diffString: getString(record, "diffString"),
+        diff: getString(record, "diff"),
+        linesAdded: getNumber(record, "linesAdded"),
+        linesRemoved: getNumber(record, "linesRemoved"),
+        fileContentAfterWrite: getString(record, "fileContentAfterWrite"),
+    };
+}
+function brandCursorReplayUnknownSourceToolName(sourceToolName) {
+    return sourceToolName;
+}
+function parseCursorReplayGenericFallbackDetails(record, sourceToolName) {
+    return {
+        variant: "genericFallback",
+        sourceToolName: brandCursorReplayUnknownSourceToolName(sourceToolName),
+        summary: getString(record, "summary"),
+        expandedText: getString(record, "expandedText"),
+    };
+}
+function isCursorReplayActivitySourceToolName(name) {
+    if (name === CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME)
+        return true;
+    if (name === "generateImage")
+        return false;
+    return isCursorReplayActivitySourceName(name);
+}
+function resolveParseActivitySourceToolName(sourceToolName) {
+    return isCursorReplayActivitySourceToolName(sourceToolName)
+        ? sourceToolName
+        : CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME;
+}
+/** Maps incomplete or non-activity replay source names onto activity-card source tool names. */
+export function resolveIncompleteReplayActivitySourceToolName(sourceToolName) {
+    if (sourceToolName === "generateImage")
+        return CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME;
+    return resolveParseActivitySourceToolName(sourceToolName);
+}
+function parseActivityVariantDetails(record) {
+    const title = getString(record, "title")?.trim();
+    if (!title)
+        return undefined;
+    return parseCursorReplayActivityDetails(record, resolveParseActivitySourceToolName(readSourceToolName(record) ?? CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME), title);
+}
+export function parseCursorReplayToolDetails(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    switch (readVariant(record)) {
+        case "nativeEdit":
+            return parseCursorReplayNativeEditDetails(record);
+        case "nativeWrite":
+            return parseCursorReplayNativeWriteDetails(record);
+        case "generateImage":
+            return parseCursorReplayGenerateImageDetails(record);
+        case "activity":
+            return parseActivityVariantDetails(record);
+        case "genericFallback":
+            return parseCursorReplayGenericFallbackDetails(record, readSourceToolName(record) ?? "tool");
+        default:
+            return undefined;
+    }
+}
+export function assembleCursorReplayActivityDetails(sourceToolName, title, fields, contentText, isError, activitySummary) {
+    const summary = isError ? fields.summary : (fields.summary ?? activitySummary);
+    return {
+        variant: "activity",
+        sourceToolName,
+        title,
+        summary,
+        expandedText: fields.expandedText ?? contentText,
+        ...(fields.collapseDetailsByDefault !== undefined ? { collapseDetailsByDefault: fields.collapseDetailsByDefault } : {}),
+        ...(fields.path !== undefined ? { path: fields.path } : {}),
+        ...(fields.fileSize !== undefined ? { fileSize: fields.fileSize } : {}),
+        ...(fields.diffString !== undefined ? { diffString: fields.diffString } : {}),
+        ...(fields.diff !== undefined ? { diff: fields.diff } : {}),
+        ...(fields.linesAdded !== undefined ? { linesAdded: fields.linesAdded } : {}),
+        ...(fields.linesRemoved !== undefined ? { linesRemoved: fields.linesRemoved } : {}),
+        ...(fields.fileContentAfterWrite !== undefined ? { fileContentAfterWrite: fields.fileContentAfterWrite } : {}),
+    };
+}
+export const CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE = "Cursor image generation";
+export function assembleCursorReplayGenerateImageDetails(fields, contentText, isError, activitySummary) {
+    const summary = isError ? fields.summary : (fields.summary ?? activitySummary);
+    return {
+        variant: "generateImage",
+        imagePath: fields.imagePath,
+        imageDisplayPath: fields.imageDisplayPath,
+        imageMimeType: fields.imageMimeType,
+        summary,
+        expandedText: fields.expandedText ?? contentText,
+    };
+}
+export function isCursorReplayNativeEditDetails(details) {
+    return details.variant === "nativeEdit";
+}
+export function isCursorReplayNativeWriteDetails(details) {
+    return details.variant === "nativeWrite";
+}
+export function isCursorReplayGenerateImageDetails(details) {
+    return details.variant === "generateImage";
+}
+export function isCursorReplayActivityDetails(details) {
+    return details.variant === "activity";
+}
+export function isCursorReplayGenericFallbackDetails(details) {
+    return details.variant === "genericFallback";
+}