pi-cursor-sdk 0.5.3 → 0.5.5

package/src/cursor-mcp-timeout-override.ts

@@ -8,12 +8,6 @@ const CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS"
 const CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_MS";
 const CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS";
 
-interface CursorMcpToolTimeoutOverrideOptions {
-	timeoutMs?: number;
-	connectTimeoutMs?: number;
-	env?: Record<string, string | undefined>;
-}
-
 interface CursorMcpToolTimeoutOverrideState {
 	installed: boolean;
 	timeoutMs: number;
@@ -61,7 +55,7 @@ function normalizeConnectTimeoutMs(timeoutMs: number): number {
 	);
 }
 
-export function resolveCursorMcpConnectTimeoutMs(
+function resolveCursorMcpConnectTimeoutMs(
 	env: Record<string, string | undefined> = process.env,
 ): number {
 	const explicitMs = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV]);
@@ -81,7 +75,7 @@ function isCursorSdkMcpProtocolTimeoutStack(stack: string | undefined): boolean
 	);
 }
 
-export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
 	if (!stack) return false;
 	return (
 		isCursorSdkMcpProtocolTimeoutStack(stack) &&
@@ -89,7 +83,7 @@ export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boole
 	);
 }
 
-export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
+function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
 	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
 	// The SDK minifies the Client class name; the protocol method and SDK
 	// frame, not that constructor's spelling, establish this timeout purpose.
@@ -121,15 +115,9 @@ function patchedSetTimeout(
 	return Reflect.apply(delegate, globalThis, [handler, nextDelay, ...args]) as ReturnType<GlobalSetTimeout>;
 }
 
