pi-cursor-sdk 0.5.0 → 0.5.3

package/dist/context.js

@@ -25,12 +25,13 @@ export function getCursorToolTailGuardText(options = {}) {
             : getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance: options.includePiBridgeGuidance }),
         "Exact-output requests: output exactly the requested text; no preamble or checks unless asked.",
         "Tools: call available Cursor SDK/MCP tools; never print tool cards as assistant text.",
+        "Do not comment on GitHub issues or PRs unless the user asked.",
         options.includePiBridgeGuidance === false ? undefined : CURSOR_PI_BRIDGE_PREFERENCE_TEXT,
     ].filter((line) => line !== undefined).join("\n");
 }
 function getCursorToolBoundaryText(options = {}) {
     const includePiBridgeGuidance = options.includePiBridgeGuidance !== false;
-    const includePiAskQuestionGuidance = includePiBridgeGuidance && options.includePiAskQuestionGuidance !== false;
+    const includePiAskQuestionGuidance = includePiBridgeGuidance && options.includePiAskQuestionGuidance === true;
     const lines = [
         "Cursor SDK tool boundary:",
         "Call only Cursor SDK/MCP tools exposed in this run; pi history names, replay labels, and transcript names are not callable.",
@@ -38,7 +39,7 @@ function getCursorToolBoundaryText(options = {}) {
             ? "For exposed pi bridge tools, call pi__* MCP names, not pi card/history names."
             : undefined,
         "Do not claim pi-side or WebSearch/WebFetch tools unless Cursor ran an equivalent tool.",
-        includePiAskQuestionGuidance ? "Use pi__cursor_ask_question for material choices if exposed." : undefined,
+        includePiAskQuestionGuidance ? "Use pi__cursor_ask_question only if the user asked to be prompted." : undefined,
         getCursorPlanModeToolGuidanceText(options.agentMode, { includePiBridgeGuidance }),
         "Images: only latest user images are sent; ask to reattach prior images.",
     ].filter((line) => line !== undefined);
@@ -47,9 +48,11 @@ function getCursorToolBoundaryText(options = {}) {
     }
     return lines.join("\n");
 }
-function getCursorBootstrapTailSections(options = {}) {
+function getCursorBootstrapTailSections(options, hasNewNativeUser = true) {
     return [
-        "Answer the latest user request above using the instructions and Cursor SDK capabilities available in this run.",
+        hasNewNativeUser
+            ? "Answer the latest user request above using the instructions and Cursor SDK capabilities available in this run."
+            : "Continue from the pending background context above using Cursor SDK capabilities. No new user request was submitted; earlier user requests are history, not new instructions.",
         getCursorToolTailGuardText({ ...options, includePlanModeGuidance: false }),
     ];
 }
@@ -65,23 +68,11 @@ function isImageBlock(block) {
 function isToolCallBlock(block) {
     return block.type === "toolCall";
 }
-function extractLatestImages(messages) {
-    // Find the last user message and extract images only from it
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const msg = messages[i];
-        if (msg.role !== "user")
-            continue;
-        if (typeof msg.content === "string")
-            return [];
-        const images = [];
-        for (const block of msg.content) {
-            if (isImageBlock(block) && block.data && block.mimeType) {
-                images.push({ data: block.data, mimeType: block.mimeType });
-            }
-        }
-        return images;
-    }
-    return [];
+function extractLatestImages(messages, latestUserIndex = getLatestUserMessageIndex(messages)) {
+    const message = messages[latestUserIndex];
+    if (!message || message.role !== "user" || typeof message.content === "string")
+        return [];
+    return message.content.flatMap((block) => isImageBlock(block) && block.data && block.mimeType ? [{ data: block.data, mimeType: block.mimeType }] : []);
 }
 function formatContentBlocks(content) {
     if (typeof content === "string")
@@ -99,7 +90,7 @@ function formatContentBlocks(content) {
 }
 function formatToolCall(toolCall) {
     const args = JSON.stringify(toolCall.arguments) ?? "";
-    return `Tool call (${getCursorReplayPromptLabel(toolCall.name)}, call ${toolCall.id}): ${args}`;
+    return `Historical tool request (${getCursorReplayPromptLabel(toolCall.name)}, call ${toolCall.id}): ${args}`;
 }
 function sanitizeSystemPromptForCursor(systemPrompt) {
     let sanitized = systemPrompt;
@@ -135,7 +126,7 @@ function formatMessage(msg) {
         }
         case "toolResult": {
             const text = formatContentBlocks(msg.content);
-            const label = msg.isError ? "Tool error" : "Tool result";
+            const label = msg.isError ? "Historical tool error" : "Historical tool result";
             return `${label} (${getCursorReplayPromptLabel(msg.toolName)}, call ${msg.toolCallId}): ${text}`;
         }
     }
@@ -147,17 +138,29 @@ function getLatestUserMessageIndex(messages) {
     }
     return -1;
 }
+export function getCursorPendingInput(messages, nativeSourceRoles) {
+    const start = messages.findLastIndex((message) => message.role === "assistant") + 1;
+    const latestUserIndex = nativeSourceRoles.findLastIndex((role, index) => index >= start && role === "user");
+    return { start, latestUserIndex };
+}
+function formatPromptMessage(message, index, nativeSourceRoles) {
+    if (message.role === "user" && nativeSourceRoles && nativeSourceRoles[index] !== "user") {
+        const text = formatContentBlocks(message.content);
+        return text ? `Background context: ${text}` : undefined;
+    }
+    return formatMessage(message);
+}
 function getSectionCost(section) {
     return section.length + SECTION_SEPARATOR.length;
 }
-function applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, latestUserMessageIndex, options) {
+function applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, requiredMessageIndexes, options) {
     const maxInputTokens = options.maxInputTokens;
     if (maxInputTokens === undefined || !Number.isFinite(maxInputTokens) || maxInputTokens <= 0) {
         return [...sectionsBeforeMessages, ...messageSections.map((section) => section.text), ...sectionsAfterMessages];
     }
     const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
     const maxChars = Math.max(1, Math.floor(maxInputTokens * charsPerToken));
-    const requiredMessageSections = messageSections.filter((section) => section.index === latestUserMessageIndex);
+    const requiredMessageSections = messageSections.filter((section) => requiredMessageIndexes.includes(section.index));
     const requiredCost = [...sectionsBeforeMessages, ...requiredMessageSections.map((section) => section.text), ...sectionsAfterMessages].reduce((total, section) => total + getSectionCost(section), 0);
     let remainingChars = maxChars - requiredCost;
     const includedMessageIndexes = new Set(requiredMessageSections.map((section) => section.index));
@@ -272,7 +275,7 @@ export function computeCursorContextFingerprint(context) {
     };
     return JSON.stringify(payload);
 }
-export function shouldBootstrapCursorContext(sendState, context) {
+export function shouldBootstrapCursorContext(sendState, context, nativeSourceRoles) {
     if (!sendState.bootstrapped)
         return true;
     const previous = parseCursorContextFingerprint(sendState.contextFingerprint);
@@ -296,9 +299,17 @@ export function shouldBootstrapCursorContext(sendState, context) {
         if (current.messageHashes[index] !== previous.messageHashes[index])
             return true;
     }
-    // An incremental prompt carries only the latest new user message. Rebootstrap
-    // if additional model-visible input (such as ! shell output) would be lost.
     const appended = normalizePiContextMessages(context.messages.slice(previous.messageHashes.length));
+    if (nativeSourceRoles) {
+        const messages = normalizePiContextMessages(context.messages);
+        const offset = messages.length - appended.length;
+        // Native summaries invalidate the pool; other pending input travels together.
+        if (nativeSourceRoles.slice(offset).some((role) => role === "branchSummary" || role === "compactionSummary"))
+            return true;
+        const { start } = getCursorPendingInput(messages, nativeSourceRoles);
+        return appended.some((message, index) => message.role === "user" && offset + index < start);
+    }
+    // Without native origin, an incremental prompt carries only the final user.
     const appendedUsers = appended.filter((message) => message.role === "user");
     return appended.length > 0 && (appendedUsers.length !== 1 || appended.at(-1)?.role !== "user");
 }
@@ -309,19 +320,25 @@ export function shouldBootstrapCursorSend(sendState, context) {
 export function buildCursorIncrementalPrompt(context, options = {}) {
     // Incremental sends omit Pi system instructions and the full tool boundary; the session agent retains both from bootstrap.
     const messages = normalizePiContextMessages(context.messages);
-    const latestUserMessageIndex = getLatestUserMessageIndex(messages);
+    const pending = options.nativeSourceRoles && getCursorPendingInput(messages, options.nativeSourceRoles);
+    const latestUserMessageIndex = pending ? pending.latestUserIndex : getLatestUserMessageIndex(messages);
     const latestUserMessage = latestUserMessageIndex >= 0 ? messages[latestUserMessageIndex] : undefined;
     const latestUserText = latestUserMessage ? formatMessage(latestUserMessage) : undefined;
     const sectionsBeforeMessages = [
         "Continue the conversation using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from earlier context as if they were available.",
     ];
-    const latestUserMessageSections = latestUserText && latestUserMessageIndex >= 0 ? [{ index: latestUserMessageIndex, text: latestUserText }] : [];
-    const images = extractLatestImages(messages);
+    const latestUserMessageSections = pending
+        ? messages.flatMap((message, index) => {
+            const text = index >= pending.start ? formatPromptMessage(message, index, options.nativeSourceRoles) : undefined;
+            return text ? [{ index, text }] : [];
+        })
+        : latestUserText && latestUserMessageIndex >= 0 ? [{ index: latestUserMessageIndex, text: latestUserText }] : [];
+    const images = extractLatestImages(messages, latestUserMessageIndex);
     const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
     const budgetOptions = options.maxInputTokens === undefined
         ? options
         : { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
-    const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [getCursorToolTailGuardText(options)], latestUserMessageIndex, budgetOptions);
+    const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [getCursorToolTailGuardText(options)], latestUserMessageSections.map((section) => section.index), budgetOptions);
     return { text: parts.join(SECTION_SEPARATOR), images };
 }
 /** Native compaction/tree instructions are already a complete summarization request. */
@@ -349,17 +366,19 @@ export function buildCursorPrompt(context, options = {}) {
     const messages = normalizePiContextMessages(context.messages);
     const messageSections = messages
         .map((msg, index) => {
-        const text = formatMessage(msg);
+        const text = formatPromptMessage(msg, index, options.nativeSourceRoles);
         return text ? { index, text } : undefined;
     })
         .filter((section) => section !== undefined);
-    const sectionsAfterMessages = getCursorBootstrapTailSections(options);
-    const images = extractLatestImages(messages);
+    const pending = options.nativeSourceRoles && getCursorPendingInput(messages, options.nativeSourceRoles);
+    const sectionsAfterMessages = getCursorBootstrapTailSections(options, !pending || pending.latestUserIndex >= 0);
+    const images = extractLatestImages(messages, pending ? pending.latestUserIndex : getLatestUserMessageIndex(messages));
     const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
     const budgetOptions = options.maxInputTokens === undefined
         ? options
         : { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
-    const parts = applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, getLatestUserMessageIndex(messages), budgetOptions);
+    const parts = applyPromptBudget(sectionsBeforeMessages, messageSections, sectionsAfterMessages, pending ? messageSections.filter((section) => section.index >= pending.start).map((section) => section.index)
+        : [getLatestUserMessageIndex(messages)], budgetOptions);
     const text = parts.join(SECTION_SEPARATOR);
     return { text, images };
 }

package/dist/cursor-api-key.js

@@ -1,10 +1,7 @@
-import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { envApiKeyAuth } from "@earendil-works/pi-ai";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
 export const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
-const CURSOR_PROVIDER_ID = "cursor";
-// Non-secret literal sentinel for pi's provider registry. Pi 0.77 treats `$ENV_VAR`
-// values as unconfigured when the env var is absent, which hides fallback models
-// before `/login`. Keep the provider available and resolve the real key in the
-// Cursor provider turn path from pi auth or CURSOR_API_KEY.
+// Legacy no-auth availability policy only; never a configured models.json key.
 export const CURSOR_API_KEY_CONFIG_VALUE = "pi-cursor-sdk-cursor-api-key-placeholder";
 const CURSOR_API_KEY_PLACEHOLDERS = new Set([
     CURSOR_API_KEY_ENV_VAR,
@@ -13,22 +10,40 @@ const CURSOR_API_KEY_PLACEHOLDERS = new Set([
     CURSOR_API_KEY_CONFIG_VALUE,
 ]);
 export function resolveCursorApiKey(apiKey) {
+    return normalizeCursorApiKey(apiKey) ?? (apiKey && CURSOR_API_KEY_PLACEHOLDERS.has(apiKey.trim())
+        ? normalizeCursorApiKey(process.env.CURSOR_API_KEY) : undefined);
+}
+export function normalizeCursorApiKey(apiKey) {
     const trimmed = apiKey?.trim();
-    if (!trimmed)
+    if (!trimmed || CURSOR_API_KEY_PLACEHOLDERS.has(trimmed))
         return undefined;
-    if (CURSOR_API_KEY_PLACEHOLDERS.has(trimmed))
-        return process.env.CURSOR_API_KEY?.trim() || undefined;
     return trimmed;
 }
-function getStoredCursorApiKey() {
-    try {
-        const credential = readStoredCredential(CURSOR_PROVIDER_ID);
-        return resolveCursorApiKey(credential?.type === "api_key" ? credential.key : undefined);
-    }
-    catch {
-        return undefined;
-    }
+export async function resolveCursorCredentialApiKey(credential, environment) {
+    return normalizeCursorApiKey(credential?.key)
+        ?? normalizeCursorApiKey(credential?.env?.CURSOR_API_KEY)
+        ?? normalizeCursorApiKey(await environment());
 }
-export function resolveCursorRuntimeApiKey() {
-    return Promise.resolve(getStoredCursorApiKey() ?? resolveCursorApiKey(process.env.CURSOR_API_KEY));
+export function cursorApiKeyAuth() {
+    const standard = envApiKeyAuth("Cursor API key", [CURSOR_API_KEY_ENV_VAR]);
+    const auth = {
+        name: standard.name,
+        login: standard.login,
+        async check(input) {
+            const resolved = await auth.resolve(input);
+            return resolved ? { type: "api_key", source: resolved.source } : undefined;
+        },
+        async resolve({ ctx, credential, signal }) {
+            signal.throwIfAborted();
+            const key = await resolveCursorCredentialApiKey(credential, () => ctx.env(CURSOR_API_KEY_ENV_VAR));
+            signal.throwIfAborted();
+            if (key)
+                return { auth: { apiKey: key }, env: credential?.env, source: credential ? "stored credential" : CURSOR_API_KEY_ENV_VAR };
+            if (!parseEnvBoolean(process.env.PI_CURSOR_HIDE_MODELS_WHEN_LOGGED_OUT, false)) {
+                return { auth: { apiKey: CURSOR_API_KEY_CONFIG_VALUE }, source: "fallback" };
+            }
+            return undefined;
+        },
+    };
+    return auth;
 }

package/dist/cursor-cloud-options.js

@@ -59,6 +59,7 @@ export function buildCursorCloudAgentOptions(options) {
         model: options.modelSelection,
         mode: options.agentMode,
         ...(options.name ? { name: options.name } : {}),
+        ...(options.agents && Object.keys(options.agents).length ? { agents: options.agents } : {}),
         cloud,
     };
 }

package/dist/cursor-config.js

@@ -23,6 +23,7 @@ export const CURSOR_SANDBOX_ENV = "PI_CURSOR_SANDBOX";
 export const CURSOR_LOCAL_FORCE_ENV = "PI_CURSOR_LOCAL_FORCE";
 export const CURSOR_LOCAL_RESUME_ENV = "PI_CURSOR_LOCAL_RESUME";
 export const CURSOR_HTTP1_ENV = "PI_CURSOR_HTTP_1_1";
+export const CURSOR_STATE_ROOT_ENV = "PI_CURSOR_SDK_STATE_ROOT";
 const TRUST_LEVELS = {
     cli: "one-shot",
     environment: "environment",
@@ -107,6 +108,44 @@ function parseCloudEnvironment(value) {
         parsed.name = name;
     return Object.keys(parsed).length > 0 ? parsed : undefined;
 }
+const THINKING_LEVELS = {
+    off: true,
+    minimal: true,
+    low: true,
+    medium: true,
+    high: true,
+    xhigh: true,
+    max: true,
+};
+function isCursorSubagentThinkingLevel(value) {
+    return typeof value === "string" && Object.hasOwn(THINKING_LEVELS, value);
+}
+function parseCustomSubagents(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    const entries = [];
+    for (const [name, raw] of Object.entries(record)) {
+        // Extension config policy, not an upstream SDK naming restriction.
+        if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(name))
+            continue;
+        const entry = asRecord(raw);
+        const description = parseNonEmptyString(entry?.description);
+        const prompt = parseNonEmptyString(entry?.prompt);
+        if (!entry || !description || !prompt)
+            continue;
+        const model = parseNonEmptyString(entry.model);
+        const thinking = entry.thinking;
+        entries.push([name, {
+                description,
+                prompt,
+                ...(model ? { model } : {}),
+                ...(isCursorSubagentThinkingLevel(thinking) ? { thinking } : {}),
+                ...(typeof entry.fast === "boolean" ? { fast: entry.fast } : {}),
+            }]);
+    }
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
 export function parseCursorSdkConfig(value) {
     const record = asRecord(value);
     if (!record)
@@ -114,6 +153,9 @@ export function parseCursorSdkConfig(value) {
     const config = {};
     if (isCursorRuntime(record.runtime))
         config.runtime = record.runtime;
+    const subagents = parseCustomSubagents(record.subagents);
+    if (subagents)
+        config.subagents = subagents;
     const fastDefaults = asRecord(record.fastDefaults);
     if (fastDefaults) {
         config.fastDefaults = Object.fromEntries(Object.entries(fastDefaults).filter((entry) => typeof entry[1] === "boolean"));
@@ -153,6 +195,8 @@ export function parseCursorSdkConfig(value) {
     const local = asRecord(record.local);
     if (local) {
         const parsedLocal = {};
+        if (typeof local.storeRoot === "string" && local.storeRoot.trim())
+            parsedLocal.storeRoot = local.storeRoot;
         if (typeof local.autoReview === "boolean")
             parsedLocal.autoReview = local.autoReview;
         if (typeof local.sandbox === "boolean")
@@ -389,6 +433,8 @@ const CLOUD_ORDER = ["cli", "environment", "session", "user", "builtin"];
 const LOCAL_ORDER = ["cli", "environment", "project", "user", "builtin"];
 const LOCAL_FORCE_ORDER = ["cli", "environment", "builtin"];
 const HTTP1_ORDER = ["session", "environment", "user", "builtin"];
+const SUBAGENTS_ORDER = ["project", "user", "builtin"];
+const STORE_ROOT_ORDER = ["environment", "user", "builtin"];
 function buildFieldLayers(order, values) {
     return order.map((source) => (source === "builtin" ? resolved("builtin", values.builtin) : valueFrom(source, values[source])));
 }
@@ -401,6 +447,13 @@ function resolveSafetyField(order, values, risk) {
 function resolveEnvNamesSafetyField(order, values) {
     return resolveWithCap(buildFieldLayers(order, values), valueFrom("user", values.user), envNamesCap);
 }
+export function resolveCursorLocalStoreRoot({ env = process.env, user } = {}) {
+    return resolveOrdinaryField(STORE_ROOT_ORDER, {
+        environment: env[CURSOR_STATE_ROOT_ENV]?.trim() ? env[CURSOR_STATE_ROOT_ENV] : undefined,
+        user: user?.local?.storeRoot?.trim() ? user.local.storeRoot : undefined,
+        builtin: undefined,
+    });
+}
 export function cursorSdkConfigFromEnv(env = process.env) {
     const config = {};
     const runtime = validateExplicitValue(env[CURSOR_RUNTIME_ENV], CURSOR_RUNTIME_ENV, isCursorRuntime, '"local" or "cloud"');
@@ -483,6 +536,11 @@ export function resolveCursorSdkConfig(options = {}) {
             user: user?.runtime,
             builtin: builtIn.runtime,
         }, (value) => (value === "cloud" ? 1 : 0)),
+        subagents: resolveOrdinaryField(SUBAGENTS_ORDER, {
+            project: parseCustomSubagents(project?.subagents),
+            user: parseCustomSubagents(user?.subagents),
+            builtin: undefined,
+        }),
         cloud: {
             repo: resolveOrdinaryField(CLOUD_ORDER, {
                 cli: cli?.cloud?.repo,
@@ -563,6 +621,7 @@ export function resolveCursorSdkConfig(options = {}) {
             }),
         },
         local: {
+            storeRoot: resolveCursorLocalStoreRoot({ env: options.env, user }),
             autoReview: resolveOrdinaryField(LOCAL_ORDER, {
                 cli: cli?.local?.autoReview,
                 environment: env.local?.autoReview,

package/dist/cursor-custom-store-path.js

@@ -0,0 +1,177 @@
+import { accessSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, realpathSync, } from "node:fs";
+import { isAbsolute, join, parse, resolve, sep } from "node:path";
+import { noFollowFlag, openExistingRegularFileNoFollow, sameFileIdentity } from "./cursor-durable-fs.js";
+/** Lexical only: capture selection before acquisition awaits; fileless callers skip it. */
+export function normalizeCursorCustomStoreRoot(value) {
+    const root = parse(value).root;
+    const components = value.slice(root.length).split(process.platform === "win32" ? /[\\/]/ : sep);
+    if (!isAbsolute(value) || !root || value.includes("\0") || components.some(part => part === "." || part === "..") ||
+        (process.platform === "win32" && (!/^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/][^\\/]+[\\/]?)$/.test(root) ||
+            /^[\\/]{2}[?.][\\/]/.test(value)))) {
+        throw new Error("Cursor local storeRoot must be a native fully qualified absolute path without dot components or device prefixes");
+    }
+    const normalized = resolve(value);
+    if (normalized === resolve(root))
+        throw new Error("Cursor local storeRoot must not be a filesystem or share root");
+    return normalized;
+}
+function invalid(path, reason) {
+    throw new Error(`Cursor custom local store path ${reason}: ${path}`);
+}
+function statIfPresent(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function assertDirectory(path, stat, privateDirectory, afterShared) {
+    if (!stat.isDirectory())
+        invalid(path, "contains a link or non-directory");
+    if (process.platform === "win32")
+        return;
+    const uid = process.getuid();
+    if (privateDirectory || afterShared) {
+        if (stat.uid !== uid)
+            invalid(path, "is not owned by the current user");
+    }
+    else if (stat.uid !== 0 && stat.uid !== uid)
+        invalid(path, "has an untrusted owner");
+    const trustedShared = !privateDirectory && !afterShared && stat.uid === 0 && (stat.mode & 0o1000) !== 0;
+    if ((stat.mode & 0o022) !== 0 && !trustedShared)
+        invalid(path, "is group or other writable");
+    if (privateDirectory && (stat.mode & 0o300) !== 0o300)
+        invalid(path, "is not owner writable/searchable");
+}
+function restrictPrivateDirectory(path, before) {
+    if (process.platform !== "win32") {
+        const fd = openSync(path, constants.O_RDONLY | noFollowFlag());
+        try {
+            const opened = fstatSync(fd);
+            if (!opened.isDirectory() || !sameFileIdentity(before, opened) || !sameFileIdentity(opened, lstatSync(path))) {
+                invalid(path, "changed while opening");
+            }
+            fchmodSync(fd, 0o700);
+            const after = lstatSync(path);
+            if (!after.isDirectory() || !sameFileIdentity(opened, after))
+                invalid(path, "changed while restricting permissions");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    accessSync(path, constants.W_OK | constants.X_OK);
+}
+function assertTrustedSystemTarget(target) {
+    let path = parse(target).root;
+    for (const part of ["", ...target.slice(path.length).split(sep).filter(Boolean)]) {
+        path = join(path, part);
+        const stat = lstatSync(path);
+        if (!stat.isDirectory() || stat.uid !== 0 || ((stat.mode & 0o022) !== 0 && !(stat.mode & 0o1000))) {
+            invalid(path, "has an untrusted system-link target");
+        }
+    }
+}
+/** Verify ancestors before individually creating components; never realpath an arbitrary user tree. */
+export function prepareCursorCustomStoreRoot(selectedRoot) {
+    const normalized = normalizeCursorCustomStoreRoot(selectedRoot);
+    let path = parse(normalized).root;
+    let afterShared = false;
+    const components = normalized.slice(path.length).split(sep).filter(Boolean);
+    assertDirectory(path, lstatSync(path), false, false);
+    for (const [index, part] of components.entries()) {
+        path = join(path, part);
+        const leaf = index === components.length - 1;
+        let stat = statIfPresent(path);
+        if (stat?.isSymbolicLink()) {
+            if (process.platform === "win32" || leaf || afterShared || stat.uid !== 0)
+                invalid(path, "contains a link or non-directory");
+            const target = realpathSync(path);
+            assertTrustedSystemTarget(target);
+            path = target;
+            stat = lstatSync(path);
+        }
+        if (!stat) {
+            try {
+                mkdirSync(path, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+            stat = lstatSync(path);
+        }
+        assertDirectory(path, stat, leaf, afterShared);
+        if (leaf)
+            restrictPrivateDirectory(path, stat);
+        if (process.platform !== "win32" && stat.uid === 0 && (stat.mode & 0o022) !== 0)
+            afterShared = true;
+    }
+    return path;
+}
+/** Called after exact admission and again immediately before/after the public pathname-based SDK open. */
+export function guardCursorCustomStorePath(customRoot, stateRoot) {
+    if (prepareCursorCustomStoreRoot(customRoot) !== customRoot)
+        invalid(customRoot, "changed canonical identity");
+    const directories = [{ path: customRoot, stat: lstatSync(customRoot) }];
+    let path = customRoot;
+    for (const part of stateRoot.slice(customRoot.length + 1).split(sep)) {
+        path = join(path, part);
+        if (!statIfPresent(path)) {
+            try {
+                mkdirSync(path, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        const stat = lstatSync(path);
+        assertDirectory(path, stat, true, true);
+        restrictPrivateDirectory(path, stat);
+        directories.push({ path, stat });
+    }
+    const leaves = ["index.db", "index.db-wal", "index.db-shm", "index.db-journal"];
+    const originalLeaves = new Map();
+    const checkLeaves = () => {
+        for (const name of leaves) {
+            const file = join(stateRoot, name);
+            const stat = statIfPresent(file);
+            if (!stat) {
+                if (name === "index.db" && originalLeaves.has(file))
+                    invalid(file, "disappeared SQLite file");
+                continue;
+            }
+            if (!stat.isFile() || stat.nlink !== 1)
+                invalid(file, "contains a linked or nonregular SQLite file");
+            if (process.platform !== "win32" && (stat.uid !== process.getuid() || (stat.mode & 0o022))) {
+                invalid(file, "contains an unowned or shared SQLite file");
+            }
+            const before = originalLeaves.get(file);
+            if (before && !sameFileIdentity(before, stat))
+                invalid(file, "changed SQLite file identity");
+            const fd = openExistingRegularFileNoFollow(file, constants.O_RDWR);
+            closeSync(fd);
+            originalLeaves.set(file, stat);
+        }
+    };
+    checkLeaves();
+    // ponytail: the public SDK uses pathname/lazy checkpoint opens. This guards
+    // current-user private contents, not hostile same-user/admin races. Windows
+    // rejects Node-visible links/junctions but has no ACL hardening/O_NOFOLLOW
+    // equivalent here; use an ACL-protected root. Upgrade with public native APIs.
+    return { verify() {
+            if (prepareCursorCustomStoreRoot(customRoot) !== customRoot)
+                invalid(customRoot, "changed canonical identity");
+            for (const { path, stat } of directories) {
+                const after = lstatSync(path);
+                assertDirectory(path, after, true, true);
+                if (!sameFileIdentity(stat, after))
+                    invalid(path, "changed directory identity");
+            }
+            checkLeaves();
+        } };
+}

package/dist/cursor-custom-subagent-definitions.js

@@ -0,0 +1,14 @@
+import { buildCursorModelSelection, getCursorModelMetadata } from "./model-discovery.js";
+export function buildCursorCustomSubagentDefinitions(config) {
+    if (!config || !Object.keys(config).length)
+        return undefined;
+    return Object.fromEntries(Object.entries(config).map(([name, entry]) => [name, {
+            description: entry.description,
+            prompt: entry.prompt,
+            ...(entry.model === undefined ? {} : {
+                model: entry.model === "inherit" ? "inherit" : buildCursorModelSelection(entry.model, entry.thinking ?? "off", getCursorModelMetadata(entry.model)?.fastOverride ?? entry.fast),
+            }),
+        }]));
+}
+// ponytail: SDK 1.0.37 LOCAL conversion keeps only model ID/inherit; it drops params.
+// Upgrade this claim only after the installed public converter preserves them.