pi-cursor-sdk 0.1.18 → 0.1.20

package/src/cursor-agents-context.ts

@@ -0,0 +1,176 @@
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BuildSystemPromptOptions,
+	ExtensionAPI,
+	ExtensionContext,
+	ExtensionHandler,
+} from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import { isCursorModel } from "./cursor-model.js";
+import {
+	cursorSettingSourcesLoadProjectAgentsRules,
+	cursorSettingSourcesLoadUserAgentsRules,
+	getEffectiveCursorSettingSources,
+} from "./cursor-setting-sources.js";
+import type { SettingSource } from "@cursor/sdk";
+
+export const CURSOR_PRESERVE_PI_AGENTS_MD_ENV = "PI_CURSOR_PRESERVE_PI_AGENTS_MD";
+
+/** Opening tag prefix pi `buildSystemPrompt()` uses for each context file (path attribute only). */
+export const PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX = '<project_instructions path="';
+const PI_PROJECT_INSTRUCTIONS_CLOSE = "</project_instructions>";
+const PI_PROJECT_CONTEXT_OPEN = "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n";
+const PI_PROJECT_CONTEXT_CLOSE = "</project_context>\n";
+
+function normalizeContextPath(filePath: string): string {
+	return filePath.replace(/\\/g, "/");
+}
+
+function normalizeDirPath(dirPath: string): string {
+	const normalized = normalizeContextPath(dirPath).replace(/\/+$/, "");
+	return normalized || "/";
+}
+
+export type PiAgentsContextFile = {
+	path: string;
+	content: string;
+};
+
+/** Overlap classes for pi context files that Cursor also loads via `settingSources`. */
+export type PiAgentsContextOverlap = "none" | "cursor-user-agents" | "cursor-project-rules";
+
+/** Pi context filenames that can overlap Cursor project/user ambient rules. */
+const CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES = new Set(["agents.md", "claude.md"]);
+
+export function getAgentsContextFileBaseName(filePath: string): string {
+	const normalized = normalizeContextPath(filePath);
+	return normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
+}
+
+/** Actual pi agent dir `AGENTS.md` — overlaps Cursor `user` setting source (global agent instructions). */
+export function isPiAgentDirAgentsMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
+	const normalized = normalizeContextPath(filePath);
+	const agentsMdPath = `${normalizeDirPath(agentDir)}/agents.md`;
+	return normalized.toLowerCase() === agentsMdPath.toLowerCase();
+}
+
+/** Actual pi agent dir `CLAUDE.md` — kept because Cursor user rules use `~/.claude/CLAUDE.md`. */
+export function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
+	const normalized = normalizeContextPath(filePath);
+	const claudeMdPath = `${normalizeDirPath(agentDir)}/claude.md`;
+	return normalized.toLowerCase() === claudeMdPath.toLowerCase();
+}
+
+/**
+ * Classify whether a pi-loaded context file overlaps Cursor ambient rules.
+ * Project/repo `AGENTS.md` and `CLAUDE.md` overlap Cursor `project` sources.
+ * Only the actual pi agent dir `AGENTS.md` overlaps Cursor `user`; agent-dir `CLAUDE.md` is kept
+ * because Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir path.
+ */
+export function classifyContextFileOverlap(
+	filePath: string,
+	agentDir: string = getAgentDir(),
+): PiAgentsContextOverlap {
+	const base = getAgentsContextFileBaseName(filePath);
+	if (!CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES.has(base)) return "none";
+	if (base === "agents.md" && isPiAgentDirAgentsMdPath(filePath, agentDir)) return "cursor-user-agents";
+	if (base === "claude.md" && isPiAgentDirClaudeMdPath(filePath, agentDir)) return "none";
+	return "cursor-project-rules";
+}
+
+export function shouldRemovePiAgentsContextFile(
+	file: PiAgentsContextFile,
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): boolean {
+	switch (classifyContextFileOverlap(file.path, agentDir)) {
+		case "cursor-user-agents":
+			return cursorSettingSourcesLoadUserAgentsRules(settingSources);
+		case "cursor-project-rules":
+			return cursorSettingSourcesLoadProjectAgentsRules(settingSources);
+		default:
+			return false;
+	}
+}
+
+export function shouldSuppressPiAgentsContext(
+	model: ExtensionContext["model"],
+	contextFiles: readonly PiAgentsContextFile[],
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): boolean {
+	if (!isCursorModel(model)) return false;
+	if (parseEnvBoolean(process.env[CURSOR_PRESERVE_PI_AGENTS_MD_ENV], false)) return false;
+	if (contextFiles.length === 0) return false;
+	return contextFiles.some((file) => shouldRemovePiAgentsContextFile(file, settingSources, agentDir));
+}
+
+/** Exact pi `buildSystemPrompt()` serialization for one context file block (including trailing blank line). */
+export function serializePiProjectInstructionsBlock(file: PiAgentsContextFile): string {
+	return `${PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX}${file.path}">\n${file.content}\n${PI_PROJECT_INSTRUCTIONS_CLOSE}\n\n`;
+}
+
+/** Exact pi `buildSystemPrompt()` serialization for the full project context section. */
+export function serializePiProjectContextSection(contextFiles: readonly PiAgentsContextFile[]): string {
+	if (contextFiles.length === 0) return "";
+	return `${PI_PROJECT_CONTEXT_OPEN}${contextFiles.map(serializePiProjectInstructionsBlock).join("")}${PI_PROJECT_CONTEXT_CLOSE}`;
+}
+
+/** Remove pi context blocks that overlap Cursor setting sources. */
+export function removePiAgentsContextFromSystemPrompt(
+	systemPrompt: string,
+	contextFiles: readonly PiAgentsContextFile[],
+	settingSources: SettingSource[] | undefined,
+	agentDir?: string,
+): string {
+	const retainedContextFiles: PiAgentsContextFile[] = [];
+	let removedAny = false;
+	for (const file of contextFiles) {
+		if (shouldRemovePiAgentsContextFile(file, settingSources, agentDir)) {
+			removedAny = true;
+			continue;
+		}
+		retainedContextFiles.push(file);
+	}
+	if (!removedAny) return systemPrompt;
+
+	const originalSection = serializePiProjectContextSection(contextFiles);
+	const start = systemPrompt.indexOf(originalSection);
+	if (start < 0) return systemPrompt;
+
+	const replacementSection = serializePiProjectContextSection(retainedContextFiles);
+	return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+}
+
+export function resolveCursorFacingSystemPrompt(
+	systemPrompt: string,
+	model: ExtensionContext["model"],
+	systemPromptOptions?: BuildSystemPromptOptions,
+	settingSourcesRaw?: string,
+	agentDir?: string,
+): string {
+	if (!systemPromptOptions) return systemPrompt;
+	const contextFiles = systemPromptOptions.contextFiles ?? [];
+	const settingSources = getEffectiveCursorSettingSources(settingSourcesRaw);
+	if (!shouldSuppressPiAgentsContext(model, contextFiles, settingSources, agentDir)) {
+		return systemPrompt;
+	}
+	return removePiAgentsContextFromSystemPrompt(systemPrompt, contextFiles, settingSources, agentDir);
+}
+
+type CursorAgentsContextExtensionApi = Pick<ExtensionAPI, "on">;
+
+export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
+	const handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult> = (event, ctx) => {
+		const resolved = resolveCursorFacingSystemPrompt(
+			event.systemPrompt,
+			ctx.model,
+			event.systemPromptOptions,
+		);
+		if (resolved === event.systemPrompt) return;
+		return { systemPrompt: resolved };
+	};
+	pi.on("before_agent_start", handler);
+}

