pi-cursor-sdk 0.1.37 → 0.1.38

package/src/cursor-session-agent.ts

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

package/src/cursor-session-scope.ts

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

package/src/cursor-setting-sources.ts

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

package/src/cursor-skill-tool.ts

@@ -2,19 +2,15 @@ import type { Dirent } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
 	BuildSystemPromptOptions,
 	ExtensionAPI,
 	ExtensionContext,
-	ExtensionHandler,
-	SessionStartEvent,
 	Skill,
-	TurnStartEvent,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { isCursorModel } from "./cursor-model.js";
-import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-snapshot.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
 
 export const CURSOR_ACTIVATE_SKILL_TOOL_NAME = "cursor_activate_skill";
 export const CURSOR_ACTIVATE_SKILL_MCP_NAME = "pi__cursor_activate_skill";
@@ -23,12 +19,7 @@ const AVAILABLE_SKILLS_SECTION_PATTERN = /\n\nThe following skills provide speci
 const MAX_SKILL_RESOURCES = 80;
 const RESOURCE_DIR_NAMES = ["scripts", "references", "assets"] as const;
 
-type CursorSkillToolExtensionApi = Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> & {
-	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
-	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
-	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
-	on(event: "model_select", handler: (event: { model: ExtensionContext["model"] }, ctx: ExtensionContext) => Promise<void> | void): void;
-};
+type CursorSkillToolExtensionApi = Pick<ExtensionAPI, "getActiveTools" | "registerTool" | "setActiveTools"> & CursorModelLifecycleExtensionApi;
 
 type CursorActivateSkillParams = {
 	name?: string;
@@ -229,26 +220,28 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 		syncCursorSkillToolForModel(pi, model);
 	};
 
-	pi.on("session_start", (_event, ctx) => {
-		clearSkillsAndSync(ctx.model);
-	});
-	pi.on("model_select", (event) => {
-		clearSkillsAndSync(event.model);
-	});
-	pi.on("turn_start", (_event, ctx) => {
-		if (!isCursorModel(ctx.model)) setCurrentSkills([]);
-		syncCursorSkillToolForModel(pi, ctx.model);
-	});
-	pi.on("before_agent_start", (event, ctx) => {
-		if (isCursorModel(ctx.model)) {
-			setCurrentSkills(event.systemPromptOptions?.skills);
-		} else {
-			setCurrentSkills([]);
-		}
-		syncCursorSkillToolForModel(pi, ctx.model);
-		const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions);
-		if (resolved === event.systemPrompt) return undefined;
-		return { systemPrompt: resolved };
+	registerCursorModelLifecycle(pi, {
+		sessionStart: (_event, ctx) => {
+			clearSkillsAndSync(ctx.model);
+		},
+		modelSelect: (event) => {
+			clearSkillsAndSync(event.model);
+		},
+		turnStart: (_event, ctx) => {
+			if (!isCursorModel(ctx.model)) setCurrentSkills([]);
+			syncCursorSkillToolForModel(pi, ctx.model);
+		},
+		beforeAgentStart: (event, ctx) => {
+			if (isCursorModel(ctx.model)) {
+				setCurrentSkills(event.systemPromptOptions?.skills);
+			} else {
+				setCurrentSkills([]);
+			}
+			syncCursorSkillToolForModel(pi, ctx.model);
+			const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions);
+			if (resolved === event.systemPrompt) return undefined;
+			return { systemPrompt: resolved };
+		},
 	});
 }
 

package/src/cursor-state.ts

@@ -15,9 +15,12 @@ import {
 } from "./cursor-pi-tool-bridge-snapshot.js";
 import {
 	CURSOR_SETTING_SOURCES_ENV,
-	getEffectiveCursorSettingSources,
+	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
 import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle } from "./cursor-model-lifecycle.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import { getCursorModelMetadata } from "./model-discovery.js";
 
 const FAST_ENTRY_TYPE = "cursor-fast-state";
@@ -58,6 +61,7 @@ let cliForceFast = false;
 let cliForceNoFast = false;
 let sessionCursorAgentMode: AgentModeOption | undefined;
 let cliCursorModeState: CursorCliModeState = { kind: "unset" };
