pi-cursor-sdk 0.1.19 → 0.1.20

package/src/cursor-session-agent.ts

@@ -26,22 +26,53 @@ export interface SessionCursorAgentSendState {
 
 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");
@@ -92,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;
@@ -131,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 {
@@ -153,10 +198,12 @@ async function disposePoolEntryForScope(scopeKey: string, options?: { terminal?:
 	const entry = sessionAgentsByScope.get(scopeKey);
 	invalidatedScopeKeys.delete(scopeKey);
 	if (!entry) return;
-	const orphanedCreating = entry.creating;
 	sessionAgentsByScope.delete(scopeKey);
-	if (entry.creating || !entry.agent) {
-		orphanedCreating?.catch(() => {
+	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;
@@ -169,14 +216,96 @@ function createInitialSendState(): SessionCursorAgentSendState {
 }
 
 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,
@@ -185,18 +314,54 @@ function leaseFromEntry(
 	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) {
@@ -233,11 +398,13 @@ async function createSessionAgentEntry(
 	}
 
 	return {
+		status: "ready",
 		poolKey: resolvedPoolKey,
+		instanceId,
 		scopeKey,
 		agent,
 		bridgeRun,
-		sendState: createInitialSendState(),
+		sendState,
 	};
 }
 
@@ -249,95 +416,102 @@ export {
 } from "./cursor-session-send-policy.js";
 export { shouldBootstrapCursorContext, 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);
-	if (bootstrapped) {
-		entry.sendState.incrementalSendCount = 0;
-		return;
-	}
-	entry.sendState.incrementalSendCount += 1;
-}
-
 export function invalidateSessionAgent(scopeKey: string = getCursorSessionScopeKey()): void {
 	invalidatedScopeKeys.add(scopeKey);
 }
 
 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;
 	}
 }
 
@@ -383,6 +557,7 @@ export function registerCursorSessionAgent(_pi: CursorSessionAgentExtensionApi):
 
 export const __testUtils = {
 	sessionAgentsByScope,
+	getSessionCursorAgentPoolState,
 	invalidateSessionAgent,
 	disposeSessionCursorAgent,
 	resetSessionCursorAgent,

package/src/cursor-tool-lifecycle.ts

@@ -1,44 +1,19 @@
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
-import { getCursorReplayDisplayLabel, type CursorReplayLegacyToolName } from "./cursor-tool-names.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
-import { extractWebSearchQuery, resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
-import { firstNonEmptyLine, getArray, getString, getToolArgs, getToolName, normalizeToolName, truncateArg } from "./cursor-transcript-utils.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;
 
-const LIFECYCLE_ELIGIBLE_TOOLS = new Set(
-	["task", "shell", "mcp", "generateImage", "recordScreen", "semSearch", "webSearch", "webFetch", "createPlan", "updateTodos"].map(
-		(name) => name.toLowerCase(),
-	),
-);
-
-const LIFECYCLE_TITLE_KEYS: Partial<Record<string, CursorReplayLegacyToolName>> = {
-	task: "cursor_task",
-	mcp: "cursor_mcp",
-	generateimage: "cursor_generate_image",
-	recordscreen: "cursor_record_screen",
-	semsearch: "cursor_sem_search",
-	websearch: "cursor_web_search",
-	webfetch: "cursor_web_fetch",
-	createplan: "cursor_create_plan",
-	updatetodos: "cursor_update_todos",
-};
-
 export function isCursorToolLifecycleEligible(toolCall: unknown): boolean {
-	const args = getToolArgs(toolCall);
-	const name = resolveTranscriptToolName(getToolName(toolCall), args);
-	return LIFECYCLE_ELIGIBLE_TOOLS.has(normalizeToolName(name).toLowerCase());
+	return classifyCursorToolVisibility(toolCall).lifecycleEligible;
 }
 
 function getCursorToolLifecycleTitle(toolCall: unknown): string {
-	const args = getToolArgs(toolCall);
-	const name = resolveTranscriptToolName(getToolName(toolCall), args);
-	const normalized = normalizeToolName(name).toLowerCase();
-	const labelKey = LIFECYCLE_TITLE_KEYS[normalized];
-	if (labelKey) return getCursorReplayDisplayLabel(labelKey);
-	if (normalized === "shell") return "Cursor shell";
-	return `Cursor ${normalizeToolName(name)}`;
+	const visibility = classifyCursorToolVisibility(toolCall);
+	return visibility.lifecycleTitle ?? `Cursor ${visibility.normalizedName}`;
 }
 
 /** Prefixes that commonly introduce path/URI values in free-text pending lifecycle details. */
@@ -61,11 +36,10 @@ function scrubLifecycleDetail(value: string | undefined, apiKey?: string): strin
 }
 
 export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
-	const args = getToolArgs(toolCall);
-	const name = resolveTranscriptToolName(getToolName(toolCall), args);
-	const normalized = normalizeToolName(name).toLowerCase();
+	const visibility = classifyCursorToolVisibility(toolCall);
+	const args = visibility.args;
 
-	switch (normalized) {
+	switch (visibility.normalizedKey) {
 		case "task": {
 			return scrubLifecycleDetail(getString(args, "description"), apiKey) ?? "task";
 		}

package/src/cursor-tool-names.ts

@@ -51,6 +51,24 @@ const CURSOR_REPLAY_PROMPT_LABELS = {
 	cursor_web_fetch: "Cursor web fetch",
 } as const satisfies Record<CursorReplayLegacyToolName, string>;
 
+export const CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME = {
+	edit: "cursor_edit",
+	write: "cursor_write",
+	readLints: "cursor_read_lints",
+	delete: "cursor_delete",
+	updateTodos: "cursor_update_todos",
+	task: "cursor_task",
+	createPlan: "cursor_create_plan",
+	generateImage: "cursor_generate_image",
+	mcp: "cursor_mcp",
+	semSearch: "cursor_sem_search",
+	recordScreen: "cursor_record_screen",
+	webSearch: "cursor_web_search",
+	webFetch: "cursor_web_fetch",
+} as const satisfies Record<string, CursorReplayLegacyToolName>;
+
+export type CursorReplayActivityToolName = keyof typeof CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME;
+
 export function isCursorReplayLegacyToolName(toolName: string): toolName is CursorReplayLegacyToolName {
 	return CURSOR_REPLAY_LEGACY_TOOL_NAMES.some((legacyToolName) => legacyToolName === toolName);
 }
@@ -77,3 +95,12 @@ export function getCursorReplayDisplayLabel(toolName: CursorReplayToolName): str
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return "Cursor activity";
 	return CURSOR_REPLAY_PROMPT_LABELS[toolName];
 }
+
+export function getCursorReplayActivityLabelKey(toolName: string): CursorReplayLegacyToolName | undefined {
+	return CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME[toolName as CursorReplayActivityToolName];
+}
+
+export function getCursorReplayActivityTitle(toolName: string): string | undefined {
+	const labelKey = getCursorReplayActivityLabelKey(toolName);
+	return labelKey ? getCursorReplayDisplayLabel(labelKey) : undefined;
+}

package/src/cursor-tool-visibility.ts

@@ -0,0 +1,63 @@
+import { getCursorReplayActivityTitle } from "./cursor-tool-names.js";
+import { getToolArgs, getToolName, normalizeToolName } from "./cursor-transcript-utils.js";
+import { resolveTranscriptToolName } from "./cursor-web-tool-activity.js";
+
+interface CursorToolVisibilityConfig {
+	incompleteTitle?: string;
+	lifecycleTitle?: string;
+	lifecycleEligible?: boolean;
+	fastLocalDiscovery?: boolean;
+}
+
+export interface CursorToolVisibility {
+	args: Record<string, unknown>;
+	displayName: string;
+	normalizedName: string;
+	normalizedKey: string;
+	activityTitle?: string;
+	incompleteTitle?: string;
+	lifecycleTitle?: string;
+	lifecycleEligible: boolean;
+	fastLocalDiscovery: boolean;
+}
+
+const CURSOR_TOOL_VISIBILITY_BY_NAME: Record<string, CursorToolVisibilityConfig> = {
+	read: { incompleteTitle: "Cursor read", fastLocalDiscovery: true },
+	grep: { incompleteTitle: "Cursor grep", fastLocalDiscovery: true },
+	glob: { incompleteTitle: "Cursor find", fastLocalDiscovery: true },
+	ls: { incompleteTitle: "Cursor ls", fastLocalDiscovery: true },
+	shell: { incompleteTitle: "Cursor shell", lifecycleTitle: "Cursor shell", lifecycleEligible: true },
+	task: { lifecycleEligible: true },
+	mcp: { lifecycleEligible: true },
+	generateimage: { lifecycleEligible: true },
+	recordscreen: { lifecycleEligible: true },
+	semsearch: { lifecycleEligible: true },
+	websearch: { lifecycleEligible: true },
+	webfetch: { lifecycleEligible: true },
+	createplan: { lifecycleEligible: true },
+	updatetodos: { lifecycleEligible: true },
+};
+
+export function classifyCursorToolVisibility(toolCall: unknown): CursorToolVisibility {
+	const args = getToolArgs(toolCall);
+	const displayName = resolveTranscriptToolName(getToolName(toolCall), args);
+	const normalizedName = normalizeToolName(displayName);
+	const normalizedKey = normalizedName.toLowerCase();
+	const config = CURSOR_TOOL_VISIBILITY_BY_NAME[normalizedKey];
+	const replayActivityTitle = getCursorReplayActivityTitle(normalizedName);
+	return {
+		args,
+		displayName,
+		normalizedName,
+		normalizedKey,
+		activityTitle: replayActivityTitle ?? config?.incompleteTitle ?? config?.lifecycleTitle,
+		incompleteTitle: replayActivityTitle ?? config?.incompleteTitle,
+		lifecycleTitle: replayActivityTitle ?? config?.lifecycleTitle,
+		lifecycleEligible: config?.lifecycleEligible ?? false,
+		fastLocalDiscovery: config?.fastLocalDiscovery ?? false,
+	};
+}
+
+export function isFastLocalDiscoveryTool(toolCall: unknown): boolean {
+	return classifyCursorToolVisibility(toolCall).fastLocalDiscovery;
+}