pi-cursor-sdk 0.1.34 → 0.1.36

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.1.36 - 2026-06-05
+
+### Fixed
+
+- Classify Cursor backend `ConnectError: [unavailable] Error` failures with code 14 and `aiserver.v1.ErrorDetails` as recoverable network/service errors, preventing duplicate process-level uncaught exceptions from crashing pi while still surfacing scrubbed retry guidance.
+
+## 0.1.35 - 2026-06-05
+
+### Changed
+
+- Share the Cursor SDK startup-output filter through one published `shared/` helper while preserving the existing provider and maintainer-script import paths.
+- Add prompt snippets for the Cursor bridge question and skill activation tools so their pi-native prompt metadata matches their existing schemas and guidelines.
+
+### Fixed
+
+- Scope fileless/in-memory Cursor session agents by pi session ID instead of the process-wide anonymous fallback, so terminal shutdown of one ephemeral session does not poison later no-session replacements.
+
 ## 0.1.34 - 2026-06-04
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.34",
+	"version": "0.1.36",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

package/scripts/lib/cursor-sdk-output-filter.d.mts

@@ -1,5 +1,7 @@
-export declare const CURSOR_SDK_STARTUP_NOISE_PATTERNS: readonly string[];
-export declare function isCursorSdkOutputSuppressed(): boolean;
-export declare function suppressCursorSdkOutput<T>(operation: () => T): T;
-export declare function isCursorSdkStartupNoise(text: string): boolean;
-export declare function installCursorSdkOutputFilter(): () => void;
+export {
+	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	installCursorSdkOutputFilter,
+	isCursorSdkOutputSuppressed,
+	isCursorSdkStartupNoise,
+	suppressCursorSdkOutput,
+} from "../../shared/cursor-sdk-output-filter.mjs";

package/scripts/lib/cursor-sdk-output-filter.mjs

@@ -1,86 +1,7 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
-	"[hooks]",
-	"managed_skills.",
-	"CursorPluginsAgentSkillsService load completed",
-	"LocalCursorRulesService load completed",
-	"AgentSkillsCursorRulesService load completed",
-	"Error initializing ignore mapping for",
-	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
-];
-
-const cursorSdkOutputSuppression = new AsyncLocalStorage();
-
-export function isCursorSdkOutputSuppressed() {
-	return cursorSdkOutputSuppression.getStore() === true;
-}
-
-export function suppressCursorSdkOutput(operation) {
-	return cursorSdkOutputSuppression.run(true, operation);
-}
-
-export function isCursorSdkStartupNoise(text) {
-	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
-}
-
-function createFilteredProcessWrite(write, stream) {
-	return (chunk, encodingOrCallback, callback) => {
-		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
-		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
-			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
-			done?.();
-			return true;
-		}
-		return write.call(stream, chunk, encodingOrCallback, callback);
-	};
-}
-
-function createFilteredConsoleMethod(method) {
-	return (...args) => {
-		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
-		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
-		method(...args);
-	};
-}
-
-let activeOutputFilterInstalls = 0;
-let outputFilterOriginals;
-
-export function installCursorSdkOutputFilter() {
-	if (activeOutputFilterInstalls === 0) {
-		outputFilterOriginals = {
-			stdoutWrite: process.stdout.write,
-			stderrWrite: process.stderr.write,
-			consoleLog: console.log,
-			consoleInfo: console.info,
-			consoleWarn: console.warn,
-			consoleError: console.error,
-			consoleDebug: console.debug,
-		};
-		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
-		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr);
-		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
-		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
-		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
-		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
-		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
-	}
-	activeOutputFilterInstalls += 1;
-
-	let restored = false;
-	return () => {
-		if (restored) return;
-		restored = true;
-		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
-		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
-		process.stdout.write = outputFilterOriginals.stdoutWrite;
-		process.stderr.write = outputFilterOriginals.stderrWrite;
-		console.log = outputFilterOriginals.consoleLog;
-		console.info = outputFilterOriginals.consoleInfo;
-		console.warn = outputFilterOriginals.consoleWarn;
-		console.error = outputFilterOriginals.consoleError;
-		console.debug = outputFilterOriginals.consoleDebug;
-		outputFilterOriginals = undefined;
-	};
-}
+export {
+	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	installCursorSdkOutputFilter,
+	isCursorSdkOutputSuppressed,
+	isCursorSdkStartupNoise,
+	suppressCursorSdkOutput,
+} from "../../shared/cursor-sdk-output-filter.mjs";

package/scripts/platform-smoke/scenarios.mjs

@@ -48,12 +48,12 @@ Steps:
 1. read ./package.json and remember the package name.
 2. grep ./README.md for "pi-cursor-sdk".
 3. find README.md from repo root.
