pi-cursor-sdk 0.4.0 → 0.5.2

package/dist/cursor-session-store.js

@@ -1,9 +1,14 @@
 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 { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { guardCursorCustomStorePath, normalizeCursorCustomStoreRoot, prepareCursorCustomStoreRoot } from "./cursor-custom-store-path.js";
 let sdkOperationsForTests;
+const activeWorkspaceRoots = new Map();
+// 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) {
     return createHash("sha256")
         .update("pi-cursor-sdk-session-store\0")
@@ -11,9 +16,8 @@ export function hashCursorSessionStoreScope(scopeKey) {
         .digest("hex")
         .slice(0, 32);
 }
-export function buildCursorSessionStateRoot(defaultStateRoot, scopeKey, persistent) {
-    const baseRoot = persistent ? defaultStateRoot : join(tmpdir(), `pi-cursor-sdk-${randomUUID()}`);
-    return join(baseRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
+export function buildCursorSessionStateRoot(defaultStateRoot, scopeKey) {
+    return join(defaultStateRoot, "pi-sessions", hashCursorSessionStoreScope(scopeKey));
 }
 async function getSdkOperations() {
     if (sdkOperationsForTests)
@@ -27,76 +31,262 @@ async function getSdkOperations() {
         openSqliteStore: (options) => SqliteLocalAgentStore.open(options),
     };
 }
-export async function getCursorSessionStoreIdentities(cwd, scopeKey, persistent) {
-    const defaultStateRoot = await (await getSdkOperations()).getDefaultStateRoot(cwd);
+function leaseWorkspaceRoot(key, ownership) {
+    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, storeRoot) {
+    return JSON.stringify([cwd, storeRoot ?? null]);
+}
+function acquireWorkspaceRoot(cwd, storeRoot) {
+    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, workspaceRoot, storeRoot) {
+    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(cwd, scopeKey, selectedRoot, use) {
+    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", defaultStore: { version: 1, stateRoot: workspaceRoot } }
+                : { domain: "custom", storeRoot }),
+        });
+    }
+    finally {
+        lease.release();
+    }
+}
 export function cursorSessionStoreIdentitiesEqual(left, right) {
     return left.version === right.version && left.stateRoot === right.stateRoot;
 }
-async function openOwnedCursorSessionStore(cwd, identity, removalRoot) {
+function rejectedStorePath(stateRoot, base) {
+    // 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.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+function assertSafeStorePath(stateRoot, base, label) {
+    const rejected = rejectedStorePath(stateRoot, base);
+    if (rejected)
+        throw new Error(`Cursor ${label} path contains a link or non-directory: ${rejected}`);
+}
+function workspaceHashes(cwd) {
+    const current = createHash("sha256").update(cwd).digest("hex");
+    try {
+        return { current, legacy: createHash("md5").update(cwd).digest("hex") };
+    }
+    catch (error) {
+        if (error.code === "ERR_OSSL_EVP_UNSUPPORTED" ||
+            (error instanceof Error && error.message === "Digest method not supported"))
+            return { current, legacy: undefined };
+        throw error;
+    }
+}
+function assertSafeWorkspaceLayout(cwd) {
+    // 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, defaultStateRoot) {
+    // 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) {
+    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, 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, 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, identity, options) {
     const openedIdentity = Object.freeze({ ...identity });
+    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;
     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();
             }
         },
     };
 }
