pi-cursor-sdk 0.5.0 → 0.5.2

package/src/cursor-api-key.ts

@@ -1,12 +1,9 @@
-import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { envApiKeyAuth, type ApiKeyAuth, type ApiKeyCredential } from "@earendil-works/pi-ai";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 
 export const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
-const CURSOR_PROVIDER_ID = "cursor";
 
-// Non-secret literal sentinel for pi's provider registry. Pi 0.77 treats `$ENV_VAR`
-// values as unconfigured when the env var is absent, which hides fallback models
-// before `/login`. Keep the provider available and resolve the real key in the
-// Cursor provider turn path from pi auth or CURSOR_API_KEY.
+// Legacy no-auth availability policy only; never a configured models.json key.
 export const CURSOR_API_KEY_CONFIG_VALUE = "pi-cursor-sdk-cursor-api-key-placeholder";
 
 const CURSOR_API_KEY_PLACEHOLDERS = new Set([
@@ -17,21 +14,44 @@ const CURSOR_API_KEY_PLACEHOLDERS = new Set([
 ]);
 
 export function resolveCursorApiKey(apiKey?: string): string | undefined {
+	return normalizeCursorApiKey(apiKey) ?? (apiKey && CURSOR_API_KEY_PLACEHOLDERS.has(apiKey.trim())
+		? normalizeCursorApiKey(process.env.CURSOR_API_KEY) : undefined);
+}
+
+export function normalizeCursorApiKey(apiKey?: string): string | undefined {
 	const trimmed = apiKey?.trim();
-	if (!trimmed) return undefined;
-	if (CURSOR_API_KEY_PLACEHOLDERS.has(trimmed)) return process.env.CURSOR_API_KEY?.trim() || undefined;
+	if (!trimmed || CURSOR_API_KEY_PLACEHOLDERS.has(trimmed)) return undefined;
 	return trimmed;
 }
 
-function getStoredCursorApiKey(): string | undefined {
-	try {
-		const credential = readStoredCredential(CURSOR_PROVIDER_ID);
-		return resolveCursorApiKey(credential?.type === "api_key" ? credential.key : undefined);
-	} catch {
-		return undefined;
-	}
+export async function resolveCursorCredentialApiKey(
+	credential: ApiKeyCredential | undefined,
+	environment: () => Promise<string | undefined>,
+): Promise<string | undefined> {
+	return normalizeCursorApiKey(credential?.key)
+		?? normalizeCursorApiKey(credential?.env?.CURSOR_API_KEY)
+		?? normalizeCursorApiKey(await environment());
 }
 
-export function resolveCursorRuntimeApiKey(): Promise<string | undefined> {
-	return Promise.resolve(getStoredCursorApiKey() ?? resolveCursorApiKey(process.env.CURSOR_API_KEY));
+export function cursorApiKeyAuth(): ApiKeyAuth {
+	const standard = envApiKeyAuth("Cursor API key", [CURSOR_API_KEY_ENV_VAR]);
+	const auth: ApiKeyAuth = {
+		name: standard.name,
+		login: standard.login,
+		async check(input) {
+			const resolved = await auth.resolve(input);
+			return resolved ? { type: "api_key", source: resolved.source } : undefined;
+		},
+		async resolve({ ctx, credential, signal }) {
+			signal.throwIfAborted();
+			const key = await resolveCursorCredentialApiKey(credential, () => ctx.env(CURSOR_API_KEY_ENV_VAR));
+			signal.throwIfAborted();
+			if (key) return { auth: { apiKey: key }, env: credential?.env, source: credential ? "stored credential" : CURSOR_API_KEY_ENV_VAR };
+			if (!parseEnvBoolean(process.env.PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT, false)) {
+				return { auth: { apiKey: CURSOR_API_KEY_CONFIG_VALUE }, source: "fallback" };
+			}
+			return undefined;
+		},
+	};
+	return auth;
 }

package/src/cursor-cloud-options.ts

@@ -49,6 +49,7 @@ export function buildCursorCloudAgentOptions(options: {
 	agentMode: AgentModeOption;
 	resolvedConfig: CursorResolvedSdkConfig;
 	name?: string;
+	agents?: AgentOptions["agents"];
 }): AgentOptions {
 	const { resolvedConfig } = options;
 	const environment = resolvedConfig.cloud.environment.value;
@@ -91,6 +92,7 @@ export function buildCursorCloudAgentOptions(options: {
 		model: options.modelSelection,
 		mode: options.agentMode,
 		...(options.name ? { name: options.name } : {}),
+		...(options.agents && Object.keys(options.agents).length ? { agents: options.agents } : {}),
 		cloud,
 	};
 }

package/src/cursor-config.ts

@@ -13,6 +13,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { parseOptionalEnvBoolean } from "./cursor-env-boolean.js";
 import { asRecord } from "./cursor-record-utils.js";
 
@@ -36,6 +37,7 @@ export const CURSOR_SANDBOX_ENV = "PI_CURSOR_SANDBOX";
 export const CURSOR_LOCAL_FORCE_ENV = "PI_CURSOR_LOCAL_FORCE";
 export const CURSOR_LOCAL_RESUME_ENV = "PI_CURSOR_LOCAL_RESUME";
 export const CURSOR_HTTP1_ENV = "PI_CURSOR_HTTP_1_1";
+export const CURSOR_STATE_ROOT_ENV = "PI_CURSOR_SDK_STATE_ROOT";
 
 export type CursorConfigSource = "cli" | "environment" | "project" | "user" | "session" | "model-alias" | "builtin";
 export type CursorConfigTrustLevel = "one-shot" | "environment" | "trusted-project" | "user" | "session" | "model-catalog" | "builtin";
@@ -48,9 +50,20 @@ export interface CursorCloudEnvironmentConfig {
 	name?: string;
 }
 
+export interface CursorCustomSubagentConfig {
+	description: string;
+	prompt: string;
+	model?: string;
+	thinking?: ModelThinkingLevel;
+	fast?: boolean;
+}
+
+export type CursorCustomSubagentsConfig = Record<string, CursorCustomSubagentConfig>;
+
 export interface CursorSdkConfig {
 	fastDefaults?: Record<string, boolean>;
 	runtime?: CursorRuntime;
+	subagents?: CursorCustomSubagentsConfig;
 	cloud?: {
 		repo?: string;
 		branch?: string;
@@ -73,6 +86,7 @@ export interface CursorSdkConfig {
 		force?: boolean;
 		resume?: boolean;
 		useHttp1ForAgent?: boolean;
+		storeRoot?: string;
 	};
 }
 
@@ -94,6 +108,7 @@ export interface CursorResolvedSetting<T> {
 
 export interface CursorResolvedSdkConfig {
 	runtime: CursorResolvedSetting<CursorRuntime>;
+	subagents: CursorResolvedSetting<CursorCustomSubagentsConfig | undefined>;
 	cloud: {
 		repo: CursorResolvedSetting<string | undefined>;
 		branch: CursorResolvedSetting<string | undefined>;
@@ -113,6 +128,7 @@ export interface CursorResolvedSdkConfig {
 		force: CursorResolvedSetting<boolean>;
 		resume: CursorResolvedSetting<boolean>;
 		useHttp1ForAgent: CursorResolvedSetting<boolean>;
+		storeRoot: CursorResolvedSetting<string | undefined>;
 	};
 }
 
@@ -237,6 +253,44 @@ function parseCloudEnvironment(value: unknown): CursorCloudEnvironmentConfig | u
 	return Object.keys(parsed).length > 0 ? parsed : undefined;
 }
 
+const THINKING_LEVELS = {
+	off: true,
+	minimal: true,
+	low: true,
+	medium: true,
+	high: true,
+	xhigh: true,
+	max: true,
+} satisfies Record<ModelThinkingLevel, true>;
+
+function isCursorSubagentThinkingLevel(value: unknown): value is ModelThinkingLevel {
+	return typeof value === "string" && Object.hasOwn(THINKING_LEVELS, value);
+}
+
+function parseCustomSubagents(value: unknown): CursorCustomSubagentsConfig | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const entries: Array<[string, CursorCustomSubagentConfig]> = [];
+	for (const [name, raw] of Object.entries(record)) {
+		// Extension config policy, not an upstream SDK naming restriction.
+		if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(name)) continue;
+		const entry = asRecord(raw);
+		const description = parseNonEmptyString(entry?.description);
+		const prompt = parseNonEmptyString(entry?.prompt);
+		if (!entry || !description || !prompt) continue;
+		const model = parseNonEmptyString(entry.model);
+		const thinking = entry.thinking;
+		entries.push([name, {
+			description,
+			prompt,
+			...(model ? { model } : {}),
+			...(isCursorSubagentThinkingLevel(thinking) ? { thinking } : {}),
+			...(typeof entry.fast === "boolean" ? { fast: entry.fast } : {}),
+		}]);
+	}
+	return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
 export function parseCursorSdkConfig(value: unknown): CursorSdkConfig | undefined {
 	const record = asRecord(value);
 	if (!record) return undefined;
@@ -244,6 +298,9 @@ export function parseCursorSdkConfig(value: unknown): CursorSdkConfig | undefine
 
 	if (isCursorRuntime(record.runtime)) config.runtime = record.runtime;
 
+	const subagents = parseCustomSubagents(record.subagents);
+	if (subagents) config.subagents = subagents;
+
 	const fastDefaults = asRecord(record.fastDefaults);
 	if (fastDefaults) {
 		config.fastDefaults = Object.fromEntries(
@@ -275,6 +332,7 @@ export function parseCursorSdkConfig(value: unknown): CursorSdkConfig | undefine
 	const local = asRecord(record.local);
 	if (local) {
 		const parsedLocal: NonNullable<CursorSdkConfig["local"]> = {};
+		if (typeof local.storeRoot === "string" && local.storeRoot.trim()) parsedLocal.storeRoot = local.storeRoot;
 		if (typeof local.autoReview === "boolean") parsedLocal.autoReview = local.autoReview;
 		if (typeof local.sandbox === "boolean") parsedLocal.sandbox = local.sandbox;
 		if (typeof local.force === "boolean") parsedLocal.force = local.force;
@@ -533,6 +591,8 @@ const CLOUD_ORDER: CursorFieldSource[] = ["cli", "environment", "session", "user
 const LOCAL_ORDER: CursorFieldSource[] = ["cli", "environment", "project", "user", "builtin"];
 const LOCAL_FORCE_ORDER: CursorFieldSource[] = ["cli", "environment", "builtin"];
 const HTTP1_ORDER: CursorFieldSource[] = ["session", "environment", "user", "builtin"];
+const SUBAGENTS_ORDER: CursorFieldSource[] = ["project", "user", "builtin"];
+const STORE_ROOT_ORDER: CursorFieldSource[] = ["environment", "user", "builtin"];
 
 function buildFieldLayers<T>(order: CursorFieldSource[], values: CursorFieldValues<T>): Array<CursorResolvedSetting<T> | undefined> {
 	return order.map((source) => (source === "builtin" ? resolved("builtin", values.builtin as T) : valueFrom(source, values[source])));
@@ -550,6 +610,16 @@ function resolveEnvNamesSafetyField(order: CursorFieldSource[], values: CursorFi
 	return resolveWithCap(buildFieldLayers(order, values), valueFrom("user", values.user), envNamesCap);
 }
 
+export function resolveCursorLocalStoreRoot(
+	{ env = process.env, user }: Pick<ResolveCursorSdkConfigOptions, "env" | "user"> = {},
+): CursorResolvedSetting<string | undefined> {
+	return resolveOrdinaryField(STORE_ROOT_ORDER, {
+		environment: env[CURSOR_STATE_ROOT_ENV]?.trim() ? env[CURSOR_STATE_ROOT_ENV] : undefined,
+		user: user?.local?.storeRoot?.trim() ? user.local.storeRoot : undefined,
+		builtin: undefined,
+	});
+}
+
 export function cursorSdkConfigFromEnv(env: Record<string, string | undefined> = process.env): CursorSdkConfig {
 	const config: CursorSdkConfig = {};
 	const runtime = validateExplicitValue(env[CURSOR_RUNTIME_ENV], CURSOR_RUNTIME_ENV, isCursorRuntime, '"local" or "cloud"');
@@ -648,6 +718,11 @@ export function resolveCursorSdkConfig(options: ResolveCursorSdkConfigOptions =
 			},
 			(value) => (value === "cloud" ? 1 : 0),
 		),
+		subagents: resolveOrdinaryField(SUBAGENTS_ORDER, {
+			project: parseCustomSubagents(project?.subagents),
+			user: parseCustomSubagents(user?.subagents),
+			builtin: undefined,
+		}),
 		cloud: {
 			repo: resolveOrdinaryField(CLOUD_ORDER, {
 				cli: cli?.cloud?.repo,
@@ -752,6 +827,7 @@ export function resolveCursorSdkConfig(options: ResolveCursorSdkConfigOptions =
 			}),
 		},
 		local: {
+			storeRoot: resolveCursorLocalStoreRoot({ env: options.env, user }),
 			autoReview: resolveOrdinaryField(LOCAL_ORDER, {
 				cli: cli?.local?.autoReview,
 				environment: env.local?.autoReview,

package/src/cursor-custom-store-path.ts

@@ -0,0 +1,151 @@
+import {
+	accessSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync,
+	openSync, realpathSync, type Stats,
+} from "node:fs";
+import { isAbsolute, join, parse, resolve, sep } from "node:path";
+import { noFollowFlag, openExistingRegularFileNoFollow, sameFileIdentity } from "./cursor-durable-fs.js";
+
+/** Lexical only: capture selection before acquisition awaits; fileless callers skip it. */
+export function normalizeCursorCustomStoreRoot(value: string): string {
+	const root = parse(value).root;
+	const components = value.slice(root.length).split(process.platform === "win32" ? /[\\/]/ : sep);
+	if (!isAbsolute(value) || !root || value.includes("\0") || components.some(part => part === "." || part === "..") ||
+		(process.platform === "win32" && (!/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+[\\/]?)$/.test(root) ||
+			/^[\\/]{2}[?.][\\/]/.test(value)))) {
+		throw new Error("Cursor local storeRoot must be a native fully qualified absolute path without dot components or device prefixes");
+	}
+	const normalized = resolve(value);
+	if (normalized === resolve(root)) throw new Error("Cursor local storeRoot must not be a filesystem or share root");
+	return normalized;
+}
+
+function invalid(path: string, reason: string): never {
+	throw new Error(`Cursor custom local store path ${reason}: ${path}`);
+}
+
+function statIfPresent(path: string): Stats | undefined {
+	try { return lstatSync(path); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+}
+
+function assertDirectory(path: string, stat: Stats, privateDirectory: boolean, afterShared: boolean): void {
+	if (!stat.isDirectory()) invalid(path, "contains a link or non-directory");
+	if (process.platform === "win32") return;
+	const uid = process.getuid!();
+	if (privateDirectory || afterShared) {
+		if (stat.uid !== uid) invalid(path, "is not owned by the current user");
+	} else if (stat.uid !== 0 && stat.uid !== uid) invalid(path, "has an untrusted owner");
+	const trustedShared = !privateDirectory && !afterShared && stat.uid === 0 && (stat.mode & 0o1000) !== 0;
+	if ((stat.mode & 0o022) !== 0 && !trustedShared) invalid(path, "is group or other writable");
+	if (privateDirectory && (stat.mode & 0o300) !== 0o300) invalid(path, "is not owner writable/searchable");
+}
+
+function restrictPrivateDirectory(path: string, before: Stats): void {
+	if (process.platform !== "win32") {
+		const fd = openSync(path, constants.O_RDONLY | noFollowFlag());
+		try {
+			const opened = fstatSync(fd);
+			if (!opened.isDirectory() || !sameFileIdentity(before, opened) || !sameFileIdentity(opened, lstatSync(path))) {
+				invalid(path, "changed while opening");
+			}
+			fchmodSync(fd, 0o700);
+			const after = lstatSync(path);
+			if (!after.isDirectory() || !sameFileIdentity(opened, after)) invalid(path, "changed while restricting permissions");
+		} finally { closeSync(fd); }
+	}
+	accessSync(path, constants.W_OK | constants.X_OK);
+}
+
+function assertTrustedSystemTarget(target: string): void {
+	let path = parse(target).root;
+	for (const part of ["", ...target.slice(path.length).split(sep).filter(Boolean)]) {
+		path = join(path, part);
+		const stat = lstatSync(path);
+		if (!stat.isDirectory() || stat.uid !== 0 || ((stat.mode & 0o022) !== 0 && !(stat.mode & 0o1000))) {
+			invalid(path, "has an untrusted system-link target");
+		}
+	}
+}
+
+/** Verify ancestors before individually creating components; never realpath an arbitrary user tree. */
+export function prepareCursorCustomStoreRoot(selectedRoot: string): string {
+	const normalized = normalizeCursorCustomStoreRoot(selectedRoot);
+	let path = parse(normalized).root;
+	let afterShared = false;
+	const components = normalized.slice(path.length).split(sep).filter(Boolean);
+	assertDirectory(path, lstatSync(path), false, false);
+	for (const [index, part] of components.entries()) {
+		path = join(path, part);
+		const leaf = index === components.length - 1;
+		let stat = statIfPresent(path);
+		if (stat?.isSymbolicLink()) {
+			if (process.platform === "win32" || leaf || afterShared || stat.uid !== 0) invalid(path, "contains a link or non-directory");
+			const target = realpathSync(path);
+			assertTrustedSystemTarget(target);
+			path = target;
+			stat = lstatSync(path);
+		}
+		if (!stat) {
+			try { mkdirSync(path, { mode: 0o700 }); }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+			stat = lstatSync(path);
+		}
+		assertDirectory(path, stat, leaf, afterShared);
+		if (leaf) restrictPrivateDirectory(path, stat);
+		if (process.platform !== "win32" && stat.uid === 0 && (stat.mode & 0o022) !== 0) afterShared = true;
+	}
+	return path;
+}
+
+/** Called after exact admission and again immediately before/after the public pathname-based SDK open. */
+export function guardCursorCustomStorePath(customRoot: string, stateRoot: string): { verify(): void } {
+	if (prepareCursorCustomStoreRoot(customRoot) !== customRoot) invalid(customRoot, "changed canonical identity");
+	const directories = [{ path: customRoot, stat: lstatSync(customRoot) }];
+	let path = customRoot;
+	for (const part of stateRoot.slice(customRoot.length + 1).split(sep)) {
+		path = join(path, part);
+		if (!statIfPresent(path)) {
+			try { mkdirSync(path, { mode: 0o700 }); }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+		}
+		const stat = lstatSync(path);
+		assertDirectory(path, stat, true, true);
+		restrictPrivateDirectory(path, stat);
+		directories.push({ path, stat });
+	}
+	const leaves = ["index.db", "index.db-wal", "index.db-shm", "index.db-journal"];
+	const originalLeaves = new Map<string, Stats>();
+	const checkLeaves = () => {
+		for (const name of leaves) {
+			const file = join(stateRoot, name);
+			const stat = statIfPresent(file);
+			if (!stat) {
+				if (name === "index.db" && originalLeaves.has(file)) invalid(file, "disappeared SQLite file");
+				continue;
+			}
+			if (!stat.isFile() || stat.nlink !== 1) invalid(file, "contains a linked or nonregular SQLite file");
+			if (process.platform !== "win32" && (stat.uid !== process.getuid!() || (stat.mode & 0o022))) {
+				invalid(file, "contains an unowned or shared SQLite file");
+			}
+			const before = originalLeaves.get(file);
+			if (before && !sameFileIdentity(before, stat)) invalid(file, "changed SQLite file identity");
+			const fd = openExistingRegularFileNoFollow(file, constants.O_RDWR);
+			closeSync(fd);
+			originalLeaves.set(file, stat);
+		}
+	};
+	checkLeaves();
+	// ponytail: the public SDK uses pathname/lazy checkpoint opens. This guards
+	// current-user private contents, not hostile same-user/admin races. Windows
+	// rejects Node-visible links/junctions but has no ACL hardening/O_NOFOLLOW
+	// equivalent here; use an ACL-protected root. Upgrade with public native APIs.
+	return { verify() {
+		if (prepareCursorCustomStoreRoot(customRoot) !== customRoot) invalid(customRoot, "changed canonical identity");
+		for (const { path, stat } of directories) {
+			const after = lstatSync(path);
+			assertDirectory(path, after, true, true);
+			if (!sameFileIdentity(stat, after)) invalid(path, "changed directory identity");
+		}
+		checkLeaves();
+	} };
+}

package/src/cursor-custom-subagent-definitions.ts

@@ -0,0 +1,21 @@
+import type { AgentOptions } from "@cursor/sdk";
+import type { CursorCustomSubagentsConfig } from "./cursor-config.js";
+import { buildCursorModelSelection, getCursorModelMetadata } from "./model-discovery.js";
+
+export function buildCursorCustomSubagentDefinitions(config: CursorCustomSubagentsConfig | undefined): AgentOptions["agents"] {
+	if (!config || !Object.keys(config).length) return undefined;
+	return Object.fromEntries(Object.entries(config).map(([name, entry]) => [name, {
+		description: entry.description,
+		prompt: entry.prompt,
+		...(entry.model === undefined ? {} : {
+			model: entry.model === "inherit" ? "inherit" : buildCursorModelSelection(
+				entry.model,
+				entry.thinking ?? "off",
+				getCursorModelMetadata(entry.model)?.fastOverride ?? entry.fast,
+			),
+		}),
+	}]));
+}
+
+// ponytail: SDK 1.0.36 LOCAL conversion keeps only model ID/inherit; it drops params.
+// Upgrade this claim only after the installed public converter preserves them.

package/src/cursor-fallback-models.generated.ts

@@ -1,6 +1,6 @@
 import type { ModelListItem } from "@cursor/sdk";
 
-// Generated with @cursor/sdk@1.0.32 from 45 Cursor models.
+// Generated with @cursor/sdk@1.0.36 from 45 Cursor models.
 // Refresh with: npm run refresh:cursor-snapshots -- --write
 // Do not add secrets; this file stores public model metadata only.
 export const FALLBACK_MODEL_ITEMS = [

package/src/cursor-fallback-warning.ts

@@ -8,15 +8,19 @@ export type CursorFallbackWarningExtensionApi = CursorModelLifecycleExtensionApi
 
 export function registerCursorFallbackIssueWarning(
 	pi: CursorFallbackWarningExtensionApi,
-	issue: CursorModelFallbackIssue,
-): void {
+): (nextIssue: CursorModelFallbackIssue | undefined) => void {
+	let issue: CursorModelFallbackIssue | undefined;
 	const warnedSessionScopeKeys = new Set<string>();
 
 	registerCursorModelLifecycle(pi, (ctx: ExtensionContext) => {
-		if (!isCursorModel(ctx.model) || !ctx.hasUI) return;
+		if (!issue || !isCursorModel(ctx.model) || !ctx.hasUI) return;
 		const scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
 		if (warnedSessionScopeKeys.has(scopeKey)) return;
 		warnedSessionScopeKeys.add(scopeKey);
 		ctx.ui.notify(issue.message, "warning");
 	});
+	return (nextIssue) => {
+		if (nextIssue?.reason !== issue?.reason || nextIssue?.message !== issue?.message) warnedSessionScopeKeys.clear();
+		issue = nextIssue;
+	};
 }

package/src/cursor-live-run-coordinator.ts

@@ -153,6 +153,7 @@ interface CursorLiveRunPrivateState {
 	waiters: Set<ProgressWaiter>;
 	idleDisposeTimer?: ReturnType<typeof setTimeout>;
 	idleDisposeRequested: boolean;
+	pendingCallUnsubscribers?: Array<() => void>;
 	leased: boolean;
 	leaseQueue: LeaseWaiter[];
 	releasing?: Promise<void>;
@@ -313,6 +314,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 				leased: false,
 				leaseQueue: [],
 			});
+			const state = getPrivateState(run);
+			state.pendingCallUnsubscribers = [...new Set([run.bridgeRun, run.sessionBridgeRun])].flatMap((bridge) =>
+				bridge ? [bridge.onPendingToolCallsChanged(() => {
+					if (state.idleDisposeRequested || state.idleDisposeTimer) coordinator.requestIdleDispose(run);
+				})] : [],
+			);
 			pendingRuns.set(run.id, run);
 			pendingRunIdsByScopeKey.set(sessionAgentScopeKey, run.id);
 			return run;
@@ -492,9 +499,15 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			const state = getPrivateState(run);
 			clearIdleDisposeTimer(run);
 			state.idleDisposeRequested = true;
-			if (state.leased || state.leaseQueue.length > 0) return;
-			state.idleDisposeRequested = false;
+			if (state.leased || state.leaseQueue.length > 0 ||
+				[run.bridgeRun, run.sessionBridgeRun].some((bridge) => bridge?.hasPendingToolCalls())) return;
 			state.idleDisposeTimer = setTimeout(() => {
+				state.idleDisposeTimer = undefined;
+				if (state.leased || state.leaseQueue.length > 0 ||
+					[run.bridgeRun, run.sessionBridgeRun].some((bridge) => bridge?.hasPendingToolCalls())) {
+					coordinator.requestIdleDispose(run);
+					return;
+				}
 				void coordinator.release(run).catch(() => {
 					// Idle dispose must not leave release failures as unhandled rejections.
 				});
@@ -509,6 +522,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 				if (run.disposed) return;
 				const abandoned = !isSuccessfulCursorLiveRun(run);
 				run.disposed = true;
+				for (const unsubscribe of state.pendingCallUnsubscribers ?? []) {
+					try { unsubscribe(); } catch {
+						// Cleanup continues even if an observer cannot detach.
+					}
+				}
+				state.pendingCallUnsubscribers = [];
 				unregister(run);
 				clearIdleDisposeTimer(run);
 				state.idleDisposeRequested = false;

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

@@ -91,7 +91,9 @@ export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boole
 
 export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
 	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
-	return /\bClient\.(?:connect|listTools)\b|\bMcpSdkClient\.getTools\b/.test(stack);
+	// SDK 1.0.36 minifies the Client class name; the protocol method and SDK
+	// frame, not that constructor's spelling, establish this timeout purpose.
+	return /^\s*at (?:[\w$]+\.)?(?:connect|listTools|getTools)\s*\(.*(?:node_modules[/\\]@cursor[/\\]sdk|@cursor\/sdk\/dist)/m.test(stack);
 }
 
 function isCursorSdkDefaultMcpTimeout(delay: SetTimeoutDelay): boolean {

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

@@ -67,6 +67,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	private readonly knownMcpToolNames: ReadonlySet<string>;
 	private readonly knownCursorMcpCallIds = new Set<string>();
 	private readonly queuedRequests: CursorPiBridgeToolRequest[] = [];
+	private readonly pendingToolCallListeners = new Set<() => void>();
 	private readonly pendingByPiToolCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByBridgeCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByCursorMcpCallId = new Map<string, PendingBridgeCall>();
@@ -190,6 +191,23 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		return this.pendingByPiToolCallId.has(piToolCallId);
 	}
 
+	hasPendingToolCalls(): boolean {
+		return this.pendingCount() > 0;
+	}
+
+	onPendingToolCallsChanged(listener: () => void): () => void {
+		this.pendingToolCallListeners.add(listener);
+		return () => { this.pendingToolCallListeners.delete(listener); };
+	}
+
+	private notifyPendingToolCallsChanged(): void {
+		for (const listener of this.pendingToolCallListeners) {
+			try { listener(); } catch {
+				// Observers must not prevent call registration or protocol settlement.
+			}
+		}
+	}
+
 	cancelPendingPiToolCallId(piToolCallId: string, reason: string): boolean {
 		const pending = this.pendingByPiToolCallId.get(piToolCallId);
 		if (!pending) return false;
@@ -234,6 +252,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		if (this.disposed) return;
 		this.disposed = true;
 		this.cancel("Cursor pi tool bridge run disposed");
+		this.pendingToolCallListeners.clear();
 		await waitForProtocolFlush();
 		await Promise.allSettled([
 			this.mcpTransport?.close(),
@@ -315,6 +334,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 			this.pendingByBridgeCallId.set(request.bridgeCallId, pending);
 			this.pendingByCursorMcpCallId.set(cursorMcpCallId, pending);
 			this.knownCursorMcpCallIds.add(cursorMcpCallId);
+			this.notifyPendingToolCallsChanged();
 			pending.timeout = setTimeout(() => {
 				const reason = `Cursor pi bridge CallTool timed out after ${this.callTimeoutMs} ms`;
 				this.rejectAndAbortPending(pending, new Error(reason));
@@ -438,5 +458,6 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		if (pending.request.cursorMcpCallId) this.pendingByCursorMcpCallId.delete(pending.request.cursorMcpCallId);
 		const queuedIndex = this.queuedRequests.findIndex((request) => request.bridgeCallId === pending.request.bridgeCallId);
 		if (queuedIndex >= 0) this.queuedRequests.splice(queuedIndex, 1);
+		this.notifyPendingToolCallsChanged();
 	}
 }

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

@@ -7,7 +7,7 @@ import type {
 	CursorPiToolBridgeSnapshotApi,
 } from "./cursor-pi-tool-bridge-types.js";
 import { asRecord } from "./cursor-record-utils.js";
-import type { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
+import { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
 import {
 	buildCursorPiToolBridgeSnapshot,
 	buildCursorPiToolBridgeSurfaceSignature,
@@ -55,7 +55,6 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 				exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(this.env),
 			})
 			: createEmptySnapshot();
-		const { CursorPiToolBridgeRunImpl } = await import("./cursor-pi-tool-bridge-run.js");
 		const run = new CursorPiToolBridgeRunImpl(this, this.env, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
 		this.runs.add(run);
 		await run.start();

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

@@ -60,6 +60,9 @@ export interface CursorPiToolBridgeRun {
 	resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void>;
 	resolveToolResultsFromContext(context: Context): Promise<void>;
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
+	hasPendingToolCalls(): boolean;
+	/** Synchronous changes; observer errors cannot affect settlement. Returns an idempotent unsubscribe. */
+	onPendingToolCallsChanged(listener: () => void): () => void;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;
 	setDebugRecorder(recorder?: CursorSdkEventDebugRecorder): void;