pi-cursor-sdk 0.1.37 → 0.1.38

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

@@ -1,7 +1,7 @@
 import type { SendOptions } from "@cursor/sdk";
+import { countCursorAgentMessages } from "./cursor-agent-message-web-tools.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
-import { getCursorAgentMessageOffset } from "./cursor-provider-turn-message-offset.js";
 import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type {
 	CursorProviderTurnRunnerParams,
@@ -41,7 +41,12 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 	try {
 		abortRegistration?.signal.addEventListener("abort", abortListener, { once: true });
 		throwIfAborted();
-		const cursorAgentMessageOffset = await getCursorAgentMessageOffset(agent.agentId, cwd, sdkEventDebug);
+		let cursorAgentMessageOffset: number | undefined;
+		try {
+			cursorAgentMessageOffset = await countCursorAgentMessages(agent.agentId, cwd);
+		} catch (error) {
+			sdkEventDebug?.recordError("cursor_agent_message_count", error);
+		}
 		throwIfAborted();
 		sdkEventDebug?.recordSendMeta({
 			mode: meta.sendPlan.mode,

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

@@ -61,7 +61,7 @@ export type CursorProviderTurnRuntime = DirectCursorProviderTurnRuntime | LiveCu
  * Send, finalize, and cleanup phases receive this immutable object instead of
  * keeping parallel liveRun/turnCoordinator/resource bags in sync by convention.
  */
-export interface PreparedCursorProviderTurn {
+export interface CursorProviderTurnPrepareResult {
 	agent: SDKAgent;
 	cwd: string;
 	payload: CursorProviderTurnSendPayload;
@@ -74,8 +74,6 @@ export interface PreparedCursorProviderTurn {
 	runtime: CursorProviderTurnRuntime;
 }
 
-export type CursorProviderTurnPrepareResult = PreparedCursorProviderTurn;
-
 export interface CursorProviderTurnSend {
 	run: Awaited<ReturnType<SDKAgent["send"]>>;
 	cursorAgentMessageOffset: number | undefined;

package/src/cursor-provider.ts

@@ -8,6 +8,7 @@ import {
 	type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
 import {
+	cursorLiveRuns,
 	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
 	getPendingCursorLiveRun,
 	hasTrailingUserMessagesAfterToolResults,
@@ -15,12 +16,12 @@ import {
 	resetCursorNativeReplayIdleDisposeMs,
 	setCursorNativeReplayIdleDisposeMs,
 } from "./cursor-provider-live-run-drain.js";
-import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { disposeAllSessionCursorAgents } from "./cursor-session-agent.js";
 import { attachCursorSdkEventDebugPiStreamTap, type CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
-import { CursorProviderTurnRunner, resolveCursorApiKey } from "./cursor-provider-turn-runner.js";
+import { resolveCursorApiKey } from "./cursor-api-key.js";
+import { CursorProviderTurnRunner } from "./cursor-provider-turn-runner.js";
 
 function makeInitialMessage(model: Model<Api>): AssistantMessage {
 	return {

package/src/cursor-question-tool.ts

@@ -1,8 +1,9 @@
-import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { isCursorModel } from "./cursor-model.js";
-import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
 
 export const CURSOR_ASK_QUESTION_TOOL_NAME = "cursor_ask_question";
 
@@ -35,12 +36,7 @@ interface CursorQuestionDetails {
 	cancelled: boolean;
 }
 
-interface CursorQuestionToolExtensionApi extends Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> {
-	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
-	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent>): void;
-	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
-	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
-}
+interface CursorQuestionToolExtensionApi extends Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools">, CursorModelLifecycleExtensionApi {}
 
 type RawQuestionOption = string | { label?: string; value?: string; description?: string };
 
@@ -232,16 +228,7 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 		},
 	});
 
-	pi.on("session_start", (_event, ctx) => {
-		syncCursorQuestionToolForModel(pi, ctx.model);
-	});
-	pi.on("before_agent_start", (_event, ctx) => {
+	registerCursorModelLifecycle(pi, (ctx) => {
 		syncCursorQuestionToolForModel(pi, ctx.model);
 	});
-	pi.on("turn_start", (_event, ctx) => {
-		syncCursorQuestionToolForModel(pi, ctx.model);
-	});
-	pi.on("model_select", (event) => {
-		syncCursorQuestionToolForModel(pi, event.model);
-	});
 }

package/src/cursor-record-utils.ts

@@ -10,6 +10,48 @@ export function hasUsableText(value: string | undefined): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
 
+export function getString(record: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = record?.[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+export function getNumber(record: Record<string, unknown> | undefined, key: string): number | undefined {
+	const value = record?.[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function getBoolean(record: Record<string, unknown> | undefined, key: string): boolean | undefined {
+	const value = record?.[key];
+	return typeof value === "boolean" ? value : undefined;
+}
+
+export function getRecord(record: Record<string, unknown> | undefined, key: string): Record<string, unknown> | undefined {
+	return asRecord(record?.[key]);
+}
+
+export function getArray(record: Record<string, unknown> | undefined, key: string): unknown[] | undefined {
+	const value = record?.[key];
+	return Array.isArray(value) ? value : undefined;
+}
+
+export function firstNonEmptyString(...values: Array<string | undefined>): string | undefined {
+	for (const value of values) {
+		const trimmed = value?.trim();
+		if (trimmed) return trimmed;
+	}
+	return undefined;
+}
+
+export function stringifyUnknown(value: unknown, options: { pretty?: boolean } = {}): string {
+	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: Record<string, unknown> | undefined,
 	keys: readonly string[],

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

@@ -1,4 +1,3 @@
-import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import type {
 	CursorReplayGenerateImageSummaryArgs,
 	CursorReplayMcpSummaryArgs,
@@ -13,16 +12,20 @@ import type {
 	CursorReplayWebSearchSummaryArgs,
 } from "./cursor-replay-summary-args.js";
 import type { CursorReplayGenerateImageDetailFields } from "./cursor-replay-tool-details.js";
-import { asRecord } from "./cursor-record-utils.js";
+import { asRecord, getArray, getNumber, getString } from "./cursor-record-utils.js";
+import { firstNonEmptyLine, formatDisplayPath, truncateArg } from "./cursor-transcript-utils.js";
 import {
-	firstNonEmptyLine,
-	formatDisplayPath,
-	getArray,
-	getNumber,
-	getRecord,
-	getString,
-	truncateArg,
-} from "./cursor-transcript-utils.js";
+	collectTaskText,
+	getGenerateImageDisplayPath,
+	getGenerateImagePath,
+	readMcpDisplayResult,
+	getReadLintDiagnostics,
+	getReadLintPaths,
+	getTaskDescription,
+	getTodoItems,
+	getTodoTotalCount,
+	inferImageMimeType,
+} from "./cursor-tool-result-display-readers.js";
 import { extractWebFetchTarget, extractWebSearchQuery } from "./cursor-web-tool-args.js";
 
 export interface CursorReplayActivityBuildContext {
@@ -48,14 +51,6 @@ export function buildDeleteReplayDetailFields({ args, result, options }: CursorR
 	};
 }
 
-export function buildEmptyReplayDetailFields(): Record<string, never> {
-	return {};
-}
-
-export function buildCollapsedReplayDetailFields(): { collapseDetailsByDefault: true } {
-	return { collapseDetailsByDefault: true };
-}
-
 export function buildReadLintsReplaySummaryArgs({
 	args,
 	result,
@@ -75,7 +70,7 @@ export function buildTodoReplaySummaryArgs(
 	result: CursorReplayActivityBuildContext["result"],
 ): CursorReplayTodoSummaryArgs {
 	const todos = getTodoItems(args, result);
-	const totalCount = getNumber(asRecord(result.value), "totalCount") ?? getNumber(args, "totalCount") ?? todos.length;
+	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;
@@ -94,7 +89,7 @@ export function buildCreatePlanReplaySummaryArgs({ args, result }: CursorReplayA
 }
 
 export function buildTaskReplaySummaryArgs({ args, result }: CursorReplayActivityBuildContext): CursorReplayTaskSummaryArgs {
-	const description = getString(args, "description") ?? getString(asRecord(result.value), "description") ?? "task";
+	const description = getTaskDescription(args, result);
 	const preview = firstNonEmptyLine(collectTaskText(result));
 	return {
 		description: truncateArg(description),
@@ -117,7 +112,7 @@ export function buildGenerateImageReplaySummaryArgs({
 
 export function buildMcpReplaySummaryArgs({ args, result }: CursorReplayActivityBuildContext): CursorReplayMcpSummaryArgs {
 	const toolName = getString(args, "toolName") ?? "mcp";
-	const preview = getMcpResultPreview(result);
+	const preview = readMcpDisplayResult(result).preview;
 	return {
 		toolName: truncateArg(toolName),
 		...(preview ? { preview } : {}),
@@ -173,104 +168,3 @@ export function buildGenerateImageReplayDetailFields(
 		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-tool-details.ts

@@ -1,3 +1,4 @@
+import { asRecord, getBoolean, getNumber, getString } from "./cursor-record-utils.js";
 import { isCursorReplayActivitySourceName, type CursorReplayActivitySourceName } from "./cursor-replay-source-names.js";
 
 /** Replay detail variants keyed by replay card disposition, not SDK source tool alone. */
@@ -111,70 +112,51 @@ export type CursorReplayGenerateImageDetailFields = Pick<
 	"summary" | "expandedText" | "imagePath" | "imageDisplayPath" | "imageMimeType"
 >;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function readOptionalString(record: Record<string, unknown>, key: string): string | undefined {
-	const value = record[key];
-	return typeof value === "string" ? value : undefined;
-}
-
-function readOptionalNumber(record: Record<string, unknown>, key: string): number | undefined {
-	const value = record[key];
-	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
-function readOptionalBoolean(record: Record<string, unknown>, key: string): boolean | undefined {
-	const value = record[key];
-	return typeof value === "boolean" ? value : undefined;
-}
-
 function readSourceToolName(record: Record<string, unknown>): string | undefined {
-	const sourceToolName = readOptionalString(record, "sourceToolName");
+	const sourceToolName = getString(record, "sourceToolName");
 	return sourceToolName?.trim() ? sourceToolName.trim() : undefined;
 }
 
 function readVariant(record: Record<string, unknown>): string | undefined {
-	const variant = readOptionalString(record, "variant");
+	const variant = getString(record, "variant");
 	return variant?.trim() ? variant.trim() : undefined;
 }
 
 function parseCursorReplayNativeEditDetails(record: Record<string, unknown>): CursorReplayNativeEditDetails {
 	return {
 		variant: "nativeEdit",
-		path: readOptionalString(record, "path"),
-		linesAdded: readOptionalNumber(record, "linesAdded"),
-		linesRemoved: readOptionalNumber(record, "linesRemoved"),
-		diffString: readOptionalString(record, "diffString"),
-		diff: readOptionalString(record, "diff"),
-		firstChangedLine: readOptionalNumber(record, "firstChangedLine"),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
+		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: Record<string, unknown>): CursorReplayNativeWriteDetails {
 	return {
 		variant: "nativeWrite",
-		path: readOptionalString(record, "path"),
-		linesCreated: readOptionalNumber(record, "linesCreated"),
-		fileSize: readOptionalNumber(record, "fileSize"),
-		fileContentAfterWrite: readOptionalString(record, "fileContentAfterWrite"),
-		expandedText: readOptionalString(record, "expandedText"),
-		summary: readOptionalString(record, "summary"),
+		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: Record<string, unknown>): CursorReplayGenerateImageDetails {
-	const collapseDetailsByDefault = readOptionalBoolean(record, "collapseDetailsByDefault");
+	const collapseDetailsByDefault = getBoolean(record, "collapseDetailsByDefault");
 	return {
 		variant: "generateImage",
-		imagePath: readOptionalString(record, "imagePath"),
-		imageDisplayPath: readOptionalString(record, "imageDisplayPath"),
-		imageMimeType: readOptionalString(record, "imageMimeType"),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
+		imagePath: getString(record, "imagePath"),
+		imageDisplayPath: getString(record, "imageDisplayPath"),
+		imageMimeType: getString(record, "imageMimeType"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
 		...(collapseDetailsByDefault !== undefined ? { collapseDetailsByDefault } : {}),
 	};
 }
@@ -188,16 +170,16 @@ function parseCursorReplayActivityDetails(
 		variant: "activity",
 		sourceToolName,
 		title,
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
-		collapseDetailsByDefault: readOptionalBoolean(record, "collapseDetailsByDefault"),
-		path: readOptionalString(record, "path"),
-		fileSize: readOptionalNumber(record, "fileSize"),
-		diffString: readOptionalString(record, "diffString"),
-		diff: readOptionalString(record, "diff"),
-		linesAdded: readOptionalNumber(record, "linesAdded"),
-		linesRemoved: readOptionalNumber(record, "linesRemoved"),
-		fileContentAfterWrite: readOptionalString(record, "fileContentAfterWrite"),
+		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"),
 	};
 }
 
@@ -212,8 +194,8 @@ function parseCursorReplayGenericFallbackDetails(
 	return {
 		variant: "genericFallback",
 		sourceToolName: brandCursorReplayUnknownSourceToolName(sourceToolName),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
 	};
 }
 
@@ -237,10 +219,8 @@ export function resolveIncompleteReplayActivitySourceToolName(
 	return resolveParseActivitySourceToolName(sourceToolName);
 }
 
-type CursorReplayVariantParser = (record: Record<string, unknown>) => CursorReplayToolDetails | undefined;
-
 function parseActivityVariantDetails(record: Record<string, unknown>): CursorReplayActivityDetails | undefined {
-	const title = readOptionalString(record, "title")?.trim();
+	const title = getString(record, "title")?.trim();
 	if (!title) return undefined;
 	return parseCursorReplayActivityDetails(
 		record,
@@ -249,31 +229,23 @@ function parseActivityVariantDetails(record: Record<string, unknown>): CursorRep
 	);
 }
 
-const CURRENT_REPLAY_VARIANT_PARSERS: Readonly<Record<CursorReplayToolDetailsVariant, CursorReplayVariantParser>> = {
-	nativeEdit: parseCursorReplayNativeEditDetails,
-	nativeWrite: parseCursorReplayNativeWriteDetails,
-	generateImage: parseCursorReplayGenerateImageDetails,
-	activity: parseActivityVariantDetails,
-	genericFallback: (record) => parseCursorReplayGenericFallbackDetails(record, readSourceToolName(record) ?? "tool"),
-};
-
 export function parseCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	if (!isRecord(value)) return undefined;
-	const variant = readVariant(value);
-	if (!variant) return undefined;
-	return CURRENT_REPLAY_VARIANT_PARSERS[variant as CursorReplayToolDetailsVariant]?.(value);
-}
-
-export function buildCursorReplayNativeEditDetails(
-	fields: Omit<CursorReplayNativeEditDetails, "variant">,
-): CursorReplayNativeEditDetails {
-	return { variant: "nativeEdit", ...fields };
-}
-
-export function buildCursorReplayNativeWriteDetails(
-	fields: Omit<CursorReplayNativeWriteDetails, "variant">,
-): CursorReplayNativeWriteDetails {
-	return { variant: "nativeWrite", ...fields };
+	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(

package/src/cursor-sdk-event-debug.ts

@@ -7,6 +7,7 @@ import type { CursorPiToolBridgeDiagnosticEvent } from "./cursor-pi-tool-bridge-
 import { serializeCursorPiToolBridgeDiagnostic } from "./cursor-pi-tool-bridge-diagnostics.js";
 import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge-types.js";
 import type { CursorLiveQueuedEvent } from "./cursor-live-run-coordinator.js";
+import { asRecord } from "./cursor-record-utils.js";
 import { getCursorSessionFile } from "./cursor-session-scope.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import {
@@ -93,11 +94,10 @@ interface CursorSdkRunLike {
 }
 
 function eventType(value: unknown): string {
-	if (value && typeof value === "object") {
-		if ("type" in value && typeof value.type === "string") return value.type;
-		if ("event" in value && typeof value.event === "string") return value.event;
-		if ("kind" in value && typeof value.kind === "string") return value.kind;
-	}
+	const record = asRecord(value);
+	if (typeof record?.type === "string") return record.type;
+	if (typeof record?.event === "string") return record.event;
+	if (typeof record?.kind === "string") return record.kind;
 	return "unknown";
 }
 
@@ -106,7 +106,7 @@ function resolveCursorSdkEventDebugStderrEnabled(env: Record<string, string | un
 }
 
 function isNodeErrorWithCode(error: unknown, code: string): boolean {
-	return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === code;
+	return asRecord(error)?.code === code;
 }
 
 function snapshotCursorSdkEventDebugRecord(record: unknown): unknown {

package/src/cursor-sensitive-text.ts

@@ -1,3 +1,4 @@
+import { asRecord } from "./cursor-record-utils.js";
 import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 /** Provider-facing wrapper; canonical scrubbing lives in shared/cursor-sensitive-text.mjs. */
 import { scrubSensitiveText as scrubSensitiveTextJs } from "../shared/cursor-sensitive-text.mjs";
@@ -9,10 +10,9 @@ export function scrubSensitiveText(text: string, apiKey?: string): string {
 function scrubDisplayValue(value: unknown, apiKey?: string): unknown {
 	if (typeof value === "string") return scrubSensitiveText(value, apiKey);
 	if (Array.isArray(value)) return value.map((entry) => scrubDisplayValue(entry, apiKey));
-	if (value && typeof value === "object") {
-		return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
-	}
-	return value;
+	const record = asRecord(value);
+	if (!record) return value;
+	return Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
 }
 
 export function scrubPiToolDisplay(display: CursorPiToolDisplay, apiKey?: string): CursorPiToolDisplay {

package/src/cursor-session-agent-lifecycle.ts

@@ -0,0 +1,47 @@
+import type {
+	ExtensionHandler,
+	SessionBeforeTreeEvent,
+	SessionCompactEvent,
+	SessionShutdownEvent,
+	SessionTreeEvent,
+} from "@earendil-works/pi-coding-agent";
+import { onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+
+export interface CursorSessionAgentLifecycleExtensionApi {
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "model_select", handler: () => Promise<void> | void): void;
+}
+
+export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
+	onCursorSessionScopeKeyChange(async (previousScopeKey) => {
+		const { disposeSessionCursorAgent } = await import("./cursor-session-agent.js");
+		await disposeSessionCursorAgent(previousScopeKey);
+	});
+	pi.on("session_shutdown", async (event) => {
+		const { disposeSessionCursorAgent, resetSessionCursorAgent } = await import("./cursor-session-agent.js");
+		if (event.reason === "reload") {
+			await resetSessionCursorAgent();
+			return;
+		}
+		await disposeSessionCursorAgent();
+	});
+	pi.on("session_compact", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+	pi.on("session_before_tree", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+	pi.on("session_tree", async () => {
+		const { resetSessionCursorAgent } = await import("./cursor-session-agent.js");
+		await resetSessionCursorAgent();
+	});
+	pi.on("model_select", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+}