pi-cursor-sdk 0.1.37 → 0.1.39

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## Unreleased
 
+## 0.1.39 - 2026-06-08
+
+### Fixed
+
+- Surface Cursor shell command starts with scrubbed command previews, including path-bearing commands, and stream bounded `shell-output-delta` stdout/stderr progress before completion so users do not stare at only pi's generic `Working...` state.
+- Mark generic Cursor SDK run failures and Cursor SDK network failures with pi-native retry classifier phrases so pi's existing auto-retry/backoff flow can recover transient failures automatically instead of requiring a manual follow-up message.
+
+## 0.1.38 - 2026-06-08
+
+### Added
+
+- Add shared Cursor replay result readers so transcript formatting, native replay cards, and activity builders consume the same MCP-like content/diff/file-preview extraction logic.
+- Add a canonical Cursor model lifecycle sync helper for session start, before-agent-start, model selection, and turn start registration paths.
+- Add lazy Cursor provider registration so extension startup can register models and commands without importing the Cursor SDK runtime until the provider is invoked.
+- Add shared Cursor native tool-name and pi-tool-bridge environment helpers for provider/runtime registration code.
+
+### Changed
+
+- Centralize Cursor tool presentation ownership in the typed presentation registry, including labels, aliases, lifecycle titles, replay metadata, side-effect policies, and web-tool classification.
+- Consolidate Cursor session cwd, session file/id, generation, and scope-key handling in `cursor-session-scope`; remove the older cwd/message-offset helper split.
+- Simplify Cursor session-agent lifecycle invalidation on model select, compaction preparation, tree navigation, shutdown, and scope changes.
+- Refine Cursor tool lifecycle/replay display routing so completed replay cards, inactive traces, native replay activation, and duplicate step/delta completions share one display path.
+- Keep Cursor agents-context dedup and fallback-catalog warning registration model-scoped through the shared lifecycle helper.
+- Keep edit/write replay previews on the shared structured diff/file preview renderers while retaining SDK expanded-text fallback behavior.
+- Update maintainer docs and repo map entries for the new ownership boundaries.
+
+### Fixed
+
+- Clear started Cursor tool calls when a completed delta reports the same tool under a different SDK call id, preventing stale native replay edit starts from surfacing as `Cursor edit did not complete` after successful final text.
+- Keep Cursor agents-context dedup registration in a tracked module so clean package builds resolve `src/index.ts` imports.
+- Accept Windows-rendered absolute `README.md` paths in platform-smoke grep-card detection without weakening prompt false-positive checks.
+- Preserve Cursor skill activation and question-tool registration through lazy provider/runtime import boundaries.
+- Preserve fast local discovery incomplete-tool suppression while still surfacing aborts, SDK failures, and no-text incomplete runs.
+
 ## 0.1.37 - 2026-06-06
 
 ### Changed

package/README.md

@@ -361,11 +361,11 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 
 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.
+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, and are phrased as pi retryable provider errors so automatic retry/backoff can recover transient SDK failures.
 
 Aborted runs now include a likely cause when determinable, for example `Cancelled: prompt interrupted.` for user cancel or `Cancelled: Cursor SDK run was cancelled.` for SDK-side cancellation.
 
-Network failures from the Cursor SDK connect layer (for example `ConnectError: read ETIMEDOUT` or `ConnectError: [aborted] read ECONNRESET`) surface as a scrubbed retry hint instead of crashing pi. Check your connection and retry; persistent failures may indicate a transient Cursor service or network issue.
+Network failures from the Cursor SDK connect layer (for example `ConnectError: read ETIMEDOUT` or `ConnectError: [aborted] read ECONNRESET`) surface as scrubbed `Network error` messages instead of crashing pi, matching pi's native auto-retry classifier. Persistent failures may indicate a transient Cursor service or network issue.
 
 You can also restart pi with a key in the same shell or launcher that starts pi:
 

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

@@ -29,7 +29,7 @@ Current implementation notes:
 - Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.17 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.17` `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.17` `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 also shown as bounded live progress while one shell call is active and used as display-only fallback for empty successful shell completions, while 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 native replay uses one neutral replay tool name, `cursor`, plus native-compatible card names when renderer-compatible (`read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`). Neutral replay identity lives in `activityTitle`, `activitySummary`, and typed replay details, not in extra registered tool names. 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.

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

