pi-cursor-sdk 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## Unreleased
+## 0.1.9 - 2026-05-14
+
+### Fixed
+
+- Clean up recorded native Cursor tool replay outputs when abandoned replay runs are disposed, avoiding retained file or command output in process memory.
+- Restore `/cursor-fast` state when session persistence fails during command handling.
+- Preserve distinct same-payload Cursor tool completions while deduplicating duplicate SDK completion surfaces.
+- Respect exact `model@context` context-window cache overrides before falling back to parsed base-model context values.
+- Emit native replay text block endings with saved content indexes instead of searching by object identity.
+- Redact discovery failure details with the same secret patterns used for stream errors.
+
+### Changed
+
+- Update fallback Sonnet 4.6 context variants from `300k` to the current `200k` catalog variant.
+- Skip ambiguous Cursor SDK aliases shared by multiple base models or colliding with base model IDs, preventing misleading pi model rows.
+- Reduce context-window cache reloads during model catalog registration.
+- Document image carry-forward as a product decision rather than silently changing current latest-user-message image forwarding behavior.
+
+## 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
+- unambiguous latest-style Cursor aliases returned by `Cursor.models.list()` are registered too, using the same context suffixes when the target model has context variants; aliases shared by multiple base models or colliding with a base model ID are skipped because their SDK resolution and displayed metadata can diverge
 
 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
 
@@ -202,7 +203,7 @@ If no key is available from `/login`, `CURSOR_API_KEY`, or `--api-key`, model di
 
 - `composer-2`
 - `gpt-5.5@1m`, `gpt-5.5@272k`
-- `claude-sonnet-4-6@1m`, `claude-sonnet-4-6@300k`
+- `claude-sonnet-4-6@1m`, `claude-sonnet-4-6@200k`
 - `claude-opus-4-7@1m`, `claude-opus-4-7@300k`
 
 Fallback models are a conservative startup model list. Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-key`. If you add auth after startup, run `/reload` or restart pi to refresh the full live Cursor model catalog.
@@ -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

@@ -13,6 +13,7 @@ Current implementation notes:
 - Cursor `fast` is extension state, not model identity.
 - Cursor fast status uses `ctx.ui.setStatus()`; 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`.
+- Product decision pending: image payload forwarding currently sends images only from the latest user message. If the latest user turn is plain text after an earlier image turn, the transcript keeps an `[image omitted from transcript]` placeholder but no image bytes are sent to Cursor. Changing this to carry images forward across turns requires a deliberate product decision about token cost, privacy, stale visual context, and expected multimodal follow-up behavior.
 - `@cursor/sdk` is a package dependency of this extension; users should not need a global SDK install.
 - Cursor auth uses pi-native API-key resolution for provider `cursor`: CLI `--api-key`, stored `~/.pi/agent/auth.json` API key from `/login`, then `CURSOR_API_KEY`. The extension config file stores only non-secret Cursor-only state such as fast defaults.
 - Local agents do not pass `settingSources` by default because the current Cursor SDK writes setting/rule loading INFO logs directly to terminal output, which corrupts pi's TUI.
@@ -20,7 +21,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 only unambiguous 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`. Aliases shared by multiple base models, such as generic family aliases, are skipped because the pi row metadata would otherwise imply one base model while Cursor may resolve the alias to another.
 
 ## Goal
 
@@ -69,6 +71,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 +138,9 @@ 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 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`, 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 +181,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 +190,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
 
