pi-cursor-sdk 0.1.17 → 0.1.19

package/src/cursor-agents-context.ts

@@ -0,0 +1,176 @@
+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,
+	getEffectiveCursorSettingSources,
+} from "./cursor-setting-sources.js";
+import type { SettingSource } from "@cursor/sdk";
+
+export const CURSOR_PRESERVE_PI_AGENTS_MD_ENV = "PI_CURSOR_PRESERVE_PI_AGENTS_MD";
+
+/** Opening tag prefix pi `buildSystemPrompt()` uses for each context file (path attribute only). */
+export const PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX = '<project_instructions path="';
+const PI_PROJECT_INSTRUCTIONS_CLOSE = "</project_instructions>";
+const PI_PROJECT_CONTEXT_OPEN = "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+const PI_PROJECT_CONTEXT_CLOSE = "</project_context>\n";
+
+function normalizeContextPath(filePath: string): string {
+	return filePath.replace(/\\/g, "/");
+}
+
+function normalizeDirPath(dirPath: string): string {
+	const normalized = normalizeContextPath(dirPath).replace(/\/+$/, "");
+	return normalized || "/";
+}
+
+export type PiAgentsContextFile = {
+	path: string;
+	content: string;
+};
+
+/** Overlap classes for pi context files that Cursor also loads via `settingSources`. */
+export type PiAgentsContextOverlap = "none" | "cursor-user-agents" | "cursor-project-rules";
+
+/** Pi context filenames that can overlap Cursor project/user ambient rules. */
+const CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES = new Set(["agents.md", "claude.md"]);
+
+export function getAgentsContextFileBaseName(filePath: string): string {
+	const normalized = normalizeContextPath(filePath);
+	return normalized.slice(normalized.lastIndexOf("/") + 1).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();
+}
+
+/** 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();
+}
+
+/**
+ * Classify whether a pi-loaded context file overlaps Cursor ambient rules.
+ * Project/repo `AGENTS.md` and `CLAUDE.md` overlap Cursor `project` sources.
+ * Only the actual pi agent dir `AGENTS.md` overlaps Cursor `user`; agent-dir `CLAUDE.md` is kept
+ * because Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir path.
+ */
+export function classifyContextFileOverlap(
+	filePath: string,
+	agentDir: string = getAgentDir(),
+): PiAgentsContextOverlap {
+	const base = getAgentsContextFileBaseName(filePath);
+	if (!CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES.has(base)) return "none";
+	if (base === "agents.md" && isPiAgentDirAgentsMdPath(filePath, agentDir)) return "cursor-user-agents";
+	if (base === "claude.md" && isPiAgentDirClaudeMdPath(filePath, agentDir)) return "none";
+	return "cursor-project-rules";
+}
+
+export function shouldRemovePiAgentsContextFile(
+	file: PiAgentsContextFile,
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): boolean {
+	switch (classifyContextFileOverlap(file.path, agentDir)) {
+		case "cursor-user-agents":
+			return cursorSettingSourcesLoadUserAgentsRules(settingSources);
+		case "cursor-project-rules":
+			return cursorSettingSourcesLoadProjectAgentsRules(settingSources);
+		default:
+			return false;
+	}
+}
+
+export function shouldSuppressPiAgentsContext(
+	model: ExtensionContext["model"],
+	contextFiles: readonly PiAgentsContextFile[],
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): boolean {
+	if (!isCursorModel(model)) return false;
+	if (parseEnvBoolean(process.env[CURSOR_PRESERVE_PI_AGENTS_MD_ENV], false)) return false;
+	if (contextFiles.length === 0) return false;
+	return contextFiles.some((file) => shouldRemovePiAgentsContextFile(file, settingSources, agentDir));
+}
+
+/** Exact pi `buildSystemPrompt()` serialization for one context file block (including trailing blank line). */
+export function serializePiProjectInstructionsBlock(file: PiAgentsContextFile): string {
+	return `${PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX}${file.path}">\n${file.content}\n${PI_PROJECT_INSTRUCTIONS_CLOSE}\n\n`;
+}
+
+/** Exact pi `buildSystemPrompt()` serialization for the full project context section. */
+export function serializePiProjectContextSection(contextFiles: readonly PiAgentsContextFile[]): string {
+	if (contextFiles.length === 0) return "";
+	return `${PI_PROJECT_CONTEXT_OPEN}${contextFiles.map(serializePiProjectInstructionsBlock).join("")}${PI_PROJECT_CONTEXT_CLOSE}`;
+}
+
+/** Remove pi context blocks that overlap Cursor setting sources. */
+export function removePiAgentsContextFromSystemPrompt(
+	systemPrompt: string,
+	contextFiles: readonly PiAgentsContextFile[],
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): string {
+	const retainedContextFiles: PiAgentsContextFile[] = [];
+	let removedAny = false;
+	for (const file of contextFiles) {
+		if (shouldRemovePiAgentsContextFile(file, settingSources, agentDir)) {
+			removedAny = true;
+			continue;
+		}
+		retainedContextFiles.push(file);
+	}
+	if (!removedAny) return systemPrompt;
+
+	const originalSection = serializePiProjectContextSection(contextFiles);
+	const start = systemPrompt.indexOf(originalSection);
+	if (start < 0) return systemPrompt;
+
+	const replacementSection = serializePiProjectContextSection(retainedContextFiles);
+	return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+}
+
+export function resolveCursorFacingSystemPrompt(
+	systemPrompt: string,
+	model: ExtensionContext["model"],
+	systemPromptOptions?: BuildSystemPromptOptions,
+	settingSourcesRaw?: string,
+	agentDir?: string,
+): string {
+	if (!systemPromptOptions) return systemPrompt;
+	const contextFiles = systemPromptOptions.contextFiles ?? [];
+	const settingSources = getEffectiveCursorSettingSources(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-context-tools.ts

@@ -0,0 +1,6 @@
+import type { Context } from "@earendil-works/pi-ai";
+
+/** Tool names from the provider context snapshot at stream start (not live pi.getActiveTools()). */
+export function getActiveContextToolNames(context: Context): ReadonlySet<string> | undefined {
+	return context.tools ? new Set(context.tools.map((tool) => tool.name)) : undefined;
+}

package/src/cursor-display-text.ts

@@ -0,0 +1,10 @@
+/** Canonical single-line sanitization and truncation for Cursor replay/trace display. */
+export function sanitizeCursorDisplayLine(value: string): string {
+	return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export function truncateCursorDisplayLine(value: string, maxLength = 240): string {
+	const sanitized = sanitizeCursorDisplayLine(value);
+	if (sanitized.length <= maxLength) return sanitized;
+	return `${sanitized.slice(0, maxLength - 1)}…`;
+}

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

@@ -0,0 +1,118 @@
+import {
+	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
+	getCursorReplayDisplayLabel,
+	type CursorReplayLegacyToolName,
+} from "./cursor-tool-names.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import {
+	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+	type DiscardedIncompleteStartedToolCallReason,
+} from "./cursor-sdk-event-debug.js";
+import { getToolArgs, getToolName, normalizeToolName, truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+import { resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
+
+export type IncompleteCursorToolDiscardReason = DiscardedIncompleteStartedToolCallReason;
+
+const INCOMPLETE_TITLE_KEYS: Partial<Record<string, CursorReplayLegacyToolName>> = {
+	task: "cursor_task",
+	mcp: "cursor_mcp",
+	generateimage: "cursor_generate_image",
+	recordscreen: "cursor_record_screen",
+	semsearch: "cursor_sem_search",
+	websearch: "cursor_web_search",
+	webfetch: "cursor_web_fetch",
+	createplan: "cursor_create_plan",
+	updatetodos: "cursor_update_todos",
+	readlints: "cursor_read_lints",
+	delete: "cursor_delete",
+	edit: "cursor_edit",
+	write: "cursor_write",
+};
+
+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:
+			return "missing completion";
+		case "abort":
+			return "aborted";
+		case "sdk-failure":
+			return "SDK run failed";
+		case "run-drain":
+			return "run ended during drain";
+	}
+}
+
+export function getIncompleteCursorToolActivityTitle(toolCall: unknown): string {
+	const args = getToolArgs(toolCall);
+	const name = resolveTranscriptToolName(getToolName(toolCall), args);
+	const normalized = normalizeToolName(name).toLowerCase();
+	const labelKey = INCOMPLETE_TITLE_KEYS[normalized];
+	if (labelKey) return getCursorReplayDisplayLabel(labelKey);
+	switch (normalized) {
+		case "read":
+			return "Cursor read";
+		case "shell":
+			return "Cursor shell";
+		case "grep":
+			return "Cursor grep";
+		case "glob":
+			return "Cursor find";
+		case "ls":
+			return "Cursor ls";
+		default:
+			return buildGenericIncompleteActivityTitle(name);
+	}
+}
+
+export function buildIncompleteCursorToolDisplay(
+	toolCall: unknown,
+	reason: IncompleteCursorToolDiscardReason,
+	options: { apiKey?: string } = {},
+): CursorPiToolDisplay {
+	const args = getToolArgs(toolCall);
+	const transcriptName = resolveTranscriptToolName(getToolName(toolCall), args);
+	const activityTitle = getIncompleteCursorToolActivityTitle(toolCall);
+	const headline = `${activityTitle} did not complete`;
+	const reasonText = scrubSensitiveText(formatIncompleteCursorToolReasonText(reason), options.apiKey);
+	const contentText = `${headline}\n${reasonText}`;
+	return {
+		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
+		args: {
+			cursorToolName: normalizeToolName(transcriptName),
+			activityTitle,
+			activitySummary: reasonText,
+			incomplete: true,
+		},
+		result: {
+			content: [{ type: "text", text: contentText }],
+			details: {
+				cursorToolName: normalizeToolName(transcriptName),
+				title: headline,
+				summary: reasonText,
+			},
+		},
+		isError: true,
+	};
+}
+
+export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): string {
+	const details = display.result.details;
+	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
+	const argsRecord = display.args;
+	const title =
+		(typeof detailRecord?.title === "string" && detailRecord.title.trim()) ||
+		(typeof argsRecord.activityTitle === "string" && argsRecord.activityTitle.trim()
+			? `${argsRecord.activityTitle} did not complete`
+			: "Cursor tool did not complete");
+	const summary =
+		(typeof detailRecord?.summary === "string" && detailRecord.summary.trim()) ||
+		(typeof argsRecord.activitySummary === "string" && argsRecord.activitySummary.trim()) ||
+		formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
+	return `${truncateCursorDisplayLine(title)}: ${truncateCursorDisplayLine(summary)}\n`;
+}

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

@@ -10,6 +10,7 @@ import {
 import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display.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";
 
 export class CursorLiveRunAbortError extends Error {
 	constructor() {
@@ -46,7 +47,9 @@ export interface CursorLiveRun {
 	cancelled: boolean;
 	disposed: boolean;
 	errorMessage?: string;
+	abortMessage?: string;
 	chainUserInputAfterCompletion: boolean;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export interface CursorLiveRunCreateParams {
@@ -57,6 +60,7 @@ export interface CursorLiveRunCreateParams {
 	sessionAgentScopeKey?: string;
 	promptInputTokens: number;
 	textDeltas?: string[];
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export interface CursorLiveRunCoordinatorDeps {
@@ -70,7 +74,7 @@ export interface CursorLiveRunCoordinator {
 	start(params: CursorLiveRunCreateParams): CursorLiveRun;
 	attachSdkRun(run: CursorLiveRun, sdkRun: CursorLiveSdkRun): void;
 	markFinished(run: CursorLiveRun, finalText: string): void;
-	markCancelled(run: CursorLiveRun): void;
+	markCancelled(run: CursorLiveRun, abortMessage?: string): void;
 	markError(run: CursorLiveRun, errorMessage: string): void;
 	queueEvent(run: CursorLiveRun, event: CursorLiveQueuedEvent): void;
 	peekEvent(run: CursorLiveRun): CursorLiveQueuedEvent | undefined;
@@ -268,6 +272,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 				cancelled: false,
 				disposed: false,
 				chainUserInputAfterCompletion: false,
+				debugRecorder: params.debugRecorder,
 			};
 			privateStates.set(run, {
 				waiters: new Set(),
@@ -294,9 +299,10 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			coordinator.requestIdleDispose(run);
 		},
 
-		markCancelled(run): void {
+		markCancelled(run, abortMessage): void {
 			if (run.disposed) return;
 			run.cancelled = true;
+			run.abortMessage = abortMessage;
 			run.done = true;
 			notifyProgress(run);
 			coordinator.requestIdleDispose(run);
@@ -313,6 +319,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 		queueEvent(run, event): void {
 			if (run.disposed) return;
 			run.pendingEvents.push(event);
+			run.debugRecorder?.recordLiveRunEvent(event);
 			notifyProgress(run);
 		},
 
@@ -433,7 +440,9 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			if (state.leased || state.leaseQueue.length > 0) return;
 			state.idleDisposeRequested = false;
 			state.idleDisposeTimer = setTimeout(() => {
-				void coordinator.release(run);
+				void coordinator.release(run).catch(() => {
+					// Idle dispose must not leave release failures as unhandled rejections.
+				});
 			}, deps.getIdleDisposeMs());
 			state.idleDisposeTimer.unref?.();
 		},
@@ -463,10 +472,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 					}
 				}
 				if (abandoned) {
-					try {
-						await run.sdkRun?.cancel();
-					} catch {
-						// cancellation failure should not block session-agent abandonment
+					if (!run.done) {
+						try {
+							await run.sdkRun?.cancel();
+						} catch {
+							// cancellation failure should not block session-agent abandonment
+						}
 					}
 					await deps.abandonSessionAgent(run.sessionAgentScopeKey);
 				}

package/src/cursor-model.ts

@@ -0,0 +1,12 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const CURSOR_PROVIDER = "cursor";
+export const CURSOR_SDK_API = "cursor-sdk";
+
+export type CursorModelRef =
+	| Pick<NonNullable<ExtensionContext["model"]>, "provider" | "api">
+	| undefined;
+
+export function isCursorModel(model: CursorModelRef): boolean {
+	return model?.provider === CURSOR_PROVIDER || model?.api === CURSOR_SDK_API;
+}

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

@@ -0,0 +1,48 @@
+import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
+import type { Context } from "@earendil-works/pi-ai";
+
+export type NativeReplayDisposition = "queue_replay" | "inactive_trace" | "transcript_trace";
+
+export interface NativeReplayRoutingInput {
+	toolName: string;
+	useNativeToolReplay: boolean;
+	activeToolNames?: ReadonlySet<string>;
+	hasLiveRun: boolean;
+}
+
+export function isNativeToolActiveInContext(toolName: string, activeToolNames?: ReadonlySet<string>): boolean {
+	return activeToolNames === undefined || activeToolNames.has(toolName);
+}
+
+/**
+ * Canonical native replay routing for coordinator and live-run drain.
+ * Extension resync (pi active tools) is separate; this uses context.tools snapshot only.
+ */
+export function resolveNativeReplayDisposition(input: NativeReplayRoutingInput): NativeReplayDisposition {
+	if (!input.useNativeToolReplay || !canRenderCursorToolNatively(input.toolName)) {
+		return "transcript_trace";
+	}
+	if (isNativeToolActiveInContext(input.toolName, input.activeToolNames) && input.hasLiveRun) {
+		return "queue_replay";
+	}
+	if (!isNativeToolActiveInContext(input.toolName, input.activeToolNames)) {
+		return "inactive_trace";
+	}
+	return "transcript_trace";
+}
+
+export function partitionNativeToolsByActiveContext<T extends { toolName: string }>(
+	context: Context,
+	tools: readonly T[],
+): { active: T[]; inactive: T[] } {
+	const activeToolNames = getActiveContextToolNames(context);
+	if (!activeToolNames) return { active: [...tools], inactive: [] };
+	const active: T[] = [];
+	const inactive: T[] = [];
+	for (const tool of tools) {
+		if (activeToolNames.has(tool.toolName)) active.push(tool);
+		else inactive.push(tool);
+	}
+	return { active, inactive };
+}

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

@@ -0,0 +1,29 @@
+import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+
+function getCursorReplayResultText(display: CursorPiToolDisplay): string | undefined {
+	for (const content of display.result.content) {
+		if (content.type !== "text") continue;
+		const text = truncateCursorDisplayLine(content.text);
+		if (text) return text;
+	}
+	return undefined;
+}
+
+/** Unified inactive native-replay fallback: `title: summary` in thinking trace. */
+export function formatInactiveCursorReplayTrace(display: CursorPiToolDisplay): string {
+	const details = asRecord(display.result.details);
+	const args = asRecord(display.args);
+	const title = typeof details?.title === "string" && details.title.trim()
+		? details.title.trim()
+		: typeof args?.activityTitle === "string" && args.activityTitle.trim()
+			? args.activityTitle.trim()
+			: `Cursor ${display.toolName}`;
+	const summary = typeof details?.summary === "string" && details.summary.trim()
+		? details.summary.trim()
+		: typeof args?.activitySummary === "string" && args.activitySummary.trim()
+			? args.activitySummary.trim()
+			: getCursorReplayResultText(display) ?? "completed";
+	return `${truncateCursorDisplayLine(title)}: ${truncateCursorDisplayLine(summary)}\n`;
+}

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

@@ -1,12 +1,12 @@
-import type { ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
 import {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
-	CURSOR_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
 	NATIVE_CURSOR_TOOL_NAMES,
 	registerNativeCursorTool,
 	type NativeCursorToolName,
 } from "./cursor-native-tool-display-tools.js";
+import { isCursorModel } from "./cursor-model.js";
 import {
 	isCursorNativeToolDisplayRequested,
 	isCursorNativeToolRegistrationRequested,
@@ -16,10 +16,14 @@ import {
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-names.js";
 
+const CORE_PI_TOOL_NAMES = new Set(["read", "bash", "edit", "write"]);
+
 type CursorNativeToolRegistryApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "registerTool" | "setActiveTools">;
 
 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;
 }
 
@@ -30,10 +34,6 @@ function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: Nati
 
 type NativeRegistrationContext = { hasUI: boolean; ui: Pick<ExtensionContext["ui"], "notify">; model?: ExtensionContext["model"] };
 
-function isCursorModel(model: ExtensionContext["model"]): boolean {
-	return model?.provider === "cursor" || model?.api === "cursor-sdk";
-}
-
 export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
 	if (registeredNativeToolNames.size === 0) return;
 	const activeToolNames = new Set(pi.getActiveTools());
@@ -46,7 +46,8 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 			changed = true;
 		}
 	} else {
-		for (const toolName of CURSOR_REPLAY_TOOL_NAMES) {
+		for (const toolName of registeredNativeToolNames) {
+			if (CORE_PI_TOOL_NAMES.has(toolName)) continue;
 			if (!activeToolNames.delete(toolName)) continue;
 			changed = true;
 		}
@@ -85,6 +86,12 @@ export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExten
 	pi.on("session_start", (_event, ctx) => {
 		registerAvailableNativeCursorTools(pi, ctx);
 	});
+	pi.on("before_agent_start", (_event, ctx) => {
+		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	});
+	pi.on("turn_start", (_event, ctx) => {
+		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	});
 	pi.on("model_select", (event) => {
 		syncRegisteredNativeCursorToolsForModel(pi, event.model);
 	});

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

@@ -4,6 +4,7 @@ import { getLanguageFromPath, highlightCode, type ToolDefinition } from "@earend
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
+import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-transcript-utils.js";
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 	getCursorReplayDisplayLabel,
@@ -258,9 +259,27 @@ function getCursorReplayActivityTitle(toolName: CursorReplayToolName, args: Reco
 	return getCursorReplayToolLabel(toolName);
 }
 
+function formatReplayRecordingDurationMs(ms: number | undefined): string | undefined {
+	if (ms === undefined || !Number.isFinite(ms) || ms < 0) return undefined;
+	if (ms < 1000) return `${Math.round(ms)}ms`;
+	const seconds = ms / 1000;
+	return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+}
+
+function formatReplaySemSearchQuery(args: Record<string, unknown> | undefined): string | undefined {
+	const query = typeof args?.query === "string" ? args.query.trim() : undefined;
+	if (!query) return undefined;
+	const targetDirectories = Array.isArray(args?.targetDirectories)
+		? args.targetDirectories.filter((entry): entry is string => typeof entry === "string")
+		: [];
+	const dirHint =
+		targetDirectories.length > 0 ? ` (${targetDirectories.length} dir${targetDirectories.length === 1 ? "" : "s"})` : "";
+	return `${query}${dirHint}`;
+}
+
 function getCursorReplayCallSummary(toolName: CursorReplayToolName, args: Record<string, unknown> | undefined): string | undefined {
 	const activitySummary = typeof args?.activitySummary === "string" && args.activitySummary.trim() ? args.activitySummary.trim() : undefined;
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME && activitySummary) return activitySummary;
+	if (activitySummary) return activitySummary;
 
 	const path = typeof args?.path === "string" ? args.path : undefined;
 	const description = typeof args?.description === "string" ? args.description : undefined;
@@ -271,19 +290,33 @@ function getCursorReplayCallSummary(toolName: CursorReplayToolName, args: Record
 
 	if (toolName === "cursor_edit" || toolName === "cursor_write" || toolName === "cursor_delete") return path ?? "unknown";
 	if (toolName === "cursor_read_lints") {
-		const target = paths.length > 0 ? paths.join(" ") : path;
-		if (target && diagnosticCount !== undefined) return `${target} · ${diagnosticCount} diagnostic${diagnosticCount === 1 ? "" : "s"}`;
+		const target = paths.length > 0 ? paths.join(", ") : path;
+		if (target && diagnosticCount !== undefined) {
+			return `${diagnosticCount} diagnostic${diagnosticCount === 1 ? "" : "s"} in ${target}`;
+		}
 		return target;
 	}
 	if (toolName === "cursor_update_todos" || toolName === "cursor_create_plan") {
 		return totalCount !== undefined ? `${totalCount} item${totalCount === 1 ? "" : "s"}` : undefined;
 	}
 	if (toolName === "cursor_task") return description;
-	if (toolName === "cursor_generate_image") return prompt;
+	if (toolName === "cursor_generate_image") return path ?? prompt;
 	if (toolName === "cursor_mcp") return typeof args?.toolName === "string" ? args.toolName : undefined;
+	if (toolName === "cursor_sem_search") return formatReplaySemSearchQuery(args);
+	if (toolName === "cursor_record_screen") {
+		const duration = formatReplayRecordingDurationMs(
+			typeof args?.recordingDurationMs === "number" ? args.recordingDurationMs : undefined,
+		);
+		if (path && duration) return `${path} · ${duration}`;
+		if (path) return path;
+		if (typeof args?.mode === "string") return args.mode;
+	}
+	if (toolName === "cursor_web_search") return typeof args?.query === "string" ? args.query : undefined;
+	if (toolName === "cursor_web_fetch") return typeof args?.url === "string" ? args.url : undefined;
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) {
-		if (typeof args?.path === "string") return args.path;
+		if (path) return path;
 		if (typeof args?.toolName === "string") return args.toolName;
+		return formatReplaySemSearchQuery(args);
 	}
 	return undefined;
 }
@@ -440,6 +473,31 @@ export function renderCursorReplayResult(
 	return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
 }
 
+export function renderNativeLookingCursorReadReplayResult(
+	result: Parameters<CursorReplayRenderResult>[0],
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+	context: Parameters<CursorReplayRenderResult>[3],
+	renderBase: () => Component | undefined,
+): Component {
+	const base = renderBase?.() ?? new Text("", 0, 0);
+	const readArgs = context.args as Record<string, unknown> | undefined;
+	const replayDetails = result.details as Record<string, unknown> | undefined;
+	const usesLocalPreview =
+		readArgs?.localReadPreview === true ||
+		replayDetails?.localReadPreview === true ||
+		isLocalReadPreviewContent(firstContentText(result));
+	if (usesLocalPreview && !options.expanded && !context.isError) {
+		const noticeText = `\n${theme.fg("warning", LOCAL_READ_PREVIEW_NOTICE)}`;
+		if (base instanceof Text) {
+			base.setText(noticeText);
+			return base;
+		}
+		return new Text(noticeText, 0, 0);
+	}
+	return base;
+}
+
 export function createCursorReplayOnlyToolDefinition(toolName: CursorReplayToolName): ToolDefinition<typeof cursorReplayToolSchema, unknown> {
 	const cursorToolName = toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "activity" : getCursorReplaySourceToolName(toolName);
 	const sideEffectDescription = toolName === "cursor_edit" || toolName === "cursor_write" || toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "file mutations" : "real tool work";