pi-cursor-sdk 0.3.6 → 0.3.8

package/docs/cursor-testing-lessons.md

@@ -33,7 +33,7 @@ When changing provider/runtime behavior, ask whether the bug spans **pi extensio
 Native replay routing intentionally uses two layers:
 
 1. **Extension resync** (`before_agent_start`, `turn_start`) updates pi's active tool set via `syncRegisteredNativeCursorToolsForModel`. This fixes the common case where plan-mode execute strips `grep`/`find`/`cursor` before the next turn.
-2. **Provider routing** uses the **`context.tools` snapshot** captured when `streamCursor()` starts (`getActiveContextToolNames` in `src/cursor-context-tools.ts`). It does not read live `pi.getActiveTools()` mid-stream.
+2. **Provider routing** uses the **request tool snapshot** captured when `streamCursor()` starts (`getActiveContextToolNames` in `src/cursor-context-tools.ts`): legacy `context.tools` on stock Pi 0.84/0.85, or tools replayed by the host's public helpers on transcript-only Pi. An explicit empty snapshot is not an absent legacy snapshot. It does not read live `pi.getActiveTools()` mid-stream. The bridge intentionally retains its separate registry-owned surface.
 
 `src/cursor-native-replay-routing.ts` centralizes provider-side routing against the same `context.tools` snapshot:
 
@@ -48,6 +48,28 @@ Disposition outcomes:
 
 If resync runs but `context.tools` is still stale (e.g. only `read` listed), the provider must **not** emit `toolUse` for inactive tools. `test/cursor-native-replay-stress.test.ts` covers that stale-snapshot path.
 
+## Stock/transcript provider contract
+
+`test/cursor-provider-pi-context.test.ts` drives real `ModelRuntime` / `ModelRegistry` requests into `streamCursor`, with only Cursor SDK execution mocked. Run it against each supported host with all Pi peer imports pinned to that host (including nested native imports); a top-level package version alone is not resolution evidence. Cover stock 0.84.0, stock 0.85.1, and the transcript host. Transcript-only cases are not stock features and are skipped there.
+
+The test covers bootstrap/incremental prompts, empty-vs-absent request tools, native replay/drain, cloud fresh/bootstrap selection, and actual host prompt serialization for context files and skills. It is offline contract evidence, not a replacement for the required live platform/cloud release gates.
+
+### Native package identity regression
+
+Pi's manifest loads the shipped `src/index.ts` graph, while scripts and programmatic consumers retain `dist/`. Native ESM imports of compiled JS can bypass Pi's host-peer aliases when another Pi version is installed beside the extension. A TypeScript wrapper around compiled JS does not fix transitive ownership. Do not remove local peers or use an import hook to turn this regression green.
+
+`test/native-package-host.test.ts` packs and normally installs the package with both 0.84.0 and 0.85.1 peers, then exercises the actual manifest via the installed development host's SDK and CLI (including the bundled CLI when shipped by that host; Pi 0.84 ships only the modular CLI). It also checks a minimal native managed install. For each additional pinned host, run the same offline probe against the installed tarball (not this checkout):
+
+```bash
+node scripts/check-pi-host-runtime.mjs /path/to/pi-coding-agent /path/to/installed/pi-cursor-sdk --out=/new/evidence/sdk
+node scripts/check-pi-host-runtime.mjs /path/to/pi-coding-agent /path/to/installed/pi-cursor-sdk --cli=modular --out=/new/evidence/modular
+node scripts/check-pi-host-runtime.mjs /path/to/pi-coding-agent /path/to/installed/pi-cursor-sdk --cli=bundled --out=/new/evidence/bundled
+```
+
+The probe asserts host stream identity, ordinary prompt/tool replay, recorded native tool emission and replay execution without reading the fixture path, final drain, lazy bridge/SDK/SQLite imports and bundled ripgrep lookup. The SDK lane also invokes the actual manifest-registered provider callback with no key, requiring the expected auth preflight error before SDK execution. It uses no import redirection and makes no Cursor requests. The recorded tool fixture is offline replay evidence, not a claim of a live SDK tool call.
+
+Every host must pass the common provider, context and replay checks. Add `--verify-fork-checkpoints` only to qualify the fork's native `SystemMessage.replace` support; explicit qualification fails on hosts lacking those semantics or transcript helpers. This additional host check is not a Cursor requirement. Published Pi 0.85.1 uses its supported shorthand context instead of synthetic transcript messages. None of these probes replaces the live platform gate.
+
 ## Auth: use `auth.json`, not only env
 
 pi resolves Cursor auth in this order:
