pi-cursor-sdk 0.4.0 → 0.5.2

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

@@ -4,7 +4,7 @@ import { asRecord, getString } from "./cursor-record-utils.js";
 import { fsyncExistingRegularFile } from "./cursor-durable-fs.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
 import {
 	CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE,
 	isCursorLocalAgentId,
@@ -16,9 +16,9 @@ import {
 	type CursorSessionAgentResumeScope,
 } from "./cursor-session-agent-resume.js";
 import {
-	cursorSessionStoreIdentitiesEqual,
-	getCursorSessionStoreIdentities,
+	withCursorSessionStoreIdentities,
 	openCursorSessionStore,
+	resolveCursorSessionStoreIdentity,
 } from "./cursor-session-store.js";
 
 export const CURSOR_SESSION_AGENT_CLEANUP_ENTRY_TYPE = "cursor-sdk-agent-cleanup";
@@ -96,7 +96,7 @@ function getCurrentCleanupScope(ctx: LocalResumeCleanupCommandContext): CursorSe
 	const sessionId = ctx.sessionManager.getSessionId();
 	const repoRoot = resolveCursorSessionRepoRoot(ctx.cwd);
 	return {
-		scopeKey: getCursorSessionScopeKey(),
+		scopeKey: cursorSessionScopeKeyForManager(ctx.sessionManager),
 		...(sessionFile ? { sessionFile } : {}),
 		...(sessionId ? { sessionId } : {}),
 		cwd: ctx.cwd,
@@ -264,7 +264,7 @@ function appendDurableCleanupEntry(
 	return fsyncExistingRegularFile(sessionFile);
 }
 
-export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext): Promise<void> {
+export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanupApi, args: string, ctx: LocalResumeCleanupCommandContext, storeRoot?: string): Promise<void> {
 	const usage = "Usage: /cursor-local-resume-cleanup [--dry-run|--yes]";
 	const tokens = args.trim().split(/\s+/).filter(Boolean);
 	const dryRun = tokens.length === 0 || (tokens.length === 1 && tokens[0] === "--dry-run");
@@ -299,7 +299,7 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 		return;
 	}
 
-	if (!appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
+	if (!scope.sessionFile || !appendDurableCleanupEntry(pi, ctx, { action: "delete", phase: "intent", ...baseEntry })) {
 		ctx.ui.notify("Cleanup intent could not be durably recorded. No agents were deleted.", "error");
 		return;
 	}
@@ -308,31 +308,32 @@ export async function runCursorSessionAgentCleanupCommand(pi: LocalResumeCleanup
 	const failedAgentIds: CursorSessionAgentCleanupFailure[] = [];
 	const openedStores = new Map<string, Awaited<ReturnType<typeof openCursorSessionStore>>>();
 	try {
-		const operations = await getSdkOperations();
-		const identities = await getCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, scope.sessionFile !== undefined);
-		for (const candidate of plan.candidates) {
-			const { agentId } = candidate;
-			try {
-				const identity = candidate.storeIdentity ?? identities.defaultStore;
-				if (
-					!cursorSessionStoreIdentitiesEqual(identity, identities.defaultStore) &&
-					!cursorSessionStoreIdentitiesEqual(identity, identities.sessionStore)
-				) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
-				let openedStore = openedStores.get(identity.stateRoot);
-				if (!openedStore) {
-					openedStore = await openCursorSessionStore(ctx.cwd, identity);
-					openedStores.set(identity.stateRoot, openedStore);
+		await withCursorSessionStoreIdentities(ctx.cwd, scope.scopeKey, storeRoot, async (identities) => {
+			const operations = await getSdkOperations();
+			for (const candidate of plan.candidates) {
+				const { agentId } = candidate;
+				try {
+					const identity = await resolveCursorSessionStoreIdentity({
+						cwd: ctx.cwd, scopeKey: scope.scopeKey,
+						identities, recordedIdentity: candidate.storeIdentity, agentId,
+					});
+					if (!identity) throw new InvalidCursorSessionStoreIdentityError("Recorded Cursor local store identity is not valid for this pi session");
+					let openedStore = openedStores.get(identity.stateRoot);
+					if (!openedStore) {
+						openedStore = await openCursorSessionStore(ctx.cwd, identity, identities.workspaceRoot, identities.storeRoot);
+						openedStores.set(identity.stateRoot, openedStore);
+					}
+					await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
+					deletedAgentIds.push(agentId);
+				} catch (error) {
+					failedAgentIds.push({
+						agentId,
+						error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
+						...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
+					});
 				}
-				await operations.delete(agentId, { cwd: ctx.cwd, store: openedStore.store });
-				deletedAgentIds.push(agentId);
-			} catch (error) {
-				failedAgentIds.push({
-					agentId,
-					error: scrubSensitiveText(getString(asRecord(error), "message") ?? String(error)),
-					...(error instanceof InvalidCursorSessionStoreIdentityError ? { retryable: false } : {}),
-				});
 			}
-		}
+		});
 	} catch (error) {
 		const message = scrubSensitiveText(getString(asRecord(error), "message") ?? String(error));
 		failedAgentIds.push(...plan.candidateAgentIds.map((agentId) => ({ agentId, error: message })));

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

@@ -4,9 +4,10 @@ import type {
 	SessionCompactEvent,
 	SessionShutdownEvent,
 	SessionTreeEvent,
+	SessionStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { clearCursorSdkHttp1 } from "./cursor-http1.js";
-import { onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import { cursorSessionScopeKeyForManager, hasLiveCursorSessions, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
 import {
 	disposeSessionCursorAgent,
 	invalidateSessionAgent,
@@ -14,6 +15,7 @@ import {
 } from "./cursor-session-agent.js";
 
 export interface CursorSessionAgentLifecycleExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
 	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;
@@ -22,30 +24,33 @@ export interface CursorSessionAgentLifecycleExtensionApi {
 }
 
 export function registerCursorSessionAgentLifecycle(pi: CursorSessionAgentLifecycleExtensionApi): void {
-	onCursorSessionScopeKeyChange(async (previousScopeKey) => {
+	let scopeKey: string | undefined;
+	pi.on("session_start", (_event, ctx) => { scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager); });
+	onCursorSessionScopeKeyChange(pi, async (previousScopeKey) => {
 		await disposeSessionCursorAgent(previousScopeKey);
 	});
 	pi.on("session_shutdown", async (event) => {
 		try {
+			if (scopeKey === undefined) return;
 			if (event.reason === "reload") {
-				await resetSessionCursorAgent();
+				await resetSessionCursorAgent(scopeKey);
 				return;
 			}
-			await disposeSessionCursorAgent();
+			await disposeSessionCursorAgent(scopeKey);
 		} finally {
-			clearCursorSdkHttp1();
+			if (!hasLiveCursorSessions()) clearCursorSdkHttp1();
 		}
 	});
 	pi.on("session_compact", () => {
-		invalidateSessionAgent();
+		if (scopeKey !== undefined) invalidateSessionAgent(scopeKey);
 	});
 	pi.on("session_before_tree", () => {
-		invalidateSessionAgent();
+		if (scopeKey !== undefined) invalidateSessionAgent(scopeKey);
 	});
 	pi.on("session_tree", async () => {
-		await resetSessionCursorAgent();
+		if (scopeKey !== undefined) await resetSessionCursorAgent(scopeKey);
 	});
 	pi.on("model_select", () => {
-		invalidateSessionAgent();
+		if (scopeKey !== undefined) invalidateSessionAgent(scopeKey);
 	});
 }

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

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { isCursorLocalAgentId } from "./cursor-session-agent-resume.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot } from "./cursor-session-scope.js";
 import { asRecord } from "./cursor-record-utils.js";
 
 export const CURSOR_SESSION_AGENT_LINEAGE_ENTRY_TYPE = "cursor-sdk-agent-lineage";
@@ -33,10 +33,12 @@ interface CursorSessionAgentLineageState {
 	recordedAgentIds: Set<string>;
 }
 
-const state: CursorSessionAgentLineageState = {
+let state: CursorSessionAgentLineageState = {
 	recordedAgentIds: new Set(),
 };
 
+const statesByScope = new Map<string, CursorSessionAgentLineageState>();
+
 export function parseCursorSessionAgentLineageEntryData(value: unknown): CursorSessionAgentLineageEntryData | undefined {
 	const record = asRecord(value);
 	if (
@@ -77,10 +79,14 @@ function readRecordedAgentIds(entries: readonly SessionEntry[], sessionId: strin
 }
 
 /** Best-effort forensic lineage at the local Agent.send() boundary. Independent of resume. */
-export function recordCursorSessionAgentLineage(agentId: string): void {
-	const { appendEntry, sessionId, sessionFile, scopeKey, cwd } = state;
+export function recordCursorSessionAgentLineage(agentId: string, turnScopeKey?: string): void {
+	const sessionState = turnScopeKey === undefined
+		? state
+		: statesByScope.get(turnScopeKey) ?? (state.scopeKey === turnScopeKey ? state : undefined);
+	if (!sessionState) return;
+	const { appendEntry, sessionId, sessionFile, scopeKey, cwd } = sessionState;
 	if (!appendEntry || !sessionId || !scopeKey || !cwd) return;
-	if (!isCursorLocalAgentId(agentId) || state.recordedAgentIds.has(agentId)) return;
+	if (!isCursorLocalAgentId(agentId) || sessionState.recordedAgentIds.has(agentId)) return;
 	const data: CursorSessionAgentLineageEntryData = {
 		version: LINEAGE_ENTRY_VERSION,
 		runtime: "local",
@@ -93,7 +99,7 @@ export function recordCursorSessionAgentLineage(agentId: string): void {
 	};
 	try {
 		appendEntry<CursorSessionAgentLineageEntryData>(CURSOR_SESSION_AGENT_LINEAGE_ENTRY_TYPE, data);
-		state.recordedAgentIds.add(agentId);
+		sessionState.recordedAgentIds.add(agentId);
 	} catch {
 		// Lineage is forensic metadata; a failed stock pi append must not affect the session.
 	}
@@ -105,15 +111,22 @@ interface CursorSessionAgentLineageExtensionApi {
 }
 
 export function registerCursorSessionAgentLineage(pi: CursorSessionAgentLineageExtensionApi): void {
+	const sessionState: CursorSessionAgentLineageState = { recordedAgentIds: new Set() };
 	pi.on("session_start", (_event, ctx) => {
-		state.appendEntry = pi.appendEntry;
-		state.sessionId = ctx.sessionManager.getSessionId();
-		state.sessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
-		state.scopeKey = getCursorSessionScopeKey();
-		state.cwd = ctx.cwd;
-		state.recordedAgentIds = readRecordedAgentIds(ctx.sessionManager.getEntries(), state.sessionId);
+		state = sessionState;
+		const record = sessionState;
+		if (record.scopeKey && statesByScope.get(record.scopeKey) === record) statesByScope.delete(record.scopeKey);
+		record.appendEntry = pi.appendEntry;
+		record.sessionId = ctx.sessionManager.getSessionId();
+		record.sessionFile = ctx.sessionManager.getSessionFile() ?? undefined;
+		record.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
+		statesByScope.set(record.scopeKey, record);
+		record.cwd = ctx.cwd;
+		record.recordedAgentIds = readRecordedAgentIds(ctx.sessionManager.getEntries(), record.sessionId);
 	});
 	pi.on("session_shutdown", () => {
+		const state = sessionState;
+		if (state.scopeKey && statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
 		state.appendEntry = undefined;
 		state.sessionId = undefined;
 		state.sessionFile = undefined;
@@ -124,6 +137,7 @@ export function registerCursorSessionAgentLineage(pi: CursorSessionAgentLineageE
 }
 
 function resetStateForTests(): void {
+	statesByScope.clear();
 	state.appendEntry = undefined;
 	state.sessionId = undefined;
 	state.sessionFile = undefined;

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

@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { SessionCursorAgentSendState } from "./cursor-session-agent.js";
 import { asRecord } from "./cursor-record-utils.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { getCursorSessionScopeSnapshot, getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import type { CursorSessionStoreIdentity } from "./cursor-session-store.js";
 
 export const CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE = "cursor-sdk-agent-resume";
@@ -73,7 +73,7 @@ interface CursorSessionResumeState {
 	unownedUserEntryIds: Set<string>;
 }
 
-const state: CursorSessionResumeState = {
+let lastBoundState: CursorSessionResumeState = {
 	scopeKey: getCursorSessionScopeKey(),
 	cwd: process.cwd(),
 	branchPathHash: EMPTY_BRANCH_HASH,
@@ -81,17 +81,13 @@ const state: CursorSessionResumeState = {
 	unownedUserEntryIds: new Set(),
 };
 
-// Compaction summarizer sends commit a one-message resume handle. Drop it so the
-// next normal turn_end cannot persist that lineage (#223).
-let resumeHandlePersistSuppressed = false;
+const statesByScope = new Map<string, CursorSessionResumeState>();
 
-export function suppressCursorSessionAgentResumeHandlePersist(): void {
-	resumeHandlePersistSuppressed = true;
-	state.pendingHandle = undefined;
-}
-
-export function allowCursorSessionAgentResumeHandlePersist(): void {
-	resumeHandlePersistSuppressed = false;
+function getResumeState(scopeKey?: string): CursorSessionResumeState {
+	if (scopeKey !== undefined) {
+		return statesByScope.get(scopeKey) ?? lastBoundState;
+	}
+	return lastBoundState;
 }
 
 function hashParts(parts: readonly string[]): string {
@@ -211,7 +207,8 @@ function matchesResumeScope(data: CursorSessionAgentResumeEntryData, scope: Curs
 function matchesCurrentSession(
 	data: CursorSessionAgentResumeEntryData,
 	branchPathHash: string,
-	compactionGeneration = state.compactionGeneration,
+	compactionGeneration: number,
+	state: CursorSessionResumeState,
 ): boolean {
 	return matchesResumeScope(data, state) &&
 		data.compactionGeneration === compactionGeneration &&
@@ -333,19 +330,19 @@ export function readResumableCursorSessionAgentIds(
 	return [...agentIds].sort((a, b) => a.localeCompare(b));
 }
 
-function canRestoreHandleSpanEntry(entry: SessionEntry): boolean {
+function canRestoreHandleSpanEntry(entry: SessionEntry, state: CursorSessionResumeState): boolean {
 	if (entry.type === "message" && entry.message.role === "user") return !state.unownedUserEntryIds.has(entry.id);
 	return canResumeHandleSpanEntry(entry);
 }
 
-function restoreFromBranch(branch: readonly SessionEntry[], allEntries: readonly SessionEntry[] = branch): void {
+function restoreFromBranch(branch: readonly SessionEntry[], allEntries: readonly SessionEntry[], state: CursorSessionResumeState): void {
 	const resumeIndex = indexLatestResumeEntries(allEntries);
 	let fold: ResumeBranchFoldState = { branchPathHash: EMPTY_BRANCH_HASH, compactionGeneration: 0 };
 	let lastBranchHandle: CursorSessionAgentResumeEntryData | undefined;
 	for (const entry of branch) {
 		const next = advanceResumeBranchState(entry, fold, resumeIndex, {
-			matchesEntry: matchesCurrentSession,
-			canSpanEntry: canRestoreHandleSpanEntry,
+			matchesEntry: (data, hash, generation) => matchesCurrentSession(data, hash, generation, state),
+			canSpanEntry: (entry) => canRestoreHandleSpanEntry(entry, state),
 		});
 		if (next.activeHandle && next.activeHandle !== fold.activeHandle) lastBranchHandle = next.activeHandle;
 		fold = next;
@@ -356,7 +353,9 @@ function restoreFromBranch(branch: readonly SessionEntry[], allEntries: readonly
 	state.lastBranchHandle = lastBranchHandle;
 }
 
-export function getMatchingCursorSessionAgentResumeHandle(poolKey: string): CursorSessionAgentResumeEntryData | undefined {
+export function getMatchingCursorSessionAgentResumeHandle(poolKey: string, scopeKey?: string): CursorSessionAgentResumeEntryData | undefined {
+	const state = getResumeState(scopeKey);
+	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return undefined;
 	const handle = state.activeHandle;
 	if (!handle || !isCursorLocalAgentId(handle.agentId)) return undefined;
 	if (handle.poolKey !== poolKey) return undefined;
@@ -372,8 +371,9 @@ export function getMatchingCursorSessionAgentResumeHandle(poolKey: string): Curs
 	};
 }
 
-export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle): void {
-	if (resumeHandlePersistSuppressed) return;
+export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle, scopeKey?: string): void {
+	const state = getResumeState(scopeKey);
+	if (scopeKey !== undefined && state.scopeKey !== scopeKey) return;
 	if (!isCursorLocalAgentId(input.agentId)) return;
 	state.pendingHandle = {
 		runtime: input.runtime,
@@ -384,13 +384,8 @@ export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessio
 	};
 }
 
-function flushPendingCursorSessionAgentResumeHandle(branch: readonly SessionEntry[]): void {
-	if (resumeHandlePersistSuppressed) {
-		state.pendingHandle = undefined;
-		restoreFromBranch(branch);
-		return;
-	}
-	restoreFromBranch(branch);
+function flushPendingCursorSessionAgentResumeHandle(branch: readonly SessionEntry[], state: CursorSessionResumeState): void {
+	restoreFromBranch(branch, branch, state);
 	const pending = state.pendingHandle;
 	state.pendingHandle = undefined;
 	if (!pending || !state.appendEntry) return;
@@ -432,14 +427,22 @@ interface CursorSessionAgentResumeExtensionApi {
 }
 
 export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExtensionApi): void {
-	state.appendEntry = pi.appendEntry;
+	const sessionState: CursorSessionResumeState = {
+		appendEntry: pi.appendEntry, scopeKey: getCursorSessionScopeSnapshot(pi).scopeKey,
+		cwd: process.cwd(), branchPathHash: EMPTY_BRANCH_HASH,
+		compactionGeneration: 0, unownedUserEntryIds: new Set(),
+	};
+	const state = sessionState;
 	const restoreFromSessionManager = (sessionManager: { getBranch(): SessionEntry[]; getEntries(): SessionEntry[] }): void => {
 		const branch = sessionManager.getBranch();
 		const entries = sessionManager.getEntries();
-		restoreFromBranch(branch, entries.length > 0 ? entries : branch);
+		restoreFromBranch(branch, entries.length > 0 ? entries : branch, state);
 	};
 	pi.on("session_start", (_event, ctx) => {
-		state.scopeKey = getCursorSessionScopeKey();
+		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		state.scopeKey = getCursorSessionScopeSnapshot(pi).scopeKey;
+		statesByScope.set(state.scopeKey, state);
+		lastBoundState = state;
 		state.sessionFile = ctx.sessionManager.getSessionFile?.() ?? undefined;
 		state.sessionId = ctx.sessionManager.getSessionId?.() ?? undefined;
 		state.cwd = ctx.cwd;
@@ -452,7 +455,7 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		restoreFromSessionManager(ctx.sessionManager);
 	});
 	pi.on("turn_end", (_event, ctx) => {
-		flushPendingCursorSessionAgentResumeHandle(ctx.sessionManager.getBranch());
+		flushPendingCursorSessionAgentResumeHandle(ctx.sessionManager.getBranch(), state);
 	});
 	pi.on("session_tree", (_event, ctx) => {
 		for (const entry of ctx.sessionManager.getBranch()) {
@@ -460,9 +463,14 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		}
 		restoreFromSessionManager(ctx.sessionManager);
 	});
+	pi.on("session_before_compact", () => {
+		state.pendingHandle = undefined;
+	});
+	pi.on("session_compact_failed", () => {
+		state.pendingHandle = undefined;
+	});
 	pi.on("session_compact", (event, ctx) => {
 		state.pendingHandle = undefined;
-		resumeHandlePersistSuppressed = false;
 		const branch = ctx.sessionManager.getBranch();
 		if (branch.length > 0) {
 			restoreFromSessionManager(ctx.sessionManager);
@@ -473,13 +481,19 @@ export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExt
 		state.compactionGeneration += 1;
 		state.branchPathHash = hashBranchStep(state.branchPathHash, event.compactionEntry);
 	});
+	pi.on("session_shutdown", () => {
+		if (statesByScope.get(state.scopeKey) === state) statesByScope.delete(state.scopeKey);
+		state.appendEntry = undefined;
+		state.pendingHandle = undefined;
+	});
 }
 
 function setStateForTests(next: Partial<CursorSessionResumeState>): void {
-	Object.assign(state, next);
+	Object.assign(getResumeState(), next);
 }
 
 function resetStateForTests(): void {
+	const state = lastBoundState;
 	state.appendEntry = undefined;
 	state.scopeKey = getCursorSessionScopeKey();
 	state.sessionFile = undefined;
@@ -492,7 +506,7 @@ function resetStateForTests(): void {
 	state.lastBranchHandle = undefined;
 	state.pendingHandle = undefined;
 	state.unownedUserEntryIds = new Set();
-	resumeHandlePersistSuppressed = false;
+	statesByScope.clear();
 }
 
 export const __testUtils = {
@@ -500,6 +514,5 @@ export const __testUtils = {
 	hashBranchStep,
 	reset: resetStateForTests,
 	set: setStateForTests,
-	state,
-	isResumeHandlePersistSuppressed: () => resumeHandlePersistSuppressed,
+	get state() { return getResumeState(); },
 };