pi-cursor-sdk 0.1.18 → 0.1.20

package/scripts/debug-sdk-events.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+/**
+ * Maintainer-only Cursor SDK event capture probe.
+ * Captures timestamped run.stream(), onDelta, and onStep surfaces for one run.
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import {
+	CURSOR_SETTING_SOURCES_ENV,
+	resolveCursorSettingSources,
+	scrubSensitiveText,
+} from "./lib/cursor-probe-utils.mjs";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./lib/cursor-sdk-output-filter.mjs";
+
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+
+const ARTIFACTS = {
+	metadata: "metadata.json",
+	streamEvents: "stream-events.jsonl",
+	onDelta: "on-delta.jsonl",
+	onStep: "on-step.jsonl",
+	waitResult: "wait-result.json",
+	conversation: "conversation.json",
+	summary: "summary.json",
+};
+
+const DEFAULT_MODEL = "composer-2.5";
+const RAW_ARTIFACT_WARNING =
+	"Raw artifact files may contain local paths, project text, tool args/results, or secrets from the workspace. Do not commit or share them.";
+
+function readSdkVersion() {
+	try {
+		const sdkEntry = require.resolve("@cursor/sdk");
+		const sdkPackagePath = join(dirname(sdkEntry), "../../package.json");
+		return JSON.parse(readFileSync(sdkPackagePath, "utf8")).version;
+	} catch {
+		return "unknown";
+	}
+}
+
+function artifactPath(artifactDir, name) {
+	return join(artifactDir, ARTIFACTS[name]);
+}
+
+function printHelp() {
+	console.log(`Capture timestamped Cursor SDK event timelines for one local run.
+
+Usage:
+  CURSOR_API_KEY=... npm run debug:sdk-events -- [options]
+  node scripts/debug-sdk-events.mjs [options]
+
+Options:
+  --cwd <path>                 Agent working directory. Default: process.cwd().
+  --model <id>                 Cursor model id. Default: ${DEFAULT_MODEL}.
+  --prompt <text>              Required user prompt for the run.
+  --out <dir>                  Artifact directory. Default: /tmp/pi-cursor-sdk-sdk-events-<timestamp>.
+  --setting-sources <value>    Comma-separated Cursor setting sources, or all/none.
+                               Default: PI_CURSOR_SETTING_SOURCES env, otherwise all.
+  --include-conversation       Also capture run.conversation() when supported.
+  --api-key <key>              Cursor API key. Prefer CURSOR_API_KEY to avoid shell history.
+  -h, --help                   Show this help.
+
+Stdout:
+  Prints artifact paths and summary counts only. Raw payloads stay on disk under:
+  ${ARTIFACTS.streamEvents} (run.stream()), ${ARTIFACTS.onDelta} (onDelta), ${ARTIFACTS.onStep} (onStep).
+
+Exit codes:
+  0  capture completed
+  1  invalid arguments, missing auth, or Cursor SDK failure
+
+Safety:
+  - Never prints CURSOR_API_KEY or --api-key values.
+  - Default artifact root is outside the repo (/tmp/...).
+  - ${RAW_ARTIFACT_WARNING}
+  - Verify Cursor SDK behavior against the installed @cursor/sdk package and/or
+    https://cursor.com/docs/sdk/typescript before drawing integration conclusions.`);
+}
+
+function fail(message, secrets = []) {
+	const scrubbed = scrubSensitiveText(message, secrets[0]);
+	console.error(`debug-sdk-events: ${scrubbed}`);
+	process.exit(1);
+}
+
+export function parseDebugSdkEventsArgs(argv, env = process.env) {
+	const args = {
+		cwd: process.cwd(),
+		model: DEFAULT_MODEL,
+		prompt: undefined,
+		out: undefined,
+		settingSources: resolveCursorSettingSources(env[CURSOR_SETTING_SOURCES_ENV]),
+		includeConversation: false,
+		apiKey: env.CURSOR_API_KEY?.trim() || undefined,
+		help: false,
+	};
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			args.help = true;
+			continue;
+		}
+		if (arg === "--include-conversation") {
+			args.includeConversation = true;
+			continue;
+		}
+		if (arg === "--cwd") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--cwd requires a path");
+			args.cwd = resolve(value);
+			continue;
+		}
+		if (arg.startsWith("--cwd=")) {
+			args.cwd = resolve(arg.slice("--cwd=".length));
+			continue;
+		}
+		if (arg === "--model") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--model requires a value");
+			args.model = value.trim();
+			continue;
+		}
+		if (arg.startsWith("--model=")) {
+			args.model = arg.slice("--model=".length).trim();
+			continue;
+		}
+		if (arg === "--prompt") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--prompt requires a value");
+			args.prompt = value;
+			continue;
+		}
+		if (arg.startsWith("--prompt=")) {
+			args.prompt = arg.slice("--prompt=".length);
+			continue;
+		}
+		if (arg === "--out") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--out requires a directory path");
+			args.out = resolve(value);
+			continue;
+		}
+		if (arg.startsWith("--out=")) {
+			args.out = resolve(arg.slice("--out=".length));
+			continue;
+		}
+		if (arg === "--setting-sources") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--setting-sources requires a value");
+			args.settingSources = resolveCursorSettingSources(value);
+			continue;
+		}
+		if (arg.startsWith("--setting-sources=")) {
+			args.settingSources = resolveCursorSettingSources(arg.slice("--setting-sources=".length));
+			continue;
+		}
+		if (arg === "--api-key") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--api-key requires a value");
+			args.apiKey = value.trim();
+			continue;
+		}
+		if (arg.startsWith("--api-key=")) {
+			args.apiKey = arg.slice("--api-key=".length).trim();
+			continue;
+		}
+		fail(`unknown argument: ${arg}`);
+	}
+	return args;
+}
+
+function defaultOutDir() {
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	return join("/tmp", `pi-cursor-sdk-sdk-events-${stamp}`);
+}
+
+function eventType(value) {
+	if (value && typeof value === "object" && typeof value.type === "string") return value.type;
+	return "unknown";
+}
+
+export function createTimingTracker() {
+	return {
+		eventCount: 0,
+		firstMs: undefined,
+		lastMs: undefined,
+		maxGapMs: undefined,
+		record(elapsedMs) {
+			if (this.eventCount === 0) {
+				this.firstMs = elapsedMs;
+			} else {
+				this.maxGapMs = Math.max(this.maxGapMs ?? 0, elapsedMs - (this.lastMs ?? elapsedMs));
+			}
+			this.eventCount += 1;
+			this.lastMs = elapsedMs;
+		},
+		snapshot() {
+			return {
+				eventCount: this.eventCount,
+				firstMs: this.firstMs,
+				lastMs: this.lastMs,
+				maxGapMs: this.maxGapMs,
+			};
+		},
+	};
+}
+
+export function createEventJsonlSink(artifactDir, startedAt) {
+	const paths = {
+		streamEvents: artifactPath(artifactDir, "streamEvents"),
+		onDelta: artifactPath(artifactDir, "onDelta"),
+		onStep: artifactPath(artifactDir, "onStep"),
+	};
+	for (const path of Object.values(paths)) {
+		writeFileSync(path, "");
+	}
+	const counts = {
+		stream: {},
+		onDelta: {},
+		onStep: {},
+	};
+	const timing = {
+		stream: createTimingTracker(),
+		onDelta: createTimingTracker(),
+		onStep: createTimingTracker(),
+	};
+
+	function append(pathKey, countKey, recordKey, value) {
+		const elapsedMs = Date.now() - startedAt;
+		const record = {
+			ts: new Date().toISOString(),
+			elapsedMs,
+			[recordKey]: value,
+		};
+		appendFileSync(paths[pathKey], `${JSON.stringify(record)}\n`);
+		const type = eventType(value);
+		counts[countKey][type] = (counts[countKey][type] ?? 0) + 1;
+		timing[countKey].record(elapsedMs);
+		return record;
+	}
+
+	return {
+		appendStream: (event) => append("streamEvents", "stream", "event", event),
+		appendDelta: (update) => append("onDelta", "onDelta", "update", update),
+		appendStep: (step) => append("onStep", "onStep", "step", step),
+		getSummaryState() {
+			return {
+				counts: {
+					stream: { ...counts.stream },
+					onDelta: { ...counts.onDelta },
+					onStep: { ...counts.onStep },
+				},
+				timing: {
+					stream: timing.stream.snapshot(),
+					onDelta: timing.onDelta.snapshot(),
+					onStep: timing.onStep.snapshot(),
+				},
+			};
+		},
+		close() {
+			return Promise.resolve();
+		},
+	};
+}
+
+function summarizeConversation(conversation) {
+	if (!conversation) return undefined;
+	if (Array.isArray(conversation)) return { turnCount: conversation.length };
+	return conversation;
+}
+
+export function buildSummary({
+	artifactDir,
+	counts,
+	timing,
+	waitResult,
+	conversation,
+	includeConversation,
+}) {
+	return {
+		artifactDir,
+		files: {
+			metadata: artifactPath(artifactDir, "metadata"),
+			streamEvents: artifactPath(artifactDir, "streamEvents"),
+			onDelta: artifactPath(artifactDir, "onDelta"),
+			onStep: artifactPath(artifactDir, "onStep"),
+			waitResult: artifactPath(artifactDir, "waitResult"),
+			conversation: includeConversation ? artifactPath(artifactDir, "conversation") : undefined,
+		},
+		counts,
+		timing,
+		wait: waitResult
+			? {
+					status: waitResult.status,
+					durationMs: waitResult.durationMs,
+					hasResultText: Boolean(waitResult.result?.trim()),
+				}
+			: undefined,
+		conversation: summarizeConversation(conversation),
+		warnings: [RAW_ARTIFACT_WARNING],
+	};
+}
+
+function printStdoutSummary(summary) {
+	console.log(JSON.stringify(summary, null, 2));
+}
+
+async function captureEvents(args) {
+	const artifactDir = args.out ?? defaultOutDir();
+	mkdirSync(artifactDir, { recursive: true });
+	const startedAt = Date.now();
+	const metadata = {
+		capturedAt: new Date(startedAt).toISOString(),
+		cwd: args.cwd,
+		model: args.model,
+		settingSources: args.settingSources ?? null,
+		prompt: args.prompt,
+		packageVersion: packageJson.version,
+		sdkVersion: readSdkVersion(),
+		includeConversation: args.includeConversation,
+		warnings: [RAW_ARTIFACT_WARNING],
+	};
+	writeFileSync(artifactPath(artifactDir, "metadata"), `${JSON.stringify(metadata, null, 2)}\n`);
+
+	const restoreOutputFilter = installCursorSdkOutputFilter();
+	const eventSink = createEventJsonlSink(artifactDir, startedAt);
+	let agent;
+	try {
+		const { Agent } = await suppressCursorSdkOutput(() => import("@cursor/sdk"));
+		agent = await suppressCursorSdkOutput(() =>
+			Agent.create({
+				apiKey: args.apiKey,
+				model: { id: args.model },
+				local: args.settingSources ? { cwd: args.cwd, settingSources: args.settingSources } : { cwd: args.cwd },
+			}),
+		);
+
+		const run = await suppressCursorSdkOutput(() =>
+			agent.send(
+				{ text: args.prompt },
+				{
+					onDelta: ({ update }) => eventSink.appendDelta(update),
+					onStep: ({ step }) => eventSink.appendStep(step),
+				},
+			),
+		);
+
+		await suppressCursorSdkOutput(async () => {
+			for await (const event of run.stream()) {
+				eventSink.appendStream(event);
+			}
+		});
+
+		const waitResult = await suppressCursorSdkOutput(() => run.wait());
+		writeFileSync(artifactPath(artifactDir, "waitResult"), `${JSON.stringify(waitResult, null, 2)}\n`);
+
+		let conversation;
+		if (args.includeConversation) {
+			if (run.supports("conversation")) {
+				conversation = await suppressCursorSdkOutput(() => run.conversation());
+			} else {
+				conversation = {
+					skipped: true,
+					reason: run.unsupportedReason("conversation") ?? "conversation unsupported",
+				};
+			}
+			writeFileSync(artifactPath(artifactDir, "conversation"), `${JSON.stringify(conversation, null, 2)}\n`);
+		}
+
+		const summary = buildSummary({
+			artifactDir,
+			...eventSink.getSummaryState(),
+			waitResult,
+			conversation,
+			includeConversation: args.includeConversation,
+		});
+		writeFileSync(artifactPath(artifactDir, "summary"), `${JSON.stringify(summary, null, 2)}\n`);
+		printStdoutSummary(summary);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		fail(message, [args.apiKey]);
+	} finally {
+		await eventSink.close().catch(() => {});
+		try {
+			agent?.close();
+		} finally {
+			restoreOutputFilter();
+		}
+	}
+}
+
+async function main(argv = process.argv.slice(2), env = process.env) {
+	const args = parseDebugSdkEventsArgs(argv, env);
+	if (args.help) {
+		printHelp();
+		process.exit(0);
+	}
+	if (!args.prompt?.trim()) {
+		fail("--prompt is required");
+	}
+	if (!args.apiKey) {
+		fail("Cursor API key is required. Set CURSOR_API_KEY or pass --api-key.");
+	}
+	await captureEvents(args);
+}
+
+if (import.meta.url === new URL(process.argv[1], "file:").href) {
+	main().catch((error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		fail(message);
+	});
+}

package/scripts/lib/cursor-probe-utils.mjs

@@ -0,0 +1,52 @@
+export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function resolveCursorSettingSources(raw) {
+	const trimmed = raw?.trim();
+	if (!trimmed) return ["all"];
+	const normalized = trimmed.toLowerCase();
+	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
+	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
+	return trimmed
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+}
+
+const BRIDGE_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
+const BRIDGE_ENDPOINT_TOKEN_PATTERN = "[^/\\s\"'<>]+";
+const BRIDGE_LOOPBACK_HOST_PATTERN = "127\\.0\\.0\\.1(?::\\d+)?";
+const BRIDGE_ENDPOINT_PATH_PATTERN = `${escapeRegExp(BRIDGE_ENDPOINT_ROOT)}/${BRIDGE_ENDPOINT_TOKEN_PATTERN}/mcp`;
+
+function scrubBridgeEndpointMaterial(text) {
+	return text
+		.replace(
+			new RegExp(`https?://${BRIDGE_LOOPBACK_HOST_PATTERN}${BRIDGE_ENDPOINT_PATH_PATTERN}`, "gi"),
+			"[redacted-bridge-endpoint]",
+		)
+		.replace(
+			new RegExp(`${BRIDGE_LOOPBACK_HOST_PATTERN}${BRIDGE_ENDPOINT_PATH_PATTERN}`, "gi"),
+			"[redacted-bridge-endpoint]",
+		)
+		.replace(new RegExp(BRIDGE_ENDPOINT_PATH_PATTERN, "gi"), "[redacted-bridge-endpoint]");
+}
+
+export function scrubSensitiveText(text, apiKey) {
+	let scrubbed = text;
+	const trimmedKey = apiKey?.trim();
+	if (trimmedKey) {
+		scrubbed = scrubbed.replace(new RegExp(escapeRegExp(trimmedKey), "g"), "[redacted]");
+	}
+	return scrubBridgeEndpointMaterial(
+		scrubbed
+			.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+			.replace(/((?:^|[\s,{])cookie["']?\s*[:=]\s*["']?)[^\n]+/gi, "$1[redacted]")
+			.replace(
+				/((?:authorization|api[_-]?key|apiKey|token|session(?:[_-]?id)?)["']?\s*[:=]\s*["']?)[^"'\s,;}]+/gi,
+				"$1[redacted]",
+			),
+	);
+}

package/scripts/lib/cursor-sdk-output-filter.mjs

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
+	"[hooks]",
+	"managed_skills.",
+	"CursorPluginsAgentSkillsService load completed",
+	"LocalCursorRulesService load completed",
+	"AgentSkillsCursorRulesService load completed",
+	"Error initializing ignore mapping for",
+	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
+];
+
+const cursorSdkOutputSuppression = new AsyncLocalStorage();
+
+export function isCursorSdkOutputSuppressed() {
+	return cursorSdkOutputSuppression.getStore() === true;
+}
+
+export function suppressCursorSdkOutput(operation) {
+	return cursorSdkOutputSuppression.run(true, operation);
+}
+
+export function isCursorSdkStartupNoise(text) {
+	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function createFilteredProcessWrite(write, stream) {
+	return (chunk, encodingOrCallback, callback) => {
+		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
+			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+			done?.();
+			return true;
+		}
+		return write.call(stream, chunk, encodingOrCallback, callback);
+	};
+}
+
+function createFilteredConsoleMethod(method) {
+	return (...args) => {
+		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
+		method(...args);
+	};
+}
+
+let activeOutputFilterInstalls = 0;
+let outputFilterOriginals;
+
+export function installCursorSdkOutputFilter() {
+	if (activeOutputFilterInstalls === 0) {
+		outputFilterOriginals = {
+			stdoutWrite: process.stdout.write,
+			stderrWrite: process.stderr.write,
+			consoleLog: console.log,
+			consoleInfo: console.info,
+			consoleWarn: console.warn,
+			consoleError: console.error,
+			consoleDebug: console.debug,
+		};
+		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
+		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr);
+		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
+		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
+		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
+		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
+		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
+	}
+	activeOutputFilterInstalls += 1;
+
+	let restored = false;
+	return () => {
+		if (restored) return;
+		restored = true;
+		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
+		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
+		process.stdout.write = outputFilterOriginals.stdoutWrite;
+		process.stderr.write = outputFilterOriginals.stderrWrite;
+		console.log = outputFilterOriginals.consoleLog;
+		console.info = outputFilterOriginals.consoleInfo;
+		console.warn = outputFilterOriginals.consoleWarn;
+		console.error = outputFilterOriginals.consoleError;
+		console.debug = outputFilterOriginals.consoleDebug;
+		outputFilterOriginals = undefined;
+	};
+}