pi-cursor-sdk 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.1.10 - 2026-05-15
+
+### Added
+
+- Replay Cursor SDK `edit` and `write` activity through native pi tool-use turns using non-mutating `cursor_edit` and `cursor_write` cards, so Cursor file changes are visible as first-class tool activity without shadowing pi's built-in `edit` and `write` schemas.
+- Add a maintainer `npm run refresh:cursor-snapshots` workflow for refreshing the reviewable Cursor fallback model catalog and optional checkpoint-derived context-window snapshot before releases.
+
+### Changed
+
+- Improve Cursor edit/write replay card UX with concise created/updated/deleted/unchanged summaries and expanded colored diffs.
+- Clarify image follow-up behavior: only latest user-message image bytes are forwarded; earlier images remain transcript placeholders and should be reattached or described.
+- Allow `/cursor-refresh-models` to refresh the live Cursor model catalog after auth changes without restarting pi.
+- Label local read fallback previews as transcript-time local previews when Cursor read result content is unavailable.
+
+### Fixed
+
+- Prevent local read fallback previews from escaping the workspace through symlinks and from bypassing sensitive-path checks through sensitive symlink names.
+- Budget oversized prompt history before `Agent.send`, including image-token reservations, while preserving system/tool-boundary instructions and the latest user request.
+- Preserve assistant text emitted before native Cursor tool replay.
+- Use the pi session cwd for native replay tool registration and update fallback execution to the latest session cwd.
+
+## 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

package/README.md

@@ -26,7 +26,7 @@ pi --model cursor/composer-2
 
 3. In pi, run `/login`, choose `Use an API key`, choose `Cursor`, and paste your Cursor API key.
 
-If pi started without a key, run `/reload` or restart pi after `/login` to refresh the full live Cursor model catalog. Inside pi, use `/model` to choose another Cursor model.
+If pi started without a key, run `/cursor-refresh-models` after `/login` to refresh the full live Cursor model catalog without restarting pi. Inside pi, use `/model` to choose another Cursor model.
 
 ## Requirements
 
@@ -83,7 +83,7 @@ Then, inside pi:
 4. Paste your Cursor API key.
 5. The key is saved in pi's native `~/.pi/agent/auth.json`.
 
-If pi started without a key, fallback Cursor models still register so `/login` is reachable. After `/login`, fallback model runs can use the stored key, but `/reload` or a restart is needed to refresh the full live Cursor model catalog discovered from the Cursor SDK.
+If pi started without a key, fallback Cursor models still register so `/login` is reachable. After `/login`, fallback model runs can use the stored key, and `/cursor-refresh-models` refreshes the full live Cursor model catalog discovered from the Cursor SDK without restarting pi.
 
 Environment setup:
 
@@ -113,7 +113,7 @@ pi --list-models cursor
 Expected behavior:
 
 - with a valid key, Cursor models appear under the `cursor` provider
-- if discovery cannot authenticate or reach Cursor, pi may still show fallback Cursor models; after adding auth with `/login`, fallback model runs can use the saved key, and `/reload` or restart refreshes the live catalog
+- if discovery cannot authenticate or reach Cursor, pi may still show fallback Cursor models; after adding auth with `/login`, fallback model runs can use the saved key, and `/cursor-refresh-models` refreshes the live catalog
 
 Smoke test:
 
@@ -137,7 +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
+- 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:
 
@@ -195,7 +195,7 @@ If you do not see `cursor fast`, fast mode is off.
 
 ## Images
 
-Images from the latest user message are forwarded to Cursor. Historical images are kept out of the transcript. The extension advertises `text` and `image` input for Cursor models because Cursor's SDK accepts image messages and Cursor models are expected to support them.
+Images from the latest user message are forwarded to Cursor. Historical images are kept out of the transcript and appear only as `[image omitted from transcript]` placeholders, so follow-up questions about an earlier image should reattach the image or include a textual description. The extension advertises `text` and `image` input for Cursor models because Cursor's SDK accepts image messages and Cursor models are expected to support them.
 
 ## Fallback models
 
@@ -203,18 +203,18 @@ 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.
+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 `/cursor-refresh-models` to refresh the full live Cursor model catalog without restarting pi.
 
 ## Limits
 
 - **Local Cursor SDK agents only.** This extension does not use Cursor cloud agents.
