pi-cursor-sdk 0.5.0 → 0.5.3

package/src/context.ts

@@ -12,6 +12,8 @@ export interface CursorPrompt {
 }
 
 export interface CursorPromptOptions {
+	/** From the consumed native receipt; absent for requests that differ from the canonical projection. */
+	nativeSourceRoles?: readonly string[];
 	maxInputTokens?: number;
 	charsPerToken?: number;
 	imageTokenEstimate?: number;
@@ -50,6 +52,7 @@ export function getCursorToolTailGuardText(
 			: 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 is string => line !== undefined).join("\n");
 }
@@ -58,7 +61,7 @@ function getCursorToolBoundaryText(
 	options: Pick<CursorPromptOptions, "agentMode" | "includePiAskQuestionGuidance"> & { hasToolManifest?: boolean; includePiBridgeGuidance?: boolean } = {},
 ): string {
 	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.",
@@ -66,7 +69,7 @@ function getCursorToolBoundaryText(
 			? "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 is string => line !== undefined);
@@ -77,10 +80,13 @@ function getCursorToolBoundaryText(
 }
 
 function getCursorBootstrapTailSections(
-	options: Pick<CursorPromptOptions, "agentMode" | "includePiBridgeGuidance"> = {},
+	options: Pick<CursorPromptOptions, "agentMode" | "includePiBridgeGuidance">,
+	hasNewNativeUser = true,
 ): string[] {
 	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 }),
 	];
 }
@@ -101,22 +107,11 @@ function isToolCallBlock(block: { type: string }): block is ToolCall {
 	return block.type === "toolCall";
 }
 
