pi-cursor-sdk 0.1.8 → 0.1.10

package/src/context.ts

@@ -6,6 +6,15 @@ export interface CursorPrompt {
 	images: SDKImage[];
 }
 
+export interface CursorPromptOptions {
+	maxInputTokens?: number;
+	charsPerToken?: number;
+	imageTokenEstimate?: number;
+}
+
+const DEFAULT_CHARS_PER_TOKEN = 4;
+const SECTION_SEPARATOR = "\n\n";
+
 function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
 	return block.type === "text";
 }
@@ -53,48 +62,132 @@ function formatToolCall(toolCall: ToolCall): string {
 	return `Tool call (${toolCall.name}, call ${toolCall.id}): ${args}`;
 }
 
-export function buildCursorPrompt(context: Context): CursorPrompt {
-	const parts: string[] = [];
+function formatMessage(msg: Message): string | undefined {
+	switch (msg.role) {
+		case "user": {
+			const text = formatContentBlocks(msg.content);
+			return text ? `User: ${text}` : undefined;
+		}
+		case "assistant": {
+			const blocks = Array.isArray(msg.content) ? msg.content : [{ type: "text" as const, text: String(msg.content) }];
+			const textParts: string[] = [];
+			for (const block of blocks) {
+				if (isTextBlock(block)) {
+					textParts.push(block.text);
+				} else if (isToolCallBlock(block)) {
+					textParts.push(formatToolCall(block));
+				}
+				// Omit thinking content from transcript
+			}
+			return textParts.length > 0 ? `Assistant: ${textParts.join("\n")}` : undefined;
+		}
+		case "toolResult": {
+			const text = formatContentBlocks(msg.content);
+			const label = msg.isError ? "Tool error" : "Tool result";
+			return `${label} (${msg.toolName}, call ${msg.toolCallId}): ${text}`;
+		}
+	}
+}
 
-	if (context.systemPrompt) {
-		parts.push(`System instructions from pi:\n${context.systemPrompt}`);
+function getLatestUserMessageIndex(messages: Message[]): number {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		if (messages[index].role === "user") return index;
 	}
+	return -1;
+}
 
-	for (const msg of context.messages) {
-		switch (msg.role) {
-			case "user": {
-				const text = formatContentBlocks(msg.content);
-				if (text) parts.push(`User: ${text}`);
-				break;
-			}
-			case "assistant": {
-				const blocks = Array.isArray(msg.content) ? msg.content : [{ type: "text" as const, text: String(msg.content) }];
-				const textParts: string[] = [];
-				for (const block of blocks) {
-					if (isTextBlock(block)) {
-						textParts.push(block.text);
-					} else if (isToolCallBlock(block)) {
-						textParts.push(formatToolCall(block));
-					}
-					// Omit thinking content from transcript
-				}
-				if (textParts.length > 0) {
-					parts.push(`Assistant: ${textParts.join("\n")}`);
-				}
-				break;
-			}
-			case "toolResult": {
-				const text = formatContentBlocks(msg.content);
-				const label = msg.isError ? "Tool error" : "Tool result";
-				parts.push(`${label} (${msg.toolName}, call ${msg.toolCallId}): ${text}`);
-				break;
-			}
+function getSectionCost(section: string): number {
+	return section.length + SECTION_SEPARATOR.length;
+}
+
+function applyPromptBudget(
+	sectionsBeforeMessages: string[],
+	messageSections: Array<{ index: number; text: string }>,
+	sectionsAfterMessages: string[],
+	latestUserMessageIndex: number,
+	options: CursorPromptOptions,
+): string[] {
+	const maxInputTokens = options.maxInputTokens;
+	if (maxInputTokens === undefined || !Number.isFinite(maxInputTokens) || maxInputTokens <= 0) {
+		return [...sectionsBeforeMessages, ...messageSections.map((section) => section.text), ...sectionsAfterMessages];
+	}
+
+	const charsPerToken = options.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+	const maxChars = Math.max(1, Math.floor(maxInputTokens * charsPerToken));
+	const requiredMessageSections = messageSections.filter((section) => section.index === latestUserMessageIndex);
+	const requiredCost = [...sectionsBeforeMessages, ...requiredMessageSections.map((section) => section.text), ...sectionsAfterMessages].reduce(
+		(total, section) => total + getSectionCost(section),
+		0,
+	);
+	let remainingChars = maxChars - requiredCost;
+	const includedMessageIndexes = new Set(requiredMessageSections.map((section) => section.index));
+	let omittedMessageCount = 0;
+
+	for (let index = messageSections.length - 1; index >= 0; index -= 1) {
+		const section = messageSections[index];
+		if (includedMessageIndexes.has(section.index)) continue;
+		const cost = getSectionCost(section.text);
+		if (cost <= remainingChars) {
+			includedMessageIndexes.add(section.index);
+			remainingChars -= cost;
+			continue;
 		}
+		omittedMessageCount += messageSections
+			.slice(0, index + 1)
+			.filter((candidate) => !includedMessageIndexes.has(candidate.index)).length;
+		break;
 	}
 
-	parts.push("Answer the latest user request above using your capabilities. Do not assume access to pi tools.");
+	const budgetNotice =
+		omittedMessageCount > 0
+			? [`[Earlier transcript omitted: ${omittedMessageCount} message${omittedMessageCount === 1 ? "" : "s"} to fit Cursor context budget]`]
+			: [];
+	const includedMessages = messageSections
+		.filter((section) => includedMessageIndexes.has(section.index))
+		.map((section) => section.text);
+	return [...sectionsBeforeMessages, ...budgetNotice, ...includedMessages, ...sectionsAfterMessages];
+}
+
+export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
+	const sectionsBeforeMessages: string[] = [
+		[
+			"Cursor SDK tool boundary:",
+			"Only tools exposed by the Cursor SDK in this run are callable. The pi system prompt and transcript are context only; they do not grant access to pi tools or tool names mentioned there.",
+			"If the user asks you to search, fetch, browse, or research the web, use an actual Cursor SDK web/search/browser/MCP tool call. If no such Cursor SDK tool is available, say that web search is not configured for this Cursor SDK run.",
+			"Do not plan to use or claim to have used pi-only tools such as WebSearch or WebFetch unless the Cursor SDK actually exposes and executes that tool in this run.",
+			"Image payload boundary: only images attached to the latest user message are available as image bytes. Earlier images appear only as [image omitted from transcript] placeholders; ask the user to reattach or describe a prior image if the latest request depends on it.",
+		].join("\n"),
+	];
 
+	if (context.systemPrompt) {
+		sectionsBeforeMessages.push(`System instructions from pi:\n${context.systemPrompt}`);
+	}
+
+	const messageSections = context.messages
+		.map((msg, index) => {
+			const text = formatMessage(msg);
+			return text ? { index, text } : undefined;
+		})
+		.filter((section): section is { index: number; text: string } => section !== undefined);
+	const sectionsAfterMessages = [
+		[
+			"Answer the latest user request above using your capabilities. Do not assume access to pi tools.",
+			"If the user asks for web research, do not claim to have searched the web unless a Cursor SDK web/search/browser/MCP tool was actually used.",
+		].join("\n"),
+	];
 	const images = extractLatestImages(context.messages);
+	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
+	const budgetOptions =
+		options.maxInputTokens === undefined
+			? options
+			: { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
+	const parts = applyPromptBudget(
+		sectionsBeforeMessages,
+		messageSections,
+		sectionsAfterMessages,
+		getLatestUserMessageIndex(context.messages),
+		budgetOptions,
+	);
 
-	return { text: parts.join("\n\n"), images };
+	return { text: parts.join(SECTION_SEPARATOR), images };
 }

package/src/cursor-fallback-models.generated.ts

@@ -0,0 +1,145 @@
+import type { ModelListItem } from "@cursor/sdk";
+
+// Generated/maintained fallback Cursor catalog snapshot.
+// Refresh with: npm run refresh:cursor-snapshots -- --write
+// Do not add secrets; this file stores public model metadata only.
+export const FALLBACK_MODEL_ITEMS = [
+	{
+		id: "composer-2",
+		displayName: "Cursor Composer 2",
+		parameters: [
+			{
+				id: "fast",
+				displayName: "Fast",
+				values: [{ value: "false" }, { value: "true" }],
+			},
+		],
+		variants: [
+			{
+				params: [{ id: "fast", value: "true" }],
+				displayName: "Cursor Composer 2",
+				isDefault: true,
+			},
+		],
+	},
+	{
+		id: "gpt-5.5",
+		displayName: "GPT-5.5",
+		parameters: [
+			{
+				id: "context",
+				displayName: "Context",
+				values: [{ value: "1m" }, { value: "272k" }],
+			},
+			{
+				id: "reasoning",
+				displayName: "Reasoning",
+				values: [
+					{ value: "none" },
+					{ value: "low" },
+					{ value: "medium" },
+					{ value: "high" },
+					{ value: "extra-high" },
+				],
+			},
+			{
+				id: "fast",
+				displayName: "Fast",
+				values: [{ value: "false" }, { value: "true" }],
+			},
+		],
+		variants: [
+			{
+				params: [
+					{ id: "context", value: "1m" },
+					{ id: "reasoning", value: "medium" },
+					{ id: "fast", value: "false" },
+				],
+				displayName: "GPT-5.5",
+				isDefault: true,
+			},
+		],
+	},
+	{
+		id: "claude-sonnet-4-6",
+		displayName: "Sonnet 4.6",
+		parameters: [
+			{
+				id: "thinking",
+				displayName: "Thinking",
+				values: [{ value: "false" }, { value: "true" }],
+			},
+			{
+				id: "context",
+				displayName: "Context",
+				values: [{ value: "1m" }, { value: "200k" }],
+			},
+			{
+				id: "effort",
+				displayName: "Effort",
+				values: [
+					{ value: "low" },
+					{ value: "medium" },
+					{ value: "high" },
+					{ value: "xhigh" },
+					{ value: "max" },
+				],
+			},
+			{
+				id: "fast",
+				displayName: "Fast",
+				values: [{ value: "false" }, { value: "true" }],
+			},
+		],
+		variants: [
+			{
+				params: [
+					{ id: "thinking", value: "true" },
+					{ id: "context", value: "1m" },
+					{ id: "effort", value: "medium" },
+					{ id: "fast", value: "false" },
+				],
+				displayName: "Sonnet 4.6",
+				isDefault: true,
+			},
+		],
+	},
+	{
+		id: "claude-opus-4-7",
+		displayName: "Opus 4.7",
+		parameters: [
+			{
+				id: "thinking",
+				displayName: "Thinking",
+				values: [{ value: "false" }, { value: "true" }],
+			},
+			{
+				id: "context",
+				displayName: "Context",
+				values: [{ value: "1m" }, { value: "300k" }],
+			},
+			{
+				id: "effort",
+				displayName: "Effort",
+				values: [
+					{ value: "low" },
+					{ value: "medium" },
+					{ value: "high" },
+					{ value: "xhigh" },
+					{ value: "max" },
+				],
+			},
+		],
+		variants: [
+			{
+				params: [
+					{ id: "thinking", value: "true" },
+					{ id: "context", value: "1m" },
+					{ id: "effort", value: "xhigh" },
+				],
+				displayName: "Opus 4.7",
+				isDefault: true,
+			},
+		],
+	},
+] satisfies ModelListItem[];

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

@@ -6,14 +6,16 @@ import {
 	type ExtensionContext,
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import type { TSchema } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type TSchema } from "typebox";
 import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
 
-const NATIVE_CURSOR_TOOL_NAMES = ["read", "bash", "ls"] as const;
+const NATIVE_CURSOR_TOOL_NAMES = ["read", "bash", "ls", "cursor_edit", "cursor_write"] as const;
 type NativeCursorToolName = (typeof NATIVE_CURSOR_TOOL_NAMES)[number];
 const NATIVE_CURSOR_TOOL_DISPLAY_ENV = "PI_CURSOR_NATIVE_TOOL_DISPLAY";
 // Registration-only kill switch for users who want transcript fallback without shadowing read/bash/ls.
 const NATIVE_CURSOR_TOOL_REGISTRATION_ENV = "PI_CURSOR_REGISTER_NATIVE_TOOLS";
+const cursorReplayToolSchema = Type.Object({}, { additionalProperties: true });
 
 export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 	id: string;
@@ -22,6 +24,7 @@ export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 
 const registeredNativeToolNames = new Set<NativeCursorToolName>();
 const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
+let currentNativeToolCwd = process.cwd();
 
 function readBooleanEnv(name: string): boolean | undefined {
 	const value = process.env[name]?.trim().toLowerCase();
@@ -56,9 +59,14 @@ export function canRenderCursorToolNatively(toolName: string): boolean {
 	return isNativeCursorToolName(toolName) && registeredNativeToolNames.has(toolName);
 }
 
-export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): void {
-	if (!canRenderCursorToolNatively(item.toolName)) return;
+export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): boolean {
+	if (!canRenderCursorToolNatively(item.toolName)) return false;
 	nativeToolResults.set(item.id, item);
+	return true;
+}
+
+export function deleteCursorNativeToolDisplay(id: string): void {
+	nativeToolResults.delete(id);
 }
 
 function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem | undefined {
@@ -68,14 +76,17 @@ function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem
 }
 
 export const __testUtils = {
+	nativeToolResultCount: () => nativeToolResults.size,
 	reset(): void {
 		registeredNativeToolNames.clear();
 		nativeToolResults.clear();
+		currentNativeToolCwd = process.cwd();
 	},
 };
 
 function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 	definition: ToolDefinition<TParams, TDetails, TState>,
+	getCurrentDefinition: () => ToolDefinition<TParams, TDetails, TState>,
 ): ToolDefinition<TParams, TDetails, TState> {
 	return {
 		...definition,
@@ -88,21 +99,151 @@ function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 					terminate: cursorDisplay.terminate ?? true,
 				};
 			}
-			return definition.execute(toolCallId, params, signal, onUpdate, ctx);
+			return getCurrentDefinition().execute(toolCallId, params, signal, onUpdate, ctx);
 		},
 	};
 }
 
