pi-cursor-sdk 0.5.3 → 0.5.5

package/dist/cursor-native-tool-display-replay.js

@@ -8,9 +8,9 @@ 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, getCursorReplayCallSummary, shouldShowCursorReplayCollapsedExpandHint, } from "./cursor-tool-presentation-registry.js";
 import { CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE, isCursorReplayGenerateImageDetails, isCursorReplayActivityDetails, parseCursorReplayToolDetails, } from "./cursor-replay-tool-details.js";
-export { isCursorReplayNativeEditDetails, isCursorReplayGenerateImageDetails, isCursorReplayActivityDetails, isCursorReplayNativeWriteDetails, parseCursorReplayToolDetails, } from "./cursor-replay-tool-details.js";
+export { isCursorReplayNativeEditDetails, 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 });
@@ -40,7 +40,7 @@ function buildImageReplayComponent(text, imageData, mimeType, filename, theme) {
         },
     };
 }
-export function getCursorReplayPath(args, details) {
+function getCursorReplayPath(args, details) {
     const argPath = args?.path;
     return details?.path ?? (typeof argPath === "string" && argPath.trim() ? argPath : "unknown");
 }
@@ -202,7 +202,7 @@ function formatCursorReplayActivityPreview(details, text, theme, maxLines, strip
     }
     return stripHeader ? formatCursorReplayPreview(text, theme, maxLines, true) : formatMutedBlock(text, theme);
 }
