pi-cursor-sdk 0.2.0 → 0.3.6

package/dist/cursor-partial-content-emitter.js

@@ -0,0 +1,118 @@
+const DEFAULT_THINKING_TRACE_MAX_CHARS = 50000;
+export class CursorPartialContentEmitter {
+    stream;
+    partial;
+    thinkingMaxChars;
+    mutuallyExclusive;
+    thinkingContentIndex = -1;
+    textContentIndex = -1;
+    activityTraceChars = 0;
+    activityTraceTruncated = false;
+    constructor(stream, partial, thinkingMaxChars = DEFAULT_THINKING_TRACE_MAX_CHARS, mutuallyExclusive = true) {
+        this.stream = stream;
+        this.partial = partial;
+        this.thinkingMaxChars = thinkingMaxChars;
+        this.mutuallyExclusive = mutuallyExclusive;
+    }
+    closeThinking() {
+        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() {
+        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() {
+        this.closeThinking();
+        return this.closeText();
+    }
+    appendThinkingDelta(delta, options) {
+        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, options) {
+        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, options) {
+        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) {
+        for (const delta of deltas)
+            this.appendTextDelta(delta);
+        return this.closeText();
+    }
+}

package/dist/cursor-pi-tool-bridge-abort.js

@@ -0,0 +1,114 @@
+class CursorPiToolBridgeToolExecutionAbortTracker {
+    activeExecutions = new Map();
+    processSignalHandlersInstalled = false;
+    track(toolCallId, options) {
+        this.finish(toolCallId);
+        const execution = {
+            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.abortExecution(execution);
+            this.finish(toolCallId);
+        };
+        execution.signal?.addEventListener("abort", execution.onAbort, { once: true });
+        this.activeExecutions.set(toolCallId, execution);
+        this.installProcessSignalHandlers();
+        return true;
+    }
+    finish(toolCallId) {
+        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() {
+        for (const toolCallId of [...this.activeExecutions.keys()])
+            this.finish(toolCallId);
+    }
+    abort(toolCallId, reason) {
+        const execution = this.activeExecutions.get(toolCallId);
+        if (!execution)
+            return false;
+        this.cancelExecution(execution, reason);
+        this.abortExecution(execution);
+        this.finish(toolCallId);
+        return true;
+    }
+    abortAll(reason) {
+        for (const execution of [...this.activeExecutions.values()]) {
+            this.abort(execution.toolCallId, reason);
+        }
+    }
+    getActiveCount() {
+        return this.activeExecutions.size;
+    }
+    emitProcessAbortSignalForTests(signal) {
+        this.abortActiveExecutions(signal, { preserveProcessSignalBehavior: true });
+    }
+    handleSigint = () => {
+        this.abortActiveExecutions("SIGINT");
+    };
+    handleSigterm = () => {
+        this.abortActiveExecutions("SIGTERM");
+    };
+    installProcessSignalHandlers() {
+        if (this.processSignalHandlersInstalled)
+            return;
+        this.processSignalHandlersInstalled = true;
+        process.on("SIGINT", this.handleSigint);
+        process.on("SIGTERM", this.handleSigterm);
+    }
+    uninstallProcessSignalHandlersIfIdle() {
+        if (!this.processSignalHandlersInstalled || this.activeExecutions.size > 0)
+            return;
+        this.processSignalHandlersInstalled = false;
+        process.off("SIGINT", this.handleSigint);
+        process.off("SIGTERM", this.handleSigterm);
+    }
+    abortActiveExecutions(signal, options = {}) {
+        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);
+    }
+    cancelExecution(execution, reason) {
+        try {
+            execution.cancelPending(reason);
+        }
+        catch {
+            // Cancellation is best-effort during process abort/shutdown cleanup; keep aborting siblings.
+        }
+    }
+    abortExecution(execution) {
+        try {
+            Promise.resolve(execution.abort()).catch(() => undefined);
+        }
+        catch {
+            // Abort is best-effort during process abort/shutdown cleanup; keep aborting siblings.
+        }
+    }
+    hasExternalProcessSignalListeners(signal) {
+        const ownHandler = signal === "SIGINT" ? this.handleSigint : this.handleSigterm;
+        return process.listeners(signal).some((listener) => listener !== ownHandler);
+    }
+    restoreDefaultProcessSignalBehavior(signal) {
+        setImmediate(() => {
+            process.kill(process.pid, signal);
+        });
+    }
+}
+export const bridgeToolExecutionAbortTracker = new CursorPiToolBridgeToolExecutionAbortTracker();

package/dist/cursor-pi-tool-bridge-constants.js

@@ -0,0 +1,6 @@
+export const MCP_SERVER_NAME = "pi_tools";
+export const MCP_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
+const CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN = /^cursor-pi-bridge-run-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}-tool-\d+$/i;
+export function isCursorPiBridgeToolCallId(toolCallId) {
+    return CURSOR_PI_BRIDGE_TOOL_CALL_ID_PATTERN.test(toolCallId);
+}

package/dist/cursor-pi-tool-bridge-diagnostics.js

@@ -0,0 +1,125 @@
+import { appendFileSync } from "node:fs";
+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_DEBUG_FILE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE_DEBUG_FILE";
+export const CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX = "[pi-cursor-sdk:bridge]";
+export function resolveCursorPiToolBridgeDebugEnabled(env = process.env) {
+    return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_DEBUG_ENV], false);
+}
+function createCursorMcpCallDiagnosticId(cursorMcpCallId) {
+    return cursorMcpCallId ? `cursor-mcp-call-${stableNameHash(cursorMcpCallId)}` : undefined;
+}
+function assertNeverDiagnosticEvent(_event) {
+    throw new Error("Unhandled Cursor pi tool bridge diagnostic event");
+}
+export function serializeCursorPiToolBridgeDiagnostic(event) {
+    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, event, debugRecorder) {
+    try {
+        debugRecorder?.recordBridgeDiagnostic(event);
+    }
+    catch {
+        // Diagnostics must never affect bridge execution.
+    }
+    const serialized = serializeCursorPiToolBridgeDiagnostic(event);
+    const debugFile = env[CURSOR_PI_TOOL_BRIDGE_DEBUG_FILE_ENV];
+    if (debugFile) {
+        try {
+            appendFileSync(debugFile, `${JSON.stringify(serialized)}\n`);
+        }
+        catch {
+            // Diagnostics must never affect bridge execution.
+        }
+    }
+    if (!resolveCursorPiToolBridgeDebugEnabled(env))
+        return;
+    try {
+        process.stderr.write(`${CURSOR_PI_TOOL_BRIDGE_DIAGNOSTIC_PREFIX} ${JSON.stringify(serialized)}\n`);
+    }
+    catch {
+        // Diagnostics must never affect bridge execution.
+    }
+}