-- **Cursor-side tool use is not re-executed by pi.** Cursor still uses its own internal SDK tools. The extension records completed Cursor tool activity and, in interactive TTY sessions, replays supported `read`, `bash`, and `ls` activity through pi's native tool-call path with recorded results (for example green `read` and `$ ...` cards) without forcing Cursor to call pi tools or rerun commands. Native replay wrappers are registered only for tool names not already owned by another extension; skipped tools fall back to the scrubbed Cursor activity transcript. As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results immediately, then continuing with live post-tool Cursor thinking/text, any later Cursor tool batches, or Cursor's final answer as the next assistant turn. Non-interactive/session consumers still get bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
+- **Cursor-side tool use is not re-executed by pi.** Cursor still uses its own internal SDK tools. The extension records completed Cursor tool activity and, in interactive TTY sessions, replays supported `read`, `bash`, `ls`, `edit`, and `write` activity through pi's native tool-call path with recorded results (for example green `read`, `$ ...`, and Cursor edit/write cards) without forcing Cursor to call pi tools or rerun commands. Cursor edit/write activity uses replay-only `cursor_edit` and `cursor_write` tool cards because Cursor's file-editing schema is not the same as pi's built-in `edit`/`write` schemas; those replay tools only display recorded Cursor results and never mutate files directly. If a Cursor read completion reports no content, the extension may include a bounded local file preview for safe in-workspace paths; that preview is explicitly labeled as a local preview captured at transcript time, not guaranteed Cursor-observed content. Native replay wrappers are registered only for tool names not already owned by another extension; skipped tools fall back to the scrubbed Cursor activity transcript. As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results immediately, then continuing with live post-tool Cursor thinking/text, any later Cursor tool batches, or Cursor's final answer as the next assistant turn. Non-interactive/session consumers still get bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
 - **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.
+- **Cursor setting sources are opt-in.** The extension does not pass `local.settingSources` by default because the Cursor SDK can print settings/skills loading output directly to the terminal during startup. To load configured Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities, start pi with `PI_CURSOR_SETTING_SOURCES=all`. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`.
 - **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.
@@ -223,7 +223,7 @@ Fallback models are a conservative startup model list. Actual Cursor runs still
 
 ### I can see Cursor models, but runs fail
 
-You may be seeing fallback startup models or a missing/invalid key. In interactive pi, run `/login`, choose `Use an API key`, choose `Cursor`, paste the key, then run `/reload` or restart pi.
+You may be seeing fallback startup models or a missing/invalid key. In interactive pi, run `/login`, choose `Use an API key`, choose `Cursor`, paste the key, then run `/cursor-refresh-models`.
 
 You can also restart pi with a key in the same shell or launcher that starts pi:
 
@@ -262,11 +262,15 @@ Fast mode is currently off. The footer only shows `cursor fast` when fast mode i
 
 ### My Cursor app settings or rules do not seem to apply
 
-They are not loaded by default in this extension. See [Limits](#limits).
+Cursor setting sources are not loaded by default because the Cursor SDK can print settings/skills loading output directly to the terminal. Start pi with `PI_CURSOR_SETTING_SOURCES=all`, or choose a narrower list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`.
+
+### Cursor does not call my web search MCP/tool
+
+Cursor SDK local agents load MCP servers from Cursor setting sources and inline SDK config. This extension leaves Cursor setting sources off by default to avoid startup log noise, so a web search tool needs to be configured in Cursor and settings sources need to be enabled with `PI_CURSOR_SETTING_SOURCES=all` or a narrower list.
 
 ### Cursor native tool cards conflict with another extension
 
-Cursor native replay is a UI enhancement for interactive TTY sessions. If another extension already owns `read`, `bash`, or `ls`, this extension skips only the conflicting native replay wrapper and uses the scrubbed Cursor activity transcript for that tool instead. To disable Cursor native replay registration entirely, start pi with:
+Cursor native replay is a UI enhancement for interactive TTY sessions. If another extension already owns `read`, `bash`, `ls`, `cursor_edit`, or `cursor_write`, this extension skips only the conflicting native replay wrapper and uses the scrubbed Cursor activity transcript for that tool instead. To disable Cursor native replay registration entirely, start pi with:
 
 ```bash
 PI_CURSOR_NATIVE_TOOL_DISPLAY=0 pi --model cursor/composer-2
@@ -283,6 +287,21 @@ npm test
 npm run typecheck
 ```
 
