pi-cursor-sdk 0.1.36 → 0.1.38

package/src/cursor-replay-tool-details.ts

@@ -1,3 +1,4 @@
+import { asRecord, getBoolean, getNumber, getString } from "./cursor-record-utils.js";
 import { isCursorReplayActivitySourceName, type CursorReplayActivitySourceName } from "./cursor-replay-source-names.js";
 
 /** Replay detail variants keyed by replay card disposition, not SDK source tool alone. */
@@ -55,8 +56,6 @@ export interface CursorReplayGenerateImageDetails {
 	imageMimeType?: string;
 	summary?: string;
 	expandedText?: string;
-	/** Legacy parsed title retained on older payloads; display always uses `Cursor generateImage`. */
-	title?: string;
 	collapseDetailsByDefault?: boolean;
 }
 
@@ -79,7 +78,7 @@ export interface CursorReplayActivityDetails {
 	fileContentAfterWrite?: string;
 }
 
-/** Parsed replay details without a display title (legacy or malformed payloads). */
+/** Parsed replay details without a display title. */
 export interface CursorReplayGenericFallbackDetails {
 	variant: "genericFallback";
 	sourceToolName: CursorReplayUnknownSourceToolName;
@@ -94,21 +93,6 @@ export type CursorReplayToolDetails =
 	| CursorReplayActivityDetails
 	| CursorReplayGenericFallbackDetails;
 
-/** @deprecated Use {@link CursorReplayNativeEditDetails}. */
-export type CursorReplayEditDetails = CursorReplayNativeEditDetails;
-
-/** @deprecated Use {@link CursorReplayNativeWriteDetails}. */
-export type CursorReplayWriteDetails = CursorReplayNativeWriteDetails;
-
-/** @deprecated Use {@link CursorReplayActivityDetails}. */
-export type CursorReplayTitledActivityDetails = CursorReplayActivityDetails;
-
-/** @deprecated Use {@link CursorReplayActivitySourceToolName}. */
-export type CursorReplayActivityCursorToolName = CursorReplayActivitySourceToolName;
-
-/** @deprecated Use {@link CursorReplayUnknownSourceToolName}. */
-export type CursorReplayUnknownCursorToolName = CursorReplayUnknownSourceToolName;
-
 export type CursorReplayActivityDetailFields = Pick<
 	CursorReplayActivityDetails,
 	| "summary"
@@ -128,79 +112,51 @@ export type CursorReplayGenerateImageDetailFields = Pick<
 	"summary" | "expandedText" | "imagePath" | "imageDisplayPath" | "imageMimeType"
 >;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function readOptionalString(record: Record<string, unknown>, key: string): string | undefined {
-	const value = record[key];
-	return typeof value === "string" ? value : undefined;
-}
-
-function readOptionalNumber(record: Record<string, unknown>, key: string): number | undefined {
-	const value = record[key];
-	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
-
-function readOptionalBoolean(record: Record<string, unknown>, key: string): boolean | undefined {
-	const value = record[key];
-	return typeof value === "boolean" ? value : undefined;
-}
-
-function readCurrentSourceToolName(record: Record<string, unknown>): string | undefined {
-	const sourceToolName = readOptionalString(record, "sourceToolName");
+function readSourceToolName(record: Record<string, unknown>): string | undefined {
+	const sourceToolName = getString(record, "sourceToolName");
 	return sourceToolName?.trim() ? sourceToolName.trim() : undefined;
 }
 
-function readLegacySourceToolName(record: Record<string, unknown>): string | undefined {
-	const sourceToolName = readCurrentSourceToolName(record);
-	if (sourceToolName) return sourceToolName;
-	const cursorToolName = readOptionalString(record, "cursorToolName");
-	return cursorToolName?.trim() ? cursorToolName.trim() : undefined;
-}
-
-function readLegacyVariant(record: Record<string, unknown>): string | undefined {
-	const variant = readOptionalString(record, "variant");
+function readVariant(record: Record<string, unknown>): string | undefined {
+	const variant = getString(record, "variant");
 	return variant?.trim() ? variant.trim() : undefined;
 }
 
 function parseCursorReplayNativeEditDetails(record: Record<string, unknown>): CursorReplayNativeEditDetails {
 	return {
 		variant: "nativeEdit",
-		path: readOptionalString(record, "path"),
-		linesAdded: readOptionalNumber(record, "linesAdded"),
-		linesRemoved: readOptionalNumber(record, "linesRemoved"),
-		diffString: readOptionalString(record, "diffString"),
-		diff: readOptionalString(record, "diff"),
-		firstChangedLine: readOptionalNumber(record, "firstChangedLine"),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
+		path: getString(record, "path"),
+		linesAdded: getNumber(record, "linesAdded"),
+		linesRemoved: getNumber(record, "linesRemoved"),
+		diffString: getString(record, "diffString"),
+		diff: getString(record, "diff"),
+		firstChangedLine: getNumber(record, "firstChangedLine"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
 	};
 }
 
 function parseCursorReplayNativeWriteDetails(record: Record<string, unknown>): CursorReplayNativeWriteDetails {
 	return {
 		variant: "nativeWrite",
-		path: readOptionalString(record, "path"),
-		linesCreated: readOptionalNumber(record, "linesCreated"),
-		fileSize: readOptionalNumber(record, "fileSize"),
-		fileContentAfterWrite: readOptionalString(record, "fileContentAfterWrite"),
-		expandedText: readOptionalString(record, "expandedText"),
-		summary: readOptionalString(record, "summary"),
+		path: getString(record, "path"),
+		linesCreated: getNumber(record, "linesCreated"),
+		fileSize: getNumber(record, "fileSize"),
+		fileContentAfterWrite: getString(record, "fileContentAfterWrite"),
+		expandedText: getString(record, "expandedText"),
+		summary: getString(record, "summary"),
 	};
 }
 
 function parseCursorReplayGenerateImageDetails(record: Record<string, unknown>): CursorReplayGenerateImageDetails {
-	const title = readOptionalString(record, "title");
-	const collapseDetailsByDefault = readOptionalBoolean(record, "collapseDetailsByDefault");
+	const collapseDetailsByDefault = getBoolean(record, "collapseDetailsByDefault");
 	return {
 		variant: "generateImage",
-		imagePath: readOptionalString(record, "imagePath"),
-		imageDisplayPath: readOptionalString(record, "imageDisplayPath"),
-		imageMimeType: readOptionalString(record, "imageMimeType"),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
-		...(title !== undefined ? { title } : {}),
+		imagePath: getString(record, "imagePath"),
+		imageDisplayPath: getString(record, "imageDisplayPath"),
+		imageMimeType: getString(record, "imageMimeType"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
 		...(collapseDetailsByDefault !== undefined ? { collapseDetailsByDefault } : {}),
 	};
 }
@@ -214,16 +170,16 @@ function parseCursorReplayActivityDetails(
 		variant: "activity",
 		sourceToolName,
 		title,
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
-		collapseDetailsByDefault: readOptionalBoolean(record, "collapseDetailsByDefault"),
-		path: readOptionalString(record, "path"),
-		fileSize: readOptionalNumber(record, "fileSize"),
-		diffString: readOptionalString(record, "diffString"),
-		diff: readOptionalString(record, "diff"),
-		linesAdded: readOptionalNumber(record, "linesAdded"),
-		linesRemoved: readOptionalNumber(record, "linesRemoved"),
-		fileContentAfterWrite: readOptionalString(record, "fileContentAfterWrite"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
+		collapseDetailsByDefault: getBoolean(record, "collapseDetailsByDefault"),
+		path: getString(record, "path"),
+		fileSize: getNumber(record, "fileSize"),
+		diffString: getString(record, "diffString"),
+		diff: getString(record, "diff"),
+		linesAdded: getNumber(record, "linesAdded"),
+		linesRemoved: getNumber(record, "linesRemoved"),
+		fileContentAfterWrite: getString(record, "fileContentAfterWrite"),
 	};
 }
 
@@ -238,8 +194,8 @@ function parseCursorReplayGenericFallbackDetails(
 	return {
 		variant: "genericFallback",
 		sourceToolName: brandCursorReplayUnknownSourceToolName(sourceToolName),
-		summary: readOptionalString(record, "summary"),
-		expandedText: readOptionalString(record, "expandedText"),
+		summary: getString(record, "summary"),
+		expandedText: getString(record, "expandedText"),
 	};
 }
 
@@ -263,38 +219,8 @@ export function resolveIncompleteReplayActivitySourceToolName(
 	return resolveParseActivitySourceToolName(sourceToolName);
 }
 
-function hasNativeEditChanges(record: Record<string, unknown>): boolean {
-	return Boolean(
-		readOptionalString(record, "diffString")?.trim()
-		|| readOptionalString(record, "diff")?.trim()
-		|| readOptionalNumber(record, "linesAdded")
-		|| readOptionalNumber(record, "linesRemoved"),
-	);
-}
-
-function parseLegacyEditDetails(record: Record<string, unknown>): CursorReplayToolDetails {
-	const title = readOptionalString(record, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(record, resolveParseActivitySourceToolName("edit"), title);
-	}
-	return parseCursorReplayNativeEditDetails(record);
-}
-
-function parseLegacyWriteDetails(record: Record<string, unknown>): CursorReplayToolDetails {
-	const title = readOptionalString(record, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(record, resolveParseActivitySourceToolName("write"), title);
-	}
-	return parseCursorReplayNativeWriteDetails(record);
-}
-
-type CursorReplayVariantParser = (record: Record<string, unknown>) => CursorReplayToolDetails | undefined;
-
-function parseActivityVariantDetails(
-	record: Record<string, unknown>,
-	readSourceToolName: (record: Record<string, unknown>) => string | undefined,
-): CursorReplayActivityDetails | undefined {
-	const title = readOptionalString(record, "title")?.trim();
+function parseActivityVariantDetails(record: Record<string, unknown>): CursorReplayActivityDetails | undefined {
+	const title = getString(record, "title")?.trim();
 	if (!title) return undefined;
 	return parseCursorReplayActivityDetails(
 		record,
@@ -303,79 +229,25 @@ function parseActivityVariantDetails(
 	);
 }
 
-const CURRENT_REPLAY_VARIANT_PARSERS: Readonly<Record<CursorReplayToolDetailsVariant, CursorReplayVariantParser>> = {
-	nativeEdit: parseCursorReplayNativeEditDetails,
-	nativeWrite: parseCursorReplayNativeWriteDetails,
-	generateImage: parseCursorReplayGenerateImageDetails,
-	activity: (record) => {
-		if (!readCurrentSourceToolName(record) && readOptionalString(record, "cursorToolName")?.trim()) return undefined;
-		return parseActivityVariantDetails(record, readCurrentSourceToolName);
-	},
-	genericFallback: (record) => parseCursorReplayGenericFallbackDetails(record, readCurrentSourceToolName(record) ?? "tool"),
-};
-
-const LEGACY_REPLAY_VARIANT_UPGRADERS: Readonly<Record<string, CursorReplayVariantParser>> = {
-	edit: parseLegacyEditDetails,
-	write: parseLegacyWriteDetails,
-	titledActivity: (record) => parseActivityVariantDetails(record, readLegacySourceToolName),
-};
-
-export function parseStrictCurrentCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	if (!isRecord(value)) return undefined;
-	const variant = readLegacyVariant(value);
-	if (!variant) return undefined;
-	return CURRENT_REPLAY_VARIANT_PARSERS[variant as CursorReplayToolDetailsVariant]?.(value);
-}
-
-export function upgradeLegacyCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	if (!isRecord(value)) return undefined;
-	const explicitVariant = readLegacyVariant(value);
-	if (explicitVariant) {
-		return LEGACY_REPLAY_VARIANT_UPGRADERS[explicitVariant]?.(value);
-	}
-	const sourceToolName = readLegacySourceToolName(value);
-	if (sourceToolName === "edit") return parseLegacyEditDetails(value);
-	if (sourceToolName === "write") return parseLegacyWriteDetails(value);
-	if (sourceToolName === "generateImage") return parseCursorReplayGenerateImageDetails(value);
-	const title = readOptionalString(value, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(
-			value,
-			resolveParseActivitySourceToolName(sourceToolName ?? CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME),
-			title,
-		);
-	}
-	if (sourceToolName === undefined && hasNativeEditChanges(value)) {
-		return parseCursorReplayNativeEditDetails(value);
-	}
-	return undefined;
-}
-
 export function parseCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	return parseStrictCurrentCursorReplayToolDetails(value) ?? upgradeLegacyCursorReplayToolDetails(value);
-}
-
-/** @deprecated Prefer {@link parseCursorReplayToolDetails} for validated narrowing. */
-export const asCursorReplayToolDetails = parseCursorReplayToolDetails;
-
-export function buildCursorReplayNativeEditDetails(
-	fields: Omit<CursorReplayNativeEditDetails, "variant">,
-): CursorReplayNativeEditDetails {
-	return { variant: "nativeEdit", ...fields };
-}
-
-/** @deprecated Prefer {@link buildCursorReplayNativeEditDetails}. */
-export const buildCursorReplayEditDetails = buildCursorReplayNativeEditDetails;
-
-export function buildCursorReplayNativeWriteDetails(
-	fields: Omit<CursorReplayNativeWriteDetails, "variant">,
-): CursorReplayNativeWriteDetails {
-	return { variant: "nativeWrite", ...fields };
+	const record = asRecord(value);
+	if (!record) return undefined;
+	switch (readVariant(record)) {
+		case "nativeEdit":
+			return parseCursorReplayNativeEditDetails(record);
+		case "nativeWrite":
+			return parseCursorReplayNativeWriteDetails(record);
+		case "generateImage":
+			return parseCursorReplayGenerateImageDetails(record);
+		case "activity":
+			return parseActivityVariantDetails(record);
+		case "genericFallback":
+			return parseCursorReplayGenericFallbackDetails(record, readSourceToolName(record) ?? "tool");
+		default:
+			return undefined;
+	}
 }
 
-/** @deprecated Prefer {@link buildCursorReplayNativeWriteDetails}. */
-export const buildCursorReplayWriteDetails = buildCursorReplayNativeWriteDetails;
-
 export function assembleCursorReplayActivityDetails(
 	sourceToolName: CursorReplayActivitySourceToolName,
 	title: string,
@@ -402,10 +274,7 @@ export function assembleCursorReplayActivityDetails(
 	};
 }
 
-/** @deprecated Prefer {@link assembleCursorReplayActivityDetails}. */
-export const assembleCursorReplayTitledActivityDetails = assembleCursorReplayActivityDetails;
-
-export const CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE = "Cursor generateImage" as const;
+export const CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE = "Cursor image generation" as const;
 
 export function assembleCursorReplayGenerateImageDetails(
 	fields: CursorReplayGenerateImageDetailFields,
@@ -430,18 +299,12 @@ export function isCursorReplayNativeEditDetails(
 	return details.variant === "nativeEdit";
 }
 
-/** @deprecated Prefer {@link isCursorReplayNativeEditDetails}. */
-export const isCursorReplayEditDetails = isCursorReplayNativeEditDetails;
-
 export function isCursorReplayNativeWriteDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayNativeWriteDetails {
 	return details.variant === "nativeWrite";
 }
 
-/** @deprecated Prefer {@link isCursorReplayNativeWriteDetails}. */
-export const isCursorReplayWriteDetails = isCursorReplayNativeWriteDetails;
-
 export function isCursorReplayGenerateImageDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayGenerateImageDetails {
@@ -454,9 +317,6 @@ export function isCursorReplayActivityDetails(
 	return details.variant === "activity";
 }
 
-/** @deprecated Prefer {@link isCursorReplayActivityDetails}. */
-export const isCursorReplayTitledActivityDetails = isCursorReplayActivityDetails;
-
 export function isCursorReplayGenericFallbackDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayGenericFallbackDetails {

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

@@ -7,6 +7,7 @@ import type { CursorPiToolBridgeDiagnosticEvent } from "./cursor-pi-tool-bridge-
 import { serializeCursorPiToolBridgeDiagnostic } from "./cursor-pi-tool-bridge-diagnostics.js";
 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 { parseEnvBoolean } from "./cursor-env-boolean.js";
 import {
@@ -93,11 +94,10 @@ interface CursorSdkRunLike {
 }
 
 function eventType(value: unknown): string {
-	if (value && typeof value === "object") {
-		if ("type" in value && typeof value.type === "string") return value.type;
-		if ("event" in value && typeof value.event === "string") return value.event;
-		if ("kind" in value && typeof value.kind === "string") return value.kind;
-	}
+	const record = asRecord(value);
+	if (typeof record?.type === "string") return record.type;
+	if (typeof record?.event === "string") return record.event;
+	if (typeof record?.kind === "string") return record.kind;
 	return "unknown";
 }
 
@@ -106,7 +106,7 @@ function resolveCursorSdkEventDebugStderrEnabled(env: Record<string, string | un
 }
 
 function isNodeErrorWithCode(error: unknown, code: string): boolean {
-	return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === code;
+	return asRecord(error)?.code === code;
 }
 
 function snapshotCursorSdkEventDebugRecord(record: unknown): unknown {

package/src/cursor-sensitive-text.ts

@@ -1,3 +1,4 @@
+import { asRecord } from "./cursor-record-utils.js";
 import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 /** Provider-facing wrapper; canonical scrubbing lives in shared/cursor-sensitive-text.mjs. */
 import { scrubSensitiveText as scrubSensitiveTextJs } from "../shared/cursor-sensitive-text.mjs";
@@ -9,10 +10,9 @@ export function scrubSensitiveText(text: string, apiKey?: string): string {
 function scrubDisplayValue(value: unknown, apiKey?: string): unknown {
 	if (typeof value === "string") return scrubSensitiveText(value, apiKey);
 	if (Array.isArray(value)) return value.map((entry) => scrubDisplayValue(entry, apiKey));
-	if (value && typeof value === "object") {
-		return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
-	}
-	return value;
+	const record = asRecord(value);
+	if (!record) return value;
+	return Object.fromEntries(Object.entries(record).map(([key, entry]) => [key, scrubDisplayValue(entry, apiKey)]));
 }
 
 export function scrubPiToolDisplay(display: CursorPiToolDisplay, apiKey?: string): CursorPiToolDisplay {

package/src/cursor-session-agent-lifecycle.ts

@@ -0,0 +1,47 @@
+import type {
+	ExtensionHandler,
+	SessionBeforeTreeEvent,
+	SessionCompactEvent,
+	SessionShutdownEvent,
+	SessionTreeEvent,
+} from "@earendil-works/pi-coding-agent";
+import { onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+
+export interface CursorSessionAgentLifecycleExtensionApi {
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "model_select", handler: () => Promise<void> | void): void;
+}
+
+export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
+	onCursorSessionScopeKeyChange(async (previousScopeKey) => {
+		const { disposeSessionCursorAgent } = await import("./cursor-session-agent.js");
+		await disposeSessionCursorAgent(previousScopeKey);
+	});
+	pi.on("session_shutdown", async (event) => {
+		const { disposeSessionCursorAgent, resetSessionCursorAgent } = await import("./cursor-session-agent.js");
+		if (event.reason === "reload") {
+			await resetSessionCursorAgent();
+			return;
+		}
+		await disposeSessionCursorAgent();
+	});
+	pi.on("session_compact", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+	pi.on("session_before_tree", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+	pi.on("session_tree", async () => {
+		const { resetSessionCursorAgent } = await import("./cursor-session-agent.js");
+		await resetSessionCursorAgent();
+	});
+	pi.on("model_select", async () => {
+		const { invalidateSessionAgent } = await import("./cursor-session-agent.js");
+		invalidateSessionAgent();
+	});
+}

package/src/cursor-session-agent.ts

@@ -1,10 +1,3 @@
-import type {
-	ExtensionHandler,
-	SessionBeforeTreeEvent,
-	SessionCompactEvent,
-	SessionShutdownEvent,
-	SessionTreeEvent,
-} from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
 import type { AgentModeOption, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
@@ -14,7 +7,7 @@ import {
 	type CursorPiToolBridgeRun,
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
-import { getCursorSessionScopeKey, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import { getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 import { loadCursorSdk, type CursorSdkModule } from "./cursor-sdk-runtime.js";
 
@@ -88,9 +81,12 @@ export class SessionCursorAgentScopeClosedError extends Error {
 }
 
 function assertScopeAcceptsAcquire(scopeKey: string): void {
-	if (terminalDisposedScopeKeys.has(scopeKey)) {
+	const terminalGeneration = terminalDisposedScopeGenerations.get(scopeKey);
+	if (terminalGeneration === undefined) return;
+	if (terminalGeneration >= getCursorSessionScopeGeneration(scopeKey)) {
 		throw new SessionCursorAgentScopeClosedError();
 	}
+	terminalDisposedScopeGenerations.delete(scopeKey);
 }
 
 function rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey: string, poolKey: string, error: unknown): void {
@@ -112,17 +108,9 @@ interface SessionCursorAgentCreateParams {
 	createAgent?: CursorSdkModule["Agent"]["create"];
 }
 
-interface CursorSessionAgentExtensionApi {
-	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
-	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
-	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent>): void;
-	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
-	on(event: "model_select", handler: ExtensionHandler<{ model: unknown }>): void;
-}
-
 const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
 const invalidatedScopeKeys = new Set<string>();
-const terminalDisposedScopeKeys = new Set<string>();
+const terminalDisposedScopeGenerations = new Map<string, number>();
 const scopeCreationGenerations = new Map<string, number>();
 const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
 let nextSessionAgentInstanceId = 1;
@@ -194,7 +182,7 @@ async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<voi
 async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?: boolean }): Promise<void> {
 	invalidateScopeCreations(scopeKey);
 	if (options?.terminal) {
-		terminalDisposedScopeKeys.add(scopeKey);
+		terminalDisposedScopeGenerations.set(scopeKey, getCursorSessionScopeGeneration(scopeKey));
 	}
 	const entry = sessionAgentsByScope.get(scopeKey);
 	invalidatedScopeKeys.delete(scopeKey);
@@ -416,7 +404,6 @@ export {
 	planCursorSessionSend,
 	type CursorSessionSendPlan,
 } from "./cursor-session-send-policy.js";
-export { shouldBootstrapCursorContext, shouldBootstrapCursorSend } from "./context.js";
 
 export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeKey()): void {
 	invalidatedScopeKeys.add(scopeKey);
@@ -526,35 +513,10 @@ export async function disposeSessionCursorAgent(scopeKey: string = getCursorSess
 }
 
 export async function disposeAllSessionCursorAgents(): Promise<void> {
-	const scopeKeys = [...new Set([...sessionAgentsByScope.keys(), ...terminalDisposedScopeKeys])];
+	const scopeKeys = [...new Set([...sessionAgentsByScope.keys(), ...terminalDisposedScopeGenerations.keys()])];
 	await Promise.all(scopeKeys.map((scopeKey) => disposePoolEntryForScope(scopeKey, { terminal: true })));
 	invalidatedScopeKeys.clear();
-	terminalDisposedScopeKeys.clear();
-}
-
-export function registerCursorSessionAgent(_pi: CursorSessionAgentExtensionApi): void {
-	onCursorSessionScopeKeyChange((previousScopeKey) => {
-		void disposePoolEntryForScope(previousScopeKey, { terminal: true });
-	});
-	_pi.on("session_shutdown", async (event) => {
-		if (event.reason === "reload") {
-			await resetSessionCursorAgent();
-			return;
-		}
-		await disposeSessionCursorAgent();
-	});
-	_pi.on("session_compact", () => {
-		invalidateSessionAgent();
-	});
-	_pi.on("session_before_tree", () => {
-		invalidateSessionAgent();
-	});
-	_pi.on("session_tree", async () => {
-		await resetSessionCursorAgent();
-	});
-	_pi.on("model_select", () => {
-		invalidateSessionAgent();
-	});
+	terminalDisposedScopeGenerations.clear();
 }
 
 export const __testUtils = {

package/src/cursor-session-scope.ts

@@ -7,14 +7,17 @@ interface CursorSessionScopeExtensionApi {
 const ANONYMOUS_SESSION_SCOPE_KEY = "__anonymous__";
 const EPHEMERAL_SESSION_SCOPE_PREFIX = "__ephemeral__:";
 
-type CursorSessionScopeChangeHandler = (previousScopeKey: string) => void;
+type CursorSessionScopeChangeHandler = (previousScopeKey: string) => Promise<void> | void;
 
 const state = {
 	sessionCwd: process.cwd(),
 	sessionFile: undefined as string | undefined,
 	sessionId: undefined as string | undefined,
+	sessionGeneration: 0,
 };
 
+const scopeGenerations = new Map<string, number>([[ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration]]);
+let nextSessionGeneration = 1;
 let scopeChangeHandler: CursorSessionScopeChangeHandler | undefined;
 
 /**
@@ -34,7 +37,16 @@ export function getCursorSessionScopeKey(): string {
 	return ANONYMOUS_SESSION_SCOPE_KEY;
 }
 
-export function getCursorSessionCwdFromScope(): string {
+export function getCursorSessionScopeGeneration(scopeKey: string = getCursorSessionScopeKey()): number {
+	return scopeGenerations.get(scopeKey) ?? 0;
+}
+
+/**
+ * Pi session cwd when known; falls back to process.cwd() before session_start.
+ * Updated on session_start only until pi threads cwd into streamSimple—mid-session cwd
+ * changes without a new session_start event are not reflected here.
+ */
+export function getCursorSessionCwd(): string {
 	return state.sessionCwd;
 }
 
@@ -42,12 +54,19 @@ function setCursorSessionScope(cwd: string, sessionFile: string | undefined, ses
 	state.sessionCwd = cwd;
 	state.sessionFile = sessionFile;
 	state.sessionId = sessionId;
+	state.sessionGeneration = nextSessionGeneration;
+	nextSessionGeneration += 1;
+	scopeGenerations.set(getCursorSessionScopeKey(), state.sessionGeneration);
 }
 
 function resetCursorSessionScope(): void {
 	state.sessionCwd = process.cwd();
 	state.sessionFile = undefined;
 	state.sessionId = undefined;
+	state.sessionGeneration = 0;
+	nextSessionGeneration = 1;
+	scopeGenerations.clear();
+	scopeGenerations.set(ANONYMOUS_SESSION_SCOPE_KEY, state.sessionGeneration);
 }
 
 export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeHandler): void {
@@ -55,7 +74,7 @@ export function onCursorSessionScopeKeyChange(handler: CursorSessionScopeChangeH
 }
 
 export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi): void {
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
 		const previousScopeKey = getCursorSessionScopeKey();
 		setCursorSessionScope(
 			ctx.cwd,
@@ -63,7 +82,7 @@ export function registerCursorSessionScope(pi: CursorSessionScopeExtensionApi):
 			ctx.sessionManager?.getSessionId?.() ?? undefined,
 		);
 		if (previousScopeKey !== getCursorSessionScopeKey()) {
-			scopeChangeHandler?.(previousScopeKey);
+			await scopeChangeHandler?.(previousScopeKey);
 		}
 	});
 }

package/src/cursor-setting-sources.ts

@@ -11,16 +11,16 @@ export function resolveCursorSettingSources(raw?: string): SettingSource[] | und
 	return resolveCursorSettingSourcesJs(raw) as SettingSource[] | undefined;
 }
 
-export function getEffectiveCursorSettingSources(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): SettingSource[] | undefined {
+export function getEffectiveCursorSettingSources(
+	raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV],
+): SettingSource[] | undefined {
 	return resolveCursorSettingSources(raw);
 }
 
-export function cursorSettingSourcesLoadUserAgentsRules(settingSources: SettingSource[] | undefined): boolean {
+export function cursorSettingSourcesIncludes(
+	settingSources: SettingSource[] | undefined,
+	source: Extract<SettingSource, "user" | "project">,
+): boolean {
 	if (!settingSources?.length) return false;
-	return settingSources.includes("all") || settingSources.includes("user");
-}
-
-export function cursorSettingSourcesLoadProjectAgentsRules(settingSources: SettingSource[] | undefined): boolean {
-	if (!settingSources?.length) return false;
-	return settingSources.includes("all") || settingSources.includes("project");
+	return settingSources.includes("all") || settingSources.includes(source);
 }