pi-cursor-sdk 0.1.15 → 0.1.16

package/src/context.ts

@@ -1,5 +1,8 @@
+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 { getCursorPiBridgeContractText } from "./cursor-bridge-contract.js";
 import { getCursorReplayPromptLabel } from "./cursor-tool-names.js";
 
 export interface CursorPrompt {
@@ -13,9 +16,14 @@ export interface CursorPromptOptions {
 	imageTokenEstimate?: number;
 }
 
-const DEFAULT_CHARS_PER_TOKEN = 4;
+export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
+export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
+function normalizePiContextMessages(messages: Context["messages"]): Message[] {
+	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+}
+
 function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
 	return block.type === "text";
 }
@@ -131,7 +139,7 @@ function applyPromptBudget(
 		return [...sectionsBeforeMessages, ...messageSections.map((section) => section.text), ...sectionsAfterMessages];
 	}
 
-	const charsPerToken = options.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+	const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_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(
@@ -167,11 +175,177 @@ function applyPromptBudget(
 	return [...sectionsBeforeMessages, ...budgetNotice, ...includedMessages, ...sectionsAfterMessages];
 }
 
+export function estimateCursorTextTokens(text: string, options: Pick<CursorPromptOptions, "charsPerToken"> = {}): number {
+	const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
+	return Math.ceil(text.length / charsPerToken);
+}
+
+export function estimateCursorPromptTokens(prompt: CursorPrompt, options: Pick<CursorPromptOptions, "charsPerToken" | "imageTokenEstimate"> = {}): number {
+	return estimateCursorTextTokens(prompt.text, options) + prompt.images.length * (options.imageTokenEstimate ?? CURSOR_IMAGE_TOKEN_ESTIMATE);
+}
+
+export function estimateCursorPromptMessageTokens(message: Message, options: Pick<CursorPromptOptions, "charsPerToken"> = {}): number {
+	const text = formatMessage(message);
+	return text ? estimateCursorTextTokens(text, options) : 0;
+}
+
+export function estimateCursorContextTokens(context: Context, options: CursorPromptOptions = {}): number {
+	return estimateCursorPromptTokens(buildCursorPrompt(context, options), options);
+}
+
+interface CursorContextFingerprintPayload {
+	systemHash: string;
+	messageHashes: string[];
+}
+
+function hashCursorContextValue(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function serializeMessageForFingerprint(message: Message, index: number): string {
+	switch (message.role) {
+		case "user": {
+			const text =
+				typeof message.content === "string"
+					? message.content
+					: JSON.stringify(message.content);
+			return hashCursorContextValue(`user:${message.timestamp ?? index}:${text}`);
+		}
+		case "assistant":
+			return hashCursorContextValue(`assistant:${message.timestamp ?? index}:${JSON.stringify(message.content)}`);
+		case "toolResult":
+			return hashCursorContextValue(
+				`toolResult:${message.timestamp ?? index}:${message.toolCallId}:${message.toolName}:${JSON.stringify(message.content)}:${message.isError === true}`,
+			);
+	}
+}
+
+function serializeRawPiMessageForFingerprint(message: Context["messages"][number], index: number): string {
+	const role = (message as { role?: string }).role;
+	switch (role) {
+		case "branchSummary": {
+			const entry = message as { summary?: string; fromId?: string; timestamp?: number };
+			return hashCursorContextValue(
+				`branchSummary:${entry.timestamp ?? index}:${entry.fromId ?? ""}:${entry.summary ?? ""}`,
+			);
+		}
+		case "compactionSummary": {
+			const entry = message as { summary?: string; tokensBefore?: number; timestamp?: number };
+			return hashCursorContextValue(
+				`compactionSummary:${entry.timestamp ?? index}:${entry.tokensBefore ?? ""}:${entry.summary ?? ""}`,
+			);
+		}
+		case "custom": {
+			const entry = message as { customType?: string; content?: unknown; timestamp?: number };
+			return hashCursorContextValue(
+				`custom:${entry.timestamp ?? index}:${entry.customType ?? ""}:${JSON.stringify(entry.content)}`,
+			);
+		}
+		case "bashExecution": {
+			const entry = message as {
+				command?: string;
+				output?: string;
+				exitCode?: number | null;
+				cancelled?: boolean;
+				excludeFromContext?: boolean;
+				timestamp?: number;
+			};
+			if (entry.excludeFromContext) {
+				return hashCursorContextValue(`bashExecution:excluded:${entry.timestamp ?? index}`);
+			}
+			return hashCursorContextValue(
+				`bashExecution:${entry.timestamp ?? index}:${entry.command ?? ""}:${entry.output ?? ""}:${entry.exitCode ?? ""}:${entry.cancelled === true}`,
+			);
+		}
+		default:
+			return serializeMessageForFingerprint(message as Message, index);
+	}
+}
+
+function parseCursorContextFingerprint(fingerprint: string): CursorContextFingerprintPayload | undefined {
+	try {
+		const parsed = JSON.parse(fingerprint) as CursorContextFingerprintPayload;
+		if (!parsed || typeof parsed.systemHash !== "string" || !Array.isArray(parsed.messageHashes)) return undefined;
+		if (!parsed.messageHashes.every((entry) => typeof entry === "string")) return undefined;
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+export function computeCursorContextFingerprint(context: Context): string {
+	const payload: CursorContextFingerprintPayload = {
+		systemHash: hashCursorContextValue(context.systemPrompt ?? ""),
+		messageHashes: context.messages.map((message, index) => serializeRawPiMessageForFingerprint(message, index)),
+	};
+	return JSON.stringify(payload);
+}
+
+export function shouldBootstrapCursorSend(
+	sendState: { bootstrapped: boolean; contextFingerprint: string },
+	context: Context,
+): boolean {
+	if (!sendState.bootstrapped) return true;
+	const previous = parseCursorContextFingerprint(sendState.contextFingerprint);
+	if (!previous) return true;
+	const current = parseCursorContextFingerprint(computeCursorContextFingerprint(context));
+	if (!current) return true;
+	if (current.systemHash !== previous.systemHash) return true;
+	if (current.messageHashes.length < previous.messageHashes.length) return true;
+	if (current.messageHashes.length > previous.messageHashes.length) {
+		for (let index = previous.messageHashes.length; index < context.messages.length; index += 1) {
+			const role = (context.messages[index] as { role?: string }).role;
+			if (role === "branchSummary" || role === "compactionSummary") return true;
+		}
+	}
+	for (let index = 0; index < previous.messageHashes.length; index += 1) {
+		if (current.messageHashes[index] !== previous.messageHashes[index]) return true;
+	}
+	return false;
+}
+
+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);
+	const latestUserMessageIndex = getLatestUserMessageIndex(messages);
+	const latestUserMessage = latestUserMessageIndex >= 0 ? messages[latestUserMessageIndex] : undefined;
+	const latestUserText = latestUserMessage ? formatMessage(latestUserMessage) : undefined;
+	const sectionsBeforeMessages = [
+		"Continue the conversation using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from earlier context as if they were available.",
+	];
+	if (context.systemPrompt) {
+		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
+	}
+	const latestUserMessageSections =
+		latestUserText && latestUserMessageIndex >= 0 ? [{ index: latestUserMessageIndex, text: latestUserText }] : [];
+	const images = extractLatestImages(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, latestUserMessageSections, [], 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.",
@@ -184,7 +358,8 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
 	}
 
-	const messageSections = context.messages
+	const messages = normalizePiContextMessages(context.messages);
+	const messageSections = messages
 		.map((msg, index) => {
 			const text = formatMessage(msg);
 			return text ? { index, text } : undefined;
@@ -196,7 +371,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
 		].join("\n"),
 	];
-	const images = extractLatestImages(context.messages);
+	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =
 		options.maxInputTokens === undefined
@@ -206,7 +381,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages,
 		messageSections,
 		sectionsAfterMessages,
-		getLatestUserMessageIndex(context.messages),
+		getLatestUserMessageIndex(messages),
 		budgetOptions,
 	);
 	const text = parts.join(SECTION_SEPARATOR);

package/src/cursor-bridge-contract.ts

@@ -0,0 +1,27 @@
+export const CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX = "pi__";
+
+const CURSOR_PI_BRIDGE_CONTRACT_LINES = [
+	"Pi bridge contract:",
+	`${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* names are live Cursor MCP bridge tool names only when exposed in the current run.`,
+	`Call the ${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* MCP tool name, not the real pi tool name shown in pi history or transcripts.`,
+	"Bridged calls execute through normal pi tool flow, so pi shows the real pi tool name and returns a normal pi tool result.",
+	"Replay IDs, replay labels, and transcript tool names are display-only/context-only, not callable tools.",
+	"Cursor-native host tools, settings, plugins, and configured MCP servers are separate from the pi bridge.",
+] as const;
+
+export function getCursorPiBridgeContractText(): string {
+	return CURSOR_PI_BRIDGE_CONTRACT_LINES.join("\n");
+}
+
+export function buildCursorPiBridgeMcpToolDescription(options: {
+	piToolName: string;
+	mcpToolName: string;
+	piToolDescription: string;
+}): string {
+	return [
+		options.piToolDescription,
+		"",
+		getCursorPiBridgeContractText(),
+		`This run exposes real pi tool ${options.piToolName} as Cursor MCP tool ${options.mcpToolName}.`,
+	].join("\n");
+}

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

@@ -0,0 +1,65 @@
+import type { Context, Message, ToolResultMessage } from "@earendil-works/pi-ai";
+import { CURSOR_APPROX_CHARS_PER_TOKEN, estimateCursorPromptMessageTokens } from "./context.js";
+
+export interface CursorLiveRunAccountingState {
+	promptInputTokens: number;
+	promptInputTokensReported: boolean;
+	consumedToolResultIds: ReadonlySet<string>;
+}
+
+export interface CursorLiveToolResultConsumption {
+	state: CursorLiveRunAccountingState;
+	toolResults: ToolResultMessage[];
+	toolResultInputTokens: number;
+	toolCallIds: string[];
+}
+
+export function createCursorLiveRunAccountingState(promptInputTokens: number): CursorLiveRunAccountingState {
+	return {
+		promptInputTokens,
+		promptInputTokensReported: false,
+		consumedToolResultIds: new Set(),
+	};
+}
+
+function asToolResultMessage(message: Message): ToolResultMessage | undefined {
+	return message.role === "toolResult" ? message : undefined;
+}
+
+export function consumeCursorLiveToolResults(
+	state: CursorLiveRunAccountingState,
+	context: Context,
+	isMatchingToolResult: (toolResult: ToolResultMessage) => boolean,
+): CursorLiveToolResultConsumption {
+	const consumedToolResultIds = new Set(state.consumedToolResultIds);
+	const toolResults: ToolResultMessage[] = [];
+	let toolResultInputTokens = 0;
+
+	for (const message of context.messages) {
+		const toolResult = asToolResultMessage(message);
+		if (!toolResult) continue;
+		if (consumedToolResultIds.has(toolResult.toolCallId)) continue;
+		if (!isMatchingToolResult(toolResult)) continue;
+		consumedToolResultIds.add(toolResult.toolCallId);
+		toolResults.push(toolResult);
+		toolResultInputTokens += estimateCursorPromptMessageTokens(toolResult, { charsPerToken: CURSOR_APPROX_CHARS_PER_TOKEN });
+	}
+
+	return {
+		state: { ...state, consumedToolResultIds },
+		toolResults,
+		toolResultInputTokens,
+		toolCallIds: toolResults.map((toolResult) => toolResult.toolCallId),
+	};
+}
+
+export function takeCursorLiveTurnInputTokens(
+	state: CursorLiveRunAccountingState,
+	toolResultInputTokens: number,
+): { state: CursorLiveRunAccountingState; sessionInputTokens: number } {
+	const promptInputTokens = state.promptInputTokensReported ? 0 : state.promptInputTokens;
+	return {
+		state: state.promptInputTokensReported ? state : { ...state, promptInputTokensReported: true },
+		sessionInputTokens: promptInputTokens + toolResultInputTokens,
+	};
+}

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

@@ -12,6 +12,8 @@ import {
 	highlightCode,
 	type ExtensionAPI,
 	type ExtensionContext,
+	type ExtensionHandler,
+	type SessionStartEvent,
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
@@ -45,6 +47,13 @@ export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 const registeredNativeToolNames = new Set<NativeCursorToolName>();
 const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
 
+type CursorNativeToolRegistryApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "registerTool" | "setActiveTools">;
+
+interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
+}
+
 function readBooleanEnv(name: string): boolean | undefined {
 	const value = process.env[name]?.trim().toLowerCase();
 	if (value === "1" || value === "true" || value === "yes" || value === "on") return true;
@@ -566,12 +575,12 @@ function createNativeCursorToolDefinition(toolName: NativeCursorToolName, cwd: s
 	throw new Error(`Unsupported Cursor native replay tool: ${toolName}`);
 }
 
-function registerNativeCursorTool(pi: ExtensionAPI, toolName: NativeCursorToolName): void {
+function registerNativeCursorTool(pi: Pick<ExtensionAPI, "registerTool">, toolName: NativeCursorToolName): void {
 	const definition = createNativeCursorToolDefinition(toolName, getCursorSessionCwd());
 	pi.registerTool(wrapNativeCursorTool(definition, () => createNativeCursorToolDefinition(toolName, getCursorSessionCwd())));
 }
 
-function hasNonBuiltinTool(pi: ExtensionAPI, toolName: NativeCursorToolName): boolean {
+function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: NativeCursorToolName): boolean {
 	const existingTool = pi.getAllTools().find((tool) => tool.name === toolName);
 	return existingTool !== undefined && existingTool.sourceInfo.source !== "builtin";
 }
@@ -582,7 +591,7 @@ function isCursorModel(model: ExtensionContext["model"]): boolean {
 	return model?.provider === "cursor" || model?.api === "cursor-sdk";
 }
 
-function syncRegisteredNativeCursorToolsForModel(pi: ExtensionAPI, model: ExtensionContext["model"]): void {
+function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
 	if (registeredNativeToolNames.size === 0) return;
 	const activeToolNames = new Set(pi.getActiveTools());
 	let changed = false;
@@ -602,7 +611,7 @@ function syncRegisteredNativeCursorToolsForModel(pi: ExtensionAPI, model: Extens
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-function registerAvailableNativeCursorTools(pi: ExtensionAPI, ctx: NativeRegistrationContext): void {
+function registerAvailableNativeCursorTools(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	if (!isCursorNativeToolRegistrationRequested()) {
 		registeredNativeToolNames.clear();
 		return;
@@ -629,7 +638,7 @@ function registerAvailableNativeCursorTools(pi: ExtensionAPI, ctx: NativeRegistr
 	}
 }
 
-export function registerCursorNativeToolDisplay(pi: ExtensionAPI): void {
+export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
 	pi.on("session_start", (_event, ctx) => {
 		registerAvailableNativeCursorTools(pi, ctx);
 	});