@@ -484,42 +488,22 @@ Fast flag example:
 pi --model cursor/gpt-5.5@1m --cursor-fast -p "Say ok only"
 ```
 
-## Current Discovered Model Capability Examples
+## Discovered Model Capability Examples
 
-Current live Cursor data says:
+These examples document the capability shapes the extension handles, not an exhaustive live catalog. The exact Cursor catalog changes over time; use `pi -e . --list-models cursor` or `Cursor.models.list()` for the current model surface. When the SDK reports aliases, only unambiguous aliases are registered; shared generic aliases are skipped.
 
-| Model | Cursor controls | Pi representation |
+| Example model shape | Cursor controls | Pi representation |
 |---|---|---|
-| `default` | none | plain model |
-| `composer-2` | fast | plain model + fast extension state |
-| `composer-1.5` | none | plain model |
-| `gpt-5.5` | context, reasoning, fast | context variants + native thinking + fast state |
-| `gpt-5.4` | context, reasoning, fast | context variants + native thinking + fast state |
-| `gpt-5.4-mini` | reasoning | plain model + native thinking |
-| `gpt-5.4-nano` | reasoning | plain model + native thinking |
-| `gpt-5.3-codex` | reasoning, fast | plain model + native thinking + fast state |
-| `gpt-5.3-codex-spark` | reasoning | plain model + native thinking |
-| `gpt-5.2` | reasoning, fast | plain model + native thinking + fast state |
-| `gpt-5.2-codex` | reasoning, fast | plain model + native thinking + fast state |
-| `gpt-5.1-codex-max` | reasoning, fast | plain model + native thinking + fast state |
-| `gpt-5.1-codex-mini` | reasoning | plain model + native thinking |
-| `gpt-5.1` | reasoning | plain model + native thinking |
-| `claude-opus-4-7` | thinking, context, effort | context variants + native thinking |
-| `claude-opus-4-6` | thinking, context, effort, fast | context variants + native thinking + fast state |
-| `claude-opus-4-5` | thinking | plain model + native thinking |
-| `claude-sonnet-4-6` | thinking, context, effort | context variants + native thinking |
-| `claude-sonnet-4-5` | thinking, context | context-qualified model + native thinking |
-| `claude-sonnet-4` | thinking, context | context-qualified model + native thinking |
-| `claude-haiku-4-5` | thinking | plain model + native thinking |
-| `grok-4.3` | context | context variants |
-| `grok-4-20` | thinking | plain model + native thinking |
-| `gemini-3.1-pro` | none | plain model |
-| `gemini-3-flash` | none | plain model |
-| `gemini-2.5-flash` | none | plain model |
-| `gpt-5-mini` | none | plain model |
-| `kimi-k2.5` | none | plain model |
-
-If Cursor later adds `fast`, `context`, `reasoning`, or `effort` to a model, the extension picks it up dynamically.
+| plain model, such as `default` or models with no exposed controls | none | plain model |
+| `composer-2`-style model | fast | plain model + fast extension state |
+| GPT-style reasoning model with context variants | context, reasoning, fast when exposed | context variants + native thinking + optional fast state |
+| Claude-style thinking model with context variants | thinking, context, effort when exposed | context variants + native thinking + optional fast state |
+| Claude-style thinking model without context variants | thinking and/or effort | plain model + native thinking |
+| context-only model | context | context variants |
+| unique latest alias for any shape | aliases | same pi rows as the base model shape, using the alias as `ModelSelection.id` |
+| shared generic alias across multiple base models | aliases | skipped to avoid misleading pi rows |
+
+If Cursor later adds `fast`, `context`, `reasoning`, `effort`, or aliases to a model, the extension picks up unambiguous capability changes dynamically.
 
 ## Detailed Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"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

@@ -4,6 +4,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { BUNDLED_CONTEXT_WINDOWS } from "./bundled-context-windows.js";
 
 const CONTEXT_WINDOW_CACHE_FILE = "cursor-sdk-context-windows.json";
+let userContextWindowOverrideLoadCount = 0;
 
 interface ContextWindowCacheFile {
 	contextWindows?: Record<string, number>;
@@ -18,6 +19,7 @@ function isPositiveInteger(value: unknown): value is number {
 }
 
 function loadUserContextWindowOverrides(): Map<string, number> {
+	userContextWindowOverrideLoadCount += 1;
 	const path = getCachePath();
 	const overrides = new Map<string, number>();
 	if (!existsSync(path)) return overrides;
@@ -40,6 +42,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");
@@ -76,4 +82,8 @@ export function saveCachedContextWindow(modelId: string, contextWindow: number):
 
 export const __testUtils = {
 	getCachePath,
+	getUserContextWindowOverrideLoadCount: () => userContextWindowOverrideLoadCount,
+	resetUserContextWindowOverrideLoadCount: () => {
+		userContextWindowOverrideLoadCount = 0;
+	},
 };

package/src/cursor-native-tool-display.ts

@@ -56,9 +56,14 @@ export function canRenderCursorToolNatively(toolName: string): boolean {
 	return isNativeCursorToolName(toolName) && registeredNativeToolNames.has(toolName);
 }
 
-export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): void {
-	if (!canRenderCursorToolNatively(item.toolName)) return;
+export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): boolean {
+	if (!canRenderCursorToolNatively(item.toolName)) return false;
 	nativeToolResults.set(item.id, item);
+	return true;
+}
+
+export function deleteCursorNativeToolDisplay(id: string): void {
+	nativeToolResults.delete(id);
 }
 
 function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem | undefined {
@@ -68,6 +73,7 @@ function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem
 }
 
 export const __testUtils = {
+	nativeToolResultCount: () => nativeToolResults.size,
 	reset(): void {
 		registeredNativeToolNames.clear();
 		nativeToolResults.clear();

package/src/cursor-provider.ts

@@ -17,6 +17,7 @@ import { buildCursorPiToolDisplay, formatCursorToolTranscript, mergeCursorToolCa
 import {
 	canRenderCursorToolNatively,
 	isCursorNativeToolDisplayRuntimeEnabled,
+	deleteCursorNativeToolDisplay,
 	recordCursorNativeToolDisplay,
 	type CursorNativeToolDisplayItem,
 } from "./cursor-native-tool-display.js";
@@ -58,6 +59,7 @@ const AUTH_CURSOR_SDK_ERROR_MESSAGE =
 const APPROX_CHARS_PER_TOKEN = 4;
 const IMAGE_TOKEN_ESTIMATE = 1200;
 const CURSOR_ACTIVITY_TRACE_MAX_CHARS = 50000;
+const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
 const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
 
 type CursorNativeQueuedEvent =
@@ -73,10 +75,13 @@ interface CursorNativeLiveRun {
 	promptInputTokensReported: boolean;
 	pendingEvents: CursorNativeQueuedEvent[];
 	textDeltas: string[];
+	recordedToolDisplayIds: string[];
 	finalText?: string;
 	done: boolean;
 	cancelled: boolean;
+	disposed: boolean;
 	errorMessage?: string;
+	idleDisposeTimer?: ReturnType<typeof setTimeout>;
 	waiters: Set<() => void>;
 }
 
@@ -88,6 +93,7 @@ interface CursorNativeTurnState {
 }
 
 let cursorNativeReplayCounter = 0;
+let cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
 const pendingCursorNativeRuns = new Map<string, CursorNativeLiveRun>();
 
 function escapeRegExp(value: string): string {
@@ -264,6 +270,21 @@ function queueCursorNativeEvent(run: CursorNativeLiveRun, event: CursorNativeQue
 	notifyCursorNativeRun(run);
 }
 
+function clearCursorNativeRunIdleDispose(run: CursorNativeLiveRun): void {
+	if (!run.idleDisposeTimer) return;
+	clearTimeout(run.idleDisposeTimer);
+	run.idleDisposeTimer = undefined;
+}
+
+function scheduleCursorNativeRunIdleDispose(run: CursorNativeLiveRun): void {
+	if (run.disposed) return;
+	clearCursorNativeRunIdleDispose(run);
+	run.idleDisposeTimer = setTimeout(() => {
+		void disposeCursorNativeRun(run);
+	}, cursorNativeReplayIdleDisposeMs);
+	run.idleDisposeTimer.unref?.();
+}
+
 function isCursorNativeRunReady(run: CursorNativeLiveRun): boolean {
 	return run.pendingEvents.length > 0 || run.done || run.cancelled || run.errorMessage !== undefined;
 }
@@ -310,12 +331,13 @@ function closeCursorNativeThinkingBlock(turn: CursorNativeTurnState): void {
 
 function closeCursorNativeTextBlock(turn: CursorNativeTurnState): string {
 	if (turn.textContentIndex < 0) return "";
-	const block = turn.partial.content[turn.textContentIndex];
+	const contentIndex = turn.textContentIndex;
+	const block = turn.partial.content[contentIndex];
 	turn.textContentIndex = -1;
 	if (block.type !== "text") return "";
 	turn.stream.push({
 		type: "text_end",
-		contentIndex: turn.partial.content.indexOf(block),
+		contentIndex,
 		content: block.text,
 		partial: turn.partial,
 	});
@@ -402,15 +424,24 @@ function emitCursorNativeToolUseTurn(
 		stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(tool.args), partial });
 		const block = partial.content[contentIndex];
 		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
-		recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate });
+		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate })) {
+			run.recordedToolDisplayIds.push(tool.id);
+		}
 	}
 	setApproximateUsage(partial, takeCursorNativePromptInputTokens(run), outputText);
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
+	scheduleCursorNativeRunIdleDispose(run);
 }
 
 async function disposeCursorNativeRun(run: CursorNativeLiveRun): Promise<void> {
+	if (run.disposed) return;
+	run.disposed = true;
 	pendingCursorNativeRuns.delete(run.id);
+	clearCursorNativeRunIdleDispose(run);
+	for (const toolDisplayId of run.recordedToolDisplayIds) deleteCursorNativeToolDisplay(toolDisplayId);
+	run.recordedToolDisplayIds = [];
+	run.waiters.clear();
 	try {
 		await run.agent[Symbol.asyncDispose]();
 	} catch {
@@ -484,7 +515,13 @@ async function replayPendingCursorNativeRun(
 	if (!replayId) return false;
 	const run = pendingCursorNativeRuns.get(replayId);
 	if (!run) return false;
-	await emitCursorNativeRunNextTurn(stream, partial, run, signal);
+	clearCursorNativeRunIdleDispose(run);
+	try {
+		await emitCursorNativeRunNextTurn(stream, partial, run, signal);
+	} catch (error) {
+		if (error instanceof CursorAbortError) await disposeCursorNativeRun(run);
+		throw error;
+	}
 	return true;
 }
 
@@ -498,6 +535,7 @@ export function streamCursor(
 	(async () => {
 		const partial = makeInitialMessage(model);
 		let agent: SDKAgent | null = null;
+		let activeNativeRun: CursorNativeLiveRun | undefined;
 		let resolvedApiKey: string | undefined;
 		let abortSignal: AbortSignal | undefined;
 		let abortListener: (() => void) | undefined;
@@ -551,14 +589,21 @@ export function streamCursor(
 						promptInputTokensReported: false,
 						pendingEvents: [],
 						textDeltas,
+						recordedToolDisplayIds: [],
 						done: false,
 						cancelled: false,
+						disposed: false,
 						waiters: new Set(),
 					}
 				: undefined;
-			if (liveRun) pendingCursorNativeRuns.set(liveRun.id, liveRun);
+			if (liveRun) {
+				pendingCursorNativeRuns.set(liveRun.id, liveRun);
+				activeNativeRun = liveRun;
+			}
 			const startedToolCalls = new Map<string, unknown>();
-			const completedToolFingerprints = new Set<string>();
+			const completedToolIdentities = new Set<string>();
+			const completedStartedToolFingerprints = new Set<string>();
+			const completedFallbackToolFingerprints = new Set<string>();
 
 			const appendLiveTextDelta = (text: string): void => {
 				if (textContentIndex < 0) {
@@ -652,12 +697,25 @@ export function streamCursor(
 				}
 			};
 
-			const handleCompletedToolCall = (toolCall: unknown): void => {
+			const handleCompletedToolCall = (
+				toolCall: unknown,
+				options: { identity?: string; source?: "started" | "fallback" } = {},
+			): void => {
 				const transcript = scrubSensitiveText(formatCursorToolTranscript(toolCall, { cwd }), resolvedApiKey);
 				const display = buildCursorPiToolDisplay(toolCall, { cwd });
 				const fingerprint = getToolFingerprint({ toolName: display.toolName, args: display.args, result: display.result });
-				if (completedToolFingerprints.has(fingerprint)) return;
-				completedToolFingerprints.add(fingerprint);
+				if (options.identity && completedToolIdentities.has(options.identity)) return;
+				if (options.source === "started") {
+					if (completedFallbackToolFingerprints.has(fingerprint)) return;
+				} else if (completedStartedToolFingerprints.has(fingerprint) || completedFallbackToolFingerprints.has(fingerprint)) {
+					return;
+				}
+				if (options.identity) completedToolIdentities.add(options.identity);
+				if (options.source === "started") {
+					completedStartedToolFingerprints.add(fingerprint);
+				} else {
+					completedFallbackToolFingerprints.add(fingerprint);
+				}
 
 				if (useNativeToolReplay && canRenderCursorToolNatively(display.toolName) && liveRun) {
 					nativeToolReplayStarted = true;
@@ -704,7 +762,11 @@ export function streamCursor(
 				} else if (update.type === "tool-call-completed") {
 					const mergedToolCall = mergeCursorToolCalls(startedToolCalls.get(update.callId), update.toolCall);
 					startedToolCalls.delete(update.callId);
-					handleCompletedToolCall(mergedToolCall);
+					const identity = typeof update.callId === "string" ? `cursor-tool:${update.callId}` : undefined;
+					handleCompletedToolCall(mergedToolCall, {
+						identity,
+						source: identity ? "started" : "fallback",
+					});
 				} else if (update.type === "summary") {
 					const summary = `Cursor summary: ${truncateSingleLine(update.summary)}\n`;
 					if (liveRun && nativeToolReplayStarted) {
@@ -723,7 +785,12 @@ export function streamCursor(
 				const step = getObjectField(args.step, "message") ? args.step : undefined;
 				if (getObjectField(args.step, "type") !== "toolCall") return;
 				const toolCall = getObjectField(step, "message");
-				if (toolCall) handleCompletedToolCall(toolCall);
+				const stepId = getObjectField(args.step, "id") ?? getObjectField(toolCall, "id") ?? getObjectField(toolCall, "callId");
+				if (toolCall) {
+					handleCompletedToolCall(toolCall, {
+						identity: typeof stepId === "string" ? `cursor-tool:${stepId}` : undefined,
+					});
+				}
 			};
 
 			// Handle abort signal
@@ -750,21 +817,31 @@ export function streamCursor(
 				void run
 					.wait()
 					.then(async (result) => {
+						if (liveRun.disposed) return;
 						await cacheSdkContextWindow(liveRun.agent.agentId, model.id);
+						if (liveRun.disposed) return;
 						liveRun.cancelled = result.status === "cancelled";
 						liveRun.finalText = hasUsableText(result.result) ? result.result : liveRun.textDeltas.join("");
 						liveRun.done = true;
 						notifyCursorNativeRun(liveRun);
+						scheduleCursorNativeRunIdleDispose(liveRun);
 					})
 					.catch((error: unknown) => {
+						if (liveRun.disposed) return;
 						liveRun.errorMessage = sanitizeError(error, resolvedApiKey ?? options?.apiKey);
 						notifyCursorNativeRun(liveRun);
+						scheduleCursorNativeRunIdleDispose(liveRun);
 					});
 
-				await waitForCursorNativeRunProgress(liveRun, options?.signal);
-				await settleCursorNativeToolBatch(liveRun);
-				closeTraceBlock();
-				await emitCursorNativeRunNextTurn(stream, partial, liveRun, options?.signal);
+				try {
+					await waitForCursorNativeRunProgress(liveRun, options?.signal);
+					await settleCursorNativeToolBatch(liveRun);
+					closeTraceBlock();
+					await emitCursorNativeRunNextTurn(stream, partial, liveRun, options?.signal);
+				} catch (error) {
+					if (error instanceof CursorAbortError) await disposeCursorNativeRun(liveRun);
+					throw error;
+				}
 				agent = null;
 				return;
 			}
@@ -794,6 +871,8 @@ export function streamCursor(
 				stream.push({ type: "error", reason: "error", error: partial });
 			}
 		} finally {
+			if (activeNativeRun?.disposed) agent = null;
+
 			if (abortSignal && abortListener) {
 				abortSignal.removeEventListener("abort", abortListener);
 			}
@@ -813,3 +892,14 @@ export function streamCursor(
 
 	return stream;
 }
+
+export const __testUtils = {
+	DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS,
+	pendingCursorNativeRunCount: () => pendingCursorNativeRuns.size,
+	setCursorNativeReplayIdleDisposeMs: (value: number) => {
+		cursorNativeReplayIdleDisposeMs = value;
+	},
+	resetCursorNativeReplayIdleDisposeMs: () => {
+		cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+	},
+};

package/src/cursor-state.ts

@@ -105,16 +105,25 @@ function restoreMapValue(map: Map<string, boolean>, key: string, previous: boole
 function persistFastPreference(pi: ExtensionAPI, baseModelId: string, fast: boolean): void {
 	const previousSession = sessionFastPreferences.get(baseModelId);
 	const previousGlobal = globalFastPreferences.get(baseModelId);
+	let savedGlobal = false;
 	sessionFastPreferences.set(baseModelId, fast);
 	globalFastPreferences.set(baseModelId, fast);
 	try {
 		saveGlobalFastPreferences();
+		savedGlobal = true;
+		pi.appendEntry<CursorFastEntryData>(FAST_ENTRY_TYPE, { baseModelId, fast });
 	} catch (error) {
 		restoreMapValue(sessionFastPreferences, baseModelId, previousSession);
 		restoreMapValue(globalFastPreferences, baseModelId, previousGlobal);
+		if (savedGlobal) {
+			try {
+				saveGlobalFastPreferences();
+			} catch {
+				// Preserve the original append failure reported to the user.
+			}
+		}
 		throw error;
 	}
-	pi.appendEntry<CursorFastEntryData>(FAST_ENTRY_TYPE, { baseModelId, fast });
 }
 
 export function getEffectiveFastForModelId(modelId: string): boolean | undefined {

package/src/cursor-tool-transcript.ts

@@ -281,15 +281,18 @@ function renderTreeNode(node: unknown, depth = 0, lines: string[] = []): string[
 	return lines;
 }
 
-function formatLs(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
-	const path = formatPathArg(args, options) ?? ".";
-	if (result.status === "error") return joinSections(`ls ${path}`, formatError(result.error));
-
+function getLsBody(result: NormalizedResult, options: TranscriptOptions): string {
 	const value = asRecord(result.value);
 	const root = value?.directoryTreeRoot ?? result.value;
 	const treeLines = renderTreeNode(root);
 	const body = treeLines.length > 0 ? treeLines.join("\n") : stringifyUnknown(result.value);
-	return joinSections(`ls ${path}`, limitText(body, options));
+	return limitText(body, options);
+}
+
+function formatLs(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
+	const path = formatPathArg(args, options) ?? ".";
+	if (result.status === "error") return joinSections(`ls ${path}`, formatError(result.error));
+	return joinSections(`ls ${path}`, getLsBody(result, options));
 }
 
 function formatGlob(args: Record<string, unknown>, result: NormalizedResult, options: TranscriptOptions): string {
@@ -528,7 +531,7 @@ export function buildCursorPiToolDisplay(toolCall: unknown, options: TranscriptO
 		return {
 			toolName: "ls",
 			args,
-			result: textToolResult(result.status === "error" ? formatError(result.error) : formatLs(args, result, options).split("\n\n").slice(1).join("\n\n").trim()),
+			result: textToolResult(result.status === "error" ? formatError(result.error) : getLsBody(result, options).trim()),
 			isError: result.status === "error",
 		};
 	}

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 { loadContextWindowCache } from "./context-window-cache.js";
 
 const CURSOR_PROVIDER_ID = "cursor";
 const CURSOR_API_KEY_ENV_VAR = "CURSOR_API_KEY";
@@ -88,7 +88,7 @@ const FALLBACK_MODEL_ITEMS: ModelListItem[] = [
 			{
 				id: "context",
 				displayName: "Context",
-				values: [{ value: "1m" }, { value: "300k" }],
+				values: [{ value: "1m" }, { value: "200k" }],
 			},
 			{
 				id: "effort",
@@ -165,6 +165,7 @@ export type CursorModelFallbackReason = "missing-api-key" | "discovery-failed" |
 export interface CursorModelFallbackIssue {
 	reason: CursorModelFallbackReason;
 	message: string;
+	errorMessage?: string;
 }
 
 export interface DiscoverModelsOptions {
@@ -217,6 +218,7 @@ async function getDiscoveryApiKey(): Promise<string | undefined> {
 export interface CursorModelMetadata {
 	piModelId: string;
 	baseModelId: string;
+	selectionModelId: string;
 	displayName: string;
 	defaultParams: ModelParameterValue[];
 	context?: string;
@@ -340,35 +342,44 @@ 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 {
-	if (context) return parseContextWindow(context) ?? FALLBACK_CONTEXT_WINDOW;
-	return getCachedContextWindow(piModelId) ?? FALLBACK_CONTEXT_WINDOW;
+function getContextWindow(contextWindowCache: Map<string, number>, piModelId: string, context?: string, baseModelId?: string): number {
+	return (
+		contextWindowCache.get(piModelId) ??
+		(context ? parseContextWindow(context) : undefined) ??
+		(baseModelId ? contextWindowCache.get(baseModelId) : undefined) ??
+		contextWindowCache.get("default") ??
+		FALLBACK_CONTEXT_WINDOW
+	);
 }
 
 function toMetadata(
 	item: ModelListItem,
 	piModelId: string,
+	selectionModelId: string,
 	defaultParams: ModelParameterValue[],
 	context: string | undefined,
+	contextWindowCache: Map<string, number>,
 ): CursorModelMetadata {
 	const thinkingLevelMap = getThinkingLevelMap(item);
 	const fastValue = getParamValue(defaultParams, "fast")?.toLowerCase();
 	return {
 		piModelId,
 		baseModelId: item.id,
+		selectionModelId,
 		displayName: item.displayName || item.id,
 		defaultParams: cloneParams(defaultParams),
 		...(context ? { context } : {}),
-		contextWindow: getContextWindow(piModelId, context),
+		contextWindow: getContextWindow(contextWindowCache, piModelId, context, item.id),
 		supportsFast: getParameter(item, "fast") !== undefined,
 		defaultFast: fastValue === "true",
 		supportsReasoning: thinkingLevelMap !== undefined,
@@ -400,18 +411,56 @@ function getContextValues(item: ModelListItem): string[] {
 	return getParameter(item, "context")?.values.map((value) => value.value) ?? [];
 }
 
-function toModelConfigs(item: ModelListItem): ProviderModelConfig[] {
+function getAmbiguousAliases(items: ModelListItem[]): Set<string> {
+	const aliasOwners = new Map<string, Set<string>>();
+	for (const item of items) {
+		for (const rawAlias of item.aliases ?? []) {
+			const alias = rawAlias.trim();
+			if (!alias || alias === item.id) continue;
+			const owners = aliasOwners.get(alias) ?? new Set<string>();
+			owners.add(item.id);
+			aliasOwners.set(alias, owners);
+		}
+	}
+	return new Set([...aliasOwners.entries()].filter(([, owners]) => owners.size > 1).map(([alias]) => alias));
+}
+
+function getModelIds(item: ModelListItem, reservedBaseModelIds: Set<string>, ambiguousAliases: 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) || ambiguousAliases.has(alias)) continue;
+		ids.push(alias);
+	}
+	return ids;
+}
+
+function toModelConfigs(
+	item: ModelListItem,
+	usedPiModelIds: Set<string>,
+	reservedBaseModelIds: Set<string>,
+	ambiguousAliases: Set<string>,
+	contextWindowCache: Map<string, number>,
+): 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, 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)));
+		}
+	}
 
-	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 +469,11 @@ 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));
+	const ambiguousAliases = getAmbiguousAliases(items);
+	const contextWindowCache = loadContextWindowCache();
+	return sortModelsByBaseId(items).flatMap((item) => toModelConfigs(item, usedPiModelIds, reservedBaseModelIds, ambiguousAliases, contextWindowCache));
 }
 
 export function getCursorModelMetadata(modelId: string): CursorModelMetadata | undefined {
@@ -501,7 +554,25 @@ 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 scrubDiscoveryErrorText(text: string, apiKey: string): string {
+	let scrubbed = text.replace(new RegExp(apiKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"), "[redacted]");
+	return scrubbed
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
+		.replace(/((?:^|[\s,{])cookie["']?\s*[:=]\s*["']?)[^\n]+/gi, "$1[redacted]")
+		.replace(
+			/((?:authorization|api[_-]?key|apiKey|token|session(?:[_-]?id)?)["']?\s*[:=]\s*["']?)[^"'\s,;}]+/gi,
+			"$1[redacted]",
+		)
+		.trim();
+}
+
+function sanitizeDiscoveryError(error: unknown, apiKey: string): string | undefined {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	const scrubbed = scrubDiscoveryErrorText(message, apiKey);
+	return scrubbed || undefined;
 }
 
 function useFallbackModels(options: DiscoverModelsOptions, issue: CursorModelFallbackIssue): ProviderModelConfig[] {
@@ -527,10 +598,12 @@ export async function discoverModels(options: DiscoverModelsOptions = {}): Promi
 			reason: "empty-model-list",
 			message: `Cursor model discovery returned no models. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
 		});
-	} catch {
+	} catch (error) {
+		const errorMessage = sanitizeDiscoveryError(error, apiKey);
 		return useFallbackModels(options, {
 			reason: "discovery-failed",
-			message: `Cursor model discovery failed. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
+			message: `Cursor model discovery failed${errorMessage ? `: ${errorMessage}` : ""}. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,
+			...(errorMessage ? { errorMessage } : {}),
 		});
 	}
 }