pi-cursor-sdk 0.1.36 → 0.1.38

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## 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
+
+- Cut Cursor native replay over to one canonical replay surface: neutral `cursor` activity cards plus native-compatible `read`, `bash`, `grep`, `find`, `ls`, `edit`, and `write` cards. Legacy `cursor_*` replay wrapper names, alias exports, old `cursorToolName` replay-detail parsing, and replay-only prompt metadata are removed instead of preserved behind compatibility shims (#123).
+- Keep edit/write replay previews on the shared structured diff/file preview renderers, while retaining unstructured `expandedText` unified-diff extraction only as a fallback for current SDK payloads that do not include structured diff fields.
+
+### Fixed
+
+- Stop registering duplicate replay-only prompt snippets/guidelines for every Cursor SDK activity wrapper, eliminating the inflated prompt metadata reported by issue #123 while preserving current TUI replay card titles, summaries, typed details, and `sourceToolName` display metadata.
+
 ## 0.1.36 - 2026-06-05
 
 ### Fixed

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

@@ -30,7 +30,7 @@ Current implementation notes:
 - 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.
-- 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 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.
 - 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.

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

@@ -70,9 +70,9 @@ 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 legacy JSONL compatibility only; it is never the primary preview source when structured fields are present. Legacy paths retain `extractUnifiedDiffSection` + delegation solely for old session JSONL that predates structured population; no parallel +/- coloring loops exist for new paths.
+**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.
 
 This matrix covers **Cursor native tool replay only**. It does not describe the [live pi MCP bridge](#live-bridge-vs-replay) or Cursor-native host tools, settings, plugins, and configured MCP servers from the Cursor SDK local-agent path.
 
@@ -98,15 +98,15 @@ 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; legacy payloads with `cursorToolName`/`title` are parsed into the matching disposition at the boundary.
+**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.
 
-Neutral activity rows use pi tool name `cursor` with `activityTitle` / `activitySummary` metadata. Legacy internal replay label keys such as `cursor_sem_search` are compatibility details; user-visible collapsed cards use labels like **Cursor semantic search**.
+Neutral activity rows use pi tool name `cursor` with `activityTitle` / `activitySummary` metadata. User-visible collapsed cards use labels like **Cursor semantic search**.
 
 ## 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 |
 | --- | --- |
@@ -184,15 +184,15 @@ For shell replay, completed `stdout` / `stderr` remain the primary source. If a
 
 Non-interactive and session consumers still receive bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
 
-## Synthetic-name policy
+## Replay-name policy
 
-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 that already contain old internal replay names are rewritten to safe labels in prompt text and display surfaces.
+Cursor native replay has one neutral replay tool name, `cursor`, plus native-compatible card names when renderer-compatible: `read`, `bash`, `grep`, `find`, `ls`, `edit`, and `write`. Neutral replay identity lives in `activityTitle`, `activitySummary`, and typed replay details, not in extra registered tool names.
 
 Bridge MCP names are also not pi tool names. Cursor may see names such as `pi__sem_reindex` inside the local MCP bridge, but pi session output uses the real pi tool name.
 
 ## Conflicts and opt out
 
-Native replay wrappers are registered only for tool names not already owned by another extension. If another extension already owns a wrapper name needed for replay, pi-cursor-sdk skips only the conflicting wrapper and uses the scrubbed Cursor activity transcript for that tool instead. Legacy replay wrappers remain registered for old sessions, but their model-facing and user-visible labels are sanitized.
+Native replay wrappers are registered only for tool names not already owned by another extension. If another extension already owns a wrapper name needed for replay, pi-cursor-sdk skips only the conflicting wrapper and uses the scrubbed Cursor activity transcript for that tool instead.
 
 Disable native replay registration entirely:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.36",
+	"version": "0.1.38",
 	"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(
@@ -103,7 +99,6 @@ export function buildIncompleteCursorToolDisplay(
 	return {
 		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 		args: {
-			cursorToolName: visibility.normalizedName,
 			activityTitle,
 			activitySummary: reasonText,
 			incomplete: true,
@@ -125,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";