pi-cursor-sdk 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## Unreleased
+## 0.1.8 - 2026-05-14
+
+### Changed
+
+- Update the verified dependency baseline to `@cursor/sdk` 1.0.13 and Vitest 4.1.6.
+- Register latest-style Cursor SDK model aliases returned by `Cursor.models.list()` as pi-selectable Cursor model IDs, including context-qualified alias variants where applicable.
+- Clarify Max Mode behavior against current Cursor SDK docs: Cursor may enable required Max Mode automatically, but the extension still only advertises catalog-exposed context variants.
 
 ## 0.1.7 - 2026-05-10
 

package/README.md

@@ -137,6 +137,7 @@ How to read model IDs:
 - `cursor/...` is the Cursor provider registered by this extension
 - `@1m`, `@272k`, and `@300k` are context-window variants
 - `:medium`, `:high`, and `:xhigh` are pi thinking-level suffixes for models where the Cursor SDK exposes a pi-controllable thinking parameter
+- latest-style Cursor aliases returned by `Cursor.models.list()` are registered too, using the same context suffixes when the target model has context variants
 
 Examples with pi thinking controls:
 
@@ -146,7 +147,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` is extension state, not model identity.
+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` is extension state, not model identity. Alias model IDs still share Cursor-only state, such as fast defaults, with their underlying Cursor base model.
 
 ## Thinking support
 
@@ -214,7 +215,7 @@ Fallback models are a conservative startup model list. Actual Cursor runs still
 - **Pi tool schemas are not passed through to Cursor.** This extension is a Cursor provider, not a bridge that forwards pi's tool system into Cursor.
 - **One fresh Cursor agent is created per provider call.** Cursor agent state is not reused between pi provider calls.
 - **Ambient Cursor setting/rule layers are not loaded by default.** The current Cursor SDK writes setting/rule loading logs directly to terminal output, which corrupts pi's TUI, so the extension leaves those layers out.
-- **Max Mode is not exposed for these local runs.** The extension only advertises exact context windows supported by the SDK path it uses.
+- **Max Mode is not a manual pi variant.** Cursor's SDK may enable Max Mode automatically for models that require it. This extension only advertises exact context-window variants that the SDK catalog exposes and otherwise uses conservative SDK-derived default/non-Max context windows.
 - **Output token limits are conservative.** Cursor SDK model metadata does not currently expose output token limits directly.
 - **Token usage is approximate in pi.** Cursor SDK usage events include internal agent/tool/cache work, so the extension reports an approximate replayable pi prompt/output size for context display and compaction decisions.
 

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

@@ -20,7 +20,8 @@ Current implementation notes:
 - Cursor-side thinking remains visible. Cursor internal tool activity is recorded from SDK events and scrubbed. In interactive TTY sessions, supported completed `read`, `bash`, and `ls` activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native green cards without forcing Cursor to call pi tools or rerunning Cursor's reads/shell commands. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` disables native replay, and `PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is a registration-only opt-out that keeps the transcript fallback without shadowing pi tool names. When these native cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK completions arrive: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later Cursor tool batches as further `toolUse` turns, then Cursor's final assistant answer. Non-interactive runs keep bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when native tool replay is not active.
 - Cursor SDK usage events report cumulative internal agent/tool/cache work, not the replayable pi prompt context. The extension reports approximate prompt/output usage for pi context display and compaction decisions instead of copying raw Cursor SDK usage. When native replay splits one Cursor SDK run into multiple pi turns, prompt input is counted once for the run; later synthetic replay turns report `input: 0` and only their own output estimate.
 - For models without a catalog `context` parameter, context windows are not hardcoded. The extension ships a bundled SDK-derived default/non-Max cache generated from `createAgentPlatform().checkpointStore.loadLatest(agentId).tokenDetails.maxTokens`. Successful runs can update a local override cache, but model discovery does not probe models at startup.
-- Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.12 exposes internal protobuf fields named `maxMode`/`max_mode`, but the public `ModelSelection` type and the local executor path do not pass a Max Mode selector for local agent runs. Do not advertise Max Mode context windows unless the SDK catalog exposes an exact parameter/variant or the SDK public API adds a Max Mode selector that the extension actually sends.
+- Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.13 documentation says the SDK may enable Max Mode automatically when a selected model requires it, but the public local-agent `ModelSelection` path still does not expose a manual Max Mode selector. Do not advertise Max Mode context windows unless the SDK catalog exposes an exact parameter/variant or the SDK public API adds a Max Mode selector that the extension actually sends.
+- `@cursor/sdk` 1.0.13 adds latest-style `ModelListItem.aliases`. The extension registers those aliases as pi model IDs (with the same context suffixes when applicable) and sends the alias back in `ModelSelection.id`, while sharing Cursor-only state such as fast defaults with the underlying catalog `id`.
 
 ## Goal
 
