pi-cursor-sdk 0.1.15 → 0.1.16

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

@@ -2,8 +2,16 @@ import { createHash, randomUUID } from "node:crypto";
 import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from "node:http";
 import type { AddressInfo } from "node:net";
 import type { McpServerConfig } from "@cursor/sdk";
-import type { Context } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
+import type {
+	ExtensionAPI,
+	ExtensionHandler,
+	SessionShutdownEvent,
+	ToolCallEvent,
+	ToolCallEventResult,
+	ToolInfo,
+	ToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
 import { Server as McpProtocolServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import {
@@ -12,10 +20,13 @@ import {
 	type CallToolResult,
 	type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
+import { buildCursorPiBridgeMcpToolDescription, CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX } from "./cursor-bridge-contract.js";
 import { isExcludedFromCursorBridgeExposure } from "./cursor-tool-names.js";
 
 const CURSOR_PI_TOOL_BRIDGE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE";
 const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+const CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_DEBUG";
+const CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX = "[pi-cursor-sdk:bridge]";
 const LOOPBACK_HOST = "127.0.0.1";
 const MCP_SERVER_NAME = "pi_tools";
 const MCP_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
@@ -25,6 +36,74 @@ const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "none", "no", "disable
 const ENABLED_ENV_VALUES = new Set(["1", "true", "on", "yes", "enabled"]);
 const OVERLAPPING_CURSOR_NATIVE_PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "write", "edit", "grep", "find", "ls"]);
 
+type CursorPiToolBridgeSkippedReason = "disabled" | "no_exposed_tools";
+type CursorPiToolBridgeRejectionKind = "cancelled" | "error";
+
+interface CursorPiToolBridgeLifecycleDiagnosticFields {
+	runId: string;
+	enabled: boolean;
+	exposedToolCount: number;
+	pendingCount: number;
+}
+
+interface CursorPiToolBridgeRunCreatedDiagnostic extends CursorPiToolBridgeLifecycleDiagnosticFields {
+	event: "run_created";
+}
+
+interface CursorPiToolBridgeRunSkippedDiagnostic extends CursorPiToolBridgeLifecycleDiagnosticFields {
+	event: "run_skipped";
+	reason: CursorPiToolBridgeSkippedReason;
+}
+
+interface CursorPiToolBridgeToolsExposedDiagnostic extends CursorPiToolBridgeLifecycleDiagnosticFields {
+	event: "tools_exposed";
+	pairs: Array<{ piToolName: string; mcpToolName: string }>;
+}
+
+interface CursorPiToolBridgeRunCancelledDiagnostic extends CursorPiToolBridgeLifecycleDiagnosticFields {
+	event: "run_cancelled";
+	queuedCount: number;
+	cancelledRequestCount: number;
+}
+
+interface CursorPiToolBridgeRunDisposedDiagnostic extends CursorPiToolBridgeLifecycleDiagnosticFields {
+	event: "run_disposed";
+}
+
+interface CursorPiToolBridgeRequestDiagnosticFields {
+	runId: string;
+	bridgeCallId: string;
+	cursorMcpCallId?: string;
+	piToolCallId: string;
+	mcpToolName: string;
+	piToolName: string;
+	pendingCount: number;
+}
+
+interface CursorPiToolBridgeRequestQueuedDiagnostic extends CursorPiToolBridgeRequestDiagnosticFields {
+	event: "request_queued";
+}
+
+interface CursorPiToolBridgeRequestResolvedDiagnostic extends CursorPiToolBridgeRequestDiagnosticFields {
+	event: "request_resolved";
+	isError: boolean;
+}
+
+interface CursorPiToolBridgeRequestRejectedDiagnostic extends CursorPiToolBridgeRequestDiagnosticFields {
+	event: "request_rejected";
+	rejectionKind: CursorPiToolBridgeRejectionKind;
+}
+
+export type CursorPiToolBridgeDiagnosticEvent =
+	| CursorPiToolBridgeRunCreatedDiagnostic
+	| CursorPiToolBridgeRunSkippedDiagnostic
+	| CursorPiToolBridgeToolsExposedDiagnostic
+	| CursorPiToolBridgeRunCancelledDiagnostic
+	| CursorPiToolBridgeRunDisposedDiagnostic
+	| CursorPiToolBridgeRequestQueuedDiagnostic
+	| CursorPiToolBridgeRequestResolvedDiagnostic
+	| CursorPiToolBridgeRequestRejectedDiagnostic;
+
 export interface CursorPiMcpInputSchema {
 	type: "object";
 	properties?: Record<string, object>;
@@ -66,23 +145,34 @@ export interface CursorPiToolBridgeRun {
 	mcpServers?: Record<string, McpServerConfig>;
 	snapshot: CursorPiToolBridgeSnapshot;
 	takeQueuedToolRequests(): CursorPiBridgeToolRequest[];
+	resolveToolResults(toolResults: readonly ToolResultMessage[]): void;
 	resolveToolResultsFromContext(context: Context): void;
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
+	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;
 	cancel(reason: string): void;
 	dispose(): Promise<void>;
 }
 
-export interface CursorPiToolBridgeRunOptions {
-	onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
-}
-
 export interface CursorPiToolBridge {
 	isEnabled(): boolean;
+	getToolSurfaceSignature(): string;
 	createRun(options?: CursorPiToolBridgeRunOptions): Promise<CursorPiToolBridgeRun>;
 	disposeAll(reason?: string): Promise<void>;
 }
 
+export interface CursorPiToolBridgeRunOptions {
+	onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+}
+
+type CursorPiToolBridgeSnapshotApi = Pick<ExtensionAPI, "getActiveTools" | "getAllTools">;
+
+interface CursorPiToolBridgeExtensionApi extends CursorPiToolBridgeSnapshotApi {
+	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
+	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent>): void;
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+}
+
 interface PendingBridgeCall {
 	request: CursorPiBridgeToolRequest;
 	resolve: (result: CallToolResult) => void;
@@ -92,6 +182,140 @@ interface PendingBridgeCall {
 	settled: boolean;
 }
 
+interface CursorPiToolBridgeActiveToolExecution {
+	toolCallId: string;
+	abort: () => Promise<void> | void;
+	cancelPending: (reason: string) => void;
+	signal?: AbortSignal;
+	onAbort?: () => void;
+}
+
+class CursorPiToolBridgeToolExecutionAbortTracker {
+	private readonly activeExecutions = new Map<string, CursorPiToolBridgeActiveToolExecution>();
+	private processSignalHandlersInstalled = false;
+
+	track(
+		toolCallId: string,
+		options: {
+			signal?: AbortSignal;
+			abort: () => Promise<void> | void;
+			cancelPending: (reason: string) => void;
+		},
+	): boolean {
+		this.finish(toolCallId);
+		const execution: CursorPiToolBridgeActiveToolExecution = {
+			toolCallId,
+			abort: options.abort,
+			cancelPending: options.cancelPending,
+			signal: options.signal,
+		};
+		if (options.signal?.aborted) {
+			this.cancelExecution(execution, "Cursor pi bridge tool execution was already aborted");
+			this.abortExecution(execution);
+			return false;
+		}
+
+		execution.onAbort = () => {
+			this.cancelExecution(execution, "Cursor pi bridge tool execution was aborted");
+			this.finish(toolCallId);
+		};
+		execution.signal?.addEventListener("abort", execution.onAbort, { once: true });
+		this.activeExecutions.set(toolCallId, execution);
+		this.installProcessSignalHandlers();
+		return true;
+	}
+
+	finish(toolCallId: string): void {
+		const execution = this.activeExecutions.get(toolCallId);
+		if (!execution) return;
+		if (execution.onAbort) execution.signal?.removeEventListener("abort", execution.onAbort);
+		this.activeExecutions.delete(toolCallId);
+		this.uninstallProcessSignalHandlersIfIdle();
+	}
+
+	finishAll(): void {
+		for (const toolCallId of [...this.activeExecutions.keys()]) this.finish(toolCallId);
+	}
+
+	abortAll(reason: string): void {
+		for (const execution of [...this.activeExecutions.values()]) {
+			this.cancelExecution(execution, reason);
+			this.abortExecution(execution);
+			this.finish(execution.toolCallId);
+		}
+	}
+
+	getActiveCount(): number {
+		return this.activeExecutions.size;
+	}
+
+	emitProcessAbortSignalForTests(signal: NodeJS.Signals): void {
+		this.abortActiveExecutions(signal, { preserveProcessSignalBehavior: true });
+	}
+
+	private readonly handleSigint = (): void => {
+		this.abortActiveExecutions("SIGINT");
+	};
+
+	private readonly handleSigterm = (): void => {
+		this.abortActiveExecutions("SIGTERM");
+	};
+
+	private installProcessSignalHandlers(): void {
+		if (this.processSignalHandlersInstalled) return;
+		this.processSignalHandlersInstalled = true;
+		process.on("SIGINT", this.handleSigint);
+		process.on("SIGTERM", this.handleSigterm);
+	}
+
+	private uninstallProcessSignalHandlersIfIdle(): void {
+		if (!this.processSignalHandlersInstalled || this.activeExecutions.size > 0) return;
+		this.processSignalHandlersInstalled = false;
+		process.off("SIGINT", this.handleSigint);
+		process.off("SIGTERM", this.handleSigterm);
+	}
+
+	private abortActiveExecutions(
+		signal: NodeJS.Signals,
+		options: { preserveProcessSignalBehavior?: boolean } = {},
+	): void {
+		if (this.activeExecutions.size === 0) return;
+		const shouldRestoreDefaultSignalBehavior =
+			options.preserveProcessSignalBehavior !== true && !this.hasExternalProcessSignalListeners(signal);
+		this.abortAll(`Cursor pi bridge tool execution interrupted by ${signal}`);
+		if (shouldRestoreDefaultSignalBehavior) this.restoreDefaultProcessSignalBehavior(signal);
+	}
+
+	private cancelExecution(execution: CursorPiToolBridgeActiveToolExecution, reason: string): void {
+		try {
+			execution.cancelPending(reason);
+		} catch {
+			// Cancellation is best-effort during process abort/shutdown cleanup; keep aborting siblings.
+		}
+	}
+
+	private abortExecution(execution: CursorPiToolBridgeActiveToolExecution): void {
+		try {
+			Promise.resolve(execution.abort()).catch(() => undefined);
+		} catch {
+			// Abort is best-effort during process abort/shutdown cleanup; keep aborting siblings.
+		}
+	}
+
+	private hasExternalProcessSignalListeners(signal: NodeJS.Signals): boolean {
+		const ownHandler = signal === "SIGINT" ? this.handleSigint : this.handleSigterm;
+		return process.listeners(signal).some((listener) => listener !== ownHandler);
+	}
+
+	private restoreDefaultProcessSignalBehavior(signal: NodeJS.Signals): void {
+		setImmediate(() => {
+			process.kill(process.pid, signal);
+		});
+	}
+}
+
+const bridgeToolExecutionAbortTracker = new CursorPiToolBridgeToolExecutionAbortTracker();
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
@@ -121,8 +345,12 @@ function stableNameHash(value: string): string {
 	return createHash("sha256").update(value).digest("hex").slice(0, 8);
 }
 
+function createCursorMcpCallDiagnosticId(cursorMcpCallId: string | undefined): string | undefined {
+	return cursorMcpCallId ? `cursor-mcp-call-${stableNameHash(cursorMcpCallId)}` : undefined;
+}
+
 function createMcpToolName(piToolName: string, usedMcpToolNames: Set<string>): string {
-	const baseName = `pi__${sanitizeMcpToolNameStem(piToolName)}`;
+	const baseName = `${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}${sanitizeMcpToolNameStem(piToolName)}`;
 	if (!usedMcpToolNames.has(baseName)) {
 		usedMcpToolNames.add(baseName);
 		return baseName;
@@ -168,12 +396,137 @@ export function resolveCursorPiToolBridgeBuiltinsEnabled(env: Record<string, str
 	return false;
 }
 
+export function resolveCursorPiToolBridgeDebugEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	const raw = env[CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV]?.trim().toLowerCase();
+	if (!raw) return false;
+	if (ENABLED_ENV_VALUES.has(raw)) return true;
+	if (DISABLED_ENV_VALUES.has(raw)) return false;
+	return false;
+}
+
+function assertNeverDiagnosticEvent(_event: never): never {
+	throw new Error("Unhandled Cursor pi tool bridge diagnostic event");
+}
+
+function serializeCursorPiToolBridgeDiagnostic(event: CursorPiToolBridgeDiagnosticEvent): Record<string, unknown> {
+	switch (event.event) {
+		case "run_created":
+			return {
+				event: event.event,
+				runId: event.runId,
+				enabled: event.enabled,
+				exposedToolCount: event.exposedToolCount,
+				pendingCount: event.pendingCount,
+			};
+		case "run_skipped":
+			return {
+				event: event.event,
+				runId: event.runId,
+				enabled: event.enabled,
+				exposedToolCount: event.exposedToolCount,
+				pendingCount: event.pendingCount,
+				reason: event.reason,
+			};
+		case "tools_exposed":
+			return {
+				event: event.event,
+				runId: event.runId,
+				enabled: event.enabled,
+				exposedToolCount: event.exposedToolCount,
+				pendingCount: event.pendingCount,
+				pairs: event.pairs.map((pair) => ({ piToolName: pair.piToolName, mcpToolName: pair.mcpToolName })),
+			};
+		case "run_cancelled":
+			return {
+				event: event.event,
+				runId: event.runId,
+				enabled: event.enabled,
+				exposedToolCount: event.exposedToolCount,
+				pendingCount: event.pendingCount,
+				queuedCount: event.queuedCount,
+				cancelledRequestCount: event.cancelledRequestCount,
+			};
+		case "run_disposed":
+			return {
+				event: event.event,
+				runId: event.runId,
+				enabled: event.enabled,
+				exposedToolCount: event.exposedToolCount,
+				pendingCount: event.pendingCount,
+			};
+		case "request_queued":
+			return {
+				event: event.event,
+				runId: event.runId,
+				bridgeCallId: event.bridgeCallId,
+				cursorMcpCallId: createCursorMcpCallDiagnosticId(event.cursorMcpCallId),
+				piToolCallId: event.piToolCallId,
+				mcpToolName: event.mcpToolName,
+				piToolName: event.piToolName,
+				pendingCount: event.pendingCount,
+			};
+		case "request_resolved":
+			return {
+				event: event.event,
+				runId: event.runId,
+				bridgeCallId: event.bridgeCallId,
+				cursorMcpCallId: createCursorMcpCallDiagnosticId(event.cursorMcpCallId),
+				piToolCallId: event.piToolCallId,
+				mcpToolName: event.mcpToolName,
+				piToolName: event.piToolName,
+				pendingCount: event.pendingCount,
+				isError: event.isError,
+			};
+		case "request_rejected":
+			return {
+				event: event.event,
+				runId: event.runId,
+				bridgeCallId: event.bridgeCallId,
+				cursorMcpCallId: createCursorMcpCallDiagnosticId(event.cursorMcpCallId),
+				piToolCallId: event.piToolCallId,
+				mcpToolName: event.mcpToolName,
+				piToolName: event.piToolName,
+				pendingCount: event.pendingCount,
+				rejectionKind: event.rejectionKind,
+			};
+	}
+	return assertNeverDiagnosticEvent(event);
+}
+
+function writeCursorPiToolBridgeDiagnostic(env: Record<string, string | undefined>, event: CursorPiToolBridgeDiagnosticEvent): void {
+	if (!resolveCursorPiToolBridgeDebugEnabled(env)) return;
+	try {
+		process.stderr.write(`${CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX} ${JSON.stringify(serializeCursorPiToolBridgeDiagnostic(event))}\n`);
+	} catch {
+		// Diagnostics must never affect bridge execution.
+	}
+}
+
 function isOverlappingCursorNativePiToolName(toolName: string): boolean {
 	return OVERLAPPING_CURSOR_NATIVE_PI_BUILTIN_TOOL_NAMES.has(toolName);
 }
 
+export function buildCursorPiToolBridgeSurfaceSignature(snapshot: CursorPiToolBridgeSnapshot): string {
+	if (snapshot.tools.length === 0) return "bridge:empty";
+	const serializedTools = snapshot.tools
+		.map((tool) =>
+			JSON.stringify({
+				piToolName: tool.piToolName,
+				mcpToolName: tool.mcpToolName,
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+				source: tool.sourceInfo?.source,
+				path: tool.sourceInfo?.path,
+				scope: tool.sourceInfo?.scope,
+			}),
+		)
+		.sort()
+		.join("\0");
+	return `bridge:on:${stableNameHash(serializedTools)}`;
+}
+
 export function buildCursorPiToolBridgeSnapshot(
-	pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
+	pi: CursorPiToolBridgeSnapshotApi,
 	options: CursorPiToolBridgeSnapshotOptions = {},
 ): CursorPiToolBridgeSnapshot {
 	const activeToolNames = new Set(pi.getActiveTools());
@@ -209,7 +562,11 @@ export function buildCursorPiToolBridgeSnapshot(
 function snapshotToolToMcpTool(tool: CursorPiBridgeToolDefinition): Tool {
 	return {
 		name: tool.mcpToolName,
-		description: tool.description,
+		description: buildCursorPiBridgeMcpToolDescription({
+			piToolName: tool.piToolName,
+			mcpToolName: tool.mcpToolName,
+			piToolDescription: tool.description,
+		}),
 		inputSchema: tool.inputSchema,
 		_meta: { piToolName: tool.piToolName },
 	};
@@ -237,7 +594,7 @@ function convertPiContentToMcpContent(content: unknown): CallToolResult["content
 	return mcpContent.length > 0 ? mcpContent : [{ type: "text", text: "" }];
 }
 
-function asToolResultMessage(value: Context["messages"][number]): Extract<Context["messages"][number], { role: "toolResult" }> | undefined {
+function asToolResultMessage(value: Context["messages"][number]): ToolResultMessage | undefined {
 	return value.role === "toolResult" ? value : undefined;
 }
 
@@ -273,6 +630,7 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	mcpServers?: Record<string, McpServerConfig>;
 
 	private readonly registry: CursorPiToolBridgeRegistry;
+	private readonly env: Record<string, string | undefined>;
 	private readonly endpointPath: string;
 	private readonly knownMcpToolNames: ReadonlySet<string>;
 	private readonly knownCursorMcpCallIds = new Set<string>();
@@ -280,7 +638,8 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 	private readonly pendingByPiToolCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByBridgeCallId = new Map<string, PendingBridgeCall>();
 	private readonly pendingByCursorMcpCallId = new Map<string, PendingBridgeCall>();
-	private readonly onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	private onToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	private liveRunHandlerDetached = false;
 	private mcpServer?: McpProtocolServer;
 	private mcpTransport?: StreamableHTTPServerTransport;
 	private toolCallCounter = 0;
@@ -288,16 +647,18 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 
 	constructor(
 		registry: CursorPiToolBridgeRegistry,
+		env: Record<string, string | undefined>,
 		snapshot: CursorPiToolBridgeSnapshot,
 		enabled: boolean,
 		options: CursorPiToolBridgeRunOptions = {},
 	) {
 		this.registry = registry;
+		this.env = env;
 		this.snapshot = snapshot;
 		this.enabled = enabled;
 		this.onToolRequest = options.onToolRequest;
-		this.id = `cursor-pi-bridge-${randomUUID()}`;
-		this.endpointPath = `${MCP_ENDPOINT_ROOT}/${this.id}/${randomUUID()}/mcp`;
+		this.id = `cursor-pi-bridge-run-${randomUUID()}`;
+		this.endpointPath = `${MCP_ENDPOINT_ROOT}/${randomUUID()}/mcp`;
 		this.knownMcpToolNames = new Set(snapshot.tools.map((tool) => tool.mcpToolName));
 	}
 
@@ -308,6 +669,27 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.mcpServers = { [MCP_SERVER_NAME]: { type: "http", url: endpointUrl } };
 	}
 
+	emitStartDiagnostics(bridgeEnabled: boolean): void {
+		const base = this.lifecycleDiagnosticFields();
+		this.emitDiagnostic({ event: "run_created", ...base });
+		if (!this.enabled) {
+			this.emitDiagnostic({
+				event: "run_skipped",
+				...base,
+				reason: bridgeEnabled ? "no_exposed_tools" : "disabled",
+			});
+			return;
+		}
+		this.emitDiagnostic({
+			event: "tools_exposed",
+			...base,
+			pairs: this.snapshot.tools.map((tool) => ({
+				piToolName: tool.piToolName,
+				mcpToolName: tool.mcpToolName,
+			})),
+		});
+	}
+
 	async handleHttpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
 		if (this.disposed || !this.mcpTransport) {
 			res.writeHead(410, { "content-type": "application/json" }).end(JSON.stringify({ error: "Cursor pi tool bridge run is disposed" }));
@@ -320,10 +702,23 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		return this.queuedRequests.splice(0);
 	}
 
-	resolveToolResultsFromContext(context: Context): void {
-		for (const message of context.messages) {
-			const toolResult = asToolResultMessage(message);
-			if (!toolResult) continue;
+	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void {
+		if (!handler) {
+			this.liveRunHandlerDetached = true;
+			this.rejectQueuedToolRequestsWithoutHandler("Cursor pi tool bridge has no active live run");
+		} else {
+			this.liveRunHandlerDetached = false;
+		}
+		this.onToolRequest = handler;
+		if (handler) {
+			for (const request of this.queuedRequests.splice(0)) {
+				handler(request);
+			}
+		}
+	}
+
+	resolveToolResults(toolResults: readonly ToolResultMessage[]): void {
+		for (const toolResult of toolResults) {
 			const pending = this.pendingByPiToolCallId.get(toolResult.toolCallId);
 			if (!pending || pending.settled) continue;
 			this.resolvePending(pending, {
@@ -333,10 +728,21 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		}
 	}
 
+	resolveToolResultsFromContext(context: Context): void {
+		this.resolveToolResults(context.messages.map(asToolResultMessage).filter((message): message is ToolResultMessage => message !== undefined));
+	}
+
 	hasPendingPiToolCallId(piToolCallId: string): boolean {
 		return this.pendingByPiToolCallId.has(piToolCallId);
 	}
 
+	cancelPendingPiToolCallId(piToolCallId: string, reason: string): boolean {
+		const pending = this.pendingByPiToolCallId.get(piToolCallId);
+		if (!pending) return false;
+		this.rejectPending(pending, new Error(reason), "cancelled");
+		return true;
+	}
+
 	isBridgeMcpToolCall(toolCall: unknown): boolean {
 		if (!isRecord(toolCall)) return false;
 		const toolName = getStringField(toolCall, ["name", "toolName", "mcpToolName"]);
@@ -352,9 +758,19 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 
 	cancel(reason: string): void {
 		const error = new Error(reason);
+		const pendingCount = this.pendingCount();
+		const queuedCount = this.queuedRequests.length;
+		if (pendingCount > 0 || queuedCount > 0) {
+			this.emitDiagnostic({
+				event: "run_cancelled",
+				...this.lifecycleDiagnosticFields(pendingCount),
+				queuedCount,
+				cancelledRequestCount: pendingCount,
+			});
+		}
 		this.queuedRequests.splice(0);
 		for (const pending of [...this.pendingByBridgeCallId.values()]) {
-			this.rejectPending(pending, error);
+			this.rejectPending(pending, error, "cancelled");
 		}
 	}
 
@@ -368,6 +784,10 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 			this.mcpServer?.close(),
 		]);
 		await this.registry.unregisterRun(this.endpointPath, this);
+		this.emitDiagnostic({
+			event: "run_disposed",
+			...this.lifecycleDiagnosticFields(),
+		});
 	}
 
 	private async createMcpServer(): Promise<void> {
@@ -422,7 +842,7 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 				settled: false,
 			};
 			pending.onAbort = () => {
-				this.rejectPending(pending, new Error("Cursor MCP bridge tool request was aborted"));
+				this.rejectPending(pending, new Error("Cursor MCP bridge tool request was aborted"), "cancelled");
 			};
 			if (signal?.aborted) {
 				pending.onAbort();
@@ -433,35 +853,97 @@ class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 			this.pendingByBridgeCallId.set(request.bridgeCallId, pending);
 			this.pendingByCursorMcpCallId.set(cursorMcpCallId, pending);
 			this.knownCursorMcpCallIds.add(cursorMcpCallId);
-			this.queuedRequests.push(request);
-			this.onToolRequest?.(request);
+			if (!this.onToolRequest) {
+				if (this.liveRunHandlerDetached) {
+					this.rejectPending(pending, new Error("Cursor pi tool bridge has no active live run"), "cancelled");
+					return;
+				}
+				this.queuedRequests.push(request);
+				this.emitRequestQueuedDiagnostic(request);
+				return;
+			}
+			this.emitRequestQueuedDiagnostic(request);
+			this.onToolRequest(request);
 		});
 	}
 
+	private rejectQueuedToolRequestsWithoutHandler(reason: string): void {
+		while (this.queuedRequests.length > 0) {
+			const request = this.queuedRequests.shift()!;
+			const pending = this.pendingByPiToolCallId.get(request.piToolCallId);
+			if (pending) this.rejectPending(pending, new Error(reason), "cancelled");
+		}
+	}
+
 	private resolvePending(pending: PendingBridgeCall, result: CallToolResult): void {
 		if (pending.settled) return;
 		pending.settled = true;
 		this.removePending(pending);
+		this.emitRequestResolvedDiagnostic(pending.request, result.isError === true);
 		pending.resolve(result);
 	}
 
-	private rejectPending(pending: PendingBridgeCall, error: Error): void {
+	private rejectPending(pending: PendingBridgeCall, error: Error, kind: "cancelled" | "error" = "error"): void {
 		if (pending.settled) return;
 		pending.settled = true;
 		this.removePending(pending);
+		this.emitRequestRejectedDiagnostic(pending.request, kind);
 		pending.reject(error);
 	}
 
+	private lifecycleDiagnosticFields(pendingCount = this.pendingCount()): CursorPiToolBridgeLifecycleDiagnosticFields {
+		return {
+			runId: this.id,
+			enabled: this.enabled,
+			exposedToolCount: this.snapshot.tools.length,
+			pendingCount,
+		};
+	}
+
+	private requestDiagnosticFields(request: CursorPiBridgeToolRequest): CursorPiToolBridgeRequestDiagnosticFields {
+		return {
+			runId: this.id,
+			bridgeCallId: request.bridgeCallId,
+			cursorMcpCallId: request.cursorMcpCallId,
+			piToolCallId: request.piToolCallId,
+			mcpToolName: request.mcpToolName,
+			piToolName: request.piToolName,
+			pendingCount: this.pendingCount(),
+		};
+	}
+
+	private emitRequestQueuedDiagnostic(request: CursorPiBridgeToolRequest): void {
+		this.emitDiagnostic({ event: "request_queued", ...this.requestDiagnosticFields(request) });
+	}
+
+	private emitRequestResolvedDiagnostic(request: CursorPiBridgeToolRequest, isError: boolean): void {
+		this.emitDiagnostic({ event: "request_resolved", ...this.requestDiagnosticFields(request), isError });
+	}
+
+	private emitRequestRejectedDiagnostic(request: CursorPiBridgeToolRequest, rejectionKind: CursorPiToolBridgeRejectionKind): void {
+		this.emitDiagnostic({ event: "request_rejected", ...this.requestDiagnosticFields(request), rejectionKind });
+	}
+
+	private emitDiagnostic(event: CursorPiToolBridgeDiagnosticEvent): void {
+		writeCursorPiToolBridgeDiagnostic(this.env, event);
+	}
+
+	private pendingCount(): number {
+		return this.pendingByBridgeCallId.size;
+	}
+
 	private removePending(pending: PendingBridgeCall): void {
 		pending.signal?.removeEventListener("abort", pending.onAbort ?? (() => undefined));
 		this.pendingByPiToolCallId.delete(pending.request.piToolCallId);
 		this.pendingByBridgeCallId.delete(pending.request.bridgeCallId);
 		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);
 	}
 }
 
 class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
-	private readonly pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">;
+	private readonly pi: CursorPiToolBridgeSnapshotApi;
 	private readonly env: Record<string, string | undefined>;
 	private readonly runs = new Set<CursorPiToolBridgeRunImpl>();
 	private readonly routes = new Map<string, CursorPiToolBridgeRunImpl>();
@@ -469,7 +951,7 @@ class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 	private listenPromise?: Promise<void>;
 
 	constructor(
-		pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
+		pi: CursorPiToolBridgeSnapshotApi,
 		env: Record<string, string | undefined> = process.env,
 	) {
 		this.pi = pi;
@@ -480,6 +962,14 @@ class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 		return resolveCursorPiToolBridgeEnabled(this.env);
 	}
 
+	getToolSurfaceSignature(): string {
+		if (!this.isEnabled()) return "bridge:off";
+		const snapshot = buildCursorPiToolBridgeSnapshot(this.pi, {
+			exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(this.env),
+		});
+		return buildCursorPiToolBridgeSurfaceSignature(snapshot);
+	}
+
 	async createRun(options: CursorPiToolBridgeRunOptions = {}): Promise<CursorPiToolBridgeRun> {
 		const bridgeEnabled = this.isEnabled();
 		const snapshot = bridgeEnabled
@@ -487,9 +977,10 @@ class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 				exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(this.env),
 			})
 			: createEmptySnapshot();
-		const run = new CursorPiToolBridgeRunImpl(this, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
+		const run = new CursorPiToolBridgeRunImpl(this, this.env, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
 		this.runs.add(run);
 		await run.start();
+		run.emitStartDiagnostics(bridgeEnabled);
 		return run;
 	}
 
@@ -523,6 +1014,20 @@ class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 		return this.routes.size;
 	}
 
+	hasPendingPiToolCallId(piToolCallId: string): boolean {
+		for (const run of this.runs) {
+			if (run.hasPendingPiToolCallId(piToolCallId)) return true;
+		}
+		return false;
+	}
+
+	cancelPendingPiToolCallId(piToolCallId: string, reason: string): boolean {
+		for (const run of this.runs) {
+			if (run.cancelPendingPiToolCallId(piToolCallId, reason)) return true;
+		}
+		return false;
+	}
+
 	private async ensureHttpServer(): Promise<void> {
 		if (this.httpServer) {
 			await this.listenPromise;
@@ -601,12 +1106,32 @@ class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 
 let registeredCursorPiToolBridge: CursorPiToolBridgeRegistry | undefined;
 
-export function registerCursorPiToolBridge(pi: ExtensionAPI): CursorPiToolBridge {
+export function registerCursorPiToolBridge(pi: CursorPiToolBridgeExtensionApi): CursorPiToolBridge {
+	bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge extension reloaded");
 	void registeredCursorPiToolBridge?.disposeAll("Cursor pi tool bridge extension reloaded");
 	const bridge = new CursorPiToolBridgeRegistry(pi);
 	registeredCursorPiToolBridge = bridge;
+	pi.on("tool_call", (event, ctx) => {
+		if (!bridge.hasPendingPiToolCallId(event.toolCallId)) return undefined;
+		const trackingStarted = bridgeToolExecutionAbortTracker.track(event.toolCallId, {
+			signal: ctx.signal,
+			abort: () => {
+				void ctx.abort();
+			},
+			cancelPending: (reason) => {
+				bridge.cancelPendingPiToolCallId(event.toolCallId, reason);
+			},
+		});
+		if (trackingStarted) return undefined;
+		return { block: true, reason: "Cursor pi bridge tool execution was aborted before it started" };
+	});
+	pi.on("tool_result", (event) => {
+		bridgeToolExecutionAbortTracker.finish(event.toolCallId);
+	});
 	pi.on("session_shutdown", async (event) => {
-		await bridge.disposeAll(`Cursor pi tool bridge session shutdown: ${event.reason}`);
+		const reason = `Cursor pi tool bridge session shutdown: ${event.reason}`;
+		bridgeToolExecutionAbortTracker.abortAll(reason);
+		await bridge.disposeAll(reason);
 	});
 	return bridge;
 }
@@ -618,10 +1143,12 @@ export function getRegisteredCursorPiToolBridge(): CursorPiToolBridge | undefine
 export const __testUtils = {
 	CURSOR_PI_TOOL_BRIDGE_ENV,
 	CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV,
+	CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV,
+	CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX,
 	LOOPBACK_HOST,
 	MCP_SERVER_NAME,
 	createRegistry(
-		pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">,
+		pi: CursorPiToolBridgeSnapshotApi,
 		env: Record<string, string | undefined> = process.env,
 	) {
 		return new CursorPiToolBridgeRegistry(pi, env);
@@ -629,7 +1156,17 @@ export const __testUtils = {
 	getRegisteredBridgeForTests() {
 		return registeredCursorPiToolBridge;
 	},
+	serializeDiagnosticForTests(event: CursorPiToolBridgeDiagnosticEvent) {
+		return serializeCursorPiToolBridgeDiagnostic(event);
+	},
+	getActiveBridgeToolExecutionAbortCount() {
+		return bridgeToolExecutionAbortTracker.getActiveCount();
+	},
+	emitBridgeToolExecutionProcessAbortSignalForTests(signal: NodeJS.Signals) {
+		bridgeToolExecutionAbortTracker.emitProcessAbortSignalForTests(signal);
+	},
 	resetRegisteredBridgeForTests() {
+		bridgeToolExecutionAbortTracker.abortAll("Cursor pi tool bridge test reset");
 		const bridge = registeredCursorPiToolBridge;
 		registeredCursorPiToolBridge = undefined;
 		return bridge?.disposeAll("Cursor pi tool bridge test reset") ?? Promise.resolve();