pi-cursor-sdk 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 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
+
+- Classify Cursor backend `ConnectError: [unavailable] Error` failures with code 14 and `aiserver.v1.ErrorDetails` as recoverable network/service errors, preventing duplicate process-level uncaught exceptions from crashing pi while still surfacing scrubbed retry guidance.
+
 ## 0.1.35 - 2026-06-05
 
 ### Changed

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

@@ -72,7 +72,7 @@ Source of truth for SDK tool names: `@cursor/sdk@1.0.17` conversation `ToolType`
 
 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).
 
-**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.
 
@@ -100,9 +100,9 @@ This matrix covers **Cursor native tool replay only**. It does not describe the
 
 **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.
 
-**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
 
@@ -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.35",
+	"version": "0.1.37",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",

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

@@ -103,7 +103,6 @@ export function buildIncompleteCursorToolDisplay(
 	return {
 		toolName: CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 		args: {
-			cursorToolName: visibility.normalizedName,
 			activityTitle,
 			activitySummary: reasonText,
 			incomplete: true,

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

@@ -8,9 +8,6 @@ import { LOCAL_READ_PREVIEW_NOTICE, isLocalReadPreviewContent } from "./cursor-t
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
 	getCursorReplayCallSummary,
-	getCursorReplaySideEffectDescription,
-	getCursorReplayOperationLabel,
-	getCursorReplayWrapperLabel,
 	type CursorReplayToolName,
 } from "./cursor-tool-presentation-registry.js";
 import {
@@ -28,24 +25,17 @@ import {
 
 export type {
 	CursorReplayNativeEditDetails,
-	CursorReplayEditDetails,
 	CursorReplayGenerateImageDetails,
 	CursorReplayGenericFallbackDetails,
 	CursorReplayActivityDetails,
-	CursorReplayTitledActivityDetails,
 	CursorReplayToolDetails,
 	CursorReplayNativeWriteDetails,
-	CursorReplayWriteDetails,
 } from "./cursor-replay-tool-details.js";
 export {
-	asCursorReplayToolDetails,
 	isCursorReplayNativeEditDetails,
-	isCursorReplayEditDetails,
 	isCursorReplayGenerateImageDetails,
 	isCursorReplayActivityDetails,
-	isCursorReplayTitledActivityDetails,
 	isCursorReplayNativeWriteDetails,
-	isCursorReplayWriteDetails,
 	parseCursorReplayToolDetails,
 } from "./cursor-replay-tool-details.js";
 
@@ -245,10 +235,8 @@ function formatCursorReplayActivityDiffPreview(
 	const body = (stripHeader ? stripCursorReplayHeader(text) : text).trimEnd();
 	const diffSection = body ? extractUnifiedDiffSection(body) : undefined;
 	if (!diffSection || !hasUnifiedDiffHunk(diffSection)) return undefined;
-	// Legacy-only shim (old JSONL with no diffString on the activity details).
-	// All actual diff coloring now lives in the single `formatCursorReplayDiff` renderer.
-	// This path exists solely so pre-structured sessions still get colored diffs via the same
-	// high-quality implementation used for nativeEdit and new structured activity cases.
+	// Fallback for unstructured activity details that carry a unified diff only in expanded text.
+	// All actual diff coloring lives in the single `formatCursorReplayDiff` renderer.
 	return formatCursorReplayDiff(diffSection, theme, maxLines);
 }
 
@@ -350,11 +338,11 @@ export function formatCursorReplayFilePreview(
 	return renderedLines.join("\n");
 }
 
-function getCursorReplayActivityTitle(toolName: CursorReplayToolName, args: Record<string, unknown> | undefined): string {
+function getCursorReplayCardTitle(toolName: CursorReplayToolName, args: Record<string, unknown> | undefined): string {
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME && typeof args?.activityTitle === "string" && args.activityTitle.trim()) {
 		return args.activityTitle.trim();
 	}
-	return getCursorReplayWrapperLabel(toolName);
+	return "Cursor activity";
 }
 
 export function renderCursorReplayCall(
@@ -364,7 +352,7 @@ export function renderCursorReplayCall(
 	isPartial: boolean,
 ): Text {
 	if (!isPartial) return new Text("", 0, 0);
-	let text = theme.fg("toolTitle", theme.bold(`${getCursorReplayActivityTitle(toolName, args)} `));
+	let text = theme.fg("toolTitle", theme.bold(`${getCursorReplayCardTitle(toolName, args)} `));
 	const summary = getCursorReplayCallSummary(toolName, args);
 	if (summary) text += theme.fg("accent", summary);
 	return new Text(text.trimEnd(), 0, 0);
@@ -602,19 +590,13 @@ export function renderNativeLookingCursorReadReplayResult(
 }
 
 export function createCursorReplayOnlyToolDefinition(toolName: CursorReplayToolName): ToolDefinition<typeof cursorReplayToolSchema, unknown> {
-	const cursorToolName = toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "activity" : getCursorReplayOperationLabel(toolName);
-	const sideEffectDescription = getCursorReplaySideEffectDescription(toolName);
 	return {
 		name: toolName,
-		label: getCursorReplayWrapperLabel(toolName),
-		description: `Replay display for a Cursor SDK ${cursorToolName} operation. This tool only returns recorded Cursor results and never executes ${sideEffectDescription} directly.`,
-		promptSnippet: `Render a recorded Cursor SDK ${cursorToolName} operation without executing ${sideEffectDescription}.`,
-		promptGuidelines: [
-			`Use this tool only for replaying Cursor SDK ${cursorToolName} results that were already produced by Cursor; it does not execute ${sideEffectDescription}.`,
-		],
+		label: "Cursor activity",
+		description: "Display recorded Cursor SDK tool activity. This tool only returns recorded Cursor results and never executes work directly.",
 		parameters: cursorReplayToolSchema,
 		async execute() {
-			throw new Error(`No recorded Cursor ${cursorToolName} result was available. This replay-only tool does not execute ${sideEffectDescription}.`);
+			throw new Error("No recorded Cursor activity result was available. This replay-only tool does not execute work directly.");
 		},
 		renderCall(args, theme, context) {
 			return renderCursorReplayCall(toolName, args as Record<string, unknown>, theme, context.isPartial);

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

@@ -13,7 +13,6 @@ import type { TSchema } from "typebox";
 import { getCursorSessionCwd } from "./cursor-session-cwd.js";
 import {
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	CURSOR_REPLAY_LEGACY_TOOL_NAMES,
 	isCursorReplayToolName,
 } from "./cursor-tool-names.js";
 import {
@@ -31,7 +30,7 @@ import {
 } from "./cursor-native-tool-display-state.js";
 
 const CURSOR_MODEL_ACTIVE_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
-const CURSOR_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME, ...CURSOR_REPLAY_LEGACY_TOOL_NAMES] as const;
+const CURSOR_REPLAY_TOOL_NAMES = [CURSOR_REPLAY_ACTIVITY_TOOL_NAME] as const;
 
 type AnyToolDefinition = ToolDefinition<TSchema, unknown, unknown>;
 type RenderCall = NonNullable<AnyToolDefinition["renderCall"]>;

package/src/cursor-provider-errors.ts

@@ -9,7 +9,7 @@ const GENERIC_CURSOR_SDK_ERROR_MESSAGE =
 const AUTH_CURSOR_SDK_ERROR_MESSAGE =
 	"Cursor SDK request failed because the Cursor SDK API key may be invalid or unauthorized. Cursor Agent CLI/Desktop login is not reused. Run /login -> Use an API key -> Cursor, verify CURSOR_API_KEY, or pass --api-key, then retry.";
 const NETWORK_CURSOR_SDK_ERROR_MESSAGE =
-	"Cursor SDK request timed out during network I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
+	"Cursor SDK request failed during network or service I/O. Check your connection and retry; if this keeps happening, try again later or verify Cursor service availability.";
 
 const GENERIC_CURSOR_RUN_FAILURE_TEXT = "cursor sdk run failed";
 
@@ -47,6 +47,10 @@ function isUnauthenticatedConnectCode(code: unknown): boolean {
 	return code === 16 || (typeof code === "string" && /^(?:16|unauthenticated)$/i.test(code));
 }
 
+function isUnavailableConnectCode(code: unknown): boolean {
+	return code === 14 || (typeof code === "string" && /^(?:14|unavailable)$/i.test(code));
+}
+
 function isCursorExtensionConnectStack(stack: string): boolean {
 	return stack.includes("@connectrpc/connect-node") && /(?:^|[\\/])pi-cursor-sdk(?:[\\/]|$)/.test(stack);
 }
@@ -101,6 +105,10 @@ export function classifyCursorConnectError(error: unknown): CursorConnectErrorCl
 		return { kind: "unauthenticated", source: getCursorConnectSource(error, record) };
 	}
 
+	if (isUnavailableConnectCode(code)) {
+		return { kind: "network", source: getCursorConnectSource(error, record) };
+	}
+
 	const causeCode = getErrorStringField(cause, "code");
 	const causeSyscall = getErrorStringField(cause, "syscall");
 	if (isLikelyNetworkTimeout(`${message}\n${rawMessage}\n${causeCode ?? ""}\n${causeSyscall ?? ""}`)) {
@@ -179,8 +187,9 @@ export function sanitizeCursorProviderError(error: unknown, apiKey?: string): st
 	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
 	if (message === MISSING_CURSOR_API_KEY_MESSAGE) return MISSING_CURSOR_API_KEY_MESSAGE;
 	const scrubbed = scrubSensitiveText(message, apiKey).trim();
-	if (isUnauthenticatedConnectError(error) || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	const connectClassification = classifyCursorConnectError(error);
+	if (connectClassification?.kind === "unauthenticated" || isLikelyAuthError(scrubbed)) return AUTH_CURSOR_SDK_ERROR_MESSAGE;
+	if (connectClassification?.kind === "network" || isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	if (isGenericErrorMessage(scrubbed)) return GENERIC_CURSOR_SDK_ERROR_MESSAGE;
-	if (isLikelyNetworkTimeout(scrubbed)) return NETWORK_CURSOR_SDK_ERROR_MESSAGE;
 	return scrubbed || GENERIC_CURSOR_SDK_ERROR_MESSAGE;
 }

package/src/cursor-replay-tool-details.ts

@@ -55,8 +55,6 @@ export interface CursorReplayGenerateImageDetails {
 	imageMimeType?: string;
 	summary?: string;
 	expandedText?: string;
-	/** Legacy parsed title retained on older payloads; display always uses `Cursor generateImage`. */
-	title?: string;
 	collapseDetailsByDefault?: boolean;
 }
 
@@ -79,7 +77,7 @@ export interface CursorReplayActivityDetails {
 	fileContentAfterWrite?: string;
 }
 
-/** Parsed replay details without a display title (legacy or malformed payloads). */
+/** Parsed replay details without a display title. */
 export interface CursorReplayGenericFallbackDetails {
 	variant: "genericFallback";
 	sourceToolName: CursorReplayUnknownSourceToolName;
@@ -94,21 +92,6 @@ export type CursorReplayToolDetails =
 	| CursorReplayActivityDetails
 	| CursorReplayGenericFallbackDetails;
 
-/** @deprecated Use {@link CursorReplayNativeEditDetails}. */
-export type CursorReplayEditDetails = CursorReplayNativeEditDetails;
-
-/** @deprecated Use {@link CursorReplayNativeWriteDetails}. */
-export type CursorReplayWriteDetails = CursorReplayNativeWriteDetails;
-
-/** @deprecated Use {@link CursorReplayActivityDetails}. */
-export type CursorReplayTitledActivityDetails = CursorReplayActivityDetails;
-
-/** @deprecated Use {@link CursorReplayActivitySourceToolName}. */
-export type CursorReplayActivityCursorToolName = CursorReplayActivitySourceToolName;
-
-/** @deprecated Use {@link CursorReplayUnknownSourceToolName}. */
-export type CursorReplayUnknownCursorToolName = CursorReplayUnknownSourceToolName;
-
 export type CursorReplayActivityDetailFields = Pick<
 	CursorReplayActivityDetails,
 	| "summary"
@@ -147,19 +130,12 @@ function readOptionalBoolean(record: Record<string, unknown>, key: string): bool
 	return typeof value === "boolean" ? value : undefined;
 }
 
-function readCurrentSourceToolName(record: Record<string, unknown>): string | undefined {
+function readSourceToolName(record: Record<string, unknown>): string | undefined {
 	const sourceToolName = readOptionalString(record, "sourceToolName");
 	return sourceToolName?.trim() ? sourceToolName.trim() : undefined;
 }
 
-function readLegacySourceToolName(record: Record<string, unknown>): string | undefined {
-	const sourceToolName = readCurrentSourceToolName(record);
-	if (sourceToolName) return sourceToolName;
-	const cursorToolName = readOptionalString(record, "cursorToolName");
-	return cursorToolName?.trim() ? cursorToolName.trim() : undefined;
-}
-
-function readLegacyVariant(record: Record<string, unknown>): string | undefined {
+function readVariant(record: Record<string, unknown>): string | undefined {
 	const variant = readOptionalString(record, "variant");
 	return variant?.trim() ? variant.trim() : undefined;
 }
@@ -191,7 +167,6 @@ function parseCursorReplayNativeWriteDetails(record: Record<string, unknown>): C
 }
 
 function parseCursorReplayGenerateImageDetails(record: Record<string, unknown>): CursorReplayGenerateImageDetails {
-	const title = readOptionalString(record, "title");
 	const collapseDetailsByDefault = readOptionalBoolean(record, "collapseDetailsByDefault");
 	return {
 		variant: "generateImage",
@@ -200,7 +175,6 @@ function parseCursorReplayGenerateImageDetails(record: Record<string, unknown>):
 		imageMimeType: readOptionalString(record, "imageMimeType"),
 		summary: readOptionalString(record, "summary"),
 		expandedText: readOptionalString(record, "expandedText"),
-		...(title !== undefined ? { title } : {}),
 		...(collapseDetailsByDefault !== undefined ? { collapseDetailsByDefault } : {}),
 	};
 }
@@ -263,37 +237,9 @@ export function resolveIncompleteReplayActivitySourceToolName(
 	return resolveParseActivitySourceToolName(sourceToolName);
 }
 
-function hasNativeEditChanges(record: Record<string, unknown>): boolean {
-	return Boolean(
-		readOptionalString(record, "diffString")?.trim()
-		|| readOptionalString(record, "diff")?.trim()
-		|| readOptionalNumber(record, "linesAdded")
-		|| readOptionalNumber(record, "linesRemoved"),
-	);
-}
-
-function parseLegacyEditDetails(record: Record<string, unknown>): CursorReplayToolDetails {
-	const title = readOptionalString(record, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(record, resolveParseActivitySourceToolName("edit"), title);
-	}
-	return parseCursorReplayNativeEditDetails(record);
-}
-
-function parseLegacyWriteDetails(record: Record<string, unknown>): CursorReplayToolDetails {
-	const title = readOptionalString(record, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(record, resolveParseActivitySourceToolName("write"), title);
-	}
-	return parseCursorReplayNativeWriteDetails(record);
-}
-
 type CursorReplayVariantParser = (record: Record<string, unknown>) => CursorReplayToolDetails | undefined;
 
-function parseActivityVariantDetails(
-	record: Record<string, unknown>,
-	readSourceToolName: (record: Record<string, unknown>) => string | undefined,
-): CursorReplayActivityDetails | undefined {
+function parseActivityVariantDetails(record: Record<string, unknown>): CursorReplayActivityDetails | undefined {
 	const title = readOptionalString(record, "title")?.trim();
 	if (!title) return undefined;
 	return parseCursorReplayActivityDetails(
@@ -307,75 +253,29 @@ const CURRENT_REPLAY_VARIANT_PARSERS: Readonly<Record<CursorReplayToolDetailsVar
 	nativeEdit: parseCursorReplayNativeEditDetails,
 	nativeWrite: parseCursorReplayNativeWriteDetails,
 	generateImage: parseCursorReplayGenerateImageDetails,
-	activity: (record) => {
-		if (!readCurrentSourceToolName(record) && readOptionalString(record, "cursorToolName")?.trim()) return undefined;
-		return parseActivityVariantDetails(record, readCurrentSourceToolName);
-	},
-	genericFallback: (record) => parseCursorReplayGenericFallbackDetails(record, readCurrentSourceToolName(record) ?? "tool"),
+	activity: parseActivityVariantDetails,
+	genericFallback: (record) => parseCursorReplayGenericFallbackDetails(record, readSourceToolName(record) ?? "tool"),
 };
 
-const LEGACY_REPLAY_VARIANT_UPGRADERS: Readonly<Record<string, CursorReplayVariantParser>> = {
-	edit: parseLegacyEditDetails,
-	write: parseLegacyWriteDetails,
-	titledActivity: (record) => parseActivityVariantDetails(record, readLegacySourceToolName),
-};
-
-export function parseStrictCurrentCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
+export function parseCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
 	if (!isRecord(value)) return undefined;
-	const variant = readLegacyVariant(value);
+	const variant = readVariant(value);
 	if (!variant) return undefined;
 	return CURRENT_REPLAY_VARIANT_PARSERS[variant as CursorReplayToolDetailsVariant]?.(value);
 }
 
-export function upgradeLegacyCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	if (!isRecord(value)) return undefined;
-	const explicitVariant = readLegacyVariant(value);
-	if (explicitVariant) {
-		return LEGACY_REPLAY_VARIANT_UPGRADERS[explicitVariant]?.(value);
-	}
-	const sourceToolName = readLegacySourceToolName(value);
-	if (sourceToolName === "edit") return parseLegacyEditDetails(value);
-	if (sourceToolName === "write") return parseLegacyWriteDetails(value);
-	if (sourceToolName === "generateImage") return parseCursorReplayGenerateImageDetails(value);
-	const title = readOptionalString(value, "title")?.trim();
-	if (title) {
-		return parseCursorReplayActivityDetails(
-			value,
-			resolveParseActivitySourceToolName(sourceToolName ?? CURSOR_REPLAY_UNREGISTERED_ACTIVITY_TOOL_NAME),
-			title,
-		);
-	}
-	if (sourceToolName === undefined && hasNativeEditChanges(value)) {
-		return parseCursorReplayNativeEditDetails(value);
-	}
-	return undefined;
-}
-
-export function parseCursorReplayToolDetails(value: unknown): CursorReplayToolDetails | undefined {
-	return parseStrictCurrentCursorReplayToolDetails(value) ?? upgradeLegacyCursorReplayToolDetails(value);
-}
-
-/** @deprecated Prefer {@link parseCursorReplayToolDetails} for validated narrowing. */
-export const asCursorReplayToolDetails = parseCursorReplayToolDetails;
-
 export function buildCursorReplayNativeEditDetails(
 	fields: Omit<CursorReplayNativeEditDetails, "variant">,
 ): CursorReplayNativeEditDetails {
 	return { variant: "nativeEdit", ...fields };
 }
 
-/** @deprecated Prefer {@link buildCursorReplayNativeEditDetails}. */
-export const buildCursorReplayEditDetails = buildCursorReplayNativeEditDetails;
-
 export function buildCursorReplayNativeWriteDetails(
 	fields: Omit<CursorReplayNativeWriteDetails, "variant">,
 ): CursorReplayNativeWriteDetails {
 	return { variant: "nativeWrite", ...fields };
 }
 
-/** @deprecated Prefer {@link buildCursorReplayNativeWriteDetails}. */
-export const buildCursorReplayWriteDetails = buildCursorReplayNativeWriteDetails;
-
 export function assembleCursorReplayActivityDetails(
 	sourceToolName: CursorReplayActivitySourceToolName,
 	title: string,
@@ -402,10 +302,7 @@ export function assembleCursorReplayActivityDetails(
 	};
 }
 
-/** @deprecated Prefer {@link assembleCursorReplayActivityDetails}. */
-export const assembleCursorReplayTitledActivityDetails = assembleCursorReplayActivityDetails;
-
-export const CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE = "Cursor generateImage" as const;
+export const CURSOR_REPLAY_GENERATE_IMAGE_RESULT_TITLE = "Cursor image generation" as const;
 
 export function assembleCursorReplayGenerateImageDetails(
 	fields: CursorReplayGenerateImageDetailFields,
@@ -430,18 +327,12 @@ export function isCursorReplayNativeEditDetails(
 	return details.variant === "nativeEdit";
 }
 
-/** @deprecated Prefer {@link isCursorReplayNativeEditDetails}. */
-export const isCursorReplayEditDetails = isCursorReplayNativeEditDetails;
-
 export function isCursorReplayNativeWriteDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayNativeWriteDetails {
 	return details.variant === "nativeWrite";
 }
 
-/** @deprecated Prefer {@link isCursorReplayNativeWriteDetails}. */
-export const isCursorReplayWriteDetails = isCursorReplayNativeWriteDetails;
-
 export function isCursorReplayGenerateImageDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayGenerateImageDetails {
@@ -454,9 +345,6 @@ export function isCursorReplayActivityDetails(
 	return details.variant === "activity";
 }
 
-/** @deprecated Prefer {@link isCursorReplayActivityDetails}. */
-export const isCursorReplayTitledActivityDetails = isCursorReplayActivityDetails;
-
 export function isCursorReplayGenericFallbackDetails(
 	details: CursorReplayToolDetails,
 ): details is CursorReplayGenericFallbackDetails {

package/src/cursor-tool-names.ts

@@ -1,18 +1,9 @@
 export {
-	CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME,
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	CURSOR_REPLAY_LEGACY_TOOL_NAMES,
-	getCursorReplayActivityLabelKey,
 	getCursorReplayActivityTitle,
-	getCursorReplayDisplayLabel,
 	getCursorReplayPromptLabel,
-	getCursorReplaySideEffectDescription,
-	getCursorReplayOperationLabel,
-	getCursorReplayWrapperLabel,
-	isCursorReplayLegacyToolName,
 	isCursorReplayToolName,
 	isExcludedFromCursorBridgeExposure,
 	type CursorReplayActivityToolName,
-	type CursorReplayLegacyToolName,
 	type CursorReplayToolName,
 } from "./cursor-tool-presentation-registry.js";

package/src/cursor-tool-presentation-registry.ts

@@ -57,8 +57,6 @@ export const CURSOR_REPLAY_ACTIVITY_TOOL_NAME = "cursor" as const;
 
 export type CursorWebToolKind = "webSearch" | "webFetch";
 
-export type CursorReplaySideEffectCategory = "file_mutations" | "real_tool_work";
-
 export type CursorToolLifecycleLabelKind =
 	| "task"
 	| "shell"
@@ -96,10 +94,6 @@ export interface CursorToolPresentationSpec {
 	normalizedName: CursorReplaySourceToolName;
 	/** Raw SDK/host names that resolve to this tool via {@link normalizeCursorToolName}. */
 	nameAliases?: readonly string[];
-	replayLegacyName?: string;
-	/** Human-readable SDK operation label for replay-only tool descriptions when it differs from {@link normalizedName}. */
-	replayOperationLabel?: string;
-	promptLabel: string;
 	displayLabel: string;
 	visibility: CursorToolVisibilityPolicy;
 	webKind?: CursorWebToolKind;
@@ -107,52 +101,43 @@ export interface CursorToolPresentationSpec {
 	webNamePatterns?: readonly RegExp[];
 	lifecycleLabelKind?: CursorToolLifecycleLabelKind;
 	replayCallSummary?: CursorReplayCallSummaryBuilder;
-	/** Short label for replay-only tool definitions (for example `edit` for `cursor_edit`). */
-	replayWrapperLabel?: string;
-	/** Whether replay-only wrappers describe file mutations or other recorded tool work. */
-	replaySideEffectCategory?: CursorReplaySideEffectCategory;
 	activityReplay?: CursorToolActivityReplaySpec;
 	generateImageReplay?: CursorToolGenerateImageReplaySpec;
 }
 
 const WEB_SEARCH_NAME_PATTERN =
-	/^(?:web[-_ ]?search|search[-_ ]?web|websearch|browser[-_ ]?search|cursor[-_ ]?web[-_ ]?search)$/i;
+	/^(?:web[-_ ]?search|search[-_ ]?web|websearch|browser[-_ ]?search)$/i;
 const WEB_FETCH_NAME_PATTERN =
-	/^(?:web[-_ ]?fetch|fetch[-_ ]?web|webfetch|browser[-_ ]?fetch|fetch[-_ ]?url|cursor[-_ ]?web[-_ ]?fetch)$/i;
+	/^(?:web[-_ ]?fetch|fetch[-_ ]?web|webfetch|browser[-_ ]?fetch|fetch[-_ ]?url)$/i;
 
 export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	{
 		normalizedName: "read",
 		nameAliases: ["read_file"],
-		promptLabel: "read",
 		displayLabel: "read",
 		visibility: { incompleteTitle: "Cursor read", fastLocalDiscovery: true },
 	},
 	{
 		normalizedName: "grep",
 		nameAliases: ["grep_search", "search"],
-		promptLabel: "grep",
 		displayLabel: "grep",
 		visibility: { incompleteTitle: "Cursor grep", fastLocalDiscovery: true },
 	},
 	{
 		normalizedName: "glob",
 		nameAliases: ["file_search"],
-		promptLabel: "glob",
 		displayLabel: "glob",
 		visibility: { incompleteTitle: "Cursor find", fastLocalDiscovery: true },
 	},
 	{
 		normalizedName: "ls",
 		nameAliases: ["list_dir"],
-		promptLabel: "ls",
 		displayLabel: "ls",
 		visibility: { incompleteTitle: "Cursor ls", fastLocalDiscovery: true },
 	},
 	{
 		normalizedName: "shell",
 		nameAliases: ["run_terminal_cmd", "terminal", "bash"],
-		promptLabel: "shell",
 		displayLabel: "shell",
 		visibility: {
 			incompleteTitle: "Cursor shell",
@@ -174,29 +159,19 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 			"notebook_edit",
 			"notebookedit",
 		],
-		replayLegacyName: "cursor_edit",
-		promptLabel: "Cursor edit",
 		displayLabel: "Cursor edit",
 		visibility: {},
-		replayWrapperLabel: "edit",
-		replaySideEffectCategory: "file_mutations",
 		replayCallSummary: withActivitySummaryFallback(summarizeReplayPath),
 	},
 	{
 		normalizedName: "write",
 		nameAliases: ["write_file", "writefile"],
-		replayLegacyName: "cursor_write",
-		promptLabel: "Cursor write",
 		displayLabel: "Cursor write",
 		visibility: {},
-		replayWrapperLabel: "write",
-		replaySideEffectCategory: "file_mutations",
 		replayCallSummary: withActivitySummaryFallback(summarizeReplayPath),
 	},
 	{
 		normalizedName: "delete",
-		replayLegacyName: "cursor_delete",
-		promptLabel: "Cursor delete",
 		displayLabel: "Cursor delete",
 		visibility: {},
 		replayCallSummary: withActivitySummaryFallback(summarizeReplayPath),
@@ -207,8 +182,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "readLints",
-		replayLegacyName: "cursor_read_lints",
-		promptLabel: "Cursor diagnostics",
 		displayLabel: "Cursor diagnostics",
 		visibility: {},
 		replayCallSummary: withActivitySummaryFallback(summarizeReplayReadLints),
@@ -219,8 +192,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "updateTodos",
-		replayLegacyName: "cursor_update_todos",
-		promptLabel: "Cursor todos",
 		displayLabel: "Cursor todos",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "updateTodos",
@@ -232,8 +203,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "createPlan",
-		replayLegacyName: "cursor_create_plan",
-		promptLabel: "Cursor plan",
 		displayLabel: "Cursor plan",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "createPlan",
@@ -245,8 +214,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "task",
-		replayLegacyName: "cursor_task",
-		promptLabel: "Cursor task",
 		displayLabel: "Cursor task",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "task",
@@ -258,8 +225,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "generateImage",
-		replayLegacyName: "cursor_generate_image",
-		promptLabel: "Cursor image generation",
 		displayLabel: "Cursor image generation",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "generateImage",
@@ -273,9 +238,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "mcp",
-		replayLegacyName: "cursor_mcp",
-		replayOperationLabel: "MCP",
-		promptLabel: "Cursor MCP",
 		displayLabel: "Cursor MCP",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "mcp",
@@ -287,8 +249,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "semSearch",
-		replayLegacyName: "cursor_sem_search",
-		promptLabel: "Cursor semantic search",
 		displayLabel: "Cursor semantic search",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "semSearch",
@@ -300,8 +260,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	},
 	{
 		normalizedName: "recordScreen",
-		replayLegacyName: "cursor_record_screen",
-		promptLabel: "Cursor screen recording",
 		displayLabel: "Cursor screen recording",
 		visibility: { lifecycleEligible: true },
 		lifecycleLabelKind: "recordScreen",
@@ -314,9 +272,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	{
 		normalizedName: "webSearch",
 		nameAliases: ["websearch", "web_search", "web-search"],
-		replayLegacyName: "cursor_web_search",
-		replayOperationLabel: "web search",
-		promptLabel: "Cursor web search",
 		displayLabel: "Cursor web search",
 		visibility: { lifecycleEligible: true },
 		webKind: "webSearch",
@@ -333,9 +288,6 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 	{
 		normalizedName: "webFetch",
 		nameAliases: ["webfetch", "web_fetch", "web-fetch"],
-		replayLegacyName: "cursor_web_fetch",
-		replayOperationLabel: "web fetch",
-		promptLabel: "Cursor web fetch",
 		displayLabel: "Cursor web fetch",
 		visibility: { lifecycleEligible: true },
 		webKind: "webFetch",
@@ -354,56 +306,19 @@ export const CURSOR_TOOL_PRESENTATION_SPECS = [
 type CursorToolPresentationSpecEntry = (typeof CURSOR_TOOL_PRESENTATION_SPECS)[number];
 
 export type CursorNormalizedToolName = CursorReplaySourceToolName;
+export type CursorReplayToolName = typeof CURSOR_REPLAY_ACTIVITY_TOOL_NAME;
 
-export type CursorReplayLegacyToolName = Extract<
-	CursorToolPresentationSpecEntry,
-	{ readonly replayLegacyName: string }
->["replayLegacyName"];
-
-export type CursorReplayToolName = typeof CURSOR_REPLAY_ACTIVITY_TOOL_NAME | CursorReplayLegacyToolName;
-
-type CursorToolPresentationSpecWithReplayLegacy = Extract<
+type CursorToolPresentationSpecWithNeutralActivity = Extract<
 	CursorToolPresentationSpecEntry,
-	{ readonly replayLegacyName: string }
->;
+	{ readonly activityReplay: CursorToolActivityReplaySpec } | { readonly generateImageReplay: CursorToolGenerateImageReplaySpec }
+> | Extract<CursorToolPresentationSpecEntry, { readonly normalizedName: "edit" | "write" }>;
 
-const CURSOR_REPLAY_ACTIVITY_SIDE_EFFECT_CATEGORY: CursorReplaySideEffectCategory = "file_mutations";
+export type CursorReplayActivityToolName = CursorToolPresentationSpecWithNeutralActivity["normalizedName"];
 
-function hasReplayLegacyName(spec: CursorToolPresentationSpecEntry): spec is CursorToolPresentationSpecWithReplayLegacy {
-	return "replayLegacyName" in spec;
+function hasNeutralActivityTitle(spec: CursorToolPresentationSpec): boolean {
+	return Boolean(spec.activityReplay || spec.generateImageReplay || spec.normalizedName === "edit" || spec.normalizedName === "write");
 }
 
-type ReplayActivityLabelKeysFromSpecs<Specs extends readonly CursorToolPresentationSpecEntry[]> = {
-	[K in Extract<Specs[number], { readonly replayLegacyName: string }>["normalizedName"]]: Extract<
-		Specs[number],
-		{ readonly replayLegacyName: string; normalizedName: K }
-	>["replayLegacyName"];
-};
-
-function buildReplayActivityLabelKeysByToolName<const Specs extends readonly CursorToolPresentationSpecEntry[]>(
-	specs: Specs,
-): ReplayActivityLabelKeysFromSpecs<Specs> {
-	const labelKeys: Record<string, CursorReplayLegacyToolName> = {};
-	for (const spec of specs) {
-		if (!hasReplayLegacyName(spec)) continue;
-		labelKeys[spec.normalizedName] = spec.replayLegacyName;
-	}
-	return labelKeys as ReplayActivityLabelKeysFromSpecs<Specs>;
-}
-
-const CURSOR_REPLAY_SPECS = CURSOR_TOOL_PRESENTATION_SPECS.filter(hasReplayLegacyName);
-
-/** Stable registration order for native replay tool wrappers (registry declaration order). */
-export const CURSOR_REPLAY_LEGACY_TOOL_NAMES: readonly CursorReplayLegacyToolName[] = CURSOR_REPLAY_SPECS.map(
-	(spec) => spec.replayLegacyName,
-);
-
-export const CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME = buildReplayActivityLabelKeysByToolName(
-	CURSOR_TOOL_PRESENTATION_SPECS,
-);
-
-export type CursorReplayActivityToolName = keyof typeof CURSOR_REPLAY_ACTIVITY_LABEL_KEYS_BY_TOOL_NAME;
-
 const SPECS_BY_NORMALIZED_NAME = new Map<string, CursorToolPresentationSpec>(
 	CURSOR_TOOL_PRESENTATION_SPECS.map((spec) => [spec.normalizedName, spec]),
 );
@@ -412,10 +327,6 @@ const SPECS_BY_NORMALIZED_KEY = new Map<string, CursorToolPresentationSpec>(
 	CURSOR_TOOL_PRESENTATION_SPECS.map((spec) => [spec.normalizedName.toLowerCase(), spec]),
 );
 
-const SPECS_BY_REPLAY_LEGACY_NAME = new Map<CursorReplayLegacyToolName, CursorToolPresentationSpec>(
-	CURSOR_REPLAY_SPECS.map((spec) => [spec.replayLegacyName, spec]),
-);
-
 const ALIAS_TO_NORMALIZED_NAME = new Map<string, CursorNormalizedToolName>(
 	CURSOR_TOOL_PRESENTATION_SPECS.flatMap((spec) => {
 		const aliases = "nameAliases" in spec ? spec.nameAliases : undefined;
@@ -437,11 +348,7 @@ export function getCursorToolPresentationSpec(
 ): CursorToolPresentationSpec | undefined {
 	const trimmed = name.trim();
 	if (!trimmed) return undefined;
-	return (
-		SPECS_BY_NORMALIZED_NAME.get(trimmed) ??
-		SPECS_BY_NORMALIZED_KEY.get(trimmed.toLowerCase()) ??
-		(isCursorReplayLegacyToolName(trimmed) ? SPECS_BY_REPLAY_LEGACY_NAME.get(trimmed) : undefined)
-	);
+	return SPECS_BY_NORMALIZED_NAME.get(trimmed) ?? SPECS_BY_NORMALIZED_KEY.get(trimmed.toLowerCase());
 }
 
 export function normalizeCursorToolName(name: string): string {
@@ -464,64 +371,21 @@ export function classifyCursorWebToolKind(name: string | undefined): CursorWebTo
 	return spec?.webKind;
 }
 
-const CURSOR_REPLAY_LEGACY_TOOL_NAME_SET: ReadonlySet<string> = new Set(CURSOR_REPLAY_LEGACY_TOOL_NAMES);
-
-export function isCursorReplayLegacyToolName(toolName: string): toolName is CursorReplayLegacyToolName {
-	return CURSOR_REPLAY_LEGACY_TOOL_NAME_SET.has(toolName);
-}
-
 export function isCursorReplayToolName(toolName: string): toolName is CursorReplayToolName {
-	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME || isCursorReplayLegacyToolName(toolName);
+	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME;
 }
 
 export function isExcludedFromCursorBridgeExposure(toolName: string): boolean {
-	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME || isCursorReplayLegacyToolName(toolName);
-}
-
-export function getCursorReplayWrapperLabel(toolName: CursorReplayToolName): string {
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return getCursorReplayDisplayLabel(toolName);
-	const spec = SPECS_BY_REPLAY_LEGACY_NAME.get(toolName);
-	return spec?.replayWrapperLabel ?? getCursorReplayDisplayLabel(toolName);
-}
-
-export function getCursorReplaySideEffectCategory(toolName: CursorReplayToolName): CursorReplaySideEffectCategory {
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return CURSOR_REPLAY_ACTIVITY_SIDE_EFFECT_CATEGORY;
-	return SPECS_BY_REPLAY_LEGACY_NAME.get(toolName)?.replaySideEffectCategory ?? "real_tool_work";
-}
-
-export function getCursorReplaySideEffectDescription(toolName: CursorReplayToolName): string {
-	return getCursorReplaySideEffectCategory(toolName) === "file_mutations" ? "file mutations" : "real tool work";
-}
-
-export function getCursorReplayOperationLabel(toolName: CursorReplayLegacyToolName): string {
-	const spec = SPECS_BY_REPLAY_LEGACY_NAME.get(toolName);
-	return spec?.replayOperationLabel ?? spec?.normalizedName ?? toolName;
+	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME;
 }
 
 export function getCursorReplayPromptLabel(toolName: string): string {
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return "Cursor activity";
-	if (isCursorReplayLegacyToolName(toolName)) {
-		const spec = SPECS_BY_REPLAY_LEGACY_NAME.get(toolName);
-		return spec?.promptLabel ?? toolName;
-	}
-	return toolName;
-}
-
-export function getCursorReplayDisplayLabel(toolName: CursorReplayToolName): string {
-	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) return "Cursor activity";
-	const spec = SPECS_BY_REPLAY_LEGACY_NAME.get(toolName);
-	return spec?.displayLabel ?? toolName;
-}
-
-export function getCursorReplayActivityLabelKey(toolName: string): CursorReplayLegacyToolName | undefined {
-	const spec = getCursorToolPresentationSpec(toolName);
-	if (!spec?.replayLegacyName || !isCursorReplayLegacyToolName(spec.replayLegacyName)) return undefined;
-	return spec.replayLegacyName;
+	return toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME ? "Cursor activity" : toolName;
 }
 
 export function getCursorReplayActivityTitle(toolName: string): string | undefined {
 	const spec = getCursorToolPresentationSpec(toolName);
-	if (!spec?.replayLegacyName) return undefined;
+	if (!spec || !hasNeutralActivityTitle(spec)) return undefined;
 	return spec.displayLabel;
 }
 
@@ -546,11 +410,11 @@ export function getCursorToolGenerateImageReplaySpec(normalizedKey: string): Cur
 }
 
 export function getCursorReplayCallSummary(
-	toolName: CursorReplayToolName,
+	toolName: CursorReplayToolName | CursorReplaySourceToolName,
 	args: CursorReplaySummaryArgs | undefined,
 ): string | undefined {
 	if (toolName === CURSOR_REPLAY_ACTIVITY_TOOL_NAME) {
 		return readCursorReplaySummaryString(args, "activitySummary") ?? summarizeReplayGenericActivity(args);
 	}
-	return SPECS_BY_REPLAY_LEGACY_NAME.get(toolName)?.replayCallSummary?.(args);
+	return getCursorToolPresentationSpec(toolName)?.replayCallSummary?.(args);
 }

package/src/cursor-transcript-tool-specs.ts

@@ -1,15 +1,12 @@
 import {
 	CURSOR_KNOWN_NORMALIZED_TOOL_NAMES,
 	CURSOR_REPLAY_ACTIVITY_TOOL_NAME,
-	getCursorReplayActivityLabelKey,
 	getCursorReplayActivityTitle,
 	getCursorReplayCallSummary,
-	getCursorReplayDisplayLabel,
 	getCursorToolActivityReplaySpec,
 	getCursorToolGenerateImageReplaySpec,
 	type CursorNormalizedToolName,
 	type CursorReplayActivityToolName,
-	type CursorReplayLegacyToolName,
 } from "./cursor-tool-presentation-registry.js";
 import { resolveCursorEditDiff } from "./cursor-edit-diff.js";
 import {
@@ -88,12 +85,6 @@ interface ToolDisplaySpec {
 	buildPiToolDisplay: (context: ToolDisplayContext) => CursorPiToolDisplay;
 }
 
-function requireReplayActivityLabelKey(normalizedName: CursorReplayActivityToolName): CursorReplayLegacyToolName {
-	const labelKey = getCursorReplayActivityLabelKey(normalizedName);
-	if (!labelKey) throw new Error(`Missing replay activity label for ${normalizedName}`);
-	return labelKey;
-}
-
 function textToolResult(text: string, details?: unknown): PiToolDisplayResult {
 	return { content: [{ type: "text", text }], details };
 }
@@ -112,10 +103,10 @@ function buildCursorActivityDisplayArgs(
 }
 
 function buildRegistryReplaySummary(
-	labelKey: CursorReplayLegacyToolName,
+	sourceToolName: CursorReplayActivityToolName,
 	args: CursorReplaySummaryArgs,
 ): string | undefined {
-	return getCursorReplayCallSummary(labelKey, args);
+	return getCursorReplayCallSummary(sourceToolName, args);
 }
 
 function buildReplaySummaryDisplay(
@@ -151,10 +142,9 @@ function buildActivityReplayDisplay(
 	const spec = TOOL_DISPLAY_SPECS[sourceToolName];
 	const activity = getCursorToolActivityReplaySpec(sourceToolName);
 	if (!activity) throw new Error(`Missing activity replay spec for ${sourceToolName}`);
-	const labelKey = requireReplayActivityLabelKey(sourceToolName);
-	const activityTitle = getCursorReplayDisplayLabel(labelKey);
+	const activityTitle = getCursorReplayActivityTitle(sourceToolName) ?? buildGenericUnknownToolActivityTitle(sourceToolName);
 	const replayArgs = activity.buildActivityArgs(context);
-	const activitySummary = buildRegistryReplaySummary(labelKey, replayArgs);
+	const activitySummary = buildRegistryReplaySummary(sourceToolName, replayArgs);
 	const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
 	const contentText = spec.formatTranscript(context).trimEnd();
 	const activityFields = activity.buildDetails(context, contentText);
@@ -173,10 +163,9 @@ function buildGenerateImageReplayDisplay(context: ToolDisplayContext): CursorPiT
 	const spec = TOOL_DISPLAY_SPECS.generateImage;
 	const replay = getCursorToolGenerateImageReplaySpec("generateImage");
 	if (!replay) throw new Error("Missing generate image replay spec");
-	const labelKey = requireReplayActivityLabelKey("generateImage");
-	const activityTitle = getCursorReplayDisplayLabel(labelKey);
+	const activityTitle = getCursorReplayActivityTitle("generateImage") ?? "Cursor image generation";
 	const replayArgs = replay.buildActivityArgs(context);
-	const activitySummary = buildRegistryReplaySummary(labelKey, replayArgs);
+	const activitySummary = buildRegistryReplaySummary("generateImage", replayArgs);
 	const activityArgs = buildCursorActivityDisplayArgs({ ...replayArgs }, activityTitle, activitySummary);
 	const contentText = spec.formatTranscript(context).trimEnd();
 	const details = assembleCursorReplayGenerateImageDetails(
@@ -201,11 +190,7 @@ function buildGenericPiToolDisplay(context: ToolDisplayContext): CursorPiToolDis
 	const fallbackBody = contentText.includes("\n\n") ? contentText.slice(contentText.indexOf("\n\n") + 2) : "";
 	const activitySummary =
 		result.status === "error" ? undefined : firstNonEmptyLine(fallbackBody);
-	const activityArgs = buildCursorActivityDisplayArgs(
-		{ cursorToolName: displayName === "unknown" ? "tool" : displayName },
-		activityTitle,
-		activitySummary,
-	);
+	const activityArgs = buildCursorActivityDisplayArgs({}, activityTitle, activitySummary);
 	const summary =
 		result.status === "error"
 			? undefined