pi-cursor-sdk 0.4.0 → 0.5.2

package/src/cursor-session-store.ts

@@ -1,9 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync } from "node:fs";
 import { rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { dirname, join, toNamespacedPath } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep, toNamespacedPath } from "node:path";
 import type { LocalAgentStore } from "@cursor/sdk";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 
 export interface CursorSessionStoreIdentity {
 	readonly version: 1;
@@ -16,15 +18,32 @@ export interface OpenCursorSessionStore {
 	dispose(): Promise<void>;
 }
 
-export interface CursorSessionStoreSelection {
+type CursorPersistentStoreIdentities = {
+	workspaceRoot: string;
+	sessionStore: CursorSessionStoreIdentity;
+} & ({
+	domain: "default";
+	defaultStore: CursorSessionStoreIdentity;
+	storeRoot?: never;
+} | {
+	domain: "custom";
+	storeRoot: string;
+	defaultStore?: never;
+});
+
+export type CursorSessionStoreSelection = {
 	sessionStore: OpenCursorSessionStore;
-	identities: {
-		defaultStore: CursorSessionStoreIdentity;
-		sessionStore: CursorSessionStoreIdentity;
-	};
+} & ({
+	persistent: true;
+	identities: CursorPersistentStoreIdentities;
 	resumeAttemptAllowed: boolean;
 	resumeFallback: boolean;
-}
+} | {
+	persistent: false;
+	identities: { sessionStore: CursorSessionStoreIdentity };
+	resumeAttemptAllowed: false;
+	resumeFallback: false;
+});
 
 interface CursorSessionStoreSdkOperations {
 	getDefaultStateRoot(cwd: string): string | Promise<string>;
@@ -32,6 +51,9 @@ interface CursorSessionStoreSdkOperations {
 }
 
 let sdkOperationsForTests: CursorSessionStoreSdkOperations | undefined;
+const activeWorkspaceRoots = new Map<string, { root: Promise<string>; users: number }>();
+// ponytail: leases protect only extension-owned stores in this process. Other SDK
+// users/processes must stop before upgrade; a cross-process lock belongs in the SDK.
 
 export function hashCursorSessionStoreScope(scopeKey: string): string {
 	return createHash("sha256")
@@ -41,9 +63,8 @@ export function hashCursorSessionStoreScope(scopeKey: string): string {
 		.slice(0, 32);
 }
 
-export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string, persistent: boolean): string {
-	const baseRoot = persistent ? defaultStateRoot : join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
-	return join(baseRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
+export function buildCursorSessionStateRoot(defaultStateRoot: string, scopeKey: string): string {
+	return join(defaultStateRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
 }
 
 async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
@@ -58,21 +79,81 @@ async function getSdkOperations(): Promise<CursorSessionStoreSdkOperations> {
 	};
 }
 
-export async function getCursorSessionStoreIdentities(
-	cwd: string,
-	scopeKey: string,
-	persistent: boolean,
-): Promise<{ defaultStore: CursorSessionStoreIdentity; sessionStore: CursorSessionStoreIdentity }> {
-	const defaultStateRoot = await (await getSdkOperations()).getDefaultStateRoot(cwd);
+function leaseWorkspaceRoot(key: string, ownership: { root: Promise<string>; users: number }) {
+	ownership.users++;
+	let released = false;
 	return {
-		defaultStore: { version: 1, stateRoot: defaultStateRoot },
-		sessionStore: {
-			version: 1,
-			stateRoot: buildCursorSessionStateRoot(defaultStateRoot, scopeKey, persistent),
+		root: ownership.root,
+		release: () => {
+			if (released) return;
+			released = true;
+			if (--ownership.users === 0) activeWorkspaceRoots.delete(key);
 		},
 	};
 }
 
+function workspaceLeaseKey(cwd: string, storeRoot: string | undefined): string {
+	return JSON.stringify([cwd, storeRoot ?? null]);
+}
+
+function acquireWorkspaceRoot(cwd: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	let ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) {
+		ownership = {
+			// Publish ownership synchronously, before SDK loading or the public getter.
+			root: Promise.resolve().then(async () => {
+				if (storeRoot !== undefined) {
+					const root = prepareCursorCustomStoreRoot(storeRoot);
+					return join(root, createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 32));
+				}
+				const operations = await getSdkOperations();
+				assertSafeWorkspaceLayout(cwd);
+				const root = await operations.getDefaultStateRoot(cwd);
+				assertSafeStorePath(root, dirname(root), "local store");
+				return root;
+			}),
+			users: 0,
+		};
+		activeWorkspaceRoots.set(key, ownership);
+	}
+	return leaseWorkspaceRoot(key, ownership);
+}
+
+function retainWorkspaceRoot(cwd: string, workspaceRoot: string, storeRoot: string | undefined) {
+	const key = workspaceLeaseKey(cwd, storeRoot);
+	const ownership = activeWorkspaceRoots.get(key);
+	if (!ownership) throw new Error("Cursor local workspace ownership is not active");
+	const lease = leaseWorkspaceRoot(key, ownership);
+	return {
+		...lease,
+		root: lease.root.then((root) => {
+			if (root !== workspaceRoot) throw new Error("Cursor local workspace ownership root mismatch");
+			return root;
+		}),
+	};
+}
+
+export async function withCursorSessionStoreIdentities<T>(
+	cwd: string,
+	scopeKey: string,
+	selectedRoot: string | undefined,
+	use: (identities: CursorPersistentStoreIdentities) => Promise<T>,
+): Promise<T> {
+	const storeRoot = selectedRoot === undefined ? undefined : normalizeCursorCustomStoreRoot(selectedRoot);
+	const lease = acquireWorkspaceRoot(cwd, storeRoot);
+	try {
+		const workspaceRoot = await lease.root;
+		return await use({
+			workspaceRoot,
+			sessionStore: { version: 1, stateRoot: buildCursorSessionStateRoot(workspaceRoot, scopeKey) },
+			...(storeRoot === undefined
+				? { domain: "default" as const, defaultStore: { version: 1 as const, stateRoot: workspaceRoot } }
+				: { domain: "custom" as const, storeRoot }),
+		});
+	} finally { lease.release(); }
+}
+
 export function cursorSessionStoreIdentitiesEqual(
 	left: CursorSessionStoreIdentity,
 	right: CursorSessionStoreIdentity,
@@ -80,30 +161,151 @@ export function cursorSessionStoreIdentitiesEqual(
 	return left.version === right.version && left.stateRoot === right.stateRoot;
 }
 
+function rejectedStorePath(stateRoot: string, base: string): string | undefined {
+	// User-managed ancestors above the SDK prefix (or our temporary removal root)
+	// may be links/junctions. Owned components, including the base, may not.
+	let path = resolve(base);
+	const suffix = relative(path, resolve(stateRoot));
+	if (suffix === ".." || suffix.startsWith(`..${sep}`) || isAbsolute(suffix)) return stateRoot;
+	for (const component of ["", ...suffix.split(sep).filter(Boolean)]) {
+		path = join(path, component);
+		try {
+			if (!lstatSync(path).isDirectory()) return path;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+}
+
+function assertSafeStorePath(stateRoot: string, base: string, label: string): void {
+	const rejected = rejectedStorePath(stateRoot, base);
+	if (rejected) throw new Error(`Cursor ${label} path contains a link or non-directory: ${rejected}`);
+}
+
+function workspaceHashes(cwd: string): { current: string; legacy: string | undefined } {
+	const current = createHash("sha256").update(cwd).digest("hex");
+	try {
+		return { current, legacy: createHash("md5").update(cwd).digest("hex") };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ERR_OSSL_EVP_UNSUPPORTED" ||
+			(error instanceof Error && error.message === "Digest method not supported")) return { current, legacy: undefined };
+		throw error;
+	}
+}
+
+function assertSafeWorkspaceLayout(cwd: string): void {
+	// ponytail: SDK 1.0.36 has no public read-only root resolver; use one when exposed.
+	// This pure layout is contract-verified against its factory and public getter;
+	// guard it before that getter can rename MD5 history through an owned link.
+	const slug = cwd.replace(/[^a-zA-Z0-9]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+	const prefix = join(homedir(), ".cursor", "projects", slug, "sdk-agent-store");
+	const { current, legacy } = workspaceHashes(cwd);
+	for (const hash of [current, legacy]) {
+		if (hash) assertSafeStorePath(join(prefix, hash), prefix, "local store");
+	}
+}
+
+function legacyWorkspaceRoot(cwd: string, defaultStateRoot: string): string | undefined {
+	// The public getter owns migration and may return MD5 after a failed rename.
+	const { current, legacy } = workspaceHashes(cwd);
+	if (!legacy) return undefined;
+	const prefix = dirname(defaultStateRoot);
+	if (defaultStateRoot !== join(prefix, current) && defaultStateRoot !== join(prefix, legacy)) return undefined;
+	return join(prefix, legacy);
+}
+
+export async function resolveCursorSessionStoreIdentity(options: {
+	cwd: string;
+	scopeKey: string;
+	identities: CursorPersistentStoreIdentities;
+	recordedIdentity?: CursorSessionStoreIdentity;
+	agentId: string;
+}): Promise<CursorSessionStoreIdentity | undefined> {
+	const { cwd, scopeKey, identities, agentId } = options;
+	if (identities.domain === "custom") {
+		if (!options.recordedIdentity || !cursorSessionStoreIdentitiesEqual(options.recordedIdentity, identities.sessionStore)) return undefined;
+		// Cleanup admits each candidate before cached-store reuse, which skips the open-time guard.
+		assertSafeStorePath(identities.sessionStore.stateRoot, dirname(identities.workspaceRoot), "local store");
+		guardCursorCustomStorePath(dirname(identities.workspaceRoot), identities.sessionStore.stateRoot).verify();
+		return identities.sessionStore;
+	}
+	const legacyRoot = legacyWorkspaceRoot(cwd, identities.defaultStore.stateRoot);
+	const legacyDefault = legacyRoot ? { version: 1 as const, stateRoot: legacyRoot } : undefined;
+	// Version-1 handles predate recorded identities and used the default workspace
+	// store. If both roots survive, that old store still owns their data.
+	const recorded = options.recordedIdentity ?? legacyDefault ?? identities.defaultStore;
+	const base = dirname(identities.defaultStore.stateRoot);
+	const current = [identities.defaultStore, identities.sessionStore];
+	const exact = current.find((identity) => cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (exact) {
+		assertSafeStorePath(exact.stateRoot, base, "local store");
+		return exact;
+	}
+	if (!legacyRoot) return undefined;
+	const legacySession = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(legacyRoot, scopeKey) };
+	const legacy = [legacyDefault, legacySession].find((identity) =>
+		identity && cursorSessionStoreIdentitiesEqual(identity, recorded));
+	if (!legacy) return undefined;
+	assertSafeStorePath(legacy.stateRoot, base, "local store");
+	if (existsSync(legacyRoot)) return legacy; // No merge or silent owner switch.
+	const migrated = legacy === legacyDefault ? identities.defaultStore : identities.sessionStore;
+	assertSafeStorePath(migrated.stateRoot, base, "local store");
+	if (!existsSync(migrated.stateRoot)) return undefined;
+	// A missing legacy path alone is not migration proof. The exact cwd/scope
+	// destination must independently contain this recorded agent with this cwd.
+	const opened = await openCursorSessionStore(cwd, migrated, identities.defaultStore.stateRoot);
+	try {
+		const agent = await opened.store.agents.get({ agentId });
+		return agent?.cwd === cwd ? migrated : undefined;
+	} finally {
+		await opened.dispose();
+	}
+}
+
 async function openOwnedCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
-	removalRoot?: string,
+	options: { workspaceRoot: string; storeRoot?: string } | { removalRoot: string },
 ): Promise<OpenCursorSessionStore> {
 	const openedIdentity = Object.freeze({ ...identity });
-	let store: LocalAgentStore & { dispose(): Promise<void> };
+	const lease = "workspaceRoot" in options ? retainWorkspaceRoot(cwd, options.workspaceRoot, options.storeRoot) : undefined;
+	const removalRoot = "removalRoot" in options ? options.removalRoot : undefined;
+	const removeTemporaryStore = async () => {
+		if (removalRoot) {
+			assertSafeStorePath(openedIdentity.stateRoot, removalRoot, "temporary store removal");
+			await rm(removalRoot, { recursive: true, force: true });
+		}
+	};
+	let store: (LocalAgentStore & { dispose(): Promise<void> }) | undefined;
 	try {
-		store = await (await getSdkOperations()).openSqliteStore({
+		await lease?.root;
+		const base = "workspaceRoot" in options ? dirname(options.workspaceRoot) : options.removalRoot;
+		assertSafeStorePath(openedIdentity.stateRoot, base, "local store");
+		const guard = "workspaceRoot" in options && options.storeRoot !== undefined
+			? guardCursorCustomStorePath(base, openedIdentity.stateRoot) : undefined;
+		const operations = await getSdkOperations();
+		guard?.verify();
+		store = await operations.openSqliteStore({
 			workspaceRef: cwd,
 			stateRoot: toNamespacedPath(openedIdentity.stateRoot),
 		});
+		guard?.verify();
 	} catch (error) {
-		if (removalRoot) await rm(removalRoot, { recursive: true, force: true }).catch(() => undefined);
+		await store?.dispose().catch(() => undefined);
+		lease?.release();
+		await removeTemporaryStore().catch(() => undefined);
 		throw error;
 	}
+	const openedStore = store;
 	return {
 		identity: openedIdentity,
-		store,
+		store: openedStore,
 		dispose: async () => {
 			try {
-				await store.dispose();
+				await openedStore.dispose();
 			} finally {
-				if (removalRoot) await rm(removalRoot, { recursive: true, force: true });
+				lease?.release();
+				await removeTemporaryStore();
 			}
 		},
 	};
@@ -112,40 +314,44 @@ async function openOwnedCursorSessionStore(
 export function openCursorSessionStore(
 	cwd: string,
 	identity: CursorSessionStoreIdentity,
+	workspaceRoot: string,
+	storeRoot?: string,
 ): Promise<OpenCursorSessionStore> {
-	return openOwnedCursorSessionStore(cwd, identity);
+	return openOwnedCursorSessionStore(cwd, identity, { workspaceRoot, storeRoot });
 }
 
 export async function openCursorSessionStoreForScope(options: {
 	cwd: string;
 	scopeKey: string;
 	persistent: boolean;
-	hasResumeHandle: boolean;
-	resumeIdentity?: CursorSessionStoreIdentity;
+	storeRoot?: string;
+	resume?: { identity?: CursorSessionStoreIdentity; agentId: string };
 }): Promise<CursorSessionStoreSelection> {
-	const identities = await getCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.persistent);
-	const requestedResumeIdentity = options.hasResumeHandle
-		? options.resumeIdentity ?? (options.persistent ? identities.defaultStore : undefined)
-		: undefined;
-	const resumableIdentities = options.persistent
-		? [identities.defaultStore, identities.sessionStore]
-		: [identities.sessionStore];
-	const resumeIdentity = requestedResumeIdentity && resumableIdentities
-		.find((identity) => cursorSessionStoreIdentitiesEqual(identity, requestedResumeIdentity));
-	let resumeAttemptAllowed = options.hasResumeHandle && resumeIdentity !== undefined;
-	let resumeFallback = options.persistent && options.hasResumeHandle && !resumeIdentity;
-	const selectedIdentity = resumeIdentity ?? identities.sessionStore;
-	const removalRoot = options.persistent ? undefined : dirname(dirname(identities.sessionStore.stateRoot));
-	let sessionStore: OpenCursorSessionStore;
-	try {
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, selectedIdentity, removalRoot);
-	} catch (error) {
-		if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
-		resumeAttemptAllowed = false;
-		resumeFallback = true;
-		sessionStore = await openOwnedCursorSessionStore(options.cwd, identities.sessionStore);
+	if (!options.persistent) {
+		const removalRoot = join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
+		const identity = { version: 1 as const, stateRoot: buildCursorSessionStateRoot(removalRoot, options.scopeKey) };
+		const sessionStore = await openOwnedCursorSessionStore(options.cwd, identity, { removalRoot });
+		return { persistent: false, sessionStore, identities: { sessionStore: identity }, resumeAttemptAllowed: false, resumeFallback: false };
 	}
-	return { sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	return withCursorSessionStoreIdentities(options.cwd, options.scopeKey, options.storeRoot, async (identities) => {
+		const resumeIdentity = options.resume ? await resolveCursorSessionStoreIdentity({
+			cwd: options.cwd, scopeKey: options.scopeKey, identities,
+			recordedIdentity: options.resume.identity, agentId: options.resume.agentId,
+		}).catch(() => undefined) : undefined; // Unreadable resume storage falls back; fresh-store failures still propagate.
+		let resumeAttemptAllowed = resumeIdentity !== undefined;
+		let resumeFallback = options.resume !== undefined && !resumeIdentity;
+		const selectedIdentity = resumeIdentity ?? identities.sessionStore;
+		let sessionStore: OpenCursorSessionStore;
+		try {
+			sessionStore = await openCursorSessionStore(options.cwd, selectedIdentity, identities.workspaceRoot, identities.storeRoot);
+		} catch (error) {
+			if (!resumeIdentity || cursorSessionStoreIdentitiesEqual(resumeIdentity, identities.sessionStore)) throw error;
+			resumeAttemptAllowed = false;
+			resumeFallback = true;
+			sessionStore = await openCursorSessionStore(options.cwd, identities.sessionStore, identities.workspaceRoot, identities.storeRoot);
+		}
+		return { persistent: true, sessionStore, identities, resumeAttemptAllowed, resumeFallback };
+	});
 }
 
 export const __testUtils = {

package/src/cursor-skill-tool.ts

@@ -29,15 +29,13 @@ type CursorActivateSkillParams = {
 };
 
 interface CursorSkillActivationDetails {
-	name?: string;
-	filePath?: string;
-	baseDir?: string;
+	name: string;
+	filePath: string;
+	baseDir: string;
 	resources: string[];
 	availableSkillNames: string[];
 }
 
-let currentSkillsByName = new Map<string, Skill>();
-
 function escapeXml(value: string): string {
 	return value
 		.replace(/&/g, "&amp;")
@@ -51,14 +49,6 @@ function getVisibleSkills(skills: readonly Skill[] | undefined): Skill[] {
 	return (skills ?? []).filter((skill) => !skill.disableModelInvocation);
 }
 
-function setCurrentSkills(skills: readonly Skill[] | undefined): void {
-	currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
-}
-
-function getAvailableSkillNames(): string[] {
-	return [...currentSkillsByName.keys()].sort();
-}
-
 function resolveEffectiveRuntimeForSkillLifecycle(
 	cursorModel: boolean,
 	ctx: Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "isProjectTrusted">>,
@@ -66,27 +56,6 @@ function resolveEffectiveRuntimeForSkillLifecycle(
 	return cursorModel ? resolveEffectiveCursorConfigForContext(ctx).runtime.value : "local";
 }
 
-function shouldExposeSkillTool(model: ExtensionContext["model"], runtime: CursorRuntime): boolean {
-	return runtime === "local" && isCursorModel(model) && resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
-}
-
-function syncCursorSkillToolForModel(
-	pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">,
-	model: ExtensionContext["model"],
-	runtime: CursorRuntime,
-): void {
-	const activeToolNames = new Set(pi.getActiveTools());
-	const shouldBeActive = !arePiToolsDisabled(pi) && shouldExposeSkillTool(model, runtime);
-	const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	if (shouldBeActive === alreadyActive) return;
-	if (shouldBeActive) {
-		activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	} else {
-		activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
-	}
-	pi.setActiveTools([...activeToolNames]);
-}
-
 export function formatCursorSkillsForPrompt(skills: readonly Skill[]): string {
 	const visibleSkills = getVisibleSkills(skills);
 	if (visibleSkills.length === 0) return "";
@@ -157,16 +126,6 @@ async function listSkillResourcePaths(baseDir: string): Promise<string[]> {
 	return resources;
 }
 
-function buildActivationDetails(skill: Skill | undefined, resources: string[] = []): CursorSkillActivationDetails {
-	return {
-		name: skill?.name,
-		filePath: skill?.filePath,
-		baseDir: skill ? dirname(skill.filePath) : undefined,
-		resources,
-		availableSkillNames: getAvailableSkillNames(),
-	};
-}
-
 function formatSkillResources(resources: readonly string[]): string {
 	if (resources.length === 0) return "<skill_resources />";
 	return [
@@ -190,18 +149,37 @@ function wrapSkillContent(skill: Skill, content: string, resources: readonly str
 }
 
 export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
+	let currentSkillsByName = new Map<string, Skill>();
+
+	function setCurrentSkills(skills: readonly Skill[] | undefined): void {
+		currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
+	}
+
+	function getAvailableSkillNames(): string[] {
+		return [...currentSkillsByName.keys()].sort();
+	}
+
+	function syncCursorSkillToolForModel(model: ExtensionContext["model"], runtime: CursorRuntime): void {
+		const activeToolNames = new Set(pi.getActiveTools());
+		const shouldBeActive = !arePiToolsDisabled(pi) && runtime === "local" && isCursorModel(model)
+			&& resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
+		const alreadyActive = activeToolNames.has(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		if (shouldBeActive === alreadyActive) return;
+		if (shouldBeActive) {
+			activeToolNames.add(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		} else {
+			activeToolNames.delete(CURSOR_ACTIVATE_SKILL_TOOL_NAME);
+		}
+		pi.setActiveTools([...activeToolNames]);
+	}
+
 	pi.registerTool({
 		name: CURSOR_ACTIVATE_SKILL_TOOL_NAME,
 		label: "Cursor skill",
 		description: "Load full pi Agent Skill instructions for Cursor. Use with a skill name from the current <available_skills> catalog before applying that skill.",
-		promptSnippet: "Load full pi Agent Skill instructions for a listed skill before Cursor applies that skill",
 		parameters: Type.Object({
 			name: Type.String({ description: "Skill name from the current <available_skills> catalog" }),
 		}),
-		promptGuidelines: [
-			`Use ${CURSOR_ACTIVATE_SKILL_TOOL_NAME} only for skill names listed in the current <available_skills> catalog.`,
-			"After loading a skill, follow its instructions and resolve relative skill paths against the returned skill directory.",
-		],
 		async execute(_toolCallId, params) {
 			const requestedName = (params as CursorActivateSkillParams).name?.trim();
 			if (!requestedName) {
@@ -221,7 +199,13 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 				]);
 				return {
 					content: [{ type: "text" as const, text: wrapSkillContent(skill, content, resources) }],
-					details: buildActivationDetails(skill, resources),
+					details: {
+						name: skill.name,
+						filePath: skill.filePath,
+						baseDir: dirname(skill.filePath),
+						resources,
+						availableSkillNames: getAvailableSkillNames(),
+					} satisfies CursorSkillActivationDetails,
 				};
 			} catch (error) {
 				throw new Error(
@@ -233,7 +217,7 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 
 	const clearSkillsAndSync = (model: ExtensionContext["model"], runtime: CursorRuntime = "local"): void => {
 		setCurrentSkills([]);
-		syncCursorSkillToolForModel(pi, model, runtime);
+		syncCursorSkillToolForModel(model, runtime);
 	};
 
 	registerCursorModelLifecycle(pi, {
@@ -247,7 +231,7 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 			const cursorModel = isCursorModel(ctx.model);
 			const runtime = resolveEffectiveRuntimeForSkillLifecycle(cursorModel, ctx);
 			if (!cursorModel || runtime === "cloud") setCurrentSkills([]);
-			syncCursorSkillToolForModel(pi, ctx.model, runtime);
+			syncCursorSkillToolForModel(ctx.model, runtime);
 		},
 		beforeAgentStart: (event, ctx) => {
 			const cursorModel = isCursorModel(ctx.model);
@@ -257,18 +241,10 @@ export function registerCursorSkillTool(pi: CursorSkillToolExtensionApi): void {
 			} else {
 				setCurrentSkills([]);
 			}
-			syncCursorSkillToolForModel(pi, ctx.model, runtime);
+			syncCursorSkillToolForModel(ctx.model, runtime);
 			const resolved = resolveCursorSkillSystemPrompt(event.systemPrompt, ctx.model, event.systemPromptOptions, runtime);
 			if (resolved === event.systemPrompt) return undefined;
 			return { systemPrompt: resolved };
 		},
 	});
 }
-
-export const __testUtils = {
-	AVAILABLE_SKILLS_SECTION_PATTERN,
-	buildActivationDetails,
-	setCurrentSkills,
-	listSkillResourcePaths,
-	wrapSkillContent,
-};