pi-cursor-sdk 0.4.0 → 0.5.2

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.36 LOCAL conversion keeps only model ID/inherit; it drops params.
+// Upgrade this claim only after the installed public converter preserves them.

package/src/cursor-durable-fs.ts

@@ -1,6 +1,7 @@
-import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync } from "node:fs";
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 
-function sameFileIdentity(left: { dev: number; ino: number }, right: { dev: number; ino: number }): boolean {
+export function sameFileIdentity(left: { dev: number; ino: number }, right: { dev: number; ino: number }): boolean {
 	return left.dev === right.dev && left.ino === right.ino;
 }
 
@@ -28,7 +29,68 @@ export function openExistingRegularFileNoFollow(path: string, flags: number): nu
 	}
 }
 
-/** Opens a read-write descriptor (required for Windows FlushFileBuffers) so fsync applies to the real file, not a swapped-in symlink target. */
+/** Creates a private regular file without replacing or following an existing path. */
+export function createRegularFileExclusive(path: string, flags: number, mode: number): number {
+	const fd = openSync(path, flags | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), mode);
+	try {
+		const opened = fstatSync(fd);
+		const after = lstatSync(path);
+		if (!opened.isFile() || !after.isFile() || !sameFileIdentity(opened, after)) throw new Error("created file changed while opening");
+		return fd;
+	} catch (error) { closeSync(fd); throw error; }
+}
+
+/** Bounded, fail-closed framed journals; an incomplete last frame is not recognized. */
+export function readDurableFramePrefix(path: string, maxBytes = 16 * 1024 * 1024): { frames: unknown[]; incompleteTail: boolean } {
+	let fd: number;
+	try { fd = openExistingRegularFileNoFollow(path, constants.O_RDONLY); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { frames: [], incompleteTail: false }; throw error; }
+	try {
+		if (fstatSync(fd).size > maxBytes) throw new Error("journal exceeds size limit");
+		const buffer = Buffer.alloc(Math.min(fstatSync(fd).size + 1, maxBytes + 1));
+		let length = 0;
+		while (length < buffer.length) { const count = readSync(fd, buffer, length, buffer.length - length, length); if (!count) break; length += count; }
+		if (length === buffer.length) throw new Error("journal changed or exceeds size limit");
+		const text = buffer.subarray(0, length).toString("utf8");
+		const end = text.lastIndexOf("\n");
+		return {
+			frames: end < 0 ? [] : text.slice(0, end).split("\n").map(line => JSON.parse(line) as unknown),
+			incompleteTail: !!text && !text.endsWith("\n"),
+		};
+	} finally { closeSync(fd); }
+}
+
+export function readDurableFrames(path: string, maxBytes = 16 * 1024 * 1024): unknown[] {
+	const result = readDurableFramePrefix(path, maxBytes);
+	if (result.incompleteTail) throw new Error("incomplete journal frame");
+	return result.frames;
+}
+
+export function appendDurableFrame(path: string, data: unknown, validate?: (frames: unknown[]) => void): void {
+	// Validate framing and the owner's complete candidate history once, before recognition.
+	const frames = readDurableFrames(path);
+	validate?.([...frames, data]);
+	let created = false;
+	let fd: number;
+	try { fd = createRegularFileExclusive(path, constants.O_RDWR | constants.O_APPEND, 0o600); created = true; }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		fd = openExistingRegularFileNoFollow(path, constants.O_RDWR | constants.O_APPEND);
+	}
+	try {
+		if (process.platform !== "win32") fchmodSync(fd, 0o600);
+		const frame = `${JSON.stringify(data)}\n`;
+		if (fstatSync(fd).size + Buffer.byteLength(frame) > 16 * 1024 * 1024) throw new Error("journal exceeds size limit");
+		writeFileSync(fd, frame);
+		fsyncSync(fd);
+		if (created && process.platform !== "win32") {
+			const directoryFd = openSync(dirname(path), constants.O_RDONLY);
+			try { fsyncSync(directoryFd); } finally { closeSync(directoryFd); }
+		}
+	} finally { closeSync(fd); }
+}
+
+/** Opens a read-write descriptor (required for Windows FlushFileBuffers) without following a swapped-in symlink. */
 export function fsyncExistingRegularFile(path: string): boolean {
 	let fd: number | undefined;
 	try {

package/src/cursor-fallback-models.generated.ts

@@ -1,6 +1,6 @@
 import type { ModelListItem } from "@cursor/sdk";
 
-// Generated with @cursor/sdk@1.0.32 from 42 Cursor models.
+// Generated with @cursor/sdk@1.0.36 from 45 Cursor models.
 // Refresh with: npm run refresh:cursor-snapshots -- --write
 // Do not add secrets; this file stores public model metadata only.
 export const FALLBACK_MODEL_ITEMS = [
@@ -5599,6 +5599,185 @@ export const FALLBACK_MODEL_ITEMS = [
 			}
 		]
 	},
+	{
+		id: "claude-sonnet-5-5",
+		displayName: "Claude Sonnet 5.5",
+		parameters: [
+			{
+				id: "context",
+				displayName: "Context",
+				values: [
+					{
+						value: "300k",
+						displayName: "300K"
+					},
+					{
+						value: "1m",
+						displayName: "1M"
+					}
+				]
+			},
+			{
+				id: "reasoning_effort",
+				displayName: "Effort",
+				values: [
+					{
+						value: "low",
+						displayName: "Low"
+					},
+					{
+						value: "medium",
+						displayName: "Medium"
+					},
+					{
+						value: "high",
+						displayName: "High"
+					},
+					{
+						value: "xhigh",
+						displayName: "Extra High"
+					},
+					{
+						value: "max",
+						displayName: "Max"
+					}
+				]
+			}
+		],
+		variants: [
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "low"
+					}
+				],
+				displayName: "Claude Sonnet 5.5  Low"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "medium"
+					}
+				],
+				displayName: "Claude Sonnet 5.5  Medium"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "high"
+					}
+				],
+				displayName: "Claude Sonnet 5.5  High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "xhigh"
+					}
+				],
+				displayName: "Claude Sonnet 5.5  Extra High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "300k"
+					},
+					{
+						id: "reasoning_effort",
+						value: "max"
+					}
+				],
+				displayName: "Claude Sonnet 5.5  Max"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "low"
+					}
+				],
+				displayName: "Claude Sonnet 5.5 1M Low"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "medium"
+					}
+				],
+				displayName: "Claude Sonnet 5.5 1M Medium"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "high"
+					}
+				],
+				displayName: "Claude Sonnet 5.5 1M High",
+				isDefault: true
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "xhigh"
+					}
+				],
+				displayName: "Claude Sonnet 5.5 1M Extra High"
+			},
+			{
+				params: [
+					{
+						id: "context",
+						value: "1m"
+					},
+					{
+						id: "reasoning_effort",
+						value: "max"
+					}
+				],
+				displayName: "Claude Sonnet 5.5 1M Max"
+			}
+		]
+	},
 	{
 		id: "composer-2",
 		displayName: "Composer 2",
@@ -5979,6 +6158,114 @@ export const FALLBACK_MODEL_ITEMS = [
 			}
 		]
 	},