package/src/cursor-incomplete-tool-visibility.ts

@@ -0,0 +1,124 @@
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME } from "./cursor-tool-names.js";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import {
+	DISCARDED_INCOMPLETE_TOOL_CALL_REASON,
+	type DiscardedIncompleteStartedToolCallReason,
+} from "./cursor-sdk-event-debug.js";
+import { truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
+
+export type IncompleteCursorToolDiscardReason = DiscardedIncompleteStartedToolCallReason;
+
+export interface IncompleteCursorToolRunOutcome {
+	reason: IncompleteCursorToolDiscardReason;
+	assistantTextProduced: boolean;
+}
+
+export interface IncompleteCursorToolRunOutcomeInput {
+	reason?: IncompleteCursorToolDiscardReason;
+	status?: string;
+	signalAborted?: boolean;
+	assistantTextProduced?: boolean;
+}
+
+export type IncompleteCursorToolVisibilityDecision = "emit" | "suppress" | "debugOnly";
+
+export function buildIncompleteCursorToolRunOutcome(
+	outcome: IncompleteCursorToolRunOutcomeInput = {},
+): IncompleteCursorToolRunOutcome {
+	return {
+		reason:
+			outcome.reason ??
+			(outcome.status === "cancelled" || outcome.signalAborted
+				? "abort"
+				: outcome.status === "error"
+					? "sdk-failure"
+					: DISCARDED_INCOMPLETE_TOOL_CALL_REASON),
+		assistantTextProduced: outcome.assistantTextProduced ?? false,
+	};
+}
+
+export function resolveIncompleteCursorToolVisibility(
+	toolCall: unknown,
+	outcome: IncompleteCursorToolRunOutcome,
+): IncompleteCursorToolVisibilityDecision {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	if (
+		outcome.reason === DISCARDED_INCOMPLETE_TOOL_CALL_REASON &&
+		outcome.assistantTextProduced &&
+		visibility.fastLocalDiscovery
+	) {
+		return "debugOnly";
+	}
+	return "emit";
+}
+
+function buildGenericIncompleteActivityTitle(displayName: string): string {
+	if (!displayName || displayName === "unknown") return "Cursor tool";
+	return `Cursor ${truncateArg(displayName)}`;
+}
+
+export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToolDiscardReason): string {
+	switch (reason) {
+		case DISCARDED_INCOMPLETE_TOOL_CALL_REASON:
+			return "missing completion";
+		case "abort":
+			return "aborted";
+		case "sdk-failure":
+			return "SDK run failed";
+		case "run-drain":
+			return "run ended during drain";
+	}
+}
+
+export function getIncompleteCursorToolActivityTitle(toolCall: unknown): string {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	return visibility.incompleteTitle ?? buildGenericIncompleteActivityTitle(visibility.displayName);
+}
+
+export function buildIncompleteCursorToolDisplay(
+	toolCall: unknown,
+	reason: IncompleteCursorToolDiscardReason,
+	options: { apiKey?: string } = {},
+): CursorPiToolDisplay {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	const activityTitle = getIncompleteCursorToolActivityTitle(toolCall);
+	const headline = `${activityTitle} did not complete`;
+	const reasonText = scrubSensitiveText(formatIncompleteCursorToolReasonText(reason), options.apiKey);
+	const contentText = `${headline}\n${reasonText}`;
+	return {
+		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
+		args: {
+			cursorToolName: visibility.normalizedName,
+			activityTitle,
+			activitySummary: reasonText,
+			incomplete: true,
+		},
+		result: {
+			content: [{ type: "text", text: contentText }],
+			details: {
+				cursorToolName: visibility.normalizedName,
+				title: headline,
+				summary: reasonText,
+			},
+		},
+		isError: true,
+	};
+}
+
+export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): string {
+	const details = display.result.details;
+	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
+	const argsRecord = display.args;
+	const title =
+		(typeof detailRecord?.title === "string" && detailRecord.title.trim()) ||
+		(typeof argsRecord.activityTitle === "string" && argsRecord.activityTitle.trim()
+			? `${argsRecord.activityTitle} did not complete`
+			: "Cursor tool did not complete");
+	const summary =
+		(typeof detailRecord?.summary === "string" && detailRecord.summary.trim()) ||
+		(typeof argsRecord.activitySummary === "string" && argsRecord.activitySummary.trim()) ||
+		formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
+	return `${truncateCursorDisplayLine(title)}: ${truncateCursorDisplayLine(summary)}\n`;
+}

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