-export function formatCursorReplayPreview(text, theme, maxLines = CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES, stripHeader = true) {
+function formatCursorReplayPreview(text, theme, maxLines = CURSOR_REPLAY_COLLAPSED_PREVIEW_LINES, stripHeader = true) {
     const body = (stripHeader ? stripCursorReplayHeader(text) : text).trimEnd();
     if (!body)
         return undefined;
@@ -240,7 +240,7 @@ function getCursorReplayCardTitle(toolName, args) {
     }
     return "Cursor activity";
 }
-export function renderCursorReplayCall(toolName, args, theme, isPartial) {
+function renderCursorReplayCall(toolName, args, theme, isPartial) {
     if (!isPartial)
         return new Text("", 0, 0);
     let text = theme.fg("toolTitle", theme.bold(`${getCursorReplayCardTitle(toolName, args)} `));

package/dist/cursor-native-tools.js

@@ -0,0 +1,11 @@
+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 = process.env) {
+    return parseEnvBoolean(env[CURSOR_NATIVE_TOOLS_ENV], true);
+}
+export function assertCursorNativeToolsRuntime(runtime, nativeToolsEnabled) {
+    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/dist/cursor-pi-tool-bridge-env.js

@@ -1,8 +1,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 = process.env) {
     return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
 }
@@ -16,3 +16,26 @@ export function resolveCursorPiToolBridgeCallTimeoutMs(env = process.env) {
         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 function resolveCursorPiToolBridgeUrlHost(env = process.env) {
+    return env[CURSOR_PI_TOOL_BRIDGE_HOST_ENV]?.trim().toLowerCase() === "localhost" ? "localhost" : DEFAULT_URL_HOST;
+}
+function parsePort(text) {
+    if (!PORT_PATTERN.test(text))
+        return undefined;
+    const port = Number(text);
+    return port >= 1 && port <= 65535 ? port : undefined;
+}
+export function resolveCursorPiToolBridgePortRange(env = process.env) {
+    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/dist/cursor-pi-tool-bridge-server.js

@@ -1,15 +1,57 @@
 import { createServer } from "node:http";
+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 { buildCursorPiToolBridgeSnapshot, buildCursorPiToolBridgeSurfaceSignature, createEmptySnapshot, resolveCursorPiToolBridgeBuiltinsEnabled, 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, port, host = LOOPBACK_HOST) {
+    return new Promise((resolve, reject) => {
+        const onError = (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) {
+    await Promise.all(servers.map(async (server) => {
+        if (!server.listening)
+            return;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (error) => {
+                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 {
     pi;
     env;
     runs = new Set();
     routes = new Map();
-    httpServer;
+    httpServers = [];
+    advertisedHost;
     listenPromise;
     serverLifecycle = Promise.resolve();
     constructor(pi, env = process.env) {
@@ -36,7 +78,17 @@ export class CursorPiToolBridgeRegistry {
             : 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;
     }
@@ -51,9 +103,9 @@ export class CursorPiToolBridgeRegistry {
             await this.ensureHttpServer();
             this.routes.set(pathname, run);
             const address = this.getHttpServerAddress();
-            if (!address)
+            if (!address || !this.advertisedHost)
                 throw new Error("Cursor pi tool bridge HTTP server is not listening");
-            return `http://${LOOPBACK_HOST}:${address.port}${pathname}`;
+            return `http://${this.advertisedHost}:${address.port}${pathname}`;
         });
     }
     async unregisterRun(pathname, run) {
@@ -71,7 +123,7 @@ export class CursorPiToolBridgeRegistry {
         return result;
     }
     getHttpServerAddress() {
-        const address = asRecord(this.httpServer?.address());
+        const address = asRecord(this.httpServers[0]?.address());
         if (typeof address?.port !== "number")
             return undefined;
         return {
@@ -99,13 +151,17 @@ export class CursorPiToolBridgeRegistry {
     }
     async ensureHttpServer() {
         this.listenPromise ??= this.startHttpServer().catch((error) => {
-            this.httpServer = undefined;
+            this.httpServers = [];
+            this.advertisedHost = undefined;
             this.listenPromise = undefined;
             throw error;
         });
         await this.listenPromise;
     }
     async startHttpServer() {
+        // 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"),
@@ -115,51 +171,45 @@ export class CursorPiToolBridgeRegistry {
             const parsedBody = context.get("parsedBody");
             return this.handleHttpRequest(context.req.raw, parsedBody);
         });
-        const server = createServer(getRequestListener(app.fetch, { overrideGlobalObjects: false }));
-        this.httpServer = server;
-        await new Promise((resolve, reject) => {
-            const onError = (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().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.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");
     }
     async closeHttpServer() {
         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((resolve, reject) => {
-            let settled = false;
-            let closeTimer;
-            const settle = (error) => {
-                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);
     }
     async handleHttpRequest(request, parsedBody) {
         const url = new URL(request.url);

package/dist/cursor-pi-tool-bridge-snapshot.js

@@ -1,5 +1,5 @@
 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";
+export { 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-presentation-registry.js";
 const OVERLAPPING_CURSOR_NATIVE_PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "write", "edit", "grep", "find", "ls"]);

package/dist/cursor-pi-tool-bridge.js

@@ -1,11 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV, CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX, 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 { CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX, serializeCursorPiToolBridgeDiagnostic, } from "./cursor-pi-tool-bridge-diagnostics.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";
 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, } from "./cursor-pi-tool-bridge-env.js";
+export { resolveCursorPiToolBridgeBuiltinsEnabled, resolveCursorPiToolBridgeCallTimeoutMs, resolveCursorPiToolBridgeEnabled, } from "./cursor-pi-tool-bridge-env.js";
 export { buildCursorPiToolBridgeSnapshot, buildCursorPiToolBridgeSurfaceSignature, } from "./cursor-pi-tool-bridge-snapshot.js";
 const bridges = new Map();
 const activeCallsByPi = new Map();
@@ -110,13 +109,7 @@ export function getRegisteredCursorPiToolBridge(pi) {
     return pi ? bridges.get(pi) : registeredCursorPiToolBridge;
 }
 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, env = process.env) {
         return new CursorPiToolBridgeRegistry(pi, env);
     },
@@ -130,7 +123,6 @@ export const __testUtils = {
         return bridgeToolExecutionAbortTracker.getActiveCount();
     },
     buildWindowsBridgeBashAbortCommandForTests: buildWindowsBridgeBashAbortCommand,
-    installWindowsBridgeBashAbortMarkerForTests: installWindowsBridgeBashAbortMarker,
     emitBridgeToolExecutionProcessAbortSignalForTests(signal) {
         bridgeToolExecutionAbortTracker.emitProcessAbortSignalForTests(signal);
     },

package/dist/cursor-provider-errors.js

@@ -214,12 +214,6 @@ export function classifyCursorConnectError(error) {
     }
     return undefined;
 }
-export function isCursorSdkAbortConnectError(error) {
-    return classifyCursorConnectError(error)?.kind === "abort";
-}
-export function isUnauthenticatedConnectError(error) {
-    return classifyCursorConnectError(error)?.kind === "unauthenticated";
-}
 function isLikelyNetworkTimeout(message) {
     return (/\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENETUNREACH|EAI_AGAIN|NGHTTP2_ENHANCE_YOUR_CALM|ERR_HTTP2_STREAM_ERROR|ERR_HTTP2_SESSION_ERROR)\b/i.test(message) ||
         /\bConnectError\b.*\b(unavailable|deadline|timeout|timed out)\b/i.test(message) ||

package/dist/cursor-provider-live-run-drain.js

@@ -9,7 +9,7 @@ import { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text
 import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
 import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
 import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.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) {
     if (!raw || /[^0-9]/.test(raw))
         return DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
@@ -36,7 +36,7 @@ export function createCursorNativeReplayId() {
 function getCursorNativeReplayIdFromToolCallId(toolCallId) {
     return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
 }
-export function getPendingCursorLiveRun(context, scopeKey) {
+function getPendingCursorLiveRun(context, scopeKey) {
     return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId, scopeKey);
 }
 export function getActiveCursorLiveRunForCurrentScope(scopeKey) {
@@ -357,7 +357,7 @@ export async function drainCursorLiveRunTurn(stream, partial, model, context, ru
         });
     }
 }
-export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder, scopeKey, occupancyFloor) {
+export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder, scopeKey, occupancyFloor, nativeToolsEnabled = true) {
     turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
     while (true) {
         const run = getPendingCursorLiveRun(context, scopeKey) ?? getActiveCursorLiveRunForCurrentScope(scopeKey);
@@ -369,6 +369,11 @@ export async function drainExistingCursorLiveRunBeforeSend(stream, partial, mode
             const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
                 if (run.disposed)
                     return "continue_send";
+                // 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/dist/cursor-provider-overflow.js

@@ -12,7 +12,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
  * false-positive surface matches pi's built-in detection for other providers.
@@ -37,9 +37,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) {
+function normalizeCursorOverflowErrorMessage(errorMessage) {
     const message = errorMessage?.trim();
     if (!message)
         return undefined;
@@ -53,22 +53,6 @@ export function normalizeCursorOverflowErrorMessage(errorMessage) {
     }
     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, isCursorProvider) {
-    if (!isCursorProvider || message.stopReason !== "error")
-        return undefined;
-    const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
-    if (!rewritten)
-        return undefined;
-    return { ...message, errorMessage: rewritten };
-}
 /**
  * Register a `message_end` handler that rewrites Cursor context-overflow
  * failures into the `context_length_exceeded` form pi auto-compacts on.
@@ -82,9 +66,11 @@ export function registerCursorOverflowNormalization(pi) {
         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/dist/cursor-provider-turn-finalize.js

@@ -4,6 +4,7 @@ import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-w
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { isCursorRunFinishedSuccessfully, resolveCursorRunOutcome, } from "./cursor-provider-run-outcome.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { resolveCursorLocalRunTerminalError } from "./cursor-local-run-terminal-error.js";
 export async function cacheSdkContextWindow(agentId, modelId, cwd, store) {
     try {
         const { createAgentPlatform } = await loadCursorSdk();
@@ -91,6 +92,7 @@ export async function awaitFinalizeCursorRunOutcome(params) {
     let waitResult;
     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");

package/dist/cursor-provider-turn-prepare.js

@@ -24,6 +24,7 @@ import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { assertCursorNativeToolsRuntime } from "./cursor-native-tools.js";
 import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
 function buildCursorCloudPromptContext(context, handoff, nativeSourceRoles) {
     if (handoff === "bootstrap")
@@ -182,7 +183,7 @@ async function prepareCursorCloudProviderTurn(prepareParams) {
     }
 }
 async function prepareCursorLocalProviderTurn(prepareParams) {
-    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;
     let sessionAgentScopeKey;
@@ -212,6 +213,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             settingSources,
             localSafety,
             agents,
+            nativeToolsEnabled,
             localResume: resolvedConfig.local.resume.value,
             storeRoot: resolvedConfig.local.storeRoot.value,
             useHttp1ForAgent,
@@ -236,6 +238,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
                 ...getCursorPromptOptions(model),
                 nativeSourceRoles: params.request.nativeSourceRoles,
                 agentMode,
+                nativeToolsEnabled,
                 includePiBridgeGuidance,
                 includePiAskQuestionGuidance: false,
             };
@@ -245,6 +248,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             return {
                 ...promptOptions,
                 toolManifest: buildCursorToolManifestText({
+                    nativeToolsEnabled,
                     bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
                     piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
                     includePiBridgeGuidance,
@@ -295,6 +299,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             agentMode,
             localForce: resolvedConfig.local.force.value,
             localResume: resolvedConfig.local.resume.value,
+            ...(nativeToolsEnabled ? {} : { nativeToolsEnabled: false, tools: ["mcp"] }),
             resumedAgent: sessionAgentLease.resumed,
             activeToolNames: activeToolNames ? [...activeToolNames] : [],
             sessionAgentScopeKey,
@@ -308,6 +313,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
             ? cursorLiveRuns.start({
                 id: useNativeToolReplay ? nativeReplayId : bridgeRun?.id ?? nativeReplayId,
                 agent,
+                nativeToolsEnabled,
                 bridgeRun,
                 sessionBridgeRun,
                 sessionAgentScopeKey,
@@ -387,6 +393,7 @@ async function prepareCursorLocalProviderTurn(prepareParams) {
 export async function prepareCursorProviderTurn(prepareParams) {
     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);
     if (resolvedConfig.runtime.value === "local" && params.request.purpose !== "normal") {

package/dist/cursor-provider-turn-runner.js

@@ -1,5 +1,6 @@
+import { assertCursorNativeToolsRuntime, resolveCursorNativeToolsEnabled } from "./cursor-native-tools.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
-import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns, drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
@@ -45,6 +46,12 @@ export class CursorProviderTurnRunner {
             this.throwIfAborted();
             const { scope } = this.params;
             const cwd = scope.cwd;
+            // Resolved once here, before any drain await, so the drain decision and the
+            // prepare dispatch below always act on the same config snapshot.
+            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
+            this.runtimeTarget = resolvedConfig.runtime.value;
+            const nativeToolsEnabled = resolveCursorNativeToolsEnabled();
+            assertCursorNativeToolsRuntime(this.runtimeTarget, nativeToolsEnabled);
             this.sdkEventDebug = CursorSdkEventDebugSink.maybeCreate({
                 cwd,
                 modelId: model.id,
@@ -53,12 +60,8 @@ export class CursorProviderTurnRunner {
             });
             sdkEventDebugRef.current = this.sdkEventDebug;
             this.sdkEventDebug?.recordContextSnapshot(context);
-            // Resolved once here, before any drain await, so the drain decision and the
-            // prepare dispatch below always act on the same config snapshot.
-            const resolvedConfig = resolveCursorProviderTurnConfig(cwd, scope.projectTrusted, scope.scopeKey);
-            this.runtimeTarget = resolvedConfig.runtime.value;
             if (resolvedConfig.runtime.value === "local" && this.params.request.purpose === "normal") {
-                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor)) ===
+                if ((await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug, scope.scopeKey, this.params.request.occupancyFloor, nativeToolsEnabled)) ===
                     "stream_ended") {
                     return;
                 }
@@ -72,6 +75,7 @@ export class CursorProviderTurnRunner {
                 sdkEventDebug: this.sdkEventDebug,
                 throwIfAborted: () => this.throwIfAborted(),
                 resolvedConfig,
+                nativeToolsEnabled,
             });
             const usage = await this.params.usageRecorder.start({
                 agent: prepared.agent,
@@ -145,6 +149,13 @@ export class CursorProviderTurnRunner {
             });
         }
         catch (error) {
+            // This body owns the session turn lease; a queued request aborted before
+            // entry must not release another request's run in handleOuterCatch().
+            if (!prepared && (error instanceof CursorLiveRunAbortError || options?.signal?.aborted)) {
+                const pending = cursorLiveRuns.getActiveForScope(this.params.scope.scopeKey);
+                if (pending && !pending.disposed)
+                    await cursorLiveRuns.release(pending);
+            }
             await runFinalizer.applyTerminalEvent({ kind: "error", prepared: started ?? prepared, error });
         }
         finally {

package/dist/cursor-provider-turn-send.js

@@ -3,6 +3,7 @@ import { createCursorCloudLifecyclePersistenceError } from "./cursor-cloud-lifec
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { consumeCursorLocalForceOverride } from "./cursor-runtime-state.js";
 import { recordCursorSessionAgentLineage } from "./cursor-session-agent-lineage.js";
+import { watchCursorLocalRunTerminalError } from "./cursor-local-run-terminal-error.js";
 const CLOUD_LEDGER_CANCEL_TIMEOUT_MS = 5000;
 async function requestBoundedCloudRunCancellation(run) {
     let timer;
@@ -105,6 +106,8 @@ export async function sendCursorProviderTurn(sendParams) {
             recordCursorSessionAgentLineage(agent.agentId, params.scope.scopeKey);
         }
         const run = await runPromise;
+        if (prepared.runtimeTarget === "local")
+            watchCursorLocalRunTerminalError(prepared.store, run);
         sdkRun = run;
         runtime.sdkRun = run;
         try {

package/dist/cursor-provider.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "@earendil-works/pi-ai";
-import { cursorLiveRuns, DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS, getPendingCursorLiveRun, hasTrailingUserMessagesAfterToolResults, releaseAllPendingCursorLiveRunsForTests, resetCursorNativeReplayIdleDisposeMs, setCursorNativeReplayIdleDisposeMs, } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns, hasTrailingUserMessagesAfterToolResults, releaseAllPendingCursorLiveRunsForTests, resetCursorNativeReplayIdleDisposeMs, setCursorNativeReplayIdleDisposeMs, } from "./cursor-provider-live-run-drain.js";
 import { disposeAllSessionCursorAgents } from "./cursor-session-agent.js";
 import { attachCursorSdkEventDebugPiStreamTap } from "./cursor-sdk-event-debug.js";
 import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
@@ -66,10 +66,7 @@ export function streamCursor(model, context, options, ownership) {
     return stream;
 }
 export const __testUtils = {
-    DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
     pendingCursorNativeRunCount: cursorLiveRuns.count,
-    getPendingCursorLiveRun,
-    getActiveCursorLiveRunForScope: cursorLiveRuns.getActiveForScope,
     hasTrailingUserMessagesAfterToolResults,
     setCursorNativeReplayIdleDisposeMs,
     resetCursorNativeReplayIdleDisposeMs,

package/dist/cursor-runtime-state.js

@@ -4,8 +4,8 @@ import { asRecord } from "./cursor-record-utils.js";
 import { getResolvedSessionCursorHttp1Enabled } from "./cursor-http1.js";
 import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { cursorSettingsScopeForContext, getCursorSessionSettings } from "./cursor-session-settings.js";
-export const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
-export const CURSOR_CLOUD_ACK_DISCLOSURE = [
+const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
+const CURSOR_CLOUD_ACK_DISCLOSURE = [
     "Cursor Cloud executes this work remotely.",
     "Fresh context is used by default; prior Pi context is included only with explicit bootstrap opt-in.",
     "Pi-local tools and the Pi bridge are unavailable, and Pi environment variables are not forwarded.",
@@ -76,7 +76,7 @@ export function resolveCursorStatusRuntime(ctx) {
         return { kind: "invalid", message: error instanceof Error ? error.message : String(error) };
     }
 }
-export function formatResolvedCursorRuntime(runtime) {
+function formatResolvedCursorRuntime(runtime) {
     const cap = runtime.cappedBy;
     return cap
         ? `${runtime.value} (source: ${runtime.source} safety cap over ${cap.cappedSource} ${cap.cappedValue})`