pi-cursor-sdk 0.1.39 → 0.1.41

package/scripts/visual-tui-smoke.mjs

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { accessSync, chmodSync, constants, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { accessSync, constants, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { commonBooleanFlag, commonRepeatStringFlag, parseArgv } from "./lib/cursor-cli-args.mjs";
 import { buildCursorSmokeEnvPlan, CURSOR_SDK_EVENT_DEBUG_ENV_NAMES, sealedNodePath } from "./lib/cursor-smoke-env.mjs";
+import { writeVisualManifest } from "./lib/cursor-visual-manifest.mjs";
+import { runVisualSmokeSelfTest } from "./visual-tui-smoke-self-test.mjs";
 import { buildTerminalHtml, writeTerminalScreenshot } from "./lib/cursor-visual-render.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -71,6 +72,7 @@ Artifacts written:
   <label>.html                  Self-contained browser/xterm render.
   <label>.png                   Browser-rendered screenshot, unless --no-screenshot.
   <label>.jsonl.path            Latest persisted pi session JSONL path.
+  <label>.manifest.json         Agent-readable artifact index for this run.
 
 Prerequisites:
   - pi, node, tmux, and npm-installed dev dependencies on PATH / in node_modules.
@@ -363,6 +365,7 @@ function buildLaunchPlan(options, commands, shell) {
 		...envAssignments.map(([name, value]) => `${name}=${shellQuote(value)}`),
 		"exec",
 		shellQuote(commands.pi),
+		"--approve",
 		"-e", shellQuote(options.ext),
 		"--cursor-no-fast",
 		"--cursor-mode", shellQuote(options.mode),
@@ -447,205 +450,60 @@ function runVisualSmoke(options) {
 		const htmlPath = `${base}.html`;
 		const pngPath = `${base}.png`;
 		const jsonlPathFile = `${base}.jsonl.path`;
+		const manifestPath = `${base}.manifest.json`;
 
 		writeUtf8(ansiPath, ansi);
 		writeUtf8(textPath, plain);
 		writeUtf8(htmlPath, buildTerminalHtml({ ansi, plain, options }));
 
+		const partialArtifacts = { ansiPath, textPath, htmlPath, pngPath, jsonlPathFile, manifestPath };
 		const jsonlPath = findLatestJsonl(options.sessionDir, { sinceMs: runStartedAtMs, previousMtimes: jsonlMtimesBeforeRun });
-		if (!jsonlPath) throw new Error(`no current-run persisted .jsonl found under ${options.sessionDir}`);
+		if (!jsonlPath) {
+			const message = `no current-run persisted .jsonl found under ${options.sessionDir}`;
+			writeVisualManifest(manifestPath, options, partialArtifacts, { message, writtenAt: new Date().toISOString() });
+			throw new Error(message);
+		}
 		writeUtf8(jsonlPathFile, `${jsonlPath}\n`);
 
-		return { ansiPath, textPath, htmlPath, pngPath, jsonlPathFile, jsonlPath };
+		return { ...partialArtifacts, jsonlPath };
 	} finally {
 		if (bufferLoaded) run(commands.tmux, ["delete-buffer", "-b", bufferName]);
 		if (sessionStarted) run(commands.tmux, ["kill-session", "-t", sessionName]);
 	}
 }
 
-function assertSelfTest(condition, message) {
-	if (!condition) throw new Error(`self-test failed: ${message}`);
-}
-
-function envMap(assignments) {
-	return new Map(assignments.map(([name, value]) => [name, value]));
-}
-
-function parseEnvCapture(path) {
-	return new Map(
-		readFileSync(path, "utf8")
-			.split("\n")
-			.filter(Boolean)
-			.map((line) => {
-				const index = line.indexOf("=");
-				return index === -1 ? [line, ""] : [line.slice(0, index), line.slice(index + 1)];
-			}),
-	);
-}
-
-function runSelfTest() {
-	const tempDir = mkdtempSync(join(tmpdir(), "pi-cursor-sdk-visual-self-test-"));
-	try {
-		const binDir = join(tempDir, "bin");
-		mkdirSync(binDir, { recursive: true });
-		const fakePi = join(binDir, "pi");
-		const fakeNode = join(binDir, "node");
-		const fakeNodeMarker = join(tempDir, "fake-node-used");
-		const envCapture = join(tempDir, "fake-pi.env");
-		writeFileSync(
-			fakePi,
-			`#!/usr/bin/env node\nconst { writeFileSync } = require("node:fs");\nwriteFileSync(${JSON.stringify(envCapture)}, Object.entries(process.env).map(([key, value]) => key + "=" + (value ?? "")).join("\\n") + "\\n", "utf8");\n`,
-			"utf8",
-		);
-		writeFileSync(fakeNode, `#!/bin/sh\necho fake-node-used > ${shellQuote(fakeNodeMarker)}\nexit 99\n`, "utf8");
-		chmodSync(fakePi, 0o755);
-		chmodSync(fakeNode, 0o755);
-
-		const promptFile = join(tempDir, "prompt.txt");
-		writeFileSync(promptFile, "file prompt", "utf8");
-		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt-file", promptFile, "--prompt", "inline prompt"]).prompt === "inline prompt", "--prompt should override an earlier --prompt-file");
-		assertSelfTest(parseArgs(["--label", "prompt-dash", "--prompt", "--starts-with-dash"]).prompt === "--starts-with-dash", "--prompt should accept dash-prefixed free-form text");
-		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt", "inline prompt", "--prompt-file", promptFile]).prompt === "file prompt", "--prompt-file should override an earlier --prompt");
-
-		const jsonlDir = join(tempDir, "jsonl-filter");
-		mkdirSync(jsonlDir, { recursive: true });
-		const staleJsonl = join(jsonlDir, "stale.jsonl");
-		const freshJsonl = join(jsonlDir, "fresh.jsonl");
-		writeFileSync(staleJsonl, "{}\n", "utf8");
-		utimesSync(staleJsonl, new Date(1_000), new Date(1_000));
-		const previousJsonlMtimes = snapshotJsonlMtimes(jsonlDir);
-		writeFileSync(freshJsonl, "{}\n", "utf8");
-		utimesSync(freshJsonl, new Date(3_000), new Date(3_000));
-		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 2_000, previousMtimes: previousJsonlMtimes }) === freshJsonl, "JSONL discovery should ignore unchanged stale files before run start");
-		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 4_000, previousMtimes: snapshotJsonlMtimes(jsonlDir) }) === undefined, "JSONL discovery should not return stale evidence when current run has no changed JSONL");
-
-		assertSelfTest(!sealedNodePath(process.execPath, "").includes(delimiter), "empty inherited PATH must not leave an empty PATH segment");
-		const hostilePath = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
-		const sealedHostilePath = sealedNodePath(process.execPath, hostilePath);
-		assertSelfTest(resolveCommand("pi", hostilePath) === fakePi, "direct PATH resolver did not prefer fake PATH head");
-		assertSelfTest(requireNode() === process.execPath, "node resolver must use process.execPath");
-		assertSelfTest(requireCommand("pi", { envPath: hostilePath, env: { ...process.env, PATH: sealedHostilePath } }) === fakePi, "pi prereq should use sealed PATH when executing the shim");
-		assertSelfTest(!existsSync(fakeNodeMarker), "pi prereq should not use hostile fake node");
-
-		const baseOptions = {
-			ext: ROOT,
-			cwd: ROOT,
-			mode: DEFAULT_MODE,
-			model: DEFAULT_MODEL,
-			outDir: tempDir,
-			safeLabel: "self-test",
-			sessionDir: join(tempDir, "session"),
-			sessionId: "self-test",
-			settingSources: DEFAULT_SETTING_SOURCES,
-			bridge: false,
-			exposeBuiltinTools: false,
-			eventDebug: false,
-		};
-		const plan = buildLaunchPlan(baseOptions, { pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath }, "/bin/sh");
-		const defaults = envMap(plan.envAssignments);
-		assertSelfTest(defaults.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "native display must be forced on");
-		assertSelfTest(defaults.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "native tool registration must be forced on");
-		assertSelfTest(defaults.get("PI_CURSOR_SETTING_SOURCES") === "none", "setting sources must default to none");
-		assertSelfTest(defaults.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "bridge must default off");
-		assertSelfTest(defaults.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "built-in exposure must default off");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(plan.clearEnvNames.includes(name), `${name} must be cleared by default`);
-		}
-		assertSelfTest(plan.script.includes(shellQuote(fakePi)), "launch script must use resolved pi path");
-		assertSelfTest(!plan.script.includes(" exec pi "), "launch script must not use bare pi");
-		const hostileEnv = {
-			...process.env,
-			...Object.fromEntries(DEBUG_ENV_NAMES.map((name) => [name, join(tempDir, name)])),
-			PATH: hostilePath,
-			PI_CURSOR_REGISTER_NATIVE_TOOLS: "0",
-			PI_CURSOR_SETTING_SOURCES: "all",
-			PI_CURSOR_PI_TOOL_BRIDGE: "1",
-			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "1",
-		};
-		const probe = run("/bin/sh", ["-c", plan.script], { env: hostileEnv });
-		assertSelfTest(probe.status === 0, `fake-pi env capture exited ${probe.status}: ${probe.stderr?.toString() ?? ""}`);
-		const capturedEnv = parseEnvCapture(envCapture);
-		assertSelfTest(!existsSync(fakeNodeMarker), "launch PATH should force the resolved node before hostile fake node");
-		assertSelfTest((capturedEnv.get("PATH") ?? "").split(delimiter)[0] === dirname(process.execPath), "captured PATH should start with resolved node directory");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "captured env should force native display on");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "captured env should force native registration on");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_SETTING_SOURCES") === "none", "captured env should force settings off");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "captured env should force bridge off");
-		assertSelfTest(capturedEnv.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "captured env should force built-in exposure off");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(!capturedEnv.has(name), `${name} should be absent from captured env by default`);
-		}
-
-		const optInPlan = buildLaunchPlan(
-			{ ...baseOptions, settingSources: "all", bridge: true, exposeBuiltinTools: true, eventDebug: true },
-			{ pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath },
-			"/bin/sh",
-		);
-		const optIns = envMap(optInPlan.envAssignments);
-		assertSelfTest(optIns.get("PI_CURSOR_SETTING_SOURCES") === "all", "setting source opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_PI_TOOL_BRIDGE") === "1", "bridge opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "1", "built-in exposure opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug opt-in must be reflected");
-		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir must be deterministic under out-dir");
-		for (const name of DEBUG_ENV_NAMES) {
-			assertSelfTest(optInPlan.clearEnvNames.includes(name), `${name} must be cleared even when event debug is explicit`);
-		}
-		const eventDebugProbe = run("/bin/sh", ["-c", optInPlan.script], { env: hostileEnv });
-		assertSelfTest(eventDebugProbe.status === 0, `fake-pi event-debug env capture exited ${eventDebugProbe.status}: ${eventDebugProbe.stderr?.toString() ?? ""}`);
-		const capturedEventDebugEnv = parseEnvCapture(envCapture);
-		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug should be explicitly enabled");
-		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir should be deterministic under out-dir");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_RUN_DIR"), "stale event debug run dir should be cleared");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_SESSION_DIR"), "stale event debug session dir should be cleared");
-		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_STDERR"), "stale event debug stderr flag should be cleared");
-
-		const fakeTmux = join(binDir, "tmux");
-		const deleteBufferMarker = join(tempDir, "delete-buffer-called");
-		writeFileSync(
-			fakeTmux,
-			`#!/bin/sh\ncase "$1" in\n  -V) echo 'tmux fake'; exit 0 ;;\n  new-session) exit 0 ;;\n  load-buffer) cat >/dev/null; exit 0 ;;\n  paste-buffer) exit 77 ;;\n  delete-buffer) echo deleted > ${shellQuote(deleteBufferMarker)}; exit 0 ;;\n  kill-session) exit 0 ;;\n  *) echo "unexpected tmux command: $*" >&2; exit 64 ;;\nesac\n`,
-			"utf8",
-		);
-		chmodSync(fakeTmux, 0o755);
-		const originalPath = process.env.PATH;
-		try {
-			process.env.PATH = hostilePath;
-			let pasteFailed = false;
-			try {
-				runVisualSmoke({
-					...baseOptions,
-					prompt: "buffer cleanup prompt",
-					startupMs: 1,
-					waitMs: 1,
-					width: 80,
-					height: 24,
-					historyLines: 100,
-				});
-			} catch (error) {
-				pasteFailed = /paste-buffer failed/.test(error instanceof Error ? error.message : String(error));
-			}
-			assertSelfTest(pasteFailed, "fake tmux paste failure should exercise prompt-buffer cleanup path");
-			assertSelfTest(existsSync(deleteBufferMarker), "prompt tmux buffer should be deleted when paste/send fails");
-		} finally {
-			if (originalPath === undefined) delete process.env.PATH;
-			else process.env.PATH = originalPath;
-		}
-		console.log("[visual-smoke] self-test PASS");
-	} finally {
-		rmSync(tempDir, { recursive: true, force: true });
-	}
-}
 
 const options = parseArgs(process.argv.slice(2));
