pi-cursor-sdk 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.1.6 - 2026-05-10
+
+### Fixed
+
+- Avoid loading failures when another extension already owns `read`, `bash`, or `ls`; Cursor native replay now registers only non-conflicting wrappers and falls back to scrubbed activity transcripts for skipped tools.
+- `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` now skips Cursor native replay tool registration instead of only disabling replay at runtime.
+
 ## 0.1.5 - 2026-05-09
 
 ### Changed

package/README.md

@@ -210,7 +210,7 @@ Fallback models are a conservative startup model list. Actual Cursor runs still
 ## Limits
 
 - **Local Cursor SDK agents only.** This extension does not use Cursor cloud agents.
-- **Cursor-side tool use is not re-executed by pi.** Cursor still uses its own internal SDK tools. The extension records completed Cursor tool activity and, in interactive TTY sessions, replays supported `read`, `bash`, and `ls` activity through pi's native tool-call path with recorded results (for example green `read` and `$ ...` cards) without forcing Cursor to call pi tools or rerun commands. As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results immediately, then continuing with live post-tool Cursor thinking/text, any later Cursor tool batches, or Cursor's final answer as the next assistant turn. Non-interactive/session consumers still get bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
+- **Cursor-side tool use is not re-executed by pi.** Cursor still uses its own internal SDK tools. The extension records completed Cursor tool activity and, in interactive TTY sessions, replays supported `read`, `bash`, and `ls` activity through pi's native tool-call path with recorded results (for example green `read` and `$ ...` cards) without forcing Cursor to call pi tools or rerun commands. Native replay wrappers are registered only for tool names not already owned by another extension; skipped tools fall back to the scrubbed Cursor activity transcript. As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results immediately, then continuing with live post-tool Cursor thinking/text, any later Cursor tool batches, or Cursor's final answer as the next assistant turn. Non-interactive/session consumers still get bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
 - **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.
