pi-cursor-sdk 0.1.30 → 0.1.31

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 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/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/package.json

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

package/src/cursor-state.ts

@@ -138,6 +138,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 +157,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 +349,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)));
+			}
 		}
 	}