pi-cursor-sdk 0.1.19 → 0.1.21

package/scripts/debug-provider-events.mjs

@@ -5,20 +5,26 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-	CURSOR_SETTING_SOURCES_ENV,
-	resolveCursorSettingSources,
-	scrubSensitiveText,
-} from "./lib/cursor-probe-utils.mjs";
+	apiKeySecretsFromProcess,
+	commonProbeFlags,
+	defaultApiKeyFromEnv,
+	defaultSettingSourcesFromEnv,
+	parseArgv,
+	requireApiKey,
+} from "./lib/cursor-cli-args.mjs";
+import { parseJsonLines, terminateChild, waitForChildClose } from "./lib/cursor-child-process.mjs";
+import { scrubSensitiveText } from "../shared/cursor-sensitive-text.mjs";
+import { createScriptFail } from "./lib/cursor-script-fail.mjs";
+import { serializeCursorSettingSources } from "../shared/cursor-setting-sources.mjs";
 
 const require = createRequire(import.meta.url);
 const root = fileURLToPath(new URL("..", import.meta.url));
 const packageJson = require("../package.json");
 const DEFAULT_MODEL = "cursor/composer-2.5";
 const DEFAULT_OUT_BASE = ".debug/cursor-sdk-events";
-const CHILD_SHUTDOWN_GRACE_MS = 2_000;
 const SDK_EVENT_DEBUG_LOG_PREFIX = "[pi-cursor-sdk:sdk-events]";
 const PI_SESSION_SNAPSHOT_ARTIFACT = "pi-session-snapshot.jsonl";
 const SESSION_PI_SESSION_SNAPSHOT = "pi-session.jsonl";
