pi-cursor-sdk 0.1.18 → 0.1.19

package/src/context.ts

@@ -20,6 +20,33 @@ export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
 export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
+export function getCursorToolTailGuardText(): string {
+	return "Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.";
+}
+
+function getCursorToolBoundaryText(): string {
+	return [
+		"Cursor SDK tool boundary:",
+		"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
+		getCursorPiBridgeContractText(),
+		"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
+		"Use pi__cursor_ask_question for material choices if exposed.",
+		"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
+		"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
+		"Images: only latest user images are sent; ask to reattach or describe prior images.",
+	].join("\n");
+}
+
+function getCursorBootstrapTailSections(): string[] {
+	return [
+		[
+			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
+			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
+		].join("\n"),
+		getCursorToolTailGuardText(),
+	];
+}
+
 function normalizePiContextMessages(messages: Context["messages"]): Message[] {
 	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
 }
@@ -281,7 +308,7 @@ export function computeCursorContextFingerprint(context: Context): string {
 	return JSON.stringify(payload);
 }
 
-export function shouldBootstrapCursorSend(
+export function shouldBootstrapCursorContext(
 	sendState: { bootstrapped: boolean; contextFingerprint: string },
 	context: Context,
 ): boolean {
@@ -304,6 +331,14 @@ export function shouldBootstrapCursorSend(
 	return false;
 }
 
+/** @deprecated Use planCursorSessionSend() for send mode and shouldBootstrapCursorContext() for context-only checks. */
+export function shouldBootstrapCursorSend(
+	sendState: { bootstrapped: boolean; contextFingerprint: string },
+	context: Context,
+): boolean {
+	return shouldBootstrapCursorContext(sendState, context);
+}
+
 export function buildCursorIncrementalPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
 	// Incremental sends omit the full Cursor SDK tool boundary block; the session agent retains prior bootstrap context.
 	const messages = normalizePiContextMessages(context.messages);
@@ -324,35 +359,18 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 		options.maxInputTokens === undefined
 			? options
 			: { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
-	const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [], latestUserMessageIndex, budgetOptions);
+	const parts = applyPromptBudget(
+		sectionsBeforeMessages,
+		latestUserMessageSections,
+		[getCursorToolTailGuardText()],
+		latestUserMessageIndex,
+		budgetOptions,
+	);
 	return { text: parts.join(SECTION_SEPARATOR), images };
 }
 
-export function buildCursorSendPrompt(
-	context: Context,
-	options: CursorPromptOptions,
-	sendState: { bootstrapped: boolean; contextFingerprint: string },
-): { prompt: CursorPrompt; bootstrap: boolean } {
-	const bootstrap = shouldBootstrapCursorSend(sendState, context);
-	if (bootstrap) {
-		return { prompt: buildCursorPrompt(context, options), bootstrap: true };
-	}
-	return { prompt: buildCursorIncrementalPrompt(context, options), bootstrap: false };
-}
-
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [
-		[
-			"Cursor SDK tool boundary:",
-			"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
-			getCursorPiBridgeContractText(),
-			"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
-			"Use pi__cursor_ask_question for material choices if exposed.",
-			"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
-			"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
-			"Images: only latest user images are sent; ask to reattach or describe prior images.",
-		].join("\n"),
-	];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText()];
 
 	if (context.systemPrompt) {
 		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
@@ -365,12 +383,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 			return text ? { index, text } : undefined;
 		})
 		.filter((section): section is { index: number; text: string } => section !== undefined);
-	const sectionsAfterMessages = [
-		[
-			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
-			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
-		].join("\n"),
-	];
+	const sectionsAfterMessages = getCursorBootstrapTailSections();
 	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =

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

