pi-cursor-sdk 0.1.14 → 0.1.16

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

@@ -0,0 +1,99 @@
+# Cursor native tool replay
+
+pi-cursor-sdk has two separate pi-facing paths plus Cursor's own local-agent tool surface:
+
+1. **Local pi MCP bridge:** default-on for local Cursor agents. It exposes the current pi session's bridgeable active tools to Cursor through a tokenized `127.0.0.1` MCP endpoint, excluding internal Cursor replay activity names and, by default, overlapping built-in pi tools (`read`, `bash`, `write`, `edit`, `grep`, `find`, `ls`). When Cursor calls one of those MCP tools, pi executes the real pi tool through the normal pi tool path.
+2. **Cursor native tool replay:** display-only. It renders completed Cursor SDK tool activity as pi-native-looking cards using recorded Cursor results.
+
+This document is about replay. Replay is not execution and is not the local pi bridge.
+
+## Live bridge vs replay
+
+| Surface | Names Cursor can call | Names pi shows | IDs | Execution behavior |
+| --- | --- | --- | --- | --- |
+| Local pi MCP bridge | Live MCP names such as `pi__sem_reindex`, only when exposed in the current run | Real pi tool names such as `sem_reindex` | Bridge run and tool IDs begin with `cursor-pi-bridge-*` | Real pi execution through normal pi `toolCall` / `toolResult` flow |
+| Cursor native tool replay | None; replay names are not callable tools | Native-compatible card names or neutral Cursor activity labels | Replay IDs begin with `cursor-replay-*` | Display-only recorded Cursor results; no re-run, file mutation, MCP call, or pi state mutation |
+| Cursor-native host tools/settings/plugins/MCP | Cursor SDK local-agent tool names, as provided by Cursor | Only replay cards or transcript summaries when reported by the SDK | Cursor SDK-owned IDs | Neither pi bridge nor replay execution; owned by the Cursor SDK local agent path |
+
+Replay labels, replay cards, and transcript tool names are display-only/context-only. Bridge MCP names are also not pi tool names: Cursor must call the exposed `pi__*` MCP name, while pi history and cards use the real pi tool name.
+
+## Local pi bridge summary
+
+The bridge is enabled by default when bridgeable active pi tools exist. Cursor sees bridge-owned MCP names such as `pi__sem_reindex`, while pi history and tool cards use the real pi tool name such as `sem_reindex`. The bridge hides overlapping built-in pi tools by default because Cursor already has native equivalents; extension/custom tools and non-overlapping active tools present in pi's active tool registry normally remain exposed. pi-cursor-sdk also registers `cursor_ask_question` for Cursor models when the bridge is enabled, exposed to Cursor as `pi__cursor_ask_question`, so Cursor can ask the user to choose instead of silently defaulting when the pi UI is available. The bridge does not call pi tool `execute()` handlers directly; it queues the request, emits a real pi `toolCall`, waits for the matching pi `toolResult`, and resolves the Cursor MCP call back into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled.
+
+Rollback, timeout, and diagnostics controls:
+
+```bash
+PI_CURSOR_PI_TOOL_BRIDGE=0 pi --model cursor/composer-2.5
+PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 pi --model cursor/composer-2.5
+PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS=7200 pi --model cursor/composer-2.5
+PI_CURSOR_MCP_TOOL_TIMEOUT_MS=7200000 pi --model cursor/composer-2.5
+PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1 pi --model cursor/composer-2.5
+```
+
+`PI_CURSOR_PI_TOOL_BRIDGE=0` disables the bridge, including `pi__cursor_ask_question`. `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` opts in to exposing overlapping pi tool names that Cursor already has native equivalents for (`read`, `bash`, `write`, `edit`, `grep`, `find`, and `ls`). By default those names are hidden even when pi's Cursor replay wrapper has registered them as extension tools; non-overlapping active built-ins remain bridgeable by default. `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` emits typed, allowlisted, scrubbed single-line JSONL bridge diagnostics to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`; it is off by default, uses run-safe IDs that are not reused in endpoint paths, and does not print endpoint URLs/path components/tokens, raw args/results, file contents, or secrets. Cursor-native tools, Cursor settings, plugins, and configured Cursor MCP servers still come from the Cursor SDK local agent path. Cloud Cursor agents are out of scope for this bridge.
+
+## What gets replayed
+
+When Cursor reports completed tool activity, the extension can display recorded results for:
+
+- `read`
+- `bash`
+- `grep`
+- `find`
+- `ls`
+- `edit`
+- `write`
+- diagnostics
+- delete
+- todos and plans
+- tasks
+- image generation
+- MCP activity
+
+Cursor `glob` activity is displayed through native `find` cards.
+
+Edit and write activity replays through pi-facing `edit` and `write` cards only when replay arguments truthfully satisfy the matching pi schema, but still uses recorded Cursor results only. The adapter passes through truthful Cursor paths, content when Cursor reported it, and recorded diff/details; it does not pretend Cursor's editing schema is pi's schema and it fails closed if a recorded replay result is missing. Cursor `StrReplace` with recorded replacement text displays as native-looking `edit`; path-only Cursor `edit` and notebook edit activity fall back to neutral Cursor activity so pi does not reject the replay before recorded-result handling. Cursor `write` displays as native-looking `write`. Diagnostics, delete, todos/plans, task, image, and MCP activity use neutral Cursor activity cards with pi's default success/error tool shell. Neutral Cursor activity cards carry display metadata such as `activityTitle` and `activitySummary`, so partial/collapsed cards can say `Cursor plan`, `Cursor todos`, `Cursor MCP`, or `Cursor edit` instead of only `Cursor activity`. These replay tools only display recorded Cursor results; they never mutate files or execute tool work directly. Replay paths are normalized to workspace-relative paths when possible. Collapsed replay cards include bounded previews for diffs and text details so small edits, todos, task output, and MCP results are visible without expanding; edit previews omit raw unified diff headers and show compact numbered changed/context lines using pi's native diff added/removed/context colors, and write previews use syntax highlighting when pi can infer a language from the path. Image generation replay cards show the saved image path in the collapsed summary and render the image inline when pi terminal image display is enabled and the generated file is still readable.
+
+## What replay does not do
+
+Native replay is display-only:
+
+- pi does not re-run Cursor-side commands.
+- pi does not apply Cursor-side edits or deletes.
+- pi does not call Cursor-side MCP servers.
+- replay-only cards do not update pi state or generate images.
+- replay does not expose pi tool schemas to Cursor; the local pi MCP bridge is the separate path that exposes active pi tools.
+- Cursor workflow tools such as `SwitchMode` and Cursor todo state are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards do not drive pi plan-mode state.
+
+If a Cursor read completion reports no content, the extension may include a bounded local file preview for safe in-workspace paths. That preview is labeled as a local preview captured at transcript time, not guaranteed Cursor-observed content.
+
+Other unsupported Cursor SDK tools may still be described through a bounded scrubbed activity transcript when the SDK reports completed tool-call data. Started Cursor SDK tool calls that never receive a completion event are discarded without a synthetic replay error; missing completion is not itself treated as a Cursor tool failure. Explicit failures remain visible when Cursor reports an error through a completed tool call or step result. Some Cursor-internal workflow actions may only appear in Cursor's own thinking stream or not be reported as replayable SDK tool completions.
+
+## Ordering and non-interactive output
+
+As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results, then continuing with live post-tool Cursor thinking/text, later Cursor tool batches, or Cursor's final answer as the next assistant turn. For plan-mode runs, neutral Cursor plan/todo cards can therefore appear before the final Cursor plan text.
+
+Bridged pi tool calls follow the same visible pi `toolUse` turn shape, but they are real pi tool executions rather than replayed Cursor results. Split-run usage accounting keeps Cursor SDK internal counters out of pi usage: each live Cursor prompt is counted once, replay/bridge tool-call turns include visible assistant activity in output estimates, consumed tool results are counted once as input on the following assistant turn, and `usage.totalTokens` remains the replayable Cursor prompt/context estimate.
+
+For shell replay, completed `stdout` / `stderr` remain the primary source. If a successful completed shell result is empty and Cursor emitted unambiguous `shell-output-delta` data while exactly one shell call was active, the replay card uses that delta as display-only fallback data. Overlapping shell calls make delta attribution ambiguous, so those fallback deltas are dropped rather than guessed. `(no output)` is kept only when no completed output or safe delta fallback is available.
+
+Non-interactive and session consumers still receive bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.
+
+## Synthetic-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.
+
+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.
+
+Disable native replay registration entirely:
+
+```bash
+PI_CURSOR_NATIVE_TOOL_DISPLAY=0 pi --model cursor/composer-2.5
+```
+
+`PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is also accepted as a registration-only opt-out.

package/docs/cursor-native-tool-visual-audit.md

@@ -0,0 +1,183 @@
+# Cursor Native Tool Visual Audit Workflow
+
+This workflow verifies Cursor SDK tool replay the way a human sees it in pi's interactive TUI, without stealing macOS focus.
+
+Use it before accepting replay-card commits or PRs. Text logs and JSONL are necessary, but they are not enough when the claim is visual parity: always keep before/after PNGs for the exact prompt.
+
+## When to use this
+
+Use this workflow when changing or reviewing:
+
+- Cursor native tool replay cards.
+- Tool-call turn ordering.
+- Tool-result error styling.
+- Truncation, continuation hints, timeout labels, or path display.
+- Any PR claiming native TUI parity.
+
+Do not use this for ordinary unit-only logic changes.
+
+## Why this workflow exists
+
+Earlier manual verification used a visible Terminal window plus `screencapture`. That worked, but it stole system focus and made it easy for the user to type into the audit window by accident.
+
+The preferred workflow is now offscreen:
+
+1. Spawn `pi` in a pseudo-terminal at a fixed size.
+2. Feed the prompt programmatically.
+3. Save raw ANSI output and plain text output.
+4. Render the terminal buffer through xterm.js in headless Playwright.
+5. Save a PNG screenshot.
+6. Inspect the session JSONL for exact persisted `toolCall` / `toolResult` data.
+
+This gives human-like visual evidence without activating Terminal, iTerm, or a browser window.
+
+## Tool stack
+
+Install the harness outside this repo so generated assets and temporary dependencies do not pollute commits:
+
+```bash
+HARNESS=/tmp/pi-visual-harness
+rm -rf "$HARNESS"
+mkdir -p "$HARNESS"
+cd "$HARNESS"
+npm init -y
+npm install node-pty @xterm/xterm playwright
+npm rebuild node-pty
+```
+
+`npm rebuild node-pty` is useful after Node upgrades; without it, `node-pty` may fail with `posix_spawnp failed`.
+
+## Runner contract
+
+A runner script should:
+
+- Spawn `pi -e <extension-dir> --model cursor/composer-2.5` with:
+  - `PI_CURSOR_NATIVE_TOOL_DISPLAY=1`
+  - `TERM=xterm-256color`
+  - fixed PTY size, for example `150x45`
+  - cwd set to the target audit repo.
+- Wait for startup.
+- Write the exact prompt and carriage return to the PTY.
+- Wait a bounded amount of time.
+- Save:
+  - `<label>.ansi` raw terminal bytes.
+  - `<label>.txt` stripped text for quick search.
+  - `<label>.png` rendered xterm screenshot.
+  - `<label>.jsonl.path` pointing to the latest pi session JSONL.
+- Kill the PTY child after capture.
+- Check for leftover commands when prompts can background work, especially shell timeout tests.
+
+Example invocation shape:
+
+```bash
+node /tmp/pi-visual-harness/run-pi-visual.mjs \
+  --label after-shell-nonzero \
+  --ext /path/to/pi-cursor-sdk \
+  --cwd /path/to/test-workspace \
+  --prompt "Run \`printf 'cursor-shell-stderr\\n' >&2; exit 7\` using only the shell/terminal tool. Do not use read, grep, glob, find, ls, edit, or write. Print the command result exactly, then stop." \
+  --wait-ms 30000 \
+  --out-dir /tmp/pi-visual-harness/review-current
+```
+
+Keep the runner in `/tmp` unless the project explicitly decides to check in a maintained audit harness.
+
+## Before/after comparison
+
+Use a clean worktree for the baseline and the active worktree for the candidate change:
+
+```bash
+BASE=/tmp/pi-cursor-visual-review
+BEFORE_WT=$BASE/before-main
+AFTER_WT=/path/to/pi-cursor-sdk
+TARGET=/path/to/test-workspace
+
+rm -rf "$BASE"
+git fetch origin main
+BASE_COMMIT=$(git merge-base origin/main HEAD)
+git worktree add --detach "$BEFORE_WT" "$BASE_COMMIT"
+
+# Optional speedup when the before worktree has no install of its own.
+ln -s "$AFTER_WT/node_modules" "$BEFORE_WT/node_modules"
+```
+
+Then run the same prompt against both extension dirs:
+
+```bash
+node /tmp/pi-visual-harness/run-pi-visual.mjs \
+  --label before-glob-single \
+  --ext "$BEFORE_WT" \
+  --cwd "$TARGET" \
+  --prompt "Find files matching \`src/tools/reindex.ts\` using only the glob/file-search tool. Do not use shell, bash, grep, read, or ls. Print the matched files exactly as found, then stop." \
+  --wait-ms 16000 \
+  --out-dir /tmp/pi-visual-harness/review-current
+
+node /tmp/pi-visual-harness/run-pi-visual.mjs \
+  --label after-glob-single \
+  --ext "$AFTER_WT" \
+  --cwd "$TARGET" \
+  --prompt "Find files matching \`src/tools/reindex.ts\` using only the glob/file-search tool. Do not use shell, bash, grep, read, or ls. Print the matched files exactly as found, then stop." \
+  --wait-ms 16000 \
+  --out-dir /tmp/pi-visual-harness/review-current
+```
+
+For review, create a simple HTML/PNG gallery that places `before-*.png` and `after-*.png` side by side. Keep the generated gallery in `/tmp` unless explicitly asked to commit visual artifacts.
+
+## JSONL inspection
+
+For each visual claim, inspect the JSONL path written by the runner. Confirm at least:
+
+- `toolCall.name` is the expected pi-facing replay tool name.
+- `toolCall.arguments` show the expected user-facing args.
+- `toolResult.toolName` matches the call.
+- `toolResult.content[0].text` contains the recorded body expected in the card.
+- `toolResult.isError` matches the visual card state.
+
+For local pi MCP bridge claims, also confirm:
+
+- Bridged calls appear as the real pi tool name (for example `sem_reindex`), not the MCP bridge name (for example `pi__sem_reindex`; or `read`/`pi__read` when overlapping built-ins are explicitly exposed).
+- The JSONL has no second Cursor MCP replay card for the same bridged call.
+- Non-bridge Cursor MCP activity, if present, still renders as neutral Cursor activity instead of being suppressed.
+
+Small helper pattern:
+
+```bash
+python3 - <<'PY'
+import json, pathlib
+path = pathlib.Path('/tmp/pi-visual-harness/review-current/after-shell-nonzero.jsonl.path').read_text().strip()
+for line in pathlib.Path(path).read_text().splitlines():
+    obj = json.loads(line)
+    msg = obj.get('message', {})
+    if msg.get('role') == 'assistant':
+        for part in msg.get('content', []):
+            if part.get('type') == 'toolCall':
+                print('CALL', part.get('name'), part.get('arguments'))
+    if msg.get('role') == 'toolResult':
+        text = msg.get('content', [{}])[0].get('text', '')
+        print('RESULT', msg.get('toolName'), 'isError=', msg.get('isError'), repr(text[:160]))
+PY
+```
+
+## Safety rules
+
+- Prefer the offscreen PTY renderer. Do not use `osascript`, visible Terminal windows, or `screencapture` unless a user explicitly asks for a real desktop screenshot.
+- Keep generated screenshots, HTML galleries, ANSI logs, and temporary harness dependencies out of the repo by default.
+- Use short, deterministic prompts with bounded wait times.
+- For timeout/background prompts, always check for leftovers:
+
+```bash
+ps -axo pid,etime,command | rg "sleep 2|should-not-print|<audit-session-label>" || true
+```
+
+- If the model uses a different tool than requested, record it as model/provider behavior unless JSONL shows replay lost or misrendered a completed Cursor tool event.
+- Visual output can differ slightly from macOS Terminal fonts because xterm.js renders offscreen. Treat this workflow as evidence for card class, color state, labels, ordering, truncation, and content. Use a real terminal screenshot only for pixel-level terminal-specific bugs.
+
+## Required evidence before commit or merge
+
+Before accepting a replay-card change, provide:
+
+- Before and after PNG paths.
+- The prompt used for each pair.
+- JSONL paths for each run.
+- A short statement of what changed visually.
+- The relevant JSONL `toolCall` / `toolResult` facts.
+- `npm test` and `npm run typecheck` results, unless the change is documentation-only.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.14",
+	"version": "0.1.16",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -26,6 +26,9 @@
 		"scripts/refresh-cursor-model-snapshots.mjs",
 		"README.md",
 		"docs/cursor-model-ux-spec.md",
+		"docs/cursor-live-smoke-checklist.md",
+		"docs/cursor-native-tool-replay.md",
+		"docs/cursor-native-tool-visual-audit.md",
 		"LICENSE",
 		"CHANGELOG.md"
 	],
@@ -40,7 +43,8 @@
 		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs"
 	},
 	"dependencies": {
-		"@cursor/sdk": "^1.0.13"
+		"@cursor/sdk": "^1.0.13",
+		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/context.ts

@@ -1,5 +1,9 @@
+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 { getCursorPiBridgeContractText } from "./cursor-bridge-contract.js";
+import { getCursorReplayPromptLabel } from "./cursor-tool-names.js";
 
 export interface CursorPrompt {
 	text: string;
@@ -12,9 +16,14 @@ export interface CursorPromptOptions {
 	imageTokenEstimate?: number;
 }
 
-const DEFAULT_CHARS_PER_TOKEN = 4;
+export const CURSOR_APPROX_CHARS_PER_TOKEN = 4;
+export const CURSOR_IMAGE_TOKEN_ESTIMATE = 1200;
 const SECTION_SEPARATOR = "\n\n";
 
+function normalizePiContextMessages(messages: Context["messages"]): Message[] {
+	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+}
+
 function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
 	return block.type === "text";
 }
@@ -58,8 +67,26 @@ function formatContentBlocks(content: string | { type: string; text?: string; da
 }
 
 function formatToolCall(toolCall: ToolCall): string {
-	const args = JSON.stringify(toolCall.arguments);
-	return `Tool call (${toolCall.name}, call ${toolCall.id}): ${args}`;
+	const args = JSON.stringify(toolCall.arguments) ?? "";
+	return `Tool call (${getCursorReplayPromptLabel(toolCall.name)}, call ${toolCall.id}): ${args}`;
+}
+
+function sanitizeSystemPromptForCursor(systemPrompt: string): string {
+	let sanitized = systemPrompt;
+	sanitized = sanitized.replace(
+		/Available tools:\n[\s\S]*?\n\nIn addition to the tools above, you may have access to other custom tools depending on the project\.\n\n/g,
+		"Pi tool catalog omitted: Cursor can call only Cursor SDK tools exposed in this run.\n\n",
+	);
+	sanitized = sanitized.replace(
+		/Guidelines:\n[\s\S]*?\n\nPi documentation /g,
+		"Guidelines:\n- Be concise in your responses.\n- Show file paths clearly when working with files.\n\nPi documentation ",
+	);
+	sanitized = sanitized.replace(
+		/\n\nThe following skills provide specialized instructions for specific tasks\.[\s\S]*?<\/available_skills>/g,
+		"",
+	);
+	sanitized = sanitized.replace(/\n+Semantic code intelligence priority:[\s\S]*$/g, "");
+	return sanitized.trim();
 }
 
 function formatMessage(msg: Message): string | undefined {
@@ -84,7 +111,7 @@ function formatMessage(msg: Message): string | undefined {
 		case "toolResult": {
 			const text = formatContentBlocks(msg.content);
 			const label = msg.isError ? "Tool error" : "Tool result";
-			return `${label} (${msg.toolName}, call ${msg.toolCallId}): ${text}`;
+			return `${label} (${getCursorReplayPromptLabel(msg.toolName)}, call ${msg.toolCallId}): ${text}`;
 		}
 	}
 }
@@ -112,7 +139,7 @@ function applyPromptBudget(
 		return [...sectionsBeforeMessages, ...messageSections.map((section) => section.text), ...sectionsAfterMessages];
 	}
 
-	const charsPerToken = options.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+	const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
 	const maxChars = Math.max(1, Math.floor(maxInputTokens * charsPerToken));
 	const requiredMessageSections = messageSections.filter((section) => section.index === latestUserMessageIndex);
 	const requiredCost = [...sectionsBeforeMessages, ...requiredMessageSections.map((section) => section.text), ...sectionsAfterMessages].reduce(
@@ -148,22 +175,191 @@ function applyPromptBudget(
 	return [...sectionsBeforeMessages, ...budgetNotice, ...includedMessages, ...sectionsAfterMessages];
 }
 
+export function estimateCursorTextTokens(text: string, options: Pick<CursorPromptOptions, "charsPerToken"> = {}): number {
+	const charsPerToken = options.charsPerToken ?? CURSOR_APPROX_CHARS_PER_TOKEN;
+	return Math.ceil(text.length / charsPerToken);
+}
+
+export function estimateCursorPromptTokens(prompt: CursorPrompt, options: Pick<CursorPromptOptions, "charsPerToken" | "imageTokenEstimate"> = {}): number {
+	return estimateCursorTextTokens(prompt.text, options) + prompt.images.length * (options.imageTokenEstimate ?? CURSOR_IMAGE_TOKEN_ESTIMATE);
+}
+
+export function estimateCursorPromptMessageTokens(message: Message, options: Pick<CursorPromptOptions, "charsPerToken"> = {}): number {
+	const text = formatMessage(message);
+	return text ? estimateCursorTextTokens(text, options) : 0;
+}
+
+export function estimateCursorContextTokens(context: Context, options: CursorPromptOptions = {}): number {
+	return estimateCursorPromptTokens(buildCursorPrompt(context, options), options);
+}
+
+interface CursorContextFingerprintPayload {
+	systemHash: string;
+	messageHashes: string[];
+}
+
+function hashCursorContextValue(value: string): string {
+	return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function serializeMessageForFingerprint(message: Message, index: number): string {
+	switch (message.role) {
+		case "user": {
+			const text =
+				typeof message.content === "string"
+					? message.content
+					: JSON.stringify(message.content);
+			return hashCursorContextValue(`user:${message.timestamp ?? index}:${text}`);
+		}
+		case "assistant":
+			return hashCursorContextValue(`assistant:${message.timestamp ?? index}:${JSON.stringify(message.content)}`);
+		case "toolResult":
+			return hashCursorContextValue(
+				`toolResult:${message.timestamp ?? index}:${message.toolCallId}:${message.toolName}:${JSON.stringify(message.content)}:${message.isError === true}`,
+			);
+	}
+}
+
+function serializeRawPiMessageForFingerprint(message: Context["messages"][number], index: number): string {
+	const role = (message as { role?: string }).role;
+	switch (role) {
+		case "branchSummary": {
+			const entry = message as { summary?: string; fromId?: string; timestamp?: number };
+			return hashCursorContextValue(
+				`branchSummary:${entry.timestamp ?? index}:${entry.fromId ?? ""}:${entry.summary ?? ""}`,
+			);
+		}
+		case "compactionSummary": {
+			const entry = message as { summary?: string; tokensBefore?: number; timestamp?: number };
+			return hashCursorContextValue(
+				`compactionSummary:${entry.timestamp ?? index}:${entry.tokensBefore ?? ""}:${entry.summary ?? ""}`,
+			);
+		}
+		case "custom": {
+			const entry = message as { customType?: string; content?: unknown; timestamp?: number };
+			return hashCursorContextValue(
+				`custom:${entry.timestamp ?? index}:${entry.customType ?? ""}:${JSON.stringify(entry.content)}`,
+			);
+		}
+		case "bashExecution": {
+			const entry = message as {
+				command?: string;
+				output?: string;
+				exitCode?: number | null;
+				cancelled?: boolean;
+				excludeFromContext?: boolean;
+				timestamp?: number;
+			};
+			if (entry.excludeFromContext) {
+				return hashCursorContextValue(`bashExecution:excluded:${entry.timestamp ?? index}`);
+			}
+			return hashCursorContextValue(
+				`bashExecution:${entry.timestamp ?? index}:${entry.command ?? ""}:${entry.output ?? ""}:${entry.exitCode ?? ""}:${entry.cancelled === true}`,
+			);
+		}
+		default:
+			return serializeMessageForFingerprint(message as Message, index);
+	}
+}
+
+function parseCursorContextFingerprint(fingerprint: string): CursorContextFingerprintPayload | undefined {
+	try {
+		const parsed = JSON.parse(fingerprint) as CursorContextFingerprintPayload;
+		if (!parsed || typeof parsed.systemHash !== "string" || !Array.isArray(parsed.messageHashes)) return undefined;
+		if (!parsed.messageHashes.every((entry) => typeof entry === "string")) return undefined;
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+export function computeCursorContextFingerprint(context: Context): string {
+	const payload: CursorContextFingerprintPayload = {
+		systemHash: hashCursorContextValue(context.systemPrompt ?? ""),
+		messageHashes: context.messages.map((message, index) => serializeRawPiMessageForFingerprint(message, index)),
+	};
+	return JSON.stringify(payload);
+}
+
+export function shouldBootstrapCursorSend(
+	sendState: { bootstrapped: boolean; contextFingerprint: string },
+	context: Context,
+): boolean {
+	if (!sendState.bootstrapped) return true;
+	const previous = parseCursorContextFingerprint(sendState.contextFingerprint);
+	if (!previous) return true;
+	const current = parseCursorContextFingerprint(computeCursorContextFingerprint(context));
+	if (!current) return true;
+	if (current.systemHash !== previous.systemHash) return true;
+	if (current.messageHashes.length < previous.messageHashes.length) return true;
+	if (current.messageHashes.length > previous.messageHashes.length) {
+		for (let index = previous.messageHashes.length; index < context.messages.length; index += 1) {
+			const role = (context.messages[index] as { role?: string }).role;
+			if (role === "branchSummary" || role === "compactionSummary") return true;
+		}
+	}
+	for (let index = 0; index < previous.messageHashes.length; index += 1) {
+		if (current.messageHashes[index] !== previous.messageHashes[index]) return true;
+	}
+	return false;
+}
+
+export function buildCursorIncrementalPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
+	// Incremental sends omit the full Cursor SDK tool boundary block; the session agent retains prior bootstrap context.
+	const messages = normalizePiContextMessages(context.messages);
+	const latestUserMessageIndex = getLatestUserMessageIndex(messages);
+	const latestUserMessage = latestUserMessageIndex >= 0 ? messages[latestUserMessageIndex] : undefined;
+	const latestUserText = latestUserMessage ? formatMessage(latestUserMessage) : undefined;
+	const sectionsBeforeMessages = [
+		"Continue the conversation using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from earlier context as if they were available.",
+	];
+	if (context.systemPrompt) {
+		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
+	}
+	const latestUserMessageSections =
+		latestUserText && latestUserMessageIndex >= 0 ? [{ index: latestUserMessageIndex, text: latestUserText }] : [];
+	const images = extractLatestImages(messages);
+	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
+	const budgetOptions =
+		options.maxInputTokens === undefined
+			? options
+			: { ...options, maxInputTokens: Math.max(1, options.maxInputTokens - imageTokenReserve) };
+	const parts = applyPromptBudget(sectionsBeforeMessages, latestUserMessageSections, [], latestUserMessageIndex, budgetOptions);
+	return { text: parts.join(SECTION_SEPARATOR), images };
+}
+
+export function buildCursorSendPrompt(
+	context: Context,
+	options: CursorPromptOptions,
+	sendState: { bootstrapped: boolean; contextFingerprint: string },
+): { prompt: CursorPrompt; bootstrap: boolean } {
+	const bootstrap = shouldBootstrapCursorSend(sendState, context);
+	if (bootstrap) {
+		return { prompt: buildCursorPrompt(context, options), bootstrap: true };
+	}
+	return { prompt: buildCursorIncrementalPrompt(context, options), bootstrap: false };
+}
+
 export function buildCursorPrompt(context: Context, options: CursorPromptOptions = {}): CursorPrompt {
 	const sectionsBeforeMessages: string[] = [
 		[
 			"Cursor SDK tool boundary:",
-			"Only tools exposed by the Cursor SDK in this run are callable. The pi system prompt and transcript are context only; they do not grant access to pi tools or tool names mentioned there.",
-			"If the user asks you to search, fetch, browse, or research the web, use an actual Cursor SDK web/search/browser/MCP tool call. If no such Cursor SDK tool is available, say that web search is not configured for this Cursor SDK run.",
-			"Do not plan to use or claim to have used pi-only tools such as WebSearch or WebFetch unless the Cursor SDK actually exposes and executes that tool in this run.",
-			"Image payload boundary: only images attached to the latest user message are available as image bytes. Earlier images appear only as [image omitted from transcript] placeholders; ask the user to reattach or describe a prior image if the latest request depends on it.",
+			"You can call only tools actually exposed by Cursor SDK in this run. Pi tool names, replay tool names, and transcript tool names are context only, not callable capabilities.",
+			getCursorPiBridgeContractText(),
+			"If asked to list or exercise available tools, list and exercise Cursor SDK tools only; do not claim access to pi-side tools from the system prompt unless Cursor exposes an equivalent tool that runs.",
+			"Use pi__cursor_ask_question for material choices if exposed.",
+			"Web: use Cursor web/search/browser/MCP or say web search is not configured; do not claim WebSearch/WebFetch unless Cursor executes them.",
+			"Replay: pi may display recorded Cursor tool activity as pi-style cards, but replay is display-only and not a capability to invoke.",
+			"Images: only latest user images are sent; ask to reattach or describe prior images.",
 		].join("\n"),
 	];
 
 	if (context.systemPrompt) {
-		sectionsBeforeMessages.push(`System instructions from pi:\n${context.systemPrompt}`);
+		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
 	}
 
-	const messageSections = context.messages
+	const messages = normalizePiContextMessages(context.messages);
+	const messageSections = messages
 		.map((msg, index) => {
 			const text = formatMessage(msg);
 			return text ? { index, text } : undefined;
@@ -171,11 +367,11 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		.filter((section): section is { index: number; text: string } => section !== undefined);
 	const sectionsAfterMessages = [
 		[
-			"Answer the latest user request above using your capabilities. Do not assume access to pi tools.",
-			"If the user asks for web research, do not claim to have searched the web unless a Cursor SDK web/search/browser/MCP tool was actually used.",
+			"Answer the latest user request above using Cursor SDK capabilities only. Do not list, promise, or call pi-only tools from the system prompt as if they were available.",
+			"If web research is requested, do not claim it unless a Cursor web/search/browser/MCP tool ran.",
 		].join("\n"),
 	];
-	const images = extractLatestImages(context.messages);
+	const images = extractLatestImages(messages);
 	const imageTokenReserve = images.length * (options.imageTokenEstimate ?? 0);
 	const budgetOptions =
 		options.maxInputTokens === undefined
@@ -185,9 +381,11 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages,
 		messageSections,
 		sectionsAfterMessages,
-		getLatestUserMessageIndex(context.messages),
+		getLatestUserMessageIndex(messages),
 		budgetOptions,
 	);
+	const text = parts.join(SECTION_SEPARATOR);
 
-	return { text: parts.join(SECTION_SEPARATOR), images };
+
+	return { text, images };
 }

package/src/cursor-bridge-contract.ts

@@ -0,0 +1,27 @@
+export const CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX = "pi__";
+
+const CURSOR_PI_BRIDGE_CONTRACT_LINES = [
+	"Pi bridge contract:",
+	`${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* names are live Cursor MCP bridge tool names only when exposed in the current run.`,
+	`Call the ${CURSOR_PI_BRIDGE_MCP_TOOL_PREFIX}* MCP tool name, not the real pi tool name shown in pi history or transcripts.`,
+	"Bridged calls execute through normal pi tool flow, so pi shows the real pi tool name and returns a normal pi tool result.",
+	"Replay IDs, replay labels, and transcript tool names are display-only/context-only, not callable tools.",
+	"Cursor-native host tools, settings, plugins, and configured MCP servers are separate from the pi bridge.",
+] as const;
+
+export function getCursorPiBridgeContractText(): string {
+	return CURSOR_PI_BRIDGE_CONTRACT_LINES.join("\n");
+}
+
+export function buildCursorPiBridgeMcpToolDescription(options: {
+	piToolName: string;
+	mcpToolName: string;
+	piToolDescription: string;
+}): string {
+	return [
+		options.piToolDescription,
+		"",
+		getCursorPiBridgeContractText(),
+		`This run exposes real pi tool ${options.piToolName} as Cursor MCP tool ${options.mcpToolName}.`,
+	].join("\n");
+}