pi-cursor-sdk 0.1.30 → 0.1.32

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 0.1.32 - 2026-06-02
+
+### Added
+
+- Add a production typing-safety regression test that blocks broad TypeScript escape hatches such as `as unknown as`, `as any`, `as never`, explicit `any`, and production `@ts-ignore` / `@ts-expect-error` usage.
+
+### Changed
+
+- Replace repeated native replay render-test `as never` casts with typed test render fixture helpers.
+- Use the maintained Homebrew Crabbox binary on `PATH` for platform smoke with a `0.24.0` minimum version, keeping `PLATFORM_SMOKE_CRABBOX` as an explicit override only.
+
+### Fixed
+
+- Harden local Cursor cache/config JSON parsing so model-list, context-window, and fast-default files are validated from `unknown` before trusted values are used.
+
+## 0.1.31 - 2026-06-01
+
+### Added
+
+- Add Cursor `:fast` and `:slow` virtual model aliases for models with a Cursor SDK `fast` parameter so subagents and workflow-spawned agents can choose fast/slow independently of saved `/cursor-fast` defaults (#112).
+
 ## 0.1.30 - 2026-06-01
 
 ### Added

package/README.md

@@ -168,7 +168,7 @@ pi --model cursor/gpt-5.5@272k:xhigh
 pi --model cursor/gpt-5.5@1m --thinking medium
 ```
 
-Cursor-only parameters are not encoded into pi model IDs. Cursor `context` becomes a pi-visible model variant because it changes pi's native `contextWindow`; Cursor `fast` and Cursor SDK conversation mode are extension state, not model identity. Alias model IDs use their selected SDK ID for Cursor-only state such as fast defaults, with read fallback for older defaults keyed by the underlying Cursor base model.
+Cursor `context` becomes a pi-visible model variant because it changes pi's native `contextWindow`. For models that expose Cursor's boolean `fast` parameter, the extension also registers virtual `:fast` and `:slow` model aliases such as `cursor/composer-2-5:slow` and `cursor/gpt-5.5@1m:fast`. Those aliases are selection-only controls for subagents and workflow-spawned agents: they send the same Cursor SDK model ID plus an explicit `fast=true` or `fast=false` param, and they take precedence over saved `/cursor-fast` session/global defaults. Cursor SDK conversation mode remains extension state, not model identity. Alias model IDs use their selected SDK ID for Cursor-only state such as fast defaults, with read fallback for older defaults keyed by the underlying Cursor base model.
 
 ## Thinking support
 
@@ -190,7 +190,7 @@ Some Cursor SDK models do not expose a `reasoning`, `effort`, or `thinking` para
 
 ## Fast mode
 
-Use `/cursor-fast` to persistently toggle fast mode for the selected Cursor model when the model supports Cursor's `fast` parameter.
+Use `/cursor-fast` to persistently toggle fast mode for the selected unsuffixed Cursor model when the model supports Cursor's `fast` parameter.
 
 Fast preferences are remembered per selected Cursor SDK model ID or alias and stored:
 
@@ -204,7 +204,16 @@ pi --model cursor/gpt-5.5@1m --cursor-fast -p "Say ok only"
 pi --model cursor/composer-2-5 --cursor-no-fast -p "Say ok only"
 ```
 
-Composer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~/.pi/agent/cursor-sdk.json`.
+For per-agent control, select the virtual model alias instead of mutating the shared saved default:
+
+```bash
+pi --model cursor/composer-2-5:slow -p "Say ok only"
+pi --model cursor/gpt-5.5@1m:fast -p "Say ok only"
+```
+
+The `:fast` and `:slow` aliases are available only for Cursor models whose catalog exposes a `fast` parameter. They override saved `/cursor-fast` session/global defaults while leaving `--cursor-fast` and `--cursor-no-fast` as explicit process-level force flags. `/cursor-fast` does not persist a new default while a virtual fast/slow alias is selected; switch to the unsuffixed model first.
+
+Composer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` or a `:slow` virtual alias for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~/.pi/agent/cursor-sdk.json`.
 
 In interactive mode, the footer only shows fast mode when fast is enabled and Cursor mode when it is non-default. Fast and plan mode share one Cursor status value, so they do not overwrite each other:
 
@@ -218,7 +227,7 @@ If you do not see `cursor fast`, fast mode is off. If you do not see `cursor pla
 
 ## Cursor SDK mode
 
-Cursor SDK conversation mode is Cursor-only extension state. It is not a pi model variant, not pi thinking/reasoning, not Cursor `fast`, and not pi's separate read-only plan-mode extension.
+Cursor SDK conversation mode is Cursor-only extension state. It is not a pi model variant, not pi thinking/reasoning, not a `:fast`/`:slow` virtual fast alias, and not pi's separate read-only plan-mode extension.
 
 Default mode is `agent`. Start a one-shot run in a specific mode:
 

package/docs/crabbox-platform-testing-lessons.md

@@ -154,7 +154,7 @@ PLATFORM_SMOKE_WINDOWS_USER=<windows-ssh-user>
 PLATFORM_SMOKE_WINDOWS_WORK_ROOT=C:\crabbox\<project>
 ```
 
-Pin Crabbox deliberately. Exact pins are best for release-critical harnesses whose parsing depends on CLI output. Minimum version checks are fine for simpler gates. Current local baseline is Crabbox `0.24.0`.
+Pin Crabbox deliberately. Exact pins are best for release-critical harnesses whose parsing depends on CLI output. Minimum version checks are fine for simpler gates. Current local baseline is Crabbox `0.24.0` or newer from the Homebrew package.
 
 ## Target setup best practices
 

package/docs/cursor-model-ux-spec.md

@@ -10,7 +10,7 @@ Current implementation notes:
 
 - Cursor context variants use `base@context` pi model IDs.
 - Cursor `reasoning`, `effort`, and boolean `thinking` parameters are driven by pi native thinking when the Cursor SDK exposes those controls.
-- Cursor `fast` is extension state, not model identity.
+- Cursor `fast` is extension state by default; models that expose `fast` also get selection-only `:fast` / `:slow` virtual aliases for per-agent overrides.
 - Cursor SDK `mode` (`agent` or `plan`) is extension session state, not model identity, pi thinking, Cursor `fast`, or pi's separate plan-mode extension.
 - Cursor status uses one coordinated `ctx.ui.setStatus("cursor", ...)` value for fast and non-default plan mode; the default pi footer remains intact.
 - Installed `@cursor/sdk` user messages accept images, and Cursor models are treated as image-capable; registered input metadata is `text` plus `image`.
@@ -136,7 +136,7 @@ Use native pi abstractions wherever possible:
 | Cursor `reasoning` | pi native thinking via `thinkingLevelMap` |
 | Cursor `effort` | pi native thinking via `thinkingLevelMap` |
 | Cursor `thinking=false` | pi native `off` |
-| Cursor `fast` | extension state, not model identity |
+| Cursor `fast` | extension state plus `:fast` / `:slow` virtual aliases for per-agent overrides |
 | Cursor SDK `mode` | extension session state; `agent` by default, `plan` via SDK-native mode |
 | Footer | default pi footer plus optional extension status |
 
@@ -156,7 +156,7 @@ Rules:
 - Register one pi model for each Cursor base model and each unambiguous SDK alias when there is no Cursor `context` parameter.
 - Register one pi model per Cursor `context` value for each Cursor base model and each unambiguous SDK alias when the model exposes a `context` parameter.
 - Skip SDK aliases that collide with another base model ID or are shared by multiple base models; those aliases can resolve differently from the pi row metadata.
-- Do not encode `reasoning`, `effort`, `thinking`, `fast`, or Cursor SDK `mode` into pi model IDs.
+- Do not encode `reasoning`, `effort`, `thinking`, or Cursor SDK `mode` into pi model IDs. For models with a Cursor `fast` parameter, also register selection-only `:fast` and `:slow` virtual model aliases that do not change pi-native metadata.
 - Prefer stable, readable `@<context>` suffixes that do not conflict with pi's final `:<thinking>` suffix parser.
 - Sort Cursor models by base ID, then context value in Cursor SDK order before calling `pi.registerProvider()`. Registration order matters for `/model` display and model cycling; `--list-models` sorts output separately.
 
@@ -168,6 +168,9 @@ cursor/gpt-5.5@272k
 cursor/claude-opus-4-8@1m
 cursor/claude-opus-4-8@300k
 cursor/composer-2-5
+cursor/composer-2-5:fast
+cursor/composer-2-5:slow
+cursor/gpt-5.5@1m:fast
 ```
 
 Avoid colon-based context IDs in the first implementation unless this spec is intentionally changed:
@@ -190,7 +193,7 @@ Reason:
 
 - `@1m` keeps context visually separate from pi's native `:medium` thinking suffix.
 - Context variants make `contextWindow` accurate in `--list-models`, the native footer, context overflow checks, and compaction logic.
-- `fast` is intentionally not a model variant because it does not affect pi model metadata and would double list noise.
+- `:fast` / `:slow` are virtual aliases, not separate Cursor SDK base models: they keep the same context/thinking metadata and only force the outgoing Cursor `fast` param. They exist so subagents and workflow-spawned agents can choose fast/slow without mutating shared `/cursor-fast` defaults.
 
 ### Metadata Per Registered Model
 
@@ -362,17 +365,18 @@ fast=false <-> fast=true
 
 Rules:
 
-- `fast` is extension state, not pi model identity.
-- Toggle with `/cursor-fast`.
-- Store per-session and global per-base-model preferences.
-- When calling `Agent.create()`, include the selected `fast` value in Cursor model params.
+- Unsuffixed models use extension state from `/cursor-fast`, per-session entries, and global defaults.
+- `:fast` / `:slow` virtual model aliases force fast on/off for that selected agent and override saved defaults without writing state.
+- Toggle unsuffixed models with `/cursor-fast`; do not persist a new default while a virtual fast alias is selected.
+- Store per-session and global per-base-model preferences for unsuffixed models.
+- When calling `Agent.create()` or `agent.send()`, include the selected `fast` value in Cursor model params.
 - Show `fast` through `ctx.ui.setStatus()` when enabled.
-- Support a first-pass CLI flag, `--cursor-fast`, to force fast mode for one run when the selected model supports it.
+- Keep `--cursor-fast` and `--cursor-no-fast` as explicit process-level force flags.
 
 Reason:
 
 - `fast` does not affect pi `contextWindow`, thinking levels, or input support.
-- Registering fast/non-fast variants would make `--list-models` noisy without improving native pi behavior.
+- The virtual aliases trade small `--list-models` noise for per-agent selection that works with subagents and dynamic workflows, where mutating a shared global fast default is the wrong abstraction.
 
 Status example:
 
@@ -521,7 +525,7 @@ Reason:
 - pi supports one final `:<thinking>` suffix.
 - Cursor-only parameters are not generic pi CLI parameters.
 - Context is already represented by the registered pi model ID.
-- `fast` is controlled by saved extension defaults or the first-pass `--cursor-fast` extension flag.
+- `fast` is controlled by saved extension defaults, `:fast` / `:slow` virtual model aliases, or the `--cursor-fast` / `--cursor-no-fast` extension flags.
 - Cursor SDK `mode` is controlled by `/cursor-mode` session state or the first-pass `--cursor-mode` extension flag; it is never encoded in `--model`.
 
 For print mode:
@@ -529,7 +533,7 @@ For print mode:
 - no keybindings,
 - use selected context model variant,
 - use `--thinking` or `:medium` for reasoning/effort,
-- use saved global `fast` defaults unless `--cursor-fast` is present,
+- use saved global `fast` defaults unless a virtual `:fast` / `:slow` model alias or force flag is present,
 - use Cursor SDK `agent` mode unless `/cursor-mode` session state or `--cursor-mode` overrides it.
 
 Fast flag example:

package/docs/platform-smoke.md

@@ -52,12 +52,12 @@ The runner uses one supported Crabbox build.
 Current baseline:
 
 ```text
-install: brew install crabbox
-version: 0.24.0
-binary: /opt/homebrew/bin/crabbox on Apple Silicon Homebrew installs
+install: brew install openclaw/tap/crabbox
+version: 0.24.0 or newer
+binary: Homebrew `crabbox` on PATH (`/opt/homebrew/bin/crabbox` on Apple Silicon Homebrew installs)
 ```
 
-Keep this exact version or replace it with another exact released Crabbox version when updating the gate. `smoke:platform:doctor` verifies the configured Crabbox binary and fails on mismatch.
+Use the Homebrew Crabbox binary on PATH for normal release gates. `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` is only an explicit override for testing a non-default binary. `smoke:platform:doctor` verifies the configured binary and fails when it is older than the configured minimum version.
 
 Required Crabbox providers:
 
@@ -188,8 +188,8 @@ export default {
     "cursor-abort-cleanup",
   ],
   requiredCrabbox: {
-    install: "brew install crabbox",
-    version: "0.24.0",
+    install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+    minVersion: "0.24.0",
   },
   ubuntuContainerImage: "cimg/node:24.16",
   nodeValidationMajor: 24,
@@ -203,6 +203,7 @@ export default {
 The doctor fails if any required value is missing.
 
 ```bash
+# Optional override; by default the gate uses Homebrew `crabbox` from PATH.
 PLATFORM_SMOKE_CRABBOX=/opt/homebrew/bin/crabbox
 
 PLATFORM_SMOKE_MAC_HOST=localhost
@@ -313,7 +314,7 @@ tar --version
 Doctor checks:
 
 1. Required env vars exist.
-2. `PLATFORM_SMOKE_CRABBOX` exists and is executable.
+2. Homebrew `crabbox` is available on PATH, or `PLATFORM_SMOKE_CRABBOX` points at an executable override.
 3. Crabbox build matches the configured baseline.
 4. Crabbox provider registry includes `local-container`, `ssh`, and `parallels`.
 5. `crabbox doctor --provider local-container --json` passes.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.30",
+	"version": "0.1.32",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

package/platform-smoke.config.mjs

@@ -13,8 +13,8 @@ export default {
 		"cursor-abort-cleanup",
 	],
 	requiredCrabbox: {
-		install: "brew install crabbox",
-		version: "0.24.0",
+		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+		minVersion: "0.24.0",
 	},
 	ubuntuContainerImage: "cimg/node:24.16",
 	nodeValidationMajor: 24,

package/scripts/platform-smoke/doctor.mjs

@@ -45,6 +45,10 @@ function shell(cmd, opts = {}) {
 	catch { return null; }
 }
 
+function commandPath(command) {
+	return shell(`command -v ${command}`);
+}
+
 function parseLeaseId(output) {
 	return output.match(/\bleased\s+(\S+)/)?.[1]
 		?? output.match(/\blease=(\S+)/)?.[1]
@@ -126,7 +130,6 @@ function runChecks(config) {
 	// ── Phase 1: environment variables ──
 	console.log("\n── Environment variables ──");
 	const requiredVars = [
-		"PLATFORM_SMOKE_CRABBOX",
 		"CURSOR_API_KEY",
 		"PLATFORM_SMOKE_WINDOWS_VM",
 		"PLATFORM_SMOKE_WINDOWS_SNAPSHOT",
@@ -134,6 +137,7 @@ function runChecks(config) {
 		"PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT",
 	];
 	const optionalVars = [
+		"PLATFORM_SMOKE_CRABBOX",
 		"PLATFORM_SMOKE_MAC_HOST",
 		"PLATFORM_SMOKE_MAC_USER",
 		"PLATFORM_SMOKE_MAC_WORK_ROOT",
@@ -151,12 +155,17 @@ function runChecks(config) {
 
 	// ── Phase 2: Crabbox binary ──
 	console.log("\n── Crabbox binary ──");
-	const cbox = env("PLATFORM_SMOKE_CRABBOX");
-	if (!cbox) {
-		fail("PLATFORM_SMOKE_CRABBOX not set");
+	const cbox = env("PLATFORM_SMOKE_CRABBOX") || "crabbox";
+	const cboxPath = env("PLATFORM_SMOKE_CRABBOX") || commandPath("crabbox");
+	if (!cboxPath) {
+		fail(`crabbox not found on PATH; install with ${config.requiredCrabbox?.install ?? "Homebrew"} or set PLATFORM_SMOKE_CRABBOX`);
 	} else {
-		try { accessSync(cbox, constants.X_OK); ok(`binary: ${cbox}`); }
-		catch { fail(`${cbox} not executable`); }
+		if (env("PLATFORM_SMOKE_CRABBOX")) {
+			try { accessSync(cboxPath, constants.X_OK); ok(`binary: ${cboxPath} (env override)`); }
+			catch { fail(`${cboxPath} not executable`); }
+		} else {
+			ok(`binary: ${cboxPath} (PATH)`);
+		}
 		const ver = silent(cbox, ["--version"]);
 		const actualVersion = ver?.split("\n")[0]?.trim();
 		if (actualVersion) ok(`version: ${actualVersion}`);
@@ -174,9 +183,9 @@ function runChecks(config) {
 		}
 		const requiredCommit = config.requiredCrabbox?.commit;
 		if (!requiredVersion && !minimumVersion && requiredCommit) {
-			const gitRoot = findGitRoot(dirname(cbox));
+			const gitRoot = findGitRoot(dirname(cboxPath));
 			const actualCommit = gitRoot ? silent("git", ["-C", gitRoot, "rev-parse", "HEAD"]) : null;
-			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cbox}`);
+			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cboxPath}`);
 			else if (actualCommit !== requiredCommit) fail(`Crabbox commit mismatch: expected ${requiredCommit}, got ${actualCommit}`);
 			else ok(`commit: ${actualCommit}`);
 		}
@@ -184,7 +193,7 @@ function runChecks(config) {
 
 	// ── Phase 3: Crabbox providers ──
 	console.log("\n── Crabbox providers ──");
-	if (cbox) {
+	if (cboxPath) {
 		const providerList = silent(cbox, ["providers"]);
 		if (providerList) {
 			for (const provider of ["ssh", "local-container", "parallels"]) {

package/src/context-window-cache.ts

@@ -18,15 +18,31 @@ function isPositiveInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseContextWindowCacheFile(value: unknown): ContextWindowCacheFile | undefined {
+	if (!isRecord(value)) return undefined;
+	const { contextWindows } = value;
+	if (contextWindows === undefined) return {};
+	if (!isRecord(contextWindows)) return undefined;
+	return {
+		contextWindows: Object.fromEntries(
+			Object.entries(contextWindows).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
+		),
+	};
+}
+
 function loadUserContextWindowOverrides(): Map<string, number> {
 	userContextWindowOverrideLoadCount += 1;
 	const path = getCachePath();
 	const overrides = new Map<string, number>();
 	if (!existsSync(path)) return overrides;
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ContextWindowCacheFile;
-		for (const [modelId, contextWindow] of Object.entries(parsed.contextWindows ?? {})) {
-			if (isPositiveInteger(contextWindow)) overrides.set(modelId, contextWindow);
+		const parsed = parseContextWindowCacheFile(JSON.parse(readFileSync(path, "utf-8")));
+		for (const [modelId, contextWindow] of Object.entries(parsed?.contextWindows ?? {})) {
+			overrides.set(modelId, contextWindow);
 		}
 	} catch {
 		return overrides;
@@ -52,10 +68,10 @@ export function getCachedContextWindow(modelId: string): number | undefined {
 }
 
 export function getCheckpointContextWindow(checkpoint: unknown): number | undefined {
-	if (checkpoint === null || typeof checkpoint !== "object") return undefined;
-	const tokenDetails = (checkpoint as Record<PropertyKey, unknown>).tokenDetails;
-	if (tokenDetails === null || typeof tokenDetails !== "object") return undefined;
-	const maxTokens = (tokenDetails as Record<PropertyKey, unknown>).maxTokens;
+	if (!isRecord(checkpoint)) return undefined;
+	const { tokenDetails } = checkpoint;
+	if (!isRecord(tokenDetails)) return undefined;
+	const { maxTokens } = tokenDetails;
 	if (!isPositiveInteger(maxTokens)) return undefined;
 	return maxTokens;
 }

package/src/cursor-state.ts

@@ -69,10 +69,13 @@ export function parseCursorAgentMode(raw: unknown): AgentModeOption | undefined
 	return isCursorAgentMode(mode) ? mode : undefined;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function isCursorFastEntryData(value: unknown): value is CursorFastEntryData {
-	if (!value || typeof value !== "object") return false;
-	const data = value as Record<string, unknown>;
-	return (typeof data.modelId === "string" || typeof data.baseModelId === "string") && typeof data.fast === "boolean";
+	if (!isRecord(value)) return false;
+	return (typeof value.modelId === "string" || typeof value.baseModelId === "string") && typeof value.fast === "boolean";
 }
 
 function getCursorFastEntryModelId(data: CursorFastEntryData): string {
@@ -80,9 +83,19 @@ function getCursorFastEntryModelId(data: CursorFastEntryData): string {
 }
 
 function isCursorModeEntryData(value: unknown): value is CursorModeEntryData {
-	if (!value || typeof value !== "object") return false;
-	const data = value as Record<string, unknown>;
-	return isCursorAgentMode(data.mode);
+	return isRecord(value) && isCursorAgentMode(value.mode);
+}
+
+function parseCursorGlobalConfig(value: unknown): CursorGlobalConfig | undefined {
+	if (!isRecord(value)) return undefined;
+	const { fastDefaults } = value;
+	if (fastDefaults === undefined) return {};
+	if (!isRecord(fastDefaults)) return undefined;
+	return {
+		fastDefaults: Object.fromEntries(
+			Object.entries(fastDefaults).filter((entry): entry is [string, boolean] => typeof entry[1] === "boolean"),
+		),
+	};
 }
 
 function getConfigPath(): string {
@@ -93,12 +106,8 @@ function loadGlobalFastPreferences(): Map<string, boolean> {
 	const path = getConfigPath();
 	if (!existsSync(path)) return new Map();
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as CursorGlobalConfig;
-		return new Map(
-			Object.entries(parsed.fastDefaults ?? {}).filter(
-				(entry): entry is [string, boolean] => typeof entry[1] === "boolean",
-			),
-		);
+		const parsed = parseCursorGlobalConfig(JSON.parse(readFileSync(path, "utf-8")));
+		return new Map(Object.entries(parsed?.fastDefaults ?? {}));
 	} catch {
 		return new Map();
 	}
@@ -138,6 +147,10 @@ function getFastPreferenceModelId(metadata: NonNullable<ReturnType<typeof getCur
 	return metadata.selectionModelId || metadata.baseModelId;
 }
 
+function getVirtualFastBaseModelId(modelId: string): string {
+	return modelId.replace(/:(?:fast|slow)$/, "");
+}
+
 function getStoredFastPreference(metadata: NonNullable<ReturnType<typeof getCursorModelMetadata>>): boolean | undefined {
 	const preferenceModelId = getFastPreferenceModelId(metadata);
 	return (
@@ -153,6 +166,7 @@ function getEffectiveFast(modelId: string): boolean | undefined {
 	if (!metadata?.supportsFast) return undefined;
 	if (cliForceNoFast) return false;
 	if (cliForceFast) return true;
+	if (metadata.fastOverride !== undefined) return metadata.fastOverride;
 	return getStoredFastPreference(metadata) ?? metadata.defaultFast;
 }
 
@@ -344,6 +358,14 @@ export function registerCursorRuntimeControls(pi: CursorRuntimeControlsExtension
 				ctx.ui.notify("Cursor fast is forced by --cursor-fast", "info");
 				return;
 			}
+			if (metadata.fastOverride !== undefined) {
+				const state = metadata.fastOverride ? "enabled" : "disabled";
+				ctx.ui.notify(
+					`Cursor fast is fixed ${state} by selected model ${metadata.piModelId}; choose ${getVirtualFastBaseModelId(metadata.piModelId)} to use /cursor-fast preferences`,
+					"info",
+				);
+				return;
+			}
 
 			const preferenceModelId = getFastPreferenceModelId(metadata);
 			const current = getEffectiveFast(metadata.piModelId) ?? false;

package/src/model-discovery.ts

@@ -88,6 +88,7 @@ export interface CursorModelMetadata {
 	contextWindow: number;
 	supportsFast: boolean;
 	defaultFast: boolean;
+	fastOverride?: boolean;
 	supportsReasoning: boolean;
 	thinkingLevelMap?: ThinkingLevelMap;
 	parameterIds: {
@@ -205,19 +206,35 @@ function getParamValue(params: ModelParameterValue[], id: string): string | unde
 	return params.find((param) => param.id === id)?.value;
 }
 
-function encodePiModelId(modelId: string, context?: string): string {
-	return context ? `${modelId}@${context}` : modelId;
+function encodePiModelId(modelId: string, context?: string, fastOverride?: boolean): string {
+	const contextQualified = context ? `${modelId}@${context}` : modelId;
+	if (fastOverride === true) return `${contextQualified}:fast`;
+	if (fastOverride === false) return `${contextQualified}:slow`;
+	return contextQualified;
 }
 
-function getModelName(item: ModelListItem, context?: string, alias?: string): string {
+function getModelName(item: ModelListItem, context?: string, alias?: string, fastOverride?: boolean): string {
 	const displayName = item.displayName || item.id;
-	const baseName = alias ? `${displayName} (${alias})` : displayName;
+	const qualifiers: string[] = [];
+	if (alias) qualifiers.push(alias);
+	if (fastOverride === true) qualifiers.push("fast");
+	if (fastOverride === false) qualifiers.push("slow");
+	const baseName = qualifiers.length > 0 ? `${displayName} (${qualifiers.join(", ")})` : displayName;
 	return context ? `${baseName} @ ${context}` : baseName;
 }
 
+function getFastOverrideBasePiModelId(piModelId: string): string {
+	return piModelId.replace(/:(?:fast|slow)$/, "");
+}
+
 function getContextWindow(contextWindowCache: Map<string, number>, piModelId: string, context?: string, baseModelId?: string): number {
-	return (
+	const fastOverrideBasePiModelId = getFastOverrideBasePiModelId(piModelId);
+	const contextWindowOverride =
 		contextWindowCache.get(piModelId) ??
+		(fastOverrideBasePiModelId !== piModelId ? contextWindowCache.get(fastOverrideBasePiModelId) : undefined);
+
+	return (
+		contextWindowOverride ??
 		(context ? parseContextWindow(context) : undefined) ??
 		(baseModelId ? contextWindowCache.get(baseModelId) : undefined) ??
 		contextWindowCache.get("default") ??
@@ -232,6 +249,7 @@ function toMetadata(
 	defaultParams: ModelParameterValue[],
 	context: string | undefined,
 	contextWindowCache: Map<string, number>,
+	fastOverride?: boolean,
 ): CursorModelMetadata {
 	const thinkingLevelMap = getThinkingLevelMap(item);
 	const fastValue = getParamValue(defaultParams, "fast")?.toLowerCase();
@@ -245,6 +263,7 @@ function toMetadata(
 		contextWindow: getContextWindow(contextWindowCache, piModelId, context, item.id),
 		supportsFast: getParameter(item, "fast") !== undefined,
 		defaultFast: fastValue === "true",
+		...(fastOverride !== undefined ? { fastOverride } : {}),
 		supportsReasoning: thinkingLevelMap !== undefined,
 		...(thinkingLevelMap ? { thinkingLevelMap } : {}),
 		parameterIds: {
@@ -310,16 +329,21 @@ function toModelConfigs(
 	const contexts = contextValues.length > 0 ? contextValues : [undefined];
 	const configs: ProviderModelConfig[] = [];
 
+	const fastOverrides = getParameter(item, "fast") === undefined ? [undefined] : [undefined, true, false];
+
 	for (const selectionModelId of getModelIds(item, reservedBaseModelIds, ambiguousAliases)) {
 		const alias = selectionModelId === item.id ? undefined : selectionModelId;
 		for (const context of contexts) {
-			const params = context ? replaceParam(defaultParams, "context", context) : defaultParams;
-			const piModelId = encodePiModelId(selectionModelId, context);
-			if (usedPiModelIds.has(piModelId)) continue;
-			usedPiModelIds.add(piModelId);
-			const metadata = toMetadata(item, piModelId, selectionModelId, params, context, contextWindowCache);
-			metadataByPiModelId.set(piModelId, metadata);
-			configs.push(toModelConfig(metadata, getModelName(item, context, alias)));
+			const contextParams = context ? replaceParam(defaultParams, "context", context) : defaultParams;
+			for (const fastOverride of fastOverrides) {
+				const params = fastOverride === undefined ? contextParams : replaceParam(contextParams, "fast", fastOverride ? "true" : "false");
+				const piModelId = encodePiModelId(selectionModelId, context, fastOverride);
+				if (usedPiModelIds.has(piModelId)) continue;
+				usedPiModelIds.add(piModelId);
+				const metadata = toMetadata(item, piModelId, selectionModelId, params, context, contextWindowCache, fastOverride);
+				metadataByPiModelId.set(piModelId, metadata);
+				configs.push(toModelConfig(metadata, getModelName(item, context, alias, fastOverride)));
+			}
 		}
 	}
 

package/src/model-list-cache.ts

@@ -8,6 +8,7 @@ import { parseEnvBoolean } from "./cursor-env-boolean.js";
 const MODEL_LIST_CACHE_FILE = "cursor-sdk-model-list.json";
 const MODEL_LIST_CACHE_VERSION = 1;
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHE_CLOCK_SKEW_MS = 5 * 60 * 1000;
 const DISABLE_ENV_VAR = "PI_CURSOR_SDK_DISABLE_MODEL_CACHE";
 const TTL_ENV_VAR = "PI_CURSOR_SDK_MODEL_CACHE_TTL_MS";
 
@@ -45,20 +46,83 @@ export function fingerprintApiKey(apiKey: string): string {
 	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function isModelParameterValue(value: unknown): value is NonNullable<ModelListItem["variants"]>[number]["params"][number] {
+	return isRecord(value) && typeof value.id === "string" && typeof value.value === "string";
+}
+
+function isModelParameterDefinitionValue(value: unknown): value is NonNullable<ModelListItem["parameters"]>[number]["values"][number] {
+	return isRecord(value) && typeof value.value === "string" && (value.displayName === undefined || typeof value.displayName === "string");
+}
+
+function isModelParameterDefinition(value: unknown): value is NonNullable<ModelListItem["parameters"]>[number] {
+	if (!isRecord(value)) return false;
+	return (
+		typeof value.id === "string" &&
+		(value.displayName === undefined || typeof value.displayName === "string") &&
+		Array.isArray(value.values) &&
+		value.values.every(isModelParameterDefinitionValue)
+	);
+}
+
+function isModelVariant(value: unknown): value is NonNullable<ModelListItem["variants"]>[number] {
+	if (!isRecord(value)) return false;
+	return (
+		Array.isArray(value.params) &&
+		value.params.every(isModelParameterValue) &&
+		typeof value.displayName === "string" &&
+		(value.description === undefined || typeof value.description === "string") &&
+		(value.isDefault === undefined || typeof value.isDefault === "boolean")
+	);
+}
+
+function isModelListItem(value: unknown): value is ModelListItem {
+	if (!isRecord(value)) return false;
+	return (
+		typeof value.id === "string" &&
+		typeof value.displayName === "string" &&
+		(value.description === undefined || typeof value.description === "string") &&
+		(value.aliases === undefined || isStringArray(value.aliases)) &&
+		(value.parameters === undefined || (Array.isArray(value.parameters) && value.parameters.every(isModelParameterDefinition))) &&
+		(value.variants === undefined || (Array.isArray(value.variants) && value.variants.every(isModelVariant)))
+	);
+}
+
+function isValidFetchedAt(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= Date.now() + MAX_CACHE_CLOCK_SKEW_MS;
+}
+
+function parseModelListCacheFile(value: unknown): ModelListCacheFile | undefined {
+	if (!isRecord(value)) return undefined;
+	if (
+		value.version !== MODEL_LIST_CACHE_VERSION ||
+		!isValidFetchedAt(value.fetchedAt) ||
+		typeof value.keyFingerprint !== "string" ||
+		!Array.isArray(value.models) ||
+		!value.models.every(isModelListItem)
+	) {
+		return undefined;
+	}
+	return {
+		version: value.version,
+		fetchedAt: value.fetchedAt,
+		keyFingerprint: value.keyFingerprint,
+		models: value.models,
+	};
+}
+
 function readCacheFile(): ModelListCacheFile | undefined {
 	const path = getCachePath();
 	if (!existsSync(path)) return undefined;
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ModelListCacheFile;
-		if (
-			parsed.version !== MODEL_LIST_CACHE_VERSION ||
-			typeof parsed.fetchedAt !== "number" ||
-			typeof parsed.keyFingerprint !== "string" ||
-			!Array.isArray(parsed.models)
-		) {
-			return undefined;
-		}
-		return parsed;
+		return parseModelListCacheFile(JSON.parse(readFileSync(path, "utf-8")));
 	} catch {
 		return undefined;
 	}