-export function openCursorSessionStore(cwd, identity) {
-    return openOwnedCursorSessionStore(cwd, identity);
+export function openCursorSessionStore(cwd, identity, workspaceRoot, storeRoot) {
+    return openOwnedCursorSessionStore(cwd, identity, { workspaceRoot, storeRoot });
 }
 export async function openCursorSessionStoreForScope(options) {
-    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;
-    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, 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;
+        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 = {
     setSdkOperations(operations) {

package/dist/cursor-skill-tool.js

@@ -11,7 +11,6 @@ export const CURSOR_ACTIVATE_SKILL_MCP_NAME = "pi__cursor_activate_skill";
 const AVAILABLE_SKILLS_SECTION_PATTERN = /<skills>\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>\n<\/skills>|\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/;
 const MAX_SKILL_RESOURCES = 80;
 const RESOURCE_DIR_NAMES = ["scripts", "references", "assets"];
-let currentSkillsByName = new Map();
 function escapeXml(value) {
     return value
         .replace(/&/g, "&amp;")
@@ -23,32 +22,9 @@ function escapeXml(value) {
 function getVisibleSkills(skills) {
     return (skills ?? []).filter((skill) => !skill.disableModelInvocation);
 }
-function setCurrentSkills(skills) {
-    currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
-}
-function getAvailableSkillNames() {
-    return [...currentSkillsByName.keys()].sort();
-}
 function resolveEffectiveRuntimeForSkillLifecycle(cursorModel, ctx) {
     return cursorModel ? resolveEffectiveCursorConfigForContext(ctx).runtime.value : "local";
 }
-function shouldExposeSkillTool(model, runtime) {
-    return runtime === "local" && isCursorModel(model) && resolveCursorPiToolBridgeEnabled() && currentSkillsByName.size > 0;
-}
-function syncCursorSkillToolForModel(pi, model, runtime) {
-    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) {
     const visibleSkills = getVisibleSkills(skills);
     if (visibleSkills.length === 0)
@@ -119,15 +95,6 @@ async function listSkillResourcePaths(baseDir) {
     }
     return resources;
 }
-function buildActivationDetails(skill, resources = []) {
-    return {
-        name: skill?.name,
-        filePath: skill?.filePath,
-        baseDir: skill ? dirname(skill.filePath) : undefined,
-        resources,
-        availableSkillNames: getAvailableSkillNames(),
-    };
-}
 function formatSkillResources(resources) {
     if (resources.length === 0)
         return "<skill_resources />";
@@ -150,18 +117,35 @@ function wrapSkillContent(skill, content, resources) {
     ].join("\n");
 }
 export function registerCursorSkillTool(pi) {
+    let currentSkillsByName = new Map();
+    function setCurrentSkills(skills) {
+        currentSkillsByName = new Map(getVisibleSkills(skills).map((skill) => [skill.name, skill]));
+    }
+    function getAvailableSkillNames() {
+        return [...currentSkillsByName.keys()].sort();
+    }
+    function syncCursorSkillToolForModel(model, runtime) {
+        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.name?.trim();
             if (!requestedName) {
@@ -178,7 +162,13 @@ export function registerCursorSkillTool(pi) {
                 ]);
                 return {
                     content: [{ type: "text", text: wrapSkillContent(skill, content, resources) }],
-                    details: buildActivationDetails(skill, resources),
+                    details: {
+                        name: skill.name,
+                        filePath: skill.filePath,
+                        baseDir: dirname(skill.filePath),
+                        resources,
+                        availableSkillNames: getAvailableSkillNames(),
+                    },
                 };
             }
             catch (error) {
@@ -188,7 +178,7 @@ export function registerCursorSkillTool(pi) {
     });
     const clearSkillsAndSync = (model, runtime = "local") => {
         setCurrentSkills([]);
-        syncCursorSkillToolForModel(pi, model, runtime);
+        syncCursorSkillToolForModel(model, runtime);
     };
     registerCursorModelLifecycle(pi, {
         sessionStart: (_event, ctx) => {
@@ -202,7 +192,7 @@ export function registerCursorSkillTool(pi) {
             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);
@@ -213,7 +203,7 @@ export function registerCursorSkillTool(pi) {
             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;
@@ -221,10 +211,3 @@ export function registerCursorSkillTool(pi) {
         },
     });
 }
-export const __testUtils = {
-    AVAILABLE_SKILLS_SECTION_PATTERN,
-    buildActivationDetails,
-    setCurrentSkills,
-    listSkillResourcePaths,
-    wrapSkillContent,
-};