pi-cursor-sdk 0.1.18 → 0.1.20

package/src/cursor-sdk-abort-error-guard.ts

@@ -0,0 +1,109 @@
+import { asRecord } from "./cursor-record-utils.js";
+
+interface CursorSdkAbortErrorSuppressionToken {
+	suppress: boolean;
+}
+
+export interface CursorSdkAbortErrorSuppression {
+	suppressAbortErrors(): void;
+	dispose(): void;
+}
+
+function getString(record: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = record?.[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+type GenericProcessEmit = (event: string | symbol, ...args: unknown[]) => boolean;
+
+// The local Cursor SDK can surface abort-time ConnectRPC cancellation as a process-level
+// uncaught exception/unhandled rejection even when run.cancel() is awaited/caught.
+const activeSuppressions = new Set<CursorSdkAbortErrorSuppressionToken>();
+let originalProcessEmit: GenericProcessEmit | undefined;
+let captureCallbackInstalled = false;
+
+export function isCursorSdkAbortConnectError(error: unknown): boolean {
+	const record = asRecord(error);
+	const name = error instanceof Error ? error.name : getString(record, "name");
+	const message = error instanceof Error ? error.message : getString(record, "message");
+	const rawMessage = getString(record, "rawMessage") ?? message;
+	const code = record?.code;
+	const cause = asRecord(record?.cause);
+	const causeName = getString(cause, "name");
+	const stack = error instanceof Error ? error.stack ?? "" : getString(record, "stack") ?? "";
+
+	return (
+		name === "ConnectError" &&
+		(code === 1 || code === "canceled") &&
+		Boolean(rawMessage && /(?:operation was aborted|canceled)/i.test(rawMessage)) &&
+		(causeName === "AbortError" || /AbortError/.test(stack)) &&
+		stack.includes("@cursor/sdk") &&
+		stack.includes("@connectrpc/connect-node")
+	);
+}
+
+function hasActiveSuppression(): boolean {
+	for (const suppression of activeSuppressions) {
+		if (suppression.suppress) return true;
+	}
+	return false;
+}
+
+function shouldSuppressProcessError(event: string | symbol, args: readonly unknown[]): boolean {
+	if (event !== "uncaughtException" && event !== "unhandledRejection") return false;
+	return hasActiveSuppression() && isCursorSdkAbortConnectError(args[0]);
+}
+
+function installProcessEmitPatch(): void {
+	if (originalProcessEmit) return;
+	originalProcessEmit = process.emit.bind(process) as GenericProcessEmit;
+	process.emit = function patchedCursorSdkAbortEmit(this: NodeJS.Process, event: string | symbol, ...args: unknown[]): boolean {
+		if (shouldSuppressProcessError(event, args)) return false;
+		return originalProcessEmit!(event, ...args);
+	} as typeof process.emit;
+}
+
+function installCaptureCallbackIfAvailable(): void {
+	if (captureCallbackInstalled || process.hasUncaughtExceptionCaptureCallback()) return;
+	process.setUncaughtExceptionCaptureCallback((error: Error) => {
+		if (shouldSuppressProcessError("uncaughtException", [error])) return;
+		uninstallCaptureCallbackIfIdle(true);
+		if (originalProcessEmit?.("uncaughtException", error)) return;
+		throw error;
+	});
+	captureCallbackInstalled = true;
+}
+
+function uninstallCaptureCallbackIfIdle(force = false): void {
+	if (!captureCallbackInstalled) return;
+	if (!force && activeSuppressions.size > 0) return;
+	process.setUncaughtExceptionCaptureCallback(null);
+	captureCallbackInstalled = false;
+}
+
+function uninstallProcessEmitPatchIfIdle(): void {
+	if (activeSuppressions.size > 0 || !originalProcessEmit) return;
+	uninstallCaptureCallbackIfIdle();
+	process.emit = originalProcessEmit as typeof process.emit;
+	originalProcessEmit = undefined;
+}
+
+export function installCursorSdkAbortErrorSuppression(): CursorSdkAbortErrorSuppression {
+	installProcessEmitPatch();
+	const token: CursorSdkAbortErrorSuppressionToken = { suppress: false };
+	activeSuppressions.add(token);
+	let disposed = false;
+	return {
+		suppressAbortErrors(): void {
+			if (disposed) return;
+			token.suppress = true;
+			installCaptureCallbackIfAvailable();
+		},
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			activeSuppressions.delete(token);
+			uninstallProcessEmitPatchIfIdle();
+		},
+	};
+}

package/src/cursor-sdk-event-debug-constants.ts

@@ -0,0 +1,40 @@
+import { resolve } from "node:path";
+
+export const CURSOR_SDK_EVENT_DEBUG_ENV = "PI_CURSOR_SDK_EVENT_DEBUG";
+export const CURSOR_SDK_EVENT_DEBUG_DIR_ENV = "PI_CURSOR_SDK_EVENT_DEBUG_DIR";
+export const CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV = "PI_CURSOR_SDK_EVENT_DEBUG_RUN_DIR";
+export const CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV = "PI_CURSOR_SDK_EVENT_DEBUG_SESSION_DIR";
+export const CURSOR_SDK_EVENT_DEBUG_STDERR_ENV = "PI_CURSOR_SDK_EVENT_DEBUG_STDERR";
+export const CURSOR_SDK_EVENT_DEBUG_LOG_PREFIX = "[pi-cursor-sdk:sdk-events]";
+
+export const SESSION_MANIFEST = "session.json";
+export const SESSION_PI_SESSION_SNAPSHOT = "pi-session.jsonl";
+
+export const ARTIFACTS = {
+	metadata: "metadata.json",
+	sendPayload: "send-payload.json",
+	contextSnapshot: "context-snapshot.json",
+	onDelta: "on-delta.jsonl",
+	onStep: "on-step.jsonl",
+	streamEvents: "stream-events.jsonl",
+	piStreamEvents: "pi-stream-events.jsonl",
+	providerEvents: "provider-events.jsonl",
+	liveRunEvents: "live-run-events.jsonl",
+	bridgeEvents: "bridge-events.jsonl",
+	bridgeRaw: "bridge-raw.jsonl",
+	displayDecisions: "display-decisions.jsonl",
+	coordinatorEvents: "coordinator-events.jsonl",
+	drainEvents: "drain-events.jsonl",
+	timeline: "timeline.jsonl",
+	piSessionSnapshot: "pi-session-snapshot.jsonl",
+	finalPartial: "final-partial.json",
+	errors: "errors.jsonl",
+	waitResult: "wait-result.json",
+	conversation: "conversation.json",
+	summary: "summary.json",
+} as const;
+
+export function resolveCursorSdkEventDebugBaseDir(cwd: string, env: Record<string, string | undefined> = process.env): string {
+	const raw = env[CURSOR_SDK_EVENT_DEBUG_DIR_ENV]?.trim();
+	return resolve(cwd, raw || ".debug/cursor-sdk-events");
+}

package/src/cursor-sdk-event-debug-session.ts

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import {
+	CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV,
+	CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV,
+	SESSION_MANIFEST,
+	resolveCursorSdkEventDebugBaseDir,
+} from "./cursor-sdk-event-debug-constants.js";
+import { getCursorSessionFile, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+
+const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
+
+interface CursorSdkEventDebugSessionState {
+	sessionKey: string;
+	sessionDir: string;
+	turnCounter: number;
+}
+
+interface CursorSdkEventDebugSessionManifest {
+	sessionKey: string;
+	sessionFile?: string;
+	sessionDir: string;
+	createdAt: string;
+	updatedAt: string;
+	turns: Array<{
+		turn: number;
+		artifactDir: string;
+		startedAt: string;
+		finalizedAt?: string;
+		summary?: Record<string, unknown>;
+	}>;
+}
+
+export interface CursorSdkEventDebugTurnAllocation {
+	artifactDir: string;
+	sessionDir?: string;
+	turn?: number;
+	sessionKey?: string;
+	pinnedRun: boolean;
+}
+
+const sessionDebugStates = new Map<string, CursorSdkEventDebugSessionState>();
+
+function sanitizePathSegment(value: string): string {
+	return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "session";
+}
+
+export function slugSessionKey(scopeKey: string): string {
+	if (scopeKey === ANONYMOUS_SESSION_SCOPE_KEY) {
+		return `anonymous-${process.pid}`;
+	}
+	const fileBase = sanitizePathSegment(basename(scopeKey).replace(/\.jsonl?$/i, "") || "session");
+	const hash = createHash("sha256").update(scopeKey).digest("hex").slice(0, 8);
+	return `${fileBase}-${hash}`;
+}
+
+function resolvePinnedRunArtifactDir(runDirOverride: string | undefined): string | undefined {
+	const trimmed = runDirOverride?.trim();
+	if (!trimmed) return undefined;
+	const dir = resolve(trimmed);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function readSessionManifest(sessionDir: string): CursorSdkEventDebugSessionManifest | undefined {
+	try {
+		return JSON.parse(readFileSync(join(sessionDir, SESSION_MANIFEST), "utf8")) as CursorSdkEventDebugSessionManifest;
+	} catch {
+		return undefined;
+	}
+}
+
+function writeSessionManifest(sessionDir: string, manifest: CursorSdkEventDebugSessionManifest): void {
+	writeFileSync(join(sessionDir, SESSION_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+function maxTurnFromManifest(manifest: CursorSdkEventDebugSessionManifest | undefined): number {
+	if (!manifest || manifest.turns.length === 0) return 0;
+	return manifest.turns.reduce((max, entry) => Math.max(max, entry.turn), 0);
+}
+
+function resolveSessionDebugDir(
+	cwd: string,
+	env: Record<string, string | undefined>,
+	scopeKey: string,
+): string {
+	const pinned = env[CURSOR_SDK_EVENT_DEBUG_SESSION_DIR_ENV]?.trim();
+	if (pinned) return resolve(pinned);
+	return join(resolveCursorSdkEventDebugBaseDir(cwd, env), "sessions", slugSessionKey(scopeKey));
+}
+
+export function allocateCursorSdkEventDebugTurn(
+	cwd: string,
+	env: Record<string, string | undefined>,
+): CursorSdkEventDebugTurnAllocation {
+	const pinnedRunDir = resolvePinnedRunArtifactDir(env[CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV]);
+	if (pinnedRunDir) {
+		return { artifactDir: pinnedRunDir, pinnedRun: true };
+	}
+
+	const scopeKey = getCursorSessionScopeKey();
+	const sessionDir = resolveSessionDebugDir(cwd, env, scopeKey);
+	mkdirSync(sessionDir, { recursive: true });
+
+	let state = sessionDebugStates.get(scopeKey);
+	if (!state || state.sessionDir !== sessionDir) {
+		const existing = readSessionManifest(sessionDir);
+		state = { sessionKey: scopeKey, sessionDir, turnCounter: maxTurnFromManifest(existing) };
+		sessionDebugStates.set(scopeKey, state);
+	}
+
+	state.turnCounter += 1;
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const artifactDir = join(sessionDir, `turn-${String(state.turnCounter).padStart(3, "0")}-${stamp}`);
+	mkdirSync(artifactDir, { recursive: true });
+
+	const existing = readSessionManifest(sessionDir);
+	const manifest: CursorSdkEventDebugSessionManifest = existing ?? {
+		sessionKey: scopeKey,
+		sessionFile: getCursorSessionFile(),
+		sessionDir,
+		createdAt: new Date().toISOString(),
+		updatedAt: new Date().toISOString(),
+		turns: [],
+	};
+	manifest.sessionFile = getCursorSessionFile();
+	manifest.updatedAt = new Date().toISOString();
+	manifest.turns.push({
+		turn: state.turnCounter,
+		artifactDir,
+		startedAt: new Date().toISOString(),
+	});
+	writeSessionManifest(sessionDir, manifest);
+
+	return {
+		artifactDir,
+		sessionDir,
+		turn: state.turnCounter,
+		sessionKey: scopeKey,
+		pinnedRun: false,
+	};
+}
+
+export function updateCursorSdkEventDebugSessionManifest(
+	sessionDir: string,
+	artifactDir: string,
+	summary: Record<string, unknown>,
+): void {
+	const manifest = readSessionManifest(sessionDir);
+	if (!manifest) return;
+	const turnEntry = manifest.turns.find((entry) => entry.artifactDir === artifactDir);
+	if (!turnEntry) return;
+	turnEntry.finalizedAt = new Date().toISOString();
+	turnEntry.summary = summary;
+	manifest.updatedAt = new Date().toISOString();
+	manifest.sessionFile = getCursorSessionFile();
+	writeSessionManifest(sessionDir, manifest);
+}
+
+export function resetCursorSdkEventDebugSessionStateForTests(): void {
+	sessionDebugStates.clear();
+}