pi-cursor-sdk 0.1.55 → 0.1.57

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

@@ -0,0 +1,439 @@
+import { createHash } from "node:crypto";
+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";
+
+export const CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE = "cursor-sdk-agent-resume";
+
+const RESUME_ENTRY_VERSION = 1;
+const MAX_LOCAL_AGENT_ID_LENGTH = 256;
+const EMPTY_BRANCH_HASH = hashParts(["cursor-sdk-agent-resume-branch", "v1"]);
+
+// @cursor/sdk AgentOptions.agentId is a public custom string, so local resume narrows it without assuming UUIDs.
+export function isCursorLocalAgentId(value: unknown): value is string {
+	return typeof value === "string" && value.length <= MAX_LOCAL_AGENT_ID_LENGTH && /^agent-[A-Za-z0-9_-]+$/.test(value);
+}
+
+export interface CursorSessionAgentResumeScope {
+	scopeKey: string;
+	sessionFile?: string;
+	sessionId?: string;
+	cwd: string;
+	repoRoot?: string;
+}
+
+export interface CursorSessionAgentResumeEntryData {
+	version: 1;
+	runtime: "local";
+	agentId: string;
+	scopeKey: string;
+	sessionFile?: string;
+	sessionId?: string;
+	cwd: string;
+	repoRoot?: string;
+	poolKey: string;
+	branchPathHash: string;
+	compactionGeneration: number;
+	sendState: SessionCursorAgentSendState;
+	createdAt: string;
+	cleanupCandidateAgentIds?: string[];
+}
+
+interface PendingCursorSessionAgentResumeHandle {
+	runtime: "local";
+	agentId: string;
+	poolKey: string;
+	sendState: SessionCursorAgentSendState;
+}
+
+interface CursorSessionResumeState {
+	appendEntry?: ExtensionAPI["appendEntry"];
+	scopeKey: string;
+	sessionFile?: string;
+	sessionId?: string;
+	cwd: string;
+	repoRoot?: string;
+	branchPathHash: string;
+	compactionGeneration: number;
+	activeHandle?: CursorSessionAgentResumeEntryData;
+	lastBranchHandle?: CursorSessionAgentResumeEntryData;
+	pendingHandle?: PendingCursorSessionAgentResumeHandle;
+	unownedUserEntryIds: Set<string>;
+}
+
+const state: CursorSessionResumeState = {
+	scopeKey: getCursorSessionScopeKey(),
+	cwd: process.cwd(),
+	branchPathHash: EMPTY_BRANCH_HASH,
+	compactionGeneration: 0,
+	unownedUserEntryIds: new Set(),
+};
+
+function hashParts(parts: readonly string[]): string {
+	const hash = createHash("sha256");
+	for (const part of parts) {
+		hash.update(part);
+		hash.update("\0");
+	}
+	return hash.digest("hex").slice(0, 32);
+}
+
+function hashBranchStep(previous: string, entry: SessionEntry): string {
+	return hashParts([
+		previous,
+		entry.type,
+		entry.id,
+		entry.parentId ?? "",
+		entry.type === "custom" ? entry.customType : "",
+	]);
+}
+
+export function resolveCursorSessionRepoRoot(cwd: string): string | undefined {
+	try {
+		return execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 2_000,
+		}).trim() || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isSendState(value: unknown): value is SessionCursorAgentSendState {
+	const record = asRecord(value);
+	return typeof record?.bootstrapped === "boolean" &&
+		typeof record.contextFingerprint === "string" &&
+		typeof record.incrementalSendCount === "number";
+}
+
+export function parseCursorSessionAgentResumeEntryData(value: unknown): CursorSessionAgentResumeEntryData | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	if (record.version !== RESUME_ENTRY_VERSION || record.runtime !== "local") return undefined;
+	if (
+		!isCursorLocalAgentId(record.agentId) ||
+		typeof record.scopeKey !== "string" ||
+		typeof record.cwd !== "string" ||
+		typeof record.poolKey !== "string" ||
+		typeof record.branchPathHash !== "string" ||
+		typeof record.compactionGeneration !== "number" ||
+		typeof record.createdAt !== "string" ||
+		!isSendState(record.sendState)
+	) return undefined;
+	if (record.sessionFile !== undefined && typeof record.sessionFile !== "string") return undefined;
+	if (record.sessionId !== undefined && typeof record.sessionId !== "string") return undefined;
+	if (record.repoRoot !== undefined && typeof record.repoRoot !== "string") return undefined;
+	const cleanupCandidateAgentIds = Array.isArray(record.cleanupCandidateAgentIds)
+		? record.cleanupCandidateAgentIds.filter(isCursorLocalAgentId)
+		: undefined;
+	return {
+		version: RESUME_ENTRY_VERSION,
+		runtime: "local",
+		agentId: record.agentId,
+		scopeKey: record.scopeKey,
+		...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
+		...(record.sessionId ? { sessionId: record.sessionId } : {}),
+		cwd: record.cwd,
+		...(record.repoRoot ? { repoRoot: record.repoRoot } : {}),
+		poolKey: record.poolKey,
+		branchPathHash: record.branchPathHash,
+		compactionGeneration: record.compactionGeneration,
+		sendState: {
+			bootstrapped: record.sendState.bootstrapped,
+			contextFingerprint: record.sendState.contextFingerprint,
+			incrementalSendCount: record.sendState.incrementalSendCount,
+		},
+		createdAt: record.createdAt,
+		...(cleanupCandidateAgentIds?.length ? { cleanupCandidateAgentIds: [...new Set(cleanupCandidateAgentIds)] } : {}),
+	};
+}
+
+function matchesResumeScope(data: CursorSessionAgentResumeEntryData, scope: CursorSessionAgentResumeScope): boolean {
+	return data.scopeKey === scope.scopeKey &&
+		data.sessionFile === scope.sessionFile &&
+		data.sessionId === scope.sessionId &&
+		data.cwd === scope.cwd &&
+		data.repoRoot === scope.repoRoot;
+}
+
+function matchesCurrentSession(
+	data: CursorSessionAgentResumeEntryData,
+	branchPathHash: string,
+	compactionGeneration = state.compactionGeneration,
+): boolean {
+	return matchesResumeScope(data, state) &&
+		data.compactionGeneration === compactionGeneration &&
+		data.branchPathHash === branchPathHash;
+}
+
+function canResumeHandleSpanEntry(entry: SessionEntry): boolean {
+	if (entry.type === "custom" || entry.type === "label" || entry.type === "session_info") return true;
+	return entry.type === "message" && entry.message.role === "user";
+}
+
+function resumeAgentLineageKey(data: CursorSessionAgentResumeEntryData): string {
+	return JSON.stringify([
+		data.agentId,
+		data.scopeKey,
+		data.sessionFile,
+		data.sessionId,
+		data.cwd,
+		data.repoRoot,
+		data.poolKey,
+	]);
+}
+
+function indexLatestResumeEntries(entries: readonly SessionEntry[]): {
+	entryIds: Set<string>;
+	latestEntryIdByLineage: Map<string, string>;
+} {
+	const entryIds = new Set<string>();
+	const latestEntryIdByLineage = new Map<string, string>();
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		entryIds.add(entry.id);
+		if (entry.type !== "custom" || entry.customType !== CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE) continue;
+		const data = parseCursorSessionAgentResumeEntryData(entry.data);
+		if (!data) continue;
+		const lineage = resumeAgentLineageKey(data);
+		if (!latestEntryIdByLineage.has(lineage)) latestEntryIdByLineage.set(lineage, entry.id);
+	}
+	return { entryIds, latestEntryIdByLineage };
+}
+
+interface ResumeBranchFoldState {
+	branchPathHash: string;
+	compactionGeneration: number;
+	activeHandle?: CursorSessionAgentResumeEntryData;
+}
+
+interface ResumeBranchFoldParams {
+	matchesEntry: (data: CursorSessionAgentResumeEntryData, branchPathHash: string, compactionGeneration: number) => boolean;
+	canSpanEntry: (entry: SessionEntry) => boolean;
+}
+
+/** One fold step shared by the tree-wide and single-branch resume-handle walks: advances
+ * branchPathHash/compactionGeneration and adopts a matching, non-superseded resume handle. */
+function advanceResumeBranchState(
+	entry: SessionEntry,
+	previous: ResumeBranchFoldState,
+	resumeIndex: { entryIds: Set<string>; latestEntryIdByLineage: Map<string, string> },
+	params: ResumeBranchFoldParams,
+): ResumeBranchFoldState {
+	if (entry.type === "custom" && entry.customType === CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE) {
+		const data = parseCursorSessionAgentResumeEntryData(entry.data);
+		const latestEntryId = data ? resumeIndex.latestEntryIdByLineage.get(resumeAgentLineageKey(data)) : undefined;
+		const superseded = resumeIndex.entryIds.has(entry.id) && latestEntryId !== entry.id;
+		if (data && params.matchesEntry(data, previous.branchPathHash, previous.compactionGeneration) && !superseded) {
+			return { ...previous, activeHandle: data };
+		}
+		return previous;
+	}
+	return {
+		branchPathHash: hashBranchStep(previous.branchPathHash, entry),
+		compactionGeneration: entry.type === "compaction" ? previous.compactionGeneration + 1 : previous.compactionGeneration,
+		activeHandle: previous.activeHandle && !params.canSpanEntry(entry) ? undefined : previous.activeHandle,
+	};
+}
+
+export function readResumableCursorSessionAgentIds(
+	entries: readonly SessionEntry[],
+	scope: CursorSessionAgentResumeScope,
+): string[] {
+	const resumeIndex = indexLatestResumeEntries(entries);
+	const states = new Map<string, ResumeBranchFoldState>();
+	const parentIds = new Set<string>();
+	let rootCount = 0;
+	let completeTree = true;
+	for (const entry of entries) {
+		if (states.has(entry.id)) completeTree = false;
+		if (entry.parentId === null) rootCount += 1;
+		const parent = entry.parentId ? states.get(entry.parentId) : undefined;
+		if (entry.parentId) {
+			parentIds.add(entry.parentId);
+			if (!parent) completeTree = false;
+		}
+		const previous: ResumeBranchFoldState = {
+			branchPathHash: parent?.branchPathHash ?? EMPTY_BRANCH_HASH,
+			compactionGeneration: parent?.compactionGeneration ?? 0,
+			activeHandle: parent?.activeHandle,
+		};
+		states.set(entry.id, advanceResumeBranchState(entry, previous, resumeIndex, {
+			matchesEntry: (data, branchPathHash, compactionGeneration) =>
+				matchesResumeScope(data, scope) &&
+				data.compactionGeneration === compactionGeneration &&
+				data.branchPathHash === branchPathHash,
+			canSpanEntry: canResumeHandleSpanEntry,
+		}));
+	}
+	if (entries.length > 0 && rootCount !== 1) completeTree = false;
+	if (!completeTree) {
+		return [...new Set(entries.flatMap((entry) => {
+			if (entry.type !== "custom" || entry.customType !== CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE) return [];
+			const data = parseCursorSessionAgentResumeEntryData(entry.data);
+			return data && matchesResumeScope(data, scope) ? [data.agentId] : [];
+		}))].sort((a, b) => a.localeCompare(b));
+	}
+	const agentIds = new Set<string>();
+	for (const [entryId, branchState] of states) {
+		if (!parentIds.has(entryId) && branchState.activeHandle) agentIds.add(branchState.activeHandle.agentId);
+	}
+	return [...agentIds].sort((a, b) => a.localeCompare(b));
+}
+
+function canRestoreHandleSpanEntry(entry: SessionEntry): 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 {
+	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,
+		});
+		if (next.activeHandle && next.activeHandle !== fold.activeHandle) lastBranchHandle = next.activeHandle;
+		fold = next;
+	}
+	state.branchPathHash = fold.branchPathHash;
+	state.compactionGeneration = fold.compactionGeneration;
+	state.activeHandle = fold.activeHandle;
+	state.lastBranchHandle = lastBranchHandle;
+}
+
+export function getMatchingCursorSessionAgentResumeHandle(poolKey: string): CursorSessionAgentResumeEntryData | undefined {
+	const handle = state.activeHandle;
+	if (!handle || !isCursorLocalAgentId(handle.agentId)) return undefined;
+	if (handle.poolKey !== poolKey) return undefined;
+	if (handle.scopeKey !== state.scopeKey) return undefined;
+	if (handle.sessionFile !== state.sessionFile) return undefined;
+	if (handle.sessionId !== state.sessionId) return undefined;
+	if (handle.cwd !== state.cwd) return undefined;
+	if (handle.repoRoot !== state.repoRoot) return undefined;
+	if (handle.compactionGeneration !== state.compactionGeneration) return undefined;
+	return {
+		...handle,
+		sendState: { ...handle.sendState },
+	};
+}
+
+export function persistCursorSessionAgentResumeHandle(input: PendingCursorSessionAgentResumeHandle): void {
+	if (!isCursorLocalAgentId(input.agentId)) return;
+	state.pendingHandle = {
+		runtime: input.runtime,
+		agentId: input.agentId,
+		poolKey: input.poolKey,
+		sendState: { ...input.sendState },
+	};
+}
+
+function flushPendingCursorSessionAgentResumeHandle(branch: readonly SessionEntry[]): void {
+	restoreFromBranch(branch);
+	const pending = state.pendingHandle;
+	state.pendingHandle = undefined;
+	if (!pending || !state.appendEntry) return;
+	const previousAgentId = state.activeHandle?.agentId ?? state.lastBranchHandle?.agentId;
+	const cleanupCandidateAgentIds = previousAgentId && previousAgentId !== pending.agentId ? [previousAgentId] : undefined;
+	const data: CursorSessionAgentResumeEntryData = {
+		version: RESUME_ENTRY_VERSION,
+		runtime: pending.runtime,
+		agentId: pending.agentId,
+		scopeKey: state.scopeKey,
+		...(state.sessionFile ? { sessionFile: state.sessionFile } : {}),
+		...(state.sessionId ? { sessionId: state.sessionId } : {}),
+		cwd: state.cwd,
+		...(state.repoRoot ? { repoRoot: state.repoRoot } : {}),
+		poolKey: pending.poolKey,
+		branchPathHash: state.branchPathHash,
+		compactionGeneration: state.compactionGeneration,
+		sendState: { ...pending.sendState },
+		createdAt: new Date().toISOString(),
+		...(cleanupCandidateAgentIds ? { cleanupCandidateAgentIds } : {}),
+	};
+	try {
+		state.appendEntry<CursorSessionAgentResumeEntryData>(CURSOR_SESSION_AGENT_RESUME_ENTRY_TYPE, data);
+		state.activeHandle = data;
+	} catch {
+		// Resume persistence is an optimization; a failed custom-entry append must not fail the completed turn.
+	}
+}
+
+interface CursorSessionAgentResumeExtensionApi {
+	appendEntry: ExtensionAPI["appendEntry"];
+	on: ExtensionAPI["on"];
+}
+
+export function registerCursorSessionAgentResume(pi: CursorSessionAgentResumeExtensionApi): void {
+	state.appendEntry = pi.appendEntry;
+	const restoreFromSessionManager = (sessionManager: { getBranch(): SessionEntry[]; getEntries(): SessionEntry[] }): void => {
+		const branch = sessionManager.getBranch();
+		const entries = sessionManager.getEntries();
+		restoreFromBranch(branch, entries.length > 0 ? entries : branch);
+	};
+	pi.on("session_start", (_event, ctx) => {
+		state.scopeKey = getCursorSessionScopeKey();
+		state.sessionFile = ctx.sessionManager.getSessionFile?.() ?? undefined;
+		state.sessionId = ctx.sessionManager.getSessionId?.() ?? undefined;
+		state.cwd = ctx.cwd;
+		state.repoRoot = resolveCursorSessionRepoRoot(ctx.cwd);
+		state.unownedUserEntryIds = new Set(ctx.sessionManager.getBranch().flatMap((entry) =>
+			entry.type === "message" && entry.message.role === "user" ? [entry.id] : []));
+		restoreFromSessionManager(ctx.sessionManager);
+	});
+	pi.on("before_agent_start", (_event, ctx) => {
+		restoreFromSessionManager(ctx.sessionManager);
+	});
+	pi.on("turn_end", (_event, ctx) => {
+		flushPendingCursorSessionAgentResumeHandle(ctx.sessionManager.getBranch());
+	});
+	pi.on("session_tree", (_event, ctx) => {
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "message" && entry.message.role === "user") state.unownedUserEntryIds.add(entry.id);
+		}
+		restoreFromSessionManager(ctx.sessionManager);
+	});
+	pi.on("session_compact", (event, ctx) => {
+		const branch = ctx.sessionManager.getBranch();
+		if (branch.length > 0) {
+			restoreFromSessionManager(ctx.sessionManager);
+			return;
+		}
+		state.activeHandle = undefined;
+		state.lastBranchHandle = undefined;
+		state.compactionGeneration += 1;
+		state.branchPathHash = hashBranchStep(state.branchPathHash, event.compactionEntry);
+	});
+}
+
+function setStateForTests(next: Partial<CursorSessionResumeState>): void {
+	Object.assign(state, next);
+}
+
+function resetStateForTests(): void {
+	state.appendEntry = undefined;
+	state.scopeKey = getCursorSessionScopeKey();
+	state.sessionFile = undefined;
+	state.sessionId = undefined;
+	state.cwd = process.cwd();
+	state.repoRoot = undefined;
+	state.branchPathHash = EMPTY_BRANCH_HASH;
+	state.compactionGeneration = 0;
+	state.activeHandle = undefined;
+	state.lastBranchHandle = undefined;
+	state.pendingHandle = undefined;
+	state.unownedUserEntryIds = new Set();
+}
+
+export const __testUtils = {
+	EMPTY_BRANCH_HASH,
+	hashBranchStep,
+	reset: resetStateForTests,
+	set: setStateForTests,
+	state,
+};