@@ -171,6 +193,8 @@ Session summaries can hide per-message usage bugs. When investigating token or c
 
 The compaction poison fixture mirrors the observed failure shape: one assistant message with `RunResult`-sized input/cache-read counts near 1M immediately before compaction. Regression coverage should prove that such usage falls back to bounded pi estimates before it reaches `AssistantMessage.usage`.
 
+Compaction continuity needs content evidence, not just a new agent ID or a successful recall reply. The compaction smoke checks the returned and persisted summaries for the exact marker before recall, verifies the original user was cut and the native kept context has no other marker source, and checks the actual bootstrap inputs too. Both post-compaction and restart recall reject tool calls: retained session/debug files must not become a filesystem fallback. Keep the raw summary and journals on failure as well as success; an unchanged later model success does not erase an earlier summary-content failure or prove a deterministic provider fix.
+
 ### False-positive edge case (2026-05-23)
 
 Plan-strip live smoke can make Cursor `read` testing docs that *document* replay failure strings. A naive whole-record JSON scan reported four failures from one successful `read` toolResult (`isError: false`).

package/docs/platform-smoke-implementation.md

@@ -18,6 +18,8 @@ Required behavior:
 - fail when a card/evidence item has the wrong success/error state;
 - fail when footer/status is missing or unreadable.
 
+The plain-text card inventory uses Node's `stripVTControlCharacters` on the complete captured ANSI stream. OSC-8 hyperlinks may use either BEL or ST (ESC followed by a backslash) terminators, and a PTY chunk may split either sequence. Do not strip chunks independently or use a greedy OSC regex: that can consume the visible `package.json` label, successful read content, or subsequent cards even when xterm renders them correctly. Raw ANSI remains unchanged for independent xterm/PNG rendering and secret scanning; exact card patterns and JSONL success/error assertions still apply. `test/fixtures/platform-read-hyperlinks.json` retains minimal native/bridge headers from real captures with only the local hyperlink target anonymized.
+
 Meaningful gap closed: earlier card assertions could pass when the prompt mentioned `pi__read` or a missing-file path even if the actual tool card/result never rendered. The gate now requires JSONL result evidence and per-evidence rendered screenshots for native read, native shell success/failure, native edit diffs, bridge read success/failure, and bridge shell success.
 
 ## Registry visual classification

package/docs/platform-smoke.md

@@ -206,7 +206,7 @@ The copy/switch lane copies a session file containing resume custom entries, swi
 
 The fallback lane rewrites a persisted handle to a missing local SDK `agent-*`, verifies create+bootstrap fallback, and asserts the continuity notice is emitted in `pi-stream-events.jsonl`.
 
-The compaction lane uses an isolated temp pi settings file with `compaction.keepRecentTokens: 1` to force manual compaction without huge dummy prompts. It verifies the pre-compaction SDK agent is not reused, the new handle records `compactionGeneration: 1`, and restart resumes the post-compaction agent.
+The compaction lane uses an isolated temp pi settings file with `compaction.keepRecentTokens: 1` to force manual compaction without huge dummy prompts. Before recall, it requires the exact marker in both the returned and native persisted summary, agreement on the kept boundary, and removal of the original marker-bearing user from the kept context. Native `get_messages` and the subsequent captured provider inputs must supply the marker only through that summary. The post-compaction agent must bootstrap without reusing the baseline or captured summarizer agents, persist `compactionGeneration: 1`, and resume as the same agent after restart. Both recall turns must return the marker without tool calls, so searching retained QA files cannot satisfy continuity. The lane retains its journals/debug artifacts and `compaction-boundary.json` on success and failure.
 
 The default/opt-out lane verifies the built-in local resume default resumes, then verifies `PI_CURSOR_LOCAL_RESUME=0` opts out and creates a new agent while bootstrapping the transcript.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "pi provider extension backed by @cursor/sdk local and cloud agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
