pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-runtime-state.ts

@@ -36,7 +36,8 @@ import {
 } from "./cursor-config.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { getResolvedSessionCursorHttp1Enabled } from "./cursor-http1.js";
-import { getCursorSessionCwd, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
+import { cursorSettingsScopeForContext, getCursorSessionSettings } from "./cursor-session-settings.js";
 
 export const CURSOR_RUNTIME_ENTRY_TYPE = "cursor-runtime-state";
 
@@ -59,20 +60,12 @@ export type CursorRuntimeStateExtensionApi = Pick<
 	"appendEntry" | "getFlag" | "registerFlag" | "registerCommand" | "on"
 >;
 
-type CursorRuntimeContext = Pick<ExtensionContext, "cwd">;
+type CursorRuntimeContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "sessionManager">>;
 
 type CursorStatusRefresh = (ctx: ExtensionContext) => void;
 
-interface CursorCliConfigSnapshot {
-	config: CursorExplicitSdkConfig;
-	cloudEnvNames?: string;
-}
 
-let cliCursorSnapshot: CursorCliConfigSnapshot = { config: {} };
-let cliLocalForceConsumed = false;
 let envLocalForceConsumed = false;
-let sessionCursorRuntime: CursorRuntime | undefined;
-let sessionCursorCloudAcknowledged = false;
 
 function isCursorRuntimeEntryData(value: unknown): value is CursorRuntimeEntryData {
 	const record = asRecord(value);
@@ -85,15 +78,17 @@ function stringFlagValue(value: boolean | string | undefined): string | undefine
 	return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
-export function getCursorCliConfig(): CursorExplicitSdkConfig {
-	const config = structuredClone(cliCursorSnapshot.config);
-	const envNames = parseExplicitCursorCloudEnvNames(cliCursorSnapshot.cloudEnvNames, "--cursor-cloud-env");
+export function getCursorCliConfig(scopeKey?: string): CursorExplicitSdkConfig {
+	const cli = getCursorSessionSettings(scopeKey).cli;
+	const config = structuredClone(cli.config);
+	const envNames = parseExplicitCursorCloudEnvNames(cli.cloudEnvNames, "--cursor-cloud-env");
 	if (envNames) config.cloud = { ...config.cloud, envNames };
 	return config;
 }
 
-export function getCursorSessionConfig(): CursorSdkConfig {
-	const useHttp1ForAgent = getResolvedSessionCursorHttp1Enabled();
+export function getCursorSessionConfig(scopeKey?: string): CursorSdkConfig {
+	const { runtime: sessionCursorRuntime, cloudAcknowledged: sessionCursorCloudAcknowledged } = getCursorSessionSettings(scopeKey);
+	const useHttp1ForAgent = getResolvedSessionCursorHttp1Enabled(scopeKey);
 	return {
 		...(sessionCursorRuntime
 			? {
@@ -108,11 +103,12 @@ export function getCursorSessionConfig(): CursorSdkConfig {
 export function resolveEffectiveCursorConfig(options: {
 	cwd: string;
 	projectTrusted?: boolean;
+	scopeKey?: string;
 }): CursorResolvedSdkConfig {
 	const loadedConfig = loadCursorSdkConfig({ cwd: options.cwd, projectTrusted: options.projectTrusted === true });
 	return resolveCursorSdkConfig({
-		cli: getCursorCliConfig(),
-		session: getCursorSessionConfig(),
+		cli: getCursorCliConfig(options.scopeKey),
+		session: getCursorSessionConfig(options.scopeKey),
 		user: loadedConfig.user,
 		project: loadedConfig.project,
 	});
@@ -121,7 +117,10 @@ export function resolveEffectiveCursorConfig(options: {
 export function resolveEffectiveCursorConfigForContext(ctx: CursorRuntimeContext): CursorResolvedSdkConfig {
 	return resolveEffectiveCursorConfig({
 		cwd: ctx.cwd,
-		projectTrusted: getCursorSessionCwd() === ctx.cwd && getCursorSessionProjectTrusted(),
+		projectTrusted: cursorSettingsScopeForContext(ctx) === undefined
+			? getCursorSessionScopeSnapshot().cwd === ctx.cwd && getCursorSessionScopeSnapshot().projectTrusted
+			: getCursorSessionSettings(cursorSettingsScopeForContext(ctx)).projectTrusted,
+		scopeKey: cursorSettingsScopeForContext(ctx),
 	});
 }
 
@@ -166,14 +165,15 @@ export function formatCursorStatus(
 	return parts.join(" · ");
 }
 
-export function consumeCursorLocalForceOverride(resolved: { value: boolean; source: string }): boolean {
+export function consumeCursorLocalForceOverride(resolved: { value: boolean; source: string }, scopeKey?: string): boolean {
 	if (!resolved.value) return false;
-	if (resolved.source === "cli" && !cliLocalForceConsumed) {
-		if (cliCursorSnapshot.config.local) {
-			const { force: _, ...local } = cliCursorSnapshot.config.local;
-			cliCursorSnapshot.config.local = local;
+	const cli = getCursorSessionSettings(scopeKey).cli;
+	if (resolved.source === "cli" && !cli.localForceConsumed) {
+		if (cli.config.local) {
+			const { force: _, ...local } = cli.config.local;
+			cli.config.local = local;
 		}
-		cliLocalForceConsumed = true;
+		cli.localForceConsumed = true;
 		return true;
 	}
 	if (resolved.source === "environment" && !envLocalForceConsumed) {
@@ -183,19 +183,21 @@ export function consumeCursorLocalForceOverride(resolved: { value: boolean; sour
 	return false;
 }
 
-export function restoreSessionCursorRuntimeState(branch: readonly SessionEntry[]): void {
-	sessionCursorRuntime = undefined;
-	sessionCursorCloudAcknowledged = false;
+export function restoreSessionCursorRuntimeState(branch: readonly SessionEntry[], scopeKey?: string): void {
+	const state = getCursorSessionSettings(scopeKey);
+	state.runtime = undefined;
+	state.cloudAcknowledged = false;
 	for (const entry of branch) {
 		if (entry.type !== "custom" || entry.customType !== CURSOR_RUNTIME_ENTRY_TYPE) continue;
 		if (isCursorRuntimeEntryData(entry.data)) {
-			sessionCursorRuntime = entry.data.runtime;
-			sessionCursorCloudAcknowledged ||= entry.data.cloudAcknowledged === true;
+			state.runtime = entry.data.runtime;
+			state.cloudAcknowledged ||= entry.data.cloudAcknowledged === true;
 		}
 	}
 }
 
-export function restoreCursorCliState(pi: Pick<ExtensionAPI, "getFlag">): void {
+export function restoreCursorCliState(pi: Pick<ExtensionAPI, "getFlag">, scopeKey?: string): void {
+	const cli = getCursorSessionSettings(scopeKey).cli;
 	const runtime = stringFlagValue(pi.getFlag("cursor-runtime"));
 	const repo = stringFlagValue(pi.getFlag("cursor-cloud-repo"));
 	const branch = stringFlagValue(pi.getFlag("cursor-cloud-branch"));
@@ -220,35 +222,35 @@ export function restoreCursorCliState(pi: Pick<ExtensionAPI, "getFlag">): void {
 	const local: NonNullable<CursorExplicitSdkConfig["local"]> = {
 		...(pi.getFlag("cursor-auto-review") === true ? { autoReview: true } : {}),
 		...(pi.getFlag("cursor-sandbox") === true ? { sandboxOptions: { enabled: true } } : {}),
-		...(!cliLocalForceConsumed && pi.getFlag("cursor-local-force") === true ? { force: true } : {}),
+		...(!cli.localForceConsumed && pi.getFlag("cursor-local-force") === true ? { force: true } : {}),
 		...(pi.getFlag("cursor-no-local-resume") === true
 			? { resume: false }
 			: pi.getFlag("cursor-local-resume") === true
 				? { resume: true }
 				: {}),
 	};
-	cliCursorSnapshot = {
-		config: {
-			...(runtime ? { runtime } : {}),
-			...(Object.keys(cloud).length ? { cloud } : {}),
-			...(Object.keys(local).length ? { local } : {}),
-		},
-		...(cloudEnvNames ? { cloudEnvNames } : {}),
+	cli.config = {
+		...(runtime ? { runtime } : {}),
+		...(Object.keys(cloud).length ? { cloud } : {}),
+		...(Object.keys(local).length ? { local } : {}),
 	};
+	cli.cloudEnvNames = cloudEnvNames;
 }
 
 function persistCursorRuntimePreference(
 	pi: Pick<ExtensionAPI, "appendEntry">,
 	runtime: CursorRuntime,
-	cloudAcknowledged = false,
+	cloudAcknowledged: boolean,
+	scopeKey: string | undefined,
 ): void {
-	const acknowledged = sessionCursorCloudAcknowledged || cloudAcknowledged;
+	const state = getCursorSessionSettings(scopeKey);
+	const acknowledged = state.cloudAcknowledged || cloudAcknowledged;
 	pi.appendEntry<CursorRuntimeEntryData>(CURSOR_RUNTIME_ENTRY_TYPE, {
 		runtime,
 		...(acknowledged ? { cloudAcknowledged: true } : {}),
 	});
-	sessionCursorRuntime = runtime;
-	sessionCursorCloudAcknowledged = acknowledged;
+	state.runtime = runtime;
+	state.cloudAcknowledged = acknowledged;
 }
 
 function registerCursorRuntimeFlags(pi: Pick<ExtensionAPI, "registerFlag">): void {
@@ -368,6 +370,7 @@ function registerCursorRuntimeCommand(
 	pi.registerCommand("cursor-runtime", {
 		description: "Set Cursor runtime for this session: local or cloud",
 		handler: async (args, ctx) => {
+			const scopeKey = cursorSettingsScopeForContext(ctx);
 			const usage = "Usage: /cursor-runtime local|cloud [--save-user|--save-project]";
 			const tokens = args.trim().split(/\s+/).filter(Boolean);
 			const raw = tokens[0];
@@ -392,7 +395,7 @@ function registerCursorRuntimeCommand(
 				ctx.ui.notify(`${currentResolution.message} Fix the explicit override before changing the session runtime.`, "error");
 				return;
 			}
-			if (saveProject && (getCursorSessionCwd() !== ctx.cwd || !getCursorSessionProjectTrusted())) {
+			if (saveProject && (getCursorSessionScopeSnapshot(pi).cwd !== ctx.cwd || !getCursorSessionScopeSnapshot(pi).projectTrusted)) {
 				ctx.ui.notify(
 					"Cannot save Cursor project config without explicit project-trust provenance. Ensure .pi/settings.json or another Pi project resource exists, trust the project, then restart pi; or restart with --approve. Project-local package installs must use --approve on every run that reads or writes .pi/cursor-sdk.json.",
 					"error",
@@ -435,7 +438,7 @@ function registerCursorRuntimeCommand(
 				}
 			}
 			try {
-				persistCursorRuntimePreference(pi, raw, cloudAcknowledged);
+				persistCursorRuntimePreference(pi, raw, cloudAcknowledged, scopeKey);
 			} catch (error) {
 				const effectiveResolution = resolveCursorStatusRuntime(ctx);
 				refreshStatus(ctx);
@@ -489,9 +492,11 @@ export function registerCursorCloudRuntimeControls(
 }
 
 export function resetCursorRuntimeStateForTests(): void {
-	cliCursorSnapshot = { config: {} };
-	cliLocalForceConsumed = false;
+	const cli = getCursorSessionSettings().cli;
+	cli.config = {};
+	cli.cloudEnvNames = undefined;
+	cli.localForceConsumed = false;
 	envLocalForceConsumed = false;
-	sessionCursorRuntime = undefined;
-	sessionCursorCloudAcknowledged = false;
+	getCursorSessionSettings().runtime = undefined;
+	getCursorSessionSettings().cloudAcknowledged = false;
 }

package/src/cursor-sdk-billed-usage.ts

@@ -1,107 +1,59 @@
-import type { SDKAgent } from "@cursor/sdk";
-import type { CursorRuntime } from "./cursor-config.js";
-import { asRecord, getArray, getString } from "./cursor-record-utils.js";
-import { readCursorSdkTurnUsage, type CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
-
-const BILLED_USAGE_TIMEOUT_MS = 5000;
-
-// ponytail: process-lifetime watermark of billed usage UUIDs per agentId; reset on process exit.
-// Upgrade to session-scoped storage if multi-day processes retain enough agent IDs to matter.
-const seenBilledRunIdsByAgent = new Map<string, Set<string>>();
-
-export function isCursorSdkClientMintedRunId(runId: string): boolean {
-	return runId.startsWith("run-");
-}
-
-export function sumCursorSdkTurnUsage(usages: readonly CursorSdkTurnUsage[]): CursorSdkTurnUsage | undefined {
-	if (usages.length === 0) return undefined;
-	return usages.reduce(
-		(total, usage) => ({
-			inputTokens: total.inputTokens + usage.inputTokens,
-			outputTokens: total.outputTokens + usage.outputTokens,
-			cacheReadTokens: total.cacheReadTokens + usage.cacheReadTokens,
-			cacheWriteTokens: total.cacheWriteTokens + usage.cacheWriteTokens,
-		}),
-	);
-}
-
-export function peekCursorBilledUsageRunIds(agentId: string): ReadonlySet<string> {
-	return seenBilledRunIdsByAgent.get(agentId) ?? new Set();
-}
-
-export function rememberCursorBilledUsageRunIds(agentId: string, runIds: readonly string[]): void {
-	if (runIds.length === 0) return;
-	let seen = seenBilledRunIdsByAgent.get(agentId);
-	if (!seen) {
-		seen = new Set();
-		seenBilledRunIdsByAgent.set(agentId, seen);
+import type { AgentUsage, SDKAgent, TokenUsage, UsageCost } from "@cursor/sdk";
+import { asRecord } from "./cursor-record-utils.js";
+
+export type CursorBillingObservation =
+	| { status: "observed-pending-settlement"; snapshot: AgentUsage }
+	| { status: "unavailable"; reason: "timeout" | "unsupported" | "request-failed" | "invalid-response" };
+
+const fields = ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens"] as const;
+export function readCursorUsageTokens(value: unknown): TokenUsage | undefined {
+	const record = asRecord(value);
+	if (!record || fields.some(key => !Number.isSafeInteger(record[key]) || (record[key] as number) < 0)) return undefined;
+	if (record.reasoningTokens !== undefined && (!Number.isSafeInteger(record.reasoningTokens) || (record.reasoningTokens as number) < 0 || (record.reasoningTokens as number) > (record.outputTokens as number))) return undefined;
+	return { inputTokens: record.inputTokens as number, outputTokens: record.outputTokens as number, cacheReadTokens: record.cacheReadTokens as number, cacheWriteTokens: record.cacheWriteTokens as number, totalTokens: record.totalTokens as number, ...(record.reasoningTokens === undefined ? {} : { reasoningTokens: record.reasoningTokens as number }) };
+}
+function readCost(value: unknown): UsageCost | undefined {
+	const record = asRecord(value);
+	if (!record || ["rawCostCents", "chargedCents"].some(key => typeof record[key] !== "number" || !Number.isFinite(record[key]) || (record[key] as number) < 0)) return undefined;
+	return { rawCostCents: record.rawCostCents as number, chargedCents: record.chargedCents as number };
+}
+function billedTokens(value: unknown): TokenUsage | undefined {
+	const usage = readCursorUsageTokens(value);
+	if (!usage || usage.totalTokens !== usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens) return undefined;
+	return usage;
+}
+export function readCursorBilledSnapshot(value: unknown): AgentUsage | undefined {
+	const record = asRecord(value);
+	const usage = billedTokens(record?.usage);
+	if (!record || !usage || !Array.isArray(record.runs)) return undefined;
+	const cost = record.cost === undefined ? undefined : readCost(record.cost);
+	if (record.cost !== undefined && !cost) return undefined;
+	const runs: AgentUsage["runs"] = [];
+	const ids = new Set<string>();
+	for (const item of record.runs) {
+		const row = asRecord(item);
+		const tokens = billedTokens(row?.usage);
+		const rowCost = row?.cost === undefined ? undefined : readCost(row.cost);
+		if (!row || typeof row.runId !== "string" || !row.runId || row.runId.length > 256 || ids.has(row.runId) || !tokens || (row.cost !== undefined && !rowCost)) return undefined;
+		ids.add(row.runId);
+		runs.push({ runId: row.runId, usage: tokens, ...(rowCost ? { cost: rowCost } : {}) });
 	}
-	for (const runId of runIds) seen.add(runId);
+	if (fields.some(key => runs.reduce((sum, row) => sum + row.usage[key], 0) > usage[key])) return undefined;
+	return { usage, runs, ...(cost ? { cost } : {}) };
 }
 
-function withTimeout<T>(promise: Promise<T>, timeoutMs = BILLED_USAGE_TIMEOUT_MS): Promise<T | undefined> {
+/** Fetch is only observation; the origin journal owns recognition. No run-ID guesses or private fallback. */
+export async function fetchCursorSdkAgentUsage(agent: Pick<SDKAgent, "getUsage">): Promise<CursorBillingObservation> {
+	if (typeof agent.getUsage !== "function") return { status: "unavailable", reason: "unsupported" };
 	let timer: ReturnType<typeof setTimeout> | undefined;
-	const timeout = new Promise<undefined>((resolve) => {
-		timer = setTimeout(() => resolve(undefined), timeoutMs);
-		timer.unref?.();
-	});
-	return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
-		if (timer) clearTimeout(timer);
-	});
+	try {
+		const timeout = new Promise<CursorBillingObservation>(resolve => {
+			timer = setTimeout(() => resolve({ status: "unavailable", reason: "timeout" }), 5000);
+			timer.unref?.();
+		});
+		return await Promise.race([Promise.resolve().then(() => agent.getUsage()).then(value => {
+			const snapshot = readCursorBilledSnapshot(value);
+			return snapshot ? { status: "observed-pending-settlement" as const, snapshot } : { status: "unavailable" as const, reason: "invalid-response" as const };
+		}, () => ({ status: "unavailable" as const, reason: "request-failed" as const })), timeout]);
+	} finally { if (timer) clearTimeout(timer); }
 }
-
-export function selectCursorBilledTurnUsage(
-	agentUsage: unknown,
-	options: { runtime: CursorRuntime; runId?: string; seenRunIds?: ReadonlySet<string> },
-): { turn?: CursorSdkTurnUsage; runIds: string[] } {
-	const runs = (getArray(asRecord(agentUsage), "runs") ?? []).flatMap((item) => {
-		const record = asRecord(item);
-		const runId = getString(record, "runId");
-		const usage = readCursorSdkTurnUsage(record?.usage);
-		return runId && usage ? [{ runId, usage }] : [];
-	});
-	if (options.runtime === "cloud" && options.runId) {
-		const match = runs.find((run) => run.runId === options.runId);
-		return match ? { turn: match.usage, runIds: [match.runId] } : { runIds: [] };
-	}
-	const unseen = runs.filter((run) => !options.seenRunIds?.has(run.runId));
-	return { turn: sumCursorSdkTurnUsage(unseen.map((run) => run.usage)), runIds: unseen.map((run) => run.runId) };
-}
-
-export async function fetchCursorSdkAgentUsage(
-	agent: SDKAgent,
-	options: { runtime: CursorRuntime; runId?: string },
-): Promise<unknown | undefined> {
-	if (typeof agent.getUsage !== "function") return undefined;
-	const query =
-		options.runtime === "cloud" && options.runId && isCursorSdkClientMintedRunId(options.runId)
-			? { runId: options.runId }
-			: undefined;
-	return withTimeout(Promise.resolve(agent.getUsage(query)));
-}
-
-export async function attachCursorSdkBilledTurnUsage(options: {
-	agent: SDKAgent;
-	agentId: string;
-	runtime: CursorRuntime;
-	runId?: string;
-}): Promise<{ agentUsage?: unknown; turn?: CursorSdkTurnUsage }> {
-	const agentUsage = await fetchCursorSdkAgentUsage(options.agent, {
-		runtime: options.runtime,
-		runId: options.runId,
-	});
-	if (!agentUsage) return {};
-	const selected = selectCursorBilledTurnUsage(agentUsage, {
-		runtime: options.runtime,
-		runId: options.runtime === "cloud" ? options.runId : undefined,
-		seenRunIds: peekCursorBilledUsageRunIds(options.agentId),
-	});
-	rememberCursorBilledUsageRunIds(options.agentId, selected.runIds);
-	return { agentUsage, turn: selected.turn };
-}
-
-export const __testUtils = {
-	reset(): void {
-		seenBilledRunIdsByAgent.clear();
-	},
-};

package/src/cursor-sdk-event-debug-session.ts

@@ -7,7 +7,7 @@ import {
 	SESSION_MANIFEST,
 	resolveCursorSdkEventDebugBaseDir,
 } from "./cursor-sdk-event-debug-constants.js";
-import { getCursorSessionFile, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, type CursorTurnScope } from "./cursor-session-scope.js";
 
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 
@@ -93,13 +93,14 @@ function resolveSessionDebugDir(
 export function allocateCursorSdkEventDebugTurn(
 	cwd: string,
 	env: Record<string, string | undefined>,
+	scope: CursorTurnScope = getCursorSessionScopeSnapshot(),
 ): CursorSdkEventDebugTurnAllocation {
 	const pinnedRunDir = resolvePinnedRunArtifactDir(env[CURSOR_SDK_EVENT_DEBUG_RUN_DIR_ENV]);
 	if (pinnedRunDir) {
 		return { artifactDir: pinnedRunDir, pinnedRun: true };
 	}
 
-	const scopeKey = getCursorSessionScopeKey();
+	const scopeKey = scope.scopeKey;
 	const sessionDir = resolveSessionDebugDir(cwd, env, scopeKey);
 	mkdirSync(sessionDir, { recursive: true });
 
@@ -118,13 +119,13 @@ export function allocateCursorSdkEventDebugTurn(
 	const existing = readSessionManifest(sessionDir);
 	const manifest: CursorSdkEventDebugSessionManifest = existing ?? {
 		sessionKey: scopeKey,
-		sessionFile: getCursorSessionFile(),
+		sessionFile: scope.sessionFile,
 		sessionDir,
 		createdAt: new Date().toISOString(),
 		updatedAt: new Date().toISOString(),
 		turns: [],
 	};
-	manifest.sessionFile = getCursorSessionFile();
+	manifest.sessionFile = scope.sessionFile;
 	manifest.updatedAt = new Date().toISOString();
 	manifest.turns.push({
 		turn: state.turnCounter,
@@ -154,7 +155,6 @@ export function updateCursorSdkEventDebugSessionManifest(
 	turnEntry.finalizedAt = new Date().toISOString();
 	turnEntry.summary = summary;
 	manifest.updatedAt = new Date().toISOString();
-	manifest.sessionFile = getCursorSessionFile();
 	writeSessionManifest(sessionDir, manifest);
 }
 

package/src/cursor-sdk-event-debug.ts

@@ -8,7 +8,7 @@ import { serializeCursorPiToolBridgeDiagnostic } from "./cursor-pi-tool-bridge-d
 import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge-types.js";
 import type { CursorLiveQueuedEvent } from "./cursor-live-run-coordinator.js";
 import { asRecord } from "./cursor-record-utils.js";
-import { getCursorSessionFile } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, type CursorTurnScope } from "./cursor-session-scope.js";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import {
 	ARTIFACTS,
@@ -58,6 +58,7 @@ export interface CursorSdkDisplayDecisionRecord {
 }
 
 export interface CursorSdkEventDebugSinkOptions {
+	scope?: CursorTurnScope;
 	cwd: string;
 	modelId: string;
 	provider: string;
@@ -250,6 +251,7 @@ export class CursorSdkEventDebugSink {
 		timeline: {} as Record<string, number>,
 		errors: 0,
 	};
+	private readonly sessionFile: string | undefined;
 	private metadata: Record<string, unknown>;
 	private readonly jsonlBuffers = new Map<string, string[]>();
 	private readonly jsonlBufferBytes = new Map<string, number>();
@@ -263,8 +265,9 @@ export class CursorSdkEventDebugSink {
 	static maybeCreate(options: CursorSdkEventDebugSinkOptions): CursorSdkEventDebugSink | undefined {
 		const env = options.env ?? process.env;
 		if (!resolveCursorSdkEventDebugEnabled(env)) return undefined;
-		const allocation = allocateCursorSdkEventDebugTurn(options.cwd, env);
-		return new CursorSdkEventDebugSink(allocation, options, env);
+		const scope = options.scope ?? getCursorSessionScopeSnapshot();
+		const allocation = allocateCursorSdkEventDebugTurn(options.cwd, env, scope);
+		return new CursorSdkEventDebugSink(allocation, { ...options, scope }, env);
 	}
 
 	private constructor(
@@ -278,6 +281,7 @@ export class CursorSdkEventDebugSink {
 		this.sessionKey = allocation.sessionKey;
 		this.pinnedRun = allocation.pinnedRun;
 		this.env = env;
+		this.sessionFile = options.scope?.sessionFile;
 		this.metadata = {
 			capturedAt: new Date().toISOString(),
 			modelId: options.modelId,
@@ -285,7 +289,7 @@ export class CursorSdkEventDebugSink {
 			cwd: options.cwd,
 			sessionDir: allocation.sessionDir,
 			sessionKey: allocation.sessionKey,
-			sessionFile: getCursorSessionFile(),
+			sessionFile: this.sessionFile,
 			turn: allocation.turn,
 			pinnedRun: allocation.pinnedRun,
 			artifacts: ARTIFACTS,
@@ -452,7 +456,7 @@ export class CursorSdkEventDebugSink {
 	}
 
 	private capturePiSessionSnapshot(): { copied: boolean; sessionFile?: string; reason?: string } {
-		const sessionFile = getCursorSessionFile();
+		const sessionFile = this.sessionFile;
 		if (!sessionFile) {
 			return { copied: false, reason: "session file unknown" };
 		}
@@ -509,7 +513,7 @@ export class CursorSdkEventDebugSink {
 			artifactDir: this.artifactDir,
 			sessionDir: this.sessionDir,
 			sessionKey: this.sessionKey,
-			sessionFile: getCursorSessionFile(),
+			sessionFile: this.sessionFile,
 			turn: this.turn,
 			elapsedMs: Date.now() - this.startedAt,
 			counts: {

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

@@ -1,7 +1,9 @@
 export {
 	CURSOR_SDK_STARTUP_NOISE_PATTERNS,
+	withCursorSdkOutputNoticeHandler,
 	installCursorSdkOutputFilter,
 	isCursorSdkOutputSuppressed,
 	isCursorSdkStartupNoise,
 	suppressCursorSdkOutput,
 } from "../shared/cursor-sdk-output-filter.mjs";
+export type { CursorSdkCapabilityNotice, CursorSdkOutputNoticeHandler } from "../shared/cursor-sdk-output-filter.mjs";

package/src/cursor-sdk-process-error-guard.ts

@@ -23,7 +23,7 @@ type GenericProcessEmit = (event: string | symbol, ...args: unknown[]) => boolea
 // ConnectRPC suppression remains scoped to active provider turns.
 const activeProviderTurns = new Set<CursorSdkProcessErrorGuardToken>();
 const activeSessions = new Set<CursorSdkSessionProcessErrorGuardToken>();
-let activeLifecycleSessionGuard: CursorSdkSessionProcessErrorGuard | undefined;
+const lifecycleSessionGuards = new Map<object, CursorSdkSessionProcessErrorGuard>();
 let originalProcessEmit: GenericProcessEmit | undefined;
 let cursorProcessEmit: GenericProcessEmit | undefined;
 let bunUnhandledRejectionListenerInstalled = false;
@@ -40,7 +40,7 @@ function hasActiveAbortSuppression(): boolean {
 }
 
 function isCursorProvenance(source: string): boolean {
-	return source === "cursor-sdk-stack" || source === "cursor-extension-connect-stack" || source === "cursor-backend-details";
+	return source === "cursor-sdk-stack" || source === "cursor-backend-details";
 }
 
 function isCursorSdkWriteIterableClosedError(error: unknown): boolean {
@@ -83,7 +83,6 @@ function shouldSuppressProcessError(event: string | symbol, args: readonly unkno
 	if (!classification) return false;
 	if (classification.kind === "abort") return hasActiveAbortSuppression();
 	if (activeProviderTurns.size === 0) return false;
-	if (classification.kind === "network") return isCursorProvenance(classification.source) || classification.source === "connect-node-stack";
 	return isCursorProvenance(classification.source);
 }
 
@@ -143,8 +142,8 @@ export const __testUtils = {
 	activeProviderTurnCount: (): number => activeProviderTurns.size,
 	activeSessionCount: (): number => activeSessions.size,
 	resetLifecycleSessionGuard(): void {
-		activeLifecycleSessionGuard?.dispose();
-		activeLifecycleSessionGuard = undefined;
+		for (const guard of lifecycleSessionGuards.values()) guard.dispose();
+		lifecycleSessionGuards.clear();
 	},
 };
 
@@ -186,11 +185,11 @@ export function installCursorSdkSessionProcessErrorGuard(): CursorSdkSessionProc
 
 export function registerCursorSdkSessionProcessErrorGuard(pi: Pick<ExtensionAPI, "on">): void {
 	pi.on("session_start", () => {
-		activeLifecycleSessionGuard?.dispose();
-		activeLifecycleSessionGuard = installCursorSdkSessionProcessErrorGuard();
+		lifecycleSessionGuards.get(pi)?.dispose();
+		lifecycleSessionGuards.set(pi, installCursorSdkSessionProcessErrorGuard());
 	});
 	pi.on("session_shutdown", () => {
-		activeLifecycleSessionGuard?.dispose();
-		activeLifecycleSessionGuard = undefined;
+		lifecycleSessionGuards.get(pi)?.dispose();
+		lifecycleSessionGuards.delete(pi);
 	});
 }

package/src/cursor-sdk-runtime.ts

@@ -1,5 +1,18 @@
-export type CursorSdkModule = typeof import("@cursor/sdk");
+// Vendor env must initialize before the static @cursor/sdk import below so
+// tree-sitter natives resolve when Pi lives outside this package's node_modules.
+import "./cursor-sdk-vendor-env.js";
+import * as CursorSdk from "@cursor/sdk";
 
+export type CursorSdkModule = typeof CursorSdk;
+
+/**
+ * Load the Cursor SDK module.
+ *
+ * Uses a static import so Pi's compiled-Bun extension graph includes @cursor/sdk
+ * (a runtime dynamic bare import is omitted from that graph; see #228).
+ * `loadCursorSdk` remains async for call-site compatibility and so vendor-env
+ * side effects (imported above) always run before callers receive the module.
+ */
 export async function loadCursorSdk(): Promise<CursorSdkModule> {
-	return import("@cursor/sdk");
+	return CursorSdk;
 }

package/src/cursor-sdk-vendor-env.ts

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCursorSdkPlatformPackageDirectory } from "./cursor-ripgrep-path.js";
+
+/**
+ * Ensure CURSOR_TREE_SITTER_VENDOR_DIR is set before @cursor/sdk first loads.
+ * Must run as a side effect of importing this module (before a static SDK import).
+ */
+export function ensureCursorTreeSitterVendorDir(): void {
+	if (process.env.CURSOR_TREE_SITTER_VENDOR_DIR !== undefined) return;
+	const packageDirectory = resolveCursorSdkPlatformPackageDirectory();
+	if (!packageDirectory) return;
+	const vendor = join(packageDirectory, "vendor");
+	if (
+		existsSync(join(vendor, "tree-sitter", "index.js")) &&
+		existsSync(join(vendor, "tree-sitter-bash", "index.js"))
+	) {
+		process.env.CURSOR_TREE_SITTER_VENDOR_DIR = vendor;
+	}
+}
+
+ensureCursorTreeSitterVendorDir();