package/src/cursor-session-agent.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { AgentModeOption, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
+import type { AgentModeOption, LocalAgentOptions, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai/compat";
 import {
 	getRegisteredCursorPiToolBridge,
@@ -8,6 +8,10 @@ import {
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionScopeGeneration, getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import {
+	getMatchingCursorSessionAgentResumeHandle,
+	persistCursorSessionAgentResumeHandle,
+} from "./cursor-session-agent-resume.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 import { loadCursorSdk, type CursorSdkModule } from "./cursor-sdk-runtime.js";
 
@@ -25,6 +29,8 @@ export interface SessionCursorAgentLease {
 	bridgeRun?: CursorPiToolBridgeRun;
 	sendState: SessionCursorAgentSendState;
 	created: boolean;
+	resumed?: boolean;
+	resumeNotice?: string;
 	commitSend(context: Context, bootstrapped: boolean): void;
 	trackRunCompletion(completion: Promise<unknown>): void;
 }
@@ -46,12 +52,18 @@ interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
 	status: "ready";
 	agent: SDKAgent;
 	bridgeRun?: CursorPiToolBridgeRun;
+	resumeEnabled: boolean;
+	resumed: boolean;
+	resumeNotice?: string;
 }
 
 interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
 	status: "busy";
 	agent: SDKAgent;
 	bridgeRun?: CursorPiToolBridgeRun;
+	resumeEnabled: boolean;
+	resumed: boolean;
+	resumeNotice?: string;
 	completionSettled: Promise<void>;
 	pendingCompletion: Promise<void>;
 	releaseBusyWait: () => void;
@@ -103,9 +115,13 @@ interface SessionCursorAgentCreateParams {
 	cwd: string;
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
+	localSafety?: CursorLocalSafetyOptions;
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
+	localResume?: boolean;
+	forceCreate?: boolean;
 	createAgent?: CursorSdkModule["Agent"]["create"];
+	resumeAgent?: CursorSdkModule["Agent"]["resume"];
 }
 
 const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
@@ -115,6 +131,24 @@ const scopeCreationGenerations = new Map<string, number>();
 const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
 let nextSessionAgentInstanceId = 1;
 
+export interface CursorLocalSafetyOptions {
+	autoReview?: boolean;
+	sandboxEnabled?: boolean;
+}
+
+export function buildCursorLocalAgentOptions(options: {
+	cwd: string;
+	settingSources?: SettingSource[];
+	localSafety?: CursorLocalSafetyOptions;
+}): LocalAgentOptions {
+	return {
+		cwd: options.cwd,
+		...(options.settingSources ? { settingSources: options.settingSources } : {}),
+		...(options.localSafety?.autoReview === true ? { autoReview: true } : {}),
+		...(options.localSafety?.sandboxEnabled === true ? { sandboxOptions: { enabled: true } } : {}),
+	};
+}
+
 function allocateSessionAgentInstanceId(): number {
 	return nextSessionAgentInstanceId++;
 }
@@ -143,6 +177,13 @@ function buildSettingSourcesPoolKey(settingSources?: SettingSource[]): string {
 	return settingSources?.join(",") ?? "";
 }
 
+function buildLocalSafetyPoolKey(localSafety?: CursorLocalSafetyOptions): string {
+	return JSON.stringify({
+		autoReview: localSafety?.autoReview === true,
+		sandboxEnabled: localSafety?.sandboxEnabled === true,
+	});
+}
+
 function buildApiKeyPoolKeyFingerprint(apiKey: string): string {
 	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
@@ -159,6 +200,7 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 		params.cwd,
 		buildModelPoolKey(params.modelSelection),
 		buildSettingSourcesPoolKey(params.settingSources),
+		buildLocalSafetyPoolKey(params.localSafety),
 		buildApiKeyPoolKeyFingerprint(params.apiKey),
 		buildBridgePoolKeySuffix(),
 	].join("\0");
@@ -225,9 +267,17 @@ function commitSessionAgentSendForLease(
 	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
 	if (bootstrapped) {
 		entry.sendState.incrementalSendCount = 0;
-		return;
+	} else {
+		entry.sendState.incrementalSendCount += 1;
+	}
+	if (entry.resumeEnabled) {
+		persistCursorSessionAgentResumeHandle({
+			runtime: "local",
+			agentId: entry.agent.agentId,
+			poolKey: entry.poolKey,
+			sendState: entry.sendState,
+		});
 	}
-	entry.sendState.incrementalSendCount += 1;
 }
 
 function normalizeRunCompletion(completion: Promise<unknown>): Promise<void> {
@@ -299,8 +349,11 @@ function leaseFromEntry(
 	params: SessionCursorAgentCreateParams,
 	created: boolean,
 ): SessionCursorAgentLease {
+	entry.resumeEnabled = params.localResume === true;
 	bindBridgeToolRequest(entry, params.onBridgeToolRequest);
 	entry.bridgeRun?.setDebugRecorder(params.debugRecorder);
+	const resumeNotice = entry.resumeNotice;
+	entry.resumeNotice = undefined;
 	return {
 		scopeKey,
 		poolKey: entry.poolKey,
@@ -309,6 +362,8 @@ function leaseFromEntry(
 		bridgeRun: entry.bridgeRun,
 		sendState: entry.sendState,
 		created,
+		resumed: entry.resumed,
+		...(resumeNotice ? { resumeNotice } : {}),
 		commitSend: (context, bootstrapped) => {
 			commitSessionAgentSendForLease(scopeKey, entry.poolKey, entry.instanceId, context, bootstrapped);
 		},
@@ -365,16 +420,41 @@ async function createSessionAgentEntry(
 	}
 
 	const resolvedPoolKey = buildSessionAgentPoolKey(scopeKey, params);
-	const createAgent = params.createAgent ?? (await loadCursorSdk()).Agent.create;
-	let agent: SDKAgent;
+	const resumeEligible = params.localResume === true && !params.forceCreate;
+	let createAgent = params.createAgent;
+	let resumeAgent = params.resumeAgent;
+	if (!createAgent || (resumeEligible && !resumeAgent)) {
+		const sdk = await loadCursorSdk();
+		createAgent ??= sdk.Agent.create;
+		resumeAgent ??= sdk.Agent.resume;
+	}
+	const agentOptions = {
+		apiKey: params.apiKey,
+		model: params.modelSelection,
+		mode: params.agentMode,
+		local: buildCursorLocalAgentOptions({
+			cwd: params.cwd,
+			settingSources: params.settingSources,
+			localSafety: params.localSafety,
+		}),
+		...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
+	};
+	let agent: SDKAgent | undefined;
+	let effectiveSendState = sendState;
+	let resumed = false;
+	let resumeNotice: string | undefined;
+	const resumeHandle = resumeEligible ? getMatchingCursorSessionAgentResumeHandle(resolvedPoolKey) : undefined;
+	if (resumeHandle && resumeAgent) {
+		try {
+			agent = await resumeAgent(resumeHandle.agentId, agentOptions);
+			effectiveSendState = { ...resumeHandle.sendState };
+			resumed = true;
+		} catch {
+			resumeNotice = "Could not resume prior Cursor agent; continuing from current pi transcript in a new Cursor agent.";
+		}
+	}
 	try {
-		agent = await createAgent({
-			apiKey: params.apiKey,
-			model: params.modelSelection,
-			mode: params.agentMode,
-			local: params.settingSources ? { cwd: params.cwd, settingSources: params.settingSources } : { cwd: params.cwd },
-			...(bridgeRun?.mcpServers ? { mcpServers: bridgeRun.mcpServers } : {}),
-		});
+		agent ??= await createAgent(agentOptions);
 	} catch (error) {
 		if (bridgeRun) {
 			bridgeRun.cancel("Cursor session agent create failed");
@@ -386,6 +466,7 @@ async function createSessionAgentEntry(
 		}
 		throw error;
 	}
+	if (!agent) throw new Error("Cursor SDK agent creation returned no agent");
 
 	return {
 		status: "ready",
@@ -394,7 +475,10 @@ async function createSessionAgentEntry(
 		scopeKey,
 		agent,
 		bridgeRun,
-		sendState,
+		sendState: effectiveSendState,
+		resumeEnabled: params.localResume === true,
+		resumed,
+		...(resumeNotice ? { resumeNotice } : {}),
 	};
 }
 
@@ -504,6 +588,17 @@ export async function acquireSessionCursorAgent(params: SessionCursorAgentCreate
 	}
 }
 
+export type RefreshSessionCursorAgentConfigResult = "reloaded" | "no-agent" | "busy" | "unsupported";
+
+export async function refreshSessionCursorAgentConfig(scopeKey: string = getCursorSessionScopeKey()): Promise<RefreshSessionCursorAgentConfigResult> {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!entry || entry.status === "creating") return "no-agent";
+	if (entry.status === "busy") return "busy";
+	if (typeof entry.agent.reload !== "function") return "unsupported";
+	await entry.agent.reload();
+	return "reloaded";
+}
+
 export async function resetSessionCursorAgent(scopeKey: string = getCursorSessionScopeKey()): Promise<void> {
 	await disposePoolEntryForScope(scopeKey);
 }
@@ -525,6 +620,7 @@ export const __testUtils = {
 	invalidateSessionAgent,
 	disposeSessionCursorAgent,
 	resetSessionCursorAgent,
+	refreshSessionCursorAgentConfig,
 	disposeAllSessionCursorAgents,
 	buildApiKeyPoolKeyFingerprint,
 	buildSessionAgentPoolKey,