+Refresh the reviewable Cursor fallback catalog before releases or after Cursor model changes:
+
+```bash
+CURSOR_API_KEY="your-key" npm run refresh:cursor-snapshots -- --write
+```
+
+Refresh the bundled default/non-Max context-window snapshot only when checkpoint-derived context windows have been collected from live local runs:
+
+```bash
+CURSOR_API_KEY="your-key" npm run refresh:cursor-snapshots -- --write \
+  --context-windows ~/.pi/agent/cursor-sdk-context-windows.json
+```
+
+The refresh script writes public model metadata only and scrubs known auth material from SDK errors. It must not be run with shell tracing that would echo API keys.
+
 Local development run:
 
 ```bash

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

@@ -13,15 +13,16 @@ 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`.
+- Image payload forwarding 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. The prompt explicitly tells Cursor that prior image bytes are unavailable and to ask the user to reattach or describe a prior image when needed. Carrying images forward across turns remains a future product decision because it affects 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.
+- Local agents do not pass `settingSources` by default because the Cursor SDK can print settings/skills loading output directly to the terminal during startup. Users can opt in with `PI_CURSOR_SETTING_SOURCES=all` or narrow loading with a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`.
 - Cursor SDK models are treated as thinking-capable even when pi reports `thinking=no`; that pi column only means the SDK did not expose a pi-controllable thinking parameter for that model.
-- 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-side thinking remains visible. Cursor internal tool activity is recorded from SDK events and scrubbed. In interactive TTY sessions, supported completed `read`, `bash`, `ls`, `edit`, and `write` 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/file edits. Cursor edit/write activity is replayed through `cursor_edit` and `cursor_write` cards rather than pi's built-in `edit`/`write` names because Cursor's edit/write schemas differ from pi's schemas; these replay-only tools display recorded Cursor results and fail closed if called without a recorded result. 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.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`.
+- `@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
 
@@ -65,7 +66,7 @@ Discovery resolves `apiKey` in this order:
 2. Stored pi auth for provider `cursor` from `AuthStorage.create().getApiKey("cursor", { includeFallback: false })`.
 3. `CURSOR_API_KEY`.
 
-Users can persist the stored key through `/login` -> `Use an API key` -> `Cursor`. If auth is added after startup, fallback models can run once pi resolves the saved key for provider requests, but `/reload` or restart is required to refresh the full live Cursor model catalog.
+Users can persist the stored key through `/login` -> `Use an API key` -> `Cursor`. If auth is added after startup, fallback models can run once pi resolves the saved key for provider requests, and `/cursor-refresh-models` refreshes the full live Cursor model catalog without restarting pi.
 
 For each model, use:
 
@@ -76,7 +77,7 @@ For each model, use:
 - `model.variants`
 - default variant: `variant.isDefault === true`, else first variant
 
-This means new Cursor models and changed Cursor parameters are picked up after reload/restart.
+This means new Cursor models and changed Cursor parameters are picked up after `/cursor-refresh-models`, reload, or restart.
 
 Pi model metadata is also a source of truth for pi-native behavior:
 
@@ -92,24 +93,21 @@ If a Cursor parameter changes any of those pi-native fields, model registration
 
 ### Refresh Current Cursor Matrix
 
-Run this whenever Cursor releases or changes models:
+Run this whenever Cursor releases or changes models, and before releases that may ship stale fallback metadata:
 
 ```bash