-4. find src/cursor-provider.ts from repo root.
+4. find src/cursor-provider.ts from repo root; this is the list=<yes/no> evidence.
 5. run shell: {{shellSmoke}}
 6. write .debug/platform-smoke/native.txt with alpha and beta.
 7. edit beta to gamma in that file.
 8. run shell and preserve the failure: {{shellFailure}}
-9. answer exactly:
+9. stop using tools and answer exactly:
 NATIVE_MATRIX_OK package=<name> grep=<yes/no> find=<yes/no> list=<yes/no> shell=<yes/no> shell_fail=<yes/no> write=<yes/no> edit=<yes/no>`,
 		finalMarker: "NATIVE_MATRIX_OK package=pi-cursor-sdk",
 		requiredCards: [

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

@@ -0,0 +1,5 @@
+export declare const CURSOR_SDK_STARTUP_NOISE_PATTERNS: readonly string[];
+export declare function isCursorSdkOutputSuppressed(): boolean;
+export declare function suppressCursorSdkOutput<T>(operation: () => T): T;
+export declare function isCursorSdkStartupNoise(text: string): boolean;
+export declare function installCursorSdkOutputFilter(): () => void;

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

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const cursorSdkOutputSuppression = new AsyncLocalStorage();
+
+export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
+	"[hooks]",
+	"managed_skills.",
+	"CursorPluginsAgentSkillsService load completed",
+	"LocalCursorRulesService load completed",
+	"AgentSkillsCursorRulesService load completed",
+	"Error initializing ignore mapping for",
+	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
+];
+
+export function isCursorSdkOutputSuppressed() {
+	return cursorSdkOutputSuppression.getStore() === true;
+}
+
+export function suppressCursorSdkOutput(operation) {
+	return cursorSdkOutputSuppression.run(true, operation);
+}
+
+export function isCursorSdkStartupNoise(text) {
+	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
+}
+
+function createFilteredProcessWrite(write, stream) {
+	return (chunk, encodingOrCallback, callback) => {
+		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
+			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+			done?.();
+			return true;
+		}
+		return write.call(stream, chunk, encodingOrCallback, callback);
+	};
+}
+
+function createFilteredConsoleMethod(method) {
+	return (...args) => {
+		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
+		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
+		method(...args);
+	};
+}
+
+let activeOutputFilterInstalls = 0;
+let outputFilterOriginals;
+
+export function installCursorSdkOutputFilter() {
+	if (activeOutputFilterInstalls === 0) {
+		outputFilterOriginals = {
+			stdoutWrite: process.stdout.write,
+			stderrWrite: process.stderr.write,
+			consoleLog: console.log,
+			consoleInfo: console.info,
+			consoleWarn: console.warn,
+			consoleError: console.error,
+			consoleDebug: console.debug,
+		};
+		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
+		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr);
+		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
+		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
+		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
+		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
+		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
+	}
+	activeOutputFilterInstalls += 1;
+
+	let restored = false;
+	return () => {
+		if (restored) return;
+		restored = true;
+		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
+		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
+		process.stdout.write = outputFilterOriginals.stdoutWrite;
+		process.stderr.write = outputFilterOriginals.stderrWrite;
+		console.log = outputFilterOriginals.consoleLog;
+		console.info = outputFilterOriginals.consoleInfo;
+		console.warn = outputFilterOriginals.consoleWarn;
+		console.error = outputFilterOriginals.consoleError;
+		console.debug = outputFilterOriginals.consoleDebug;
+		outputFilterOriginals = undefined;
+	};
+}

package/src/cursor-provider-errors.ts

@@ -9,7 +9,7 @@ const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
 const AUTH_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request failed because the Cursor SDK API key may be invalid or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request timed out during network I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
+	"Cursor SDK request failed during network or service I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
 
 const GENERIC_CURSOR_RUN_FAILURE_TEXT = "cursor sdk run failed";
 
@@ -47,6 +47,10 @@ function isUnauthenticatedConnectCode(code: unknown): boolean {
 	return code === 16 || (typeof code === "string" && /^(?:16|unauthenticated)$/i.test(code));
 }
 
+function isUnavailableConnectCode(code: unknown): boolean {
+	return code === 14 || (typeof code === "string" && /^(?:14|unavailable)$/i.test(code));
+}
+
 function isCursorExtensionConnectStack(stack: string): boolean {
 	return stack.includes("@connectrpc/connect-node") && /(?:^|[\\/])pi-cursor-sdk(?:[\\/]|$)/.test(stack);
 }
@@ -101,6 +105,10 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 		return { kind: "unauthenticated", source: getCursorConnectSource(error, record) };
 	}
 
+	if (isUnavailableConnectCode(code)) {
+		return { kind: "network", source: getCursorConnectSource(error, record) };
+	}
+
 	const causeCode = getErrorStringField(cause, "code");
 	const causeSyscall = getErrorStringField(cause, "syscall");
 	if (isLikelyNetworkTimeout(`${message}\n${rawMessage}\n${causeCode ?? ""}\n${causeSyscall ?? ""}`)) {
@@ -179,8 +187,9 @@ export function sanitizeCursorProviderError(error: unknown, apiKey?: string): st
 	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
 	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_API_KEY_MESSAGE;
 	const scrubbed = scrubSensitiveText(message, apiKey).trim();
-	if (isUnauthenticatedConnectError(error) || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	const connectClassification = classifyCursorConnectError(error);
+	if (connectClassification?.kind === "unauthenticated" || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	if (connectClassification?.kind === "network" || isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
-	if (isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
 }

package/src/cursor-question-tool.ts

@@ -196,6 +196,7 @@ export function registerCursorQuestionTool(pi: CursorQuestionToolExtensionApi):
 		label: "Cursor question",
 		description:
 			"Ask the user a clarifying question from Cursor. Use when user preferences materially affect the next step; provide options when possible.",
+		promptSnippet: "Ask the user a clarifying question through pi UI when material choices affect Cursor's next step",
 		parameters: CursorAskQuestionParamsSchema,
 		promptGuidelines: [
 			"Use cursor_ask_question only when running a Cursor model and user input would materially change the plan, scope, platform, or implementation path.",

package/src/cursor-sdk-output-filter.ts

@@ -1,100 +1,7 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-const cursorSdkOutputSuppression = new AsyncLocalStorage<boolean>();
-
-export const CURSOR_SDK_STARTUP_NOISE_PATTERNS = [
-	"[hooks]",
-	"managed_skills.",
-	"CursorPluginsAgentSkillsService load completed",
-	"LocalCursorRulesService load completed",
-	"AgentSkillsCursorRulesService load completed",
-	"Error initializing ignore mapping for",
-	"Ripgrep path not configured. Call configureRipgrepPath() at startup.",
-] as const;
-
-export function isCursorSdkOutputSuppressed(): boolean {
-	return cursorSdkOutputSuppression.getStore() === true;
-}
-
-export function suppressCursorSdkOutput<T>(operation: () => Promise<T>): Promise<T> {
-	return cursorSdkOutputSuppression.run(true, operation);
-}
-
-export function isCursorSdkStartupNoise(text: string): boolean {
-	return CURSOR_SDK_STARTUP_NOISE_PATTERNS.some((pattern) => text.includes(pattern));
-}
-
-function createFilteredProcessWrite<TWrite extends typeof process.stdout.write>(write: TWrite, stream: NodeJS.WriteStream): TWrite {
-	return ((
-		chunk: string | Uint8Array,
-		encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
-		callback?: (error?: Error | null) => void,
-	): boolean => {
-		const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
-		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) {
-			const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
-			done?.();
-			return true;
-		}
-		return write.call(stream, chunk as string, encodingOrCallback as BufferEncoding, callback);
-	}) as TWrite;
-}
-
-function createFilteredConsoleMethod<TMethod extends typeof console.log>(method: TMethod): TMethod {
-	return ((...args: Parameters<TMethod>): void => {
-		const text = args.map((arg) => (typeof arg === "string" ? arg : String(arg))).join(" ");
-		if (isCursorSdkOutputSuppressed() || isCursorSdkStartupNoise(text)) return;
-		method(...args);
-	}) as TMethod;
-}
-
-interface CursorSdkOutputFilterOriginals {
-	stdoutWrite: typeof process.stdout.write;
-	stderrWrite: typeof process.stderr.write;
-	consoleLog: typeof console.log;
-	consoleInfo: typeof console.info;
-	consoleWarn: typeof console.warn;
-	consoleError: typeof console.error;
-	consoleDebug: typeof console.debug;
-}
-
-let activeOutputFilterInstalls = 0;
-let outputFilterOriginals: CursorSdkOutputFilterOriginals | undefined;
-
-export function installCursorSdkOutputFilter(): () => void {
-	if (activeOutputFilterInstalls === 0) {
-		outputFilterOriginals = {
-			stdoutWrite: process.stdout.write,
-			stderrWrite: process.stderr.write,
-			consoleLog: console.log,
-			consoleInfo: console.info,
-			consoleWarn: console.warn,
-			consoleError: console.error,
-			consoleDebug: console.debug,
-		};
-		process.stdout.write = createFilteredProcessWrite(outputFilterOriginals.stdoutWrite, process.stdout);
-		process.stderr.write = createFilteredProcessWrite(outputFilterOriginals.stderrWrite, process.stderr) as typeof process.stderr.write;
-		console.log = createFilteredConsoleMethod(outputFilterOriginals.consoleLog);
-		console.info = createFilteredConsoleMethod(outputFilterOriginals.consoleInfo);
-		console.warn = createFilteredConsoleMethod(outputFilterOriginals.consoleWarn);
-		console.error = createFilteredConsoleMethod(outputFilterOriginals.consoleError);
-		console.debug = createFilteredConsoleMethod(outputFilterOriginals.consoleDebug);
-	}
-	activeOutputFilterInstalls += 1;
-
-	let restored = false;
-	return () => {
-		if (restored) return;
-		restored = true;
-		activeOutputFilterInstalls = Math.max(activeOutputFilterInstalls - 1, 0);
-		if (activeOutputFilterInstalls > 0 || !outputFilterOriginals) return;
-		process.stdout.write = outputFilterOriginals.stdoutWrite;
-		process.stderr.write = outputFilterOriginals.stderrWrite;
-		console.log = outputFilterOriginals.consoleLog;
-		console.info = outputFilterOriginals.consoleInfo;
-		console.warn = outputFilterOriginals.consoleWarn;
-		console.error = outputFilterOriginals.consoleError;
-		console.debug = outputFilterOriginals.consoleDebug;
-		outputFilterOriginals = undefined;
-	};
-}
+export {
+	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	installCursorSdkOutputFilter,
+	isCursorSdkOutputSuppressed,
+	isCursorSdkStartupNoise,
+	suppressCursorSdkOutput,
+} from "../shared/cursor-sdk-output-filter.mjs";

package/src/cursor-session-scope.ts

@@ -5,12 +5,14 @@ interface CursorSessionScopeExtensionApi {
 }
 
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
+const EPHEMERAL_SESSION_SCOPE_PREFIX = "__ephemeral__:";
 
 type CursorSessionScopeChangeHandler = (previousScopeKey: string) => void;
 
 const state = {
 	sessionCwd: process.cwd(),
 	sessionFile: undefined as string | undefined,
+	sessionId: undefined as string | undefined,
 };
 
 let scopeChangeHandler: CursorSessionScopeChangeHandler | undefined;
@@ -27,21 +29,25 @@ export function getCursorSessionFile(): string | undefined {
  * before the first session_start (tests and early startup).
  */
 export function getCursorSessionScopeKey(): string {
-	return state.sessionFile ?? ANONYMOUS_SESSION_SCOPE_KEY;
+	if (state.sessionFile) return state.sessionFile;
+	if (state.sessionId) return `${EPHEMERAL_SESSION_SCOPE_PREFIX}${state.sessionId}`;
+	return ANONYMOUS_SESSION_SCOPE_KEY;
 }
 
 export function getCursorSessionCwdFromScope(): string {
 	return state.sessionCwd;
 }
 
-function setCursorSessionScope(cwd: string, sessionFile: string | undefined): void {
+function setCursorSessionScope(cwd: string, sessionFile: string | undefined, sessionId?: string): void {
 	state.sessionCwd = cwd;
 	state.sessionFile = sessionFile;
+	state.sessionId = sessionId;
 }
 
 function resetCursorSessionScope(): void {
 	state.sessionCwd = process.cwd();
 	state.sessionFile = undefined;
+	state.sessionId = undefined;
 }
 
 export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeHandler): void {
@@ -51,7 +57,11 @@ export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeH
 export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi): void {
 	pi.on("session_start", (_event, ctx) => {
 		const previousScopeKey = getCursorSessionScopeKey();
-		setCursorSessionScope(ctx.cwd, ctx.sessionManager?.getSessionFile?.() ?? undefined);
+		setCursorSessionScope(
+			ctx.cwd,
+			ctx.sessionManager?.getSessionFile?.() ?? undefined,
+			ctx.sessionManager?.getSessionId?.() ?? undefined,
+		);
 		if (previousScopeKey !== getCursorSessionScopeKey()) {
 			scopeChangeHandler?.(previousScopeKey);
 		}
@@ -60,6 +70,7 @@ export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi):
 
 export const __testUtils = {
 	ANONYMOUS_SESSION_SCOPE_KEY,
+	EPHEMERAL_SESSION_SCOPE_PREFIX,
 	set: setCursorSessionScope,
 	reset: resetCursorSessionScope,
 };

package/src/cursor-skill-tool.ts

@@ -187,6 +187,7 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 		name: CURSOR_ACTIVATE_SKILL_TOOL_NAME,
 		label: "Cursor skill",
 		description: "Load full pi Agent Skill instructions for Cursor. Use with a skill name from the current <available_skills> catalog before applying that skill.",
+		promptSnippet: "Load full pi Agent Skill instructions for a listed skill before Cursor applies that skill",
 		parameters: Type.Object({
 			name: Type.String({ description: "Skill name from the current <available_skills> catalog" }),
 		}),