pi-cursor-sdk 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.5 - 2026-05-09
+
+### Changed
+
+- Added pi-native `/login` API-key integration for the Cursor provider. Startup discovery now checks pi `--api-key`, the stored `cursor` key in `~/.pi/agent/auth.json`, then `CURSOR_API_KEY`.
+- Fallback Cursor models remain available when startup discovery cannot authenticate; once auth is saved, fallback model runs can use the stored key, while `/reload` or restart refreshes the full live Cursor model catalog.
+- Improved Cursor activity display by preserving Cursor thinking, streaming Cursor text deltas live when native replay is not active, and replaying completed Cursor internal `read`, `bash`, and `ls` activity through pi's native tool rendering path in interactive TTY sessions where possible. Native Cursor tool replay now follows Codex-style ordering as Cursor SDK tool completions arrive: assistant tool-use turn, recorded pi tool results, live post-tool Cursor thinking/text, any later Cursor tool batches, then final assistant answer. Non-interactive runs keep bounded scrubbed transcript output, and raw Cursor call IDs remain omitted.
+- Stopped copying Cursor SDK cumulative internal agent/tool/cache token usage into pi usage, preventing false context-overflow and compaction triggers after long Cursor runs.
+
+### Fixed
+
+- Avoid duplicate final answer text after Cursor streams post-tool text before a later native replayed tool batch.
+
+## 0.1.4 - 2026-05-07
+
+### Fixed
+
+- Restores the GitHub install path to the normal source package layout after the npm-only bundled dependency patch.
+
 ## 0.1.3 - 2026-05-07
 
 ### Fixed

package/README.md

@@ -18,25 +18,21 @@ Or install from GitHub:
 pi install https://github.com/fitchmultz/pi-cursor-sdk
 ```
 
-2. Export your Cursor API key before starting pi:
-
-```bash
-export CURSOR_API_KEY="your-key"
-```
-
-3. Start pi with a Cursor model:
+2. Start pi with a Cursor model:
 
 ```bash
 pi --model cursor/composer-2
 ```
 
-Inside pi, use `/model` to choose another Cursor model.
+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.
 
 ## Requirements
 
 - Node.js 18+
 - pi
-- a Cursor API key available as `CURSOR_API_KEY` or passed with pi's `--api-key`
+- a Cursor 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 `@cursor/sdk`, so normal package installation brings in the SDK version this extension was built and tested against.
 
@@ -75,6 +71,22 @@ pi -e . --model cursor/composer-2
 
 Preferred setup:
 
+```bash
+pi --model cursor/composer-2
+```
+
+Then, inside pi:
+
+1. Run `/login`.
+2. Select `Use an API key`.
+3. Select `Cursor`.
+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.
+
+Environment setup:
+
 ```bash
 export CURSOR_API_KEY="your-key"
 pi --model cursor/composer-2
@@ -86,9 +98,7 @@ One-shot setup:
 pi --api-key "your-key" --model cursor/composer-2 --cursor-no-fast -p "Say ok only."
 ```
 
-Use `CURSOR_API_KEY` when possible. It gives the extension a key during startup model discovery. `--api-key` is also read for discovery and runs, but shell wrappers and launchers are easier to diagnose when the key is exported as `CURSOR_API_KEY` before pi starts.
-
-Important: if pi starts without a valid `CURSOR_API_KEY` or `--api-key`, model discovery may fall back to a conservative Cursor model list. That fallback list is only for selection/display. Cursor runs in that already-started session will fail until you restart pi with a valid key.
+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`.
 
 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.
 
@@ -103,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, but those rows are selection-only and actual runs will fail until restart with a valid key
+- 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
 
 Smoke test:
 
@@ -188,30 +198,33 @@ Images from the latest user message are forwarded to Cursor. Historical images a
 
 ## Fallback models
 
-If `CURSOR_API_KEY` is missing, model discovery fails, or discovery returns no models, the extension registers conservative fallback Cursor models and notifies interactive users when possible:
+If no key is available from `/login`, `CURSOR_API_KEY`, or `--api-key`, model discovery fails, or discovery returns no models, the extension registers conservative fallback Cursor models and notifies interactive users when possible:
 
 - `composer-2`
 - `gpt-5.5@1m`, `gpt-5.5@272k`
 - `claude-sonnet-4-6@1m`, `claude-sonnet-4-6@300k`
 - `claude-opus-4-7@1m`, `claude-opus-4-7@300k`
 
-Fallback models are only a startup model list. Actual Cursor runs still need `CURSOR_API_KEY` or `--api-key`.
+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.
 
 ## Limits
 
 - **Local Cursor SDK agents only.** This extension does not use Cursor cloud agents.
-- **Cursor-side tool use is not exposed as pi tool calls.** You may see compact Cursor trace text before the final answer, but you will not get normal pi tool-call rows for Cursor's internal tool activity.
+- **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. 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.
 - **Max Mode is not exposed for these local runs.** The extension only advertises exact context windows supported by the SDK path it uses.
 - **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.
 
 ## Troubleshooting
 
 ### I can see Cursor models, but runs fail
 
-You may be seeing fallback startup models. Restart pi with a key in the same shell or launcher that starts 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 `/reload` or restart pi.
+
+You can also restart pi with a key in the same shell or launcher that starts pi:
 
 ```bash
 export CURSOR_API_KEY="your-key"

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

@@ -14,10 +14,11 @@ Current implementation notes:
 - 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`.
 - `@cursor/sdk` is a package dependency of this extension; users should not need a global SDK install.