@@ -69,6 +70,7 @@ Users can persist the stored key through `/login` -> `Use an API key` -> `Cursor
 For each model, use:
 
 - `model.id`
+- `model.aliases`
 - `model.displayName`
 - `model.parameters`
 - `model.variants`
@@ -135,8 +137,8 @@ Register a `cursor` provider with `pi.registerProvider()`.
 
 Rules:
 
-- Register one pi model for each Cursor base model when there is no Cursor `context` parameter.
-- Register one pi model per Cursor `context` value when the model exposes a `context` parameter.
+- Register one pi model for each Cursor base model and SDK alias when there is no Cursor `context` parameter.
+- Register one pi model per Cursor `context` value for each Cursor base model and SDK alias when the model exposes a `context` parameter.
 - Do not encode `reasoning`, `effort`, `thinking`, or `fast` into pi model IDs.
 - 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.
@@ -177,7 +179,7 @@ Reason:
 
 Each registered model must set:
 
-- `id`: context-qualified pi model ID when needed.
+- `id`: context-qualified pi model ID when needed. For SDK aliases, this uses the alias as the pi-visible ID and the alias is sent back to Cursor as `ModelSelection.id`.
 - `name`: human-readable Cursor display name plus context when useful.
 - `reasoning`: `true` only if a Cursor `reasoning`, `effort`, or `thinking` parameter can map to pi thinking. This controls pi's thinking UI and `pi --list-models` `thinking` column; it must not be used to claim whether the Cursor model can think internally. Cursor SDK models are thinking-capable even when this is `false`.
 - `thinkingLevelMap`: model-specific pi-to-Cursor mapping for pi UI, clamping, persistence, and footer display.
@@ -186,7 +188,7 @@ Each registered model must set:
 - `input`: supported input types. The installed Cursor SDK accepts `SDKUserMessage.images`, and Cursor models are expected to support image input, so advertise `["text", "image"]`.
 - `cost`: zeroed unless reliable Cursor costs are available.
 
-The extension stores runtime metadata in an internal map keyed by registered pi model ID. That map records the Cursor base model ID, selected context param, default params, and discovered capabilities. `ProviderModelConfig` has no dedicated metadata field, so do not rely on hidden custom fields for this state.
+The extension stores runtime metadata in an internal map keyed by registered pi model ID. That map records the Cursor base catalog model ID, the Cursor selection model ID (base ID or alias), selected context param, default params, and discovered capabilities. `ProviderModelConfig` has no dedicated metadata field, so do not rely on hidden custom fields for this state.
 
 ## Dynamic Capabilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -38,7 +38,7 @@
 		"test:watch": "vitest"
 	},
 	"dependencies": {
-		"@cursor/sdk": "^1.0.12"
+		"@cursor/sdk": "^1.0.13"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
@@ -48,7 +48,7 @@
 		"@earendil-works/pi-ai": "^0.74.0",
 		"@earendil-works/pi-coding-agent": "^0.74.0",
 		"typescript": "^6.0.3",
-		"vitest": "^4.1.5"
+		"vitest": "^4.1.6"
 	},
 	"pi": {
 		"extensions": [

package/src/context-window-cache.ts

@@ -40,6 +40,10 @@ export function loadContextWindowCache(): Map<string, number> {
 	return cache;
 }
 
+export function getCachedContextWindowExact(modelId: string): number | undefined {
+	return loadContextWindowCache().get(modelId);
+}
+
 export function getCachedContextWindow(modelId: string): number | undefined {
 	const cache = loadContextWindowCache();
 	return cache.get(modelId) ?? cache.get("default");

package/src/model-discovery.ts

@@ -7,7 +7,7 @@ import type {
 } from "@cursor/sdk";
 import { AuthStorage, type ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import type { ModelThinkingLevel, ThinkingLevelMap } from "@earendil-works/pi-ai";
-import { getCachedContextWindow } from "./context-window-cache.js";
+import { getCachedContextWindow, getCachedContextWindowExact } from "./context-window-cache.js";
 
 const CURSOR_PROVIDER_ID = "cursor";
 const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
@@ -217,6 +217,7 @@ async function getDiscoveryApiKey(): Promise<string | undefined> {
 export interface CursorModelMetadata {
 	piModelId: string;
 	baseModelId: string;
+	selectionModelId: string;
 	displayName: string;
 	defaultParams: ModelParameterValue[];
 	context?: string;
@@ -340,23 +341,25 @@ function getParamValue(params: ModelParameterValue[], id: string): string | unde
 	return params.find((param) => param.id === id)?.value;
 }
 
-function encodePiModelId(baseModelId: string, context?: string): string {
-	return context ? `${baseModelId}@${context}` : baseModelId;
+function encodePiModelId(modelId: string, context?: string): string {
+	return context ? `${modelId}@${context}` : modelId;
 }
 
-function getModelName(item: ModelListItem, context?: string): string {
+function getModelName(item: ModelListItem, context?: string, alias?: string): string {
 	const displayName = item.displayName || item.id;
-	return context ? `${displayName} @ ${context}` : displayName;
+	const baseName = alias ? `${displayName} (${alias})` : displayName;
+	return context ? `${baseName} @ ${context}` : baseName;
 }
 
-function getContextWindow(piModelId: string, context?: string): number {
+function getContextWindow(piModelId: string, context?: string, baseModelId?: string): number {
 	if (context) return parseContextWindow(context) ?? FALLBACK_CONTEXT_WINDOW;
-	return getCachedContextWindow(piModelId) ?? FALLBACK_CONTEXT_WINDOW;
+	return getCachedContextWindowExact(piModelId) ?? (baseModelId ? getCachedContextWindow(baseModelId) : undefined) ?? FALLBACK_CONTEXT_WINDOW;
 }
 
 function toMetadata(
 	item: ModelListItem,
 	piModelId: string,
+	selectionModelId: string,
 	defaultParams: ModelParameterValue[],
 	context: string | undefined,
 ): CursorModelMetadata {
@@ -365,10 +368,11 @@ function toMetadata(
 	return {
 		piModelId,
 		baseModelId: item.id,
+		selectionModelId,
 		displayName: item.displayName || item.id,
 		defaultParams: cloneParams(defaultParams),
 		...(context ? { context } : {}),
-		contextWindow: getContextWindow(piModelId, context),
+		contextWindow: getContextWindow(piModelId, context, item.id),
 		supportsFast: getParameter(item, "fast") !== undefined,
 		defaultFast: fastValue === "true",
 		supportsReasoning: thinkingLevelMap !== undefined,
@@ -400,18 +404,40 @@ function getContextValues(item: ModelListItem): string[] {
 	return getParameter(item, "context")?.values.map((value) => value.value) ?? [];
 }
 
-function toModelConfigs(item: ModelListItem): ProviderModelConfig[] {
+function getModelIds(item: ModelListItem, reservedBaseModelIds: Set<string>): string[] {
+	const ids = [item.id];
+	for (const rawAlias of item.aliases ?? []) {
+		const alias = rawAlias.trim();
+		if (!alias || alias === item.id || ids.includes(alias) || reservedBaseModelIds.has(alias)) continue;
+		ids.push(alias);
+	}
+	return ids;
+}
+
+function toModelConfigs(
+	item: ModelListItem,
+	usedPiModelIds: Set<string>,
+	reservedBaseModelIds: Set<string>,
+): ProviderModelConfig[] {
 	const defaultParams = getDefaultParams(item);
 	const contextValues = getContextValues(item);
 	const contexts = contextValues.length > 0 ? contextValues : [undefined];
+	const configs: ProviderModelConfig[] = [];
+
+	for (const selectionModelId of getModelIds(item, reservedBaseModelIds)) {
+		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);
+			metadataByPiModelId.set(piModelId, metadata);
+			configs.push(toModelConfig(metadata, getModelName(item, context, alias)));
+		}
+	}
 
-	return contexts.map((context) => {
-		const params = context ? replaceParam(defaultParams, "context", context) : defaultParams;
-		const piModelId = encodePiModelId(item.id, context);
-		const metadata = toMetadata(item, piModelId, params, context);
-		metadataByPiModelId.set(piModelId, metadata);
-		return toModelConfig(metadata, getModelName(item, context));
-	});
+	return configs;
 }
 
 function sortModelsByBaseId(items: ModelListItem[]): ModelListItem[] {
@@ -420,7 +446,9 @@ function sortModelsByBaseId(items: ModelListItem[]): ModelListItem[] {
 
 function registerModelItems(items: ModelListItem[]): ProviderModelConfig[] {
 	metadataByPiModelId.clear();
-	return sortModelsByBaseId(items).flatMap(toModelConfigs);
+	const usedPiModelIds = new Set<string>();
+	const reservedBaseModelIds = new Set(items.map((item) => item.id));
+	return sortModelsByBaseId(items).flatMap((item) => toModelConfigs(item, usedPiModelIds, reservedBaseModelIds));
 }
 
 export function getCursorModelMetadata(modelId: string): CursorModelMetadata | undefined {
@@ -501,7 +529,7 @@ export function buildCursorModelSelection(
 		setParam(params, "fast", fastEnabled ? "true" : "false");
 	}
 
-	return params.length > 0 ? { id: metadata.baseModelId, params } : { id: metadata.baseModelId };
+	return params.length > 0 ? { id: metadata.selectionModelId, params } : { id: metadata.selectionModelId };
 }
 
 function useFallbackModels(options: DiscoverModelsOptions, issue: CursorModelFallbackIssue): ProviderModelConfig[] {