pi-cursor-sdk 0.2.0 → 0.3.7

package/src/context.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { getCursorConversationMessages, resolveCursorPiContext } from "./cursor-pi-context.js";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { AgentModeOption, SDKImage } from "@cursor/sdk";
@@ -85,7 +86,7 @@ function getCursorBootstrapTailSections(
 }
 
 function normalizePiContextMessages(messages: Context["messages"]): Message[] {
-	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+	return convertToLlm(getCursorConversationMessages({ messages }) as Parameters<typeof convertToLlm>[0]);
 }
 
 function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
@@ -137,6 +138,15 @@ function formatToolCall(toolCall: ToolCall): string {
 
 function sanitizeSystemPromptForCursor(systemPrompt: string): string {
 	let sanitized = systemPrompt;
+	// Transcript-era Pi wraps its built-in tool catalog/rules in XML sections.
+	sanitized = sanitized.replace(
+		/<tools>\n[\s\S]*?\n\nIn addition to the tools above, you may have access to other custom tools depending on the project\.\n<\/tools>/g,
+		"Pi tool catalog omitted: Cursor can call only Cursor SDK tools exposed in this run.",
+	);
+	sanitized = sanitized.replace(
+		/<rules>\n[\s\S]*?\n<\/rules>\n\n(?=<docs>\nPi documentation )/g,
+		"<rules>\n- Be concise in your responses.\n- Show file paths clearly when working with files.\n</rules>\n\n",
+	);
 	sanitized = sanitized.replace(
 		/Available tools:\n[\s\S]*?\n\nIn addition to the tools above, you may have access to other custom tools depending on the project\.\n\n/g,
 		"Pi tool catalog omitted: Cursor can call only Cursor SDK tools exposed in this run.\n\n",
@@ -279,12 +289,24 @@ function serializeMessageForFingerprint(message: Message, index: number): string
 			return hashCursorContextValue(
 				`toolResult:${message.timestamp ?? index}:${message.toolCallId}:${message.toolName}:${JSON.stringify(message.content)}:${message.isError === true}`,
 			);
+		default:
+			// System messages are handled by serializeRawPiMessageForFingerprint.
+			throw new Error("Unsupported Pi message role in Cursor context fingerprint.");
 	}
 }
 
 function serializeRawPiMessageForFingerprint(message: Context["messages"][number], index: number): string {
 	const role = (message as { role?: string }).role;
 	switch (role) {
+		case "system": {
+			const entry = message as {
+				content: unknown; sections?: unknown; toolsAdded?: unknown; toolsRemoved?: unknown;
+			};
+			return hashCursorContextValue(JSON.stringify({
+				role, content: entry.content, sections: entry.sections,
+				toolsAdded: entry.toolsAdded, toolsRemoved: entry.toolsRemoved,
+			}));
+		}
 		case "branchSummary": {
 			const entry = message as { summary?: string; fromId?: string; timestamp?: number };
 			return hashCursorContextValue(
@@ -337,7 +359,7 @@ function parseCursorContextFingerprint(fingerprint: string): CursorContextFinger
 
 export function computeCursorContextFingerprint(context: Context): string {
 	const payload: CursorContextFingerprintPayload = {
-		systemHash: hashCursorContextValue(context.systemPrompt ?? ""),
+		systemHash: hashCursorContextValue(JSON.stringify(resolveCursorPiContext(context))),
 		messageHashes: context.messages.map((message, index) => serializeRawPiMessageForFingerprint(message, index)),
 	};
 	return JSON.stringify(payload);
@@ -412,8 +434,9 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages.push(options.toolManifest);
 	}
 
-	if (context.systemPrompt) {
-		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
+	const { systemPrompt } = resolveCursorPiContext(context);
+	if (systemPrompt) {
+		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(systemPrompt)}`);
 	}
 
 	const messages = normalizePiContextMessages(context.messages);

package/src/cursor-agents-context-registration.ts

@@ -1,14 +1,14 @@
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
 import { resolveEffectiveCursorConfigForContext } from "./cursor-runtime-state.js";
+import { resolveCursorFacingSystemPrompt } from "./cursor-agents-context.js";
 
 export type CursorAgentsContextExtensionApi = CursorModelLifecycleExtensionApi;
 
 export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
 	registerCursorModelLifecycle(pi, {
-		beforeAgentStart: async (event, ctx) => {
+		beforeAgentStart: (event, ctx) => {
 			if (!isCursorModel(ctx.model)) return undefined;
-			const { resolveCursorFacingSystemPrompt } = await import("./cursor-agents-context.js");
 			const runtime = resolveEffectiveCursorConfigForContext(ctx).runtime.value;
 			const resolved = resolveCursorFacingSystemPrompt(
 				event.systemPrompt,

package/src/cursor-agents-context.ts

@@ -12,8 +12,6 @@ import {
 } from "./cursor-setting-sources.js";
 import type { SettingSource } from "@cursor/sdk";
 import type { CursorRuntime } from "./cursor-config.js";
-export { registerCursorAgentsContextDedup, type CursorAgentsContextExtensionApi } from "./cursor-agents-context-registration.js";
-
 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). */
@@ -116,9 +114,21 @@ export function serializePiProjectInstructionsBlock(file: PiAgentsContextFile):
 	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 {
+/** The two supported Pi project-context serializations; legacy includes outer spacing. */
+export function serializePiProjectContextSection(
+	contextFiles: readonly PiAgentsContextFile[],
+	format: "legacy" | "transcript" = "legacy",
+): string {
 	if (contextFiles.length === 0) return "";
+	if (format === "transcript") {
+		return [
+			"<project_context>",
+			"Project-specific instructions and guidelines:",
+			"",
+			contextFiles.map((file) => serializePiProjectInstructionsBlock(file).trimEnd()).join("\n\n"),
+			"</project_context>",
+		].join("\n");
+	}
 	return `${PI_PROJECT_CONTEXT_OPEN}${contextFiles.map(serializePiProjectInstructionsBlock).join("")}${PI_PROJECT_CONTEXT_CLOSE}`;
 }
 
@@ -140,12 +150,16 @@ export function removePiAgentsContextFromSystemPrompt(
 	}
 	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);
+	// Match only the exact known files in either supported serialization; never
+	// strip arbitrary user-authored XML or neighboring custom sections.
+	for (const format of ["legacy", "transcript"] as const) {
+		const originalSection = serializePiProjectContextSection(contextFiles, format);
+		const start = systemPrompt.indexOf(originalSection);
+		if (start < 0) continue;
+		const replacementSection = serializePiProjectContextSection(retainedContextFiles, format);
+		return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+	}
+	return systemPrompt;
 }
 
 export function resolveCursorFacingSystemPrompt(

package/src/cursor-api-key.ts

@@ -1,3 +1,5 @@
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+
 export const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
 const CURSOR_PROVIDER_ID = "cursor";
 
@@ -21,9 +23,8 @@ export function resolveCursorApiKey(apiKey?: string): string | undefined {
 	return trimmed;
 }
 
-async function getStoredCursorApiKey(): Promise<string | undefined> {
+function getStoredCursorApiKey(): string | undefined {
 	try {
-		const { readStoredCredential } = await import("@earendil-works/pi-coding-agent");
 		const credential = readStoredCredential(CURSOR_PROVIDER_ID);
 		return resolveCursorApiKey(credential?.type === "api_key" ? credential.key : undefined);
 	} catch {
@@ -31,6 +32,6 @@ async function getStoredCursorApiKey(): Promise<string | undefined> {
 	}
 }
 
-export async function resolveCursorRuntimeApiKey(): Promise<string | undefined> {
-	return (await getStoredCursorApiKey()) ?? resolveCursorApiKey(process.env.CURSOR_API_KEY);
+export function resolveCursorRuntimeApiKey(): Promise<string | undefined> {
+	return Promise.resolve(getStoredCursorApiKey() ?? resolveCursorApiKey(process.env.CURSOR_API_KEY));
 }

package/src/cursor-cloud-reporting.ts

@@ -170,17 +170,38 @@ export async function fetchCursorCloudRawUsage(
 	}
 }
 
+function mapCursorSdkAgentUsageToCloudReport(value: unknown, runId?: string): CursorCloudUsageReport | undefined {
+	const record = asRecord(value);
+	const runs = (getArray(record, "runs") ?? []).map(asRecord);
+	const matchingRun = runId ? runs.find((run) => getString(run, "runId") === runId) : undefined;
+	return normalizeUsage({
+		totalUsage: getRecord(record, "usage"),
+		runUsage: getRecord(matchingRun, "usage"),
+	});
+}
+
 export async function collectCursorCloudRunReport(options: {
 	agent: SDKAgent;
 	run: Run;
 	waitResult: RunResult;
 	apiKey: string | undefined;
+	agentUsage?: unknown;
 }): Promise<CursorCloudRunReport> {
 	const listArtifacts = options.agent.listArtifacts;
-	const [artifactResult, usage] = await Promise.all([
+	const sdkUsage =
+		options.agentUsage !== undefined
+			? mapCursorSdkAgentUsageToCloudReport(options.agentUsage, options.run.id)
+			: typeof options.agent.getUsage === "function"
+				? mapCursorSdkAgentUsageToCloudReport(
+					await withTimeout(Promise.resolve(options.agent.getUsage({ runId: options.run.id }))),
+					options.run.id,
+				)
+				: undefined;
+	const [artifactResult, restUsage] = await Promise.all([
 		typeof listArtifacts === "function" ? withTimeout(listArtifacts.call(options.agent)) : undefined,
-		fetchCursorCloudRawUsage({ agentId: options.run.agentId, runId: options.run.id, apiKey: options.apiKey }),
+		sdkUsage ? undefined : fetchCursorCloudRawUsage({ agentId: options.run.agentId, runId: options.run.id, apiKey: options.apiKey }),
 	]);
+	const usage = sdkUsage ?? restUsage;
 	const waitBranches = getArray(getRecord(asRecord(options.waitResult), "git"), "branches");
 	const runBranches = getArray(getRecord(asRecord(options.run), "git"), "branches");
 	return {

package/src/cursor-context-tools.ts

@@ -1,6 +1,8 @@
 import type { Context } from "@earendil-works/pi-ai";
+import { resolveCursorPiContext } from "./cursor-pi-context.js";
 
 /** 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;
+	const { tools } = resolveCursorPiContext(context);
+	return tools === undefined ? undefined : new Set(tools.map((tool) => tool.name));
 }