+let artifacts;
 try {
 	if (options.selfTest) {
-		runSelfTest();
+		runVisualSmokeSelfTest({
+			ROOT,
+			DEFAULT_MODE,
+			DEFAULT_MODEL,
+			DEFAULT_SETTING_SOURCES,
+			DEBUG_ENV_NAMES,
+			shellQuote,
+			parseArgs,
+			snapshotJsonlMtimes,
+			findLatestJsonl,
+			sealedNodePath,
+			resolveCommand,
+			requireNode,
+			requireCommand,
+			buildLaunchPlan,
+			run,
+			runVisualSmoke,
+		});
 		process.exit(0);
 	}
-	const artifacts = runVisualSmoke(options);
+	artifacts = runVisualSmoke(options);
+	writeVisualManifest(artifacts.manifestPath, options, artifacts);
 	checkLeftovers(options.leftoverPatterns);
 	if (options.screenshot) {
 		await writeTerminalScreenshot(artifacts.htmlPath, artifacts.pngPath, options.width, options.height);
+		artifacts.pngWritten = true;
+		writeVisualManifest(artifacts.manifestPath, options, artifacts);
 	}
 	console.log("[visual-smoke] artifacts:");
 	console.log(`  ansi:       ${artifacts.ansiPath}`);
@@ -654,6 +512,15 @@ try {
 	if (options.screenshot) console.log(`  png:        ${artifacts.pngPath}`);
 	console.log(`  jsonl.path: ${artifacts.jsonlPathFile}`);
 	console.log(`  jsonl:      ${artifacts.jsonlPath}`);
+	console.log(`  manifest:  ${artifacts.manifestPath}`);
 } catch (error) {
-	fail(error instanceof Error ? error.message : String(error));
+	const message = error instanceof Error ? error.message : String(error);
+	if (artifacts?.manifestPath) {
+		try {
+			writeVisualManifest(artifacts.manifestPath, options, artifacts, { message, writtenAt: new Date().toISOString() });
+		} catch {
+			// Preserve the original failure.
+		}
+	}
+	fail(message);
 }

package/shared/cursor-setting-sources.d.mts

@@ -1,4 +1,5 @@
 export declare const CURSOR_SETTING_SOURCES_ENV: "PI_CURSOR_SETTING_SOURCES";
+export declare const DEFAULT_CURSOR_SETTING_SOURCES: readonly string[];
 
 export declare function resolveCursorSettingSources(raw?: string): string[] | undefined;
 

package/shared/cursor-setting-sources.mjs

@@ -1,9 +1,10 @@
 /** Canonical Cursor settingSources parsing (parity-tested by provider runtime and maintainer scripts). */
 export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+export const DEFAULT_CURSOR_SETTING_SOURCES = Object.freeze(["all"]);
 
 export function resolveCursorSettingSources(raw) {
 	const trimmed = raw?.trim();
-	if (!trimmed) return ["all"];
+	if (!trimmed) return [...DEFAULT_CURSOR_SETTING_SOURCES];
 	const normalized = trimmed.toLowerCase();
 	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
 	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];

package/src/context.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
-import type { SDKImage } from "@cursor/sdk";
+import type { AgentModeOption, SDKImage } from "@cursor/sdk";
 import { getCursorReplayPromptLabel } from "./cursor-tool-presentation-registry.js";
 
 export interface CursorPrompt {
@@ -13,6 +13,7 @@ export interface CursorPromptOptions {
 	maxInputTokens?: number;
 	charsPerToken?: number;
 	imageTokenEstimate?: number;
+	agentMode?: AgentModeOption;
 	/** Compact callable-surface summary; included on bootstrap prompts when set. */
 	toolManifest?: string;
 }
@@ -21,35 +22,49 @@ export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
 export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
-export function getCursorToolTailGuardText(): string {
+export function getCursorPlanModeToolGuidanceText(agentMode: AgentModeOption | undefined): string | undefined {
+	if (agentMode !== "plan") return undefined;
+	return [
+		"Cursor SDK mode is plan for this run. In pi-cursor-sdk, plan mode may still use available Cursor SDK/MCP tools for inspection when needed.",
+		"Safe/read-only shell commands that inspect or print information are allowed when Cursor chooses to call Shell; do not say Shell is blocked by plan mode and then call it anyway.",
+		"Exposed pi__* bridge tools are also callable in plan mode when the user asks for them or they are needed to answer.",
+	].join("\n");
+}
+
+export function getCursorToolTailGuardText(
+	options: Pick<CursorPromptOptions, "agentMode"> & { includePlanModeGuidance?: boolean } = {},
+): string {
 	return [
 		"Shell: use an explicit `cd` to the repo path when running project commands; session cwd may not match paths in tool args.",
+		options.includePlanModeGuidance === false ? undefined : getCursorPlanModeToolGuidanceText(options.agentMode),
+		"Exact-output requests: if the latest user asks to reply exactly, output exactly that text and do not add preambles, diagnostics, or repo checks unless explicitly requested.",
 		"Tool boundary reminder: If a tool is needed, call an available Cursor SDK/MCP tool. Never print a tool card (for example Tool call/Shell/command) as assistant text.",
-	].join("\n");
+	].filter((line): line is string => line !== undefined).join("\n");
 }
 
-function getCursorToolBoundaryText(options: { hasToolManifest?: boolean } = {}): string {
+function getCursorToolBoundaryText(options: Pick<CursorPromptOptions, "agentMode"> & { hasToolManifest?: boolean } = {}): string {
 	const lines = [
 		"Cursor SDK tool boundary:",
 		"Call only tools exposed by Cursor SDK in this run. Pi tool names, replay labels, and transcript names are context only—not callable.",
 		"Bridged pi tools: call pi__* MCP names when exposed, not the pi card name in history. Replay activity is display-only.",
 		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor executes an equivalent tool.",
 		"Use pi__cursor_ask_question for material choices if exposed.",
+		getCursorPlanModeToolGuidanceText(options.agentMode),
 		"Images: only the latest user message's images are sent as bytes; ask to reattach or describe prior images.",
-	];
+	].filter((line): line is string => line !== undefined);
 	if (options.hasToolManifest) {
 		lines.push("See callable tool surfaces block below.");
 	}
 	return lines.join("\n");
 }
 
-function getCursorBootstrapTailSections(): string[] {
+function getCursorBootstrapTailSections(options: Pick<CursorPromptOptions, "agentMode"> = {}): string[] {
 	return [
 		[
 			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
 			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
 		].join("\n"),
-		getCursorToolTailGuardText(),
+		getCursorToolTailGuardText({ ...options, includePlanModeGuidance: false }),
 	];
 }
 
@@ -366,7 +381,7 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 	const parts = applyPromptBudget(
 		sectionsBeforeMessages,
 		latestUserMessageSections,
-		[getCursorToolTailGuardText()],
+		[getCursorToolTailGuardText(options)],
 		latestUserMessageIndex,
 		budgetOptions,
 	);
@@ -374,7 +389,7 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 }
 
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
-	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ hasToolManifest: Boolean(options.toolManifest) })];
+	const sectionsBeforeMessages: string[] = [getCursorToolBoundaryText({ agentMode: options.agentMode, hasToolManifest: Boolean(options.toolManifest) })];
 	if (options.toolManifest) {
 		sectionsBeforeMessages.push(options.toolManifest);
 	}