-function extractLatestImages(messages: Message[]): SDKImage[] {
-	// 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: SDKImage[] = [];
-		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: Message[], latestUserIndex = getLatestUserMessageIndex(messages)): SDKImage[] {
+	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: string | { type: string; text?: string; data?: string; mimeType?: string }[]): string {
@@ -133,7 +128,7 @@ function formatContentBlocks(content: string | { type: string; text?: string; da
 
 function formatToolCall(toolCall: ToolCall): string {
 	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: string): string {
@@ -182,7 +177,7 @@ function formatMessage(msg: Message): string | undefined {
 		}
 		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}`;
 		}
 	}
@@ -195,6 +190,20 @@ function getLatestUserMessageIndex(messages: Message[]): number {
 	return -1;
 }
 
+export function getCursorPendingInput(messages: Message[], nativeSourceRoles: readonly string[]) {
+	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: Message, index: number, nativeSourceRoles?: readonly string[]): string | undefined {
+	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: string): number {
 	return section.length + SECTION_SEPARATOR.length;
 }
@@ -203,7 +212,7 @@ function applyPromptBudget(
 	sectionsBeforeMessages: string[],
 	messageSections: Array<{ index: number; text: string }>,
 	sectionsAfterMessages: string[],
-	latestUserMessageIndex: number,
+	requiredMessageIndexes: readonly number[],
 	options: CursorPromptOptions,
 ): string[] {
 	const maxInputTokens = options.maxInputTokens;
@@ -213,7 +222,7 @@ function applyPromptBudget(
 
 	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,
@@ -368,6 +377,7 @@ export function computeCursorContextFingerprint(context: Context): string {
 export function shouldBootstrapCursorContext(
 	sendState: { bootstrapped: boolean; contextFingerprint: string },
 	context: Context,
+	nativeSourceRoles?: readonly string[],
 ): boolean {
 	if (!sendState.bootstrapped) return true;
 	const previous = parseCursorContextFingerprint(sendState.contextFingerprint);
@@ -385,9 +395,16 @@ export function shouldBootstrapCursorContext(
 	for (let index = 0; index < previous.messageHashes.length; index += 1) {
 		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");
 }
@@ -403,15 +420,20 @@ export function shouldBootstrapCursorSend(
 export function buildCursorIncrementalPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
 	// 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
@@ -421,7 +443,7 @@ export function buildCursorIncrementalPrompt(context: Context, options: CursorPr
 		sectionsBeforeMessages,
 		latestUserMessageSections,
 		[getCursorToolTailGuardText(options)],
-		latestUserMessageIndex,
+		latestUserMessageSections.map((section) => section.index),
 		budgetOptions,
 	);
 	return { text: parts.join(SECTION_SEPARATOR), images };
@@ -454,12 +476,13 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 	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 is { index: number; text: string } => 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
@@ -469,7 +492,8 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages,
 		messageSections,
 		sectionsAfterMessages,
-		getLatestUserMessageIndex(messages),
+		pending ? messageSections.filter((section) => section.index >= pending.start).map((section) => section.index)
+			: [getLatestUserMessageIndex(messages)],
 		budgetOptions,
 	);
 	const text = parts.join(SECTION_SEPARATOR);

package/src/cursor-api-key.ts

@@ -1,12 +1,9 @@
-import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { envApiKeyAuth, type ApiKeyAuth, type ApiKeyCredential } 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([
@@ -17,21 +14,44 @@ const CURSOR_API_KEY_PLACEHOLDERS = new Set([
 ]);
 
 export function resolveCursorApiKey(apiKey?: string): string | undefined {
+	return normalizeCursorApiKey(apiKey) ?? (apiKey && CURSOR_API_KEY_PLACEHOLDERS.has(apiKey.trim())
+		? normalizeCursorApiKey(process.env.CURSOR_API_KEY) : undefined);
+}
+
+export function normalizeCursorApiKey(apiKey?: string): string | undefined {
 	const trimmed = apiKey?.trim();
-	if (!trimmed) return undefined;
-	if (CURSOR_API_KEY_PLACEHOLDERS.has(trimmed)) return process.env.CURSOR_API_KEY?.trim() || undefined;
+	if (!trimmed || CURSOR_API_KEY_PLACEHOLDERS.has(trimmed)) return undefined;
 	return trimmed;
 }
 
-function getStoredCursorApiKey(): string | undefined {
-	try {
-		const credential = readStoredCredential(CURSOR_PROVIDER_ID);
-		return resolveCursorApiKey(credential?.type === "api_key" ? credential.key : undefined);
-	} catch {
-		return undefined;
-	}
+export async function resolveCursorCredentialApiKey(
+	credential: ApiKeyCredential | undefined,
+	environment: () => Promise<string | undefined>,
+): Promise<string | undefined> {
+	return normalizeCursorApiKey(credential?.key)
+		?? normalizeCursorApiKey(credential?.env?.CURSOR_API_KEY)
+		?? normalizeCursorApiKey(await environment());
 }
 
-export function resolveCursorRuntimeApiKey(): Promise<string | undefined> {
-	return Promise.resolve(getStoredCursorApiKey() ?? resolveCursorApiKey(process.env.CURSOR_API_KEY));
+export function cursorApiKeyAuth(): ApiKeyAuth {
+	const standard = envApiKeyAuth("Cursor API key", [CURSOR_API_KEY_ENV_VAR]);
+	const auth: ApiKeyAuth = {
+		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/src/cursor-cloud-options.ts

@@ -49,6 +49,7 @@ export function buildCursorCloudAgentOptions(options: {
 	agentMode: AgentModeOption;
 	resolvedConfig: CursorResolvedSdkConfig;
 	name?: string;
+	agents?: AgentOptions["agents"];
 }): AgentOptions {
 	const { resolvedConfig } = options;
 	const environment = resolvedConfig.cloud.environment.value;
@@ -91,6 +92,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/src/cursor-config.ts

@@ -13,6 +13,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { parseOptionalEnvBoolean } from "./cursor-env-boolean.js";
 import { asRecord } from "./cursor-record-utils.js";
 
@@ -36,6 +37,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";
 
 export type CursorConfigSource = "cli" | "environment" | "project" | "user" | "session" | "model-alias" | "builtin";
 export type CursorConfigTrustLevel = "one-shot" | "environment" | "trusted-project" | "user" | "session" | "model-catalog" | "builtin";
@@ -48,9 +50,20 @@ export interface CursorCloudEnvironmentConfig {
 	name?: string;
 }
 
+export interface CursorCustomSubagentConfig {
+	description: string;
+	prompt: string;
+	model?: string;
+	thinking?: ModelThinkingLevel;
+	fast?: boolean;
+}
+
+export type CursorCustomSubagentsConfig = Record<string, CursorCustomSubagentConfig>;
+
 export interface CursorSdkConfig {
 	fastDefaults?: Record<string, boolean>;
 	runtime?: CursorRuntime;
+	subagents?: CursorCustomSubagentsConfig;
 	cloud?: {
 		repo?: string;
 		branch?: string;
@@ -73,6 +86,7 @@ export interface CursorSdkConfig {
 		force?: boolean;
 		resume?: boolean;
 		useHttp1ForAgent?: boolean;
+		storeRoot?: string;
 	};
 }
 
@@ -94,6 +108,7 @@ export interface CursorResolvedSetting<T> {
 
 export interface CursorResolvedSdkConfig {
 	runtime: CursorResolvedSetting<CursorRuntime>;
+	subagents: CursorResolvedSetting<CursorCustomSubagentsConfig | undefined>;
 	cloud: {
 		repo: CursorResolvedSetting<string | undefined>;
 		branch: CursorResolvedSetting<string | undefined>;
@@ -113,6 +128,7 @@ export interface CursorResolvedSdkConfig {
 		force: CursorResolvedSetting<boolean>;
 		resume: CursorResolvedSetting<boolean>;
 		useHttp1ForAgent: CursorResolvedSetting<boolean>;
+		storeRoot: CursorResolvedSetting<string | undefined>;
 	};
 }
 
@@ -237,6 +253,44 @@ function parseCloudEnvironment(value: unknown): CursorCloudEnvironmentConfig | u
 	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,
+} satisfies Record<ModelThinkingLevel, true>;
+
+function isCursorSubagentThinkingLevel(value: unknown): value is ModelThinkingLevel {
+	return typeof value === "string" && Object.hasOwn(THINKING_LEVELS, value);
+}
+
+function parseCustomSubagents(value: unknown): CursorCustomSubagentsConfig | undefined {
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const entries: Array<[string, CursorCustomSubagentConfig]> = [];
+	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: unknown): CursorSdkConfig | undefined {
 	const record = asRecord(value);
 	if (!record) return undefined;
@@ -244,6 +298,9 @@ export function parseCursorSdkConfig(value: unknown): CursorSdkConfig | undefine
 
 	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(
@@ -275,6 +332,7 @@ export function parseCursorSdkConfig(value: unknown): CursorSdkConfig | undefine
 	const local = asRecord(record.local);
 	if (local) {
 		const parsedLocal: NonNullable<CursorSdkConfig["local"]> = {};
+		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") parsedLocal.sandbox = local.sandbox;
 		if (typeof local.force === "boolean") parsedLocal.force = local.force;
@@ -533,6 +591,8 @@ const CLOUD_ORDER: CursorFieldSource[] = ["cli", "environment", "session", "user
 const LOCAL_ORDER: CursorFieldSource[] = ["cli", "environment", "project", "user", "builtin"];
 const LOCAL_FORCE_ORDER: CursorFieldSource[] = ["cli", "environment", "builtin"];
 const HTTP1_ORDER: CursorFieldSource[] = ["session", "environment", "user", "builtin"];
+const SUBAGENTS_ORDER: CursorFieldSource[] = ["project", "user", "builtin"];
+const STORE_ROOT_ORDER: CursorFieldSource[] = ["environment", "user", "builtin"];
 
 function buildFieldLayers<T>(order: CursorFieldSource[], values: CursorFieldValues<T>): Array<CursorResolvedSetting<T> | undefined> {
 	return order.map((source) => (source === "builtin" ? resolved("builtin", values.builtin as T) : valueFrom(source, values[source])));
@@ -550,6 +610,16 @@ function resolveEnvNamesSafetyField(order: CursorFieldSource[], values: CursorFi
 	return resolveWithCap(buildFieldLayers(order, values), valueFrom("user", values.user), envNamesCap);
 }
 
+export function resolveCursorLocalStoreRoot(
+	{ env = process.env, user }: Pick<ResolveCursorSdkConfigOptions, "env" | "user"> = {},
+): CursorResolvedSetting<string | undefined> {
+	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: Record<string, string | undefined> = process.env): CursorSdkConfig {
 	const config: CursorSdkConfig = {};
 	const runtime = validateExplicitValue(env[CURSOR_RUNTIME_ENV], CURSOR_RUNTIME_ENV, isCursorRuntime, '"local" or "cloud"');
@@ -648,6 +718,11 @@ export function resolveCursorSdkConfig(options: ResolveCursorSdkConfigOptions =
 			},
 			(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,
@@ -752,6 +827,7 @@ export function resolveCursorSdkConfig(options: ResolveCursorSdkConfigOptions =
 			}),
 		},
 		local: {
+			storeRoot: resolveCursorLocalStoreRoot({ env: options.env, user }),
 			autoReview: resolveOrdinaryField(LOCAL_ORDER, {
 				cli: cli?.local?.autoReview,
 				environment: env.local?.autoReview,

package/src/cursor-custom-store-path.ts

@@ -0,0 +1,151 @@
+import {
+	accessSync, closeSync, constants, fchmodSync, fstatSync, lstatSync, mkdirSync,
+	openSync, realpathSync, type Stats,
+} 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: string): string {
+	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: string, reason: string): never {
+	throw new Error(`Cursor custom local store path ${reason}: ${path}`);
+}
+
+function statIfPresent(path: string): Stats | undefined {
+	try { return lstatSync(path); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+}
+
+function assertDirectory(path: string, stat: Stats, privateDirectory: boolean, afterShared: boolean): void {
+	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: string, before: Stats): void {
+	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: string): void {
+	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: string): string {
+	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 as NodeJS.ErrnoException).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: string, stateRoot: string): { verify(): void } {
+	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 as NodeJS.ErrnoException).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<string, Stats>();
+	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/src/cursor-custom-subagent-definitions.ts

@@ -0,0 +1,21 @@
+import type { AgentOptions } from "@cursor/sdk";
+import type { CursorCustomSubagentsConfig } from "./cursor-config.js";
+import { buildCursorModelSelection, getCursorModelMetadata } from "./model-discovery.js";
+
+export function buildCursorCustomSubagentDefinitions(config: CursorCustomSubagentsConfig | undefined): AgentOptions["agents"] {
+	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.