-node --input-type=module <<'EOF'
-import { Cursor } from '@cursor/sdk';
-
-const models = await Cursor.models.list({ apiKey: process.env.CURSOR_API_KEY });
-for (const model of models) {
-  const options = (model.parameters ?? [])
-    .map((param) => `${param.id}: ${param.values.map((value) => value.value).join(', ')}`)
-    .join(' | ') || 'none';
-  const defaultVariant = model.variants?.find((variant) => variant.isDefault) ?? model.variants?.[0];
-  const defaults = defaultVariant?.params?.map((param) => `${param.id}=${param.value}`).join('; ') || 'none';
-  console.log(`${model.id}\t${model.displayName}\t${options}\t${defaults}`);
-}
-EOF
+CURSOR_API_KEY="your-key" npm run refresh:cursor-snapshots -- --write
+```
+
+That command refreshes `src/cursor-fallback-models.generated.ts` only. If live local Cursor runs have collected checkpoint-derived context windows, merge them into the bundled default/non-Max snapshot too:
+
+```bash
+CURSOR_API_KEY="your-key" npm run refresh:cursor-snapshots -- --write \
+  --context-windows ~/.pi/agent/cursor-sdk-context-windows.json
 ```
 
+The script calls `Cursor.models.list({ apiKey })`, writes `src/cursor-fallback-models.generated.ts`, and updates `src/bundled-context-windows.ts` only when `--context-windows` is provided. It prints model IDs/counts only and scrubs known auth material from SDK errors; it must not print or store API keys. Review the generated diff before committing because Cursor can change aliases, defaults, and parameter meanings.
+
 ## Design Direction
 
 Use native pi abstractions wherever possible:
@@ -137,8 +135,9 @@ Register a `cursor` provider with `pi.registerProvider()`.
 
 Rules:
 
-- 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.
+- 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.
@@ -486,42 +485,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.8",
+	"version": "0.1.10",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -23,6 +23,7 @@
 	"homepage": "https://github.com/fitchmultz/pi-cursor-sdk#readme",
 	"files": [
 		"src",
+		"scripts/refresh-cursor-model-snapshots.mjs",
 		"README.md",
 		"docs/cursor-model-ux-spec.md",
 		"LICENSE",
@@ -35,7 +36,8 @@
 	"scripts": {
 		"typecheck": "tsc --noEmit",
 		"test": "vitest run",
-		"test:watch": "vitest"
+		"test:watch": "vitest",
+		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs"
 	},
 	"dependencies": {
 		"@cursor/sdk": "^1.0.13"

package/scripts/refresh-cursor-model-snapshots.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { Cursor } from "@cursor/sdk";
+
+const FALLBACK_MODELS_PATH = "src/cursor-fallback-models.generated.ts";
+const CONTEXT_WINDOWS_PATH = "src/bundled-context-windows.ts";
+const DEFAULT_CONTEXT_WINDOW = 200000;
+
+function printHelp() {
+	console.log(`Refresh reviewable Cursor model fallback snapshots.
+
+Usage:
+  npm run refresh:cursor-snapshots -- --write [options]
+  node scripts/refresh-cursor-model-snapshots.mjs [options]
+
+Options:
+  --write                       Write ${FALLBACK_MODELS_PATH}. Also write
+                                ${CONTEXT_WINDOWS_PATH} when --context-windows is supplied.
+                                Without --write, print a summary only.
+  --api-key <key>               Cursor API key. Prefer CURSOR_API_KEY to avoid shell history.
+  --context-windows <file>      Optional JSON file with {"contextWindows": {"model": 123}}
+                                or a plain {"model": 123} map, usually copied from
+                                ~/.pi/agent/cursor-sdk-context-windows.json after live runs.
+  --fallback-context-window <n> Context window to use for newly seen models that lack
+                                a catalog context parameter and no checkpoint override.
+                                Default: ${DEFAULT_CONTEXT_WINDOW}.
+  -h, --help                    Show this help.
+
+Exit codes:
+  0 success
+  1 invalid arguments, missing auth, or Cursor SDK failure
+
+Notes:
+  - This script prints model IDs/counts only; it never prints API keys.
+  - Cursor.models.list() is the source of truth for fallback catalog metadata.
+  - Checkpoint-derived context windows are optional input because collecting them
+    requires successful local SDK runs; this script does not start agents.`);
+}
+
+function fail(message) {
+	console.error(`refresh-cursor-snapshots: ${message}`);
+	process.exit(1);
+}
+
+function scrubSensitiveText(text, secrets = []) {
+	let scrubbed = text;
+	for (const secret of secrets) {
+		if (secret) scrubbed = scrubbed.split(secret).join("[REDACTED]");
+	}
+	return scrubbed
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+		.replace(/(api[_-]?key|authorization|auth[_-]?token)([\"'\s:=]+)[^\"'\s,}]+/gi, "$1$2[REDACTED]");
+}
+
+function parseArgs(argv) {
+	const args = {
+		write: false,
+		apiKey: process.env.CURSOR_API_KEY?.trim() || undefined,
+		contextWindowsPath: undefined,
+		fallbackContextWindow: DEFAULT_CONTEXT_WINDOW,
+	};
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "-h" || arg === "--help") {
+			printHelp();
+			process.exit(0);
+		}
+		if (arg === "--write") {
+			args.write = true;
+			continue;
+		}
+		if (arg === "--api-key") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--api-key requires a value");
+			args.apiKey = value.trim();
+			continue;
+		}
+		if (arg.startsWith("--api-key=")) {
+			args.apiKey = arg.slice("--api-key=".length).trim();
+			continue;
+		}
+		if (arg === "--context-windows") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--context-windows requires a file path");
+			args.contextWindowsPath = value;
+			continue;
+		}
+		if (arg.startsWith("--context-windows=")) {
+			args.contextWindowsPath = arg.slice("--context-windows=".length);
+			continue;
+		}
+		if (arg === "--fallback-context-window") {
+			const value = argv[++index];
+			if (!value || value.startsWith("--")) fail("--fallback-context-window requires a positive integer");
+			args.fallbackContextWindow = parsePositiveInteger(value, "--fallback-context-window");
+			continue;
+		}
+		if (arg.startsWith("--fallback-context-window=")) {
+			args.fallbackContextWindow = parsePositiveInteger(arg.slice("--fallback-context-window=".length), "--fallback-context-window");
+			continue;
+		}
+		fail(`unknown argument ${arg}`);
+	}
+	if (!args.apiKey) fail("missing Cursor API key; set CURSOR_API_KEY or pass --api-key");
+	return args;
+}
+
+function parsePositiveInteger(value, label) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) fail(`${label} must be a positive integer`);
+	return parsed;
+}
+
+function sanitizeModelItem(item) {
+	return stripUndefined({
+		id: item.id,
+		displayName: item.displayName,
+		description: item.description,
+		aliases: Array.isArray(item.aliases) ? [...item.aliases] : undefined,
+		parameters: Array.isArray(item.parameters)
+			? item.parameters.map((parameter) =>
+					stripUndefined({
+						id: parameter.id,
+						displayName: parameter.displayName,
+						values: Array.isArray(parameter.values)
+							? parameter.values.map((value) => stripUndefined({ value: value.value, displayName: value.displayName }))
+							: [],
+					}),
+				)
+			: undefined,
+		variants: Array.isArray(item.variants)
+			? item.variants.map((variant) =>
+					stripUndefined({
+						params: Array.isArray(variant.params) ? variant.params.map((param) => ({ id: param.id, value: param.value })) : [],
+						displayName: variant.displayName,
+						description: variant.description,
+						isDefault: variant.isDefault,
+					}),
+				)
+			: undefined,
+	});
+}
+
+function stripUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
+function stableStringify(value) {
+	return JSON.stringify(value, null, "\t").replace(/"([^"\\]+)":/g, "$1:");
+}
+
+function formatFallbackModels(models) {
+	return `import type { ModelListItem } from "@cursor/sdk";\n\n// Generated/maintained fallback Cursor catalog snapshot.\n// Refresh with: npm run refresh:cursor-snapshots -- --write\n// Do not add secrets; this file stores public model metadata only.\nexport const FALLBACK_MODEL_ITEMS = ${stableStringify(models)} satisfies ModelListItem[];\n`;
+}
+
+function parseExistingContextWindows() {
+	if (!existsSync(CONTEXT_WINDOWS_PATH)) return new Map();
+	const source = readFileSync(CONTEXT_WINDOWS_PATH, "utf8");
+	const entries = new Map();
+	const entryPattern = /(?:"([^"]+)"|([A-Za-z_$][\w$]*)):\s*(\d+)/g;
+	for (const match of source.matchAll(entryPattern)) {
+		entries.set(match[1] ?? match[2], Number(match[3]));
+	}
+	return entries;
+}
+
+function parseContextWindowsFile(path) {
+	if (!path) return new Map();
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		fail(`could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const source = parsed.contextWindows && typeof parsed.contextWindows === "object" ? parsed.contextWindows : parsed;
+	const windows = new Map();
+	for (const [modelId, contextWindow] of Object.entries(source)) {
+		if (Number.isInteger(contextWindow) && contextWindow > 0) windows.set(modelId, contextWindow);
+	}
+	return windows;
+}
+
+function hasContextParameter(model) {
+	return (model.parameters ?? []).some((parameter) => parameter.id === "context");
+}
+
+function formatContextWindows(models, checkpointWindows, fallbackContextWindow) {
+	const existing = parseExistingContextWindows();
+	const merged = new Map(existing);
+	for (const [modelId, contextWindow] of checkpointWindows) merged.set(modelId, contextWindow);
+	for (const model of models) {
+		if (!hasContextParameter(model) && !merged.has(model.id)) merged.set(model.id, fallbackContextWindow);
+	}
+	if (!merged.has("default")) merged.set("default", fallbackContextWindow);
+
+	const date = new Date().toISOString().slice(0, 10);
+	const sorted = [...merged.entries()].sort(([a], [b]) => (a === "default" ? -1 : b === "default" ? 1 : a.localeCompare(b)));
+	const lines = sorted.map(([modelId, contextWindow]) => `\t${JSON.stringify(modelId)}: ${contextWindow},`);
+	return `// Generated from Cursor SDK checkpoint tokenDetails.maxTokens on ${date}.\n// Refresh with: npm run refresh:cursor-snapshots -- --write --context-windows ~/.pi/agent/cursor-sdk-context-windows.json\n// These are default/non-Max-mode SDK context windows for Cursor models that do not\n// expose a catalog \`context\` parameter. Do not replace them with Max Mode values\n// unless the Cursor SDK exposes an exact Max Mode model selection and the extension\n// uses that selection for matching pi model IDs.\nexport const BUNDLED_CONTEXT_WINDOWS = {\n${lines.join("\n")}\n} as const satisfies Record<string, number>;\n`;
+}
+
+const args = parseArgs(process.argv.slice(2));
+let rawModels;
+try {
+	rawModels = await Cursor.models.list({ apiKey: args.apiKey });
+} catch (error) {
+	const rawMessage = error instanceof Error ? error.message : String(error);
+	fail(`Cursor.models.list() failed: ${scrubSensitiveText(rawMessage, [args.apiKey])}`);
+}
+if (!Array.isArray(rawModels) || rawModels.length === 0) fail("Cursor.models.list() returned no models");
+
+const models = rawModels.map(sanitizeModelItem).sort((a, b) => a.id.localeCompare(b.id));
+const checkpointWindows = parseContextWindowsFile(args.contextWindowsPath);
+const fallbackSource = formatFallbackModels(models);
+const contextWindowSource = args.contextWindowsPath ? formatContextWindows(models, checkpointWindows, args.fallbackContextWindow) : undefined;
+const existingContextWindowCount = parseExistingContextWindows().size;
+
+console.log(`Fetched ${models.length} Cursor models.`);
+console.log(`Context windows: ${checkpointWindows.size} checkpoint override(s), ${existingContextWindowCount} existing bundled entr${existingContextWindowCount === 1 ? "y" : "ies"}.`);
+console.log(`First models: ${models.slice(0, 8).map((model) => model.id).join(", ")}${models.length > 8 ? ", ..." : ""}`);
+
+if (args.write) {
+	writeFileSync(FALLBACK_MODELS_PATH, fallbackSource);
+	console.log(`Wrote ${FALLBACK_MODELS_PATH}`);
+	if (contextWindowSource) {
+		writeFileSync(CONTEXT_WINDOWS_PATH, contextWindowSource);
+		console.log(`Wrote ${CONTEXT_WINDOWS_PATH}`);
+	} else {
+		console.log(`Skipped ${CONTEXT_WINDOWS_PATH}; pass --context-windows to refresh checkpoint-derived context windows.`);
+	}
+} else {
+	console.log("Dry run only. Re-run with --write to update snapshots.");
+}

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;
@@ -80,4 +82,8 @@ export function saveCachedContextWindow(modelId: string, contextWindow: number):
 
 export const __testUtils = {
 	getCachePath,
+	getUserContextWindowOverrideLoadCount: () => userContextWindowOverrideLoadCount,
+	resetUserContextWindowOverrideLoadCount: () => {
+		userContextWindowOverrideLoadCount = 0;
+	},
 };