@@ -70,7 +70,7 @@ Edit and write activity replays through pi-facing `edit` and `write` cards only
 
 Source of truth for SDK tool names: `@cursor/sdk@1.0.17` 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).
+Implementation owners: `src/cursor-tool-presentation-registry.ts` (canonical names, labels, visibility, replay policy, bridge exclusions for internal replay wrappers, alias normalization, and display-spec key completeness), `src/cursor-transcript-tool-specs.ts` (registry-keyed display implementations for transcript formatting and pi display builders), `src/cursor-native-tool-display-replay.ts` (replay card rendering derived from registry replay metadata), and `src/cursor-web-tool-activity.ts` (MCP/web alias remapping before display lookup).
 
 **Maintainer invariants — edit/write replay previews:** All colored diff rendering (native `edit` cards and `Cursor edit` activity fallbacks) flows through the single `formatCursorReplayDiff()` in `src/cursor-native-tool-display-replay.ts`. Activity write fallbacks with structured `fileContentAfterWrite` use the same `formatCursorReplayFilePreview()` path as native `write` cards. Structured `diffString` (and `diff`/`lines*`) or `fileContentAfterWrite` on `CursorReplay*Details` (including activity variants) is the source of truth for TUI preview coloring/highlighting. `expandedText` on activity details is for summary/expansion and as a fallback when the current SDK reports a unified diff only in text; it is never the primary preview source when structured fields are present. No parallel +/- coloring loops exist.
 
@@ -98,7 +98,7 @@ This matrix covers **Cursor native tool replay only**. It does not describe the
 | *(host/MCP alias)* `WebFetch` / `web_fetch` / similar | neutral activity | `cursor` | Collapsed label **Cursor web fetch**; display-only Cursor web access reported by the SDK, not an executable pi web tool |
 | _(no spec; future/unknown SDK name)_ | neutral activity | `cursor` | Collapsed label **Cursor** plus SDK tool name via `buildGenericPiToolDisplay()`; bounded fallback transcript only |
 