-export function installCursorMcpToolTimeoutOverride(
-	options: CursorMcpToolTimeoutOverrideOptions = {},
-): CursorMcpToolTimeoutOverrideState {
-	installedToolTimeoutMs = normalizeOverrideTimeoutMs(
-		options.timeoutMs ?? resolveCursorMcpToolTimeoutMs(options.env),
-	);
-	installedConnectTimeoutMs = normalizeConnectTimeoutMs(
-		options.connectTimeoutMs ?? resolveCursorMcpConnectTimeoutMs(options.env),
-	);
+export function installCursorMcpToolTimeoutOverride(): CursorMcpToolTimeoutOverrideState {
+	installedToolTimeoutMs = resolveCursorMcpToolTimeoutMs();
+	installedConnectTimeoutMs = resolveCursorMcpConnectTimeoutMs();
 
 	if (!originalSetTimeout) {
 		originalSetTimeout = globalThis.setTimeout;
@@ -152,15 +140,3 @@ export function restoreCursorMcpToolTimeoutOverride(): void {
 	installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
 	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
-
-export const cursorMcpToolTimeoutOverrideDefaults = {
-	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
-	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,
-	defaultConnectTimeoutMs: DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS,
-	minConnectTimeoutMs: MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS,
-	maxNodeTimerDelayMs: MAX_NODE_TIMER_DELAY_MS,
-	timeoutMsEnv: CURSOR_MCP_TOOL_TIMEOUT_MS_ENV,
-	timeoutSecondsEnv: CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV,
-	connectTimeoutMsEnv: CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV,
-	connectTimeoutSecondsEnv: CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV,
-} as const;

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

@@ -34,14 +34,12 @@ export type {
 } from "./cursor-replay-tool-details.js";
 export {
 	isCursorReplayNativeEditDetails,
-	isCursorReplayGenerateImageDetails,
-	isCursorReplayActivityDetails,
 	isCursorReplayNativeWriteDetails,
 	parseCursorReplayToolDetails,
 } from "./cursor-replay-tool-details.js";
 
 export const CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES = 8;
-export const CURSOR_REPLAY_PREVIEW_MAX_CHARS = 4000;
+const CURSOR_REPLAY_PREVIEW_MAX_CHARS = 4000;
 export const CURSOR_REPLAY_PREVIEW_MAX_LINE_CHARS = 240;
 const CURSOR_REPLAY_HIGHLIGHT_MAX_CHARS = 12000;
 export const cursorReplayToolSchema = Type.Object({}, { additionalProperties: true });
@@ -75,7 +73,7 @@ function buildImageReplayComponent(text: string, imageData: string, mimeType: st
 	};
 }
 
-export function getCursorReplayPath(
+function getCursorReplayPath(
 	args: Record<string, unknown> | undefined,
 	details: Pick<CursorReplayNativeEditDetails, "path"> | Pick<CursorReplayNativeWriteDetails, "path"> | undefined,
 ): string {
@@ -282,7 +280,7 @@ function formatCursorReplayActivityPreview(
 	return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
 }
 
-export function formatCursorReplayPreview(
+function formatCursorReplayPreview(
 	text: string,
 	theme: CursorReplayRenderTheme,
 	maxLines = CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES,
@@ -330,7 +328,7 @@ function getCursorReplayCardTitle(toolName: CursorReplayToolName, args: Record<s
 	return "Cursor activity";
 }
 
-export function renderCursorReplayCall(
+function renderCursorReplayCall(
 	toolName: CursorReplayToolName,
 	args: Record<string, unknown> | undefined,
 	theme: CursorReplayRenderTheme,

package/src/cursor-native-tools.ts

@@ -0,0 +1,14 @@
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+
+export const CURSOR_NATIVE_TOOLS_ENV = "PI_CURSOR_NATIVE_TOOLS";
+
+/** Default preserves the SDK toolset; false selects the public MCP-only main loop. */
+export function resolveCursorNativeToolsEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	return parseEnvBoolean(env[CURSOR_NATIVE_TOOLS_ENV], true);
+}
+
+export function assertCursorNativeToolsRuntime(runtime: "local" | "cloud", nativeToolsEnabled: boolean): void {
+	if (runtime === "cloud" && !nativeToolsEnabled) {
+		throw new Error("PI_CURSOR_NATIVE_TOOLS=0 requires local runtime; Cursor Cloud does not support the SDK tools restriction. Select local runtime or remove the opt-out.");
+	}
+}

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

@@ -2,8 +2,8 @@ import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { resolveCursorMcpToolTimeoutMs } from "./cursor-mcp-timeout-override.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 const CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV = "PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS";
+const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+const CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV = "PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS";
 
 export function resolveCursorPiToolBridgeEnabled(env: Record<string, string | undefined> = process.env): boolean {
 	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
@@ -19,3 +19,32 @@ export function resolveCursorPiToolBridgeCallTimeoutMs(env: Record<string, strin
 	if (!Number.isFinite(parsed) || parsed <= 0) return mcpToolTimeoutMs;
 	return Math.min(Math.max(Math.trunc(parsed), 1), mcpToolTimeoutMs);
 }
+
+const CURSOR_PI_TOOL_BRIDGE_HOST_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_HOST";
+const CURSOR_PI_TOOL_BRIDGE_PORT_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_PORT";
+const DEFAULT_URL_HOST = "127.0.0.1";
+const PORT_PATTERN = /^\d{1,5}$/;
+
+export interface CursorPiToolBridgePortRange {
+	readonly first: number;
+	readonly last: number;
+}
+
+export function resolveCursorPiToolBridgeUrlHost(env: Record<string, string | undefined> = process.env): string {
+	return env[CURSOR_PI_TOOL_BRIDGE_HOST_ENV]?.trim().toLowerCase() === "localhost" ? "localhost" : DEFAULT_URL_HOST;
+}
+
+function parsePort(text: string): number | undefined {
+	if (!PORT_PATTERN.test(text)) return undefined;
+	const port = Number(text);
+	return port >= 1 && port <= 65535 ? port : undefined;
+}
+
+export function resolveCursorPiToolBridgePortRange(env: Record<string, string | undefined> = process.env): CursorPiToolBridgePortRange | undefined {
+	const parts = env[CURSOR_PI_TOOL_BRIDGE_PORT_ENV]?.trim().split("-");
+	if (!parts || parts.length > 2) return undefined;
+	const first = parsePort(parts[0]!);
+	const last = parts.length === 2 ? parsePort(parts[1]!) : first;
+	if (first === undefined || last === undefined || first > last) return undefined;
+	return { first, last };
+}

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

@@ -6,6 +6,10 @@ import type {
 	CursorPiToolBridgeRunOptions,
 	CursorPiToolBridgeSnapshotApi,
 } from "./cursor-pi-tool-bridge-types.js";
+import {
+	resolveCursorPiToolBridgePortRange,
+	resolveCursorPiToolBridgeUrlHost,
+} from "./cursor-pi-tool-bridge-env.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
 import {
@@ -16,15 +20,54 @@ import {
 	resolveCursorPiToolBridgeEnabled,
 } from "./cursor-pi-tool-bridge-snapshot.js";
 
-export const LOOPBACK_HOST = "127.0.0.1";
+const LOOPBACK_HOST = "127.0.0.1";
 const HTTP_SERVER_CLOSE_GRACE_MS = 250;
+const EPHEMERAL_BIND_ATTEMPTS = 10;
+
+function listenOnce(server: HttpServer, port: number, host = LOOPBACK_HOST): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		const onError = (error: Error) => {
+			server.off("listening", onListening);
+			reject(error);
+		};
+		const onListening = () => {
+			server.off("error", onError);
+			resolve();
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen({ port, host, ipv6Only: host === "::1" });
+	});
+}
+
+async function closeServers(servers: readonly HttpServer[]): Promise<void> {
+	await Promise.all(servers.map(async (server) => {
+		if (!server.listening) return;
+		await new Promise<void>((resolve, reject) => {
+			let settled = false;
+			const settle = (error?: Error): void => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(closeTimer);
+				if (error) reject(error);
+				else resolve();
+			};
+			const closeTimer = setTimeout(() => settle(), HTTP_SERVER_CLOSE_GRACE_MS);
+			closeTimer.unref?.();
+			server.close((error) => settle(error ?? undefined));
+			server.closeIdleConnections();
+			server.closeAllConnections();
+		});
+	}));
+}
 
 export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	private readonly pi: CursorPiToolBridgeSnapshotApi;
 	private readonly env: Record<string, string | undefined>;
 	private readonly runs = new Set<CursorPiToolBridgeRunImpl>();
 	private readonly routes = new Map<string, CursorPiToolBridgeRunImpl>();
-	private httpServer?: HttpServer;
+	private httpServers: HttpServer[] = [];
+	private advertisedHost?: string;
 	private listenPromise?: Promise<void>;
 	private serverLifecycle = Promise.resolve();
 
@@ -57,7 +100,14 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			: createEmptySnapshot();
 		const run = new CursorPiToolBridgeRunImpl(this, this.env, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
 		this.runs.add(run);
-		await run.start();
+		try {
+			await run.start();
+		} catch (error) {
+			try { await run.dispose(); }
+			catch { /* Preserve the original startup failure, not a secondary cleanup error. */ }
+			this.runs.delete(run);
+			throw error;
+		}
 		run.emitStartDiagnostics(bridgeEnabled);
 		return run;
 	}
@@ -74,8 +124,8 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			await this.ensureHttpServer();
 			this.routes.set(pathname, run);
 			const address = this.getHttpServerAddress();
-			if (!address) throw new Error("Cursor pi tool bridge HTTP server is not listening");
-			return `http://${LOOPBACK_HOST}:${address.port}${pathname}`;
+			if (!address || !this.advertisedHost) throw new Error("Cursor pi tool bridge HTTP server is not listening");
+			return `http://${this.advertisedHost}:${address.port}${pathname}`;
 		});
 	}
 
@@ -94,7 +144,7 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	}
 
 	getHttpServerAddress(): AddressInfo | undefined {
-		const address = asRecord(this.httpServer?.address());
+		const address = asRecord(this.httpServers[0]?.address());
 		if (typeof address?.port !== "number") return undefined;
 		return {
 			address: typeof address.address === "string" ? address.address : LOOPBACK_HOST,
@@ -123,7 +173,8 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 
 	private async ensureHttpServer(): Promise<void> {
 		this.listenPromise ??= this.startHttpServer().catch((error: unknown) => {
-			this.httpServer = undefined;
+			this.httpServers = [];
+			this.advertisedHost = undefined;
 			this.listenPromise = undefined;
 			throw error;
 		});
@@ -131,6 +182,9 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	}
 
 	private async startHttpServer(): Promise<void> {
+		// A hostname is a listener policy, not a mutable per-run URL preference.
+		const advertisedHost = resolveCursorPiToolBridgeUrlHost(this.env);
+		const range = resolveCursorPiToolBridgePortRange(this.env);
 		const [{ getRequestListener }, { createMcpHonoApp }] = await Promise.all([
 			import("@hono/node-server"),
 			import("@modelcontextprotocol/hono"),
@@ -142,49 +196,39 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 			).get("parsedBody");
 			return this.handleHttpRequest(context.req.raw, parsedBody);
 		});
-		const server = createServer(getRequestListener(app.fetch, { overrideGlobalObjects: false }));
-		this.httpServer = server;
-		await new Promise<void>((resolve, reject) => {
-			const onError = (error: Error) => {
-				server.off("listening", onListening);
-				reject(error);
-			};
-			const onListening = () => {
-				server.off("error", onError);
-				resolve();
-			};
-			server.once("error", onError);
-			server.once("listening", onListening);
-			server.listen(0, LOOPBACK_HOST);
-		});
+		const listener = getRequestListener(app.fetch, { overrideGlobalObjects: false });
+		const attempts = range ? range.last - range.first + 1 : advertisedHost === "localhost" ? EPHEMERAL_BIND_ATTEMPTS : 1;
+		for (let attempt = 0; attempt < attempts; attempt += 1) {
+			const servers = [createServer(listener)];
+			try {
+				await listenOnce(servers[0]!, range ? range.first + attempt : 0);
+				if (advertisedHost === "localhost") {
+					const port = (servers[0]!.address() as AddressInfo).port;
+					const ipv6 = createServer(listener);
+					servers.push(ipv6);
+					// Own both explicit loopbacks before publishing any tokenized URL.
+					await listenOnce(ipv6, port, "::1");
+				}
+				this.httpServers = servers;
+				this.advertisedHost = advertisedHost;
+				return;
+			} catch (error) {
+				try { await closeServers(servers); }
+				catch { throw error; } // Never retry or replace the bind failure when rollback fails.
+				if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE" || (!range && advertisedHost !== "localhost")) throw error;
+			}
+		}
+		if (range) throw new Error(`Cursor pi tool bridge could not listen on any port in ${range.first}-${range.last} (all in use)`);
+		throw new Error("Cursor pi tool bridge could not own both localhost loopback listeners on an ephemeral port");
 	}
 
 	private async closeHttpServer(): Promise<void> {
 		await this.listenPromise?.catch(() => undefined);
-		const server = this.httpServer;
-		if (!server) return;
-		this.httpServer = undefined;
+		const servers = this.httpServers;
+		this.httpServers = [];
+		this.advertisedHost = undefined;
 		this.listenPromise = undefined;
-		await new Promise<void>((resolve, reject) => {
-			let settled = false;
-			let closeTimer: ReturnType<typeof setTimeout> | undefined;
-			const settle = (error?: Error): void => {
-				if (settled) return;
-				settled = true;
-				if (closeTimer) clearTimeout(closeTimer);
-				if (error) reject(error);
-				else resolve();
-			};
-
-			closeTimer = setTimeout(() => settle(), HTTP_SERVER_CLOSE_GRACE_MS);
-			closeTimer.unref?.();
-
-			server.close((error) => {
-				settle(error ?? undefined);
-			});
-			server.closeIdleConnections();
-			server.closeAllConnections();
-		});
+		await closeServers(servers);
 	}
 
 	private async handleHttpRequest(request: Request, parsedBody?: unknown): Promise<Response> {

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

@@ -6,7 +6,6 @@ import type {
 } from "./cursor-pi-tool-bridge-types.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,

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

@@ -1,18 +1,12 @@
 import { spawnSync } from "node:child_process";
 import {
-	CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV,
 	CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX,
 	type CursorPiToolBridgeDiagnosticEvent,
 	serializeCursorPiToolBridgeDiagnostic,
 } from "./cursor-pi-tool-bridge-diagnostics.js";
-import {
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_ENV,
-} from "./cursor-pi-tool-bridge-env.js";
 import { bridgeToolExecutionAbortTracker } from "./cursor-pi-tool-bridge-abort.js";
-import { isCursorPiBridgeToolCallId, MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
-import { LOOPBACK_HOST, CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
+import { isCursorPiBridgeToolCallId } from "./cursor-pi-tool-bridge-constants.js";
+import { CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
 import type {
 	CursorPiToolBridge,
 	CursorPiToolBridgeExtensionApi,
@@ -34,9 +28,6 @@ export type {
 export type { CursorPiToolBridgeDiagnosticEvent } from "./cursor-pi-tool-bridge-diagnostics.js";
 export { resolveCursorPiToolBridgeDebugEnabled } from "./cursor-pi-tool-bridge-diagnostics.js";
 export {
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_ENV,
 	resolveCursorPiToolBridgeBuiltinsEnabled,
 	resolveCursorPiToolBridgeCallTimeoutMs,
 	resolveCursorPiToolBridgeEnabled,
@@ -145,13 +136,7 @@ export function getRegisteredCursorPiToolBridge(pi?: object): CursorPiToolBridge
 }
 
 export const __testUtils = {
-	CURSOR_PI_TOOL_BRIDGE_ENV,
-	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV,
-	CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV,
 	CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX,
-	LOOPBACK_HOST,
-	MCP_SERVER_NAME,
 	createRegistry(
 		pi: CursorPiToolBridgeSnapshotApi,
 		env: Record<string, string | undefined> = process.env,
@@ -168,7 +153,6 @@ export const __testUtils = {
 		return bridgeToolExecutionAbortTracker.getActiveCount();
 	},
 	buildWindowsBridgeBashAbortCommandForTests: buildWindowsBridgeBashAbortCommand,
-	installWindowsBridgeBashAbortMarkerForTests: installWindowsBridgeBashAbortMarker,
 	emitBridgeToolExecutionProcessAbortSignalForTests(signal: NodeJS.Signals) {
 		bridgeToolExecutionAbortTracker.emitProcessAbortSignalForTests(signal);
 	},

package/src/cursor-provider-errors.ts

@@ -258,14 +258,6 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 	return undefined;
 }
 
-export function isCursorSdkAbortConnectError(error: unknown): boolean {
-	return classifyCursorConnectError(error)?.kind === "abort";
-}
-
-export function isUnauthenticatedConnectError(error: unknown): boolean {
-	return classifyCursorConnectError(error)?.kind === "unauthenticated";
-}
-
 function isLikelyNetworkTimeout(message: string): boolean {
 	return (
 		/\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAI_AGAIN|NGHTTP2_ENHANCE_YOUR_CALM|ERR_HTTP2_STREAM_ERROR|ERR_HTTP2_SESSION_ERROR)\b/i.test(

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

@@ -29,7 +29,7 @@ import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js
 import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
-export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
+const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
 function parseCursorNativeReplayIdleDisposeMs(raw: string | undefined): number {
 	if (!raw || /[^0-9]/.test(raw)) return DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
 	const value = Number(raw);
@@ -69,7 +69,7 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId: string): string | und
 	return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
 }
 
-export function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
+function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
 	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId, scopeKey);
 }
 
@@ -449,6 +449,7 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	turnDebugRecorder: CursorSdkEventDebugRecorder | undefined,
 	scopeKey: string,
 	occupancyFloor?: number,
+	nativeToolsEnabled = true,
 ): Promise<LiveRunPreSendOutcome> {
 	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
@@ -461,6 +462,11 @@ export async function drainExistingCursorLiveRunBeforeSend(
 		try {
 			const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
 				if (run.disposed) return "continue_send" as const;
+				// Check under the drain lease, before consuming/delivering Pi results:
+				// resolving a bridge waiter can resume the SDK's old tool surface.
+				if ((run.nativeToolsEnabled !== false) !== nativeToolsEnabled) {
+					throw new Error("Cursor native tool policy changed while a local run is pending; restore the prior policy to finish it or run /cursor-abort before retrying. Already-executed work is not undone.");
+				}
 				const consumed = cursorLiveRuns.consumeToolResults(run, context, getCursorNativeReplayIdFromToolCallId);
 				await run.bridgeRun?.resolveToolResults(consumed.toolResults);
 				const shouldChainUserInput = run.chainUserInputAfterCompletion || hasTrailingUserMessagesAfterToolResults(context);

package/src/cursor-provider-overflow.ts

@@ -1,5 +1,4 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { CURSOR_PROVIDER } from "./cursor-model.js";
 
 /**
@@ -15,7 +14,7 @@ import { CURSOR_PROVIDER } from "./cursor-model.js";
  *
  * See pi `docs/custom-provider.md` -> "Context Overflow Errors".
  */
-export const CURSOR_OVERFLOW_MARKER = "context_length_exceeded";
+const CURSOR_OVERFLOW_MARKER = "context_length_exceeded";
 
 /**
  * Context-overflow phrases. These overlap pi's own `OVERFLOW_PATTERNS` so the
@@ -43,9 +42,9 @@ const CURSOR_THROTTLE_PATTERN = /too many requests|rate.?limit|throttl|retry.?af
  * Map a finalized Cursor assistant `errorMessage` to pi's overflow form.
  * Returns `undefined` when the message is not a Cursor context-overflow failure.
  *
- * Pure and idempotent so it is safe to call repeatedly and unit-test in isolation.
+ * Idempotent so repeated message delivery does not add another prefix.
  */
-export function normalizeCursorOverflowErrorMessage(errorMessage: string | undefined): string | undefined {
+function normalizeCursorOverflowErrorMessage(errorMessage: string | undefined): string | undefined {
 	const message = errorMessage?.trim();
 	if (!message) return undefined;
 	// Idempotent: never double-prefix an already-normalized message.
@@ -57,24 +56,6 @@ export function normalizeCursorOverflowErrorMessage(errorMessage: string | undef
 	return undefined;
 }
 
-/**
- * Rewrite a finalized assistant message into pi's overflow form when it is a
- * Cursor context-overflow failure. Returns the replacement message (for the
- * `message_end` result) or `undefined` to leave it unchanged.
- *
- * `isCursorProvider` carries the provider scoping decision out of the handler so
- * the full logic is unit-testable without a pi event harness.
- */
-export function rewriteCursorOverflowAssistantMessage(
-	message: AssistantMessage,
-	isCursorProvider: boolean,
-): AssistantMessage | undefined {
-	if (!isCursorProvider || message.stopReason !== "error") return undefined;
-	const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
-	if (!rewritten) return undefined;
-	return { ...message, errorMessage: rewritten };
-}
-
 export type CursorOverflowExtensionApi = Pick<ExtensionAPI, "on">;
 
 /**
@@ -89,8 +70,9 @@ export function registerCursorOverflowNormalization(pi: CursorOverflowExtensionA
 		const message = event.message;
 		if (message.role !== "assistant") return undefined;
 		const isCursorProvider = message.provider === CURSOR_PROVIDER || ctx.model?.provider === CURSOR_PROVIDER;
-		const rewritten = rewriteCursorOverflowAssistantMessage(message, isCursorProvider);
+		if (!isCursorProvider || message.stopReason !== "error") return undefined;
+		const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
 		if (!rewritten) return undefined;
-		return { message: rewritten };
+		return { message: { ...message, errorMessage: rewritten } };
 	});
 }

package/src/cursor-provider-turn-finalize.ts

@@ -16,6 +16,7 @@ import {
 } from "./cursor-provider-run-outcome.js";
 import type { StartedCursorProviderTurn } from "./cursor-provider-turn-types.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { resolveCursorLocalRunTerminalError } from "./cursor-local-run-terminal-error.js";
 
 export async function cacheSdkContextWindow(
 	agentId: string,
@@ -157,6 +158,7 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 	let waitResult: Awaited<ReturnType<typeof params.run.wait>>;
 	try {
 		waitResult = params.waitResult ?? (await params.run.wait());
+		waitResult = resolveCursorLocalRunTerminalError(params.run, waitResult, params.signal?.aborted === true);
 	} catch (error) {
 		await recordCursorProviderTerminalUsage(params.prepared, params.signal?.aborted ? "abort" : "error");
 		throw error;

package/src/cursor-provider-turn-prepare.ts

@@ -59,6 +59,7 @@ import type {
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
+import { assertCursorNativeToolsRuntime } from "./cursor-native-tools.js";
 import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
 
 export interface PrepareCursorProviderTurnParams {
@@ -69,6 +70,8 @@ export interface PrepareCursorProviderTurnParams {
 	throwIfAborted: () => void;
 	/** Snapshot resolved once by the runner before draining; reused unchanged through prepare. */
 	resolvedConfig: CursorResolvedSdkConfig;
+	/** Snapshotted before drain/acquisition, never re-read during creation/resume. */
+	nativeToolsEnabled: boolean;
 }
 
 interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnParams {
@@ -252,7 +255,7 @@ async function prepareCursorCloudProviderTurn(
 async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<LocalCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames, nativeToolsEnabled } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -289,6 +292,7 @@ async function prepareCursorLocalProviderTurn(
 			settingSources,
 			localSafety,
 			agents,
+			nativeToolsEnabled,
 			localResume: resolvedConfig.local.resume.value,
 			storeRoot: resolvedConfig.local.storeRoot.value,
 			useHttp1ForAgent,
@@ -314,6 +318,7 @@ async function prepareCursorLocalProviderTurn(
 				...getCursorPromptOptions(model),
 				nativeSourceRoles: params.request.nativeSourceRoles,
 				agentMode,
+				nativeToolsEnabled,
 				includePiBridgeGuidance,
 				includePiAskQuestionGuidance: false,
 			};
@@ -323,6 +328,7 @@ async function prepareCursorLocalProviderTurn(
 			return {
 				...promptOptions,
 				toolManifest: buildCursorToolManifestText({
+					nativeToolsEnabled,
 					bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
 					piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
 					includePiBridgeGuidance,
@@ -373,6 +379,7 @@ async function prepareCursorLocalProviderTurn(
 			agentMode,
 			localForce: resolvedConfig.local.force.value,
 			localResume: resolvedConfig.local.resume.value,
+			...(nativeToolsEnabled ? {} : { nativeToolsEnabled: false, tools: ["mcp"] }),
 			resumedAgent: sessionAgentLease.resumed,
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
@@ -386,6 +393,7 @@ async function prepareCursorLocalProviderTurn(
 			? cursorLiveRuns.start({
 					id: useNativeToolReplay ? nativeReplayId : bridgeRun?.id ?? nativeReplayId,
 					agent,
+					nativeToolsEnabled,
 					bridgeRun,
 					sessionBridgeRun,
 					sessionAgentScopeKey,
@@ -467,6 +475,7 @@ export async function prepareCursorProviderTurn(
 ): Promise<CursorProviderTurnPrepareResult> {
 	const { params, resolvedConfig } = prepareParams;
 	const { model, options } = params;
+	assertCursorNativeToolsRuntime(resolvedConfig.runtime.value, prepareParams.nativeToolsEnabled);
 
 	const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id, params.scope.scopeKey);
 	const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);