pi-cursor-sdk 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "pi provider extension backed by @cursor/sdk local and cloud agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
@@ -103,6 +103,8 @@
     "scripts/lib/cursor-sdk-output-filter.d.mts",
     "scripts/lib/ensure-built.mjs",
     "README.md",
+    "docs/reference.md",
+    "docs/development.md",
     "docs/cursor-model-ux-spec.md",
     "docs/cursor-tool-surfaces.md",
     "docs/cursor-live-smoke-checklist.md",
@@ -181,9 +183,9 @@
   },
   "devDependencies": {
     "@connectrpc/connect": "2.2.0",
-    "@earendil-works/pi-ai": "1.0.4",
-    "@earendil-works/pi-coding-agent": "1.0.4",
-    "@earendil-works/pi-tui": "1.0.4",
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@types/node": "24.19.1",
     "@typescript/typescript6": "6.0.2",

package/scripts/platform-smoke/artifact-secrets.mjs

@@ -4,7 +4,7 @@
 
 import { isUtf8 } from "node:buffer";
 import { TextDecoder } from "node:util";
-import { scrubSensitiveText } from "../../shared/cursor-sensitive-text.mjs";
+import { hasCredentialUrlMarkers, scrubSensitiveText } from "../../shared/cursor-sensitive-text.mjs";
 
 export const SECRET_PATTERNS = [
 	[/Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "Authorization header", "Authorization: Bearer [REDACTED_BEARER_TOKEN]"],
@@ -16,6 +16,10 @@ export const SECRET_PATTERNS = [
 	[/\b[^\s/:@]+:[^\s/]+@(?=[A-Za-z0-9.-]+(?::|\/|\s|$))/g, "credential-bearing SCP URL", "[REDACTED_CREDENTIAL_URL]"],
 ];
 
+function isCredentialUrlPattern(label) {
+	return label === "credential-bearing URL" || label === "credential-bearing SCP URL";
+}
+
 const AUTH_ASSIGNMENT_PATTERN = /(?:^|[^A-Za-z0-9_$])(?:authorization|api[_-]?key|apiKey|access[_-]?token|refresh[_-]?token|token)["']?\s*[:=]\s*/gim;
 const UNQUOTED_SECRET_CHARACTER = /^[A-Za-z0-9._~+/=-]$/;
 
@@ -65,7 +69,11 @@ export function redactSecrets(text) {
 	if (cursorKey && cursorKey.length > 10) {
 		redacted = redacted.split(cursorKey).join("[REDACTED_CURSOR_API_KEY]");
 	}
-	for (const [pattern, , replacement] of SECRET_PATTERNS) {
+	const credentialUrlPossible = hasCredentialUrlMarkers(redacted);
+	for (const [pattern, label, replacement] of SECRET_PATTERNS) {
+		// Global String.replace reset this state even on an impossible match.
+		pattern.lastIndex = 0;
+		if (!credentialUrlPossible && isCredentialUrlPattern(label)) continue;
 		redacted = redacted.replace(pattern, replacement);
 	}
 	return redacted;
@@ -195,13 +203,14 @@ export function scanForSecrets(value) {
 	)) {
 		violations.add("CURSOR_API_KEY literal found");
 	}
-	const patterns = SECRET_PATTERNS.filter(([, label]) =>
-		!binary || (label !== "credential-bearing URL" && label !== "credential-bearing SCP URL"));
+	const patterns = SECRET_PATTERNS.filter(([, label]) => !binary || !isCredentialUrlPattern(label));
 	const texts = buffer ? (binary ? binaryTextCandidates(buffer) : [buffer.toString("utf8")]) : [plainText];
 	for (const text of texts) {
 		if (authAssignmentSecretRanges(text).length > 0) violations.add("potential auth/token assignment");
+		const credentialUrlPossible = hasCredentialUrlMarkers(text);
 		for (const [pattern, label] of patterns) {
 			pattern.lastIndex = 0;
+			if (!credentialUrlPossible && isCredentialUrlPattern(label)) continue;
 			if (pattern.test(text)) violations.add(`potential ${label}`);
 		}
 	}

package/scripts/platform-smoke/local-resume-runner.mjs

@@ -74,7 +74,6 @@ export async function executeLocalResumeSuite(
 			shell: true,
 			timeout: 900_000,
 			allowEnv: ["CURSOR_API_KEY"],
-			captureStdoutPath: resolve(suiteDir, ".crabbox.remote.stdout.raw"),
 			sync: leaseSession?.sync,
 			config,
 		},

package/scripts/platform-smoke/target-runtime.mjs

@@ -87,6 +87,7 @@ export function stopLeaseCheck(stopResult) {
 	};
 }
 
+/** Runs a suite command with Crabbox's full-stdout capture under suiteDir, retrying one transient SSH failure without sync. */
 export async function runOnLeaseWithTransientRetry(
 	suiteDir,
 	targetName,
@@ -95,7 +96,8 @@ export async function runOnLeaseWithTransientRetry(
 	options,
 	run = runOnLease,
 ) {
-	const first = await run(targetName, leaseId, command, options);
+	const captured = { ...options, captureStdoutPath: resolve(suiteDir, ".crabbox.remote.stdout.raw") };
+	const first = await run(targetName, leaseId, command, captured);
 	if (!isTransientCrabboxSshFailure(first)) return first;
 	writeRedactedFile(
 		resolve(suiteDir, "crabbox.retry1.stdout.txt"),
@@ -106,7 +108,7 @@ export async function runOnLeaseWithTransientRetry(
 		first.stderr,
 	);
 	await new Promise((resolveRetry) => setTimeout(resolveRetry, 10_000));
-	return await run(targetName, leaseId, command, { ...options, sync: false });
+	return await run(targetName, leaseId, command, { ...captured, sync: false });
 }
 
 const ARTIFACT_CHUNK_BYTES = 32 * 1024;

package/scripts/platform-smoke/targets.mjs

@@ -501,7 +501,6 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 		shell: true,
 		timeout: 900_000,
 		allowEnv: ["CURSOR_API_KEY"],
-		captureStdoutPath: resolve(suiteDir, ".crabbox.remote.stdout.raw"),
 		sync: leaseSession?.sync,
 		config,
 	});

package/shared/cursor-sdk-output-filter.d.mts

@@ -6,3 +6,5 @@ export declare function suppressCursorSdkOutput<T>(operation: () => T): T;
 export declare function withCursorSdkOutputNoticeHandler<T>(handler: CursorSdkOutputNoticeHandler | undefined, operation: () => T): T;
 export declare function isCursorSdkStartupNoise(text: string): boolean;
 export declare function installCursorSdkOutputFilter(): () => void;
+export declare function installCursorSdkProcessOutputFilter(): void;
+export declare const __testUtils: { resetProcessOutputFilter(): void };

package/shared/cursor-sdk-output-filter.mjs

@@ -3,13 +3,26 @@ import { isUtf8 } from "node:buffer";
 import { StringDecoder } from "node:string_decoder";
 import { stripVTControlCharacters } from "node:util";
 
-const cursorSdkOutputSuppression = new AsyncLocalStorage();
-const noticeOwner = new AsyncLocalStorage();
+// Pi can reevaluate extension dependencies during reload. Share both the sink
+// ownership and async attribution scopes, not just a permanent-install flag.
+const STATE = Symbol.for("pi-cursor-sdk:output-filter:v1");
+const state = process[STATE] ??= {
+	suppression: new AsyncLocalStorage(), noticeOwner: new AsyncLocalStorage(),
+	installs: 0, originals: undefined, sinks: undefined, processCleanup: undefined,
+};
+const cursorSdkOutputSuppression = state.suppression;
+const noticeOwner = state.noticeOwner;
 // ponytail: larger frames pass unchanged. Raise this cap for a captured larger
 // SDK frame, or use a public SDK sink when unbounded suppression is required.
 const MAX_CANDIDATE_BYTES = 16 * 1024;
 const PARSER_WARNING = "shell-parser: tree-sitter natives are unavailable in this artifact; shell command analysis degrades to parsingFailed";
 const PLUGIN_PREFIX = "[local-plugins-bootstrap] loadUserLocalPlugin ";
+// Fixed compatibility notices remain exact. Only the event name varies in
+// these two verified SDK templates; unrelated [hooks] warnings must pass.
+const HOOK_EVENT_NOTICES = [
+	{ prefix: '[hooks] Unknown Claude Code event "', suffix: '", skipping' },
+	{ prefix: '[hooks] Claude Code event "', suffix: '" is not supported in Cursor and will be ignored' },
+];
 const HOOK_NOTICES = [
 	...["startup", "resume", "clear", "compact"].map(trigger => `[hooks] SessionStart trigger matcher "${trigger}" is not supported in Cursor, hooks will fire for all triggers`),
 	...["manual", "auto"].map(trigger => `[hooks] PreCompact trigger matcher "${trigger}" is not supported in Cursor, hooks will fire for all triggers`),
@@ -30,11 +43,26 @@ const CURSOR_SDK_CAPABILITY_NOTICES = {
 };
 
 export function isCursorSdkOutputSuppressed() {
-	return cursorSdkOutputSuppression.getStore() === true;
+	return cursorSdkOutputSuppression.getStore()?.active === true;
 }
 
 export function suppressCursorSdkOutput(operation) {
-	return cursorSdkOutputSuppression.run(true, operation);
+	// Detached SDK tasks inherit ALS, but must not inherit an unbounded mute
+	// after Agent.create() settles. Only known frames stay hidden afterward.
+	const scope = { active: true };
+	return cursorSdkOutputSuppression.run(scope, () => {
+		try {
+			const result = operation();
+			if (result && typeof result.then === "function") {
+				return Promise.resolve(result).finally(() => { scope.active = false; });
+			}
+			scope.active = false;
+			return result;
+		} catch (error) {
+			scope.active = false;
+			throw error;
+		}
+	});
 }
 
 /** Attribution follows the request's async work, including overlapping native sessions. */
@@ -42,12 +70,24 @@ export function withCursorSdkOutputNoticeHandler(handler, operation) {
 	return noticeOwner.run(handler, operation);
 }
 
+function hookEventNotice(line, partial = false) {
+	return HOOK_EVENT_NOTICES.some(({ prefix, suffix }) => {
+		if (partial && prefix.startsWith(line)) return true;
+		if (!line.startsWith(prefix)) return false;
+		const rest = line.slice(prefix.length), quote = rest.indexOf('"');
+		if (quote < 0) return partial && !/[\r\n]/.test(rest);
+		if (quote === 0 || /[\r\n]/.test(rest.slice(0, quote))) return false;
+		const ending = rest.slice(quote);
+		return partial ? suffix.startsWith(ending) || ending === `${suffix}\r` : ending === suffix;
+	});
+}
+
 function classify(text) {
 	if (text.replace(/\x1b\[[\d;]*m/g, "").includes("\x1b")) return;
 	const line = stripVTControlCharacters(text).replace(/\r?\n$/, "");
 	if (line === PARSER_WARNING) return "parserUnavailable";
 	if (/^\[local-plugins-bootstrap\] loadUserLocalPlugin [^\r\n]+ rejected: symlink target [^\r\n]+ is outside [^\r\n]+(?: \{[^\r\n]*\})?$/.test(line)) return "outsidePlugin";
-	if (HOOK_NOTICES.includes(line)) return "noise";
+	if (HOOK_NOTICES.includes(line) || hookEventNotice(line)) return "noise";
 	const info = /^(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d\.\d{3} INFO  (.+?)(?: ctx=[^\s]+)?(?: meta=\{[^\r\n]*\})?$/.exec(line);
 	if (info && CURSOR_SDK_STARTUP_NOISE_PATTERNS.includes(info[1])) return "noise";
 }
@@ -64,7 +104,7 @@ function possibleDiagnostic(text) {
 	const plain = stripVTControlCharacters(withoutSgr.replace(/\x1b(?:\[[\d;]*)?$/, ""));
 	if (withoutSgr.includes("\x1b") && !/\x1b(?:\[[\d;]*)?$/.test(withoutSgr)) return false;
 	if (!plain) return true;
-	if (HOOK_NOTICES.some(prefix => prefix.startsWith(plain) || plain === `${prefix}\r`)) return true;
+	if (HOOK_NOTICES.some(prefix => prefix.startsWith(plain) || plain === `${prefix}\r`) || hookEventNotice(plain, true)) return true;
 	if (PARSER_WARNING.startsWith(plain) || plain === `${PARSER_WARNING}\r`) return true;
 	if (PLUGIN_PREFIX.startsWith(plain) || plain.startsWith(PLUGIN_PREFIX)) return true;
 	const timestamp = "00:00:00.000 INFO  ";
@@ -121,39 +161,63 @@ function createFilteredProcessWrite(write, stream) {
 		if (done) process.nextTick(done);
 		return true;
 	};
+	function flush() {
+		const output = [];
+		if (size) finish(output);
+		if (output.length) write.call(stream, Buffer.concat(output));
+	}
 	return {
 		write: filteredWrite,
-		restore() {
-			active = false;
-			const output = [];
-			if (size) finish(output);
-			if (output.length) write.call(stream, Buffer.concat(output));
-		},
+		flush,
+		restore() { active = false; flush(); },
 	};
 }
 
-let activeOutputFilterInstalls = 0;
-let outputFilterOriginals;
-let sinks;
-
 export function installCursorSdkOutputFilter() {
-	if (activeOutputFilterInstalls === 0) {
-		outputFilterOriginals = { stdoutWrite: process.stdout.write, stderrWrite: process.stderr.write };
-		sinks = [createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout), createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr)];
-		process.stdout.write = sinks[0].write;
-		process.stderr.write = sinks[1].write;
+	if (state.installs === 0) {
+		state.originals = { stdoutWrite: process.stdout.write, stderrWrite: process.stderr.write };
+		state.sinks = [createFilteredProcessWrite(state.originals.stdoutWrite, process.stdout), createFilteredProcessWrite(state.originals.stderrWrite, process.stderr)];
+		process.stdout.write = state.sinks[0].write;
+		process.stderr.write = state.sinks[1].write;
 	}
-	activeOutputFilterInstalls += 1;
+	state.installs += 1;
 	let restored = false;
 	return () => {
 		if (restored) return;
 		restored = true;
-		activeOutputFilterInstalls -= 1;
-		if (activeOutputFilterInstalls > 0) return;
-		process.stdout.write = outputFilterOriginals.stdoutWrite;
-		process.stderr.write = outputFilterOriginals.stderrWrite;
-		const finishing = sinks;
-		sinks = outputFilterOriginals = undefined;
+		state.installs -= 1;
+		if (state.installs > 0) return;
+		// A later owner may wrap our write method. Keep its wrapper installed;
+		// retained filter methods become transparent delegates on restoration.
+		if (process.stdout.write === state.sinks[0].write) process.stdout.write = state.originals.stdoutWrite;
+		if (process.stderr.write === state.sinks[1].write) process.stderr.write = state.originals.stderrWrite;
+		const finishing = state.sinks;
+		state.sinks = state.originals = undefined;
 		for (const sink of finishing) sink.restore();
 	};
 }
+
+/** One narrow, process-lifetime lease survives reload, removal and failed reload. */
+export function installCursorSdkProcessOutputFilter() {
+	if (state.processCleanup) return;
+	const restore = installCursorSdkOutputFilter();
+	const flush = () => { for (const sink of state.sinks ?? []) sink.flush(); };
+	const cleanup = () => {
+		if (state.processCleanup !== cleanup) return;
+		state.processCleanup = undefined;
+		process.off("beforeExit", flush);
+		process.off("exit", onExit);
+		restore();
+	};
+	const onExit = () => { flush(); cleanup(); };
+	state.processCleanup = cleanup;
+	// beforeExit may schedule more work: keep filtering until actual exit,
+	// which flushes even when temporary owners still retain their leases.
+	process.on("beforeExit", flush);
+	process.once("exit", onExit);
+}
+
+// Canonical harness cleanup only; production owns this lease until process exit.
+export const __testUtils = {
+	resetProcessOutputFilter() { state.processCleanup?.(); },
+};

package/shared/cursor-sensitive-text.d.mts

@@ -1 +1,2 @@
+export declare function hasCredentialUrlMarkers(text: string): boolean;
 export declare function scrubSensitiveText(text: string, apiKey?: string): string;

package/shared/cursor-sensitive-text.mjs

@@ -9,7 +9,14 @@ 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`;
 
+/** Necessary markers only, not credential validation. Skip impossible regex
+ * no-matches when either marker is absent; both-marker inputs remain unbounded. */
+export function hasCredentialUrlMarkers(text) {
+	return text.includes("@") && text.includes(":");
+}
+
 function scrubUrlUserInfo(text) {
+	if (!hasCredentialUrlMarkers(text)) return text;
 	return text
 		.replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#]*@(?=[^\s/?#]+)/gi, "$1[redacted]@")
 		.replace(/\b[^\s/:@]+:[^\s/]+@(?=[A-Za-z0-9.-]+(?::|\/|\s|$))/g, "[redacted]@");

package/src/context.ts

@@ -20,6 +20,7 @@ export interface CursorPromptOptions {
 	agentMode?: AgentModeOption;
 	/** Compact callable-surface summary; included on bootstrap prompts when set. */
 	toolManifest?: string;
+	nativeToolsEnabled?: boolean;
 	includePiBridgeGuidance?: boolean;
 	includePiAskQuestionGuidance?: boolean;
 }
@@ -30,12 +31,14 @@ const SECTION_SEPARATOR = "\n\n";
 
 export function getCursorPlanModeToolGuidanceText(
 	agentMode: AgentModeOption | undefined,
-	options: { includePiBridgeGuidance?: boolean } = {},
+	options: { includePiBridgeGuidance?: boolean; nativeToolsEnabled?: boolean } = {},
 ): 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.",
+		options.nativeToolsEnabled === false
+			? "Only MCP tools exposed in this run are callable; native Shell and task/subagents are disabled."
+			: "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.",
 		options.includePiBridgeGuidance === false
 			? undefined
 			: "Exposed pi__* bridge tools are also callable in plan mode when the user asks for them or they are needed to answer.",
@@ -43,34 +46,37 @@ export function getCursorPlanModeToolGuidanceText(
 }
 
 export function getCursorToolTailGuardText(
-	options: Pick<CursorPromptOptions, "agentMode"> & { includePlanModeGuidance?: boolean; includePiBridgeGuidance?: boolean } = {},
+	options: Pick<CursorPromptOptions, "agentMode" | "nativeToolsEnabled"> & { includePlanModeGuidance?: boolean; includePiBridgeGuidance?: boolean } = {},
 ): string {
 	return [
-		"Shell: use explicit `cd` to repo path for project commands; session cwd may differ from tool args.",
+		options.nativeToolsEnabled === false ? undefined : "Shell: use explicit `cd` to repo path for project commands; session cwd may differ from tool args.",
 		options.includePlanModeGuidance === false
 			? undefined
-			: getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance: options.includePiBridgeGuidance }),
+			: getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance: options.includePiBridgeGuidance, nativeToolsEnabled: options.nativeToolsEnabled }),
 		"Exact-output requests: output exactly the requested text; no preamble or checks unless asked.",
 		"Tools: call available Cursor SDK/MCP tools; never print tool cards as assistant text.",
 		"Do not comment on GitHub issues or PRs unless the user asked.",
-		options.includePiBridgeGuidance === false ? undefined : CURSOR_PI_BRIDGE_PREFERENCE_TEXT,
+		options.includePiBridgeGuidance === false ? undefined : options.nativeToolsEnabled === false
+			? "Use only exposed pi__* MCP names for Pi work; native task/subagents are disabled."
+			: CURSOR_PI_BRIDGE_PREFERENCE_TEXT,
 	].filter((line): line is string => line !== undefined).join("\n");
 }
 
 function getCursorToolBoundaryText(
-	options: Pick<CursorPromptOptions, "agentMode" | "includePiAskQuestionGuidance"> & { hasToolManifest?: boolean; includePiBridgeGuidance?: boolean } = {},
+	options: Pick<CursorPromptOptions, "agentMode" | "includePiAskQuestionGuidance" | "nativeToolsEnabled"> & { hasToolManifest?: boolean; includePiBridgeGuidance?: boolean } = {},
 ): string {
 	const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
 	const includePiAskQuestionGuidance = includePiBridgeGuidance && options.includePiAskQuestionGuidance === true;
 	const lines = [
 		"Cursor SDK tool boundary:",
 		"Call only Cursor SDK/MCP tools exposed in this run; pi history names, replay labels, and transcript names are not callable.",
+		options.nativeToolsEnabled === false ? "Cursor native tools (including task/subagents): disabled. Only exposed MCP tools are callable." : undefined,
 		includePiBridgeGuidance
 			? "For exposed pi bridge tools, call pi__* MCP names, not pi card/history names."
 			: undefined,
 		"Do not claim pi-side or WebSearch/WebFetch tools unless Cursor ran an equivalent tool.",
 		includePiAskQuestionGuidance ? "Use pi__cursor_ask_question only if the user asked to be prompted." : undefined,
-		getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance }),
+		getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance, nativeToolsEnabled: options.nativeToolsEnabled }),
 		"Images: only latest user images are sent; ask to reattach prior images.",
 	].filter((line): line is string => line !== undefined);
 	if (options.hasToolManifest) {
@@ -80,7 +86,7 @@ function getCursorToolBoundaryText(
 }
 
 function getCursorBootstrapTailSections(
-	options: Pick<CursorPromptOptions, "agentMode" | "includePiBridgeGuidance">,
+	options: Pick<CursorPromptOptions, "agentMode" | "includePiBridgeGuidance" | "nativeToolsEnabled">,
 	hasNewNativeUser = true,
 ): string[] {
 	return [
@@ -462,6 +468,7 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		agentMode: options.agentMode,
 		hasToolManifest: Boolean(options.toolManifest),
 		includePiBridgeGuidance: options.includePiBridgeGuidance,
+		nativeToolsEnabled: options.nativeToolsEnabled,
 		includePiAskQuestionGuidance: options.includePiAskQuestionGuidance,
 	})];
 	if (options.toolManifest) {

package/src/cursor-agents-context.ts

@@ -40,7 +40,7 @@ export type PiAgentsContextOverlap = "none" | "cursor-user-agents" | "cursor-pro
 /** Pi context filenames that can overlap Cursor project/user ambient rules. */
 const CURSOR_OVERLAPPING_CONTEXT_BASE_NAMES = new Set(["agents.md", "claude.md"]);
 
-export function getAgentsContextFileBaseName(filePath: string): string {
+function getAgentsContextFileBaseName(filePath: string): string {
 	const normalized = normalizeContextPath(filePath);
 	return normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
 }
@@ -56,12 +56,12 @@ function isPiAgentDirContextFilePath(
 }
 
 /** Actual pi agent dir `AGENTS.md` — overlaps Cursor `user` setting source (global agent instructions). */
-export function isPiAgentDirAgentsMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
+function isPiAgentDirAgentsMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
 	return isPiAgentDirContextFilePath(filePath, "agents.md", agentDir);
 }
 
 /** Actual pi agent dir `CLAUDE.md` — kept because Cursor user rules use `~/.claude/CLAUDE.md`. */
-export function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
+function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
 	return isPiAgentDirContextFilePath(filePath, "claude.md", agentDir);
 }
 
@@ -71,7 +71,7 @@ export function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = ge
  * Only the actual pi agent dir `AGENTS.md` overlaps Cursor `user`; agent-dir `CLAUDE.md` is kept
  * because Cursor user rules use `~/.claude/CLAUDE.md`, not pi's agent dir path.
  */
-export function classifyContextFileOverlap(
+function classifyContextFileOverlap(
 	filePath: string,
 	agentDir: string = getAgentDir(),
 ): PiAgentsContextOverlap {
@@ -82,7 +82,7 @@ export function classifyContextFileOverlap(
 	return "cursor-project-rules";
 }
 
-export function shouldRemovePiAgentsContextFile(
+function shouldRemovePiAgentsContextFile(
 	file: PiAgentsContextFile,
 	settingSources: SettingSource[] | undefined,
 	agentDir?: string,
@@ -97,7 +97,7 @@ export function shouldRemovePiAgentsContextFile(
 	}
 }
 
-export function shouldSuppressPiAgentsContext(
+function shouldSuppressPiAgentsContext(
 	model: ExtensionContext["model"],
 	contextFiles: readonly PiAgentsContextFile[],
 	settingSources: SettingSource[] | undefined,

package/src/cursor-api-key.ts

@@ -4,7 +4,7 @@ import { parseEnvBoolean } from "./cursor-env-boolean.js";
 export const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
 
 // Legacy no-auth availability policy only; never a configured models.json key.
-export const CURSOR_API_KEY_CONFIG_VALUE = "pi-cursor-sdk-cursor-api-key-placeholder";
+const CURSOR_API_KEY_CONFIG_VALUE = "pi-cursor-sdk-cursor-api-key-placeholder";
 
 const CURSOR_API_KEY_PLACEHOLDERS = new Set([
 	CURSOR_API_KEY_ENV_VAR,

package/src/cursor-bridge-contract.ts

@@ -1,20 +1,6 @@
 export const CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX = "pi__";
 export const CURSOR_PI_BRIDGE_PREFERENCE_TEXT =
-	"When exposed, prefer pi__mcp for MCP work and pi__subagent for delegation; use Cursor-configured MCP or Cursor-native subagents only when the matching pi__ tool is not exposed or unavailable.";
-
-const CURSOR_PI_BRIDGE_CONTRACT_LINES = [
-	"Pi bridge contract:",
-	`${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* names are live Cursor MCP bridge tool names only when exposed in the current run.`,
-	`Call the ${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* MCP tool name, not the real pi tool name shown in pi history or transcripts.`,
-	CURSOR_PI_BRIDGE_PREFERENCE_TEXT,
-	"Bridged calls execute through normal pi tool flow, so pi shows the real pi tool name and returns a normal pi tool result.",
-	"Replay IDs, replay labels, and transcript tool names are display-only/context-only, not callable tools.",
-	"Cursor-native host tools, settings, plugins, and configured MCP servers are separate from the pi bridge.",
-] as const;
-
-export function getCursorPiBridgeContractText(): string {
-	return CURSOR_PI_BRIDGE_CONTRACT_LINES.join("\n");
-}
+	"For MCP work and delegation, prefer matching exposed pi__* tools using their listed names, schemas, and prompt guidelines; use Cursor-configured MCP or Cursor-native subagents only when the matching pi tool is not exposed or unavailable.";
 
 function formatPromptGuidelines(promptGuidelines: readonly string[] | undefined): string | undefined {
 	const guidelines = promptGuidelines?.map((guideline) => guideline.trim()).filter(Boolean) ?? [];

package/src/cursor-cloud-local-state.ts

@@ -532,5 +532,3 @@ export function inspectCursorCloudLocalState(
 	}
 	return { insideGitRepo: true, dirty: dirty as boolean, comparison: aheadCount > 0 ? "unpushed" : "contains_head" };
 }
-
-export const __testUtils = { sourceForDestination };

package/src/cursor-config.ts

@@ -363,7 +363,7 @@ function readCursorSdkConfigFile(path: string): CursorSdkConfig {
 	}
 }
 
-export function loadCursorSdkConfigForUpdate(path: string): Record<string, unknown> {
+function loadCursorSdkConfigForUpdate(path: string): Record<string, unknown> {
 	if (!existsSync(path)) return {};
 	let source: string;
 	try {
@@ -476,19 +476,6 @@ export function updateCursorSdkConfig(
 	});
 }
 
-export function saveCursorSdkUserConfig(config: CursorSdkConfig, path = getCursorSdkUserConfigPath()): void {
-	updateCursorSdkConfig(path, () => ({ ...config }), { newFileMode: 0o600 });
-}
-
-export function saveCursorSdkProjectConfig(cwd: string, config: CursorSdkConfig, configDirName = CONFIG_DIR_NAME): void {
-	const path = getCursorSdkProjectConfigPath(cwd, configDirName);
-	updateCursorSdkConfig(path, () => ({ ...config }));
-}
-
-export function mergeCursorSdkConfig(base: CursorSdkConfig, patch: CursorSdkConfig): CursorSdkConfig {
-	return mergeCursorSdkConfigForUpdate({ ...base }, patch) as CursorSdkConfig;
-}
-
 export function mergeCursorSdkConfigForUpdate(
 	base: Record<string, unknown>,
 	patch: CursorSdkConfig,
@@ -520,16 +507,6 @@ export function cursorFastDefaultsFromConfig(config: CursorSdkConfig | undefined
 	return new Map(Object.entries(config?.fastDefaults ?? {}));
 }
 
-export function withCursorFastDefaults<T extends object>(
-	config: T,
-	fastDefaults: Map<string, boolean>,
-): T & { fastDefaults: Record<string, boolean> } {
-	return {
-		...config,
-		fastDefaults: Object.fromEntries([...fastDefaults.entries()].sort(([a], [b]) => a.localeCompare(b))),
-	};
-}
-
 function resolved<T>(source: CursorConfigSource, value: T, cappedBy?: CursorSafetyCap<T>): CursorResolvedSetting<T> {
 	return { value, source, trustLevel: TRUST_LEVELS[source], ...(cappedBy ? { cappedBy } : {}) };
 }