pi-cursor-sdk 0.1.15 → 0.1.17

package/scripts/validate-smoke-jsonl.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Validate assistant presence and usage fields in pi session JSONL files under a smoke directory.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+function printHelp() {
+	console.log(`Validate assistant presence and usage metadata in pi smoke session JSONL files.
+
+Usage:
+  node scripts/validate-smoke-jsonl.mjs <smoke-dir>
+  SMOKE_DIR=/tmp/pi-cursor-smoke node scripts/validate-smoke-jsonl.mjs
+
+Arguments:
+  smoke-dir                     Directory containing smoke session subdirs and JSONL files.
+                                Defaults to SMOKE_DIR when the positional arg is omitted.
+
+Options:
+  -h, --help                    Show this help.
+
+Exit codes:
+  0  every scanned JSONL file has at least one assistant message and valid assistant usage metadata
+  1  invalid arguments, unreadable directory, invalid JSONL, empty/no-assistant files, or usage validation failures
+  2  no JSONL files found under the smoke directory
+
+Enforced invariants:
+  - each scanned JSONL file contains parseable JSONL records
+  - each scanned JSONL file contains at least one persisted assistant message
+  - every persisted assistant message has usage metadata
+  - assistant usage input/output/totalTokens are non-negative numbers
+  - assistant usage cacheRead/cacheWrite are exactly 0
+
+Notes:
+  - Prints one JSON summary line per scanned session file.
+  - Does not print session message contents or secrets.`);
+}
+
+function fail(message) {
+	console.error(`validate-smoke-jsonl: ${message}`);
+	process.exit(1);
+}
+
+function collectJsonlFiles(root) {
+	const files = [];
+	function walk(dir) {
+		for (const name of readdirSync(dir)) {
+			const path = join(dir, name);
+			const st = statSync(path);
+			if (st.isDirectory()) walk(path);
+			else if (path.endsWith(".jsonl")) files.push(path);
+		}
+	}
+	walk(root);
+	return files.sort();
+}
+
+function isNonNegativeNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function isBadUsage(usage) {
+	return (
+		!usage ||
+		typeof usage !== "object" ||
+		!isNonNegativeNumber(usage.input) ||
+		!isNonNegativeNumber(usage.output) ||
+		!isNonNegativeNumber(usage.totalTokens) ||
+		usage.cacheRead !== 0 ||
+		usage.cacheWrite !== 0
+	);
+}
+
+function parseJsonlFile(file) {
+	const lines = readFileSync(file, "utf8")
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter(Boolean);
+	const records = [];
+	let parseErrorCount = 0;
+	for (const line of lines) {
+		try {
+			records.push(JSON.parse(line));
+		} catch {
+			parseErrorCount += 1;
+		}
+	}
+	return { lineCount: lines.length, records, parseErrorCount };
+}
+
+function main() {
+	const args = process.argv.slice(2);
+	if (args.includes("-h") || args.includes("--help")) {
+		printHelp();
+		return;
+	}
+
+	if (args.length > 1) {
+		fail("too many arguments; pass only the smoke directory");
+	}
+
+	const smokeDir = args[0] ?? process.env.SMOKE_DIR;
+	if (!smokeDir) {
+		fail("missing smoke directory; pass a path or set SMOKE_DIR");
+	}
+
+	let files;
+	try {
+		files = collectJsonlFiles(smokeDir);
+	} catch (error) {
+		fail(error instanceof Error ? error.message : String(error));
+	}
+
+	if (files.length === 0) {
+		console.error(`validate-smoke-jsonl: no JSONL files under ${smokeDir}`);
+		process.exit(2);
+	}
+
+	let failures = 0;
+	for (const file of files) {
+		let summary;
+		try {
+			const { lineCount, records, parseErrorCount } = parseJsonlFile(file);
+			const messages = records.filter((record) => record.type === "message").map((record) => record.message);
+			const assistants = messages.filter((message) => message?.role === "assistant");
+			const usage = assistants.map((message) => message.usage).filter(Boolean);
+			const badUsage = assistants.map((message) => message.usage).filter(isBadUsage);
+			const fileFailure = lineCount === 0 || parseErrorCount > 0 || assistants.length === 0 || usage.length !== assistants.length || badUsage.length > 0;
+			if (fileFailure) failures += 1;
+			summary = {
+				file: relative(smokeDir, file),
+				lineCount,
+				parseErrorCount,
+				messageCount: messages.length,
+				assistantCount: assistants.length,
+				usageCount: usage.length,
+				badUsageCount: badUsage.length,
+			};
+		} catch (error) {
+			failures += 1;
+			summary = {
+				file: relative(smokeDir, file),
+				readError: error instanceof Error ? error.message : String(error),
+			};
+		}
+		console.log(JSON.stringify(summary));
+	}
+
+	process.exit(failures === 0 ? 0 : 1);
+}
+
+main();

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-edit-diff.ts

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

package/src/cursor-env-boolean.ts

@@ -0,0 +1,22 @@
+const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "none", "no", "disabled"]);
+const ENABLED_ENV_VALUES = new Set(["1", "true", "on", "yes", "enabled"]);
+
+function normalizeEnvBoolean(raw: string | undefined): string | undefined {
+	const normalized = raw?.trim().toLowerCase();
+	return normalized || undefined;
+}
+
+export function parseOptionalEnvBoolean(raw: string | undefined): boolean | undefined {
+	const normalized = normalizeEnvBoolean(raw);
+	if (!normalized) return undefined;
+	if (DISABLED_ENV_VALUES.has(normalized)) return false;
+	if (ENABLED_ENV_VALUES.has(normalized)) return true;
+	return undefined;
+}
+
+export function parseEnvBoolean(
+	raw: string | undefined,
+	defaultValue: boolean,
+): boolean {
+	return parseOptionalEnvBoolean(raw) ?? defaultValue;
+}

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