package/dist/cursor-pi-tool-bridge-env.js

@@ -0,0 +1,18 @@
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+import { resolveCursorMcpToolTimeoutMs } from "./cursor-mcp-timeout-override.js";
+export const CURSOR_PI_TOOL_BRIDGE_ENV = "PI_CURSOR_PI_TOOL_BRIDGE";
+export const CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV = "PI_CURSOR_EXPOSE_BUILTIN_TOOLS";
+export const CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV = "PI_CURSOR_PI_BRIDGE_CALL_TIMEOUT_MS";
+export function resolveCursorPiToolBridgeEnabled(env = process.env) {
+    return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_ENV], true);
+}
+export function resolveCursorPiToolBridgeBuiltinsEnabled(env = process.env) {
+    return parseEnvBoolean(env[CURSOR_PI_TOOL_BRIDGE_BUILTINS_ENV], false);
+}
+export function resolveCursorPiToolBridgeCallTimeoutMs(env = process.env) {
+    const mcpToolTimeoutMs = resolveCursorMcpToolTimeoutMs(env);
+    const parsed = Number(env[CURSOR_PI_TOOL_BRIDGE_CALL_TIMEOUT_MS_ENV]?.trim());
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return mcpToolTimeoutMs;
+    return Math.min(Math.max(Math.trunc(parsed), 1), mcpToolTimeoutMs);
+}

package/dist/cursor-pi-tool-bridge-mcp.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { buildCursorPiBridgeMcpToolDescription, CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX } from "./cursor-bridge-contract.js";
+import { asRecord, stringifyUnknown } from "./cursor-record-utils.js";
+export function normalizeMcpInputSchema(schema) {
+    const record = asRecord(schema);
+    if (record?.type === "object")
+        return record;
+    return { type: "object", properties: {} };
+}
+export function normalizeMcpArgs(args) {
+    const record = asRecord(args);
+    return record ? { ...record } : {};
+}
+export function waitForProtocolFlush() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function sanitizeMcpToolNameStem(toolName) {
+    const stem = toolName
+        .trim()
+        .replace(/[^A-Za-z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return stem || "tool";
+}
+export function stableNameHash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+export function createMcpToolName(piToolName, usedMcpToolNames) {
+    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) {
+    return {
+        name: tool.mcpToolName,
+        description: buildCursorPiBridgeMcpToolDescription({
+            piToolName: tool.piToolName,
+            mcpToolName: tool.mcpToolName,
+            piToolDescription: tool.description,
+            piToolPromptGuidelines: tool.promptGuidelines,
+        }),
+        inputSchema: tool.inputSchema,
+        _meta: { piToolName: tool.piToolName },
+    };
+}
+export function convertPiContentToMcpContent(content) {
+    if (!Array.isArray(content)) {
+        return [{ type: "text", text: stringifyUnknown(content) }];
+    }
+    const mcpContent = [];
+    for (const block of content) {
+        const record = asRecord(block);
+        if (record?.type === "text" && typeof record.text === "string") {
+            mcpContent.push({ type: "text", text: record.text });
+            continue;
+        }
+        if (record?.type === "image" && typeof record.data === "string" && typeof record.mimeType === "string") {
+            mcpContent.push({ type: "image", data: record.data, mimeType: record.mimeType });
+            continue;
+        }
+        mcpContent.push({ type: "text", text: stringifyUnknown(block) });
+    }
+    return mcpContent.length > 0 ? mcpContent : [{ type: "text", text: "" }];
+}
+export function asToolResultMessage(value) {
+    return value.role === "toolResult" ? value : undefined;
+}
+export function containsKnownMcpToolName(value, knownMcpToolNames, depth = 0) {
+    if (depth > 4)
+        return false;
+    if (Array.isArray(value))
+        return value.some((entry) => containsKnownMcpToolName(entry, knownMcpToolNames, depth + 1));
+    const record = asRecord(value);
+    if (!record)
+        return false;
+    for (const field of ["tool", "toolName", "name", "mcpToolName", "serverToolName"]) {
+        const fieldValue = record[field];
+        if (typeof fieldValue === "string" && knownMcpToolNames.has(fieldValue))
+            return true;
+    }
+    for (const nestedField of ["args", "arguments", "input"]) {
+        if (containsKnownMcpToolName(record[nestedField], knownMcpToolNames, depth + 1))
+            return true;
+    }
+    return false;
+}