+	{
+		id: "glm-5p3",
+		displayName: "GLM 5.3",
+		parameters: [
+			{
+				id: "reasoning",
+				displayName: "Reasoning",
+				values: [
+					{
+						value: "low",
+						displayName: "Low"
+					},
+					{
+						value: "high",
+						displayName: "High"
+					},
+					{
+						value: "max",
+						displayName: "Max"
+					}
+				]
+			}
+		],
+		variants: [
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "low"
+					}
+				],
+				displayName: "GLM 5.3 Low"
+			},
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "high"
+					}
+				],
+				displayName: "GLM 5.3 High"
+			},
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "max"
+					}
+				],
+				displayName: "GLM 5.3 Max",
+				isDefault: true
+			}
+		]
+	},
+	{
+		id: "glm-5p3-flash",
+		displayName: "GLM 5.3 Flash",
+		parameters: [
+			{
+				id: "reasoning",
+				displayName: "Reasoning",
+				values: [
+					{
+						value: "low",
+						displayName: "Low"
+					},
+					{
+						value: "high",
+						displayName: "High"
+					},
+					{
+						value: "max",
+						displayName: "Max"
+					}
+				]
+			}
+		],
+		variants: [
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "low"
+					}
+				],
+				displayName: "GLM 5.3 Flash Low"
+			},
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "high"
+					}
+				],
+				displayName: "GLM 5.3 Flash High"
+			},
+			{
+				params: [
+					{
+						id: "reasoning",
+						value: "max"
+					}
+				],
+				displayName: "GLM 5.3 Flash Max",
+				isDefault: true
+			}
+		]
+	},
 	{
 		id: "gpt-5-mini",
 		displayName: "GPT-5 Mini",

package/src/cursor-fallback-warning.ts

@@ -1,22 +1,26 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isCursorModel } from "./cursor-model.js";
 import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