-function registerNativeCursorTool(pi: ExtensionAPI, toolName: NativeCursorToolName, cwd: string): void {
-	if (toolName === "read") {
-		pi.registerTool(wrapNativeCursorTool(createReadToolDefinition(cwd)));
-		return;
+interface CursorReplayToolDetails {
+	cursorToolName?: "edit" | "write";
+	path?: string;
+	linesAdded?: number;
+	linesRemoved?: number;
+	linesCreated?: number;
+	fileSize?: number;
+	diffString?: string;
+}
+
+function asCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
+	return value && typeof value === "object" ? (value as CursorReplayToolDetails) : undefined;
+}
+
+function getCursorReplayPath(args: Record<string, unknown> | undefined, details: CursorReplayToolDetails | undefined): string {
+	const argPath = args?.path;
+	return details?.path ?? (typeof argPath === "string" && argPath.trim() ? argPath : "unknown");
+}
+
+type CursorReplayRenderCall = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderCall"]>;
+type CursorReplayRenderResult = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderResult"]>;
+type CursorReplayRenderTheme = Parameters<CursorReplayRenderCall>[1];
+
+function formatCursorReplayDiff(diff: string, theme: CursorReplayRenderTheme, maxLines: number): string {
+	const lines = diff.split("\n");
+	const visible = lines.slice(0, maxLines);
+	const rendered = visible.map((line) => {
+		if (line.startsWith("+") && !line.startsWith("+++")) return theme.fg("success", line);
+		if (line.startsWith("-") && !line.startsWith("---")) return theme.fg("error", line);
+		return theme.fg("muted", line);
+	});
+	if (lines.length > maxLines) rendered.push(theme.fg("muted", `... (${lines.length - maxLines} more diff lines)`));
+	return rendered.join("\n");
+}
+
+function renderCursorReplayCall(
+	toolName: "cursor_edit" | "cursor_write",
+	args: Record<string, unknown> | undefined,
+	theme: CursorReplayRenderTheme,
+	isPartial: boolean,
+): Text {
+	if (!isPartial) return new Text("", 0, 0);
+	const cursorToolName = toolName === "cursor_edit" ? "edit" : "write";
+	let text = theme.fg("toolTitle", theme.bold(`Cursor ${cursorToolName} `));
+	text += theme.fg("accent", getCursorReplayPath(args, undefined));
+	return new Text(text, 0, 0);
+}
+
+function pluralize(count: number, noun: string): string {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+function hasCursorEditChanges(details: CursorReplayToolDetails): boolean {
+	return Boolean(details.diffString) || Boolean(details.linesAdded) || Boolean(details.linesRemoved);
+}
+
+function classifyCursorEditOperation(details: CursorReplayToolDetails): "created" | "deleted" | "updated" | "unchanged" {
+	if (!hasCursorEditChanges(details)) return "unchanged";
+	if (details.diffString?.startsWith("--- /dev/null")) return "created";
+	if (details.diffString?.includes("\n+++ /dev/null")) return "deleted";
+	return "updated";
+}
+
+function formatCursorEditSummary(details: CursorReplayToolDetails): string {
+	const operation = classifyCursorEditOperation(details);
+	if (operation === "unchanged") return "no changes needed";
+	if (operation === "created" && details.linesAdded !== undefined) return `created ${pluralize(details.linesAdded, "line")}`;
+	if (operation === "deleted" && details.linesRemoved !== undefined) return `deleted ${pluralize(details.linesRemoved, "line")}`;
+	const parts = [
+		details.linesAdded ? `added ${pluralize(details.linesAdded, "line")}` : undefined,
+		details.linesRemoved ? `removed ${pluralize(details.linesRemoved, "line")}` : undefined,
+	].filter((part): part is string => Boolean(part));
+	return parts.length > 0 ? parts.join(", ") : "updated file";
+}
+
+function renderCursorReplayResult(
+	result: Parameters<CursorReplayRenderResult>[0],
+	options: Parameters<CursorReplayRenderResult>[1],
+	theme: Parameters<CursorReplayRenderResult>[2],
+	isError: boolean,
+): Text {
+	if (options.isPartial) return new Text(theme.fg("warning", "Replaying Cursor tool result..."), 0, 0);
+	const details = asCursorReplayToolDetails(result.details);
+	const content = result.content[0];
+	const text = content?.type === "text" ? content.text : "";
+	if (isError) return new Text(theme.fg("error", text.split("\n")[0] || "Cursor replay failed"), 0, 0);
+
+	if (details?.cursorToolName === "edit") {
+		const summary = formatCursorEditSummary(details);
+		let rendered = `${theme.fg("toolTitle", theme.bold(`Cursor ${classifyCursorEditOperation(details)}`))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`;
+		if (details.diffString) rendered += options.expanded ? `\n${formatCursorReplayDiff(details.diffString, theme, 40)}` : theme.fg("muted", " (expand for diff)");
+		return new Text(rendered, 0, 0);
 	}
-	if (toolName === "bash") {
-		pi.registerTool(wrapNativeCursorTool(createBashToolDefinition(cwd)));
-		return;
+
+	if (details?.cursorToolName === "write") {
+		const parts = [
+			details.linesCreated !== undefined ? `${details.linesCreated} line${details.linesCreated === 1 ? "" : "s"}` : undefined,
+			details.fileSize !== undefined ? `${details.fileSize} bytes` : undefined,
+		].filter(Boolean);
+		const summary = parts.length > 0 ? parts.join(", ") : "written";
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("Cursor write"))} ${theme.fg("accent", getCursorReplayPath(undefined, details))} ${theme.fg("success", summary)}`,
+			0,
+			0,
+		);
 	}
-	pi.registerTool(wrapNativeCursorTool(createLsToolDefinition(cwd)));
+
+	return new Text(text || theme.fg("success", "Cursor tool result replayed"), 0, 0);
+}
+
+function createCursorReplayOnlyToolDefinition(toolName: "cursor_edit" | "cursor_write"): ToolDefinition<typeof cursorReplayToolSchema, unknown> {
+	const cursorToolName = toolName === "cursor_edit" ? "edit" : "write";
+	return {
+		name: toolName,
+		label: `Cursor ${cursorToolName}`,
+		description: `Replay display for a Cursor SDK ${cursorToolName} operation. This tool only returns recorded Cursor results and never mutates files directly.`,
+		parameters: cursorReplayToolSchema,
+		renderShell: "self",
+		async execute() {
+			throw new Error(`No recorded Cursor ${cursorToolName} result was available. This replay-only tool does not execute file mutations.`);
+		},
+			renderCall(args, theme, context) {
+			return renderCursorReplayCall(toolName, args as Record<string, unknown>, theme, context.isPartial);
+		},
+		renderResult(result, options, theme, context) {
+			return renderCursorReplayResult(result, options, theme, context.isError);
+		},
+	};
+}
+
+function createNativeCursorToolDefinition(toolName: NativeCursorToolName, cwd: string): ToolDefinition<TSchema, unknown, unknown> {
+	if (toolName === "read") return createReadToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
+	if (toolName === "bash") return createBashToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
+	if (toolName === "ls") return createLsToolDefinition(cwd) as ToolDefinition<TSchema, unknown, unknown>;
+	return createCursorReplayOnlyToolDefinition(toolName) as ToolDefinition<TSchema, unknown, unknown>;
+}
+
+function registerNativeCursorTool(pi: ExtensionAPI, toolName: NativeCursorToolName): void {
+	const definition = createNativeCursorToolDefinition(toolName, currentNativeToolCwd);
+	pi.registerTool(wrapNativeCursorTool(definition, () => createNativeCursorToolDefinition(toolName, currentNativeToolCwd)));
 }
 
 function hasNonBuiltinTool(pi: ExtensionAPI, toolName: NativeCursorToolName): boolean {
@@ -116,7 +257,7 @@ function registerAvailableNativeCursorTools(pi: ExtensionAPI, ctx: ExtensionCont
 		return;
 	}
 
-	const cwd = process.cwd();
+	currentNativeToolCwd = ctx.cwd;
 	const skippedToolNames: string[] = [];
 	for (const toolName of NATIVE_CURSOR_TOOL_NAMES) {
 		if (registeredNativeToolNames.has(toolName)) continue;
@@ -124,7 +265,7 @@ function registerAvailableNativeCursorTools(pi: ExtensionAPI, ctx: ExtensionCont
 			skippedToolNames.push(toolName);
 			continue;
 		}
-		registerNativeCursorTool(pi, toolName, cwd);
+		registerNativeCursorTool(pi, toolName);
 		registeredNativeToolNames.add(toolName);
 	}