pi-cursor-sdk 0.1.18 → 0.1.20

package/src/cursor-session-agent.ts

@@ -16,30 +16,63 @@ import {
 } from "./cursor-pi-tool-bridge.js";
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionScopeKey, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
+import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
 
 export interface SessionCursorAgentSendState {
 	bootstrapped: boolean;
 	contextFingerprint: string;
+	incrementalSendCount: number;
 }
 
 export interface SessionCursorAgentLease {
 	scopeKey: string;
+	poolKey: string;
+	instanceId: number;
 	agent: SDKAgent;
 	bridgeRun?: CursorPiToolBridgeRun;
 	sendState: SessionCursorAgentSendState;
 	created: boolean;
+	commitSend(context: Context, bootstrapped: boolean): void;
+	trackRunCompletion(completion: Promise<unknown>): void;
 }
 
-interface SessionCursorAgentPoolEntry {
+interface SessionCursorAgentPoolEntryBase {
 	poolKey: string;
+	instanceId: number;
 	scopeKey: string;
-	agent?: SDKAgent;
-	bridgeRun?: CursorPiToolBridgeRun;
 	sendState: SessionCursorAgentSendState;
-	creating?: Promise<SessionCursorAgentPoolEntry>;
-	creationGeneration?: number;
 }
 
+interface SessionCursorAgentCreatingEntry extends SessionCursorAgentPoolEntryBase {
+	status: "creating";
+	creating: Promise<SessionCursorAgentReadyEntry>;
+	creationGeneration: number;
+}
+
+interface SessionCursorAgentReadyEntry extends SessionCursorAgentPoolEntryBase {
+	status: "ready";
+	agent: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+}
+
+interface SessionCursorAgentBusyEntry extends SessionCursorAgentPoolEntryBase {
+	status: "busy";
+	agent: SDKAgent;
+	bridgeRun?: CursorPiToolBridgeRun;
+	completionSettled: Promise<void>;
+	pendingCompletion: Promise<void>;
+	releaseBusyWait: () => void;
+	busyGeneration: number;
+}
+
+type SessionCursorAgentActiveEntry = SessionCursorAgentReadyEntry | SessionCursorAgentBusyEntry;
+type SessionCursorAgentPoolEntry =
+	| SessionCursorAgentCreatingEntry
+	| SessionCursorAgentReadyEntry
+	| SessionCursorAgentBusyEntry;
+
+type SessionCursorAgentPoolState = { status: "empty" } | SessionCursorAgentPoolEntry;
+
 class SessionCursorAgentCreationSupersededError extends Error {
 	constructor() {
 		super("Cursor session agent creation was superseded");
@@ -74,6 +107,7 @@ interface SessionCursorAgentCreateParams {
 	modelSelection: ModelSelection;
 	settingSources?: SettingSource[];
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
+	debugRecorder?: CursorSdkEventDebugRecorder;
 	createAgent?: typeof Agent.create;
 }
 
@@ -89,6 +123,20 @@ const sessionAgentsByScope = new Map<string, SessionCursorAgentPoolEntry>();
 const invalidatedScopeKeys = new Set<string>();
 const terminalDisposedScopeKeys = new Set<string>();
 const scopeCreationGenerations = new Map<string, number>();
+const EMPTY_POOL_STATE: SessionCursorAgentPoolState = { status: "empty" };
+let nextSessionAgentInstanceId = 1;
+
+function allocateSessionAgentInstanceId(): number {
+	return nextSessionAgentInstanceId++;
+}
+
+function getSessionCursorAgentPoolState(scopeKey: string): SessionCursorAgentPoolState {
+	return sessionAgentsByScope.get(scopeKey) ?? EMPTY_POOL_STATE;
+}
+
+function isActivePoolEntry(entry: SessionCursorAgentPoolEntry | undefined): entry is SessionCursorAgentActiveEntry {
+	return entry?.status === "ready" || entry?.status === "busy";
+}
 
 function getScopeCreationGeneration(scopeKey: string): number {
 	return scopeCreationGenerations.get(scopeKey) ?? 0;
@@ -128,13 +176,13 @@ function buildSessionAgentPoolKey(scopeKey: string, params: SessionCursorAgentCr
 }
 
 async function disposePoolEntry(entry: SessionCursorAgentPoolEntry): Promise<void> {
+	if (!isActivePoolEntry(entry)) return;
 	entry.bridgeRun?.cancel("Cursor session agent disposed");
 	try {
 		await entry.bridgeRun?.dispose();
 	} catch {
 		// disposal failure should not block session replacement
 	}
-	if (!entry.agent) return;
 	try {
 		await entry.agent[Symbol.asyncDispose]();
 	} catch {
@@ -151,47 +199,175 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 	invalidatedScopeKeys.delete(scopeKey);
 	if (!entry) return;
 	sessionAgentsByScope.delete(scopeKey);
-	if (entry.creating || !entry.agent) return;
+	if (entry.status === "busy") {
+		entry.releaseBusyWait();
+	}
+	if (entry.status === "creating") {
+		entry.creating.catch(() => {
+			// In-flight Agent.create was orphaned by scope disposal; active waiters surface errors elsewhere.
+		});
+		return;
+	}
 	await disposePoolEntry(entry);
 }
 
 function createInitialSendState(): SessionCursorAgentSendState {
-	return { bootstrapped: false, contextFingerprint: "" };
+	return { bootstrapped: false, contextFingerprint: "", incrementalSendCount: 0 };
 }
 
 function bindBridgeToolRequest(
-	entry: SessionCursorAgentPoolEntry,
+	entry: SessionCursorAgentActiveEntry,
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void,
 ): void {
 	entry.bridgeRun?.setOnToolRequest(onBridgeToolRequest);
 }
 
+function commitSessionAgentSendForLease(
+	scopeKey: string,
+	poolKey: string,
+	instanceId: number,
+	context: Context,
+	bootstrapped: boolean,
+): void {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!isActivePoolEntry(entry)) return;
+	if (entry.poolKey !== poolKey || entry.instanceId !== instanceId) return;
+	entry.sendState.bootstrapped = bootstrapped || entry.sendState.bootstrapped;
+	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
+	if (bootstrapped) {
+		entry.sendState.incrementalSendCount = 0;
+		return;
+	}
+	entry.sendState.incrementalSendCount += 1;
+}
+
+function normalizeRunCompletion(completion: Promise<unknown>): Promise<void> {
+	return Promise.resolve(completion).then(
+		() => undefined,
+		() => undefined,
+	);
+}
+
+function buildBusyPoolEntry(
+	entry: SessionCursorAgentActiveEntry,
+	completionSettled: Promise<void>,
+): SessionCursorAgentBusyEntry {
+	let releaseBusyWait = (): void => {};
+	const releaseSignal = new Promise<"released">((resolve) => {
+		releaseBusyWait = () => resolve("released");
+	});
+	const pendingCompletion = Promise.race([
+		completionSettled.then(() => "completed" as const),
+		releaseSignal,
+	]).then((outcome) => {
+		const current = sessionAgentsByScope.get(entry.scopeKey);
+		if (
+			outcome === "completed" &&
+			current?.status === "busy" &&
+			current.poolKey === entry.poolKey &&
+			current.instanceId === entry.instanceId &&
+			current.pendingCompletion === pendingCompletion
+		) {
+			sessionAgentsByScope.set(entry.scopeKey, { ...current, status: "ready" });
+		}
+	});
+
+	return {
+		...entry,
+		status: "busy",
+		completionSettled,
+		pendingCompletion,
+		releaseBusyWait,
+		busyGeneration: getScopeCreationGeneration(entry.scopeKey),
+	};
+}
+
+function trackSessionAgentRunCompletionForLease(
+	scopeKey: string,
+	poolKey: string,
+	instanceId: number,
+	completion: Promise<unknown>,
+): void {
+	const entry = sessionAgentsByScope.get(scopeKey);
+	if (!isActivePoolEntry(entry)) return;
+	if (entry.poolKey !== poolKey || entry.instanceId !== instanceId) return;
+
+	const completionToTrack = normalizeRunCompletion(completion);
+	const completionSettled = (entry.status === "busy"
+		? Promise.all([entry.completionSettled, completionToTrack]).then(() => undefined)
+		: completionToTrack
+	);
+	if (entry.status === "busy") {
+		entry.releaseBusyWait();
+	}
+
+	sessionAgentsByScope.set(scopeKey, buildBusyPoolEntry(entry, completionSettled));
+}
+
 function leaseFromEntry(
-	entry: SessionCursorAgentPoolEntry,
+	entry: SessionCursorAgentReadyEntry,
 	scopeKey: string,
 	params: SessionCursorAgentCreateParams,
 	created: boolean,
 ): SessionCursorAgentLease {
 	bindBridgeToolRequest(entry, params.onBridgeToolRequest);
+	entry.bridgeRun?.setDebugRecorder(params.debugRecorder);
 	return {
 		scopeKey,
-		agent: entry.agent!,
+		poolKey: entry.poolKey,
+		instanceId: entry.instanceId,
+		agent: entry.agent,
 		bridgeRun: entry.bridgeRun,
 		sendState: entry.sendState,
 		created,
+		commitSend: (context, bootstrapped) => {
+			commitSessionAgentSendForLease(scopeKey, entry.poolKey, entry.instanceId, context, bootstrapped);
+		},
+		trackRunCompletion: (completion) => {
+			trackSessionAgentRunCompletionForLease(scopeKey, entry.poolKey, entry.instanceId, completion);
+		},
 	};
 }
 
-async function createSessionAgentEntry(
+function getCurrentReadyPoolEntry(scopeKey: string, poolKey: string): SessionCursorAgentReadyEntry | undefined {
+	const current = sessionAgentsByScope.get(scopeKey);
+	if (current?.status !== "ready") return undefined;
+	if (current.poolKey !== poolKey) return undefined;
+	return current;
+}
+
+async function tryLeaseReadyEntry(
+	entry: SessionCursorAgentActiveEntry,
 	scopeKey: string,
+	params: SessionCursorAgentCreateParams,
 	poolKey: string,
+	created: boolean,
+): Promise<SessionCursorAgentLease | undefined> {
+	if (entry.status === "busy") {
+		await entry.pendingCompletion;
+	}
+	assertScopeAcceptsAcquire(scopeKey);
+	if (invalidatedScopeKeys.has(scopeKey)) {
+		await disposePoolEntryForScope(scopeKey);
+		return undefined;
+	}
+	const readyEntry = getCurrentReadyPoolEntry(scopeKey, poolKey);
+	if (!readyEntry) return undefined;
+	return leaseFromEntry(readyEntry, scopeKey, params, created);
+}
+
+async function createSessionAgentEntry(
+	scopeKey: string,
+	instanceId: number,
+	sendState: SessionCursorAgentSendState,
 	params: SessionCursorAgentCreateParams,
-): Promise<SessionCursorAgentPoolEntry> {
+): Promise<SessionCursorAgentReadyEntry> {
 	const registeredBridge = getRegisteredCursorPiToolBridge();
 	let bridgeRun: CursorPiToolBridgeRun | undefined;
 	if (registeredBridge) {
 		bridgeRun = await registeredBridge.createRun({
 			onToolRequest: params.onBridgeToolRequest,
+			debugRecorder: params.debugRecorder,
 		});
 		if (!bridgeRun.enabled || !bridgeRun.mcpServers) {
 			await bridgeRun.dispose();
@@ -222,22 +398,23 @@ async function createSessionAgentEntry(
 	}
 
 	return {
+		status: "ready",
 		poolKey: resolvedPoolKey,
+		instanceId,
 		scopeKey,
 		agent,
 		bridgeRun,
-		sendState: createInitialSendState(),
+		sendState,
 	};
 }
 
-export { shouldBootstrapCursorSend } from "./context.js";
-
-export function commitSessionAgentSend(scopeKey: string, context: Context, bootstrapped: boolean): void {
-	const entry = sessionAgentsByScope.get(scopeKey);
-	if (!entry) return;
-	entry.sendState.bootstrapped = bootstrapped || entry.sendState.bootstrapped;
-	entry.sendState.contextFingerprint = computeCursorContextFingerprint(context);
-}
+export {
+	buildCursorSessionSendPrompt,
+	MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP,
+	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);
@@ -245,77 +422,96 @@ export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeK
 
 export async function acquireSessionCursorAgent(params: SessionCursorAgentCreateParams): Promise<SessionCursorAgentLease> {
 	const scopeKey = getCursorSessionScopeKey();
-	assertScopeAcceptsAcquire(scopeKey);
-	if (invalidatedScopeKeys.has(scopeKey)) {
-		await disposePoolEntryForScope(scopeKey);
-	}
 
-	const poolKey = buildSessionAgentPoolKey(scopeKey, params);
-	const existing = sessionAgentsByScope.get(scopeKey);
-	if (existing?.poolKey === poolKey && !existing.creating) {
-		return leaseFromEntry(existing, scopeKey, params, false);
-	}
+	while (true) {
+		assertScopeAcceptsAcquire(scopeKey);
+		if (invalidatedScopeKeys.has(scopeKey)) {
+			await disposePoolEntryForScope(scopeKey);
+		}
 
-	if (existing && existing.poolKey !== poolKey) {
-		await disposePoolEntryForScope(scopeKey);
-	}
+		const poolKey = buildSessionAgentPoolKey(scopeKey, params);
+		const state = getSessionCursorAgentPoolState(scopeKey);
 
-	let entry = sessionAgentsByScope.get(scopeKey);
-	if (entry?.creating) {
-		try {
-			await entry.creating;
-		} catch (error) {
-			if (error instanceof SessionCursorAgentCreationSupersededError) {
-				assertScopeAcceptsAcquire(scopeKey);
-				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
-			} else {
+		if ((state.status === "ready" || state.status === "busy") && state.poolKey !== poolKey) {
+			await disposePoolEntryForScope(scopeKey);
+			continue;
+		}
+
+		if (state.status === "ready") {
+			return leaseFromEntry(state, scopeKey, params, false);
+		}
+
+		if (state.status === "busy") {
+			const busyGeneration = state.busyGeneration;
+			await state.pendingCompletion;
+			if (busyGeneration !== getScopeCreationGeneration(scopeKey)) continue;
+			continue;
+		}
+
+		if (state.status === "creating") {
+			if (state.poolKey !== poolKey) {
+				await disposePoolEntryForScope(scopeKey);
+				continue;
+			}
+			try {
+				await state.creating;
+			} catch (error) {
+				if (error instanceof SessionCursorAgentCreationSupersededError) {
+					assertScopeAcceptsAcquire(scopeKey);
+					rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+					continue;
+				}
 				throw error;
 			}
+			continue;
 		}
-		entry = sessionAgentsByScope.get(scopeKey);
-		if (entry && entry.poolKey === poolKey && entry.agent && !entry.creating) {
-			return leaseFromEntry(entry, scopeKey, params, false);
-		}
-	}
 
-	assertScopeAcceptsAcquire(scopeKey);
-	const creationGeneration = getScopeCreationGeneration(scopeKey);
-	const placeholder: SessionCursorAgentPoolEntry = {
-		poolKey,
-		scopeKey,
-		sendState: createInitialSendState(),
-		creationGeneration,
-	};
-	const creating = createSessionAgentEntry(scopeKey, poolKey, params).then(async (createdEntry) => {
-		const stillCurrent =
-			sessionAgentsByScope.get(scopeKey) === placeholder &&
-			getScopeCreationGeneration(scopeKey) === placeholder.creationGeneration;
-		if (!stillCurrent) {
-			await disposePoolEntry(createdEntry);
+		assertScopeAcceptsAcquire(scopeKey);
+		const creationGeneration = getScopeCreationGeneration(scopeKey);
+		const instanceId = allocateSessionAgentInstanceId();
+		const sendState = createInitialSendState();
+		let placeholder: SessionCursorAgentCreatingEntry;
+		const creating = createSessionAgentEntry(scopeKey, instanceId, sendState, params).then(async (createdEntry) => {
+			const stillCurrent =
+				sessionAgentsByScope.get(scopeKey) === placeholder &&
+				getScopeCreationGeneration(scopeKey) === placeholder.creationGeneration;
+			if (!stillCurrent) {
+				await disposePoolEntry(createdEntry);
+				if (sessionAgentsByScope.get(scopeKey) === placeholder) {
+					sessionAgentsByScope.delete(scopeKey);
+				}
+				throw new SessionCursorAgentCreationSupersededError();
+			}
+			sessionAgentsByScope.set(scopeKey, createdEntry);
+			return createdEntry;
+		});
+		placeholder = {
+			status: "creating",
+			poolKey,
+			instanceId,
+			scopeKey,
+			sendState,
+			creationGeneration,
+			creating,
+		};
+		sessionAgentsByScope.set(scopeKey, placeholder);
+
+		try {
+			const createdEntry = await creating;
+			const lease = await tryLeaseReadyEntry(createdEntry, scopeKey, params, poolKey, true);
+			if (lease) return lease;
+			continue;
+		} catch (error) {
 			if (sessionAgentsByScope.get(scopeKey) === placeholder) {
 				sessionAgentsByScope.delete(scopeKey);
 			}
-			throw new SessionCursorAgentCreationSupersededError();
-		}
-		sessionAgentsByScope.set(scopeKey, createdEntry);
-		return createdEntry;
-	});
-	placeholder.creating = creating;
-	sessionAgentsByScope.set(scopeKey, placeholder);
-
-	try {
-		const createdEntry = await creating;
-		return leaseFromEntry(createdEntry, scopeKey, params, true);
-	} catch (error) {
-		if (sessionAgentsByScope.get(scopeKey) === placeholder) {
-			sessionAgentsByScope.delete(scopeKey);
-		}
-		if (error instanceof SessionCursorAgentCreationSupersededError) {
-			assertScopeAcceptsAcquire(scopeKey);
-			rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
-			return acquireSessionCursorAgent(params);
+			if (error instanceof SessionCursorAgentCreationSupersededError) {
+				assertScopeAcceptsAcquire(scopeKey);
+				rethrowSupersededWhenReplacedByDifferentPoolKey(scopeKey, poolKey, error);
+				continue;
+			}
+			throw error;
 		}
-		throw error;
 	}
 }
 
@@ -361,6 +557,7 @@ export function registerCursorSessionAgent(_pi: CursorSessionAgentExtensionApi):
 
 export const __testUtils = {
 	sessionAgentsByScope,
+	getSessionCursorAgentPoolState,
 	invalidateSessionAgent,
 	disposeSessionCursorAgent,
 	resetSessionCursorAgent,

package/src/cursor-session-send-policy.ts

@@ -0,0 +1,43 @@
+import type { Context } from "@earendil-works/pi-ai";
+import {
+	buildCursorIncrementalPrompt,
+	buildCursorPrompt,
+	shouldBootstrapCursorContext,
+	type CursorPrompt,
+	type CursorPromptOptions,
+} from "./context.js";
+import type { SessionCursorAgentSendState } from "./cursor-session-agent.js";
+
+// Long-lived SDK session agents can drift tool-call behavior; recreate the agent after this many successful incremental sends.
+export const MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP = 20;
+
+export type CursorSessionSendMode = "bootstrap" | "incremental";
+
+export type CursorSessionSendReason = "initial" | "context_divergence" | "incremental_threshold" | "incremental";
+
+export interface CursorSessionSendPlan {
+	mode: CursorSessionSendMode;
+	resetAgent: boolean;
+	reason: CursorSessionSendReason;
+}
+
+export function planCursorSessionSend(sendState: SessionCursorAgentSendState, context: Context): CursorSessionSendPlan {
+	if (!sendState.bootstrapped) {
+		return { mode: "bootstrap", resetAgent: false, reason: "initial" };
+	}
+	if (sendState.incrementalSendCount >= MAX_COMPLETED_INCREMENTAL_SENDS_BEFORE_REBOOTSTRAP) {
+		return { mode: "bootstrap", resetAgent: true, reason: "incremental_threshold" };
+	}
+	if (shouldBootstrapCursorContext(sendState, context)) {
+		return { mode: "bootstrap", resetAgent: true, reason: "context_divergence" };
+	}
+	return { mode: "incremental", resetAgent: false, reason: "incremental" };
+}
+
+export function buildCursorSessionSendPrompt(
+	context: Context,
+	options: CursorPromptOptions,
+	plan: CursorSessionSendPlan,
+): CursorPrompt {
+	return plan.mode === "bootstrap" ? buildCursorPrompt(context, options) : buildCursorIncrementalPrompt(context, options);
+}

package/src/cursor-setting-sources.ts

@@ -0,0 +1,29 @@
+import type { SettingSource } from "@cursor/sdk";
+
+export const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
+
+export function resolveCursorSettingSources(raw?: string): SettingSource[] | undefined {
+	const trimmed = raw?.trim();
+	if (!trimmed) return ["all"];
+	const normalized = trimmed.toLowerCase();
+	if (["0", "false", "off", "none", "omit", "disabled"].includes(normalized)) return undefined;
+	if (["1", "true", "on", "all"].includes(normalized)) return ["all"];
+	return trimmed
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter((entry): entry is SettingSource => Boolean(entry));
+}
+
+export function getEffectiveCursorSettingSources(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): SettingSource[] | undefined {
+	return resolveCursorSettingSources(raw);
+}
+
+export function cursorSettingSourcesLoadUserAgentsRules(settingSources: SettingSource[] | undefined): 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");
+}

package/src/cursor-state.ts

@@ -2,9 +2,9 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext, SessionStartEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isCursorModel } from "./cursor-model.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 
-const CURSOR_PROVIDER = "cursor";
 const FAST_ENTRY_TYPE = "cursor-fast-state";
 const GLOBAL_CONFIG_FILE = "cursor-sdk.json";
 
@@ -94,10 +94,6 @@ function getEffectiveFast(baseModelId: string, modelId: string): boolean | undef
 	return sessionFastPreferences.get(baseModelId) ?? globalFastPreferences.get(baseModelId) ?? metadata.defaultFast;
 }
 
-function isCursorModel(model: CursorFastControlsModel): boolean {
-	return model?.provider === CURSOR_PROVIDER || model?.api === "cursor-sdk";
-}
-
 function updateCursorStatus(ctx: { model: CursorFastControlsModel; ui: Pick<ExtensionContext["ui"], "setStatus"> }, model = ctx.model): void {
 	if (!model || !isCursorModel(model)) {
 		ctx.ui.setStatus("cursor", undefined);

package/src/cursor-tool-lifecycle.ts

@@ -0,0 +1,85 @@
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { extractWebSearchQuery } from "./cursor-web-tool-activity.js";
+import { firstNonEmptyLine, getArray, getString, truncateArg } from "./cursor-transcript-utils.js";
+import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
+
+/** Defer pending lifecycle lines so fast start+complete pairs coalesce into the completed replay card only. */
+export const CURSOR_TOOL_LIFECYCLE_DEFER_MS = 75;
+
+export function isCursorToolLifecycleEligible(toolCall: unknown): boolean {
+	return classifyCursorToolVisibility(toolCall).lifecycleEligible;
+}
+
+function getCursorToolLifecycleTitle(toolCall: unknown): string {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	return visibility.lifecycleTitle ?? `Cursor ${visibility.normalizedName}`;
+}
+
+/** Prefixes that commonly introduce path/URI values in free-text pending lifecycle details. */
+const LIFECYCLE_DETAIL_PATH_PREFIX = String.raw`(?:^|[\s'"({=,:;\[\]{}])`;
+
+function containsCursorLifecycleUnsafeDetail(text: string): boolean {
+	if (/\b[a-z][a-z0-9+.-]*:\/\//i.test(text)) return true;
+	if (/\bwww\.\S+/i.test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}~\\/\\S*`).test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}\\/\\S+`).test(text)) return true;
+	if (new RegExp(`${LIFECYCLE_DETAIL_PATH_PREFIX}[A-Za-z]:[\\\\/]`).test(text)) return true;
+	return false;
+}
+
+function scrubLifecycleDetail(value: string | undefined, apiKey?: string): string | undefined {
+	if (!value?.trim()) return undefined;
+	const scrubbed = truncateCursorDisplayLine(scrubSensitiveText(value, apiKey));
+	if (containsCursorLifecycleUnsafeDetail(scrubbed)) return undefined;
+	return scrubbed;
+}
+
+export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
+	const visibility = classifyCursorToolVisibility(toolCall);
+	const args = visibility.args;
+
+	switch (visibility.normalizedKey) {
+		case "task": {
+			return scrubLifecycleDetail(getString(args, "description"), apiKey) ?? "task";
+		}
+		case "shell": {
+			return "shell";
+		}
+		case "mcp": {
+			return scrubLifecycleDetail(getString(args, "toolName"), apiKey) ?? "mcp";
+		}
+		case "generateimage": {
+			return scrubLifecycleDetail(getString(args, "prompt") ?? getString(args, "description"), apiKey) ?? "image generation";
+		}
+		case "recordscreen": {
+			return scrubLifecycleDetail(getString(args, "mode"), apiKey) ?? "screen recording";
+		}
+		case "semsearch": {
+			return scrubLifecycleDetail(getString(args, "query"), apiKey) ?? "semantic search";
+		}
+		case "websearch": {
+			return scrubLifecycleDetail(extractWebSearchQuery(args), apiKey) ?? "web search";
+		}
+		case "webfetch": {
+			return "web fetch";
+		}
+		case "createplan": {
+			const plan = getString(args, "plan");
+			return scrubLifecycleDetail(plan ? firstNonEmptyLine(plan) ?? plan : undefined, apiKey) ?? "plan";
+		}
+		case "updatetodos": {
+			const todos = getArray(args, "todos") ?? getArray(args, "items");
+			if (todos && todos.length > 0) return truncateArg(`${todos.length} item${todos.length === 1 ? "" : "s"}`);
+			return "todos";
+		}
+		default:
+			return undefined;
+	}
+}
+
+export function formatCursorToolLifecycleProgressText(toolCall: unknown, apiKey?: string): string | undefined {
+	const label = buildCursorToolLifecycleLabel(toolCall, apiKey);
+	if (!label) return undefined;
+	return `${getCursorToolLifecycleTitle(toolCall)}: ${label}\n`;
+}