pi-cursor-sdk 0.1.15 → 0.1.17

package/src/cursor-partial-content-emitter.ts

@@ -0,0 +1,121 @@
+import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai";
+
+const DEFAULT_THINKING_TRACE_MAX_CHARS = 50000;
+
+export interface CursorPartialContentEmitterOptions {
+	stream: AssistantMessageEventStream;
+	partial: AssistantMessage;
+	thinkingMaxChars?: number;
+	mutuallyExclusive?: boolean;
+}
+
+export class CursorPartialContentEmitter {
+	private thinkingContentIndex = -1;
+	private textContentIndex = -1;
+	private activityTraceChars = 0;
+	private activityTraceTruncated = false;
+
+	constructor(
+		private readonly stream: AssistantMessageEventStream,
+		private readonly partial: AssistantMessage,
+		private readonly thinkingMaxChars = DEFAULT_THINKING_TRACE_MAX_CHARS,
+		private readonly mutuallyExclusive = true,
+	) {}
+
+	closeThinking(): void {
+		if (this.thinkingContentIndex < 0) return;
+		const block = this.partial.content[this.thinkingContentIndex];
+		if (block.type === "thinking") {
+			this.stream.push({
+				type: "thinking_end",
+				contentIndex: this.thinkingContentIndex,
+				content: block.thinking,
+				partial: this.partial,
+			});
+		}
+		this.thinkingContentIndex = -1;
+	}
+
+	closeText(): string {
+		if (this.textContentIndex < 0) return "";
+		const contentIndex = this.textContentIndex;
+		const block = this.partial.content[contentIndex];
+		this.textContentIndex = -1;
+		if (block.type !== "text") return "";
+		this.stream.push({
+			type: "text_end",
+			contentIndex,
+			content: block.text,
+			partial: this.partial,
+		});
+		return block.text;
+	}
+
+	closeAll(): string {
+		this.closeThinking();
+		return this.closeText();
+	}
+
+	appendThinkingDelta(delta: string, options?: { closeText?: boolean }): void {
+		const closeText = options?.closeText ?? this.mutuallyExclusive;
+		if (closeText) this.closeText();
+		if (this.activityTraceTruncated || !delta) return;
+
+		let text = delta;
+		if (this.thinkingMaxChars >= 0 && this.activityTraceChars + text.length > this.thinkingMaxChars) {
+			const remainingChars = Math.max(this.thinkingMaxChars - this.activityTraceChars, 0);
+			text = `${text.slice(0, remainingChars)}\n[Cursor activity trace truncated]\n`;
+			this.activityTraceTruncated = true;
+		}
+		if (!text) return;
+
+		if (this.thinkingContentIndex < 0) {
+			this.thinkingContentIndex = this.partial.content.length;
+			this.partial.content.push({ type: "thinking", thinking: "" });
+			this.stream.push({ type: "thinking_start", contentIndex: this.thinkingContentIndex, partial: this.partial });
+		}
+		const block = this.partial.content[this.thinkingContentIndex];
+		if (block.type !== "thinking") return;
+		block.thinking += text;
+		this.activityTraceChars += text.length;
+		this.stream.push({
+			type: "thinking_delta",
+			contentIndex: this.thinkingContentIndex,
+			delta: text,
+			partial: this.partial,
+		});
+	}
+
+	appendTextDelta(delta: string, options?: { closeThinking?: boolean }): void {
+		const closeThinking = options?.closeThinking ?? this.mutuallyExclusive;
+		if (closeThinking) this.closeThinking();
+		if (!delta) return;
+		if (this.textContentIndex < 0) {
+			this.textContentIndex = this.partial.content.length;
+			this.partial.content.push({ type: "text", text: "" });
+			this.stream.push({ type: "text_start", contentIndex: this.textContentIndex, partial: this.partial });
+		}
+		const block = this.partial.content[this.textContentIndex];
+		if (block.type !== "text") return;
+		block.text += delta;
+		this.stream.push({
+			type: "text_delta",
+			contentIndex: this.textContentIndex,
+			delta,
+			partial: this.partial,
+		});
+	}
+
+	appendThinkingBlock(text: string, options?: { closeText?: boolean }): void {
+		const closeText = options?.closeText ?? this.mutuallyExclusive;
+		if (closeText) this.closeAll();
+		else this.closeThinking();
+		this.appendThinkingDelta(text.endsWith("\n") ? text : `${text}\n`, { closeText: false });
+		this.closeThinking();
+	}
+
+	flushText(deltas: string[]): string {
+		for (const delta of deltas) this.appendTextDelta(delta);
+		return this.closeText();
+	}
+}

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

@@ -0,0 +1,133 @@
+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);
+		});
+	}
+}
+
+export const bridgeToolExecutionAbortTracker = new CursorPiToolBridgeToolExecutionAbortTracker();

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