@@ -390,7 +405,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 			return text ? { index, text } : undefined;
 		})
 		.filter((section): section is { index: number; text: string } => section !== undefined);
-	const sectionsAfterMessages = getCursorBootstrapTailSections();
+	const sectionsAfterMessages = getCursorBootstrapTailSections(options);
 	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =

package/src/cursor-active-tools.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type CursorActiveToolApi = Pick<ExtensionAPI, "getActiveTools">;
+
+export function arePiToolsDisabled(pi: CursorActiveToolApi): boolean {
+	return pi.getActiveTools().length === 0;
+}

package/src/cursor-native-tool-display-registration.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { arePiToolsDisabled } from "./cursor-active-tools.js";
 import {
 	CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES,
 	isNativeCursorToolName,
@@ -13,6 +14,7 @@ import {
 	NATIVE_CURSOR_TOOL_DISPLAY_ENV,
 	readBooleanEnv,
 	registeredNativeToolNames,
+	setCursorNativeToolDisplayRuntimeRequested,
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
@@ -70,37 +72,41 @@ function hasAttemptedNativeCursorToolRegistration(): boolean {
 	return registeredNativeToolNames.size > 0 || skippedNativeToolNames.size > 0;
 }
 
+function removeRegisteredNonCoreNativeCursorTools(pi: CursorNativeToolActivationApi): void {
+	if (registeredNativeToolNames.size === 0) return;
+	const activeToolNames = new Set(pi.getActiveTools());
+	let changed = false;
+	for (const toolName of registeredNativeToolNames) {
+		if (isCursorCorePiReplayToolName(toolName)) continue;
+		if (!activeToolNames.delete(toolName)) continue;
+		changed = true;
+	}
+	if (changed) pi.setActiveTools([...activeToolNames]);
+}
+
 export function syncRegisteredNativeCursorToolsForModel(
 	pi: CursorNativeToolActivationApi,
 	model: ExtensionContext["model"],
 ): void {
 	if (registeredNativeToolNames.size === 0) return;
+	if (!isCursorModel(model)) {
+		removeRegisteredNonCoreNativeCursorTools(pi);
+		return;
+	}
+	if (arePiToolsDisabled(pi)) return;
 	const activeToolNames = new Set(pi.getActiveTools());
 	let changed = false;
-	if (isCursorModel(model)) {
-		for (const toolName of registeredNativeToolNames) {
-			if (isCursorReplayToolName(toolName) && !CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES.some((activeReplayToolName) => activeReplayToolName === toolName)) continue;
-			if (activeToolNames.has(toolName)) continue;
-			activeToolNames.add(toolName);
-			changed = true;
-		}
-	} else {
-		for (const toolName of registeredNativeToolNames) {
-			if (isCursorCorePiReplayToolName(toolName)) continue;
-			if (!activeToolNames.delete(toolName)) continue;
-			changed = true;
-		}
+	for (const toolName of registeredNativeToolNames) {
+		if (isCursorReplayToolName(toolName) && !CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES.some((activeReplayToolName) => activeReplayToolName === toolName)) continue;
+		if (activeToolNames.has(toolName)) continue;
+		activeToolNames.add(toolName);
+		changed = true;
 	}
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
 async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
-	if (!isCursorNativeToolRegistrationRequested()) {
-		registeredNativeToolNames.clear();
-		skippedNativeToolNames.clear();
-		return;
-	}
-	if (ctx.mode !== "tui" || !isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
+	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
@@ -111,9 +117,13 @@ async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolReg
 }
 
 async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
-	if (isCursorModel(ctx.model) && !hasAttemptedNativeCursorToolRegistration()) {
-		await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+	const requested = isCursorNativeToolRegistrationRequested(ctx.mode);
+	setCursorNativeToolDisplayRuntimeRequested(requested);
+	if (!requested) {
+		removeRegisteredNonCoreNativeCursorTools(pi);
+		return;
 	}
+	await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 

package/src/cursor-native-tool-display-state.ts

@@ -13,18 +13,25 @@ export const registeredNativeToolNames = new Set<string>();
 export const skippedNativeToolNames = new Set<string>();
 export const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
 
+let nativeToolDisplayRuntimeRequested = false;
+
 export function readBooleanEnv(name: string, env: Record<string, string | undefined> = process.env): boolean | undefined {
 	return parseOptionalEnvBoolean(env[name]);
 }
 
-export function isCursorNativeToolDisplayRequested(): boolean {
+export function isCursorNativeToolDisplayRequested(mode?: string): boolean {
 	const override = readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV);
 	if (override !== undefined) return override;
+	if (mode) return mode === "tui" || mode === "json" || mode === "rpc";
 	return process.stdout.isTTY === true;
 }
 
-export function isCursorNativeToolRegistrationRequested(): boolean {
-	return readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) !== false && isCursorNativeToolDisplayRequested();
+export function isCursorNativeToolRegistrationRequested(mode?: string): boolean {
+	return mode !== "print" && readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) !== false && isCursorNativeToolDisplayRequested(mode);
+}
+
+export function setCursorNativeToolDisplayRuntimeRequested(requested: boolean): void {
+	nativeToolDisplayRuntimeRequested = requested;
 }
 
 export function isCursorNativeToolDisplayEnabled(): boolean {
@@ -32,7 +39,7 @@ export function isCursorNativeToolDisplayEnabled(): boolean {
 }
 
 export function isCursorNativeToolDisplayRuntimeEnabled(): boolean {
-	return isCursorNativeToolDisplayRequested() && registeredNativeToolNames.size > 0;
+	return nativeToolDisplayRuntimeRequested && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) !== false && registeredNativeToolNames.size > 0;
 }
 
 export function canRenderCursorToolNatively(toolName: string): boolean {
@@ -70,9 +77,11 @@ export function isCursorFileMutationToolName(toolName: string): toolName is "edi
 export const __testUtils = {
 	nativeToolResultCount: () => nativeToolResults.size,
 	registerNativeToolNameForTests(toolName: string): void {
+		nativeToolDisplayRuntimeRequested = true;
 		registeredNativeToolNames.add(toolName);
 	},
 	reset(): void {
+		nativeToolDisplayRuntimeRequested = false;
 		registeredNativeToolNames.clear();
 		skippedNativeToolNames.clear();
 		nativeToolResults.clear();

package/src/cursor-pi-tool-bridge-run.ts

@@ -150,7 +150,8 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.debugRecorder = recorder;
 	}
 
-	resolveToolResults(toolResults: readonly ToolResultMessage[]): void {
+	async resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void> {
+		let resolvedCount = 0;
 		for (const toolResult of toolResults) {
 			const pending = this.pendingByPiToolCallId.get(toolResult.toolCallId);
 			if (!pending || pending.settled) continue;
@@ -158,11 +159,13 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 				content: convertPiContentToMcpContent(toolResult.content),
 				isError: toolResult.isError || undefined,
 			});
+			resolvedCount += 1;
 		}
+		if (resolvedCount > 0) await waitForProtocolFlush();
 	}
 
-	resolveToolResultsFromContext(context: Context): void {
-		this.resolveToolResults(context.messages.map(asToolResultMessage).filter((message): message is ToolResultMessage => message !== undefined));
+	async resolveToolResultsFromContext(context: Context): Promise<void> {
+		await this.resolveToolResults(context.messages.map(asToolResultMessage).filter((message): message is ToolResultMessage => message !== undefined));
 	}
 
 	hasPendingPiToolCallId(piToolCallId: string): boolean {

package/src/cursor-pi-tool-bridge-types.ts

@@ -61,8 +61,8 @@ export interface CursorPiToolBridgeRun {
 	mcpServers?: Record<string, McpServerConfig>;
 	snapshot: CursorPiToolBridgeSnapshot;
 	takeQueuedToolRequests(): CursorPiBridgeToolRequest[];
-	resolveToolResults(toolResults: readonly ToolResultMessage[]): void;
-	resolveToolResultsFromContext(context: Context): void;
+	resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void>;
+	resolveToolResultsFromContext(context: Context): Promise<void>;
 	hasPendingPiToolCallId(piToolCallId: string): boolean;
 	isBridgeMcpToolCall(toolCall: unknown): boolean;
 	setOnToolRequest(handler?: (request: CursorPiBridgeToolRequest) => void): void;

package/src/cursor-provider-errors.ts

@@ -15,7 +15,7 @@ const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
 // Keep this phrase aligned with pi's agent-level retry classifier (`provider.?returned.?error`).
 const RETRYABLE_CURSOR_RUN_FAILURE_PREFIX = "Provider returned error: Cursor SDK run failed";
 
-export type CursorSdkRunFailureSource = Pick<RunResult, "id" | "status" | "durationMs" | "model" | "result">;
+export type CursorSdkRunFailureSource = Pick<RunResult, "id" | "requestId" | "status" | "durationMs" | "model" | "result">;
 
 function isGenericErrorMessage(message: string): boolean {
 	const normalized = message.trim().toLowerCase();
@@ -159,6 +159,7 @@ export function formatCursorSdkRunFailureDetail(result: CursorSdkRunFailureSourc
 	const parts = [RETRYABLE_CURSOR_RUN_FAILURE_PREFIX];
 	if (result.model?.id) parts.push(`model ${result.model.id}`);
 	parts.push(`run ${shortRunId(result.id)}`);
+	if (result.requestId) parts.push(`request ${shortRunId(result.requestId)}`);
 	if (typeof result.durationMs === "number") parts.push(`${result.durationMs}ms`);
 	return parts.join(" · ");
 }

package/src/cursor-provider-live-run-drain.ts

@@ -414,7 +414,7 @@ export async function drainExistingCursorLiveRunBeforeSend(
 			const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
 				if (run.disposed) return "continue_send" as const;
 				const consumed = cursorLiveRuns.consumeToolResults(run, context, getCursorNativeReplayIdFromToolCallId);
-				run.bridgeRun?.resolveToolResults(consumed.toolResults);
+				await run.bridgeRun?.resolveToolResults(consumed.toolResults);
 				const shouldChainUserInput = run.chainUserInputAfterCompletion || hasTrailingUserMessagesAfterToolResults(context);
 				if (shouldChainUserInput) run.chainUserInputAfterCompletion = true;
 				while (!cursorLiveRuns.isReady(run)) {

package/src/cursor-provider-turn-prepare.ts

@@ -89,7 +89,7 @@ export async function prepareCursorProviderTurn(
 		throwIfAborted();
 
 		const buildPromptOptions = (plan: ReturnType<typeof planCursorSessionSend>) => {
-			const promptOptions = getCursorPromptOptions(model);
+			const promptOptions = { ...getCursorPromptOptions(model), agentMode };
 			if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
 				return promptOptions;
 			}

package/src/cursor-provider-turn-send.ts

@@ -78,12 +78,14 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 		sdkRun = run;
 		sdkEventDebug?.recordRunMeta({
 			runId: run.id,
+			requestId: run.requestId,
 			agentId: run.agentId,
 			status: run.status,
 		});
 		sdkEventDebug?.attachRunStream(run);
 		sdkEventDebug?.recordProviderEvent("agent_send_returned", {
 			runId: run.id,
+			requestId: run.requestId,
 			agentId: run.agentId,
 			status: run.status,
 		});