@@ -72,113 +78,32 @@ Safety:
   - Raw artifact files may contain local paths, tool args/results, or secrets. Do not commit or share them.`);
 }
 
-function fail(message, secrets = []) {
-	const scrubbed = scrubSensitiveText(message, secrets[0]);
-	console.error(`debug-provider-events: ${scrubbed}`);
-	process.exit(1);
-}
+const fail = createScriptFail("debug-provider-events");
 
 export function parseDebugProviderEventsArgs(argv, env = process.env) {
-	const args = {
-		cwd: root,
-		model: DEFAULT_MODEL,
-		prompt: undefined,
-		promptFile: undefined,
-		out: undefined,
-		settingSources: resolveCursorSettingSources(env[CURSOR_SETTING_SOURCES_ENV]),
-		sessionDir: undefined,
-		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 === "--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 === "--prompt-file") {
-			const value = argv[++index];
-			if (!value || value.startsWith("--")) fail("--prompt-file requires a path");
-			args.promptFile = resolve(value);
-			continue;
-		}
-		if (arg.startsWith("--prompt-file=")) {
-			args.promptFile = resolve(arg.slice("--prompt-file=".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 === "--session-dir") {
-			const value = argv[++index];
-			if (!value || value.startsWith("--")) fail("--session-dir requires a path");
-			args.sessionDir = resolve(value);
-			continue;
-		}
-		if (arg.startsWith("--session-dir=")) {
-			args.sessionDir = resolve(arg.slice("--session-dir=".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;
+	return parseArgv(argv, {
+		defaults: {
+			cwd: root,
+			model: DEFAULT_MODEL,
+			prompt: undefined,
+			promptFile: undefined,
+			out: undefined,
+			settingSources: defaultSettingSourcesFromEnv(env),
+			sessionDir: undefined,
+			apiKey: defaultApiKeyFromEnv(env),
+		},
+		flags: {
+			cwd: commonProbeFlags.cwd,
+			model: commonProbeFlags.model,
+			prompt: commonProbeFlags.prompt,
+			promptFile: commonProbeFlags.promptFile,
+			out: commonProbeFlags.out,
+			sessionDir: commonProbeFlags.sessionDir,
+			apiKey: commonProbeFlags.apiKey,
+			settingSources: commonProbeFlags.settingSources,
+		},
+		fail,
+	});
 }
 
 function defaultOutDir(cwd) {
@@ -186,55 +111,6 @@ function defaultOutDir(cwd) {
 	return join(cwd, DEFAULT_OUT_BASE, stamp);
 }
 
-function parseEvents(stdout) {
-	const events = [];
-	for (const line of stdout.split("\n")) {
-		if (!line.trim()) continue;
-		try {
-			events.push(JSON.parse(line));
-		} catch {
-			// ignore partial lines
-		}
-	}
-	return events;
-}
-
-function waitForChildClose(child) {
-	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(child.exitCode ?? 1);
-	return new Promise((resolve) => {
-		child.once("close", (code) => resolve(code ?? 1));
-	});
-}
-
-function signalChild(child, signal) {
-	if (!child.pid) return;
-	try {
-		if (process.platform === "win32") {
-			child.kill(signal);
-		} else {
-			process.kill(-child.pid, signal);
-		}
-	} catch {
-		try {
-			child.kill(signal);
-		} catch {
-			// child already exited
-		}
-	}
-}
-
-async function terminateChild(child) {
-	child.stdin.destroy();
-	if (child.exitCode !== null || child.signalCode !== null) return;
-	signalChild(child, "SIGTERM");
-	const killTimer = setTimeout(() => signalChild(child, "SIGKILL"), CHILD_SHUTDOWN_GRACE_MS);
-	try {
-		await waitForChildClose(child);
-	} finally {
-		clearTimeout(killTimer);
-	}
-}
-
 function readCaptureSummary(artifactDir, stderr) {
 	const summaryPath = join(artifactDir, SUMMARY_ARTIFACT);
 	try {
@@ -254,6 +130,25 @@ function readCaptureSummary(artifactDir, stderr) {
 	return undefined;
 }
 
+function assertCompleteCaptureSummary(captureSummary, artifactDir, apiKey) {
+	if (!captureSummary?.artifactDir) {
+		fail(`missing summary.json in ${artifactDir}`, [apiKey]);
+	}
+	if (!captureSummary.artifacts || typeof captureSummary.artifacts !== "object") {
+		fail(`summary.json missing artifacts in ${artifactDir}`, [apiKey]);
+	}
+	if (!captureSummary.counts || typeof captureSummary.counts !== "object") {
+		fail(`summary.json missing counts in ${artifactDir}`, [apiKey]);
+	}
+	if (typeof captureSummary.elapsedMs !== "number") {
+		fail(`summary.json missing elapsedMs in ${artifactDir}`, [apiKey]);
+	}
+	if (typeof captureSummary.waitResultRecorded !== "boolean") {
+		fail(`summary.json missing waitResultRecorded in ${artifactDir}`, [apiKey]);
+	}
+	return captureSummary;
+}
+
 export function backfillPiSessionSnapshot(captureSummary, artifactDir, sessionDir) {
 	const sessionFile = captureSummary?.piSessionSnapshot?.sessionFile ?? captureSummary?.sessionFile;
 	if (!captureSummary || captureSummary.piSessionSnapshot?.copied || !sessionFile || !existsSync(sessionFile)) {
@@ -279,12 +174,12 @@ export function backfillPiSessionSnapshot(captureSummary, artifactDir, sessionDi
 	}
 }
 
-export async function runDebugProviderEvents(args) {
+export async function runDebugProviderEvents(args, envInput = process.env) {
 	if (args.promptFile) {
 		args.prompt = readFileSync(args.promptFile, "utf8");
 	}
 	if (!args.prompt?.trim()) fail("--prompt or --prompt-file is required");
-	if (!args.apiKey) fail("CURSOR_API_KEY or --api-key is required");
+	args.apiKey = requireApiKey(args, envInput, fail);
 
 	const artifactDir = args.out ?? defaultOutDir(args.cwd);
 	const sessionDir = args.sessionDir ?? join(artifactDir, "session");
@@ -303,13 +198,13 @@ export async function runDebugProviderEvents(args) {
 		sessionDir,
 	];
 	const env = {
-		...process.env,
+		...envInput,
 		CURSOR_API_KEY: args.apiKey,
 		PI_CURSOR_SDK_EVENT_DEBUG: "1",
 		PI_CURSOR_SDK_EVENT_DEBUG_RUN_DIR: artifactDir,
-		PI_CURSOR_SETTING_SOURCES: args.settingSources?.join(",") ?? "all",
-		PI_CURSOR_NATIVE_TOOL_DISPLAY: envFlag(process.env.PI_CURSOR_NATIVE_TOOL_DISPLAY, "1"),
-		PI_CURSOR_PI_TOOL_BRIDGE: envFlag(process.env.PI_CURSOR_PI_TOOL_BRIDGE, "1"),
+		PI_CURSOR_SETTING_SOURCES: serializeCursorSettingSources(args.settingSources),
+		PI_CURSOR_NATIVE_TOOL_DISPLAY: envFlag(envInput.PI_CURSOR_NATIVE_TOOL_DISPLAY, "1"),
+		PI_CURSOR_PI_TOOL_BRIDGE: envFlag(envInput.PI_CURSOR_PI_TOOL_BRIDGE, "1"),
 	};
 
 	const child = spawn("pi", piArgs, {
@@ -336,10 +231,10 @@ export async function runDebugProviderEvents(args) {
 	try {
 		send({ type: "prompt", message: args.prompt });
 		await new Promise((resolve, reject) => {
-			const timeoutMs = Number(process.env.PI_PROVIDER_EVENT_DEBUG_TIMEOUT_MS ?? 600_000);
+			const timeoutMs = Number(envInput.PI_PROVIDER_EVENT_DEBUG_TIMEOUT_MS ?? 600_000);
 			const start = Date.now();
 			const tick = () => {
-				const events = parseEvents(stdout);
+				const events = parseJsonLines(stdout);
 				if (events.some((event) => event.type === "agent_end")) {
 					resolve(events);
 					return;
@@ -359,10 +254,11 @@ export async function runDebugProviderEvents(args) {
 			fail(`pi exited ${exitCode}\nstderr=${scrubSensitiveText(stderr.slice(-2000), args.apiKey)}`, [args.apiKey]);
 		}
 
-		const captureSummary = backfillPiSessionSnapshot(readCaptureSummary(artifactDir, stderr), artifactDir, sessionDir);
-		if (!captureSummary?.artifactDir) {
-			fail(`missing summary.json in ${artifactDir}`, [args.apiKey]);
-		}
+		const captureSummary = assertCompleteCaptureSummary(
+			backfillPiSessionSnapshot(readCaptureSummary(artifactDir, stderr), artifactDir, sessionDir),
+			artifactDir,
+			args.apiKey,
+		);
 
 		return {
 			artifactDir: captureSummary.artifactDir,
@@ -392,12 +288,11 @@ async function main(argv = process.argv.slice(2), env = process.env) {
 		printHelp();
 		return;
 	}
-	console.log(JSON.stringify(await runDebugProviderEvents(args)));
+	console.log(JSON.stringify(await runDebugProviderEvents(args, env)));
 }
 
 if (import.meta.url === new URL(process.argv[1], "file:").href) {
 	main().catch((error) => {
-		console.error(error instanceof Error ? error.message : String(error));
-		process.exitCode = 1;
+		fail(error instanceof Error ? error.message : String(error), apiKeySecretsFromProcess());
 	});
 }

package/scripts/debug-sdk-events.d.mts

@@ -0,0 +1,90 @@
+export interface CursorDebugSdkEventsArgs {
+	cwd: string;
+	model: string;
+	prompt?: string;
+	out?: string;
+	settingSources?: string[] | undefined;
+	includeConversation: boolean;
+	apiKey?: string;
+	help: boolean;
+}
+
+export interface CursorSdkEventDebugSummary {
+	artifactDir: string;
+	files: {
+		metadata: string;
+		streamEvents: string;
+		onDelta: string;
+		onStep: string;
+		waitResult: string;
+		conversation?: string;
+	};
+	counts: {
+		stream: Record<string, number>;
+		onDelta: Record<string, number>;
+		onStep: Record<string, number>;
+	};
+	timing: {
+		stream: CursorSdkEventTimingSnapshot;
+		onDelta: CursorSdkEventTimingSnapshot;
+		onStep: CursorSdkEventTimingSnapshot;
+	};
+	wait?: {
+		status: string;
+		durationMs: number;
+		hasResultText: boolean;
+	};
+	conversation?: { turnCount: number } | Record<string, unknown>;
+	warnings: string[];
+}
+
+export interface CursorSdkEventTimingSnapshot {
+	eventCount: number;
+	firstMs?: number;
+	lastMs?: number;
+	maxGapMs?: number;
+}
+
+export declare function parseDebugSdkEventsArgs(
+	argv: string[],
+	env?: NodeJS.ProcessEnv,
+): CursorDebugSdkEventsArgs;
+
+export declare function createTimingTracker(): {
+	eventCount: number;
+	firstMs?: number;
+	lastMs?: number;
+	maxGapMs?: number;
+	record(elapsedMs: number): void;
+	snapshot(): CursorSdkEventTimingSnapshot;
+};
+
+export interface CursorSdkEventJsonlSink {
+	appendStream(event: unknown): void;
+	appendDelta(update: unknown): void;
+	appendStep(step: unknown): void;
+	getSummaryState(): {
+		counts: {
+			stream: Record<string, number>;
+			onDelta: Record<string, number>;
+			onStep: Record<string, number>;
+		};
+		timing: {
+			stream: CursorSdkEventTimingSnapshot;
+			onDelta: CursorSdkEventTimingSnapshot;
+			onStep: CursorSdkEventTimingSnapshot;
+		};
+	};
+	close(): Promise<void>;
+}
+
+export declare function createEventJsonlSink(artifactDir: string, startedAt: number): CursorSdkEventJsonlSink;
+
+export declare function buildSummary(input: {
+	artifactDir: string;
+	counts: CursorSdkEventDebugSummary["counts"];
+	timing: CursorSdkEventDebugSummary["timing"];
+	waitResult?: { status: string; durationMs: number; result?: string };
+	conversation?: unknown;
+	includeConversation: boolean;
+}): CursorSdkEventDebugSummary;

package/scripts/debug-sdk-events.mjs

@@ -5,12 +5,17 @@
  */
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import {
-	CURSOR_SETTING_SOURCES_ENV,
-	resolveCursorSettingSources,
-	scrubSensitiveText,
-} from "./lib/cursor-probe-utils.mjs";
+	apiKeySecretsFromProcess,
+	commonProbeFlags,
+	defaultApiKeyFromEnv,
+	defaultSettingSourcesFromEnv,
+	defaultTimestampedDir,
+	parseArgv,
+	requireApiKey,
+} from "./lib/cursor-cli-args.mjs";
+import { createScriptFail } from "./lib/cursor-script-fail.mjs";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./lib/cursor-sdk-output-filter.mjs";
 
 const require = createRequire(import.meta.url);
@@ -78,101 +83,36 @@ Safety:
     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);
-}
+const fail = createScriptFail("debug-sdk-events");
 
 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}`);
