pi-cursor-sdk 0.1.37 → 0.1.39

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

@@ -1,12 +1,12 @@
-import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler, SessionStartEvent, TurnStartEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
 	NATIVE_CURSOR_TOOL_NAMES,
-	registerNativeCursorTool,
 	type NativeCursorToolName,
-} from "./cursor-native-tool-display-tools.js";
+} from "./cursor-native-tool-names.js";
 import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
 import {
 	isCursorNativeToolDisplayRequested,
 	isCursorNativeToolRegistrationRequested,
@@ -15,7 +15,7 @@ import {
 	registeredNativeToolNames,
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
-import { isCursorReplayToolName } from "./cursor-tool-names.js";
+import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
 
 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);
@@ -27,12 +27,7 @@ function isCursorCorePiReplayToolName(toolName: string): toolName is (typeof CUR
 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;
-	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent>): void;
-	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
-	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
-}
+export interface CursorNativeToolDisplayExtensionApi extends CursorNativeToolRegistryApi, CursorModelLifecycleExtensionApi {}
 
 function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: NativeCursorToolName): boolean {
 	const existingTool = pi.getAllTools().find((tool) => tool.name === toolName);
@@ -43,11 +38,12 @@ type NativeRegistrationContext = Pick<ExtensionContext, "mode" | "model"> & {
 	ui: Pick<ExtensionContext["ui"], "notify">;
 };
 
-function registerNativeCursorToolsFromSet(
+async function registerNativeCursorToolsFromSet(
 	pi: CursorNativeToolRegistryApi,
 	toolNames: readonly NativeCursorToolName[],
-): NativeCursorToolName[] {
+): Promise<NativeCursorToolName[]> {
 	const newlySkippedToolNames: NativeCursorToolName[] = [];
+	let registerNativeCursorTool: ((pi: CursorNativeToolRegistryApi, toolName: NativeCursorToolName) => void) | undefined;
 	for (const toolName of toolNames) {
 		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
 		if (hasNonBuiltinTool(pi, toolName)) {
@@ -55,6 +51,7 @@ function registerNativeCursorToolsFromSet(
 			newlySkippedToolNames.push(toolName);
 			continue;
 		}
+		registerNativeCursorTool ??= (await import("./cursor-native-tool-display-tools.js")).registerNativeCursorTool;
 		registerNativeCursorTool(pi, toolName);
 		registeredNativeToolNames.add(toolName);
 	}
@@ -97,7 +94,7 @@ export function syncRegisteredNativeCursorToolsForModel(
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
 	if (!isCursorNativeToolRegistrationRequested()) {
 		registeredNativeToolNames.clear();
 		skippedNativeToolNames.clear();
@@ -107,31 +104,22 @@ function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryA
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
-		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
-		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
+		...(await registerNativeCursorToolsFromSet(pi, nonCoreToolNames)),
+		...(await registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES)),
 	];
 	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
 }
 
-function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
+async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
 	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
-		ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+		await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	}
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
-	pi.on("session_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("before_agent_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("turn_start", (_event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
-	});
-	pi.on("model_select", (event, ctx) => {
-		ensureThenSyncNativeCursorToolsForModel(pi, { ...ctx, model: event.model });
+	registerCursorModelLifecycle(pi, async (ctx) => {
+		await ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 }
 

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

@@ -1,9 +1,10 @@
 import { readFileSync, statSync } from "node:fs";
-import { basename, extname } from "node:path";
+import { basename } from "node:path";
 import { getLanguageFromPath, highlightCode, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Image, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
+import { inferImageMimeType } from "./cursor-tool-result-display-readers.js";
 import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-transcript-utils.js";
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
@@ -17,7 +18,6 @@ import {
 	type CursorReplayActivityDetails,
 	type CursorReplayToolDetails,
 	type CursorReplayNativeWriteDetails,
-	isCursorReplayNativeEditDetails,
 	isCursorReplayGenerateImageDetails,
 	isCursorReplayActivityDetails,
 	parseCursorReplayToolDetails,
@@ -49,22 +49,6 @@ type CursorReplayRenderCall = NonNullable<ToolDefinition<typeof cursorReplayTool
 type CursorReplayRenderResult = NonNullable<ToolDefinition<typeof cursorReplayToolSchema, unknown>["renderResult"]>;
 export type CursorReplayRenderTheme = Parameters<CursorReplayRenderCall>[1];
 
-function inferImageMimeTypeFromPath(path: string | undefined): string | undefined {
-	switch (extname(path ?? "").toLowerCase()) {
-		case ".png":
-			return "image/png";
-		case ".jpg":
-		case ".jpeg":
-			return "image/jpeg";
-		case ".gif":
-			return "image/gif";
-		case ".webp":
-			return "image/webp";
-		default:
-			return undefined;
-	}
-}
-
 function readImageFileForReplay(path: string | undefined): string | undefined {
 	if (!path) return undefined;
 	try {
@@ -464,7 +448,7 @@ function renderExpandableCursorReplayResult(
 	}
 	if (details.imagePath && !isError && context.showImages) {
 		const imageData = readImageFileForReplay(details.imagePath);
-		const mimeType = details.imageMimeType ?? inferImageMimeTypeFromPath(details.imagePath);
+		const mimeType = details.imageMimeType ?? inferImageMimeType(details.imagePath);
 		if (imageData && mimeType) return buildImageReplayComponent(rendered, imageData, mimeType, basename(details.imagePath ?? "generated-image"), theme);
 	}
 	return new Text(rendered, 0, 0);
@@ -485,7 +469,6 @@ function renderCursorReplayEditResult(
 function renderCursorReplayWriteResult(
 	details: CursorReplayNativeWriteDetails,
 	result: Parameters<CursorReplayRenderResult>[0],
-	options: Parameters<CursorReplayRenderResult>[1],
 	theme: Parameters<CursorReplayRenderResult>[2],
 ): Component {
 	const text = firstContentText(result);
@@ -532,7 +515,7 @@ function renderCursorReplayDetails(
 		case "nativeEdit":
 			return renderCursorReplayEditResult(details, options, theme);
 		case "nativeWrite":
-			return renderCursorReplayWriteResult(details, result, options, theme);
+			return renderCursorReplayWriteResult(details, result, theme);
 		case "generateImage":
 			return renderCursorGenerateImageResult(details, result, options, theme, context, isError);
 		case "activity":

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

@@ -1,4 +1,4 @@
-import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { parseOptionalEnvBoolean } from "./cursor-env-boolean.js";
 
 export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {

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

@@ -10,11 +10,17 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
-import { getCursorSessionCwd } from "./cursor-session-cwd.js";
+import { getCursorSessionCwd } from "./cursor-session-scope.js";
 import {
-	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	isCursorReplayToolName,
-} from "./cursor-tool-names.js";
+	BUILTIN_NATIVE_CURSOR_TOOL_NAMES,
+	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
+	CURSOR_REPLAY_TOOL_NAMES,
+	isNativeCursorToolName,
+	NATIVE_CURSOR_TOOL_NAMES,
+	type BuiltinNativeCursorToolName,
+	type NativeCursorToolName,
+} from "./cursor-native-tool-names.js";
+import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
 import {
 	createCursorReplayOnlyToolDefinition,
 	isCursorReplayNativeEditDetails,
@@ -29,8 +35,6 @@ import {
 	isCursorReplayToolCallId,
 } from "./cursor-native-tool-display-state.js";
 
-const CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
-const CURSOR_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
 
 type AnyToolDefinition = ToolDefinition<TSchema, unknown, unknown>;
 type RenderCall = NonNullable<AnyToolDefinition["renderCall"]>;
@@ -117,8 +121,6 @@ function renderWriteReplayResult(
 		: renderBase();
 }
 
-type BuiltinNativeCursorToolName = "read" | "bash" | "edit" | "write" | "grep" | "find" | "ls";
-
 const NATIVE_CURSOR_TOOL_STRATEGIES: Record<BuiltinNativeCursorToolName, NativeReplayStrategy> = {
 	read: {
 		createDefinition: (cwd) => createReadToolDefinition(cwd) as AnyToolDefinition,
@@ -145,12 +147,6 @@ const NATIVE_CURSOR_TOOL_STRATEGIES: Record<BuiltinNativeCursorToolName, NativeR
 	ls: { createDefinition: (cwd) => createLsToolDefinition(cwd) as AnyToolDefinition },
 };
 
-const BUILTIN_NATIVE_CURSOR_TOOL_NAMES = Object.keys(NATIVE_CURSOR_TOOL_STRATEGIES) as BuiltinNativeCursorToolName[];
-export const NATIVE_CURSOR_TOOL_NAMES = [
-	...BUILTIN_NATIVE_CURSOR_TOOL_NAMES,
-	...CURSOR_REPLAY_TOOL_NAMES,
-] as readonly NativeCursorToolName[];
-export type NativeCursorToolName = BuiltinNativeCursorToolName | typeof CURSOR_REPLAY_TOOL_NAMES[number];
 
 function getNativeReplayStrategy(toolName: string): NativeReplayStrategy | undefined {
 	return Object.hasOwn(NATIVE_CURSOR_TOOL_STRATEGIES, toolName)
@@ -158,9 +154,6 @@ function getNativeReplayStrategy(toolName: string): NativeReplayStrategy | undef
 		: undefined;
 }
 
-export function isNativeCursorToolName(toolName: string): toolName is NativeCursorToolName {
-	return NATIVE_CURSOR_TOOL_NAMES.some((nativeToolName) => nativeToolName === toolName);
-}
 
 export function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 	definition: ToolDefinition<TParams, TDetails, TState>,

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

@@ -0,0 +1,16 @@
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME } from "./cursor-tool-presentation-registry.js";
+
+export const CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
+export const CURSOR_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
+export const BUILTIN_NATIVE_CURSOR_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
+export const NATIVE_CURSOR_TOOL_NAMES = [
+	...BUILTIN_NATIVE_CURSOR_TOOL_NAMES,
+	...CURSOR_REPLAY_TOOL_NAMES,
+] as readonly NativeCursorToolName[];
+
+export type BuiltinNativeCursorToolName = typeof BUILTIN_NATIVE_CURSOR_TOOL_NAMES[number];
+export type NativeCursorToolName = BuiltinNativeCursorToolName | typeof CURSOR_REPLAY_TOOL_NAMES[number];
+
+export function isNativeCursorToolName(toolName: string): toolName is NativeCursorToolName {
+	return NATIVE_CURSOR_TOOL_NAMES.some((nativeToolName) => nativeToolName === toolName);
+}

package/src/cursor-pi-tool-bridge-env.ts

@@ -0,0 +1,12 @@
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+
+export const CURSOR_PI_TOOL_BRIDGE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE";
+export const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+
+export function resolveCursorPiToolBridgeEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
+}
+
+export function resolveCursorPiToolBridgeBuiltinsEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV], false);
+}

package/src/cursor-pi-tool-bridge-mcp.ts

@@ -3,19 +3,17 @@ import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
 import { buildCursorPiBridgeMcpToolDescription, CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX } from "./cursor-bridge-contract.js";
 import type { CursorPiBridgeToolDefinition, CursorPiMcpInputSchema } from "./cursor-pi-tool-bridge-types.js";
-import { getFirstStringByKeys } from "./cursor-record-utils.js";
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
+import { asRecord, stringifyUnknown } from "./cursor-record-utils.js";
 
 export function normalizeMcpInputSchema(schema: unknown): CursorPiMcpInputSchema {
-	if (isRecord(schema) && schema.type === "object") return schema as CursorPiMcpInputSchema;
+	const record = asRecord(schema);
+	if (record?.type === "object") return record as CursorPiMcpInputSchema;
 	return { type: "object", properties: {} };
 }
 
 export function normalizeMcpArgs(args: unknown): Record<string, unknown> {
-	return isRecord(args) ? { ...args } : {};
+	const record = asRecord(args);
+	return record ? { ...record } : {};
 }
 
 export function waitForProtocolFlush(): Promise<void> {
@@ -73,21 +71,21 @@ export function snapshotToolToMcpTool(tool: CursorPiBridgeToolDefinition): Tool
 
 export function convertPiContentToMcpContent(content: unknown): CallToolResult["content"] {
 	if (!Array.isArray(content)) {
-		return [{ type: "text", text: typeof content === "string" ? content : JSON.stringify(content) }];
+		return [{ type: "text", text: stringifyUnknown(content) }];
 	}
 
 	const mcpContent: CallToolResult["content"] = [];
 	for (const block of content) {
-		if (!isRecord(block)) continue;
-		if (block.type === "text" && typeof block.text === "string") {
-			mcpContent.push({ type: "text", text: block.text });
+		const record = asRecord(block);
+		if (record?.type === "text" && typeof record.text === "string") {
+			mcpContent.push({ type: "text", text: record.text });
 			continue;
 		}
-		if (block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
-			mcpContent.push({ type: "image", data: block.data, mimeType: block.mimeType });
+		if (record?.type === "image" && typeof record.data === "string" && typeof record.mimeType === "string") {
+			mcpContent.push({ type: "image", data: record.data, mimeType: record.mimeType });
 			continue;
 		}
-		mcpContent.push({ type: "text", text: JSON.stringify(block) });
+		mcpContent.push({ type: "text", text: stringifyUnknown(block) });
 	}
 
 	return mcpContent.length > 0 ? mcpContent : [{ type: "text", text: "" }];
@@ -97,22 +95,19 @@ export function asToolResultMessage(value: Context["messages"][number]): ToolRes
 	return value.role === "toolResult" ? value : undefined;
 }
 
-export function getStringField(record: Record<string, unknown>, fields: string[]): string | undefined {
-	return getFirstStringByKeys(record, fields, { nonEmpty: true });
-}
-
 export function containsKnownMcpToolName(value: unknown, knownMcpToolNames: ReadonlySet<string>, depth = 0): boolean {
 	if (depth > 4) return false;
 	if (Array.isArray(value)) return value.some((entry) => containsKnownMcpToolName(entry, knownMcpToolNames, depth + 1));
-	if (!isRecord(value)) return false;
+	const record = asRecord(value);
+	if (!record) return false;
 
 	for (const field of ["tool", "toolName", "name", "mcpToolName", "serverToolName"]) {
-		const fieldValue = value[field];
+		const fieldValue = record[field];
 		if (typeof fieldValue === "string" && knownMcpToolNames.has(fieldValue)) return true;
 	}
 
 	for (const nestedField of ["args", "arguments", "input"]) {
-		if (containsKnownMcpToolName(value[nestedField], knownMcpToolNames, depth + 1)) return true;
+		if (containsKnownMcpToolName(record[nestedField], knownMcpToolNames, depth + 1)) return true;
 	}
 
 	return false;

package/src/cursor-pi-tool-bridge-run.ts

@@ -27,12 +27,11 @@ import {
 	asToolResultMessage,
 	containsKnownMcpToolName,
 	convertPiContentToMcpContent,
-	getStringField,
-	isRecord,
 	normalizeMcpArgs,
 	snapshotToolToMcpTool,
 	waitForProtocolFlush,
 } from "./cursor-pi-tool-bridge-mcp.js";
+import { asRecord, getFirstStringByKeys } from "./cursor-record-utils.js";
 
 export interface CursorPiToolBridgeRunHost {
 	registerRun(pathname: string, run: CursorPiToolBridgeRunImpl): Promise<string>;
@@ -178,12 +177,13 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	}
 
 	isBridgeMcpToolCall(toolCall: unknown): boolean {
-		if (!isRecord(toolCall)) return false;
-		const toolName = getStringField(toolCall, ["name", "toolName", "mcpToolName"]);
+		const record = asRecord(toolCall);
+		if (!record) return false;
+		const toolName = getFirstStringByKeys(record, ["name", "toolName", "mcpToolName"], { nonEmpty: true });
 		if (toolName && this.knownMcpToolNames.has(toolName)) return true;
 
 		const isMcpEnvelope = toolName === "mcp" || toolName === MCP_SERVER_NAME;
-		const cursorMcpCallId = getStringField(toolCall, ["call_id", "callId", "id", "toolCallId", "requestId"]);
+		const cursorMcpCallId = getFirstStringByKeys(record, ["call_id", "callId", "id", "toolCallId", "requestId"], { nonEmpty: true });
 		if (cursorMcpCallId && this.knownCursorMcpCallIds.has(cursorMcpCallId) && isMcpEnvelope) return true;
 
 		if (containsKnownMcpToolName(toolCall, this.knownMcpToolNames)) return true;

package/src/cursor-pi-tool-bridge-server.ts

@@ -6,7 +6,7 @@ import type {
 	CursorPiToolBridgeRunOptions,
 	CursorPiToolBridgeSnapshotApi,
 } from "./cursor-pi-tool-bridge-types.js";
-import { isRecord } from "./cursor-pi-tool-bridge-mcp.js";
+import { asRecord } from "./cursor-record-utils.js";
 import type { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
 import {
 	buildCursorPiToolBridgeSnapshot,
@@ -84,8 +84,13 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	}
 
 	getHttpServerAddress(): AddressInfo | undefined {
-		const address = this.httpServer?.address();
-		return isRecord(address) && typeof address.port === "number" ? address as AddressInfo : undefined;
+		const address = asRecord(this.httpServer?.address());
+		if (typeof address?.port !== "number") return undefined;
+		return {
+			address: typeof address.address === "string" ? address.address : LOOPBACK_HOST,
+			family: typeof address.family === "string" ? address.family : "IPv4",
+			port: address.port,
+		};
 	}
 
 	getEndpointCount(): number {

package/src/cursor-pi-tool-bridge-snapshot.ts

@@ -4,13 +4,15 @@ import type {
 	CursorPiToolBridgeSnapshotApi,
 	CursorPiToolBridgeSnapshotOptions,
 } from "./cursor-pi-tool-bridge-types.js";
-import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { createMcpToolName, normalizeMcpInputSchema, stableNameHash } from "./cursor-pi-tool-bridge-mcp.js";
+export {
+	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
+	CURSOR_PI_TOOL_BRIDGE_ENV,
+	resolveCursorPiToolBridgeBuiltinsEnabled,
+	resolveCursorPiToolBridgeEnabled,
+} from "./cursor-pi-tool-bridge-env.js";
 import { isRegisteredCursorNativeToolName } from "./cursor-native-tool-display-state.js";
-import { isExcludedFromCursorBridgeExposure } from "./cursor-tool-names.js";
-
-export const CURSOR_PI_TOOL_BRIDGE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE";
-export const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+import { isExcludedFromCursorBridgeExposure } from "./cursor-tool-presentation-registry.js";
 
 const OVERLAPPING_CURSOR_NATIVE_PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "write", "edit", "grep", "find", "ls"]);
 
@@ -22,14 +24,6 @@ export function createEmptySnapshot(): CursorPiToolBridgeSnapshot {
 	};
 }
 
-export function resolveCursorPiToolBridgeEnabled(env: Record<string, string | undefined> = process.env): boolean {
-	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
-}
-
-export function resolveCursorPiToolBridgeBuiltinsEnabled(env: Record<string, string | undefined> = process.env): boolean {
-	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV], false);
-}
-
 function isOverlappingCursorNativePiToolName(toolName: string): boolean {
 	return OVERLAPPING_CURSOR_NATIVE_PI_BUILTIN_TOOL_NAMES.has(toolName);
 }

package/src/cursor-pi-tool-bridge.ts

@@ -8,11 +8,7 @@ import {
 import {
 	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
 	CURSOR_PI_TOOL_BRIDGE_ENV,
-	buildCursorPiToolBridgeSnapshot,
-	buildCursorPiToolBridgeSurfaceSignature,
-	resolveCursorPiToolBridgeBuiltinsEnabled,
-	resolveCursorPiToolBridgeEnabled,
-} from "./cursor-pi-tool-bridge-snapshot.js";
+} from "./cursor-pi-tool-bridge-env.js";
 import { bridgeToolExecutionAbortTracker } from "./cursor-pi-tool-bridge-abort.js";
 import { MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
 import { LOOPBACK_HOST, CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
@@ -37,10 +33,14 @@ export type {
 export type { CursorPiToolBridgeDiagnosticEvent } from "./cursor-pi-tool-bridge-diagnostics.js";
 export { resolveCursorPiToolBridgeDebugEnabled } from "./cursor-pi-tool-bridge-diagnostics.js";
 export {
-	buildCursorPiToolBridgeSnapshot,
-	buildCursorPiToolBridgeSurfaceSignature,
+	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
+	CURSOR_PI_TOOL_BRIDGE_ENV,
 	resolveCursorPiToolBridgeBuiltinsEnabled,
 	resolveCursorPiToolBridgeEnabled,
+} from "./cursor-pi-tool-bridge-env.js";
+export {
+	buildCursorPiToolBridgeSnapshot,
+	buildCursorPiToolBridgeSurfaceSignature,
 } from "./cursor-pi-tool-bridge-snapshot.js";
 
 let registeredCursorPiToolBridge: CursorPiToolBridgeRegistry | undefined;

package/src/cursor-provider-errors.ts

@@ -8,10 +8,12 @@ const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request failed. The Cursor SDK API key may be missing, invalid, or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const AUTH_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request failed because the Cursor SDK API key may be invalid or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
+// Keep "Network error" aligned with pi's agent-level retry classifier.
 const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request failed during network or service I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
+	"Network error: Cursor SDK request failed during network or service I/O. Check your connection; pi will retry automatically when auto-retry is enabled.";
 
-const GENERIC_CURSOR_RUN_FAILURE_TEXT = "cursor sdk run failed";
+// Keep this phrase aligned with pi's agent-level retry classifier (`provider.?returned.?error`).
+const RETRYABLE_CURSOR_RUN_FAILURE_PREFIX = "Provider returned error: Cursor SDK run failed";
 
 export type CursorSdkRunFailureSource = Pick<RunResult, "id" | "status" | "durationMs" | "model" | "result">;
 
@@ -20,9 +22,13 @@ function isGenericErrorMessage(message: string): boolean {
 	return normalized === "" || normalized === "error" || normalized === "unknown error";
 }
 
+function isGenericCursorRunFailureMessage(message: string): boolean {
+	return /^cursor sdk run failed\.?$/i.test(message.trim());
+}
+
 function isKnownGenericRunFailureText(message: string): boolean {
 	const normalized = message.trim().toLowerCase();
-	return normalized === "" || normalized === GENERIC_CURSOR_RUN_FAILURE_TEXT || isGenericErrorMessage(normalized);
+	return normalized === "" || isGenericCursorRunFailureMessage(message) || isGenericErrorMessage(normalized);
 }
 
 function isLikelyAuthError(message: string): boolean {
@@ -150,7 +156,7 @@ export function formatCursorSdkRunFailureDetail(result: CursorSdkRunFailureSourc
 		return fromRun;
 	}
 
-	const parts = ["Cursor SDK run failed"];
+	const parts = [RETRYABLE_CURSOR_RUN_FAILURE_PREFIX];
 	if (result.model?.id) parts.push(`model ${result.model.id}`);
 	parts.push(`run ${shortRunId(result.id)}`);
 	if (typeof result.durationMs === "number") parts.push(`${result.durationMs}ms`);
@@ -190,6 +196,7 @@ export function sanitizeCursorProviderError(error: unknown, apiKey?: string): st
 	const connectClassification = classifyCursorConnectError(error);
 	if (connectClassification?.kind === "unauthenticated" || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
 	if (connectClassification?.kind === "network" || isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
+	if (isGenericCursorRunFailureMessage(scrubbed)) return RETRYABLE_CURSOR_RUN_FAILURE_PREFIX;
 	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
 	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
 }

package/src/cursor-provider-lazy.ts

@@ -0,0 +1,51 @@
+import {
+	createAssistantMessageEventStream,
+	type Api,
+	type AssistantMessage,
+	type AssistantMessageEventStream,
+	type Context,
+	type Model,
+	type SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+
+function makeProviderLoadErrorMessage(model: Model<Api>, error: unknown): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [],
+		api: model.api,
+		provider: model.provider,
+		model: model.id,
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "error",
+		timestamp: Date.now(),
+		errorMessage: `Failed to load Cursor provider runtime: ${error instanceof Error ? error.message : String(error)}`,
+	};
+}
+
+export function streamCursorLazy(
+	model: Model<Api>,
+	context: Context,
+	options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+	const outer = createAssistantMessageEventStream();
+	queueMicrotask(async () => {
+		try {
+			const { streamCursor } = await import("./cursor-provider.js");
+			for await (const event of streamCursor(model, context, options)) {
+				outer.push(event);
+			}
+		} catch (error) {
+			const message = makeProviderLoadErrorMessage(model, error);
+			outer.push({ type: "error", reason: "error", error: message });
+			outer.end(message);
+		}
+	});
+	return outer;
+}

package/src/cursor-provider-live-run-drain.ts

@@ -17,7 +17,7 @@ import {
 	deleteCursorNativeToolDisplay,
 	recordCursorNativeToolDisplay,
 	type CursorNativeToolDisplayItem,
-} from "./cursor-native-tool-display.js";
+} from "./cursor-native-tool-display-state.js";
 import { type CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
 import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";

package/src/cursor-provider-run-finalizer.ts

@@ -1,6 +1,5 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
-import { abandonSessionCursorAgent } from "./cursor-provider-live-run-drain.js";
+import { abandonSessionCursorAgent, cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import {
 	classifyCursorRunEmission,
 	getCursorRunAbortMessage,
@@ -12,7 +11,10 @@ import {
 	sanitizeCursorProviderError,
 } from "./cursor-provider-errors.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
-import type { IncompleteCursorToolRunOutcomeInput } from "./cursor-incomplete-tool-visibility.js";
+import {
+	buildIncompleteCursorToolRunOutcome,
+	type IncompleteCursorToolRunOutcomeInput,
+} from "./cursor-incomplete-tool-visibility.js";
 import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
@@ -24,8 +26,6 @@ import type {
 } from "./cursor-provider-turn-types.js";
 import { applyCursorApproximateUsage } from "./cursor-usage-accounting.js";
 import { hasUsableText } from "./cursor-record-utils.js";
-import { buildIncompleteCursorToolRunOutcome } from "./cursor-incomplete-tool-visibility.js";
-
 export type CursorTurnTerminalEvent =
 	| {
 			kind: "direct";

package/src/cursor-provider-run-outcome.ts

@@ -10,7 +10,6 @@ import { hasUsableText } from "./cursor-record-utils.js";
 import {
 	buildIncompleteCursorToolRunOutcome,
 	type IncompleteCursorToolRunOutcome,
-	type IncompleteCursorToolRunOutcomeInput,
 } from "./cursor-incomplete-tool-visibility.js";
 
 /** Unified SDK wait() facts consumed by live and direct emission strategies. */