+const invalidCursorModeNotifiedSessionScopeKeys = new Set<string>();
 
 export function isCursorAgentMode(value: unknown): value is AgentModeOption {
 	return value === "agent" || value === "plan";
@@ -69,13 +73,10 @@ export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined
 	return isCursorAgentMode(mode) ? mode : undefined;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function isCursorFastEntryData(value: unknown): value is CursorFastEntryData {
-	if (!isRecord(value)) return false;
-	return (typeof value.modelId === "string" || typeof value.baseModelId === "string") && typeof value.fast === "boolean";
+	const record = asRecord(value);
+	if (!record) return false;
+	return (typeof record.modelId === "string" || typeof record.baseModelId === "string") && typeof record.fast === "boolean";
 }
 
 function getCursorFastEntryModelId(data: CursorFastEntryData): string {
@@ -83,17 +84,19 @@ function getCursorFastEntryModelId(data: CursorFastEntryData): string {
 }
 
 function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
-	return isRecord(value) && isCursorAgentMode(value.mode);
+	return isCursorAgentMode(asRecord(value)?.mode);
 }
 
 function parseCursorGlobalConfig(value: unknown): CursorGlobalConfig | undefined {
-	if (!isRecord(value)) return undefined;
-	const { fastDefaults } = value;
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const { fastDefaults } = record;
 	if (fastDefaults === undefined) return {};
-	if (!isRecord(fastDefaults)) return undefined;
+	const fastDefaultsRecord = asRecord(fastDefaults);
+	if (!fastDefaultsRecord) return undefined;
 	return {
 		fastDefaults: Object.fromEntries(
-			Object.entries(fastDefaults).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
+			Object.entries(fastDefaultsRecord).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
 		),
 	};
 }
@@ -174,23 +177,38 @@ function formatInvalidCursorMode(raw: string): string {
 	return `Invalid --cursor-mode "${raw}". Use "agent" or "plan".`;
 }
 
-export function getEffectiveCursorAgentMode(): AgentModeOption {
+export type CursorAgentModeResolution =
+	| { kind: "valid"; mode: AgentModeOption }
+	| { kind: "invalid"; raw: string; message: string };
+
+export function getStoredCursorAgentMode(): AgentModeOption {
+	return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+}
+
+export function resolveCursorAgentMode(): CursorAgentModeResolution {
 	switch (cliCursorModeState.kind) {
 		case "valid":
-			return cliCursorModeState.mode;
+			return { kind: "valid", mode: cliCursorModeState.mode };
 		case "invalid":
-			throw new Error(cliCursorModeState.message);
+			return { kind: "invalid", raw: cliCursorModeState.raw, message: cliCursorModeState.message };
 		case "unset":
-			return sessionCursorAgentMode ?? DEFAULT_CURSOR_AGENT_MODE;
+			return { kind: "valid", mode: getStoredCursorAgentMode() };
 	}
 }
 
+export function getCursorProviderAgentModeOrThrow(): AgentModeOption {
+	const resolution = resolveCursorAgentMode();
+	if (resolution.kind === "invalid") throw new Error(resolution.message);
+	return resolution.mode;
+}
+
 function formatCursorStatus(fast: boolean | undefined): string | undefined {
 	const parts: string[] = [];
+	const modeResolution = resolveCursorAgentMode();
 	if (fast === true) parts.push("fast");
-	if (cliCursorModeState.kind === "invalid") {
+	if (modeResolution.kind === "invalid") {
 		parts.push("mode invalid");
-	} else if (getEffectiveCursorAgentMode() === "plan") {
+	} else if (modeResolution.mode === "plan") {
 		parts.push("plan");
 	}
 	return parts.length > 0 ? `cursor ${parts.join(" · ")}` : undefined;
@@ -255,7 +273,7 @@ function persistCursorModePreference(pi: Pick<ExtensionAPI, "appendEntry">, mode
 	}
 }
 
-function restoreCliCursorMode(raw: boolean | string | undefined, mode: ExtensionContext["mode"], notify: ExtensionContext["ui"]["notify"]): void {
+function restoreCliCursorMode(raw: boolean | string | undefined): void {
 	cliCursorModeState = { kind: "unset" };
 	if (raw === undefined || raw === "" || raw === false) return;
 	const parsed = parseCursorAgentMode(raw);
@@ -266,15 +284,19 @@ function restoreCliCursorMode(raw: boolean | string | undefined, mode: Extension
 	const rawText = String(raw);
 	const message = formatInvalidCursorMode(rawText);
 	cliCursorModeState = { kind: "invalid", raw: rawText, message };
-	if (mode === "tui") {
-		notify(message, "error");
-		return;
-	}
-	throw new Error(message);
+}
+
+function notifyInvalidCursorModeIfCursorActive(ctx: Pick<ExtensionContext, "hasUI" | "mode" | "ui">): void {
+	const modeResolution = resolveCursorAgentMode();
+	if (modeResolution.kind !== "invalid" || !ctx.hasUI || ctx.mode !== "tui") return;
+	const scopeKey = getCursorSessionScopeKey();
+	if (invalidCursorModeNotifiedSessionScopeKeys.has(scopeKey)) return;
+	invalidCursorModeNotifiedSessionScopeKeys.add(scopeKey);
+	ctx.ui.notify(modeResolution.message, "error");
 }
 
 function formatEffectiveCursorSettingSourcesLabel(raw: string | undefined = process.env[CURSOR_SETTING_SOURCES_ENV]): string {
-	const effective = getEffectiveCursorSettingSources(raw);
+	const effective = resolveCursorSettingSources(raw);
 	const effectiveLabel = effective === undefined ? "none" : effective.join(",");
 	const rawLabel = raw?.trim() ? raw.trim() : "(unset → all)";
 	return `${rawLabel} (effective: ${effectiveLabel})`;
@@ -395,10 +417,11 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 			const usage = "Usage: /cursor-mode agent|plan";
 			const mode = parseCursorAgentMode(args);
 			if (!args.trim()) {
-				try {
-					ctx.ui.notify(`Cursor mode is ${getEffectiveCursorAgentMode()}. ${usage}`, "info");
-				} catch (error) {
-					ctx.ui.notify(`${error instanceof Error ? error.message : String(error)} ${usage}`, "error");
+				const modeResolution = resolveCursorAgentMode();
+				if (modeResolution.kind === "invalid") {
+					ctx.ui.notify(`${modeResolution.message} ${usage}`, "error");
+				} else {
+					ctx.ui.notify(`Cursor mode is ${modeResolution.mode}. ${usage}`, "info");
 				}
 				return;
 			}
@@ -429,28 +452,26 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 		},
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
-		globalFastPreferences = loadGlobalFastPreferences();
-		cliForceFast = pi.getFlag("cursor-fast") === true;
-		cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
-		restoreSessionFastPreferences(ctx);
-		restoreSessionCursorMode(ctx);
-		restoreCliCursorMode(pi.getFlag("cursor-mode"), ctx.mode, ctx.ui.notify.bind(ctx.ui));
-		updateCursorStatus(ctx);
-	});
-
-	pi.on("model_select", async (event, ctx) => {
-		updateCursorStatus(ctx, event.model);
-	});
-
-	pi.on("turn_start", async (_event, ctx) => {
-		updateCursorStatus(ctx);
+	registerCursorModelLifecycle(pi, {
+		sessionStart: (_event, ctx) => {
+			globalFastPreferences = loadGlobalFastPreferences();
+			cliForceFast = pi.getFlag("cursor-fast") === true;
+			cliForceNoFast = pi.getFlag("cursor-no-fast") === true;
+			restoreSessionFastPreferences(ctx);
+			restoreSessionCursorMode(ctx);
+			restoreCliCursorMode(pi.getFlag("cursor-mode"));
+		},
+		sync: (ctx) => {
+			if (isCursorModel(ctx.model)) notifyInvalidCursorModeIfCursorActive(ctx);
+			updateCursorStatus(ctx);
+		},
 	});
 }
 
 function resetCursorModeStateForTests(): void {
 	sessionCursorAgentMode = undefined;
 	cliCursorModeState = { kind: "unset" };
+	invalidCursorModeNotifiedSessionScopeKeys.clear();
 }
 
 export const __testUtils = {

package/src/cursor-tool-lifecycle.ts

@@ -1,9 +1,10 @@
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import { getCursorToolLifecycleLabelKind } from "./cursor-tool-presentation-registry.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";
+import { extractWebSearchQuery } from "./cursor-web-tool-args.js";
+import { getArray, getString } from "./cursor-record-utils.js";
+import { firstNonEmptyLine, truncateArg } from "./cursor-transcript-utils.js";
+import { classifyCursorToolVisibility, type CursorToolVisibility } 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;
@@ -12,8 +13,7 @@ export function isCursorToolLifecycleEligible(toolCall: unknown): boolean {
 	return classifyCursorToolVisibility(toolCall).lifecycleEligible;
 }
 
-function getCursorToolLifecycleTitle(toolCall: unknown): string {
-	const visibility = classifyCursorToolVisibility(toolCall);
+function getCursorToolLifecycleTitle(visibility: CursorToolVisibility): string {
 	return visibility.lifecycleTitle ?? `Cursor ${visibility.normalizedName}`;
 }
 
@@ -36,8 +36,10 @@ function scrubLifecycleDetail(value: string | undefined, apiKey?: string): strin
 	return scrubbed;
 }
 
-export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
-	const visibility = classifyCursorToolVisibility(toolCall);
+function buildCursorToolLifecycleLabelFromVisibility(
+	visibility: CursorToolVisibility,
+	apiKey?: string,
+): string | undefined {
 	const args = visibility.args;
 
 	switch (getCursorToolLifecycleLabelKind(visibility.normalizedKey)) {
@@ -79,8 +81,13 @@ export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string
 	}
 }
 
+export function buildCursorToolLifecycleLabel(toolCall: unknown, apiKey?: string): string | undefined {
+	return buildCursorToolLifecycleLabelFromVisibility(classifyCursorToolVisibility(toolCall), apiKey);
+}
+
 export function formatCursorToolLifecycleProgressText(toolCall: unknown, apiKey?: string): string | undefined {
-	const label = buildCursorToolLifecycleLabel(toolCall, apiKey);
+	const visibility = classifyCursorToolVisibility(toolCall);
+	const label = buildCursorToolLifecycleLabelFromVisibility(visibility, apiKey);
 	if (!label) return undefined;
-	return `${getCursorToolLifecycleTitle(toolCall)}: ${label}\n`;
+	return `${getCursorToolLifecycleTitle(visibility)}: ${label}\n`;
 }