-**Unknown/future fallback path:** SDK tool names with no registry-backed `TOOL_DISPLAY_SPECS` entry (future or unknown types) use `buildGenericPiToolDisplay()` in `src/cursor-transcript-tool-specs.ts` with bounded `formatFallback()` content from `src/cursor-transcript-tool-formatters.ts`. Lookup uses `Object.hasOwn(TOOL_DISPLAY_SPECS, name)` so inherited object keys such as `constructor` or `toString` cannot accidentally match a registry spec. When native replay is enabled, those completions queue through neutral pi tool name `cursor` (not native pi `read`/`bash`/… cards). Collapsed labels read like **Cursor futureSemSearchWidget** (title `Cursor` plus the SDK tool name) with optional bounded `activitySummary` from scrubbed args/result lines. Errors keep `details.summary` undefined so unbounded raw errors do not leak into replay cards (#52). Known explicit specs still win over this path; real pi bridge tool names such as `edit` and `write` are not suppressed by internal replay-wrapper exclusions.
+**Unknown/future fallback path:** SDK tool names with no registry-backed display implementation entry (future or unknown types) use `buildGenericPiToolDisplay()` in `src/cursor-transcript-tool-specs.ts` with bounded `formatFallback()` content from `src/cursor-transcript-tool-formatters.ts`. Lookup uses `Object.hasOwn()` on the display implementation table so inherited object keys such as `constructor` or `toString` cannot accidentally match a registry spec. When native replay is enabled, those completions queue through neutral pi tool name `cursor` (not native pi `read`/`bash`/… cards). Collapsed labels read like **Cursor futureSemSearchWidget** (title `Cursor` plus the SDK tool name) with optional bounded `activitySummary` from scrubbed args/result lines. Errors keep `details.summary` undefined so unbounded raw errors do not leak into replay cards (#52). Known explicit specs still win over this path; real pi bridge tool names such as `edit` and `write` are not suppressed by internal replay-wrapper exclusions.
 
 **Replay detail disposition model:** `src/cursor-replay-tool-details.ts` stores replay card disposition separately from SDK source tool identity. Variants are `nativeEdit`, `nativeWrite`, `activity` (`sourceToolName` + display `title`), `generateImage`, and `genericFallback`. Path-only or notebook edit/write fallbacks produce `activity` details (neutral `cursor` cards) instead of structured edit/write variants with optional `title` escape hatches. Native edit/write cards use `nativeEdit` / `nativeWrite` only when pi-facing replay args satisfy the matching schema. The renderer dispatches on `variant` only.
 
@@ -106,7 +106,7 @@ Neutral activity rows use pi tool name `cursor` with `activityTitle` / `activity
 
 ## Runtime alias normalization
 
-Before lookup in `TOOL_DISPLAY_SPECS`, completed SDK tool names pass through `normalizeToolName()` in `src/cursor-transcript-utils.ts`. Documented aliases:
+Before display lookup, completed SDK tool names pass through `normalizeCursorToolName()` in `src/cursor-tool-presentation-registry.ts`; MCP web tool names are additionally remapped by `resolveTranscriptToolName()` in `src/cursor-web-tool-activity.ts`. Documented aliases:
 
 | Runtime alias | Canonical SDK name |
 | --- | --- |
@@ -169,7 +169,7 @@ Most Cursor tool visibility is completion-based: the completed replay card (or b
 Lifecycle rules:
 
 - Eligible tools include `task`, `shell`, `mcp`, `generateImage`, `recordScreen`, `semSearch`, web search/fetch activity, and plan/todo activity. Fast local tools such as `read`, `grep`, and `glob` do not get lifecycle lines in normal cases.
-- Lifecycle text is emitted as a single bounded, scrubbed thinking line such as `Cursor MCP: external_search` or `Cursor shell: shell`. Shell pending labels intentionally omit command text; the completed replay card remains the source of truth for recorded shell activity. Lifecycle lines are not separate permanent replay cards and do not rerun tools.
+- Lifecycle text is emitted as a single bounded, scrubbed thinking line such as `Cursor MCP: external_search` or `Cursor shell: npm test`. Shell pending labels show a scrubbed/truncated command preview, matching pi's native bash UX; the completed replay card remains the source of truth for recorded shell results. Lifecycle lines are not separate permanent replay cards and do not rerun tools.
 - A short defer window coalesces fast start+complete pairs: if a tool completes before the defer elapses, only the completed replay card/trace is shown.
 - pi bridge MCP calls (`pi__*`) are excluded because pi already shows the real pi tool execution path.
 - Implementation: `src/cursor-tool-lifecycle.ts` (eligibility/labels) and `src/cursor-provider-turn-coordinator.ts` (defer, emit, bridge exclusion).
@@ -180,7 +180,7 @@ As Cursor SDK tool completions arrive, the extension mirrors native Codex orderi
 
 Bridged pi tool calls follow the same visible pi `toolUse` turn shape, but they are real pi tool executions rather than replayed Cursor results. Split-run usage accounting keeps Cursor SDK internal counters out of pi usage: each live Cursor prompt is counted once, replay/bridge tool-call turns include visible assistant activity in output estimates, consumed tool results are counted once as input on the following assistant turn, and `usage.totalTokens` remains the replayable Cursor prompt/context estimate.
 
-For shell replay, completed `stdout` / `stderr` remain the primary source. If a successful completed shell result is empty and Cursor emitted unambiguous `shell-output-delta` data while exactly one shell call was active, the replay card uses that delta as display-only fallback data. Overlapping shell calls make delta attribution ambiguous, so those fallback deltas are dropped rather than guessed. `(no output)` is kept only when no completed output or safe delta fallback is available.
+For shell replay, completed `stdout` / `stderr` remain the primary source. While exactly one shell call is active, the provider also emits a bounded scrubbed preview of the first few `shell-output-delta` stdout/stderr chunks so long-running commands show visible progress before completion. If a successful completed shell result is empty, the replay card uses unambiguous buffered delta data as display-only fallback data. Overlapping shell calls make delta attribution ambiguous, so those fallback/progress deltas are dropped rather than guessed. `(no output)` is kept only when no completed output or safe delta fallback is available.
 
 Non-interactive and session consumers still receive bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
 

package/package.json

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

package/scripts/platform-smoke/card-detect.mjs

@@ -11,7 +11,7 @@ import { resolve } from "node:path";
 
 const CARD_PATTERNS = [
 	{ id: "read", pattern: /^\s*read (?:\.\/)?package\.json\s*$/i },
-	{ id: "grep", pattern: /^\s*grep \/pi-cursor-sdk\/ in README\.md\s*$/i },
+	{ id: "grep", pattern: /^\s*grep \/pi-cursor-sdk\/ in\s+(?:(?:\S+[\\/])?README\.md)\s*$/i },
 	{ id: "find", pattern: /^\s*find README\.md in\s+\S+/i },
 	{ id: "list", pattern: /^\s*(?:find \* in src|find src\/\* in \.|Get-ChildItem -Name \.\/src)\s*/i },
 	{ id: "shell-success", pattern: /^\s*cursor visual smoke\s*$/i },

package/src/context-window-cache.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { BUNDLED_CONTEXT_WINDOWS } from "./bundled-context-windows.js";
+import { asRecord } from "./cursor-record-utils.js";
 
 const CONTEXT_WINDOW_CACHE_FILE = "cursor-sdk-context-windows.json";
 let userContextWindowOverrideLoadCount = 0;
@@ -18,18 +19,16 @@ function isPositiveInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function parseContextWindowCacheFile(value: unknown): ContextWindowCacheFile | undefined {
-	if (!isRecord(value)) return undefined;
-	const { contextWindows } = value;
+	const record = asRecord(value);
+	if (!record) return undefined;
+	const { contextWindows } = record;
 	if (contextWindows === undefined) return {};
-	if (!isRecord(contextWindows)) return undefined;
+	const contextWindowRecord = asRecord(contextWindows);
+	if (!contextWindowRecord) return undefined;
 	return {
 		contextWindows: Object.fromEntries(
-			Object.entries(contextWindows).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
+			Object.entries(contextWindowRecord).filter((entry): entry is [string, number] => isPositiveInteger(entry[1])),
 		),
 	};
 }
@@ -68,12 +67,9 @@ export function getCachedContextWindow(modelId: string): number | undefined {
 }
 
 export function getCheckpointContextWindow(checkpoint: unknown): number | undefined {
-	if (!isRecord(checkpoint)) return undefined;
-	const { tokenDetails } = checkpoint;
-	if (!isRecord(tokenDetails)) return undefined;
-	const { maxTokens } = tokenDetails;
-	if (!isPositiveInteger(maxTokens)) return undefined;
-	return maxTokens;
+	const tokenDetails = asRecord(checkpoint)?.tokenDetails;
+	const maxTokens = asRecord(tokenDetails)?.maxTokens;
+	return isPositiveInteger(maxTokens) ? maxTokens : undefined;
 }
 
 export function saveCachedContextWindow(modelId: string, contextWindow: number): void {

package/src/context.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { SDKImage } from "@cursor/sdk";
-import { getCursorReplayPromptLabel } from "./cursor-tool-names.js";
+import { getCursorReplayPromptLabel } from "./cursor-tool-presentation-registry.js";
 
 export interface CursorPrompt {
 	text: string;

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

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "@cursor/sdk";
-import { asRecord, getArray, getString, stringifyUnknown } from "./cursor-transcript-utils.js";
+import { asRecord, getArray, getString } from "./cursor-record-utils.js";
+import { stringifyUnknown } from "./cursor-transcript-utils.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 
 const CURSOR_AGENT_MESSAGE_PAGE_LIMIT = 8;

package/src/cursor-agents-context-registration.ts

@@ -0,0 +1,18 @@
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+
+export type CursorAgentsContextExtensionApi = CursorModelLifecycleExtensionApi;
+
+export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
+	registerCursorModelLifecycle(pi, {
+		beforeAgentStart: async (event, ctx) => {
+			const { resolveCursorFacingSystemPrompt } = await import("./cursor-agents-context.js");
+			const resolved = resolveCursorFacingSystemPrompt(
+				event.systemPrompt,
+				ctx.model,
+				event.systemPromptOptions,
+			);
+			if (resolved === event.systemPrompt) return undefined;
+			return { systemPrompt: resolved };
+		},
+	});
+}

package/src/cursor-agents-context.ts

@@ -1,20 +1,17 @@
 import type {
-	BeforeAgentStartEvent,
-	BeforeAgentStartEventResult,
 	BuildSystemPromptOptions,
-	ExtensionAPI,
 	ExtensionContext,
-	ExtensionHandler,
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { parseEnvBoolean } from "./cursor-env-boolean.js";
 import { isCursorModel } from "./cursor-model.js";
 import {
-	cursorSettingSourcesLoadProjectAgentsRules,
-	cursorSettingSourcesLoadUserAgentsRules,
+	cursorSettingSourcesIncludes,
 	getEffectiveCursorSettingSources,
+	resolveCursorSettingSources,
 } from "./cursor-setting-sources.js";
 import type { SettingSource } from "@cursor/sdk";
+export { registerCursorAgentsContextDedup, type CursorAgentsContextExtensionApi } from "./cursor-agents-context-registration.js";
 
 export const CURSOR_PRESERVE_PI_AGENTS_MD_ENV = "PI_CURSOR_PRESERVE_PI_AGENTS_MD";
 
@@ -49,18 +46,24 @@ export function getAgentsContextFileBaseName(filePath: string): string {
 	return normalized.slice(normalized.lastIndexOf("/") + 1).toLowerCase();
 }
 
+function isPiAgentDirContextFilePath(
+	filePath: string,
+	fileName: "agents.md" | "claude.md",
+	agentDir: string = getAgentDir(),
+): boolean {
+	const normalized = normalizeContextPath(filePath);
+	const expectedPath = `${normalizeDirPath(agentDir)}/${fileName}`;
+	return normalized.toLowerCase() === expectedPath.toLowerCase();
+}
+
 /** Actual pi agent dir `AGENTS.md` — overlaps Cursor `user` setting source (global agent instructions). */
 export function isPiAgentDirAgentsMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
-	const normalized = normalizeContextPath(filePath);
-	const agentsMdPath = `${normalizeDirPath(agentDir)}/agents.md`;
-	return normalized.toLowerCase() === agentsMdPath.toLowerCase();
+	return isPiAgentDirContextFilePath(filePath, "agents.md", agentDir);
 }
 
 /** Actual pi agent dir `CLAUDE.md` — kept because Cursor user rules use `~/.claude/CLAUDE.md`. */
 export function isPiAgentDirClaudeMdPath(filePath: string, agentDir: string = getAgentDir()): boolean {
-	const normalized = normalizeContextPath(filePath);
-	const claudeMdPath = `${normalizeDirPath(agentDir)}/claude.md`;
-	return normalized.toLowerCase() === claudeMdPath.toLowerCase();
+	return isPiAgentDirContextFilePath(filePath, "claude.md", agentDir);
 }
 
 /**
@@ -87,9 +90,9 @@ export function shouldRemovePiAgentsContextFile(
 ): boolean {
 	switch (classifyContextFileOverlap(file.path, agentDir)) {
 		case "cursor-user-agents":
-			return cursorSettingSourcesLoadUserAgentsRules(settingSources);
+			return cursorSettingSourcesIncludes(settingSources, "user");
 		case "cursor-project-rules":
-			return cursorSettingSourcesLoadProjectAgentsRules(settingSources);
+			return cursorSettingSourcesIncludes(settingSources, "project");
 		default:
 			return false;
 	}
@@ -153,24 +156,12 @@ export function resolveCursorFacingSystemPrompt(
 ): string {
 	if (!systemPromptOptions) return systemPrompt;
 	const contextFiles = systemPromptOptions.contextFiles ?? [];
-	const settingSources = getEffectiveCursorSettingSources(settingSourcesRaw);
+	const settingSources =
+		settingSourcesRaw === undefined
+			? getEffectiveCursorSettingSources()
+			: resolveCursorSettingSources(settingSourcesRaw);
 	if (!shouldSuppressPiAgentsContext(model, contextFiles, settingSources, agentDir)) {
 		return systemPrompt;
 	}
 	return removePiAgentsContextFromSystemPrompt(systemPrompt, contextFiles, settingSources, agentDir);
 }
-
-type CursorAgentsContextExtensionApi = Pick<ExtensionAPI, "on">;
-
-export function registerCursorAgentsContextDedup(pi: CursorAgentsContextExtensionApi): void {
-	const handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult> = (event, ctx) => {
-		const resolved = resolveCursorFacingSystemPrompt(
-			event.systemPrompt,
-			ctx.model,
-			event.systemPromptOptions,
-		);
-		if (resolved === event.systemPrompt) return;
-		return { systemPrompt: resolved };
-	};
-	pi.on("before_agent_start", handler);
-}

package/src/cursor-edit-diff.ts

@@ -1,8 +1,10 @@
+import { asRecord } from "./cursor-record-utils.js";
+
 const CURSOR_EDIT_DIFF_FIELD_ORDER = ["diffString", "diff", "unifiedDiff", "patch"] as const;
 
 export function resolveCursorEditDiff(source: unknown): string | undefined {
-	if (!source || typeof source !== "object") return undefined;
-	const record = source as Record<string, unknown>;
+	const record = asRecord(source);
+	if (!record) return undefined;
 	for (const key of CURSOR_EDIT_DIFF_FIELD_ORDER) {
 		const value = record[key];
 		if (typeof value === "string" && value.length > 0) return value;

package/src/cursor-fallback-warning.ts

@@ -0,0 +1,22 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isCursorModel } from "./cursor-model.js";
+import { registerCursorModelLifecycle, type CursorModelLifecycleExtensionApi } from "./cursor-model-lifecycle.js";
+import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
+import type { CursorModelFallbackIssue } from "./model-discovery.js";
+
+export type CursorFallbackWarningExtensionApi = CursorModelLifecycleExtensionApi;
+
+export function registerCursorFallbackIssueWarning(
+	pi: CursorFallbackWarningExtensionApi,
+	issue: CursorModelFallbackIssue,
+): void {
+	const warnedSessionScopeKeys = new Set<string>();
+
+	registerCursorModelLifecycle(pi, (ctx: ExtensionContext) => {
+		if (!isCursorModel(ctx.model) || !ctx.hasUI) return;
+		const scopeKey = getCursorSessionScopeKey();
+		if (warnedSessionScopeKeys.has(scopeKey)) return;
+		warnedSessionScopeKeys.add(scopeKey);
+		ctx.ui.notify(issue.message, "warning");
+	});
+}

package/src/cursor-incomplete-tool-visibility.ts

@@ -1,4 +1,4 @@
-import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME } from "./cursor-tool-names.js";
+import { CURSOR_REPLAY_ACTIVITY_TOOL_NAME, getCursorToolActivityTitle } from "./cursor-tool-presentation-registry.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
 import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import {
@@ -10,7 +10,8 @@ import {
 	parseCursorReplayToolDetails,
 	resolveIncompleteReplayActivitySourceToolName,
 } from "./cursor-replay-tool-details.js";
-import { truncateArg, type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
+import { asRecord } from "./cursor-record-utils.js";
+import { type CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { classifyCursorToolVisibility } from "./cursor-tool-visibility.js";
 
 export type IncompleteCursorToolDiscardReason = DiscardedIncompleteStartedToolCallReason;
@@ -59,11 +60,6 @@ export function resolveIncompleteCursorToolVisibility(
 	return "emit";
 }
 
-function buildGenericIncompleteActivityTitle(displayName: string): string {
-	if (!displayName || displayName === "unknown") return "Cursor tool";
-	return `Cursor ${truncateArg(displayName)}`;
-}
-
 export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToolDiscardReason): string {
 	switch (reason) {
 		case DISCARDED_INCOMPLETE_TOOL_CALL_REASON:
@@ -79,7 +75,7 @@ export function formatIncompleteCursorToolReasonText(reason: IncompleteCursorToo
 
 export function getIncompleteCursorToolActivityTitle(toolCall: unknown): string {
 	const visibility = classifyCursorToolVisibility(toolCall);
-	return visibility.incompleteTitle ?? buildGenericIncompleteActivityTitle(visibility.displayName);
+	return visibility.incompleteTitle ?? getCursorToolActivityTitle(visibility.displayName);
 }
 
 export function buildIncompleteCursorToolDisplay(
@@ -124,8 +120,7 @@ export function formatIncompleteCursorToolTrace(display: CursorPiToolDisplay): s
 			formatIncompleteCursorToolReasonText(DISCARDED_INCOMPLETE_TOOL_CALL_REASON);
 		return `${truncateCursorDisplayLine(parsed.title)}: ${truncateCursorDisplayLine(summary)}\n`;
 	}
-	const details = display.result.details;
-	const detailRecord = details && typeof details === "object" ? (details as Record<string, unknown>) : undefined;
+	const detailRecord = asRecord(display.result.details);
 	const argsRecord = display.args;
 	const title =
 		(typeof detailRecord?.title === "string" && detailRecord.title.trim()) ||

package/src/cursor-live-run-coordinator.ts

@@ -7,7 +7,7 @@ import {
 	type CursorLiveRunAccountingState,
 	type CursorLiveToolResultConsumption,
 } from "./cursor-live-run-accounting.js";
-import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display.js";
+import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display-state.js";
 import type { CursorPiBridgeToolRequest, CursorPiToolBridgeRun } from "./cursor-pi-tool-bridge.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";

package/src/cursor-mcp-timeout-override.ts

@@ -151,8 +151,6 @@ export function restoreCursorMcpToolTimeoutOverride(): void {
 	installedConnectTimeoutMs = DEFAULT_CURSOR_MCP_CONNECT_TIMEOUT_MS;
 }
 
-export const restoreCursorMcpToolTimeoutOverrideForTests = restoreCursorMcpToolTimeoutOverride;
-
 export const cursorMcpToolTimeoutOverrideDefaults = {
 	cursorSdkDefaultTimeoutMs: CURSOR_SDK_MCP_DEFAULT_TIMEOUT_MS,
 	defaultOverrideTimeoutMs: DEFAULT_CURSOR_MCP_TOOL_TIMEOUT_MS,

package/src/cursor-model-lifecycle.ts

@@ -0,0 +1,72 @@
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	ExtensionContext,
+	ExtensionHandler,
+	SessionStartEvent,
+	TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+export type CursorModelLifecycleContext = ExtensionContext;
+
+type CursorModelSelectEvent = { model: ExtensionContext["model"] };
+
+type CursorModelLifecycleSyncHandler = (ctx: CursorModelLifecycleContext) => Promise<void> | void;
+type CursorModelSessionStartHandler = ExtensionHandler<SessionStartEvent>;
+type CursorModelSelectHandler = (event: CursorModelSelectEvent, ctx: CursorModelLifecycleContext) => Promise<void> | void;
+type CursorModelTurnStartHandler = ExtensionHandler<TurnStartEvent>;
+type CursorModelBeforeAgentStartHandler = ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>;
+
+export interface CursorModelLifecycleExtensionApi {
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "before_agent_start", handler: CursorModelBeforeAgentStartHandler): void;
+	on(event: "model_select", handler: (event: CursorModelSelectEvent, ctx: ExtensionContext) => Promise<void> | void): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+}
+
+export interface CursorModelLifecycleHandlers {
+	sessionStart?: CursorModelSessionStartHandler;
+	modelSelect?: CursorModelSelectHandler;
+	turnStart?: CursorModelTurnStartHandler;
+	sync?: CursorModelLifecycleSyncHandler;
+	beforeAgentStart?: CursorModelBeforeAgentStartHandler;
+}
+
+function normalizeLifecycleHandlers(
+	handlerOrHandlers: CursorModelLifecycleSyncHandler | CursorModelLifecycleHandlers,
+): CursorModelLifecycleHandlers {
+	return typeof handlerOrHandlers === "function" ? { sync: handlerOrHandlers } : handlerOrHandlers;
+}
+
+export function registerCursorModelLifecycle(
+	pi: CursorModelLifecycleExtensionApi,
+	handlerOrHandlers: CursorModelLifecycleSyncHandler | CursorModelLifecycleHandlers,
+): void {
+	const handlers = normalizeLifecycleHandlers(handlerOrHandlers);
+	const sync = handlers.sync;
+	if (handlers.sessionStart || sync) {
+		pi.on("session_start", async (event, ctx) => {
+			await handlers.sessionStart?.(event, ctx);
+			await sync?.(ctx);
+		});
+	}
+	if (handlers.modelSelect || sync) {
+		pi.on("model_select", async (event, ctx) => {
+			const effectiveCtx = { ...ctx, model: event.model };
+			await handlers.modelSelect?.(event, effectiveCtx);
+			await sync?.(effectiveCtx);
+		});
+	}
+	if (handlers.turnStart || sync) {
+		pi.on("turn_start", async (event, ctx) => {
+			await handlers.turnStart?.(event, ctx);
+			await sync?.(ctx);
+		});
+	}
+	if (handlers.beforeAgentStart || sync) {
+		pi.on("before_agent_start", async (event, ctx) => {
+			await sync?.(ctx);
+			return await handlers.beforeAgentStart?.(event, ctx);
+		});
+	}
+}

package/src/cursor-native-replay-routing.ts

@@ -1,4 +1,4 @@
-import { canRenderCursorToolNatively } from "./cursor-native-tool-display.js";
+import { canRenderCursorToolNatively } from "./cursor-native-tool-display-state.js";
 import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import type { Context } from "@earendil-works/pi-ai";
 

package/src/cursor-native-replay-trace.ts

@@ -1,4 +1,4 @@
-import type { CursorPiToolDisplay } from "./cursor-tool-transcript.js";
+import type { CursorPiToolDisplay } from "./cursor-transcript-utils.js";
 import { asRecord } from "./cursor-record-utils.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";