pi-cursor-sdk 0.1.20 → 0.1.22

package/shared/cursor-sensitive-text.d.mts

@@ -0,0 +1 @@
+export declare function scrubSensitiveText(text: string, apiKey?: string): string;

package/{scripts/lib/cursor-probe-utils.mjs → shared/cursor-sensitive-text.mjs}

@@ -1,21 +1,9 @@
-export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+/** Canonical secret/bridge scrubbing (parity-tested by provider runtime and maintainer scripts). */
 
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-export function resolveCursorSettingSources(raw) {
-	const trimmed = raw?.trim();
-	if (!trimmed) return ["all"];
-	const normalized = trimmed.toLowerCase();
-	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
-	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
-	return trimmed
-		.split(",")
-		.map((entry) => entry.trim())
-		.filter(Boolean);
-}
-
 const BRIDGE_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
 const BRIDGE_ENDPOINT_TOKEN_PATTERN = "[^/\\s\"'<>]+";
 const BRIDGE_LOOPBACK_HOST_PATTERN = "127\\.0\\.0\\.1(?::\\d+)?";

package/shared/cursor-setting-sources.d.mts

@@ -0,0 +1,5 @@
+export declare const CURSOR_SETTING_SOURCES_ENV: "PI_CURSOR_SETTING_SOURCES";
+
+export declare function resolveCursorSettingSources(raw?: string): string[] | undefined;
+
+export declare function serializeCursorSettingSources(settingSources: string[] | undefined): string;

package/shared/cursor-setting-sources.mjs

@@ -0,0 +1,22 @@
+/** Canonical Cursor settingSources parsing (parity-tested by provider runtime and maintainer scripts). */
+export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+
+export function resolveCursorSettingSources(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return ["all"];
+	const normalized = trimmed.toLowerCase();
+	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
+	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
+	const sources = trimmed
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+	if (sources.length === 0) return undefined;
+	return sources;
+}
+
+/** Serialize parsed settingSources for PI_CURSOR_SETTING_SOURCES (undefined => explicit none). */
+export function serializeCursorSettingSources(settingSources) {
+	if (settingSources === undefined || settingSources.length === 0) return "none";
+	return settingSources.join(",");
+}

package/src/context.ts

@@ -2,7 +2,6 @@ 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 {
@@ -14,6 +13,8 @@ export interface CursorPromptOptions {
 	maxInputTokens?: number;
 	charsPerToken?: number;
 	imageTokenEstimate?: number;
+	/** Compact callable-surface summary; included on bootstrap prompts when set. */
+	toolManifest?: string;
 }
 
 export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
@@ -21,20 +22,25 @@ 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.";
+	return [
+		"Shell: use an explicit `cd` to the repo path when running project commands; session cwd may not match paths in tool args.",
+		"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.",
+	].join("\n");
 }
 
-function getCursorToolBoundaryText(): string {
-	return [
+function getCursorToolBoundaryText(options: { hasToolManifest?: boolean } = {}): string {
+	const lines = [
 		"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.",
+		"Call only tools exposed by Cursor SDK in this run. Pi tool names, replay labels, and transcript names are context only—not callable.",
+		"Bridged pi tools: call pi__* MCP names when exposed, not the pi card name in history. Replay activity is display-only.",
+		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor executes an equivalent tool.",
 		"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");
+		"Images: only the latest user message's images are sent as bytes; ask to reattach or describe prior images.",
+	];
+	if (options.hasToolManifest) {
+		lines.push("See callable tool surfaces block below.");
+	}
+	return lines.join("\n");
 }
 
 function getCursorBootstrapTailSections(): string[] {
@@ -370,7 +376,10 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 }
 
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText()];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ hasToolManifest: Boolean(options.toolManifest) })];
+	if (options.toolManifest) {
+		sectionsBeforeMessages.push(options.toolManifest);
+	}
 
 	if (context.systemPrompt) {
 		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);