@@ -263,6 +263,16 @@ Fast mode is currently off. The footer only shows `cursor fast` when fast mode i
 
 They are not loaded by default in this extension. See [Limits](#limits).
 
+### Cursor native tool cards conflict with another extension
+
+Cursor native replay is a UI enhancement for interactive TTY sessions. If another extension already owns `read`, `bash`, or `ls`, this extension skips only the conflicting native replay wrapper and uses the scrubbed Cursor activity transcript for that tool instead. To disable Cursor native replay registration entirely, start pi with:
+
+```bash
+PI_CURSOR_NATIVE_TOOL_DISPLAY=0 pi --model cursor/composer-2
+```
+
+`PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is also accepted as a registration-only opt-out.
+
 ## Development
 
 Run checks:

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

@@ -17,7 +17,7 @@ Current implementation notes:
 - 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 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-side thinking remains visible. Cursor internal tool activity is recorded from SDK events and scrubbed. In interactive TTY sessions, supported completed `read`, `bash`, and `ls` activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native green cards without forcing Cursor to call pi tools or rerunning Cursor's reads/shell commands. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.5",
+	"version": "0.1.6",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

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

@@ -3,12 +3,16 @@ import {
 	createLsToolDefinition,
 	createReadToolDefinition,
 	type ExtensionAPI,
+	type ExtensionContext,
 	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"]);
+const NATIVE_CURSOR_TOOL_NAMES = ["read", "bash", "ls"] as const;
+type NativeCursorToolName = (typeof NATIVE_CURSOR_TOOL_NAMES)[number];
+const NATIVE_CURSOR_TOOL_DISPLAY_ENV = "PI_CURSOR_NATIVE_TOOL_DISPLAY";
+const NATIVE_CURSOR_TOOL_REGISTRATION_ENV = "PI_CURSOR_REGISTER_NATIVE_TOOLS";
 
 export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 	id: string;
@@ -16,26 +20,41 @@ export interface CursorNativeToolDisplayItem extends CursorPiToolDisplay {
 }
 
 let nativeToolDisplayEnabled = false;
+const registeredNativeToolNames = new Set<string>();
 const nativeToolResults = new Map<string, CursorNativeToolDisplayItem>();
 
+function readBooleanEnv(name: string): boolean | undefined {
+	const value = process.env[name]?.trim().toLowerCase();
+	if (value === "1" || value === "true" || value === "yes" || value === "on") return true;
+	if (value === "0" || value === "false" || value === "no" || value === "off") return false;
+	return undefined;
+}
+
+function isCursorNativeToolDisplayRequested(): boolean {
+	const override = readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV);
+	if (override !== undefined) return override;
+	return process.stdout.isTTY === true;
+}
+
+function isCursorNativeToolRegistrationRequested(): boolean {
+	if (readBooleanEnv(NATIVE_CURSOR_TOOL_REGISTRATION_ENV) === false) return false;
+	return isCursorNativeToolDisplayRequested();
+}
+
 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;
+	return isCursorNativeToolDisplayRequested() && registeredNativeToolNames.size > 0;
 }
 
 export function canRenderCursorToolNatively(toolName: string): boolean {
-	return NATIVE_CURSOR_TOOL_NAMES.has(toolName);
+	return registeredNativeToolNames.has(toolName);
 }
 
 export function recordCursorNativeToolDisplay(item: CursorNativeToolDisplayItem): void {
-	if (!nativeToolDisplayEnabled || !canRenderCursorToolNatively(item.toolName)) return;
+	if (!canRenderCursorToolNatively(item.toolName)) return;
 	nativeToolResults.set(item.id, item);
 }
 
@@ -48,6 +67,7 @@ function consumeCursorNativeToolDisplay(id: string): CursorNativeToolDisplayItem
 export const __testUtils = {
 	reset(): void {
 		nativeToolDisplayEnabled = false;
+		registeredNativeToolNames.clear();
 		nativeToolResults.clear();
 	},
 };
@@ -71,10 +91,55 @@ function wrapNativeCursorTool<TParams extends TSchema, TDetails, TState>(
 	};
 }
 
-export function registerCursorNativeToolDisplay(pi: ExtensionAPI): void {
-	nativeToolDisplayEnabled = true;
-	const cwd = process.cwd();
-	pi.registerTool(wrapNativeCursorTool(createReadToolDefinition(cwd)));
-	pi.registerTool(wrapNativeCursorTool(createBashToolDefinition(cwd)));
+function registerNativeCursorTool(pi: ExtensionAPI, toolName: NativeCursorToolName, cwd: string): void {
+	if (toolName === "read") {
+		pi.registerTool(wrapNativeCursorTool(createReadToolDefinition(cwd)));
+		return;
+	}
+	if (toolName === "bash") {
+		pi.registerTool(wrapNativeCursorTool(createBashToolDefinition(cwd)));
+		return;
+	}
 	pi.registerTool(wrapNativeCursorTool(createLsToolDefinition(cwd)));
 }
+
+function getExistingToolOwner(pi: ExtensionAPI, toolName: NativeCursorToolName): string | undefined {
+	const existingTool = pi.getAllTools().find((tool) => tool.name === toolName);
+	if (!existingTool || existingTool.sourceInfo.source === "builtin") return undefined;
+	return existingTool.sourceInfo.path ?? existingTool.sourceInfo.source;
+}
+
+function registerAvailableNativeCursorTools(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	if (!isCursorNativeToolRegistrationRequested()) {
+		nativeToolDisplayEnabled = false;
+		registeredNativeToolNames.clear();
+		return;
+	}
+
+	const cwd = process.cwd();
+	const skippedToolNames: string[] = [];
+	for (const toolName of NATIVE_CURSOR_TOOL_NAMES) {
+		if (registeredNativeToolNames.has(toolName)) continue;
+		const existingOwner = getExistingToolOwner(pi, toolName);
+		if (existingOwner) {
+			skippedToolNames.push(toolName);
+			continue;
+		}
+		registerNativeCursorTool(pi, toolName, cwd);
+		registeredNativeToolNames.add(toolName);
+	}
+
+	nativeToolDisplayEnabled = registeredNativeToolNames.size > 0;
+	if (skippedToolNames.length > 0 && readBooleanEnv(NATIVE_CURSOR_TOOL_DISPLAY_ENV) === true && ctx.hasUI) {
+		ctx.ui.notify(
+			`Cursor native tool replay skipped for ${skippedToolNames.join(", ")} because another extension already provides ${skippedToolNames.length === 1 ? "that tool" : "those tools"}. Cursor will use scrubbed activity transcripts for skipped tools.`,
+			"warning",
+		);
+	}
+}
+
+export function registerCursorNativeToolDisplay(pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx) => {
+		registerAvailableNativeCursorTools(pi, ctx);
+	});
+}