-	}
+	const includeConversation = argv.includes("--include-conversation");
+	const filteredArgv = argv.filter((arg) => arg !== "--include-conversation");
+	const args = parseArgv(filteredArgv, {
+		defaults: {
+			cwd: process.cwd(),
+			model: DEFAULT_MODEL,
+			prompt: undefined,
+			out: undefined,
+			settingSources: defaultSettingSourcesFromEnv(env),
+			includeConversation,
+			apiKey: defaultApiKeyFromEnv(env),
+		},
+		flags: {
+			cwd: commonProbeFlags.cwd,
+			model: commonProbeFlags.model,
+			prompt: commonProbeFlags.prompt,
+			out: commonProbeFlags.out,
+			apiKey: commonProbeFlags.apiKey,
+			settingSources: commonProbeFlags.settingSources,
+		},
+		fail,
+	});
 	return args;
 }
 
 function defaultOutDir() {
-	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-	return join("/tmp", `pi-cursor-sdk-sdk-events-${stamp}`);
+	return defaultTimestampedDir("pi-cursor-sdk-sdk-events");
 }
 
 function eventType(value) {
@@ -399,15 +339,13 @@ async function main(argv = process.argv.slice(2), env = process.env) {
 	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.");
-	}
+	args.apiKey = requireApiKey(args, env, fail);
 	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);
+		fail(message, apiKeySecretsFromProcess());
 	});
 }

package/scripts/fixtures/plan-strip-shim/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Simulates plan-mode execute: strips grep/find/cursor before turn_start resync.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write"];
+
+export default function planStripShim(pi: ExtensionAPI): void {
+	pi.on("turn_start", () => {
+		pi.setActiveTools(NORMAL_MODE_TOOLS);
+	});
+}