package/src/cursor-bridge-contract.ts

@@ -20,8 +20,6 @@ export function buildCursorPiBridgeMcpToolDescription(options: {
 }): string {
 	return [
 		options.piToolDescription,
-		"",
-		getCursorPiBridgeContractText(),
-		`This run exposes real pi tool ${options.piToolName} as Cursor MCP tool ${options.mcpToolName}.`,
+		`Call MCP name ${options.mcpToolName} (pi tool: ${options.piToolName}). Full tool-surface rules are in the session bootstrap prompt.`,
 	].join("\n");
 }

package/src/cursor-incomplete-tool-visibility.ts

@@ -5,6 +5,11 @@ import {
 	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
 	type DiscardedIncompleteStartedToolCallReason,
 } from "./cursor-sdk-event-debug.js";
+import {
+	assembleCursorReplayActivityDetails,
+	parseCursorReplayToolDetails,
+	resolveIncompleteReplayActivitySourceToolName,
+} from "./cursor-replay-tool-details.js";
 import { truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
 
@@ -87,6 +92,14 @@ export function buildIncompleteCursorToolDisplay(
 	const headline = `${activityTitle} did not complete`;
 	const reasonText = scrubSensitiveText(formatIncompleteCursorToolReasonText(reason), options.apiKey);
 	const contentText = `${headline}\n${reasonText}`;
+	const details = assembleCursorReplayActivityDetails(
+		resolveIncompleteReplayActivitySourceToolName(visibility.normalizedName),
+		headline,
+		{ summary: reasonText, expandedText: contentText },
+		contentText,
+		true,
+		reasonText,
+	);
 	return {
 		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 		args: {
@@ -97,17 +110,21 @@ export function buildIncompleteCursorToolDisplay(
 		},
 		result: {
 			content: [{ type: "text", text: contentText }],
-			details: {
-				cursorToolName: visibility.normalizedName,
-				title: headline,
-				summary: reasonText,
-			},
+			details,
 		},
 		isError: true,
 	};
 }
 
 export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): string {
+	const parsed = parseCursorReplayToolDetails(display.result.details);
+	if (parsed?.variant === "activity") {
+		const summary =
+			parsed.summary?.trim() ||
+			(typeof display.args.activitySummary === "string" && display.args.activitySummary.trim()) ||
+			formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
+		return `${truncateCursorDisplayLine(parsed.title)}: ${truncateCursorDisplayLine(summary)}\n`;
+	}
 	const details = display.result.details;
 	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
 	const argsRecord = display.args;

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

@@ -13,12 +13,19 @@ import {
 	NATIVE_CURSOR_TOOL_DISPLAY_ENV,
 	readBooleanEnv,
 	registeredNativeToolNames,
+	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-names.js";
 
-const CORE_PI_TOOL_NAMES = new Set(["read", "bash", "edit", "write"]);
+export const CURSOR_CORE_PI_REPLAY_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
+const CORE_PI_TOOL_NAMES = new Set<string>(CURSOR_CORE_PI_REPLAY_TOOL_NAMES);
 
-type CursorNativeToolRegistryApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools" | "registerTool" | "setActiveTools">;
+function isCursorCorePiReplayToolName(toolName: string): toolName is (typeof CURSOR_CORE_PI_REPLAY_TOOL_NAMES)[number] {
+	return CORE_PI_TOOL_NAMES.has(toolName);
+}
+
+type CursorNativeToolActivationApi = Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">;
+type CursorNativeToolRegistryApi = CursorNativeToolActivationApi & Pick<ExtensionAPI, "getAllTools" | "registerTool">;
 
 export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi {
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
@@ -34,7 +41,40 @@ function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: Nati
 
 type NativeRegistrationContext = { hasUI: boolean; ui: Pick<ExtensionContext["ui"], "notify">; model?: ExtensionContext["model"] };
 
-export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
+function registerNativeCursorToolsFromSet(
+	pi: CursorNativeToolRegistryApi,
+	toolNames: readonly NativeCursorToolName[],
+): NativeCursorToolName[] {
+	const newlySkippedToolNames: NativeCursorToolName[] = [];
+	for (const toolName of toolNames) {
+		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
+		if (hasNonBuiltinTool(pi, toolName)) {
+			skippedNativeToolNames.add(toolName);
+			newlySkippedToolNames.push(toolName);
+			continue;
+		}
+		registerNativeCursorTool(pi, toolName);
+		registeredNativeToolNames.add(toolName);
+	}
+	return newlySkippedToolNames;
+}
+
+function notifySkippedNativeCursorToolsIfNeeded(ctx: NativeRegistrationContext, skippedToolNames: readonly NativeCursorToolName[]): void {
+	if (skippedToolNames.length === 0 || readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== true || !ctx.hasUI) return;
+	ctx.ui.notify(
+		`Cursor native tool replay skipped for ${skippedToolNames.join(", ")} because another extension already provides ${skippedToolNames.length === 1 ? "that tool" : "those tools"}. Cursor will use scrubbed activity transcripts for skipped tools.`,
+		"warning",
+	);
+}
+
+function hasAttemptedNativeCursorToolRegistration(): boolean {
+	return registeredNativeToolNames.size > 0 || skippedNativeToolNames.size > 0;
+}
+
+export function syncRegisteredNativeCursorToolsForModel(
+	pi: CursorNativeToolActivationApi,
+	model: ExtensionContext["model"],
+): void {
 	if (registeredNativeToolNames.size === 0) return;
 	const activeToolNames = new Set(pi.getActiveTools());
 	let changed = false;
@@ -47,7 +87,7 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 		}
 	} else {
 		for (const toolName of registeredNativeToolNames) {
-			if (CORE_PI_TOOL_NAMES.has(toolName)) continue;
+			if (isCursorCorePiReplayToolName(toolName)) continue;
 			if (!activeToolNames.delete(toolName)) continue;
 			changed = true;
 		}
@@ -55,45 +95,41 @@ export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-function registerAvailableNativeCursorTools(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	if (!isCursorNativeToolRegistrationRequested()) {
 		registeredNativeToolNames.clear();
+		skippedNativeToolNames.clear();
 		return;
 	}
+	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
-	const skippedToolNames: string[] = [];
-	for (const toolName of NATIVE_CURSOR_TOOL_NAMES) {
-		if (registeredNativeToolNames.has(toolName)) continue;
-		if (hasNonBuiltinTool(pi, toolName)) {
-			skippedToolNames.push(toolName);
-			continue;
-		}
-		registerNativeCursorTool(pi, toolName);
-		registeredNativeToolNames.add(toolName);
-	}
-
-	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
+	const skippedToolNames = [
+		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
+		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
+	];
+	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
+}
 
-	if (skippedToolNames.length > 0 && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) === true && ctx.hasUI) {
-		ctx.ui.notify(
-			`Cursor native tool replay skipped for ${skippedToolNames.join(", ")} because another extension already provides ${skippedToolNames.length === 1 ? "that tool" : "those tools"}. Cursor will use scrubbed activity transcripts for skipped tools.`,
-			"warning",
-		);
+function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
+		ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	}
+	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
 	pi.on("session_start", (_event, ctx) => {
-		registerAvailableNativeCursorTools(pi, ctx);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 	pi.on("before_agent_start", (_event, ctx) => {
-		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 	pi.on("turn_start", (_event, ctx) => {
-		syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
-	pi.on("model_select", (event) => {
-		syncRegisteredNativeCursorToolsForModel(pi, event.model);
+	pi.on("model_select", (event, ctx) => {
+		ensureThenSyncNativeCursorToolsForModel(pi, { ...ctx, model: event.model });
 	});
 }