pi-cursor-sdk 0.1.20 → 0.1.22

package/docs/cursor-testing-lessons.md

@@ -4,6 +4,8 @@
 
 This document records maintainer testing lessons for `pi-cursor-sdk`. It complements unit tests and the [Cursor live smoke checklist](./cursor-live-smoke-checklist.md). Use it when adding regression coverage, debugging false-green releases, or building isolated smoke harnesses.
 
+For a **minimal one-session dogfood pass** (baseline env, one native + one bridge call, JSONL ID patterns, bootstrap manifest, edit diff card), use the [Cursor dogfood checklist](./cursor-dogfood-checklist.md) before running the full live smoke matrix.
+
 ## Core lesson: integration-shaped bugs beat unit mocks
 
 The native replay `Tool grep not found` failure was integration-shaped, not unit-shaped:
@@ -236,7 +238,7 @@ The script writes timestamped artifacts under `--out` (default `/tmp/pi-cursor-s
 
 Stdout prints artifact paths and summary counts only. Raw payloads stay on disk and may contain local paths, project text, tool args/results, or secrets — do not commit or share them.
 
-Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone.
+Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current cutover validation targets exact `@cursor/sdk@1.0.14` and pi 0.76.0 local packages.
 
 ## Pi provider SDK event capture
 
@@ -340,7 +342,7 @@ Ask the reporter (or capture yourself) for:
 | `pi --version` and installed `pi-cursor-sdk` version | Confirms extension/runtime in use |
 | Model ID (for example `cursor/composer-2.5`) | Routing/replay behavior is model-scoped |
 | Exact repro prompt and prior turns | Multi-turn replay history affects prompt text |
-| Flags: `--cursor-no-fast`, `PI_CURSOR_PI_TOOL_BRIDGE`, `PI_CURSOR_EXPOSE_BUILTIN_TOOLS`, `PI_CURSOR_SETTING_SOURCES` | Bridge vs native-only vs narrowed settings |
+| Flags: `--cursor-no-fast`, `PI_CURSOR_PI_TOOL_BRIDGE`, `PI_CURSOR_EXPOSE_BUILTIN_TOOLS`, `PI_CURSOR_SETTING_SOURCES`, `PI_CURSOR_TOOL_MANIFEST` | Bridge vs native-only vs narrowed settings; bootstrap callable-surface manifest |
 | Whether the listed names are `pi__*` bridge MCP, Cursor-native (`browser_navigate`, `WebSearch`), or `cursor-replay-*` replay IDs | Three different surfaces (see [Cursor native tool replay](./cursor-native-tool-replay.md#live-bridge-vs-replay)) |
 | Red toast / `errorMessage` text, if any | Distinguishes #55 failure surfacing from silent text echo |
 | Process exit / uncaught `ConnectError` / `ETIMEDOUT` stack trace, if any | Hard network crash (**#43**), not #40 model text echo |
@@ -425,4 +427,7 @@ rg '"type": "toolCall"|Tool call \(Cursor|cursor-replay-' "$SMOKE_DIR/session"/*
 - `scripts/validate-smoke-jsonl.mjs`
 - `scripts/debug-sdk-events.mjs`
 - `scripts/debug-provider-events.mjs`
-- `test/helpers/cursor-provider-harness.ts` — controllable native replay pi mock (`createNativeToolDisplayPiForTest`)
+- `shared/` — runtime-safe ESM helpers consumed by provider `src/` and maintainer scripts (`cursor-sensitive-text.mjs`, `cursor-setting-sources.mjs`).
+- `scripts/lib/` — maintainer plumbing (CLI arg parsing, secret-aware `fail()`, child-process shutdown, shell timeout/auth helpers). Re-exports `shared/` helpers so published smoke/debug scripts stay aligned with provider runtime (`test/maintainer-scripts-lib.test.ts`).
+- `test/helpers/pi-harness.ts` — canonical fake pi/extension harness (`createPiHarness`, shared model/context/event helpers)
+- `test/helpers/cursor-provider-harness.ts` — Cursor SDK provider mocks and stream helpers (re-exports pi-harness fixtures; `createNativeToolDisplayPiForTest` for native replay)

package/docs/cursor-tool-surfaces.md

@@ -0,0 +1,69 @@
+# Cursor tool surfaces in pi
+
+pi-cursor-sdk runs Cursor models through the local `@cursor/sdk` agent runtime. A single pi session can expose **three related but different** tool namespaces. This page is the user-facing guide; maintainer replay details live in [Cursor native tool replay](./cursor-native-tool-replay.md).
+
+## The three surfaces
+
+| Surface | Who owns it | Callable by Cursor? | What pi shows |
+| --- | --- | --- | --- |
+| **Cursor SDK host tools** | Cursor local agent | Yes | Native replay cards (`read`, `bash`, …) or neutral Cursor activity. Representative ToolType list: [SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix). |
+| **Configured Cursor MCP** | Cursor settings / `~/.cursor/mcp.json` | Yes (when loaded) | Neutral **Cursor MCP** activity cards on replay |
+| **Pi bridge (`pi__*`)** | pi-cursor-sdk loopback MCP | Yes, when exposed | Real pi tool names (`cursor_ask_question`, extension tools, …) |
+
+**Not callable:** `cursor-replay-*` IDs in JSONL, pi history tool names used only for display, and transcript labels. Cursor must call exposed `pi__*` MCP names for bridged pi tools, not the pi card name.
+
+## Discoverability
+
+- **MCP `listTools`** (and pi's MCP catalog when present) lists **MCP servers only** — for example `pi_tools` with `pi__cursor_ask_question`. It does **not** enumerate Cursor SDK host tools such as `Read` or `Shell`.
+- **Bootstrap prompts** include a short **Cursor SDK tool boundary** block plus a compact **callable tool surfaces** manifest by default (disable manifest with `PI_CURSOR_TOOL_MANIFEST=0`). The manifest lists host-tool categories, bridge `pi__*` names for the current run, and a reminder that configured Cursor MCP servers appear at runtime via `listTools`. MCP `listTools` entries for bridged pi tools point back to the bootstrap prompt instead of repeating the full contract.
+- **Incremental prompts** omit the full boundary block but keep a short tail guard (including an explicit shell `cd` hint); the session agent retains prior bootstrap context.
+- **In-session debug:** `/cursor-tools` prints bridge enablement, manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and the current callable-surface snapshot.
+
+## Pi bridge vs Cursor native
+
+Default behavior:
+
+- Cursor host tools handle files, shell, grep, edits, tasks, and Cursor-native MCP/plugins.
+- The pi bridge exposes **active pi tools** as `pi__*` MCP names when `PI_CURSOR_PI_TOOL_BRIDGE` is enabled (default on).
+- Overlapping pi builtins (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`) are **hidden** from the bridge unless `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1`.
+
+`pi-cursor-sdk` always registers `cursor_ask_question` for Cursor models when the bridge is on; Cursor sees `pi__cursor_ask_question`.
+
+```bash
+# Disable pi bridge entirely
+PI_CURSOR_PI_TOOL_BRIDGE=0 pi --model cursor/composer-2.5
+
+# Expose overlapping pi builtins through the bridge
+PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 pi --model cursor/composer-2.5
+
+# Disable bootstrap tool manifest
+PI_CURSOR_TOOL_MANIFEST=0 pi --model cursor/composer-2.5
+```
+
+## Cursor settings vs pi toggles
+
+Disabling or removing an MCP server **only in pi** does not remove Cursor ambient MCP loaded from Cursor config.
+
+| Control | Effect |
+| --- | --- |
+| `PI_CURSOR_SETTING_SOURCES=all` (default) | Loads user/project Cursor MCP, plugins, rules (`~/.cursor/mcp.json`, etc.) |
+| `PI_CURSOR_SETTING_SOURCES=none` | Disables ambient Cursor setting sources for local agents |
+| `PI_CURSOR_SETTING_SOURCES=project,plugins` | Narrows which layers load |
+| Empty or edited `~/.cursor/mcp.json` | Changes which user MCP servers Cursor connects to |
+
+To reproduce a **minimal** surface (pi-cursor-sdk + Cursor host only), use extension-only install, empty user MCP config, and `PI_CURSOR_SETTING_SOURCES=none` when you do not need Cursor rules/MCP from disk.
+
+## JSONL ID patterns (debugging)
+
+| ID prefix | Meaning |
+| --- | --- |
+| `cursor-replay-*` | Display-only replay of Cursor SDK activity |
+| `cursor-pi-bridge-run-*` | Live pi execution via bridge |
+
+Example mistake: treating `cursor-replay-…` as a tool to invoke. Replay never re-runs work.
+
+## Related docs
+
+- [README — Cursor provider tool contract](../README.md#cursor-provider-tool-contract)
+- [Cursor native tool replay](./cursor-native-tool-replay.md)
+- [Cursor model UX spec](./cursor-model-ux-spec.md)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.20",
+	"version": "0.1.22",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -22,21 +22,39 @@
 	},
 	"homepage": "https://github.com/fitchmultz/pi-cursor-sdk#readme",
 	"files": [
+		"shared",
 		"src",
 		"scripts/refresh-cursor-model-snapshots.mjs",
 		"scripts/steering-rpc-smoke.mjs",
 		"scripts/tmux-live-smoke.sh",
+		"scripts/visual-tui-smoke.mjs",
 		"scripts/isolated-cursor-smoke.sh",
+		"scripts/fixtures/plan-strip-shim",
 		"scripts/validate-smoke-jsonl.mjs",
 		"scripts/probe-mcp-coldstart.mjs",
 		"scripts/debug-sdk-events.mjs",
+		"scripts/debug-sdk-events.d.mts",
 		"scripts/debug-provider-events.mjs",
-		"scripts/lib/cursor-probe-utils.mjs",
+		"scripts/debug-provider-events.d.mts",
+		"scripts/lib/cursor-cli-args.mjs",
+		"scripts/lib/cursor-cli-args.d.mts",
+		"scripts/lib/cursor-child-process.mjs",
+		"scripts/lib/cursor-child-process.d.mts",
+		"scripts/lib/cursor-script-fail.mjs",
+		"scripts/lib/cursor-script-fail.d.mts",
+		"scripts/lib/cursor-smoke-env.mjs",
+		"scripts/lib/cursor-smoke-env.d.mts",
+		"scripts/lib/cursor-smoke-shell.sh",
+		"scripts/lib/cursor-visual-render.mjs",
+		"scripts/lib/cursor-visual-render.d.mts",
 		"scripts/lib/cursor-sdk-output-filter.mjs",
+		"scripts/lib/cursor-sdk-output-filter.d.mts",
 		"README.md",
 		"docs/cursor-model-ux-spec.md",
+		"docs/cursor-tool-surfaces.md",
 		"docs/cursor-live-smoke-checklist.md",
 		"docs/cursor-testing-lessons.md",
+		"docs/cursor-dogfood-checklist.md",
 		"docs/cursor-native-tool-replay.md",
 		"docs/cursor-native-tool-visual-audit.md",
 		"LICENSE",
@@ -47,11 +65,15 @@
 		"node": ">=22.19.0"
 	},
 	"scripts": {
-		"typecheck": "tsc --noEmit",
+		"typecheck": "npm run typecheck:src && npm run typecheck:tests && npm run typecheck:replay-compile",
+		"typecheck:src": "tsc --noEmit",
+		"typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
+		"typecheck:replay-compile": "tsc --noEmit -p test/tsconfig.json",
 		"test": "vitest run",
 		"test:watch": "vitest",
 		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs",
 		"smoke:live": "scripts/tmux-live-smoke.sh",
+		"smoke:visual": "node scripts/visual-tui-smoke.mjs",
 		"smoke:isolated": "scripts/isolated-cursor-smoke.sh",
 		"smoke:steering": "node scripts/steering-rpc-smoke.mjs",
 		"smoke:jsonl": "node scripts/validate-smoke-jsonl.mjs",
@@ -60,19 +82,21 @@
 		"debug:mcp-coldstart": "node scripts/probe-mcp-coldstart.mjs"
 	},
 	"dependencies": {
-		"@cursor/sdk": "^1.0.13",
+		"@cursor/sdk": "1.0.14",
 		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": "*",
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*",
+		"@earendil-works/pi-ai": ">=0.76.0",
+		"@earendil-works/pi-coding-agent": ">=0.76.0",
+		"@earendil-works/pi-tui": ">=0.76.0",
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "^0.75.5",
-		"@earendil-works/pi-coding-agent": "^0.75.5",
-		"@earendil-works/pi-tui": "^0.75.5",
+		"@earendil-works/pi-ai": "0.76.0",
+		"@earendil-works/pi-coding-agent": "0.76.0",
+		"@earendil-works/pi-tui": "0.76.0",
+		"@xterm/xterm": "^6.0.0",
+		"playwright": "^1.60.0",
 		"typebox": "^1.1.38",
 		"typescript": "^6.0.3",
 		"vitest": "^4.1.6"

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

@@ -0,0 +1,59 @@
+export interface CursorDebugProviderEventsArgs {
+	cwd: string;
+	model: string;
+	prompt?: string;
+	promptFile?: string;
+	out?: string;
+	settingSources?: string[] | undefined;
+	sessionDir?: string;
+	apiKey?: string;
+	help: boolean;
+}
+
+export declare function parseDebugProviderEventsArgs(
+	argv: string[],
+	env?: NodeJS.ProcessEnv,
+): CursorDebugProviderEventsArgs;
+
+export interface CursorPiSessionSnapshotState {
+	copied: boolean;
+	sessionFile?: string;
+	reason?: string;
+	recoveredAfterChildExit?: boolean;
+}
+
+export type CursorDebugCaptureCounts = Record<string, number | Record<string, number>>;
+
+export interface CursorDebugCaptureSummary {
+	artifactDir: string;
+	sessionFile?: string;
+	counts: CursorDebugCaptureCounts;
+	piSessionSnapshot?: CursorPiSessionSnapshotState;
+	artifacts?: Record<string, string>;
+	elapsedMs?: number;
+	waitResultRecorded?: boolean;
+}
+
+export interface CursorDebugProviderEventsRunSummary {
+	artifactDir: string;
+	artifacts: Record<string, string>;
+	counts: CursorDebugCaptureCounts;
+	elapsedMs: number;
+	model: string;
+	cwd: string;
+	sessionDir: string;
+	extensionVersion: string;
+	sdkVersion: string;
+	waitResultRecorded: boolean;
+}
+
+export declare function backfillPiSessionSnapshot(
+	captureSummary: CursorDebugCaptureSummary | undefined,
+	artifactDir: string,
+	sessionDir: string,
+): CursorDebugCaptureSummary | undefined;
+
+export declare function runDebugProviderEvents(
+	args: CursorDebugProviderEventsArgs,
+	env?: NodeJS.ProcessEnv,
+): Promise<CursorDebugProviderEventsRunSummary>;

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;