pi-cursor-sdk 0.1.17 → 0.1.19

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/isolated-cursor-smoke.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# Isolated /tmp install + fail-fast live smoke for pi-cursor-sdk native replay.
+#
+# Validates packed extension load, plan-strip resync, and absence of "Tool * not found".
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+REAL_HOME="${REAL_HOME:-$HOME}"
+PI_AGENT_DIR="${PI_AGENT_DIR:-$REAL_HOME/.pi/agent}"
+AUTH_JSON="${AUTH_JSON:-$PI_AGENT_DIR/auth.json}"
+REPO="${REPO:-$ROOT}"
+ISOLATED="${ISOLATED:-/tmp/pi-cursor-sdk-isolated-$(date +%Y%m%dT%H%M%S)}"
+PI_LIVE_TIMEOUT="${PI_LIVE_TIMEOUT:-45}"
+SKIP_LIVE="${SKIP_LIVE:-0}"
+SKIP_UNIT="${SKIP_UNIT:-0}"
+PI_BIN="${PI_BIN:-pi}"
+PI_PATH="${PI_PATH:-/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin}"
+
+PACK_DIR="$ISOLATED/pack"
+EXTRACT_DIR="$ISOLATED/extract"
+PROJECT_DIR="$ISOLATED/project"
+SESSION_ROOT="$ISOLATED/sessions"
+SHIM_DIR="$ROOT/scripts/fixtures/plan-strip-shim"
+HOME_DIR="$ISOLATED/home"
+
+print_help() {
+	cat <<EOF
+Isolated /tmp install smoke for pi-cursor-sdk (native replay + plan-strip resync).
+
+Usage:
+  ./scripts/isolated-cursor-smoke.sh
+  SKIP_LIVE=1 ./scripts/isolated-cursor-smoke.sh
+  PI_LIVE_TIMEOUT=90 ./scripts/isolated-cursor-smoke.sh
+
+Environment:
+  REPO                          Repo under test (default: script parent directory).
+  ISOLATED                      Artifact root (default: /tmp/pi-cursor-sdk-isolated-<timestamp>).
+  REAL_HOME                     Source for auth.json (default: \$HOME).
+  AUTH_JSON                     Path to pi auth.json to seed isolated HOME (default: ~/.pi/agent/auth.json).
+  PI_LIVE_TIMEOUT               Per live pi check timeout in seconds (default: 45).
+  PI_BIN                        pi executable (default: pi on PATH).
+  PI_PATH                       PATH for isolated pi runs.
+  SKIP_LIVE=1                   Run unit tests + pack only; skip live Cursor calls.
+  SKIP_UNIT=1                   Skip repo unit tests (live checks only).
+  CURSOR_API_KEY                Optional fallback when auth.json lacks cursor provider.
+
+Prerequisites:
+  node, npm, pi, rg, python3 on PATH
+  ~/.pi/agent/auth.json with cursor provider OR CURSOR_API_KEY
+
+Exit codes:
+  0  all requested checks passed
+  1  prerequisite, unit, pack, live smoke, or JSONL replay validation failure
+EOF
+}
+
+log() {
+	printf '[isolated-smoke] %s\n' "$*"
+}
+
+fail() {
+	printf '[isolated-smoke] FAIL: %s\n' "$*" >&2
+	exit 1
+}
+
+seed_pi_agent_home() {
+	local home="$1"
+	mkdir -p "$home/.pi/agent"
+	if [[ -f "$AUTH_JSON" ]]; then
+		cp "$AUTH_JSON" "$home/.pi/agent/auth.json"
+		chmod 600 "$home/.pi/agent/auth.json"
+		log "seeded $home/.pi/agent/auth.json"
+	else
+		log "WARN: no auth.json at $AUTH_JSON"
+	fi
+	if [[ -f "$PI_AGENT_DIR/models.json" ]]; then
+		cp "$PI_AGENT_DIR/models.json" "$home/.pi/agent/models.json"
+	fi
+}
+
+has_auth_provider() {
+	local provider="$1"
+	python3 - "$provider" "$HOME_DIR/.pi/agent/auth.json" <<'PY'
+import json, sys
+provider, path = sys.argv[1], sys.argv[2]
+try:
+    data = json.load(open(path))
+except FileNotFoundError:
+    sys.exit(1)
+sys.exit(0 if provider in data and data[provider] else 1)
+PY
+}
+
+run_with_timeout() {
+	local label="$1"
+	local seconds="$2"
+	shift 2
+	log "$label (timeout ${seconds}s)"
+	if command -v timeout >/dev/null 2>&1; then
+		timeout --foreground "${seconds}s" "$@" || {
+			local rc=$?
+			[[ $rc -eq 124 ]] && fail "$label timed out after ${seconds}s"
+			fail "$label exited $rc"
+		}
+		return
+	fi
+	if command -v gtimeout >/dev/null 2>&1; then
+		gtimeout "${seconds}s" "$@" || {
+			local rc=$?
+			[[ $rc -eq 124 ]] && fail "$label timed out after ${seconds}s"
+			fail "$label exited $rc"
+		}
+		return
+	fi
+	"$@" &
+	local pid=$!
+	local waited=0
+	while kill -0 "$pid" 2>/dev/null; do
+		if (( waited >= seconds )); then
+			kill -TERM "$pid" 2>/dev/null || true
+			sleep 1
+			kill -KILL "$pid" 2>/dev/null || true
+			fail "$label timed out after ${seconds}s"
+		fi
+		sleep 1
+		waited=$((waited + 1))
+	done
+	wait "$pid" || fail "$label exited $?"
+}
+
+validate_replay_jsonl() {
+	local dir="$1"
+	node "$ROOT/scripts/validate-smoke-jsonl.mjs" --replay-errors-only "$dir"
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+	print_help
+	exit 0
+fi
+
+if [[ -f "${SECRETS_FILE:-$REAL_HOME/.secrets}" ]]; then
+	set +u
+	# shellcheck disable=SC1090
+	source "${SECRETS_FILE:-$REAL_HOME/.secrets}"
+	set -u
+fi
+
+command -v node >/dev/null || fail "missing node"
+command -v npm >/dev/null || fail "missing npm"
+command -v rg >/dev/null || fail "missing rg"
+command -v python3 >/dev/null || fail "missing python3"
+
+mkdir -p "$PACK_DIR" "$EXTRACT_DIR" "$PROJECT_DIR" "$SESSION_ROOT" "$HOME_DIR"
+seed_pi_agent_home "$HOME_DIR"
+
+log "isolated root: $ISOLATED"
+log "HOME=$HOME_DIR"
+
+if [[ "$SKIP_UNIT" != "1" ]]; then
+	log "preflight: repo unit tests"
+	run_with_timeout "npm test" 120 bash -lc "cd '$REPO' && npm test"
+fi
+
+if [[ "$SKIP_LIVE" == "1" ]]; then
+	log "SKIP_LIVE=1 — skipping live pi checks"
+	exit 0
+fi
+
+if ! has_auth_provider cursor && [[ -z "${CURSOR_API_KEY:-}" ]]; then
+	fail "no cursor auth in $HOME_DIR/.pi/agent/auth.json and CURSOR_API_KEY unset"
+fi
+
+command -v "$PI_BIN" >/dev/null || fail "PI_BIN not found: $PI_BIN"
+
+log "npm pack from $REPO"
+(cd "$REPO" && npm pack --pack-destination "$PACK_DIR" >/dev/null 2>&1)
+PACK_TGZ="$(ls -t "$PACK_DIR"/*.tgz | head -1)"
+[[ -f "$PACK_TGZ" ]] || fail "missing pack tarball"
+tar -xzf "$PACK_TGZ" -C "$EXTRACT_DIR"
+[[ -d "$EXTRACT_DIR/package" ]] || fail "extract missing package/ dir"
+
+log "npm install packed extension deps"
+run_with_timeout "npm install --omit=dev" 120 bash -lc "cd '$EXTRACT_DIR/package' && npm install --omit=dev >/dev/null 2>&1"
+
+log "pi install -l (clean HOME)"
+cp "$REPO/README.md" "$PROJECT_DIR/README.md"
+run_with_timeout "pi install" 30 env -i HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' install -l '$EXTRACT_DIR/package' >/dev/null"
+
+run_with_timeout "pi list" 15 env -i HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' list" | rg -q "extract/package" || fail "packed extension not installed"
+
+PI_ENV=(HOME="$HOME_DIR" PATH="$PI_PATH" MISE_DISABLE=1 PI_CURSOR_SETTING_SOURCES=none)
+if [[ -n "${CURSOR_API_KEY:-}" ]]; then
+	PI_ENV+=(CURSOR_API_KEY="$CURSOR_API_KEY")
+fi
+
+log "check: list-models"
+LIST_OUT="$ISOLATED/list-models.txt"
+run_with_timeout "list-models" 30 env -i "${PI_ENV[@]}" \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --list-models cursor > '$LIST_OUT' 2>&1"
+rg -q "composer-2\\.5|composer-2-5" "$LIST_OUT" || fail "composer-2.5 not listed (see $LIST_OUT)"
+
+log "check: basic provider prompt"
+BASIC_DIR="$SESSION_ROOT/basic"
+mkdir -p "$BASIC_DIR"
+run_with_timeout "basic prompt" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$BASIC_DIR' --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK' > '$ISOLATED/basic.stdout.txt' 2> '$ISOLATED/basic.stderr.txt'"
+rg -q "PI_CURSOR_ISOLATED_OK" "$ISOLATED/basic.stdout.txt" || fail "basic prompt missing PI_CURSOR_ISOLATED_OK"
+validate_replay_jsonl "$BASIC_DIR"
+
+log "check: native replay"
+REPLAY_DIR="$SESSION_ROOT/native-replay"
+mkdir -p "$REPLAY_DIR"
+run_with_timeout "native replay" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$REPLAY_DIR' -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.' > '$ISOLATED/replay.stdout.txt' 2> '$ISOLATED/replay.stderr.txt'"
+validate_replay_jsonl "$REPLAY_DIR"
+
+log "check: plan-strip shim (plan-mode execute reset)"
+PLAN_DIR="$SESSION_ROOT/plan-strip"
+mkdir -p "$PLAN_DIR"
+run_with_timeout "plan-strip replay" "$PI_LIVE_TIMEOUT" env -i "${PI_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
+	bash -c "cd '$PROJECT_DIR' && '$PI_BIN' -e '$SHIM_DIR' --cursor-no-fast --model cursor/composer-2.5 --session-dir '$PLAN_DIR' -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.' > '$ISOLATED/plan.stdout.txt' 2> '$ISOLATED/plan.stderr.txt'"
+validate_replay_jsonl "$PLAN_DIR"
+
+log "PASS isolated install smoke: $ISOLATED"

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]",
+			),
+	);
+}