pi-cursor-sdk 0.1.25 → 0.1.27

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.1.27 - 2026-05-29
+
+### Changed
+
+- Upgrade the pinned Cursor SDK runtime dependency to `@cursor/sdk@1.0.16` and keep the local validation baseline on pi `0.77.0`.
+- Align Cursor context-window checkpoint reads with the SDK 1.0.16 local platform options by scoping direct `createAgentPlatform()` calls to the pi session cwd, matching the workspace used for `Agent.create()`.
+- Review SDK 1.0.16 public-surface changes: new custom `LocalAgentStore` exports (`JsonlLocalAgentStore`, `SqliteLocalAgentStore`, store filters/paginators), per-call `store` options on local agent/list/message APIs, `Cursor.configure()` / `configureCursorSdk()` local defaults, HTTP/1 agent override support, public `CursorAgentPlatformOptions` local-store fields, and the removal of `AgentOptions.platform`. The extension continues to use the SDK default SQLite store and does not install a custom global SDK configuration because pi session cwd remains the source of truth for local persistence.
+
+## 0.1.26 - 2026-05-29
+
+### Added
+
+- Cache the discovered Cursor model catalog on disk at `~/.pi/agent/cursor-sdk-model-list.json` (`0600`, keyed by an API-key fingerprint) so warm pi startups skip the live `Cursor.models.list` network round-trip that added several seconds to boot (#78). Tune with `PI_CURSOR_SDK_MODEL_CACHE_TTL_MS` (default 24h) or disable with `PI_CURSOR_SDK_DISABLE_MODEL_CACHE=1`.
+
+### Changed
+
+- Clarify setup docs and runtime auth messages: `pi-cursor-sdk` requires a Cursor SDK API key and does not reuse Cursor Agent CLI/Desktop login or subscription auth.
+- `/cursor-refresh-models` now forces a live catalog refresh, bypassing the on-disk cache and rewriting it. A previously cached catalog is preferred over the bundled fallback when a live refresh fails.
+- Lazy-load the Cursor SDK runtime so warm cached startup paths avoid importing `@cursor/sdk` until live model discovery or a Cursor turn needs it (#100).
+
+### Fixed
+
+- Prevent Cursor SDK `ConnectError: [unauthenticated]` failures from crashing pi as process-level uncaught exceptions; surface them as recoverable Cursor auth errors instead.
+
 ## 0.1.25 - 2026-05-28
 
 ### Fixed

package/README.md

@@ -24,7 +24,7 @@ pi install https://github.com/fitchmultz/pi-cursor-sdk
 pi --model cursor/composer-2.5
 ```
 
-3. In pi, run `/login`, choose `Use an API key`, choose `Cursor`, and paste your Cursor API key.
+3. In pi, run `/login`, choose `Use an API key`, choose `Cursor`, and paste your Cursor SDK API key.
 
 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.
 
@@ -32,9 +32,9 @@ If pi started without a key, run `/cursor-refresh-models` after `/login` to refr
 
 - Node.js 22.19+
 - pi 0.76.0 or newer
-- a Cursor API key saved through `/login`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`
+- a Cursor SDK API key saved through `/login`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`
 
-No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.15`, so normal package installation brings in the SDK version this extension was built and tested against. This package declares a pi **minimum** of 0.76.0 with no maximum peer version, so users who update pi before this extension is republished are not blocked from trying the existing extension. The current validation baseline is pi 0.77.0 plus Cursor SDK 1.0.15; older pi or Cursor SDK compatibility paths are not maintained.
+No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.16`, so normal package installation brings in the SDK version this extension was built and tested against. This package declares a pi **minimum** of 0.76.0 with no maximum peer version, so users who update pi before this extension is republished are not blocked from trying the existing extension. The current validation baseline is pi 0.77.0 plus Cursor SDK 1.0.16; older pi or Cursor SDK compatibility paths are not maintained.
 
 ## Install
 
@@ -67,7 +67,11 @@ npm install
 pi -e . --model cursor/composer-2.5
 ```
 
-## Configure your Cursor API key
+## Configure your Cursor SDK API key
+
+`pi-cursor-sdk` passes an explicit API key to the Cursor SDK. It does **not** reuse Cursor Agent CLI login, Cursor Desktop login, or Cursor subscription/OAuth state shown by `agent status`.
+
+Use either a user API key from Cursor Dashboard → Integrations or a service account API key from Team settings. Team Admin API keys are not supported by the Cursor SDK. Then configure the key with one of the methods below.
 
 Preferred setup:
 
@@ -80,11 +84,13 @@ Then, inside pi:
 1. Run `/login`.
 2. Select `Use an API key`.
 3. Select `Cursor`.
-4. Paste your Cursor API key.
+4. Paste your Cursor SDK 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, and `/cursor-refresh-models` refreshes the full live Cursor model catalog discovered from the Cursor SDK without restarting pi.
 
+Note: if `/login` shows `Cursor ✓ key in models.json` but you have not saved a Cursor key and `CURSOR_API_KEY` is unset, that status is a pi auth-status limitation. A real Cursor SDK API key is still required for Cursor runs.
+
 Environment setup:
 
 ```bash
@@ -100,6 +106,18 @@ pi --api-key "your-key" --model cursor/composer-2.5 --cursor-no-fast -p "Say ok
 
 Discovery uses pi's native resolution order for this extension: `--api-key`, the stored `cursor` key in `~/.pi/agent/auth.json`, then `CURSOR_API_KEY`.
 
+### Model catalog cache
+
+To avoid a live `Cursor.models.list` network round-trip on every pi startup, the discovered catalog is cached on disk at `~/.pi/agent/cursor-sdk-model-list.json` (written `0600`, keyed by an API-key fingerprint — the key itself is never stored). Warm startups within the cache TTL skip the network call and avoid loading `@cursor/sdk` until a Cursor turn needs it; `/cursor-refresh-models` always bypasses the cache and refreshes the live catalog. If a refresh fails, a previously cached catalog is preferred over the generic bundled fallback.
+
+```bash
+# Cache lifetime in milliseconds (default 86400000 = 24h).
+PI_CURSOR_SDK_MODEL_CACHE_TTL_MS=3600000 pi --model cursor/composer-2.5
+
+# Disable the cache and always discover live.
+PI_CURSOR_SDK_DISABLE_MODEL_CACHE=1 pi --model cursor/composer-2.5
+```
+
 Do not store the API key in `~/.pi/agent/cursor-sdk.json`. That file is only for non-secret extension state such as Cursor fast defaults. `PATH` is only for executable lookup and should not contain the API key.
 
 ## Verify your setup
@@ -118,9 +136,12 @@ Expected behavior:
 Smoke test:
 
 ```bash
-pi --model cursor/composer-2.5 --cursor-no-fast -p "Reply with: ok"
+pi --model cursor/composer-2.5 --cursor-no-fast --no-session --mode json \
+  -p "Reply exactly PI_CURSOR_MODEL_OK and nothing else."
 ```
 
+Expected: the final assistant text is `PI_CURSOR_MODEL_OK`. If auth is missing or invalid, pi should tell you to configure a Cursor SDK API key via `/login`, `CURSOR_API_KEY`, or `--api-key`.
+
 ## Choosing a model
 
 Choose Cursor models interactively with `/model`, or pass a model on the command line:
@@ -306,7 +327,7 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 
 ### 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 `/cursor-refresh-models`.
+You may be seeing fallback startup models or a missing/invalid Cursor SDK API key. Cursor Agent CLI/Desktop login is not reused by this extension. In interactive pi, run `/login`, choose `Use an API key`, choose `Cursor`, paste the key, then run `/cursor-refresh-models`.
 
 When a Cursor run fails after auth is configured, pi now surfaces scrubbed provider detail instead of only `Cursor SDK run failed`. Generic SDK failures include safe run metadata such as model id, a short run id prefix, and duration when available. Check the red toast or assistant error message for that detail before retrying.
 

package/docs/cursor-live-smoke-checklist.md

@@ -66,7 +66,7 @@ The replay scan flags only error `toolResult` / error assistant messages with `T
 Pass criteria:
 
 - `pi --version` reports pi 0.77.0 for this cutover baseline.
-- `npm ls` shows `@cursor/sdk@1.0.15` and local `@earendil-works/*@0.77.0` packages.
+- `npm ls` shows `@cursor/sdk@1.0.16` and local `@earendil-works/*@0.77.0` packages.
 - `cursor/composer-2.5` appears in the model list.
 - No Cursor key or auth token is printed.
 - If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
@@ -115,7 +115,7 @@ Run a real interactive session under tmux:
 ```bash
 SESSION="pi-cursor-sdk-smoke-$(date +%s)"
 tmux new-session -d -s "$SESSION" -x 120 -y 40 -- zsh -lc \
-  "cd '$PWD' && PI_CURSOR_SETTING_SOURCES=none pi -e . --cursor-no-fast --model cursor/composer-2.5 --session-dir '$SMOKE_DIR/tui' --session-id cursor-sdk-1015-tui --no-tools 'TUI smoke. Compute 19 + 23. Reply only with SUM=<number>.'"
+  "cd '$PWD' && PI_CURSOR_SETTING_SOURCES=none pi -e . --cursor-no-fast --model cursor/composer-2.5 --session-dir '$SMOKE_DIR/tui' --session-id cursor-sdk-1016-tui --no-tools 'TUI smoke. Compute 19 + 23. Reply only with SUM=<number>.'"
 ```
 
 Observe with `tmux capture-pane -pt "$SESSION"` or attach manually.
@@ -131,10 +131,10 @@ Pass criteria:
 
 ## 4. Mandatory visual card/color rendering check
 
-This is the canonical visual release path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use pi 0.77.0, `@cursor/sdk@1.0.15`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
+This is the canonical visual release path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use pi 0.77.0, `@cursor/sdk@1.0.16`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
 
 ```bash
-VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1015-visual.XXXXXX)"
+VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"
 VISUAL_ARGS=(
   --ext "$PWD"
   --cwd "$PWD"
@@ -204,7 +204,7 @@ Pass criteria:
 PI_CURSOR_SETTING_SOURCES=none \
 pi -e . --cursor-no-fast --cursor-mode plan --model cursor/composer-2.5 \
   --session-dir "$SMOKE_DIR/cursor-mode-plan" \
-  --session-id cursor-sdk-1015-plan \
+  --session-id cursor-sdk-1016-plan \
   --no-tools \
   -p 'Cursor mode smoke. Reply with one short implementation plan for printing hello.' \
   > "$SMOKE_DIR/cursor-mode-plan.stdout.txt" \

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

@@ -15,7 +15,7 @@ Current implementation notes:
 - Cursor status uses one coordinated `ctx.ui.setStatus("cursor", ...)` value for fast and non-default plan mode; the default pi footer remains intact.
 - Installed `@cursor/sdk` user messages accept images, and Cursor models are treated as image-capable; registered input metadata is `text` plus `image`.
 - 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.
-- Exact `@cursor/sdk@1.0.15` is a package dependency of this extension; users should not need a global SDK install. pi 0.77.0 is the current validation baseline, while published pi peer dependencies are minimum-only `>=0.76.0` ranges with no upper bound. Newer pi versions are allowed to attempt loading this extension before a matching extension release exists; compatibility is best-effort until validated.
+- Exact `@cursor/sdk@1.0.16` is a package dependency of this extension; users should not need a global SDK install. pi 0.77.0 is the current validation baseline, while published pi peer dependencies are minimum-only `>=0.76.0` ranges with no upper bound. Newer pi versions are allowed to attempt loading this extension before a matching extension release exists; compatibility is best-effort until validated.
 - 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 pass `settingSources: ["all"]` by default so Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available. Users can narrow loading with a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`, or disable ambient setting sources with `PI_CURSOR_SETTING_SOURCES=none`. The provider suppresses direct Cursor SDK bootstrap stdout/stderr/console noise (including late first-send workspace loading such as hook compatibility warnings) so it does not pollute pi's TUI.
 - On `cursor/*` models, pi-cursor-sdk removes only pi-generated `<project_instructions>` blocks that overlap the effective Cursor `settingSources`: `user` for `~/.pi/agent/AGENTS.md`; `project` for discovered repo/parent `AGENTS.md` and `CLAUDE.md` (verified Cursor behavior: local agents load project `AGENTS.md` and `CLAUDE.md`). `~/.pi/agent/CLAUDE.md` is not removed (Cursor user layer uses `~/.claude/CLAUDE.md`). Blocks are removed by exact pi serialization match from structured `contextFiles` via the `before_agent_start` hook, not in `buildCursorPrompt` sanitization. Suppression is skipped with `-nc`, `PI_CURSOR_SETTING_SOURCES=none`, narrowed sources such as `plugins` that omit the matching layer, or `PI_CURSOR_PRESERVE_PI_AGENTS_MD=1`. Switching away from a Cursor model restores pi's full context block on the next user message.
@@ -26,18 +26,18 @@ Current implementation notes:
 - Prompt text is the primary provider/bridge contract. Bootstrap prompts carry a short boundary block plus the callable-surface manifest by default (`PI_CURSOR_TOOL_MANIFEST=1`). MCP `listTools` descriptions use a one-line pointer to the bootstrap prompt instead of repeating the full contract (`buildCursorPiBridgeMcpToolDescription()`). Cursor must call the exposed `pi__*` MCP name, not the real pi tool name shown in pi history or transcripts. Pi emits and executes the real pi tool name. Maintainer debug: `/cursor-tools` prints bridge/manifest enablement, effective `PI_CURSOR_SETTING_SOURCES`, and the current callable-surface snapshot.
 - The provider also registers `cursor_ask_question` for Cursor models when the bridge is enabled. Cursor sees it as `pi__cursor_ask_question`, and pi executes it through the normal tool path so interactive users can choose options from pi UI. In non-UI modes it reports that UI is unavailable so Cursor can state a default assumption instead. `PI_CURSOR_PI_TOOL_BRIDGE=0` disables the local bridge, including question bridging. Cloud Cursor agents remain out of scope for the bridge.
 - The bridge queues MCP calls, emits provider `toolcall_*` events, waits for matching pi `toolResult` messages by `toolCallId`, resolves the result back into the same live Cursor SDK run without creating a new `Agent`, and never calls tool `execute()` handlers directly. The same-run resume invariant holds unless the run was disposed, aborted, or cancelled.
-- Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.15 has a 60-second MCP request default with no public per-server timeout option. The extension extends the verified Cursor SDK MCP `callTool` timeout path to 3600 seconds by default and shortens the verified first-send MCP initialize/listTools timeout paths to 10 seconds by default so unavailable configured MCP servers do not block the first reply for a full minute; unknown MCP protocol timeout stacks keep the SDK default. Users can override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`.
+- Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.16 has a 60-second MCP request default with no public per-server timeout option. The extension extends the verified Cursor SDK MCP `callTool` timeout path to 3600 seconds by default and shortens the verified first-send MCP initialize/listTools timeout paths to 10 seconds by default so unavailable configured MCP servers do not block the first reply for a full minute; unknown MCP protocol timeout stacks keep the SDK default. Users can override tool-call timeouts with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`, and initialize/listTools timeouts with `PI_CURSOR_MCP_CONNECT_TIMEOUT_MS` or `PI_CURSOR_MCP_CONNECT_TIMEOUT_SECONDS`.
 - Bridge diagnostics are opt-in only: `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` writes typed, allowlisted, scrubbed single-line JSONL records to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`. Diagnostics are scrubbed operational logs, not anonymous telemetry. They intentionally include tool names, safe correlation IDs, run lifecycle, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. Correlation IDs are generated independently from the tokenized endpoint path, and Cursor MCP call IDs are hashed before serialization. Diagnostics must not include endpoint paths/URLs/path components/tokens, API keys, bearer tokens, cookies, session credentials, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, or local private session paths in tracked docs, and they must not call pi UI status, notification, or footer APIs. If tool names themselves are unacceptable for a release target, bridge debug diagnostics are not safe for shared logs under the current contract.
 - This repo does not provide a generic desktop-automation, browser-driver, or CDP recipe. Provider docs should describe pi-cursor-sdk's Cursor provider/bridge contract only.
-- Cursor internal tool activity is recorded from SDK events and scrubbed. Maintainer reference for all 16 `@cursor/sdk@1.0.15` `ToolType` values, runtime alias normalization, and intentional mapping/fallback rules: [Cursor native tool replay — SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix) (official SDK docs: https://cursor.com/docs/sdk/typescript). In interactive TTY sessions, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, MCP, semantic search, and screen recording activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native-looking cards without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor MCP`, or `Cursor edit`. For long-running or externally meaningful Cursor tools (`task`, `shell`, `mcp`, `generateImage`, `recordScreen`, `semSearch`, web search/fetch, plan/todo), the provider may surface one low-noise deferred in-progress thinking line such as `Cursor MCP: external_search` from bounded, scrubbed SDK args; fast local tools (`read`, `grep`, `glob`, and similar) skip lifecycle lines when completion follows immediately, and pi bridge MCP calls are excluded because pi already shows real pi tool execution ([lifecycle visibility](./cursor-native-tool-replay.md#low-noise-tool-lifecycle-visibility)). Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, 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. Cursor workflow tools such as mode/task/todo/plan activity are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are surfaced with bounded user-visible labels/traces (neutral activity cards when native replay routing allows, otherwise the same inactive or transcript trace fallbacks used for completed replay) instead of being silently discarded when the run failed/aborted, produced no assistant text, or involved external/side-effectful tools; incomplete fast local discovery starts (`read`, `grep`, `glob`, `ls`) remain maintainer-debug-only after successful text-producing runs so stale SDK start events do not create red post-answer cards. Explicit failures remain visible when Cursor reports them through completed tool calls or step results. Pi bridge MCP starts remain excluded from duplicate incomplete Cursor cards because pi already shows real pi tool execution. `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 bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is used only as display-only fallback for empty successful shell completions, and overlapping shell calls drop ambiguous deltas instead of guessing. Non-interactive runs keep bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.
+- Cursor internal tool activity is recorded from SDK events and scrubbed. Maintainer reference for all 16 `@cursor/sdk@1.0.16` `ToolType` values, runtime alias normalization, and intentional mapping/fallback rules: [Cursor native tool replay — SDK ToolType replay matrix](./cursor-native-tool-replay.md#sdk-tooltype-replay-matrix) (official SDK docs: https://cursor.com/docs/sdk/typescript). In interactive TTY sessions, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, MCP, semantic search, and screen recording activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native-looking cards without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor MCP`, or `Cursor edit`. For long-running or externally meaningful Cursor tools (`task`, `shell`, `mcp`, `generateImage`, `recordScreen`, `semSearch`, web search/fetch, plan/todo), the provider may surface one low-noise deferred in-progress thinking line such as `Cursor MCP: external_search` from bounded, scrubbed SDK args; fast local tools (`read`, `grep`, `glob`, and similar) skip lifecycle lines when completion follows immediately, and pi bridge MCP calls are excluded because pi already shows real pi tool execution ([lifecycle visibility](./cursor-native-tool-replay.md#low-noise-tool-lifecycle-visibility)). Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, 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. Cursor workflow tools such as mode/task/todo/plan activity are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are surfaced with bounded user-visible labels/traces (neutral activity cards when native replay routing allows, otherwise the same inactive or transcript trace fallbacks used for completed replay) instead of being silently discarded when the run failed/aborted, produced no assistant text, or involved external/side-effectful tools; incomplete fast local discovery starts (`read`, `grep`, `glob`, `ls`) remain maintainer-debug-only after successful text-producing runs so stale SDK start events do not create red post-answer cards. Explicit failures remain visible when Cursor reports them through completed tool calls or step results. Pi bridge MCP starts remain excluded from duplicate incomplete Cursor cards because pi already shows real pi tool execution. `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 bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is used only as display-only fallback for empty successful shell completions, and overlapping shell calls drop ambiguous deltas instead of guessing. Non-interactive runs keep bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.
 - Synthetic replay names are internal compatibility details. New model-facing prompt text and user-visible cards use native tool names when renderer-compatible, or neutral Cursor activity labels when not. Legacy sessions containing old internal replay names are sanitized before prompt/display. Bridge MCP names such as `pi__sem_reindex` are MCP-only; pi session output uses real pi tool names.
 - Cursor SDK usage events report cumulative internal agent/tool/cache work, not the replayable pi prompt context. The extension does not copy raw Cursor SDK usage into pi usage or compaction. For Cursor assistant messages, `usage.input`/`usage.output` are approximate pi session activity components: initial Cursor prompt input is counted once, consumed split-run tool results are counted as deduped input on the following assistant turn, and assistant output includes visible text/thinking/tool-call content. `usage.totalTokens` is the replayable Cursor prompt/context estimate derived from the same `buildCursorPrompt()` path used for `Agent.send`; it may differ from `input + output` and is the context-safe value for display/compaction. `src/cursor-usage-accounting.ts` owns this usage policy, and `src/cursor-live-run-accounting.ts` owns prompt-once and consumed-tool-result accounting so provider usage and bridge result resolution share the same matched tool-result boundary.
 - Audit observation, 2026-05-19, superseded by the 2026-05-21 replay pass and #68 incomplete visibility, then narrowed by the 2026-05-26 fast-local suppression: a missing-file read with Composer 2.5 emitted `tool-call-started` for Cursor `read`, then streamed final text `Error: File not found`, but did not emit `tool-call-completed` or an `onStep` `toolCall` error result. Leftover external/side-effectful started calls are surfaced at run completion through the same native replay routing as completed tools (activity cards when allowed, otherwise inactive/transcript traces), while fast local discovery starts are debug-only after a successful text-producing run. Cursor-reported completed/step errors remain visible.
 - Maintainer visual verification for replay-card changes should follow [Cursor Native Tool Visual Audit Workflow](./cursor-native-tool-visual-audit.md): offscreen PTY-driven pi run, xterm.js/Playwright screenshot rendering, and JSONL inspection before accepting commits or PRs.
 - Cursor provider/runtime releases should follow [Cursor Live Smoke Checklist](./cursor-live-smoke-checklist.md) with real `pi -e . --cursor-no-fast --model cursor/composer-2.5` invocations, manual observation, temporary session dirs, diagnostics scans, and persisted JSONL inspection. See [Cursor testing lessons](./cursor-testing-lessons.md) for auth.json seeding, isolated smoke harnesses, and replay JSONL scans. Assume every runtime surface is in scope. A release is not ready when any live check is optional, deferred, mostly passing, or unobserved.
 - 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.15 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.15 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.
+- Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.16 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.
+- The installed `@cursor/sdk` exposes 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.
 - Session-scoped Cursor SDK agent pooling reuses one live `@cursor/sdk` agent across compatible follow-up turns within the same pi session scope. `planCursorSessionSend()` in `src/cursor-session-send-policy.ts` decides whether the next turn sends a full bootstrap prompt or an incremental follow-up, whether the SDK agent must be recreated, and why. `computeCursorContextFingerprint()` and `shouldBootstrapCursorContext()` remain the context-only bootstrap signal. The pool recreates the agent when context diverges, when branch or compaction summaries appear after `/tree` navigation or compaction, after 20 completed incremental sends, when the API key identity changes, after send errors, on `session_shutdown`, and when `session_before_tree` / `session_tree` invalidate the active branch. Incremental sends omit the full Cursor SDK tool boundary block because the session agent retains prior bootstrap context, but every send ends with a short tool tail guard placed after the latest user request (including an explicit shell `cd` hint).
 - Pi steering/follow-up delivery can arrive while a split live Cursor SDK run is still active. The provider resolves pending live runs by scanning trailing `toolResult` messages while skipping trailing `user` messages, tracks the active live run per session scope, and resumes the in-flight run instead of calling `Agent.send()` again. When the context ends with steering user text after tool results, the provider releases the prior live run and chains an incremental `Agent.send()` for the latest user message in the same provider turn; if the prior run emits more text or tool requests after steering arrives, that stale activity is cancelled instead of surfacing another old-run tool turn and losing the new user input. A pre-send guard waits for or resumes any still-active scoped live run before starting a fresh send so `@cursor/sdk` `AgentBusyError` (`already has active run`) does not surface to pi users. Pooled session agents mark busy as soon as live/direct `run.wait()` tracking starts (`trackRunCompletion` on the session lease), and `acquireSessionCursorAgent()` awaits that busy state before returning a lease so send planning, transcript offsets, and later `Agent.send()` do not race the prior turn's SDK run completion (for example pi auto-compaction summarization). `session_before_compact` calls `prepareCursorSessionForCompaction()` to release scoped live-run drain state and reset the pooled agent before summarization streams. Tracked completions and send commits are scoped to the pooled agent `instanceId` so disposal/replacement drops stale tracking and ignores late commits from disposed agents.
 
@@ -382,7 +382,7 @@ cursor fast
 
 ## Cursor SDK Mode Behavior
 
-Cursor SDK 1.0.15 exposes SDK-native conversation mode:
+Cursor SDK 1.0.16 exposes SDK-native conversation mode:
 
 ```ts
 type AgentModeOption = "agent" | "plan";

package/docs/cursor-native-tool-replay.md

@@ -62,13 +62,13 @@ When Cursor reports completed tool activity, the extension can display recorded
 
 Cursor `glob` activity is displayed through native `find` cards.
 
-For the full `@cursor/sdk@1.0.15` `ToolType` set, disposition matrix, and runtime alias normalization, see [SDK ToolType replay matrix](#sdk-tooltype-replay-matrix) below. Official SDK reference: https://cursor.com/docs/sdk/typescript
+For the full `@cursor/sdk@1.0.16` `ToolType` set, disposition matrix, and runtime alias normalization, see [SDK ToolType replay matrix](#sdk-tooltype-replay-matrix) below. Official SDK reference: https://cursor.com/docs/sdk/typescript
 
 Edit and write activity replays through pi-facing `edit` and `write` cards only when replay arguments truthfully satisfy the matching pi schema, but still uses recorded Cursor results only. The adapter passes through truthful Cursor paths, content when Cursor reported it, and recorded diff/details; it does not pretend Cursor's editing schema is pi's schema and it fails closed if a recorded replay result is missing. Cursor `StrReplace` with recorded replacement text displays as native-looking `edit`; path-only Cursor `edit` and notebook edit activity fall back to neutral Cursor activity so pi does not reject the replay before recorded-result handling. Cursor `write` displays as native-looking `write`. Diagnostics, delete, todos/plans, task, image, MCP, semantic search, screen recording, and web search/fetch activity use neutral Cursor activity cards with pi's default success/error tool shell. MCP completions whose `toolName` is `WebSearch` / `web_search` / `WebFetch` / similar are labeled **Cursor web search** or **Cursor web fetch** instead of generic **Cursor MCP**. Neutral Cursor activity cards carry display metadata such as `activityTitle` and `activitySummary`, so partial/collapsed cards can say `Cursor plan`, `Cursor todos`, `Cursor MCP`, `Cursor semantic search`, `Cursor screen recording`, `Cursor web search`, `Cursor web fetch`, or `Cursor edit` instead of only `Cursor activity`. These replay tools only display recorded Cursor results; they never mutate files or execute tool work directly. Replay paths are normalized to workspace-relative paths when possible. Most collapsed replay cards include bounded previews for diffs and text details so small edits, todos, task output, and MCP results are visible without expanding; web search/fetch activity stays summary-only while collapsed because those cards often arrive after final text and can otherwise bury the answer. Ctrl+O expansion shows the recorded details. Edit previews omit raw unified diff headers and show compact numbered changed/context lines using pi's native diff added/removed/context colors, and write previews use syntax highlighting when pi can infer a language from the path. Image generation replay cards show the saved image path in the collapsed summary and render the image inline when pi terminal image display is enabled and the generated file is still readable.
 
 ## SDK ToolType replay matrix
 
-Source of truth for SDK tool names: `@cursor/sdk@1.0.15` conversation `ToolType` values and https://cursor.com/docs/sdk/typescript
+Source of truth for SDK tool names: `@cursor/sdk@1.0.16` conversation `ToolType` values and https://cursor.com/docs/sdk/typescript
 
 Implementation owners: `src/cursor-tool-presentation-registry.ts` (canonical names, labels, visibility, replay policy, bridge exclusions for internal replay wrappers, and display-spec key completeness), `src/cursor-transcript-tool-specs.ts` (registry-keyed `TOOL_DISPLAY_SPECS` formatters/builders), `src/cursor-native-tool-display-replay.ts` (replay card rendering derived from registry replay metadata), and `src/cursor-transcript-utils.ts` (`normalizeToolName()` delegating to the registry).
 

package/docs/cursor-native-tool-visual-audit.md

@@ -4,19 +4,19 @@ This workflow is the canonical repo path for verifying Cursor SDK tool replay th
 
 Use it before accepting replay-card commits or PRs, and for every Cursor provider/runtime release where TUI card/color behavior could regress. Text logs and JSONL are necessary, but they are not enough when the claim is visual parity: always keep PNGs for the exact prompt, and keep before/after PNGs when reviewing a rendering change.
 
-Current validation baseline: pi 0.77.0, exact `@cursor/sdk@1.0.15`, local validation packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` at 0.77.0. Published peer dependencies remain minimum-only at pi 0.76.0+ with no upper bound, so newer pi installs can try the extension before a matching validation release exists.
+Current validation baseline: pi 0.77.0, exact `@cursor/sdk@1.0.16`, local validation packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` at 0.77.0. Published peer dependencies remain minimum-only at pi 0.76.0+ with no upper bound, so newer pi installs can try the extension before a matching validation release exists.
 
-## Cursor SDK 1.0.15 / pi 0.77.0 cutover visual record
+## Cursor SDK 1.0.16 / pi 0.77.0 cutover visual record
 
 Record the required cutover validation here or in the final release handoff. The default matrix is native replay only: the runner forces native replay registration on, forces Cursor setting sources off, disables the pi bridge, disables overlapping built-in pi tool exposure, and clears inherited Cursor SDK event-debug artifact env. With `--event-debug`, debug capture writes to a deterministic directory under the visual output directory. Do not commit raw ANSI logs, screenshots, terminal recordings, debug artifacts, or `.debug/visual-smoke` scratch files.
 
 | Field | Required value / evidence |
 | --- | --- |
 | Command/session used | `npm run smoke:visual -- --ext "$PWD" --cwd "$PWD" --mode plan --out-dir <fresh /tmp dir> --label <matrix label> --prompt <matrix prompt>` with default native-replay isolation |
-| Baseline versions | `pi --version` = 0.77.0; `npm ls` = `@cursor/sdk@1.0.15` and local `@earendil-works/*@0.77.0` |
+| Baseline versions | `pi --version` = 0.77.0; `npm ls` = `@cursor/sdk@1.0.16` and local `@earendil-works/*@0.77.0` |
 | Card categories checked | Claim only categories proven by both PNG and JSONL. Required cutover categories are read, grep/search, find/glob, list, shell success, write, edit/diff, and true read failure. Neutral Cursor plan/todo/task/mode activity is optional/opportunistic and only counts when JSONL contains a completed Cursor workflow event. |
 | Observed status/card colors | Confirm native-looking cards use native pi styling; neutral Cursor activity is not red; true errors are distinct; diff previews show red/green; plan status is readable |
-| Screenshot/ANSI evidence location | External path only, for example `/tmp/pi-cursor-sdk-1015-visual.*/read-package.{ansi,txt,html,png,jsonl.path}` |
+| Screenshot/ANSI evidence location | External path only, for example `/tmp/pi-cursor-sdk-1016-visual.*/read-package.{ansi,txt,html,png,jsonl.path}` |
 | Debug artifact location | External `.debug/cursor-sdk-events/...` or temp artifact directory path only; do not commit raw artifacts |
 | Pass/fail notes | Summarize any mismatch, blocker, or auth/environment limitation |
 

package/docs/cursor-testing-lessons.md

@@ -238,7 +238,7 @@ The script writes timestamped artifacts under `--out` (default `/tmp/pi-cursor-s
 
 Stdout prints artifact paths and summary counts only. Raw payloads stay on disk and may contain local paths, project text, tool args/results, or secrets — do not commit or share them.
 
-Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current cutover validation targets exact `@cursor/sdk@1.0.15` and pi 0.77.0 local packages.
+Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current cutover validation targets exact `@cursor/sdk@1.0.16` and pi 0.77.0 local packages.
 
 ## Pi provider SDK event capture
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.25",
+	"version": "0.1.27",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -82,7 +82,7 @@
 		"debug:mcp-coldstart": "node scripts/probe-mcp-coldstart.mjs"
 	},
 	"dependencies": {
-		"@cursor/sdk": "1.0.15",
+		"@cursor/sdk": "1.0.16",
 		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {

package/src/cursor-agent-message-web-tools.ts

@@ -1,5 +1,6 @@
-import { Agent, type AgentMessage } from "@cursor/sdk";
+import type { AgentMessage } from "@cursor/sdk";
 import { asRecord, getArray, getString, stringifyUnknown } from "./cursor-transcript-utils.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 
 const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;
 
@@ -21,6 +22,7 @@ function getOneofCaseValue(value: unknown, caseName: string): unknown {
 }
 
 async function hasCursorAgentMessageAt(agentId: string, cwd: string, offset: number): Promise<boolean> {
+	const { Agent } = await loadCursorSdk();
 	const messages = await Agent.messages.list(agentId, { runtime: "local", cwd, limit: 1, offset });
 	return messages.length > 0;
 }
@@ -46,6 +48,7 @@ export async function loadCursorTranscriptWebToolCallsAfterOffset(options: {
 	offset: number | undefined;
 }): Promise<CursorTranscriptCompletedToolCall[]> {
 	if (options.offset === undefined) return [];
+	const { Agent } = await loadCursorSdk();
 	const messages = await Agent.messages.list(options.agentId, {
 		runtime: "local",
 		cwd: options.cwd,

package/src/cursor-pi-tool-bridge-constants.ts

@@ -0,0 +1,2 @@
+export const MCP_SERVER_NAME = "pi_tools";
+export const MCP_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";

package/src/cursor-pi-tool-bridge-run.ts

@@ -9,6 +9,7 @@ import {
 	ListToolsRequestSchema,
 	type CallToolResult,
 } from "@modelcontextprotocol/sdk/types.js";
+import { MCP_ENDPOINT_ROOT, MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
 import {
 	type CursorPiToolBridgeDiagnosticEvent,
 	type CursorPiToolBridgeLifecycleDiagnosticFields,
@@ -38,8 +39,6 @@ export interface CursorPiToolBridgeRunHost {
 	unregisterRun(pathname: string, run: CursorPiToolBridgeRunImpl): Promise<void>;
 }
 
-export const MCP_SERVER_NAME = "pi_tools";
-export const MCP_ENDPOINT_ROOT = "/cursor-pi-tool-bridge";
 const MCP_SERVER_VERSION = "0.1.0";
 
 interface PendingBridgeCall {

package/src/cursor-pi-tool-bridge-server.ts

@@ -7,7 +7,7 @@ import type {
 	CursorPiToolBridgeSnapshotApi,
 } from "./cursor-pi-tool-bridge-types.js";
 import { isRecord } from "./cursor-pi-tool-bridge-mcp.js";
-import { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
+import type { CursorPiToolBridgeRunImpl } from "./cursor-pi-tool-bridge-run.js";
 import {
 	buildCursorPiToolBridgeSnapshot,
 	buildCursorPiToolBridgeSurfaceSignature,
@@ -54,6 +54,7 @@ export class CursorPiToolBridgeRegistry implements CursorPiToolBridge {
 				exposeOverlappingBuiltins: resolveCursorPiToolBridgeBuiltinsEnabled(this.env),
 			})
 			: createEmptySnapshot();
+		const { CursorPiToolBridgeRunImpl } = await import("./cursor-pi-tool-bridge-run.js");
 		const run = new CursorPiToolBridgeRunImpl(this, this.env, snapshot, bridgeEnabled && snapshot.tools.length > 0, options);
 		this.runs.add(run);
 		await run.start();

package/src/cursor-pi-tool-bridge.ts

@@ -13,8 +13,8 @@ import {
 	resolveCursorPiToolBridgeEnabled,
 } from "./cursor-pi-tool-bridge-snapshot.js";
 import { bridgeToolExecutionAbortTracker } from "./cursor-pi-tool-bridge-abort.js";
+import { MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-constants.js";
 import { LOOPBACK_HOST, CursorPiToolBridgeRegistry } from "./cursor-pi-tool-bridge-server.js";
-import { MCP_SERVER_NAME } from "./cursor-pi-tool-bridge-run.js";
 import type {
 	CursorPiToolBridge,
 	CursorPiToolBridgeExtensionApi,

package/src/cursor-provider-errors.ts

@@ -1,12 +1,13 @@
 import type { RunResult } from "@cursor/sdk";
+import { asRecord } from "./cursor-record-utils.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 
 export const MISSING_CURSOR_API_KEY_MESSAGE =
-	"Cursor SDK runs require a Cursor API key. Run /login -> Use an API key -> Cursor, set CURSOR_API_KEY before starting pi, or restart pi with --api-key.";
+	"Cursor SDK runs require a Cursor SDK API key. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, set CURSOR_API_KEY before starting pi, or restart pi with --api-key.";
 const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request failed. The API key may be missing, invalid, or unauthorized. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
+	"Cursor SDK request failed. The Cursor SDK API key may be missing, invalid, or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const AUTH_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request failed because the API key may be invalid or unauthorized. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
+	"Cursor SDK request failed because the Cursor SDK API key may be invalid or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request timed out during network I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
 
@@ -25,7 +26,78 @@ function isKnownGenericRunFailureText(message: string): boolean {
 }
 
 function isLikelyAuthError(message: string): boolean {
-	return /\b(unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
+	return /\b(unauthenticated|unauthorized|unauthorised|forbidden|invalid api key|invalid key|authentication|auth|401|403)\b/i.test(message);
+}
+
+function getErrorStringField(record: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = record?.[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function getErrorStack(error: unknown, record: Record<string, unknown> | undefined): string {
+	return error instanceof Error ? error.stack ?? "" : getErrorStringField(record, "stack") ?? "";
+}
+
+function isConnectError(error: unknown, record: Record<string, unknown> | undefined): boolean {
+	const name = error instanceof Error ? error.name : getErrorStringField(record, "name");
+	return name === "ConnectError";
+}
+
+function isUnauthenticatedConnectCode(code: unknown): boolean {
+	return code === 16 || (typeof code === "string" && /^(?:16|unauthenticated)$/i.test(code));
+}
+
+function getCursorConnectSource(error: unknown, record: Record<string, unknown> | undefined): CursorConnectErrorSource {
+	const stack = getErrorStack(error, record);
+	if (stack.includes("@cursor/sdk")) return "cursor-sdk-stack";
+	const details = Array.isArray(record?.details) ? record.details : [];
+	const hasCursorBackendDetails = details.some((detail) => {
+		const type = getErrorStringField(asRecord(detail), "type");
+		return typeof type === "string" && type.startsWith("aiserver.");
+	});
+	return hasCursorBackendDetails ? "cursor-backend-details" : "generic-connect";
+}
+
+export type CursorConnectErrorSource = "cursor-sdk-stack" | "cursor-backend-details" | "generic-connect";
+
+export type CursorConnectErrorClassification =
+	| { kind: "abort"; source: "cursor-sdk-stack" }
+	| { kind: "unauthenticated"; source: CursorConnectErrorSource };
+
+export function classifyCursorConnectError(error: unknown): CursorConnectErrorClassification | undefined {
+	const record = asRecord(error);
+	if (!isConnectError(error, record)) return undefined;
+
+	const message = error instanceof Error ? error.message : getErrorStringField(record, "message") ?? "";
+	const rawMessage = getErrorStringField(record, "rawMessage") ?? message;
+	const code = record?.code;
+	const cause = asRecord(record?.cause);
+	const causeName = getErrorStringField(cause, "name");
+	const stack = getErrorStack(error, record);
+
+	if (
+		(code === 1 || code === "canceled") &&
+		Boolean(rawMessage && /(?:operation was aborted|canceled)/i.test(rawMessage)) &&
+		(causeName === "AbortError" || /AbortError/.test(stack)) &&
+		stack.includes("@cursor/sdk") &&
+		stack.includes("@connectrpc/connect-node")
+	) {
+		return { kind: "abort", source: "cursor-sdk-stack" };
+	}
+
+	if (isUnauthenticatedConnectCode(code) || isLikelyAuthError(`${message}\n${rawMessage}`)) {
+		return { kind: "unauthenticated", source: getCursorConnectSource(error, record) };
+	}
+
+	return undefined;
+}
+
+export function isCursorSdkAbortConnectError(error: unknown): boolean {
+	return classifyCursorConnectError(error)?.kind === "abort";
+}
+
+export function isUnauthenticatedConnectError(error: unknown): boolean {
+	return classifyCursorConnectError(error)?.kind === "unauthenticated";
 }
 
 function isLikelyNetworkTimeout(message: string): boolean {
@@ -89,8 +161,8 @@ export function sanitizeCursorProviderError(error: unknown, apiKey?: string): st
 	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
 	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_API_KEY_MESSAGE;
 	const scrubbed = scrubSensitiveText(message, apiKey).trim();
+	if (isUnauthenticatedConnectError(error) || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
 	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
-	if (isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
 	if (isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
 }

package/src/cursor-provider-run-finalizer.ts

@@ -13,7 +13,7 @@ import {
 } from "./cursor-provider-errors.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import type { IncompleteCursorToolRunOutcomeInput } from "./cursor-incomplete-tool-visibility.js";
-import type { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
 import type {
@@ -63,7 +63,7 @@ export interface CursorLiveRunCompletion {
 export interface CursorRunFinalizerParams {
 	runnerParams: CursorProviderTurnRunnerParams;
 	sdkEventDebug: () => CursorSdkEventDebugSink | undefined;
-	sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>;
+	sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>;
 	resolvedApiKey: () => string | undefined;
 }
 
@@ -145,13 +145,13 @@ export class CursorRunFinalizer {
 			void liveCompletion.waitCompletion
 				.finally(async () => {
 					await this.finalizeSdkEventDebugBestEffort();
-					this.safeCleanup(() => this.params.sdkAbortErrorSuppression.dispose());
+					this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
 				})
 				.catch(() => {});
 			return;
 		}
 		await this.finalizeSdkEventDebugBestEffort();
-		this.safeCleanup(() => this.params.sdkAbortErrorSuppression.dispose());
+		this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
 	}
 
 	private async applyDirectOutcome(
@@ -195,7 +195,7 @@ export class CursorRunFinalizer {
 			await abandonSessionCursorAgent(prepared?.sessionAgentScopeKey);
 		}
 		if (error instanceof CursorLiveRunAbortError) {
-			this.params.sdkAbortErrorSuppression.suppressAbortErrors();
+			this.params.sdkProcessErrorGuard.suppressAbortErrors();
 			this.pushTerminalError(this.params.runnerParams.partial, "aborted", this.abortMessage());
 		} else {
 			this.pushTerminalError(

package/src/cursor-provider-turn-finalize.ts

@@ -1,4 +1,3 @@
-import { createAgentPlatform } from "@cursor/sdk";
 import type { SDKAgent } from "@cursor/sdk";
 import { loadCursorTranscriptWebToolCallsAfterOffset } from "./cursor-agent-message-web-tools.js";
 import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
@@ -10,10 +9,14 @@ import {
 	type CursorRunOutcome,
 } from "./cursor-provider-run-outcome.js";
 import type { CursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 
-export async function cacheSdkContextWindow(agentId: string, modelId: string): Promise<void> {
+export async function cacheSdkContextWindow(agentId: string, modelId: string, cwd?: string): Promise<void> {
 	try {
-		const platform = await createAgentPlatform();
+		const { createAgentPlatform } = await loadCursorSdk();
+		const platform = await createAgentPlatform(
+			cwd ? { workspaceRef: cwd, scopedWorkspaceRef: cwd } : undefined,
+		);
 		const checkpoint = await platform.checkpointStore.loadLatest(agentId);
 		const contextWindow = getCheckpointContextWindow(checkpoint);
 		if (contextWindow) saveCachedContextWindow(modelId, contextWindow);
@@ -113,7 +116,7 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 	params.prepared.runtime.turnCoordinator.discardIncompleteStartedToolCalls(outcome.incompleteTools);
 	await params.sdkEventDebug?.captureRunArtifacts(params.run);
 	if (params.cacheContextWindow !== false) {
-		await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId);
+		await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId, params.prepared.cwd);
 	}
 	return outcome;
 }

package/src/cursor-provider-turn-prepare.ts

@@ -1,5 +1,4 @@
 import type { SimpleStreamOptions } from "@earendil-works/pi-ai";
-import { Agent } from "@cursor/sdk";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
 import {
@@ -26,6 +25,7 @@ import { isCursorNativeToolDisplayRuntimeEnabled } from "./cursor-native-tool-di
 import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-provider-turn-api-key.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import type {
 	CursorProviderTurnPrepareResult,
 	CursorProviderTurnRunnerParams,
@@ -56,6 +56,7 @@ export async function prepareCursorProviderTurn(
 		const agentMode = getEffectiveCursorAgentMode();
 		const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
 		const settingSources = getEffectiveCursorSettingSources();
+		const { Agent } = await loadCursorSdk();
 
 		installCursorMcpToolTimeoutOverride();
 		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();

package/src/cursor-provider-turn-runner.ts

@@ -1,7 +1,7 @@
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { drainExistingCursorLiveRunBeforeSend } from "./cursor-provider-live-run-drain.js";
 import { getCursorSessionCwd } from "./cursor-session-cwd.js";
-import { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
 import {
@@ -41,7 +41,7 @@ export class CursorProviderTurnRunner {
 		discardIncompleteToolsFromPrepared(prepared, outcome);
 	}
 
-	async run(sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>): Promise<void> {
+	async run(sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>): Promise<void> {
 		const { stream, partial, model, context, options, sdkEventDebugRef } = this.params;
 		let prepared: CursorProviderTurnPrepareResult | undefined;
 		let sendResult: CursorProviderTurnSendResult | undefined;
@@ -49,7 +49,7 @@ export class CursorProviderTurnRunner {
 		const runFinalizer = new CursorRunFinalizer({
 			runnerParams: this.params,
 			sdkEventDebug: () => this.sdkEventDebug,
-			sdkAbortErrorSuppression,
+			sdkProcessErrorGuard,
 			resolvedApiKey: () => this.resolvedApiKey,
 		});
 
@@ -84,7 +84,7 @@ export class CursorProviderTurnRunner {
 				params: this.params,
 				prepared,
 				sdkEventDebug: this.sdkEventDebug,
-				sdkAbortErrorSuppression,
+				sdkProcessErrorGuard,
 				throwIfAborted: () => this.throwIfAborted(),
 			});
 			const { send } = sendResult;
@@ -131,7 +131,7 @@ export class CursorProviderTurnRunner {
 		const runFinalizer = new CursorRunFinalizer({
 			runnerParams: this.params,
 			sdkEventDebug: () => this.sdkEventDebug,
-			sdkAbortErrorSuppression: installCursorSdkAbortErrorSuppression(),
+			sdkProcessErrorGuard: installCursorSdkProcessErrorGuard(),
 			resolvedApiKey: () => this.resolvedApiKey,
 		});
 		await runFinalizer.applyTerminalEvent({ kind: "error", prepared: undefined, error });

package/src/cursor-provider-turn-send.ts

@@ -2,7 +2,7 @@ import type { SendOptions } from "@cursor/sdk";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { getCursorAgentMessageOffset } from "./cursor-provider-turn-message-offset.js";
-import type { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type {
 	CursorProviderTurnRunnerParams,
 	CursorProviderTurnPrepareResult,
@@ -14,12 +14,12 @@ export interface SendCursorProviderTurnParams {
 	params: CursorProviderTurnRunnerParams;
 	prepared: CursorProviderTurnPrepareResult;
 	sdkEventDebug: CursorSdkEventDebugSink | undefined;
-	sdkAbortErrorSuppression: ReturnType<typeof installCursorSdkAbortErrorSuppression>;
+	sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>;
 	throwIfAborted: () => void;
 }
 
 export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnParams): Promise<CursorProviderTurnSendResult> {
-	const { params, prepared, sdkEventDebug, sdkAbortErrorSuppression, throwIfAborted } = sendParams;
+	const { params, prepared, sdkEventDebug, sdkProcessErrorGuard, throwIfAborted } = sendParams;
 	const { options } = params;
 	const { agent, cwd, payload, meta, runtime } = prepared;
 	const { turnCoordinator, liveRun } = runtime;
@@ -27,7 +27,7 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 	let completed = false;
 	let sdkRun: Awaited<ReturnType<typeof agent.send>> | null = null;
 	const abortListener = () => {
-		sdkAbortErrorSuppression.suppressAbortErrors();
+		sdkProcessErrorGuard.suppressAbortErrors();
 		liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
 		if (sdkRun) {
 			sdkRun.cancel().catch(() => {});
@@ -84,7 +84,7 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 		});
 		if (liveRun) cursorLiveRuns.attachSdkRun(liveRun, run);
 		if (options?.signal?.aborted) {
-			sdkAbortErrorSuppression.suppressAbortErrors();
+			sdkProcessErrorGuard.suppressAbortErrors();
 			liveRun?.bridgeRun?.cancel("Cursor SDK run aborted");
 			await run.cancel().catch(() => {});
 			throw new CursorLiveRunAbortError();

package/src/cursor-provider.ts

@@ -18,7 +18,7 @@ import {
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { disposeAllSessionCursorAgents } from "./cursor-session-agent.js";
 import { attachCursorSdkEventDebugPiStreamTap, type CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
-import { installCursorSdkAbortErrorSuppression } from "./cursor-sdk-abort-error-guard.js";
+import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 import { CursorProviderTurnRunner, resolveCursorApiKey } from "./cursor-provider-turn-runner.js";
 
@@ -53,7 +53,7 @@ export function streamCursor(
 
 	(async () => {
 		const partial = makeInitialMessage(model);
-		const sdkAbortErrorSuppression = installCursorSdkAbortErrorSuppression();
+		const sdkProcessErrorGuard = installCursorSdkProcessErrorGuard();
 
 		const runner = new CursorProviderTurnRunner({
 			model,
@@ -65,7 +65,7 @@ export function streamCursor(
 		});
 
 		try {
-			await runner.run(sdkAbortErrorSuppression);
+			await runner.run(sdkProcessErrorGuard);
 		} catch (error) {
 			await runner.handleOuterCatch(error);
 		}

package/src/cursor-sdk-process-error-guard.ts

@@ -0,0 +1,99 @@
+import { classifyCursorConnectError, isCursorSdkAbortConnectError } from "./cursor-provider-errors.js";
+
+interface CursorSdkProcessErrorGuardToken {
+	suppressAbortErrors: boolean;
+}
+
+export interface CursorSdkProcessErrorGuard {
+	suppressAbortErrors(): void;
+	dispose(): void;
+}
+
+type GenericProcessEmit = (event: string | symbol, ...args: unknown[]) => boolean;
+
+// The local Cursor SDK can surface some ConnectRPC failures as process-level
+// uncaught exceptions/unhandled rejections even when run.wait()/run.cancel() is awaited.
+// Keep suppression scoped to active Cursor provider turns and tightly matched SDK shapes.
+const activeProviderTurns = new Set<CursorSdkProcessErrorGuardToken>();
+let originalProcessEmit: GenericProcessEmit | undefined;
+let captureCallbackInstalled = false;
+
+function hasActiveAbortSuppression(): boolean {
+	for (const turn of activeProviderTurns) {
+		if (turn.suppressAbortErrors) return true;
+	}
+	return false;
+}
+
+function isCursorProvenance(source: string): boolean {
+	return source === "cursor-sdk-stack" || source === "cursor-backend-details";
+}
+
+function shouldSuppressProcessError(event: string | symbol, args: readonly unknown[]): boolean {
+	if (event !== "uncaughtException" && event !== "unhandledRejection") return false;
+	const error = args[0];
+	const classification = classifyCursorConnectError(error);
+	if (!classification) return false;
+	if (classification.kind === "abort") return hasActiveAbortSuppression();
+	return activeProviderTurns.size > 0 && isCursorProvenance(classification.source);
+}
+
+function installProcessEmitPatch(): void {
+	if (originalProcessEmit) return;
+	originalProcessEmit = process.emit.bind(process) as GenericProcessEmit;
+	process.emit = function patchedCursorSdkProcessErrorEmit(this: NodeJS.Process, event: string | symbol, ...args: unknown[]): boolean {
+		if (shouldSuppressProcessError(event, args)) return true;
+		return originalProcessEmit!(event, ...args);
+	} as typeof process.emit;
+}
+
+function installCaptureCallbackIfAvailable(): void {
+	if (captureCallbackInstalled || process.hasUncaughtExceptionCaptureCallback()) return;
+	process.setUncaughtExceptionCaptureCallback((error: Error) => {
+		if (shouldSuppressProcessError("uncaughtException", [error])) return;
+		uninstallCaptureCallbackIfIdle(true);
+		if (originalProcessEmit?.("uncaughtException", error)) return;
+		throw error;
+	});
+	captureCallbackInstalled = true;
+}
+
+function uninstallCaptureCallbackIfIdle(force = false): void {
+	if (!captureCallbackInstalled) return;
+	if (!force && activeProviderTurns.size > 0) return;
+	process.setUncaughtExceptionCaptureCallback(null);
+	captureCallbackInstalled = false;
+}
+
+function uninstallProcessEmitPatchIfIdle(): void {
+	if (activeProviderTurns.size > 0 || !originalProcessEmit) return;
+	uninstallCaptureCallbackIfIdle();
+	process.emit = originalProcessEmit as typeof process.emit;
+	originalProcessEmit = undefined;
+}
+
+export const __testUtils = {
+	activeProviderTurnCount: (): number => activeProviderTurns.size,
+};
+
+export { isCursorSdkAbortConnectError };
+
+export function installCursorSdkProcessErrorGuard(): CursorSdkProcessErrorGuard {
+	installProcessEmitPatch();
+	installCaptureCallbackIfAvailable();
+	const token: CursorSdkProcessErrorGuardToken = { suppressAbortErrors: false };
+	activeProviderTurns.add(token);
+	let disposed = false;
+	return {
+		suppressAbortErrors(): void {
+			if (disposed) return;
+			token.suppressAbortErrors = true;
+		},
+		dispose(): void {
+			if (disposed) return;
+			disposed = true;
+			activeProviderTurns.delete(token);
+			uninstallProcessEmitPatchIfIdle();
+		},
+	};
+}

package/src/cursor-sdk-runtime.ts

@@ -0,0 +1,5 @@
+export type CursorSdkModule = typeof import("@cursor/sdk");
+
+export async function loadCursorSdk(): Promise<CursorSdkModule> {
+	return import("@cursor/sdk");
+}

package/src/cursor-session-agent.ts

@@ -6,7 +6,6 @@ import type {
 	SessionTreeEvent,
 } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
-import { Agent } from "@cursor/sdk";
 import type { AgentModeOption, ModelSelection, SDKAgent, SettingSource } from "@cursor/sdk";
 import type { Context } from "@earendil-works/pi-ai";
 import {
@@ -17,6 +16,7 @@ import {
 import { computeCursorContextFingerprint } from "./context.js";
 import { getCursorSessionScopeKey, onCursorSessionScopeKeyChange } from "./cursor-session-scope.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
+import { loadCursorSdk, type CursorSdkModule } from "./cursor-sdk-runtime.js";
 
 export interface SessionCursorAgentSendState {
 	bootstrapped: boolean;
@@ -109,7 +109,7 @@ interface SessionCursorAgentCreateParams {
 	settingSources?: SettingSource[];
 	onBridgeToolRequest?: (request: CursorPiBridgeToolRequest) => void;
 	debugRecorder?: CursorSdkEventDebugRecorder;
-	createAgent?: typeof Agent.create;
+	createAgent?: CursorSdkModule["Agent"]["create"];
 }
 
 interface CursorSessionAgentExtensionApi {
@@ -377,7 +377,7 @@ async function createSessionAgentEntry(
 	}
 
 	const resolvedPoolKey = buildSessionAgentPoolKey(scopeKey, params);
-	const createAgent = params.createAgent ?? Agent.create;
+	const createAgent = params.createAgent ?? (await loadCursorSdk()).Agent.create;
 	let agent: SDKAgent;
 	try {
 		agent = await createAgent({

package/src/cursor-tool-manifest.ts

@@ -4,7 +4,7 @@ import type { CursorPiToolBridgeSnapshot } from "./cursor-pi-tool-bridge-types.j
 export const CURSOR_TOOL_MANIFEST_ENV = "PI_CURSOR_TOOL_MANIFEST";
 
 /**
- * Representative @cursor/sdk@1.0.15 local-agent ToolType values; actual exposure can vary by run.
+ * Representative @cursor/sdk@1.0.16 local-agent ToolType values; actual exposure can vary by run.
  * See docs/cursor-native-tool-replay.md#sdk-tooltype-replay-matrix.
  */
 export const CURSOR_HOST_TOOL_MANIFEST_SUMMARY =

package/src/index.ts

@@ -67,6 +67,7 @@ export default async function (pi: CursorExtensionApi) {
 		handler: async (_args, ctx) => {
 			let refreshFallbackIssue: CursorModelFallbackIssue | undefined;
 			const refreshedModels = await discoverModels({
+				forceRefresh: true,
 				onFallback: (issue) => {
 					refreshFallbackIssue = issue;
 				},
@@ -74,7 +75,7 @@ export default async function (pi: CursorExtensionApi) {
 			registerCursorProvider(pi, refreshedModels);
 			if (!ctx.hasUI) return;
 			if (refreshFallbackIssue) {
-				ctx.ui.notify(`Cursor model catalog refresh still using fallback models: ${refreshFallbackIssue.message}`, "warning");
+				ctx.ui.notify(`Cursor model catalog refresh did not use a live catalog: ${refreshFallbackIssue.message}`, "warning");
 			} else {
 				ctx.ui.notify(`Cursor model catalog refreshed with ${refreshedModels.length} model${refreshedModels.length === 1 ? "" : "s"}.`, "info");
 			}

package/src/model-discovery.ts

@@ -1,4 +1,3 @@
-import { Cursor } from "@cursor/sdk";
 import type {
 	ModelListItem,
 	ModelParameterDefinition,
@@ -8,19 +7,26 @@ import type {
 import { AuthStorage, type ProviderModelConfig } from "@earendil-works/pi-coding-agent";
 import type { ModelThinkingLevel, ThinkingLevelMap } from "@earendil-works/pi-ai";
 import { loadContextWindowCache } from "./context-window-cache.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import { CURSOR_API_KEY_ENV_VAR, resolveCursorApiKey } from "./cursor-api-key.js";
 import { FALLBACK_MODEL_ITEMS } from "./cursor-fallback-models.generated.js";
+import {
+	fingerprintApiKey,
+	loadAnyCachedModelCatalog,
+	loadFreshCachedModels,
+	saveModelListCache,
+} from "./model-list-cache.js";
 
 const CURSOR_PROVIDER_ID = "cursor";
 const FALLBACK_CONTEXT_WINDOW = 128000;
 const FALLBACK_MAX_TOKENS = 16384;
 const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 const TEXT_AND_IMAGE_INPUT: ProviderModelConfig["input"] = ["text", "image"];
-const AUTH_SETUP_HINT = "/login (Use an API key -> Cursor), CURSOR_API_KEY, or --api-key";
+const AUTH_SETUP_HINT = "/login (Use an API key -> Cursor), CURSOR_API_KEY, or --api-key with a Cursor SDK API key; Cursor Agent CLI/Desktop login is not reused";
 const CATALOG_REFRESH_HINT =
 	"After adding auth to an already-started pi session, run /cursor-refresh-models to refresh the full live Cursor model catalog without restarting pi.";
 
-export type CursorModelFallbackReason = "missing-api-key" | "discovery-failed" | "empty-model-list";
+export type CursorModelFallbackReason = "missing-api-key" | "discovery-failed" | "empty-model-list" | "cached-after-error";
 
 export interface CursorModelFallbackIssue {
 	reason: CursorModelFallbackReason;
@@ -30,6 +36,10 @@ export interface CursorModelFallbackIssue {
 
 export interface DiscoverModelsOptions {
 	onFallback?: (issue: CursorModelFallbackIssue) => void;
+	// Bypass the on-disk model cache and always hit the live catalog. Used by the
+	// /cursor-refresh-models command; the startup path leaves this false so warm
+	// boots skip the slow network round-trip.
+	forceRefresh?: boolean;
 }
 
 function getCliApiKeyFromArgv(argv: string[] = process.argv): string | undefined {
@@ -442,9 +452,20 @@ export async function discoverModels(options: DiscoverModelsOptions = {}): Promi
 		});
 	}
 
+	const keyFingerprint = fingerprintApiKey(apiKey);
+
+	if (!options.forceRefresh) {
+		const cachedModels = loadFreshCachedModels(keyFingerprint);
+		if (cachedModels && cachedModels.length > 0) {
+			return registerModelItems(cachedModels);
+		}
+	}
+
 	try {
+		const { Cursor } = await loadCursorSdk();
 		const models = await Cursor.models.list({ apiKey });
 		if (models.length > 0) {
+			saveModelListCache(keyFingerprint, models);
 			return registerModelItems(models);
 		}
 		return useFallbackModels(options, {
@@ -453,6 +474,18 @@ export async function discoverModels(options: DiscoverModelsOptions = {}): Promi
 		});
 	} catch (error) {
 		const errorMessage = sanitizeDiscoveryError(error, apiKey);
+		// Prefer a previously cached catalog over the generic bundled fallback when
+		// a live refresh fails (e.g. transient network/auth errors), but keep the
+		// provenance visible so refresh commands do not claim a live refresh worked.
+		const cachedCatalog = loadAnyCachedModelCatalog(keyFingerprint);
+		if (cachedCatalog && cachedCatalog.models.length > 0) {
+			options.onFallback?.({
+				reason: "cached-after-error",
+				message: `Cursor model discovery failed; using cached Cursor model catalog from ${new Date(cachedCatalog.fetchedAt).toISOString()}. ${errorMessage}`,
+				errorMessage,
+			});
+			return registerModelItems(cachedCatalog.models);
+		}
 		return useFallbackModels(options, {
 			reason: "discovery-failed",
 			message: `Cursor model discovery failed${errorMessage ? `: ${errorMessage}` : ""}. Using fallback Cursor models; verify ${AUTH_SETUP_HINT}. ${CATALOG_REFRESH_HINT}`,

package/src/model-list-cache.ts

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ModelListItem } from "@cursor/sdk";
+import { parseEnvBoolean } from "./cursor-env-boolean.js";
+
+const MODEL_LIST_CACHE_FILE = "cursor-sdk-model-list.json";
+const MODEL_LIST_CACHE_VERSION = 1;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const DISABLE_ENV_VAR = "PI_CURSOR_SDK_DISABLE_MODEL_CACHE";
+const TTL_ENV_VAR = "PI_CURSOR_SDK_MODEL_CACHE_TTL_MS";
+
+interface ModelListCacheFile {
+	version: number;
+	fetchedAt: number;
+	keyFingerprint: string;
+	models: ModelListItem[];
+}
+
+export interface CachedModelList {
+	fetchedAt: number;
+	models: ModelListItem[];
+}
+
+function getCachePath(): string {
+	return join(getAgentDir(), MODEL_LIST_CACHE_FILE);
+}
+
+export function isModelCacheDisabled(): boolean {
+	return parseEnvBoolean(process.env[DISABLE_ENV_VAR], false);
+}
+
+export function getModelCacheTtlMs(): number {
+	const raw = process.env[TTL_ENV_VAR];
+	if (raw === undefined) return DEFAULT_TTL_MS;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_TTL_MS;
+	return parsed;
+}
+
+// Fingerprint the API key so a key change invalidates the cache, without ever
+// persisting the key itself.
+export function fingerprintApiKey(apiKey: string): string {
+	return createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+}
+
+function readCacheFile(): ModelListCacheFile | undefined {
+	const path = getCachePath();
+	if (!existsSync(path)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as ModelListCacheFile;
+		if (
+			parsed.version !== MODEL_LIST_CACHE_VERSION ||
+			typeof parsed.fetchedAt !== "number" ||
+			typeof parsed.keyFingerprint !== "string" ||
+			!Array.isArray(parsed.models)
+		) {
+			return undefined;
+		}
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+// Return cached models only when caching is enabled, the key matches, and the
+// entry is within the TTL. Used on the hot startup path to skip the network.
+export function loadFreshCachedModels(keyFingerprint: string, now: number = Date.now()): ModelListItem[] | undefined {
+	if (isModelCacheDisabled()) return undefined;
+	const ttlMs = getModelCacheTtlMs();
+	if (ttlMs <= 0) return undefined;
+	const cache = readCacheFile();
+	if (!cache || cache.keyFingerprint !== keyFingerprint) return undefined;
+	if (now - cache.fetchedAt > ttlMs) return undefined;
+	return cache.models;
+}
+
+// Return cached models regardless of age, as long as the key matches. Used as a
+// resilience fallback when a live discovery request fails.
+export function loadAnyCachedModelCatalog(keyFingerprint: string): CachedModelList | undefined {
+	if (isModelCacheDisabled()) return undefined;
+	const cache = readCacheFile();
+	if (!cache || cache.keyFingerprint !== keyFingerprint) return undefined;
+	return { fetchedAt: cache.fetchedAt, models: cache.models };
+}
+
+export function loadAnyCachedModels(keyFingerprint: string): ModelListItem[] | undefined {
+	return loadAnyCachedModelCatalog(keyFingerprint)?.models;
+}
+
+export function saveModelListCache(keyFingerprint: string, models: ModelListItem[]): boolean {
+	if (isModelCacheDisabled()) return false;
+	try {
+		const path = getCachePath();
+		mkdirSync(dirname(path), { recursive: true });
+		const data: ModelListCacheFile = {
+			version: MODEL_LIST_CACHE_VERSION,
+			fetchedAt: Date.now(),
+			keyFingerprint,
+			models,
+		};
+		writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+		chmodSync(path, 0o600);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export const __testUtils = {
+	getCachePath,
+	DEFAULT_TTL_MS,
+	DISABLE_ENV_VAR,
+	TTL_ENV_VAR,
+};

package/src/cursor-sdk-abort-error-guard.ts

@@ -1,113 +0,0 @@
-import { asRecord } from "./cursor-record-utils.js";
-
-interface CursorSdkAbortErrorSuppressionToken {
-	suppress: boolean;
-}
-
-export interface CursorSdkAbortErrorSuppression {
-	suppressAbortErrors(): void;
-	dispose(): void;
-}
-
-function getString(record: Record<string, unknown> | undefined, key: string): string | undefined {
-	const value = record?.[key];
-	return typeof value === "string" ? value : undefined;
-}
-
-type GenericProcessEmit = (event: string | symbol, ...args: unknown[]) => boolean;
-
-// The local Cursor SDK can surface abort-time ConnectRPC cancellation as a process-level
-// uncaught exception/unhandled rejection even when run.cancel() is awaited/caught.
-const activeSuppressions = new Set<CursorSdkAbortErrorSuppressionToken>();
-let originalProcessEmit: GenericProcessEmit | undefined;
-let captureCallbackInstalled = false;
-
-export function isCursorSdkAbortConnectError(error: unknown): boolean {
-	const record = asRecord(error);
-	const name = error instanceof Error ? error.name : getString(record, "name");
-	const message = error instanceof Error ? error.message : getString(record, "message");
-	const rawMessage = getString(record, "rawMessage") ?? message;
-	const code = record?.code;
-	const cause = asRecord(record?.cause);
-	const causeName = getString(cause, "name");
-	const stack = error instanceof Error ? error.stack ?? "" : getString(record, "stack") ?? "";
-
-	return (
-		name === "ConnectError" &&
-		(code === 1 || code === "canceled") &&
-		Boolean(rawMessage && /(?:operation was aborted|canceled)/i.test(rawMessage)) &&
-		(causeName === "AbortError" || /AbortError/.test(stack)) &&
-		stack.includes("@cursor/sdk") &&
-		stack.includes("@connectrpc/connect-node")
-	);
-}
-
-function hasActiveSuppression(): boolean {
-	for (const suppression of activeSuppressions) {
-		if (suppression.suppress) return true;
-	}
-	return false;
-}
-
-function shouldSuppressProcessError(event: string | symbol, args: readonly unknown[]): boolean {
-	if (event !== "uncaughtException" && event !== "unhandledRejection") return false;
-	return hasActiveSuppression() && isCursorSdkAbortConnectError(args[0]);
-}
-
-function installProcessEmitPatch(): void {
-	if (originalProcessEmit) return;
-	originalProcessEmit = process.emit.bind(process) as GenericProcessEmit;
-	process.emit = function patchedCursorSdkAbortEmit(this: NodeJS.Process, event: string | symbol, ...args: unknown[]): boolean {
-		if (shouldSuppressProcessError(event, args)) return false;
-		return originalProcessEmit!(event, ...args);
-	} as typeof process.emit;
-}
-
-function installCaptureCallbackIfAvailable(): void {
-	if (captureCallbackInstalled || process.hasUncaughtExceptionCaptureCallback()) return;
-	process.setUncaughtExceptionCaptureCallback((error: Error) => {
-		if (shouldSuppressProcessError("uncaughtException", [error])) return;
-		uninstallCaptureCallbackIfIdle(true);
-		if (originalProcessEmit?.("uncaughtException", error)) return;
-		throw error;
-	});
-	captureCallbackInstalled = true;
-}
-
-function uninstallCaptureCallbackIfIdle(force = false): void {
-	if (!captureCallbackInstalled) return;
-	if (!force && activeSuppressions.size > 0) return;
-	process.setUncaughtExceptionCaptureCallback(null);
-	captureCallbackInstalled = false;
-}
-
-function uninstallProcessEmitPatchIfIdle(): void {
-	if (activeSuppressions.size > 0 || !originalProcessEmit) return;
-	uninstallCaptureCallbackIfIdle();
-	process.emit = originalProcessEmit as typeof process.emit;
-	originalProcessEmit = undefined;
-}
-
-export const __testUtils = {
-	activeSuppressionCount: (): number => activeSuppressions.size,
-};
-
-export function installCursorSdkAbortErrorSuppression(): CursorSdkAbortErrorSuppression {
-	installProcessEmitPatch();
-	const token: CursorSdkAbortErrorSuppressionToken = { suppress: false };
-	activeSuppressions.add(token);
-	let disposed = false;
-	return {
-		suppressAbortErrors(): void {
-			if (disposed) return;
-			token.suppress = true;
-			installCaptureCallbackIfAvailable();
-		},
-		dispose(): void {
-			if (disposed) return;
-			disposed = true;
-			activeSuppressions.delete(token);
-			uninstallProcessEmitPatchIfIdle();
-		},
-	};
-}