-import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import { cursorSessionScopeKeyForManager } from "./cursor-session-scope.js";
 import type { CursorModelFallbackIssue } from "./model-discovery.js";
 
 export type CursorFallbackWarningExtensionApi = CursorModelLifecycleExtensionApi;
 
 export function registerCursorFallbackIssueWarning(
 	pi: CursorFallbackWarningExtensionApi,
-	issue: CursorModelFallbackIssue,
-): void {
+): (nextIssue: CursorModelFallbackIssue | undefined) => void {
+	let issue: CursorModelFallbackIssue | undefined;
 	const warnedSessionScopeKeys = new Set<string>();
 
 	registerCursorModelLifecycle(pi, (ctx: ExtensionContext) => {
-		if (!isCursorModel(ctx.model) || !ctx.hasUI) return;
-		const scopeKey = getCursorSessionScopeKey();
+		if (!issue || !isCursorModel(ctx.model) || !ctx.hasUI) return;
+		const scopeKey = cursorSessionScopeKeyForManager(ctx.sessionManager);
 		if (warnedSessionScopeKeys.has(scopeKey)) return;
 		warnedSessionScopeKeys.add(scopeKey);
 		ctx.ui.notify(issue.message, "warning");
 	});
+	return (nextIssue) => {
+		if (nextIssue?.reason !== issue?.reason || nextIssue?.message !== issue?.message) warnedSessionScopeKeys.clear();
+		issue = nextIssue;
+	};
 }

package/src/cursor-http1.ts

@@ -1,6 +1,7 @@
 import type { CursorSdkModule } from "./cursor-sdk-runtime.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
 import { asRecord } from "./cursor-record-utils.js";
+import { getCursorSessionSettings } from "./cursor-session-settings.js";
 
 export const CURSOR_HTTP1_ENTRY_TYPE = "cursor-http1-state";
 
@@ -12,7 +13,6 @@ type CursorHttp1Sdk = {
 	Cursor: Pick<CursorSdkModule["Cursor"], "configure">;
 };
 
-let sessionCursorHttp1Enabled: boolean | undefined;
 let globalPreferenceAuthoritative = false;
 let configuredCursor: CursorHttp1Sdk["Cursor"] | undefined;
 
@@ -20,16 +20,16 @@ export function isCursorHttp1EntryData(value: unknown): value is CursorHttp1Entr
 	return typeof asRecord(value)?.enabled === "boolean";
 }
 
-export function getStoredCursorHttp1Enabled(): boolean | undefined {
-	return sessionCursorHttp1Enabled;
+export function getStoredCursorHttp1Enabled(scopeKey?: string): boolean | undefined {
+	return getCursorSessionSettings(scopeKey).http1;
 }
 
-export function setStoredCursorHttp1Enabled(enabled: boolean | undefined): void {
-	sessionCursorHttp1Enabled = enabled;
+export function setStoredCursorHttp1Enabled(enabled: boolean | undefined, scopeKey?: string): void {
+	getCursorSessionSettings(scopeKey).http1 = enabled;
 }
 
-export function getResolvedSessionCursorHttp1Enabled(): boolean | undefined {
-	return globalPreferenceAuthoritative ? undefined : sessionCursorHttp1Enabled;
+export function getResolvedSessionCursorHttp1Enabled(scopeKey?: string): boolean | undefined {
+	return globalPreferenceAuthoritative ? undefined : getStoredCursorHttp1Enabled(scopeKey);
 }
 
 export function setCursorHttp1GlobalPreferenceAuthoritative(authoritative: boolean): void {
@@ -58,7 +58,7 @@ export function configureCursorSdkHttp1(
 
 export const __testUtils = {
 	reset(): void {
-		sessionCursorHttp1Enabled = undefined;
+		setStoredCursorHttp1Enabled(undefined);
 		globalPreferenceAuthoritative = false;
 		configuredCursor = undefined;
 	},