pi-cursor-sdk 0.5.3 → 0.5.4

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-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.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})`

package/dist/cursor-sdk-event-debug.js

@@ -60,10 +60,10 @@ export function resolveCursorSdkEventDebugEnabled(env = process.env) {
     return parseEnvBoolean(env[CURSOR_SDK_EVENT_DEBUG_ENV], false);
 }
 export const DISCARDED_INCOMPLETE_TOOL_CALL_REASON = "no-completion-at-run-end";
-export function hashCursorSdkCallId(callId) {
+function hashCursorSdkCallId(callId) {
     return createHash("sha256").update(callId).digest("hex").slice(0, 8);
 }
-export function serializeDiscardedIncompleteStartedToolCall(record) {
+function serializeDiscardedIncompleteStartedToolCall(record) {
     return {
         event: "discarded-incomplete-started-tool-call",
         toolName: record.toolName,

package/dist/cursor-sdk-output-filter.js

@@ -1 +1 @@
-export { CURSOR_SDK_STARTUP_NOISE_PATTERNS, withCursorSdkOutputNoticeHandler, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";
+export { __testUtils, installCursorSdkProcessOutputFilter, withCursorSdkOutputNoticeHandler, installCursorSdkOutputFilter, isCursorSdkOutputSuppressed, isCursorSdkStartupNoise, suppressCursorSdkOutput, } from "../shared/cursor-sdk-output-filter.mjs";

package/dist/cursor-sdk-process-error-guard.js

@@ -1,4 +1,4 @@
-import { classifyCursorConnectError, isCursorSdkAbortConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
+import { classifyCursorConnectError, isCursorSdkConnectionStalledError } from "./cursor-provider-errors.js";
 // Cursor SDK controlled-exec tasks can reject after their originating provider turn
 // has ended. The exact closed-writable failure is therefore session-scoped; existing
 // ConnectRPC suppression remains scoped to active provider turns.
@@ -128,7 +128,6 @@ export const __testUtils = {
         lifecycleSessionGuards.clear();
     },
 };
-export { isCursorSdkAbortConnectError };
 export function installCursorSdkProcessErrorGuard() {
     const token = { suppressAbortErrors: false };
     activeProviderTurns.add(token);

package/dist/cursor-session-agent.js

@@ -42,7 +42,7 @@ function rethrowSupersededWhenReplacedByDifferentPoolIdentity(scopeKey, poolKey,
 const sessionAgentsByScope = new Map();
 const invalidatedScopeKeys = new Set();
 const deadTransportScopeKeys = new Set();
-let deadTransportAgentDisposeTimeoutMs = 3000;
+const DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS = 3000;
 const terminalDisposedScopeGenerations = new Map();
 const scopeCreationGenerations = new Map();
 const EMPTY_POOL_STATE = { status: "empty" };
@@ -121,6 +121,8 @@ function buildSessionAgentPoolKey(scopeKey, params) {
         buildApiKeyPoolKeyFingerprint(params.apiKey),
         buildBridgePoolKeySuffix("bridge" in params ? params.bridge : getRegisteredCursorPiToolBridge()),
         ...buildCustomSubagentPoolKeySuffix(params.agents),
+        // Omit for the default so historical durable keys remain byte-for-byte stable.
+        ...(params.nativeToolsEnabled === false ? ["tools:mcp-only"] : []),
     ].join("\0");
 }
 async function disposePoolEntry(entry, options) {
@@ -141,7 +143,7 @@ async function disposePoolEntry(entry, options) {
         await (options?.deadTransport
             ? Promise.race([
                 disposal,
-                new Promise((resolve) => setTimeout(resolve, deadTransportAgentDisposeTimeoutMs).unref?.()),
+                new Promise((resolve) => setTimeout(resolve, DEAD_TRANSPORT_AGENT_DISPOSE_TIMEOUT_MS).unref?.()),
             ])
             : disposal);
     }
@@ -343,6 +345,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
                 localSafety: params.localSafety,
                 store: sessionStore.store,
             }),
+            ...(params.nativeToolsEnabled === false ? { tools: ["mcp"] } : {}),
             ...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
             ...(params.agents && Object.keys(params.agents).length ? { agents: params.agents } : {}),
         });
@@ -404,7 +407,7 @@ async function createSessionAgentEntry(scopeKey, persistentStore, instanceId, se
     }
 }
 export { buildCursorSessionSendPrompt, MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP, planCursorSessionSend, } from "./cursor-session-send-policy.js";
-export function invalidateSessionAgent(scopeKey = getCursorSessionScopeKey(), options) {
+export function invalidateSessionAgent(scopeKey, options) {
     invalidatedScopeKeys.add(scopeKey);
     if (options?.deadTransport)
         deadTransportScopeKeys.add(scopeKey);
@@ -534,11 +537,6 @@ export const __testUtils = {
     resetSessionCursorAgent,
     refreshSessionCursorAgentConfig,
     disposeAllSessionCursorAgents,
-    setDeadTransportAgentDisposeTimeoutMs(ms) {
-        const previous = deadTransportAgentDisposeTimeoutMs;
-        deadTransportAgentDisposeTimeoutMs = ms;
-        return previous;
-    },
     SessionCursorAgentCreationSupersededError,
     SessionCursorAgentScopeClosedError,
 };

package/dist/cursor-session-scope.js

@@ -3,7 +3,7 @@ import { parseArgs } from "@earendil-works/pi-coding-agent";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 const EPHEMERAL_SESSION_SCOPE_PREFIX = "__ephemeral__:";
-export const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
+const MAX_CURSOR_SESSION_NAME_LENGTH = 100;
 const state = {
     sessionCwd: process.cwd(),
     sessionFile: undefined,
@@ -65,15 +65,9 @@ export function getCursorSessionScopeKey() {
 export function getCursorSessionScopeGeneration(scopeKey = getCursorSessionScopeKey()) {
     return scopeGenerations.get(scopeKey) ?? 0;
 }
-export function getCursorSessionCwd() {
-    return state.sessionCwd;
-}
 export function getCursorSessionProjectTrusted(pi) {
     return pi ? scopes.get(pi)?.projectTrusted === true : state.projectTrusted;
 }
-export function getCursorSessionName() {
-    return state.sessionName;
-}
 function normalizeCursorSessionName(name) {
     if (name === undefined)
         return undefined;

package/dist/cursor-session-store.js

@@ -9,7 +9,7 @@ let sdkOperationsForTests;
 const activeWorkspaceRoots = new Map();
 // ponytail: leases protect only extension-owned stores in this process. Other SDK
 // users/processes must stop before upgrade; a cross-process lock belongs in the SDK.
-export function hashCursorSessionStoreScope(scopeKey) {
+function hashCursorSessionStoreScope(scopeKey) {
     return createHash("sha256")
         .update("pi-cursor-sdk-session-store\0")
         .update(scopeKey)