-- Cursor auth uses the `CURSOR_API_KEY` environment variable. The extension config file stores only non-secret Cursor-only state such as fast defaults.
+- 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.
 - 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 and tool activity are surfaced as trace content before final text. Cursor text deltas are buffered until the run finishes so the saved message order is trace first, final answer second.
+- 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. 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.
 - For models without a catalog `context` parameter, context windows are not hardcoded. The extension ships a bundled SDK-derived default/non-Max cache generated from `createAgentPlatform().checkpointStore.loadLatest(agentId).tokenDetails.maxTokens`. Successful runs can update a local override cache, but model discovery does not probe models at startup.
 - Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.12 exposes internal protobuf fields named `maxMode`/`max_mode`, but the public `ModelSelection` type and the local executor path do not pass a Max Mode selector for local agent runs. Do not advertise Max Mode context windows unless the SDK catalog exposes an exact parameter/variant or the SDK public API adds a Max Mode selector that the extension actually sends.
 
@@ -57,6 +58,14 @@ At startup, the extension calls:
 Cursor.models.list({ apiKey });
 ```
 
+Discovery resolves `apiKey` in this order:
+
+1. CLI `--api-key`.
+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.
+
 For each model, use:
 
 - `model.id`

package/package.json

@@ -1,65 +1,62 @@
 {
-  "name": "pi-cursor-sdk",
-  "version": "0.1.3",
-  "description": "pi provider extension backed by @cursor/sdk local agents",
-  "author": "Mitch Fultz (https://github.com/fitchmultz)",
-  "license": "MIT",
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "cursor",
-    "cursor-sdk",
-    "ai",
-    "extension"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/fitchmultz/pi-cursor-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/fitchmultz/pi-cursor-sdk/issues"
-  },
-  "homepage": "https://github.com/fitchmultz/pi-cursor-sdk#readme",
-  "files": [
-    "src",
-    "README.md",
-    "docs/cursor-model-ux-spec.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@cursor/sdk": "^1.0.12"
-  },
-  "bundledDependencies": [
-    "@cursor/sdk"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
-  },
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "overrides": {
-    "undici": "7.25.0",
-    "sqlite3": "6.0.1"
-  }
+	"name": "pi-cursor-sdk",
+	"version": "0.1.5",
+	"description": "pi provider extension backed by @cursor/sdk local agents",
+	"author": "Mitch Fultz (https://github.com/fitchmultz)",
+	"license": "MIT",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"cursor",
+		"cursor-sdk",
+		"ai",
+		"extension"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fitchmultz/pi-cursor-sdk.git"
+	},
+	"bugs": {
+		"url": "https://github.com/fitchmultz/pi-cursor-sdk/issues"
+	},
+	"homepage": "https://github.com/fitchmultz/pi-cursor-sdk#readme",
+	"files": [
+		"src",
+		"README.md",
+		"docs/cursor-model-ux-spec.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"dependencies": {
+		"@cursor/sdk": "^1.0.12"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^0.74.0",
+		"@earendil-works/pi-coding-agent": "^0.74.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.5"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"overrides": {
+		"undici": "7.25.0",
+		"sqlite3": "6.0.1"
+	}
 }

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

@@ -0,0 +1,80 @@
+import {
+	createBashToolDefinition,
+	createLsToolDefinition,
+	createReadToolDefinition,
+	type ExtensionAPI,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "typebox";
+import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+
+const NATIVE_CURSOR_TOOL_NAMES = new Set(["read", "bash", "ls"]);
+
+export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
+	id: string;
+	terminate?: boolean;
+}
+
+let nativeToolDisplayEnabled = false;
+const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
+
+export function isCursorNativeToolDisplayEnabled(): boolean {
+	return nativeToolDisplayEnabled;
+}
+
+export function isCursorNativeToolDisplayRuntimeEnabled(): boolean {
+	if (!nativeToolDisplayEnabled) return false;
+	const override = process.env.PI_CURSOR_NATIVE_TOOL_DISPLAY;
+	if (override === "1" || override === "true") return true;
+	if (override === "0" || override === "false") return false;
+	return process.stdout.isTTY === true;
+}
+
+export function canRenderCursorToolNatively(toolName: string): boolean {
+	return NATIVE_CURSOR_TOOL_NAMES.has(toolName);
+}
+
+export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): void {
+	if (!nativeToolDisplayEnabled || !canRenderCursorToolNatively(item.toolName)) return;
+	nativeToolResults.set(item.id, item);
+}
+
+function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem | undefined {
+	const item = nativeToolResults.get(id);
+	if (item) nativeToolResults.delete(id);
+	return item;
+}
+
+export const __testUtils = {
+	reset(): void {
+		nativeToolDisplayEnabled = false;
+		nativeToolResults.clear();
+	},
+};
+
+function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
+	definition: ToolDefinition<TParams, TDetails, TState>,
+): ToolDefinition<TParams, TDetails, TState> {
+	return {
+		...definition,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const cursorDisplay = consumeCursorNativeToolDisplay(toolCallId);
+			if (cursorDisplay) {
+				return {
+					content: cursorDisplay.result.content,
+					details: cursorDisplay.result.details as TDetails,
+					terminate: cursorDisplay.terminate ?? true,
+				};
+			}
+			return definition.execute(toolCallId, params, signal, onUpdate, ctx);
+		},
+	};
+}
+
+export function registerCursorNativeToolDisplay(pi: ExtensionAPI): void {
+	nativeToolDisplayEnabled = true;
+	const cwd = process.cwd();
+	pi.registerTool(wrapNativeCursorTool(createReadToolDefinition(cwd)));
+	pi.registerTool(wrapNativeCursorTool(createBashToolDefinition(cwd)));
+	pi.registerTool(wrapNativeCursorTool(createLsToolDefinition(cwd)));
+}