@@ -10,6 +10,7 @@ import {
 import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display.js";
 import type { CursorPiBridgeToolRequest, CursorPiToolBridgeRun } from "./cursor-pi-tool-bridge.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export class CursorLiveRunAbortError extends Error {
 	constructor() {
@@ -46,7 +47,9 @@ export interface CursorLiveRun {
 	cancelled: boolean;
 	disposed: boolean;
 	errorMessage?: string;
+	abortMessage?: string;
 	chainUserInputAfterCompletion: boolean;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export interface CursorLiveRunCreateParams {
@@ -57,6 +60,7 @@ export interface CursorLiveRunCreateParams {
 	sessionAgentScopeKey?: string;
 	promptInputTokens: number;
 	textDeltas?: string[];
+	debugRecorder?: CursorSdkEventDebugRecorder;
 }
 
 export interface CursorLiveRunCoordinatorDeps {
@@ -70,7 +74,7 @@ export interface CursorLiveRunCoordinator {
 	start(params: CursorLiveRunCreateParams): CursorLiveRun;
 	attachSdkRun(run: CursorLiveRun, sdkRun: CursorLiveSdkRun): void;
 	markFinished(run: CursorLiveRun, finalText: string): void;
-	markCancelled(run: CursorLiveRun): void;
+	markCancelled(run: CursorLiveRun, abortMessage?: string): void;
 	markError(run: CursorLiveRun, errorMessage: string): void;
 	queueEvent(run: CursorLiveRun, event: CursorLiveQueuedEvent): void;
 	peekEvent(run: CursorLiveRun): CursorLiveQueuedEvent | undefined;
@@ -268,6 +272,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 				cancelled: false,
 				disposed: false,
 				chainUserInputAfterCompletion: false,
+				debugRecorder: params.debugRecorder,
 			};
 			privateStates.set(run, {
 				waiters: new Set(),
@@ -294,9 +299,10 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			coordinator.requestIdleDispose(run);
 		},
 
-		markCancelled(run): void {
+		markCancelled(run, abortMessage): void {
 			if (run.disposed) return;
 			run.cancelled = true;
+			run.abortMessage = abortMessage;
 			run.done = true;
 			notifyProgress(run);
 			coordinator.requestIdleDispose(run);
@@ -313,6 +319,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 		queueEvent(run, event): void {
 			if (run.disposed) return;
 			run.pendingEvents.push(event);
+			run.debugRecorder?.recordLiveRunEvent(event);
 			notifyProgress(run);
 		},
 
@@ -433,7 +440,9 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 			if (state.leased || state.leaseQueue.length > 0) return;
 			state.idleDisposeRequested = false;
 			state.idleDisposeTimer = setTimeout(() => {
-				void coordinator.release(run);
+				void coordinator.release(run).catch(() => {
+					// Idle dispose must not leave release failures as unhandled rejections.
+				});
 			}, deps.getIdleDisposeMs());
 			state.idleDisposeTimer.unref?.();
 		},
@@ -463,10 +472,12 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 					}
 				}
 				if (abandoned) {
-					try {
-						await run.sdkRun?.cancel();
-					} catch {
-						// cancellation failure should not block session-agent abandonment
+					if (!run.done) {
+						try {
+							await run.sdkRun?.cancel();
+						} catch {
+							// cancellation failure should not block session-agent abandonment
+						}
 					}
 					await deps.abandonSessionAgent(run.sessionAgentScopeKey);
 				}

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

@@ -1,17 +1,23 @@
 const CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS = 3_600_000;
+const DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS = 10_000;
+const MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS = 1_000;
 const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
 const CURSOR_MCP_TOOL_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_MS";
 const CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS";
+const CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_MS";
+const CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV = "PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS";
 
 interface CursorMcpToolTimeoutOverrideOptions {
 	timeoutMs?: number;
+	connectTimeoutMs?: number;
 	env?: Record<string, string | undefined>;
 }
 
 interface CursorMcpToolTimeoutOverrideState {
 	installed: boolean;
 	timeoutMs: number;
+	connectTimeoutMs: number;
 	sdkDefaultTimeoutMs: number;
 }
 
@@ -20,7 +26,8 @@ type SetTimeoutHandler = Parameters<GlobalSetTimeout>[0];
 type SetTimeoutDelay = Parameters<GlobalSetTimeout>[1];
 
 let originalSetTimeout: GlobalSetTimeout | undefined;
-let installedTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+let installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+let installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 
 function parsePositiveNumber(value: string | undefined): number | undefined {
 	const trimmed = value?.trim();
@@ -46,15 +53,47 @@ export function resolveCursorMcpToolTimeoutMs(
 	return DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
 }
 
-export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+function normalizeConnectTimeoutMs(timeoutMs: number): number {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
+	return Math.min(
+		Math.max(Math.trunc(timeoutMs), MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS),
+		CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
+	);
+}
+
+export function resolveCursorMcpConnectTimeoutMs(
+	env: Record<string, string | undefined> = process.env,
+): number {
+	const explicitMs = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV]);
+	if (explicitMs !== undefined) return normalizeConnectTimeoutMs(explicitMs);
+
+	const explicitSeconds = parsePositiveNumber(env[CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV]);
+	if (explicitSeconds !== undefined) return normalizeConnectTimeoutMs(explicitSeconds * 1000);
+
+	return DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
+}
+
+function isCursorSdkMcpProtocolTimeoutStack(stack: string | undefined): boolean {
 	if (!stack) return false;
 	return (
 		/(?:node_modules[/\\]@cursor[/\\]sdk|node_modules\/\@cursor\/sdk|@cursor\/sdk\/dist)/.test(stack) &&
-		/\b_setupTimeout\b|\bProtocol\._setupTimeout\b/.test(stack) &&
+		/\b_setupTimeout\b|\bProtocol\._setupTimeout\b/.test(stack)
+	);
+}
+
+export function isCursorSdkMcpToolTimeoutStack(stack: string | undefined): boolean {
+	if (!stack) return false;
+	return (
+		isCursorSdkMcpProtocolTimeoutStack(stack) &&
 		/\bcallTool\b|\bClient\.callTool\b|\bMcpSdkClient\.callTool\b/.test(stack)
 	);
 }
 
+export function isCursorSdkMcpConnectTimeoutStack(stack: string | undefined): boolean {
+	if (!stack || !isCursorSdkMcpProtocolTimeoutStack(stack)) return false;
+	return /\bClient\.(?:connect|listTools)\b|\bMcpSdkClient\.getTools\b/.test(stack);
+}
+
 function isCursorSdkDefaultMcpTimeout(delay: SetTimeoutDelay): boolean {
 	return typeof delay === "number" && delay === CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS;
 }
@@ -67,10 +106,15 @@ function patchedSetTimeout(
 	const delegate = originalSetTimeout;
 	if (!delegate) throw new Error("Cursor MCP timeout override installed without original setTimeout");
 
-	const nextDelay =
-		isCursorSdkDefaultMcpTimeout(delay) && isCursorSdkMcpToolTimeoutStack(new Error().stack)
-			? installedTimeoutMs
-			: delay;
+	let nextDelay = delay;
+	if (isCursorSdkDefaultMcpTimeout(delay)) {
+		const stack = new Error().stack;
+		if (isCursorSdkMcpToolTimeoutStack(stack)) {
+			nextDelay = installedToolTimeoutMs;
+		} else if (isCursorSdkMcpConnectTimeoutStack(stack)) {
+			nextDelay = installedConnectTimeoutMs;
+		}
+	}
 
 	return Reflect.apply(delegate, globalThis, [handler, nextDelay, ...args]) as ReturnType<GlobalSetTimeout>;
 }
@@ -78,9 +122,12 @@ function patchedSetTimeout(
 export function installCursorMcpToolTimeoutOverride(
 	options: CursorMcpToolTimeoutOverrideOptions = {},
 ): CursorMcpToolTimeoutOverrideState {
-	installedTimeoutMs = normalizeOverrideTimeoutMs(
+	installedToolTimeoutMs = normalizeOverrideTimeoutMs(
 		options.timeoutMs ?? resolveCursorMcpToolTimeoutMs(options.env),
 	);
+	installedConnectTimeoutMs = normalizeConnectTimeoutMs(
+		options.connectTimeoutMs ?? resolveCursorMcpConnectTimeoutMs(options.env),
+	);
 
 	if (!originalSetTimeout) {
 		originalSetTimeout = globalThis.setTimeout;
@@ -89,23 +136,31 @@ export function installCursorMcpToolTimeoutOverride(
 
 	return {
 		installed: true,
-		timeoutMs: installedTimeoutMs,
+		timeoutMs: installedToolTimeoutMs,
+		connectTimeoutMs: installedConnectTimeoutMs,
 		sdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	};
 }
 
-export function restoreCursorMcpToolTimeoutOverrideForTests(): void {
+export function restoreCursorMcpToolTimeoutOverride(): void {
 	if (originalSetTimeout) {
 		globalThis.setTimeout = originalSetTimeout;
 		originalSetTimeout = undefined;
 	}
-	installedTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+	installedToolTimeoutMs = DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS;
+	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
 
+export const restoreCursorMcpToolTimeoutOverrideForTests = restoreCursorMcpToolTimeoutOverride;
+
 export const cursorMcpToolTimeoutOverrideDefaults = {
 	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,
+	defaultConnectTimeoutMs: DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS,
+	minConnectTimeoutMs: MIN_CURSOR_MCP_CONNECT_TIMEOUT_MS,
 	maxNodeTimerDelayMs: MAX_NODE_TIMER_DELAY_MS,
 	timeoutMsEnv: CURSOR_MCP_TOOL_TIMEOUT_MS_ENV,
 	timeoutSecondsEnv: CURSOR_MCP_TOOL_TIMEOUT_SECONDS_ENV,
+	connectTimeoutMsEnv: CURSOR_MCP_CONNECT_TIMEOUT_MS_ENV,
+	connectTimeoutSecondsEnv: CURSOR_MCP_CONNECT_TIMEOUT_SECONDS_ENV,
 } as const;

package/src/cursor-model.ts

@@ -0,0 +1,12 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const CURSOR_PROVIDER = "cursor";
+export const CURSOR_SDK_API = "cursor-sdk";
+
+export type CursorModelRef =
+	| Pick<NonNullable<ExtensionContext["model"]>, "provider" | "api">
+	| undefined;
+
+export function isCursorModel(model: CursorModelRef): boolean {
+	return model?.provider === CURSOR_PROVIDER || model?.api === CURSOR_SDK_API;
+}

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

@@ -6,6 +6,7 @@ import {
 	registerNativeCursorTool,
 	type NativeCursorToolName,
 } from "./cursor-native-tool-display-tools.js";
+import { isCursorModel } from "./cursor-model.js";
 import {
 	isCursorNativeToolDisplayRequested,
 	isCursorNativeToolRegistrationRequested,
@@ -33,10 +34,6 @@ function hasNonBuiltinTool(pi: Pick<ExtensionAPI, "getAllTools">, toolName: Nati
 
 type NativeRegistrationContext = { hasUI: boolean; ui: Pick<ExtensionContext["ui"], "notify">; model?: ExtensionContext["model"] };
 
-function isCursorModel(model: ExtensionContext["model"]): boolean {
-	return model?.provider === "cursor" || model?.api === "cursor-sdk";
-}
-
 export function syncRegisteredNativeCursorToolsForModel(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, model: ExtensionContext["model"]): void {
 	if (registeredNativeToolNames.size === 0) return;
 	const activeToolNames = new Set(pi.getActiveTools());