@@ -0,0 +1,179 @@
+import { stableNameHash } from "./cursor-pi-tool-bridge-mcp.js";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+
+export const CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_DEBUG";
+export const CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX = "[pi-cursor-sdk:bridge]";
+
+export function resolveCursorPiToolBridgeDebugEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV], false);
+}
+
+function createCursorMcpCallDiagnosticId(cursorMcpCallId: string | undefined): string | undefined {
+	return cursorMcpCallId ? `cursor-mcp-call-${stableNameHash(cursorMcpCallId)}` : undefined;
+}
+
+type CursorPiToolBridgeSkippedReason = "disabled" | "no_exposed_tools";
+export type CursorPiToolBridgeRejectionKind = "cancelled" | "error";
+
+export 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";
+}
+
+export 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;
+
+function assertNeverDiagnosticEvent(_event: never): never {
+	throw new Error("Unhandled Cursor pi tool bridge diagnostic event");
+}
+
+export 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);
+}
+
+export 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.
+	}
+}

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

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import { buildCursorPiBridgeMcpToolDescription, CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX } from "./cursor-bridge-contract.js";
+import type { CursorPiBridgeToolDefinition, CursorPiMcpInputSchema } from "./cursor-pi-tool-bridge-types.js";
+import { getFirstStringByKeys } from "./cursor-record-utils.js";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function normalizeMcpInputSchema(schema: unknown): CursorPiMcpInputSchema {
+	if (isRecord(schema) && schema.type === "object") return schema as CursorPiMcpInputSchema;
+	return { type: "object", properties: {} };
+}
+
+export function normalizeMcpArgs(args: unknown): Record<string, unknown> {
+	return isRecord(args) ? { ...args } : {};
+}
+
+export function waitForProtocolFlush(): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function sanitizeMcpToolNameStem(toolName: string): string {
+	const stem = toolName
+		.trim()
+		.replace(/[^A-Za-z0-9_-]+/g, "_")
+		.replace(/^_+|_+$/g, "");
+	return stem || "tool";
+}
+
+export function stableNameHash(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+
+export function createMcpToolName(piToolName: string, usedMcpToolNames: Set<string>): string {
+	const baseName = `${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}${sanitizeMcpToolNameStem(piToolName)}`;
+	if (!usedMcpToolNames.has(baseName)) {
+		usedMcpToolNames.add(baseName);
+		return baseName;
+	}
+
+	const hashedName = `${baseName}__${stableNameHash(piToolName)}`;
+	if (!usedMcpToolNames.has(hashedName)) {
+		usedMcpToolNames.add(hashedName);
+		return hashedName;
+	}
+
+	let counter = 2;
+	let candidate = `${hashedName}_${counter}`;
+	while (usedMcpToolNames.has(candidate)) {
+		counter += 1;
+		candidate = `${hashedName}_${counter}`;
+	}
+	usedMcpToolNames.add(candidate);
+	return candidate;
+}
+
+export function snapshotToolToMcpTool(tool: CursorPiBridgeToolDefinition): Tool {
+	return {
+		name: tool.mcpToolName,
+		description: buildCursorPiBridgeMcpToolDescription({
+			piToolName: tool.piToolName,
+			mcpToolName: tool.mcpToolName,
+			piToolDescription: tool.description,
+		}),
+		inputSchema: tool.inputSchema,
+		_meta: { piToolName: tool.piToolName },
+	};
+}
+
+export function convertPiContentToMcpContent(content: unknown): CallToolResult["content"] {
+	if (!Array.isArray(content)) {
+		return [{ type: "text", text: typeof content === "string" ? content : JSON.stringify(content) }];
+	}
+
+	const mcpContent: CallToolResult["content"] = [];
+	for (const block of content) {
+		if (!isRecord(block)) continue;
+		if (block.type === "text" && typeof block.text === "string") {
+			mcpContent.push({ type: "text", text: block.text });
+			continue;
+		}
+		if (block.type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
+			mcpContent.push({ type: "image", data: block.data, mimeType: block.mimeType });
+			continue;
+		}
+		mcpContent.push({ type: "text", text: JSON.stringify(block) });
+	}
+
+	return mcpContent.length > 0 ? mcpContent : [{ type: "text", text: "" }];
+}
+
+export function asToolResultMessage(value: Context["messages"][number]): ToolResultMessage | undefined {
+	return value.role === "toolResult" ? value : undefined;
+}
+
+export function getStringField(record: Record<string, unknown>, fields: string[]): string | undefined {
+	return getFirstStringByKeys(record, fields, { nonEmpty: true });
+}
+
+export function containsKnownMcpToolName(value: unknown, knownMcpToolNames: ReadonlySet<string>, depth = 0): boolean {
+	if (depth > 4) return false;
+	if (Array.isArray(value)) return value.some((entry) => containsKnownMcpToolName(entry, knownMcpToolNames, depth + 1));
+	if (!isRecord(value)) return false;
+
+	for (const field of ["tool", "toolName", "name", "mcpToolName", "serverToolName"]) {
+		const fieldValue = value[field];
+		if (typeof fieldValue === "string" && knownMcpToolNames.has(fieldValue)) return true;
+	}
+
+	for (const nestedField of ["args", "arguments", "input"]) {
+		if (containsKnownMcpToolName(value[nestedField], knownMcpToolNames, depth + 1)) return true;
+	}
+
+	return false;
+}