pi-cursor-sdk 0.1.37 → 0.1.38

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Unreleased
 
+## 0.1.38 - 2026-06-08
+
+### Added
+
+- Add shared Cursor replay result readers so transcript formatting, native replay cards, and activity builders consume the same MCP-like content/diff/file-preview extraction logic.
+- Add a canonical Cursor model lifecycle sync helper for session start, before-agent-start, model selection, and turn start registration paths.
+- Add lazy Cursor provider registration so extension startup can register models and commands without importing the Cursor SDK runtime until the provider is invoked.
+- Add shared Cursor native tool-name and pi-tool-bridge environment helpers for provider/runtime registration code.
+
+### Changed
+
+- Centralize Cursor tool presentation ownership in the typed presentation registry, including labels, aliases, lifecycle titles, replay metadata, side-effect policies, and web-tool classification.
+- Consolidate Cursor session cwd, session file/id, generation, and scope-key handling in `cursor-session-scope`; remove the older cwd/message-offset helper split.
+- Simplify Cursor session-agent lifecycle invalidation on model select, compaction preparation, tree navigation, shutdown, and scope changes.
+- Refine Cursor tool lifecycle/replay display routing so completed replay cards, inactive traces, native replay activation, and duplicate step/delta completions share one display path.
+- Keep Cursor agents-context dedup and fallback-catalog warning registration model-scoped through the shared lifecycle helper.
+- Keep edit/write replay previews on the shared structured diff/file preview renderers while retaining SDK expanded-text fallback behavior.
+- Update maintainer docs and repo map entries for the new ownership boundaries.
+
+### Fixed
+
+- Clear started Cursor tool calls when a completed delta reports the same tool under a different SDK call id, preventing stale native replay edit starts from surfacing as `Cursor edit did not complete` after successful final text.
+- Keep Cursor agents-context dedup registration in a tracked module so clean package builds resolve `src/index.ts` imports.
+- Accept Windows-rendered absolute `README.md` paths in platform-smoke grep-card detection without weakening prompt false-positive checks.
+- Preserve Cursor skill activation and question-tool registration through lazy provider/runtime import boundaries.
+- Preserve fast local discovery incomplete-tool suppression while still surfacing aborts, SDK failures, and no-text incomplete runs.
+
 ## 0.1.37 - 2026-06-06
 
 ### Changed

package/docs/cursor-native-tool-replay.md

@@ -70,7 +70,7 @@ Edit and write activity replays through pi-facing `edit` and `write` cards only
 
 Source of truth for SDK tool names: `@cursor/sdk@1.0.17` conversation `ToolType` values and https://cursor.com/docs/sdk/typescript
 
-Implementation owners: `src/cursor-tool-presentation-registry.ts` (canonical names, labels, visibility, replay policy, bridge exclusions for internal replay wrappers, and display-spec key completeness), `src/cursor-transcript-tool-specs.ts` (registry-keyed `TOOL_DISPLAY_SPECS` formatters/builders), `src/cursor-native-tool-display-replay.ts` (replay card rendering derived from registry replay metadata), and `src/cursor-transcript-utils.ts` (`normalizeToolName()` delegating to the registry).
+Implementation owners: `src/cursor-tool-presentation-registry.ts` (canonical names, labels, visibility, replay policy, bridge exclusions for internal replay wrappers, alias normalization, and display-spec key completeness), `src/cursor-transcript-tool-specs.ts` (registry-keyed display implementations for transcript formatting and pi display builders), `src/cursor-native-tool-display-replay.ts` (replay card rendering derived from registry replay metadata), and `src/cursor-web-tool-activity.ts` (MCP/web alias remapping before display lookup).
 
 **Maintainer invariants — edit/write replay previews:** All colored diff rendering (native `edit` cards and `Cursor edit` activity fallbacks) flows through the single `formatCursorReplayDiff()` in `src/cursor-native-tool-display-replay.ts`. Activity write fallbacks with structured `fileContentAfterWrite` use the same `formatCursorReplayFilePreview()` path as native `write` cards. Structured `diffString` (and `diff`/`lines*`) or `fileContentAfterWrite` on `CursorReplay*Details` (including activity variants) is the source of truth for TUI preview coloring/highlighting. `expandedText` on activity details is for summary/expansion and as a fallback when the current SDK reports a unified diff only in text; it is never the primary preview source when structured fields are present. No parallel +/- coloring loops exist.
 