@@ -0,0 +1,172 @@
+import { Agent, type AgentMessage } from "@cursor/sdk";
+import { asRecord, getArray, getString, stringifyUnknown } from "./cursor-transcript-utils.js";
+
+const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;
+
+export interface CursorTranscriptCompletedToolCall {
+	identity: string;
+	toolCall: unknown;
+}
+
+interface CursorTranscriptWebToolPayload {
+	kind: "webSearch" | "webFetch";
+	payload: unknown;
+}
+
+function getOneofCaseValue(value: unknown, caseName: string): unknown {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	if (record.case === caseName) return record.value;
+	return record[caseName];
+}
+
+async function hasCursorAgentMessageAt(agentId: string, cwd: string, offset: number): Promise<boolean> {
+	const messages = await Agent.messages.list(agentId, { runtime: "local", cwd, limit: 1, offset });
+	return messages.length > 0;
+}
+
+export async function countCursorAgentMessages(agentId: string, cwd: string): Promise<number> {
+	let high = 1;
+	while (await hasCursorAgentMessageAt(agentId, cwd, high)) {
+		high *= 2;
+	}
+
+	let low = 0;
+	while (low < high) {
+		const mid = Math.floor((low + high) / 2);
+		if (await hasCursorAgentMessageAt(agentId, cwd, mid)) low = mid + 1;
+		else high = mid;
+	}
+	return low;
+}
+
+export async function loadCursorTranscriptWebToolCallsAfterOffset(options: {
+	agentId: string;
+	cwd: string;
+	offset: number | undefined;
+}): Promise<CursorTranscriptCompletedToolCall[]> {
+	if (options.offset === undefined) return [];
+	const messages = await Agent.messages.list(options.agentId, {
+		runtime: "local",
+		cwd: options.cwd,
+		limit: CURSOR_AGENT_MESSAGE_PAGE_LIMIT,
+		offset: options.offset,
+	});
+	return collectCursorTranscriptWebToolCalls(messages);
+}
+
+export function collectCursorTranscriptWebToolCalls(messages: readonly AgentMessage[]): CursorTranscriptCompletedToolCall[] {
+	const toolCalls: CursorTranscriptCompletedToolCall[] = [];
+	for (const [messageIndex, message] of messages.entries()) {
+		const messageId = message.uuid || `${message.agent_id || "cursor-agent"}:${messageIndex}`;
+		const steps = getAgentConversationSteps(message.message);
+		for (const [stepIndex, step] of steps.entries()) {
+			const webTool = getStepWebToolPayload(step);
+			if (!webTool) continue;
+			const converted = convertCursorTranscriptWebTool(webTool);
+			if (!converted) continue;
+			const args = asRecord(converted.args);
+			const toolCallId = getString(args, "toolCallId") ?? getString(args, "tool_call_id") ?? `${stepIndex}`;
+			toolCalls.push({
+				identity: `cursor-transcript:${messageId}:${webTool.kind}:${toolCallId}`,
+				toolCall: converted,
+			});
+		}
+	}
+	return toolCalls;
+}
+
+function getAgentConversationSteps(message: unknown): unknown[] {
+	const record = asRecord(message);
+	const turn = getOneofCaseValue(record?.turn, "agentConversationTurn") ?? record?.agentConversationTurn;
+	return getArray(asRecord(turn), "steps") ?? [];
+}
+
+function getStepToolCall(step: unknown): unknown {
+	const stepRecord = asRecord(step);
+	const message = asRecord(stepRecord?.message);
+	return getOneofCaseValue(message, "toolCall") ?? stepRecord?.toolCall ?? message?.toolCall;
+}
+
+function getStepWebToolPayload(step: unknown): CursorTranscriptWebToolPayload | undefined {
+	const toolCall = getStepToolCall(step);
+	const toolCallRecord = asRecord(toolCall);
+	const tool = toolCallRecord?.tool;
+	const webSearchPayload =
+		getOneofCaseValue(tool, "webSearchToolCall") ??
+		getOneofCaseValue(toolCall, "webSearchToolCall") ??
+		toolCallRecord?.webSearchToolCall;
+	if (webSearchPayload) return { kind: "webSearch", payload: webSearchPayload };
+
+	const webFetchPayload =
+		getOneofCaseValue(tool, "webFetchToolCall") ??
+		getOneofCaseValue(toolCall, "webFetchToolCall") ??
+		toolCallRecord?.webFetchToolCall;
+	if (webFetchPayload) return { kind: "webFetch", payload: webFetchPayload };
+	return undefined;
+}
+
+function convertCursorTranscriptWebTool(webTool: CursorTranscriptWebToolPayload): { name: string; args: Record<string, unknown>; result: unknown } | undefined {
+	const payload = asRecord(webTool.payload);
+	if (!payload) return undefined;
+	const rawArgs = asRecord(payload.args) ?? {};
+	const args = normalizeWebToolArgs(webTool.kind, rawArgs);
+	const result = normalizeWebToolResult(payload.result);
+	if (!result) return undefined;
+	return {
+		name: webTool.kind,
+		args,
+		result,
+	};
+}
+
+function normalizeWebToolArgs(kind: "webSearch" | "webFetch", rawArgs: Record<string, unknown>): Record<string, unknown> {
+	const args = { ...rawArgs };
+	if (kind === "webSearch") {
+		const query = getString(args, "searchTerm") ?? getString(args, "search_term") ?? getString(args, "query") ?? getString(args, "q");
+		if (query && !args.searchTerm) args.searchTerm = query;
+		return args;
+	}
+	const url = getString(args, "url") ?? getString(args, "uri") ?? getString(args, "href");
+	if (url && !args.url) args.url = url;
+	return args;
+}
+
+function normalizeWebToolResult(result: unknown): unknown | undefined {
+	if (result === undefined) return undefined;
+	const success = getTranscriptResultCase(result, "success");
+	if (success !== undefined) {
+		return {
+			status: "success",
+			value: { content: [{ type: "text", text: transcriptWebSuccessText(success) }] },
+		};
+	}
+
+	const error = getTranscriptResultCase(result, "error");
+	if (error !== undefined) return { status: "error", error };
+
+	return {
+		status: "success",
+		value: { content: [{ type: "text", text: transcriptWebSuccessText(result) }] },
+	};
+}
+
+function getTranscriptResultCase(result: unknown, caseName: "success" | "error"): unknown {
+	const record = asRecord(result);
+	return getOneofCaseValue(record?.result, caseName) ?? record?.[caseName];
+}
+
+function transcriptWebSuccessText(success: unknown): string {
+	const successRecord = asRecord(success);
+	const references = getArray(successRecord, "references");
+	const chunks = references
+		?.map((reference) => getString(asRecord(reference), "chunk"))
+		.filter((chunk): chunk is string => Boolean(chunk?.trim()));
+	if (chunks && chunks.length > 0) return chunks.join("\n\n");
+	const content = getArray(successRecord, "content");
+	const text = content
+		?.map((entry) => getString(asRecord(entry), "text"))
+		.filter((entry): entry is string => Boolean(entry?.trim()));
+	if (text && text.length > 0) return text.join("\n");
+	return stringifyUnknown(success).trim() || "Cursor web activity completed.";
+}

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-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;
+}