@@ -187,7 +187,7 @@
   },
   "pi": {
     "extensions": [
-      "./dist/index.js"
+      "./src/index.ts"
     ]
   },
   "allowScripts": {

package/scripts/build.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * Purpose: Produce the compiled runtime files that the Pi extension manifest loads.
+ * Purpose: Produce compiled runtime files for scripts and programmatic consumers.
+ * Pi's manifest loads the shipped source graph through its native TypeScript loader.
  * Responsibilities: Run TypeScript emit into a staging directory, then atomically swap it
  * into dist/ so a failed TypeScript emit never destroys a previously working dist.
  * Usage: `npm run build`; also invoked by scripts/prepare.mjs during install lifecycles.

package/scripts/lib/local-resume-smoke-harness.mjs

@@ -307,7 +307,7 @@ function metadataFiles(artifactDir) {
 	return files.sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
 }
 
-function readMetadataSince(artifactDir, seenPaths) {
+export function readMetadataSince(artifactDir, seenPaths) {
 	return metadataFiles(artifactDir)
 		.filter((metadataPath) => !seenPaths.has(metadataPath))
 		.map((metadataPath) => ({
@@ -383,11 +383,6 @@ export function resumeEntryCount(entries) {
 	return resumeEntries(entries).length;
 }
 
-export function compactionEntryCount(entries) {
-	return (entries.entries ?? []).filter((entry) => entry?.type === "compaction")
-		.length;
-}
-
 function entryText(entry) {
 	const content = entry?.message?.content;
 	if (typeof content === "string") return content;

package/scripts/local-resume-smoke.mjs

@@ -8,7 +8,6 @@ import {
 	assistantEntryContaining,
 	buildLocalResumeSmokeEnv,
 	cleanupArtifactRoot,
-	compactionEntryCount,
 	createRunContext,
 	fail,
 	getEntries,
@@ -17,6 +16,7 @@ import {
 	parseTimeout,
 	promptAbortAndRead,
 	promptAndRead,
+	readMetadataSince,
 	reportFailure,
 	resumeEntries,
 	scrubSmokeText,
@@ -514,10 +514,33 @@ async function runCompactionSmoke() {
 			});
 			assertTurnMetadata("compaction baseline", baseline, { resumedAgent: false });
 			preCompactionAgentId = baseline.metadata.run.agentId;
+			const originalUser = userEntryContaining(await getEntries(rpc), marker);
+			if (!originalUser) fail("compaction baseline did not persist the marker-bearing user message");
 			const result = await rpcData(rpc, "compact", { customInstructions: `Preserve the exact marker ${marker}.` }, timeoutMs);
-			if (!result.summary || typeof result.tokensBefore !== "number") fail("manual compaction did not return a summary result", JSON.stringify(result, null, 2));
 			const compactedEntries = await getEntries(rpc);
-			if (compactionEntryCount(compactedEntries) < 1) fail("manual compaction did not append a compaction entry");
+			const compaction = compactedEntries.entries.findLast((entry) => entry.type === "compaction");
+			const active = await rpcData(rpc, "get_messages");
+			const summarizerTurns = readMetadataSince(artifactRoot, seenMetadata);
+			// Save the native boundary before assertions or any recall turn can inspect files.
+			const boundaryPath = join(artifactRoot, "compaction-boundary.json");
+			writeFileSync(boundaryPath, JSON.stringify({ result, compaction, originalUserEntryId: originalUser.id, activeMessages: active.messages, summarizerTurns }, null, 2));
+			if (typeof result.summary !== "string" || typeof result.tokensBefore !== "number") fail("manual compaction did not return a summary result", boundaryPath);
+			if (!result.summary.includes(marker)) fail("returned compaction summary lost the exact marker", boundaryPath);
+			if (!compaction) fail("manual compaction did not append a compaction entry", boundaryPath);
+			if (typeof compaction.summary !== "string" || !compaction.summary.includes(marker)) fail("persisted compaction summary lost the exact marker", boundaryPath);
+			if (compaction.summary !== result.summary || compaction.firstKeptEntryId !== result.firstKeptEntryId) fail("returned and persisted compaction boundaries disagree", boundaryPath);
+			const originalIndex = compactedEntries.entries.findIndex((entry) => entry.id === originalUser.id);
+			const keptIndex = compactedEntries.entries.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+			const compactionIndex = compactedEntries.entries.indexOf(compaction);
+			if (originalIndex < 0 || keptIndex <= originalIndex || keptIndex >= compactionIndex) fail("compaction did not move the kept boundary past the original marker-bearing user", boundaryPath);
+			// Ask the host for its active messages; do not reproduce its cut/replay algorithm.
+			const summaryMessage = active.messages.find((message) => message.role === "compactionSummary" && message.summary === compaction.summary);
+			if (!summaryMessage) fail("native active context does not contain the persisted compaction summary", boundaryPath);
+			if (active.messages.some((message) => message !== summaryMessage && JSON.stringify(message).includes(marker))) fail("kept context independently supplies the compaction marker", boundaryPath);
+			for (const turn of summarizerTurns) {
+				assertNotResumedFrom("compaction summarizer", turn, preCompactionAgentId);
+				seenMetadata.add(turn.metadataPath);
+			}
 
 			const postCompaction = await promptAndRead({
 				rpc,
@@ -527,6 +550,19 @@ async function runCompactionSmoke() {
 				seenMetadata,
 			});
 			assertNotResumedFrom("post-compaction turn", postCompaction, preCompactionAgentId);
+			for (const turn of summarizerTurns) assertNotResumedFrom("post-compaction turn versus summarizer", postCompaction, turn.metadata.run.agentId);
+			if (postCompaction.metadata.providerMeta?.sendPlan?.mode !== "bootstrap") fail("post-compaction turn did not bootstrap the compacted context", postCompaction.metadataPath);
+			// Inspect the actual provider inputs too: the native summary must be the only marker source.
+			const postDir = dirname(postCompaction.metadataPath);
+			const escapedSummary = JSON.stringify(compaction.summary).slice(1, -1);
+			for (const file of ["context-snapshot.json", "send-payload.json"]) {
+				const path = join(postDir, file);
+				const input = JSON.stringify(JSON.parse(readFileSync(path, "utf8")));
+				if (!input.includes(escapedSummary)) fail("post-compaction input omitted the persisted summary", path);
+				if (input.replace(escapedSummary, "").includes(marker)) fail("post-compaction input independently supplies the marker outside the summary", path);
+			}
+			const postSteps = readFileSync(join(postDir, "on-step.jsonl"), "utf8").split("\n").filter(Boolean).map(JSON.parse);
+			if (postSteps.some((row) => row.step?.type === "toolCall")) fail("post-compaction recall used tools instead of summary-only recall", postCompaction.metadataPath);
 			if (!postCompaction.text.includes(`MARKER=${marker}`)) fail("post-compaction turn did not recall marker", JSON.stringify({ expected: `MARKER=${marker}`, actual: postCompaction.text }, null, 2));
 			postCompactionAgentId = postCompaction.metadata.run.agentId;
 			const postHandle = latestResumeEntry(await getEntries(rpc));
@@ -544,11 +580,14 @@ async function runCompactionSmoke() {
 			});
 			assertTurnMetadata("post-compaction restart", restart, { resumedAgent: true });
 			if (restart.metadata.run.agentId !== postCompactionAgentId) fail("post-compaction restart did not resume the post-compaction agent", JSON.stringify({ expected: postCompactionAgentId, actual: restart.metadata.run.agentId }, null, 2));
+			const restartSteps = readFileSync(join(dirname(restart.metadataPath), "on-step.jsonl"), "utf8").split("\n").filter(Boolean).map(JSON.parse);
+			if (restartSteps.some((row) => row.step?.type === "toolCall")) fail("post-compaction restart used tools instead of recalling the marker", restart.metadataPath);
+			if (!restart.text.includes(`MARKER=${marker}`)) fail("post-compaction restart did not recall marker", JSON.stringify({ expected: `MARKER=${marker}`, actual: restart.text }, null, 2));
 		});
 		console.log("local-resume-compaction-smoke-ok");
 		console.error(scrubSmokeText(`[local-resume-smoke] pre-compaction ${preCompactionAgentId} replaced by and resumed post-compaction ${postCompactionAgentId}`));
 	} finally {
-		cleanupArtifactRoot(artifactRoot);
+		console.error(scrubSmokeText(`[local-resume-smoke] retained compaction evidence: ${artifactRoot}`));
 	}
 }
 

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

@@ -8,6 +8,7 @@
 
 import { writeFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 import { matchesWrappedLineAt } from "./wrapped-line-match.mjs";
 
 const CARD_PATTERNS = [
@@ -35,10 +36,7 @@ const CARD_PATTERNS = [
 ];
 
 function cleanLine(line) {
-	return line
-		.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "")
-		.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
-		.replace(/\r/g, "");
+	return stripVTControlCharacters(line).replace(/\r/g, "");
 }
 
 function matchesCardAt(lines, index, card) {

package/scripts/platform-smoke/live-suite-runner.mjs

@@ -13,6 +13,7 @@ import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSy
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
+import { stripVTControlCharacters } from "node:util";
 import { redactSecrets, writePlatformArtifactBundle } from "./artifacts.mjs";
 import { extractContentText, jsonlHasAssistantFinalTextMarker } from "./jsonl-text.mjs";
 import { getScenario, renderPrompt } from "./scenarios.mjs";
@@ -237,10 +238,6 @@ function prepareSharedPackedInstall(prepDir, logDir, artifactDir, packageName) {
 	return prepared;
 }
 
-function stripANSI(text) {
-	return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "");
-}
-
 function ptySpawnCommand(args) {
 	const cliEntry = resolve(process.cwd(), "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
 	if (!existsSync(cliEntry)) throw new Error(`Pi CLI entry not found: ${cliEntry}`);
@@ -278,7 +275,6 @@ async function runPtyPi({ artifactDir, ptyCommand, env, cwd, sessionDir, finalMa
 	}
 
 	let ansi = "";
-	let plain = "";
 	const events = [];
 	const startedAt = Date.now();
 	const { file, args } = ptyCommand;
@@ -297,7 +293,6 @@ async function runPtyPi({ artifactDir, ptyCommand, env, cwd, sessionDir, finalMa
 	let exitEvent;
 	child.onData((data) => {
 		ansi += data;
-		plain += stripANSI(data);
 		events.push({ type: "output", elapsedMs: Date.now() - startedAt, bytes: data.length });
 	});
 	child.onExit((event) => {
@@ -313,7 +308,9 @@ async function runPtyPi({ artifactDir, ptyCommand, env, cwd, sessionDir, finalMa
 	let abortObserved = false;
 	const abortStartedPath = join(cwd, ".debug", "platform-smoke", "abort-started.txt");
 	while (Date.now() - startedAt < waitMs) {
-		const currentPlain = plain;
+		// PTY chunks may split an OSC-8 link. Strip the complete captured stream,
+		// not individual chunks, and preserve the label between open/close links.
+		const currentPlain = stripVTControlCharacters(ansi);
 		const responsePlain = currentPlain.slice(responseStartOffset);
 		if (finalMarker && responsePlain.includes(finalMarker)) finalMarkerSeen = true;
 		if (finalMarkerSeen && sessionJsonlMeetsRequirements(sessionDir, scenario) && sessionJsonlHasAssistantMarker(sessionDir, finalMarker)) {
@@ -364,6 +361,7 @@ async function runPtyPi({ artifactDir, ptyCommand, env, cwd, sessionDir, finalMa
 	await waitForSessionJsonl(sessionDir, null, startedAt, events);
 	await delay(1_000);
 
+	const plain = stripVTControlCharacters(ansi);
 	writeRedactedTextFile(join(artifactDir, "terminal.ansi"), ansi);
 	writeRedactedTextFile(join(artifactDir, "terminal.txt"), plain);
 	writeFileSync(join(artifactDir, "pty.events.jsonl"), events.map((event) => JSON.stringify(event)).join("\n") + "\n");

package/scripts/platform-smoke/pty-capture.mjs

@@ -8,6 +8,7 @@
 import { spawn } from "node:child_process";
 import { writeFileSync, appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 
 const COLS = 150;
 const ROWS = 45;
@@ -27,7 +28,6 @@ export async function capturePTY(dir, command, opts = {}) {
 	const txtPath = resolve(dir, "terminal.txt");
 
 	let ansiBuffer = "";
-	let txtBuffer = "";
 
 	function appendEvent(event) {
 		appendFileSync(eventsPath, JSON.stringify(event) + "\n");
@@ -35,8 +35,6 @@ export async function capturePTY(dir, command, opts = {}) {
 	function appendOutput(data) {
 		const text = typeof data === "string" ? data : data.toString();
 		ansiBuffer += text;
-		// Strip ANSI for plain text
-		txtBuffer += stripANSI(text);
 	}
 
 	// Try node-pty first
@@ -79,7 +77,7 @@ export async function capturePTY(dir, command, opts = {}) {
 		});
 
 		writeFileSync(ansiPath, ansiBuffer);
-		writeFileSync(txtPath, txtBuffer);
+		writeFileSync(txtPath, stripVTControlCharacters(ansiBuffer));
 
 		return { code: code ?? (signal ? 1 : 0), signal, ansiPath, txtPath, eventsPath };
 	} else {
@@ -111,17 +109,12 @@ export async function capturePTY(dir, command, opts = {}) {
 		});
 
 		writeFileSync(ansiPath, ansiBuffer);
-		writeFileSync(txtPath, txtBuffer);
+		writeFileSync(txtPath, stripVTControlCharacters(ansiBuffer));
 
 		return { code: code ?? (signal ? 1 : 0), signal, ansiPath, txtPath, eventsPath };
 	}
 }
 
-/** Strip ANSI escape sequences from a string. */
-function stripANSI(str) {
-	return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
-}
-
 /** Self-test: can we create a simple PTY? */
 export async function ptySelfTest() {
 	const dir = resolve(process.cwd(), ".artifacts", "pty-self-test");

package/scripts/platform-smoke/render-ansi.mjs

@@ -7,6 +7,7 @@
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
 
 import { buildTerminalHtml, writeTerminalScreenshot } from "../lib/cursor-visual-render.mjs";
 
@@ -14,14 +15,10 @@ const COLS = 150;
 const ROWS = 45;
 const HISTORY_LINES = 3_000;
 
-function stripANSI(text) {
-	return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "");
-}
-
 /** Render terminal.ansi to terminal.html using the shared xterm.js renderer. */
 export async function renderHTML(ansiPath, htmlPath, options = {}) {
 	const ansi = readFileSync(ansiPath, "utf8");
-	const plain = options.plain ?? stripANSI(ansi);
+	const plain = options.plain ?? stripVTControlCharacters(ansi);
 	const html = buildTerminalHtml({
 		ansi,
 		plain,

package/src/context.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { getCursorConversationMessages, resolveCursorPiContext } from "./cursor-pi-context.js";
 import type { Context, Message, ToolCall } from "@earendil-works/pi-ai";
 import { convertToLlm } from "@earendil-works/pi-coding-agent";
 import type { AgentModeOption, SDKImage } from "@cursor/sdk";
@@ -85,7 +86,7 @@ function getCursorBootstrapTailSections(
 }
 
 function normalizePiContextMessages(messages: Context["messages"]): Message[] {
-	return convertToLlm(messages as Parameters<typeof convertToLlm>[0]);
+	return convertToLlm(getCursorConversationMessages({ messages }) as Parameters<typeof convertToLlm>[0]);
 }
 
 function isTextBlock(block: { type: string }): block is { type: "text"; text: string } {
@@ -137,6 +138,15 @@ function formatToolCall(toolCall: ToolCall): string {
 
 function sanitizeSystemPromptForCursor(systemPrompt: string): string {
 	let sanitized = systemPrompt;
+	// Transcript-era Pi wraps its built-in tool catalog/rules in XML sections.
+	sanitized = sanitized.replace(
+		/<tools>\n[\s\S]*?\n\nIn addition to the tools above, you may have access to other custom tools depending on the project\.\n<\/tools>/g,
+		"Pi tool catalog omitted: Cursor can call only Cursor SDK tools exposed in this run.",
+	);
+	sanitized = sanitized.replace(
+		/<rules>\n[\s\S]*?\n<\/rules>\n\n(?=<docs>\nPi documentation )/g,
+		"<rules>\n- Be concise in your responses.\n- Show file paths clearly when working with files.\n</rules>\n\n",
+	);
 	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",
@@ -279,12 +289,24 @@ function serializeMessageForFingerprint(message: Message, index: number): string
 			return hashCursorContextValue(
 				`toolResult:${message.timestamp ?? index}:${message.toolCallId}:${message.toolName}:${JSON.stringify(message.content)}:${message.isError === true}`,
 			);
+		default:
+			// System messages are handled by serializeRawPiMessageForFingerprint.
+			throw new Error("Unsupported Pi message role in Cursor context fingerprint.");
 	}
 }
 
 function serializeRawPiMessageForFingerprint(message: Context["messages"][number], index: number): string {
 	const role = (message as { role?: string }).role;
 	switch (role) {
+		case "system": {
+			const entry = message as {
+				content: unknown; sections?: unknown; toolsAdded?: unknown; toolsRemoved?: unknown;
+			};
+			return hashCursorContextValue(JSON.stringify({
+				role, content: entry.content, sections: entry.sections,
+				toolsAdded: entry.toolsAdded, toolsRemoved: entry.toolsRemoved,
+			}));
+		}
 		case "branchSummary": {
 			const entry = message as { summary?: string; fromId?: string; timestamp?: number };
 			return hashCursorContextValue(
@@ -337,7 +359,7 @@ function parseCursorContextFingerprint(fingerprint: string): CursorContextFinger
 
 export function computeCursorContextFingerprint(context: Context): string {
 	const payload: CursorContextFingerprintPayload = {
-		systemHash: hashCursorContextValue(context.systemPrompt ?? ""),
+		systemHash: hashCursorContextValue(JSON.stringify(resolveCursorPiContext(context))),
 		messageHashes: context.messages.map((message, index) => serializeRawPiMessageForFingerprint(message, index)),
 	};
 	return JSON.stringify(payload);
@@ -412,8 +434,9 @@ export function buildCursorPrompt(context: Context, options: CursorPromptOptions
 		sectionsBeforeMessages.push(options.toolManifest);
 	}
 
-	if (context.systemPrompt) {
-		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(context.systemPrompt)}`);
+	const { systemPrompt } = resolveCursorPiContext(context);
+	if (systemPrompt) {
+		sectionsBeforeMessages.push(`System instructions from pi:\n${sanitizeSystemPromptForCursor(systemPrompt)}`);
 	}
 
 	const messages = normalizePiContextMessages(context.messages);

package/src/cursor-agents-context.ts

@@ -114,9 +114,21 @@ export function serializePiProjectInstructionsBlock(file: PiAgentsContextFile):
 	return `${PI_PROJECT_INSTRUCTIONS_OPEN_PREFIX}${file.path}">\n${file.content}\n${PI_PROJECT_INSTRUCTIONS_CLOSE}\n\n`;
 }
 
-/** Exact pi `buildSystemPrompt()` serialization for the full project context section. */
-export function serializePiProjectContextSection(contextFiles: readonly PiAgentsContextFile[]): string {
+/** The two supported Pi project-context serializations; legacy includes outer spacing. */
+export function serializePiProjectContextSection(
+	contextFiles: readonly PiAgentsContextFile[],
+	format: "legacy" | "transcript" = "legacy",
+): string {
 	if (contextFiles.length === 0) return "";
+	if (format === "transcript") {
+		return [
+			"<project_context>",
+			"Project-specific instructions and guidelines:",
+			"",
+			contextFiles.map((file) => serializePiProjectInstructionsBlock(file).trimEnd()).join("\n\n"),
+			"</project_context>",
+		].join("\n");
+	}
 	return `${PI_PROJECT_CONTEXT_OPEN}${contextFiles.map(serializePiProjectInstructionsBlock).join("")}${PI_PROJECT_CONTEXT_CLOSE}`;
 }
 
@@ -138,12 +150,16 @@ export function removePiAgentsContextFromSystemPrompt(
 	}
 	if (!removedAny) return systemPrompt;
 
-	const originalSection = serializePiProjectContextSection(contextFiles);
-	const start = systemPrompt.indexOf(originalSection);
-	if (start < 0) return systemPrompt;
-
-	const replacementSection = serializePiProjectContextSection(retainedContextFiles);
-	return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+	// Match only the exact known files in either supported serialization; never
+	// strip arbitrary user-authored XML or neighboring custom sections.
+	for (const format of ["legacy", "transcript"] as const) {
+		const originalSection = serializePiProjectContextSection(contextFiles, format);
+		const start = systemPrompt.indexOf(originalSection);
+		if (start < 0) continue;
+		const replacementSection = serializePiProjectContextSection(retainedContextFiles, format);
+		return systemPrompt.slice(0, start) + replacementSection + systemPrompt.slice(start + originalSection.length);
+	}
+	return systemPrompt;
 }
 
 export function resolveCursorFacingSystemPrompt(

package/src/cursor-context-tools.ts

@@ -1,6 +1,8 @@
 import type { Context } from "@earendil-works/pi-ai";
+import { resolveCursorPiContext } from "./cursor-pi-context.js";
 
 /** Tool names from the provider context snapshot at stream start (not live pi.getActiveTools()). */
 export function getActiveContextToolNames(context: Context): ReadonlySet<string> | undefined {
-	return context.tools ? new Set(context.tools.map((tool) => tool.name)) : undefined;
+	const { tools } = resolveCursorPiContext(context);
+	return tools === undefined ? undefined : new Set(tools.map((tool) => tool.name));
 }

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

@@ -1,4 +1,5 @@
 import type { Context, ToolResultMessage } from "@earendil-works/pi-ai";
+import { getCursorConversationMessages } from "./cursor-pi-context.js";
 import type { SDKAgent } from "@cursor/sdk";
 import {
 	consumeCursorLiveToolResults,
@@ -27,6 +28,7 @@ export type CursorLiveQueuedEvent =
 	| { type: "thinking-delta"; text: string }
 	| { type: "thinking-completed" }
 	| { type: "text-delta"; text: string }
+	| { type: "text-completed" }
 	| { type: "tool"; tool: CursorNativeToolDisplayItem }
 	| { type: "bridge-tool"; request: CursorPiBridgeToolRequest };
 
@@ -155,16 +157,17 @@ interface CursorLiveRunPrivateState {
 }
 
 export function hasTrailingUserMessagesAfterToolResults(context: Context): boolean {
-	let index = context.messages.length - 1;
+	const messages = getCursorConversationMessages(context);
+	let index = messages.length - 1;
 	let sawTrailingUser = false;
-	while (index >= 0 && context.messages[index]?.role === "user") {
+	while (index >= 0 && messages[index]?.role === "user") {
 		sawTrailingUser = true;
 		index -= 1;
 	}
 	if (!sawTrailingUser) return false;
 
 	let sawToolResult = false;
-	while (index >= 0 && context.messages[index]?.role === "toolResult") {
+	while (index >= 0 && messages[index]?.role === "toolResult") {
 		sawToolResult = true;
 		index -= 1;
 	}
@@ -418,13 +421,14 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 		},
 
 		getPendingFromContext(context, getReplayId): CursorLiveRun | undefined {
-			let index = context.messages.length - 1;
-			while (index >= 0 && context.messages[index]?.role === "user") {
+			const messages = getCursorConversationMessages(context);
+			let index = messages.length - 1;
+			while (index >= 0 && messages[index]?.role === "user") {
 				index -= 1;
 			}
 
 			for (; index >= 0; index -= 1) {
-				const message = context.messages[index];
+				const message = messages[index];
 				if (message.role !== "toolResult") break;
 				const replayId = getReplayId(message.toolCallId);
 				if (replayId) {

package/src/cursor-partial-content-emitter.ts

@@ -1,6 +1,7 @@
 import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai";
 
 const DEFAULT_THINKING_TRACE_MAX_CHARS = 50000;
+export const CURSOR_TEXT_MESSAGE_SEPARATOR = "\n\n";
 
 export interface CursorPartialContentEmitterOptions {
 	stream: AssistantMessageEventStream;
@@ -12,6 +13,7 @@ export interface CursorPartialContentEmitterOptions {
 export class CursorPartialContentEmitter {
 	private thinkingContentIndex = -1;
 	private textContentIndex = -1;
+	private textMessageCompleted = false;
 	private activityTraceChars = 0;
 	private activityTraceTruncated = false;
 
@@ -86,10 +88,21 @@ export class CursorPartialContentEmitter {
 		});
 	}
 
+	completeTextMessage(): void {
+		// Defer the separator until more text arrives: an exact final answer must
+		// not gain trailing whitespace. A fresh Pi tool-use turn needs no prefix.
+		this.textMessageCompleted = this.partial.content.some((block) => block.type === "text" && block.text.length > 0);
+	}
+
 	appendTextDelta(delta: string, options?: { closeThinking?: boolean }): void {
 		const closeThinking = options?.closeThinking ?? this.mutuallyExclusive;
 		if (closeThinking) this.closeThinking();
 		if (!delta) return;
+		if (this.textMessageCompleted) {
+			this.textMessageCompleted = false;
+			this.appendTextDelta(CURSOR_TEXT_MESSAGE_SEPARATOR, { closeThinking: false });
+			this.closeText();
+		}
 		if (this.textContentIndex < 0) {
 			this.textContentIndex = this.partial.content.length;
 			this.partial.content.push({ type: "text", text: "" });

package/src/cursor-pi-context.ts

@@ -0,0 +1,44 @@
+import * as piAi from "@earendil-works/pi-ai";
+import type { Context, Message, Tool } from "@earendil-works/pi-ai";
+
+// Stock 0.84/0.85 do not export transcript helpers. Keep the namespace import in
+// Pi's static extension graph: the host loader supplies its own peer module.
+// Context remains the common structural input (its shorthand fields are optional);
+// transcript hosts pass messages only. Never implement Pi's replay rules here.
+interface PiTranscriptHelpers {
+	normalizeContext(context: Context): { messages: readonly { role: string }[] };
+	getCurrentSystemPrompt(messages: readonly { role: string }[]): string;
+	getCurrentTools(messages: readonly { role: string }[]): Tool[];
+}
+const optionalHelpers = piAi as typeof piAi & Partial<PiTranscriptHelpers>;
+const transcriptHelpers = typeof optionalHelpers.normalizeContext === "function"
+	&& typeof optionalHelpers.getCurrentSystemPrompt === "function"
+	&& typeof optionalHelpers.getCurrentTools === "function"
+	? optionalHelpers as PiTranscriptHelpers : undefined;
+
+export function isCursorSystemMessage(message: { role: string }): boolean {
+	return message.role === "system";
+}
+
+/** Conversation-only view for Cursor text/history and trailing tool-result scans. */
+export function getCursorConversationMessages(context: Pick<Context, "messages">): Message[] {
+	return context.messages.filter((message) => !isCursorSystemMessage(message));
+}
+
+export function resolveCursorPiContext(context: Context): { systemPrompt: string; tools: Tool[] | undefined } {
+	if (!transcriptHelpers) {
+		if (context.messages.some(isCursorSystemMessage)) {
+			throw new Error("Pi transcript context requires the host's public transcript replay helpers.");
+		}
+		return { systemPrompt: context.systemPrompt ?? "", tools: context.tools };
+	}
+	const messages = transcriptHelpers.normalizeContext(context).messages;
+	const legacyWithoutTools = ("systemPrompt" in context || "tools" in context)
+		&& context.tools === undefined && !context.messages.some(isCursorSystemMessage);
+	return {
+		systemPrompt: transcriptHelpers.getCurrentSystemPrompt(messages),
+		// A messages-only provider request is authoritative, including no declarations.
+		// An explicitly legacy shorthand context retains its absent-snapshot semantics.
+		tools: legacyWithoutTools ? undefined : transcriptHelpers.getCurrentTools(messages),
+	};
+}