@@ -98,7 +98,7 @@ This matrix covers **Cursor native tool replay only**. It does not describe the
 | *(host/MCP alias)* `WebFetch` / `web_fetch` / similar | neutral activity | `cursor` | Collapsed label **Cursor web fetch**; display-only Cursor web access reported by the SDK, not an executable pi web tool |
 | _(no spec; future/unknown SDK name)_ | neutral activity | `cursor` | Collapsed label **Cursor** plus SDK tool name via `buildGenericPiToolDisplay()`; bounded fallback transcript only |
 
-**Unknown/future fallback path:** SDK tool names with no registry-backed `TOOL_DISPLAY_SPECS` entry (future or unknown types) use `buildGenericPiToolDisplay()` in `src/cursor-transcript-tool-specs.ts` with bounded `formatFallback()` content from `src/cursor-transcript-tool-formatters.ts`. Lookup uses `Object.hasOwn(TOOL_DISPLAY_SPECS, name)` so inherited object keys such as `constructor` or `toString` cannot accidentally match a registry spec. When native replay is enabled, those completions queue through neutral pi tool name `cursor` (not native pi `read`/`bash`/… cards). Collapsed labels read like **Cursor futureSemSearchWidget** (title `Cursor` plus the SDK tool name) with optional bounded `activitySummary` from scrubbed args/result lines. Errors keep `details.summary` undefined so unbounded raw errors do not leak into replay cards (#52). Known explicit specs still win over this path; real pi bridge tool names such as `edit` and `write` are not suppressed by internal replay-wrapper exclusions.
+**Unknown/future fallback path:** SDK tool names with no registry-backed display implementation entry (future or unknown types) use `buildGenericPiToolDisplay()` in `src/cursor-transcript-tool-specs.ts` with bounded `formatFallback()` content from `src/cursor-transcript-tool-formatters.ts`. Lookup uses `Object.hasOwn()` on the display implementation table so inherited object keys such as `constructor` or `toString` cannot accidentally match a registry spec. When native replay is enabled, those completions queue through neutral pi tool name `cursor` (not native pi `read`/`bash`/… cards). Collapsed labels read like **Cursor futureSemSearchWidget** (title `Cursor` plus the SDK tool name) with optional bounded `activitySummary` from scrubbed args/result lines. Errors keep `details.summary` undefined so unbounded raw errors do not leak into replay cards (#52). Known explicit specs still win over this path; real pi bridge tool names such as `edit` and `write` are not suppressed by internal replay-wrapper exclusions.
 
 **Replay detail disposition model:** `src/cursor-replay-tool-details.ts` stores replay card disposition separately from SDK source tool identity. Variants are `nativeEdit`, `nativeWrite`, `activity` (`sourceToolName` + display `title`), `generateImage`, and `genericFallback`. Path-only or notebook edit/write fallbacks produce `activity` details (neutral `cursor` cards) instead of structured edit/write variants with optional `title` escape hatches. Native edit/write cards use `nativeEdit` / `nativeWrite` only when pi-facing replay args satisfy the matching schema. The renderer dispatches on `variant` only.
 
@@ -106,7 +106,7 @@ Neutral activity rows use pi tool name `cursor` with `activityTitle` / `activity
 
 ## Runtime alias normalization
 
-Before lookup in `TOOL_DISPLAY_SPECS`, completed SDK tool names pass through `normalizeToolName()` in `src/cursor-transcript-utils.ts`. Documented aliases:
+Before display lookup, completed SDK tool names pass through `normalizeCursorToolName()` in `src/cursor-tool-presentation-registry.ts`; MCP web tool names are additionally remapped by `resolveTranscriptToolName()` in `src/cursor-web-tool-activity.ts`. Documented aliases:
 
 | Runtime alias | Canonical SDK name |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.37",
+	"version": "0.1.38",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

package/scripts/platform-smoke/card-detect.mjs

@@ -11,7 +11,7 @@ import { resolve } from "node:path";
 
 const CARD_PATTERNS = [
 	{ id: "read", pattern: /^\s*read (?:\.\/)?package\.json\s*$/i },
-	{ id: "grep", pattern: /^\s*grep \/pi-cursor-sdk\/ in README\.md\s*$/i },
+	{ id: "grep", pattern: /^\s*grep \/pi-cursor-sdk\/ in\s+(?:(?:\S+[\\/])?README\.md)\s*$/i },
 	{ id: "find", pattern: /^\s*find README\.md in\s+\S+/i },
 	{ id: "list", pattern: /^\s*(?:find \* in src|find src\/\* in \.|Get-ChildItem -Name \.\/src)\s*/i },
 	{ id: "shell-success", pattern: /^\s*cursor visual smoke\s*$/i },

package/src/context-window-cache.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { BUNDLED_CONTEXT_WINDOWS } from "./bundled-context-windows.js";
+import { asRecord } from "./cursor-record-utils.js";
 
 const CONTEXT_WINDOW_CACHE_FILE = "cursor-sdk-context-windows.json";
 let userContextWindowOverrideLoadCount = 0;
@@ -18,18 +19,16 @@ function isPositiveInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function parseContextWindowCacheFile(value: unknown): ContextWindowCacheFile | undefined {
-	if (!isRecord(value)) return undefined;
-	const { contextWindows } = value;
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const { contextWindows } = record;
 	if (contextWindows === undefined) return {};
-	if (!isRecord(contextWindows)) return undefined;
+	const contextWindowRecord = asRecord(contextWindows);
+	if (!contextWindowRecord) return undefined;
 	return {
 		contextWindows: Object.fromEntries(
-			Object.entries(contextWindows).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
+			Object.entries(contextWindowRecord).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
 		),
 	};
 }
@@ -68,12 +67,9 @@ export function getCachedContextWindow(modelId: string): number | undefined {
 }
 
 export function getCheckpointContextWindow(checkpoint: unknown): number | undefined {
-	if (!isRecord(checkpoint)) return undefined;
-	const { tokenDetails } = checkpoint;
-	if (!isRecord(tokenDetails)) return undefined;
-	const { maxTokens } = tokenDetails;
-	if (!isPositiveInteger(maxTokens)) return undefined;
-	return maxTokens;
+	const tokenDetails = asRecord(checkpoint)?.tokenDetails;
+	const maxTokens = asRecord(tokenDetails)?.maxTokens;
+	return isPositiveInteger(maxTokens) ? maxTokens : undefined;
 }
 
 export function saveCachedContextWindow(modelId: string, contextWindow: number): void {

package/src/context.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { SDKImage } from "@cursor/sdk";
-import { getCursorReplayPromptLabel } from "./cursor-tool-names.js";
+import { getCursorReplayPromptLabel } from "./cursor-tool-presentation-registry.js";
 
 export interface CursorPrompt {
 	text: string;

package/src/cursor-agent-message-web-tools.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "@cursor/sdk";
-import { asRecord, getArray, getString, stringifyUnknown } from "./cursor-transcript-utils.js";
+import { asRecord, getArray, getString } from "./cursor-record-utils.js";
+import { stringifyUnknown } from "./cursor-transcript-utils.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 
 const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;

package/src/cursor-agents-context-registration.ts

@@ -0,0 +1,18 @@
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+
+export type CursorAgentsContextExtensionApi = CursorModelLifecycleExtensionApi;
+
+export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
+	registerCursorModelLifecycle(pi, {
+		beforeAgentStart: async (event, ctx) => {
+			const { resolveCursorFacingSystemPrompt } = await import("./cursor-agents-context.js");
+			const resolved = resolveCursorFacingSystemPrompt(
+				event.systemPrompt,
+				ctx.model,
+				event.systemPromptOptions,
+			);
+			if (resolved === event.systemPrompt) return undefined;
+			return { systemPrompt: resolved };
+		},
+	});
+}

package/src/cursor-agents-context.ts

@@ -1,20 +1,17 @@
 import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
 	BuildSystemPromptOptions,
-	ExtensionAPI,
 	ExtensionContext,
-	ExtensionHandler,
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import {
-	cursorSettingSourcesLoadProjectAgentsRules,
-	cursorSettingSourcesLoadUserAgentsRules,
+	cursorSettingSourcesIncludes,
 	getEffectiveCursorSettingSources,
+	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
 import type { SettingSource } from "@cursor/sdk";
+export { registerCursorAgentsContextDedup, type CursorAgentsContextExtensionApi } from "./cursor-agents-context-registration.js";
 
 export const CURSOR_PRESERVE_PI_AGENTS_MD_ENV = "PI_CURSOR_PRESERVE_PI_AGENTS_MD";
 
@@ -49,18 +46,24 @@ export function getAgentsContextFileBaseName(filePath: string): string {
 	return normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
 }
 
+function isPiAgentDirContextFilePath(
+	filePath: string,
+	fileName: "agents.md" | "claude.md",
+	agentDir: string = getAgentDir(),
+): boolean {
+	const normalized = normalizeContextPath(filePath);
+	const expectedPath = `${normalizeDirPath(agentDir)}/${fileName}`;
+	return normalized.toLowerCase() === expectedPath.toLowerCase();
+}
+
 /** Actual pi agent dir `AGENTS.md` — overlaps Cursor `user` setting source (global agent instructions). */
 export function isPiAgentDirAgentsMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
-	const normalized = normalizeContextPath(filePath);
-	const agentsMdPath = `${normalizeDirPath(agentDir)}/agents.md`;
-	return normalized.toLowerCase() === agentsMdPath.toLowerCase();
+	return isPiAgentDirContextFilePath(filePath, "agents.md", agentDir);
 }
 
 /** Actual pi agent dir `CLAUDE.md` — kept because Cursor user rules use `~/.claude/CLAUDE.md`. */
 export function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
-	const normalized = normalizeContextPath(filePath);
-	const claudeMdPath = `${normalizeDirPath(agentDir)}/claude.md`;
-	return normalized.toLowerCase() === claudeMdPath.toLowerCase();
+	return isPiAgentDirContextFilePath(filePath, "claude.md", agentDir);
 }
 
 /**
@@ -87,9 +90,9 @@ export function shouldRemovePiAgentsContextFile(
 ): boolean {
 	switch (classifyContextFileOverlap(file.path, agentDir)) {
 		case "cursor-user-agents":
-			return cursorSettingSourcesLoadUserAgentsRules(settingSources);
+			return cursorSettingSourcesIncludes(settingSources, "user");
 		case "cursor-project-rules":
-			return cursorSettingSourcesLoadProjectAgentsRules(settingSources);
+			return cursorSettingSourcesIncludes(settingSources, "project");
 		default:
 			return false;
 	}
@@ -153,24 +156,12 @@ export function resolveCursorFacingSystemPrompt(
 ): string {
 	if (!systemPromptOptions) return systemPrompt;
 	const contextFiles = systemPromptOptions.contextFiles ?? [];
-	const settingSources = getEffectiveCursorSettingSources(settingSourcesRaw);
+	const settingSources =
+		settingSourcesRaw === undefined
+			? getEffectiveCursorSettingSources()
+			: resolveCursorSettingSources(settingSourcesRaw);
 	if (!shouldSuppressPiAgentsContext(model, contextFiles, settingSources, agentDir)) {
 		return systemPrompt;
 	}
 	return removePiAgentsContextFromSystemPrompt(systemPrompt, contextFiles, settingSources, agentDir);
 }
-
-type CursorAgentsContextExtensionApi = Pick<ExtensionAPI, "on">;
-
-export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
-	const handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult> = (event, ctx) => {
-		const resolved = resolveCursorFacingSystemPrompt(
-			event.systemPrompt,
-			ctx.model,
-			event.systemPromptOptions,
-		);
-		if (resolved === event.systemPrompt) return;
-		return { systemPrompt: resolved };
-	};
-	pi.on("before_agent_start", handler);
-}

package/src/cursor-edit-diff.ts

@@ -1,8 +1,10 @@
+import { asRecord } from "./cursor-record-utils.js";
+
 const CURSOR_EDIT_DIFF_FIELD_ORDER = ["diffString", "diff", "unifiedDiff", "patch"] as const;
 
 export function resolveCursorEditDiff(source: unknown): string | undefined {
-	if (!source || typeof source !== "object") return undefined;
-	const record = source as Record<string, unknown>;
+	const record = asRecord(source);
+	if (!record) return undefined;
 	for (const key of CURSOR_EDIT_DIFF_FIELD_ORDER) {
 		const value = record[key];
 		if (typeof value === "string" && value.length > 0) return value;

package/src/cursor-fallback-warning.ts

@@ -0,0 +1,22 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import type { CursorModelFallbackIssue } from "./model-discovery.js";
+
+export type CursorFallbackWarningExtensionApi = CursorModelLifecycleExtensionApi;
+
+export function registerCursorFallbackIssueWarning(
+	pi: CursorFallbackWarningExtensionApi,
+	issue: CursorModelFallbackIssue,
+): void {
+	const warnedSessionScopeKeys = new Set<string>();
+
+	registerCursorModelLifecycle(pi, (ctx: ExtensionContext) => {
+		if (!isCursorModel(ctx.model) || !ctx.hasUI) return;
+		const scopeKey = getCursorSessionScopeKey();
+		if (warnedSessionScopeKeys.has(scopeKey)) return;
+		warnedSessionScopeKeys.add(scopeKey);
+		ctx.ui.notify(issue.message, "warning");
+	});
+}

package/src/cursor-incomplete-tool-visibility.ts

@@ -1,4 +1,4 @@
-import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME } from "./cursor-tool-names.js";
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME, getCursorToolActivityTitle } from "./cursor-tool-presentation-registry.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import {
@@ -10,7 +10,8 @@ import {
 	parseCursorReplayToolDetails,
 	resolveIncompleteReplayActivitySourceToolName,
 } from "./cursor-replay-tool-details.js";
-import { truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
 
 export type IncompleteCursorToolDiscardReason = DiscardedIncompleteStartedToolCallReason;
@@ -59,11 +60,6 @@ export function resolveIncompleteCursorToolVisibility(
 	return "emit";
 }
 
-function buildGenericIncompleteActivityTitle(displayName: string): string {
-	if (!displayName || displayName === "unknown") return "Cursor tool";
-	return `Cursor ${truncateArg(displayName)}`;
-}
-
 export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToolDiscardReason): string {
 	switch (reason) {
 		case DISCARDED_INCOMPLETE_TOOL_CALL_REASON:
@@ -79,7 +75,7 @@ export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToo
 
 export function getIncompleteCursorToolActivityTitle(toolCall: unknown): string {
 	const visibility = classifyCursorToolVisibility(toolCall);
-	return visibility.incompleteTitle ?? buildGenericIncompleteActivityTitle(visibility.displayName);
+	return visibility.incompleteTitle ?? getCursorToolActivityTitle(visibility.displayName);
 }
 
 export function buildIncompleteCursorToolDisplay(
@@ -124,8 +120,7 @@ export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): s
 			formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
 		return `${truncateCursorDisplayLine(parsed.title)}: ${truncateCursorDisplayLine(summary)}\n`;
 	}
-	const details = display.result.details;
-	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
+	const detailRecord = asRecord(display.result.details);
 	const argsRecord = display.args;
 	const title =
 		(typeof detailRecord?.title === "string" && detailRecord.title.trim()) ||

package/src/cursor-live-run-coordinator.ts

@@ -7,7 +7,7 @@ import {
 	type CursorLiveRunAccountingState,
 	type CursorLiveToolResultConsumption,
 } from "./cursor-live-run-accounting.js";
-import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display.js";
+import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display-state.js";
 import type { CursorPiBridgeToolRequest, CursorPiToolBridgeRun } from "./cursor-pi-tool-bridge.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";

package/src/cursor-mcp-timeout-override.ts

@@ -151,8 +151,6 @@ export function restoreCursorMcpToolTimeoutOverride(): void {
 	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
 
-export const restoreCursorMcpToolTimeoutOverrideForTests = restoreCursorMcpToolTimeoutOverride;
-
 export const cursorMcpToolTimeoutOverrideDefaults = {
 	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,

package/src/cursor-model-lifecycle.ts

@@ -0,0 +1,72 @@
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	ExtensionContext,
+	ExtensionHandler,
+	SessionStartEvent,
+	TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+export type CursorModelLifecycleContext = ExtensionContext;
+
+type CursorModelSelectEvent = { model: ExtensionContext["model"] };
+
+type CursorModelLifecycleSyncHandler = (ctx: CursorModelLifecycleContext) => Promise<void> | void;
+type CursorModelSessionStartHandler = ExtensionHandler<SessionStartEvent>;
+type CursorModelSelectHandler = (event: CursorModelSelectEvent, ctx: CursorModelLifecycleContext) => Promise<void> | void;
+type CursorModelTurnStartHandler = ExtensionHandler<TurnStartEvent>;
+type CursorModelBeforeAgentStartHandler = ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>;
+
+export interface CursorModelLifecycleExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: CursorModelBeforeAgentStartHandler): void;
+	on(event: "model_select", handler: (event: CursorModelSelectEvent, ctx: ExtensionContext) => Promise<void> | void): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+}
+
+export interface CursorModelLifecycleHandlers {
+	sessionStart?: CursorModelSessionStartHandler;
+	modelSelect?: CursorModelSelectHandler;
+	turnStart?: CursorModelTurnStartHandler;
+	sync?: CursorModelLifecycleSyncHandler;
+	beforeAgentStart?: CursorModelBeforeAgentStartHandler;
+}
+
+function normalizeLifecycleHandlers(
+	handlerOrHandlers: CursorModelLifecycleSyncHandler | CursorModelLifecycleHandlers,
+): CursorModelLifecycleHandlers {
+	return typeof handlerOrHandlers === "function" ? { sync: handlerOrHandlers } : handlerOrHandlers;
+}
+
+export function registerCursorModelLifecycle(
+	pi: CursorModelLifecycleExtensionApi,
+	handlerOrHandlers: CursorModelLifecycleSyncHandler | CursorModelLifecycleHandlers,
+): void {
+	const handlers = normalizeLifecycleHandlers(handlerOrHandlers);
+	const sync = handlers.sync;
+	if (handlers.sessionStart || sync) {
+		pi.on("session_start", async (event, ctx) => {
+			await handlers.sessionStart?.(event, ctx);
+			await sync?.(ctx);
+		});
+	}
+	if (handlers.modelSelect || sync) {
+		pi.on("model_select", async (event, ctx) => {
+			const effectiveCtx = { ...ctx, model: event.model };
+			await handlers.modelSelect?.(event, effectiveCtx);
+			await sync?.(effectiveCtx);
+		});
+	}
+	if (handlers.turnStart || sync) {
+		pi.on("turn_start", async (event, ctx) => {
+			await handlers.turnStart?.(event, ctx);
+			await sync?.(ctx);
+		});
+	}
+	if (handlers.beforeAgentStart || sync) {
+		pi.on("before_agent_start", async (event, ctx) => {
+			await sync?.(ctx);
+			return await handlers.beforeAgentStart?.(event, ctx);
+		});
+	}
+}

package/src/cursor-native-replay-routing.ts

@@ -1,4 +1,4 @@
-import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { canRenderCursorToolNatively } from "./cursor-native-tool-display-state.js";
 import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import type { Context } from "@earendil-works/pi-ai";
 

package/src/cursor-native-replay-trace.ts

@@ -1,4 +1,4 @@
-import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 

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

@@ -1,12 +1,12 @@
-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 {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
 	NATIVE_CURSOR_TOOL_NAMES,
-	registerNativeCursorTool,
 	type NativeCursorToolName,
-} from "./cursor-native-tool-display-tools.js";
+} from "./cursor-native-tool-names.js";
 import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
 import {
 	isCursorNativeToolDisplayRequested,
 	isCursorNativeToolRegistrationRequested,
@@ -15,7 +15,7 @@ import {
 	registeredNativeToolNames,
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
-import { isCursorReplayToolName } from "./cursor-tool-names.js";
+import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
 
 export const CURSOR_CORE_PI_REPLAY_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
 const CORE_PI_TOOL_NAMES = new Set<string>(CURSOR_CORE_PI_REPLAY_TOOL_NAMES);
@@ -27,12 +27,7 @@ function isCursorCorePiReplayToolName(toolName: string): toolName is (typeof CUR
 type CursorNativeToolActivationApi = Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">;
 type CursorNativeToolRegistryApi = CursorNativeToolActivationApi & Pick<ExtensionAPI, "getAllTools" | "registerTool">;
 
-export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi {
-	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;
-}
+export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi, CursorModelLifecycleExtensionApi {}
 
 function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: NativeCursorToolName): boolean {
 	const existingTool = pi.getAllTools().find((tool) => tool.name === toolName);
@@ -43,11 +38,12 @@ type NativeRegistrationContext = Pick<ExtensionContext, "mode" | "model"> & {
 	ui: Pick<ExtensionContext["ui"], "notify">;
 };
 
-function registerNativeCursorToolsFromSet(
+async function registerNativeCursorToolsFromSet(
 	pi: CursorNativeToolRegistryApi,
 	toolNames: readonly NativeCursorToolName[],
-): NativeCursorToolName[] {
+): Promise<NativeCursorToolName[]> {
 	const newlySkippedToolNames: NativeCursorToolName[] = [];
+	let registerNativeCursorTool: ((pi: CursorNativeToolRegistryApi, toolName: NativeCursorToolName) => void) | undefined;
 	for (const toolName of toolNames) {
 		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
 		if (hasNonBuiltinTool(pi, toolName)) {
@@ -55,6 +51,7 @@ function registerNativeCursorToolsFromSet(
 			newlySkippedToolNames.push(toolName);
 			continue;
 		}
+		registerNativeCursorTool ??= (await import("./cursor-native-tool-display-tools.js")).registerNativeCursorTool;
 		registerNativeCursorTool(pi, toolName);
 		registeredNativeToolNames.add(toolName);
 	}
@@ -97,7 +94,7 @@ export function syncRegisteredNativeCursorToolsForModel(
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
 	if (!isCursorNativeToolRegistrationRequested()) {
 		registeredNativeToolNames.clear();
 		skippedNativeToolNames.clear();
@@ -107,31 +104,22 @@ function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryA
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
-		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
-		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
+		...(await registerNativeCursorToolsFromSet(pi, nonCoreToolNames)),
+		...(await registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES)),
 	];
 	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
 }
 
-function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
 	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
-		ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+		await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	}
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
-	pi.on("session_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("before_agent_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("turn_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("model_select", (event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, { ...ctx, model: event.model });
+	registerCursorModelLifecycle(pi, async (ctx) => {
+		await ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 }
 

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

@@ -1,9 +1,10 @@
 import { readFileSync, statSync } from "node:fs";
-import { basename, extname } from "node:path";
+import { basename } from "node:path";
 import { getLanguageFromPath, highlightCode, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
+import { inferImageMimeType } from "./cursor-tool-result-display-readers.js";
 import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-transcript-utils.js";
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
@@ -17,7 +18,6 @@ import {
 	type CursorReplayActivityDetails,
 	type CursorReplayToolDetails,
 	type CursorReplayNativeWriteDetails,
-	isCursorReplayNativeEditDetails,
 	isCursorReplayGenerateImageDetails,
 	isCursorReplayActivityDetails,
 	parseCursorReplayToolDetails,
@@ -49,22 +49,6 @@ type CursorReplayRenderCall = NonNullable<ToolDefinition<typeof cursorReplayTool
 type CursorReplayRenderResult = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderResult"]>;
 export type CursorReplayRenderTheme = Parameters<CursorReplayRenderCall>[1];
 
-function inferImageMimeTypeFromPath(path: string | undefined): string | undefined {
-	switch (extname(path ?? "").toLowerCase()) {
-		case ".png":
-			return "image/png";
-		case ".jpg":
-		case ".jpeg":
-			return "image/jpeg";
-		case ".gif":
-			return "image/gif";
-		case ".webp":
-			return "image/webp";
-		default:
-			return undefined;
-	}
-}
-
 function readImageFileForReplay(path: string | undefined): string | undefined {
 	if (!path) return undefined;
 	try {
@@ -464,7 +448,7 @@ function renderExpandableCursorReplayResult(
 	}
 	if (details.imagePath && !isError && context.showImages) {
 		const imageData = readImageFileForReplay(details.imagePath);
-		const mimeType = details.imageMimeType ?? inferImageMimeTypeFromPath(details.imagePath);
+		const mimeType = details.imageMimeType ?? inferImageMimeType(details.imagePath);
 		if (imageData && mimeType) return buildImageReplayComponent(rendered, imageData, mimeType, basename(details.imagePath ?? "generated-image"), theme);
 	}
 	return new Text(rendered, 0, 0);
@@ -485,7 +469,6 @@ function renderCursorReplayEditResult(
 function renderCursorReplayWriteResult(
 	details: CursorReplayNativeWriteDetails,
 	result: Parameters<CursorReplayRenderResult>[0],
-	options: Parameters<CursorReplayRenderResult>[1],
 	theme: Parameters<CursorReplayRenderResult>[2],
 ): Component {
 	const text = firstContentText(result);
@@ -532,7 +515,7 @@ function renderCursorReplayDetails(
 		case "nativeEdit":
 			return renderCursorReplayEditResult(details, options, theme);
 		case "nativeWrite":
-			return renderCursorReplayWriteResult(details, result, options, theme);
+			return renderCursorReplayWriteResult(details, result, theme);
 		case "generateImage":
 			return renderCursorGenerateImageResult(details, result, options, theme, context, isError);
 		case "activity":

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

@@ -1,4 +1,4 @@
-import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { parseOptionalEnvBoolean } from "./cursor-env-boolean.js";
 
 export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {