pi-cursor-sdk 0.2.0 → 0.3.7

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 };
 
@@ -43,6 +45,7 @@ export interface CursorLiveRun {
 	sdkRun?: CursorLiveSdkRun;
 	ignoreFutureSdkTurnUsage?: boolean;
 	accounting: CursorLiveRunAccountingState;
+	billedTurnUsage?: CursorSdkTurnUsage;
 	pendingEvents: CursorLiveQueuedEvent[];
 	textDeltas: string[];
 	emittedText: string;
@@ -154,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;
 	}
@@ -417,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-native-tool-display-registration.ts

@@ -18,6 +18,7 @@ import {
 	skippedNativeToolNames,
 } from "./cursor-native-tool-display-state.js";
 import { isCursorReplayToolName } from "./cursor-tool-presentation-registry.js";
+import { registerNativeCursorTool } from "./cursor-native-tool-display-tools.js";
 
 export const CURSOR_CORE_PI_REPLAY_TOOL_NAMES = ["read", "bash", "edit", "write"] as const;
 const CORE_PI_TOOL_NAMES = new Set<string>(CURSOR_CORE_PI_REPLAY_TOOL_NAMES);
@@ -40,12 +41,11 @@ type NativeRegistrationContext = Pick<ExtensionContext, "mode" | "model"> & {
 	ui: Pick<ExtensionContext["ui"], "notify">;
 };
 
-async function registerNativeCursorToolsFromSet(
+function registerNativeCursorToolsFromSet(
 	pi: CursorNativeToolRegistryApi,
 	toolNames: readonly NativeCursorToolName[],
-): Promise<NativeCursorToolName[]> {
+): NativeCursorToolName[] {
 	const newlySkippedToolNames: NativeCursorToolName[] = [];
-	let registerNativeCursorTool: ((pi: CursorNativeToolRegistryApi, toolName: NativeCursorToolName) => void) | undefined;
 	for (const toolName of toolNames) {
 		if (registeredNativeToolNames.has(toolName) || skippedNativeToolNames.has(toolName)) continue;
 		if (hasNonBuiltinTool(pi, toolName)) {
@@ -53,7 +53,6 @@ async function registerNativeCursorToolsFromSet(
 			newlySkippedToolNames.push(toolName);
 			continue;
 		}
-		registerNativeCursorTool ??= (await import("./cursor-native-tool-display-tools.js")).registerNativeCursorTool;
 		registerNativeCursorTool(pi, toolName);
 		registeredNativeToolNames.add(toolName);
 	}
@@ -105,31 +104,31 @@ export function syncRegisteredNativeCursorToolsForModel(
 	if (changed) pi.setActiveTools([...activeToolNames]);
 }
 
-async function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
+function ensureNativeCursorToolsRegisteredForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	if (!isCursorModel(ctx.model) || hasAttemptedNativeCursorToolRegistration()) return;
 
 	const nonCoreToolNames = NATIVE_CURSOR_TOOL_NAMES.filter((toolName) => !isCursorCorePiReplayToolName(toolName));
 	const skippedToolNames = [
-		...(await registerNativeCursorToolsFromSet(pi, nonCoreToolNames)),
-		...(await registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES)),
+		...registerNativeCursorToolsFromSet(pi, nonCoreToolNames),
+		...registerNativeCursorToolsFromSet(pi, CURSOR_CORE_PI_REPLAY_TOOL_NAMES),
 	];
 	notifySkippedNativeCursorToolsIfNeeded(ctx, skippedToolNames);
 }
 
-async function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): Promise<void> {
+function ensureThenSyncNativeCursorToolsForModel(pi: CursorNativeToolRegistryApi, ctx: NativeRegistrationContext): void {
 	const requested = isCursorNativeToolRegistrationRequested(ctx.mode);
 	setCursorNativeToolDisplayRuntimeRequested(requested);
 	if (!requested) {
 		removeRegisteredNonCoreNativeCursorTools(pi);
 		return;
 	}
-	await ensureNativeCursorToolsRegisteredForModel(pi, ctx);
+	ensureNativeCursorToolsRegisteredForModel(pi, ctx);
 	syncRegisteredNativeCursorToolsForModel(pi, ctx.model);
 }
 
 export function registerCursorNativeToolDisplay(pi: CursorNativeToolDisplayExtensionApi): void {
-	registerCursorModelLifecycle(pi, async (ctx) => {
-		await ensureThenSyncNativeCursorToolsForModel(pi, ctx);
+	registerCursorModelLifecycle(pi, (ctx) => {
+		ensureThenSyncNativeCursorToolsForModel(pi, ctx);
 	});
 }
 

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),
+	};
+}

package/src/cursor-provider-errors.ts

@@ -166,7 +166,7 @@ function isCursorSdkStallAbortNetworkError(code: unknown, evidence: string, stac
 }
 
 /**
- * @cursor/sdk@1.0.23 throws internal RetriableError (name/kind "RetriableError") with message
+ * @cursor/sdk@1.0.27 throws internal RetriableError (name/kind "RetriableError") with message
  * "Connection stalled" or "Connection stalled repeatedly" after fetchWithRetry exhausts stalls.
  * The ConnectError is only the cause; the top-level error is not a ConnectError.
  */

package/src/cursor-provider-lazy.ts

@@ -7,8 +7,10 @@ import {
 	type Model,
 	type SimpleStreamOptions,
 } from "@earendil-works/pi-ai";
+import { streamCursor } from "./cursor-provider.js";
+import { sanitizeCursorProviderError } from "./cursor-provider-errors.js";
 
-function makeProviderLoadErrorMessage(model: Model<Api>, error: unknown): AssistantMessage {
+function makeProviderRuntimeErrorMessage(model: Model<Api>, error: unknown, apiKey?: string): AssistantMessage {
 	return {
 		role: "assistant",
 		content: [],
@@ -25,7 +27,7 @@ function makeProviderLoadErrorMessage(model: Model<Api>, error: unknown): Assist
 		},
 		stopReason: "error",
 		timestamp: Date.now(),
-		errorMessage: `Failed to load Cursor provider runtime: ${error instanceof Error ? error.message : String(error)}`,
+		errorMessage: `Cursor provider runtime failed: ${sanitizeCursorProviderError(error, apiKey)}`,
 	};
 }
 
@@ -37,12 +39,11 @@ export function streamCursorLazy(
 	const outer = createAssistantMessageEventStream();
 	queueMicrotask(async () => {
 		try {
-			const { streamCursor } = await import("./cursor-provider.js");
 			for await (const event of streamCursor(model, context, options)) {
 				outer.push(event);
 			}
 		} catch (error) {
-			const message = makeProviderLoadErrorMessage(model, error);
+			const message = makeProviderRuntimeErrorMessage(model, error, options?.apiKey);
 			outer.push({ type: "error", reason: "error", error: message });
 			outer.end(message);
 		}

package/src/cursor-provider-live-run-drain.ts

@@ -21,7 +21,7 @@ import {
 import { type CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
 import { resetSessionCursorAgent } from "./cursor-session-agent.js";
 import { applyCursorUsage } from "./cursor-usage-accounting.js";
-import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
+import { CURSOR_TEXT_MESSAGE_SEPARATOR, CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
 import { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text.js";
 import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
@@ -88,11 +88,9 @@ function splitTextIntoReplayDeltas(text: string): string[] {
 }
 
 async function emitTextDeltas(
-	stream: AssistantMessageEventStream,
-	partial: AssistantMessage,
+	emitter: CursorPartialContentEmitter,
 	deltas: string[],
 ): Promise<string> {
-	const emitter = new CursorPartialContentEmitter(stream, partial, -1, true);
 	for (const delta of deltas) {
 		emitter.appendTextDelta(delta);
 		await Promise.resolve();
@@ -121,11 +119,11 @@ export function flushPendingCursorLiveRunTraceEventsToStream(
 	stream: AssistantMessageEventStream,
 	partial: AssistantMessage,
 	run: CursorLiveRun,
-	options?: { includeTracesBehindQueuedTools?: boolean },
+	options?: { includeTracesBehindQueuedTools?: boolean; emitter?: CursorPartialContentEmitter },
 ): void {
 	if (run.disposed) return;
 	const turn: CursorLiveTurnState = {
-		emitter: new CursorPartialContentEmitter(stream, partial, -1, true),
+		emitter: options?.emitter ?? new CursorPartialContentEmitter(stream, partial, -1, true),
 		emittedText: "",
 	};
 	while (true) {
@@ -157,6 +155,12 @@ function emitCursorLiveQueuedEvent(
 		turn.emitter.appendThinkingDelta(event.text);
 	} else if (event.type === "thinking-completed") {
 		turn.emitter.closeThinking();
+	} else if (event.type === "text-completed") {
+		turn.emitter.completeTextMessage();
+		// Logical separators also keep suffix/prefix dedup aware of SDK messages,
+		// including boundaries queued across Pi tool-use turns.
+		if (turn.emittedText) turn.emittedText += CURSOR_TEXT_MESSAGE_SEPARATOR;
+		if (run?.emittedText) run.emittedText += CURSOR_TEXT_MESSAGE_SEPARATOR;
 	} else if (event.type === "text-delta") {
 		turn.emittedText += event.text;
 		if (run) run.emittedText += event.text;
@@ -296,7 +300,7 @@ export async function drainCursorLiveRunTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; emitter?: CursorPartialContentEmitter },
 ): Promise<CursorLiveRunDrainOutcome> {
 	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	debugRecorder?.recordDrainEvent("turn_start", {
@@ -308,7 +312,7 @@ export async function drainCursorLiveRunTurn(
 	let outcome: CursorLiveRunDrainOutcome | undefined;
 	let outcomeDetails: Record<string, unknown> = {};
 	const turn: CursorLiveTurnState = {
-		emitter: new CursorPartialContentEmitter(stream, partial, -1, true),
+		emitter: options.emitter ?? new CursorPartialContentEmitter(stream, partial, -1, true),
 		emittedText: "",
 	};
 
@@ -378,11 +382,12 @@ export async function drainCursorLiveRunTurn(
 				turn.emitter.closeAll();
 				const finalText = trimCurrentTurnAlreadyEmittedCursorText(run.finalText ?? run.textDeltas.join(""), turn.emittedText, run.emittedText);
 				if (finalText) {
-					await emitTextDeltas(stream, partial, splitTextIntoReplayDeltas(finalText));
+					await emitTextDeltas(turn.emitter, splitTextIntoReplayDeltas(finalText));
 				}
 				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 					runtime: "local",
 					turn: cursorLiveRuns.takeSdkTurnUsage(run),
+					billed: run.billedTurnUsage,
 				});
 				if (run.resumeNotice) {
 					emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);

package/src/cursor-provider-run-finalizer.ts

@@ -186,6 +186,7 @@ export class CursorRunFinalizer {
 				applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
 					runtime: prepared.runtimeTarget,
 					turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
+					billed: prepared.runtime.billedTurnUsage,
 				});
 				if (prepared.meta.resumeNotice) emitDisplayOnlyTraceBlock(stream, partial, prepared.meta.resumeNotice);
 				if (displayOnlyTraceBlock) emitDisplayOnlyTraceBlock(stream, partial, displayOnlyTraceBlock);

package/src/cursor-provider-turn-coordinator.ts

@@ -1,5 +1,6 @@
 import type { AssistantMessage, AssistantMessageEventStream } from "@earendil-works/pi-ai";
 import type { InteractionUpdate } from "@cursor/sdk";
+import { CURSOR_TEXT_MESSAGE_SEPARATOR } from "./cursor-partial-content-emitter.js";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import { truncateCursorDisplayLine } from "./cursor-display-text.js";
@@ -65,6 +66,7 @@ export class CursorSdkTurnCoordinator {
 	private readonly lifecycleEmitter: CursorToolLifecycleEmitter;
 	private readonly contentEmitter;
 	private sdkTurnUsage?: CursorSdkTurnUsage;
+	private hasPendingTextMessage = false;
 
 	constructor(options: CursorSdkTurnCoordinatorOptions) {
 		this.stream = options.stream;
@@ -153,6 +155,7 @@ export class CursorSdkTurnCoordinator {
 			cursorLiveRuns.recordSdkTurnEnded(this.liveRun, sdkTurnUsage);
 		}
 		if (update.type === "text-delta") {
+			if (update.text) this.hasPendingTextMessage = true;
 			this.textDeltas.push(update.text);
 			if (this.liveRun) {
 				cursorLiveRuns.queueEvent(this.liveRun, { type: "text-delta", text: update.text });
@@ -247,6 +250,18 @@ export class CursorSdkTurnCoordinator {
 
 	handleStep(stepEnvelope: unknown): void {
 		const stepType = getField(stepEnvelope, "type");
+		if (stepType === "assistantMessage") {
+			// SDK onStep completes a message; onDelta chunks within it are tokens,
+			// not separate messages. Keep the boundary in both output and final-text
+			// deduplication, without replaying the completed step's text a second time.
+			if (this.hasPendingTextMessage) {
+				this.hasPendingTextMessage = false;
+				this.textDeltas.push(CURSOR_TEXT_MESSAGE_SEPARATOR);
+				if (this.liveRun) cursorLiveRuns.queueEvent(this.liveRun, { type: "text-completed" });
+				else this.contentEmitter.completeTextMessage();
+			}
+			return;
+		}
 		const step = getField(stepEnvelope, "message") ? stepEnvelope : undefined;
 		const rawStepToolCall = getField(step, "message");
 		if (stepType !== "toolCall") return;

package/src/cursor-provider-turn-emit.ts

@@ -1,4 +1,5 @@
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
 import {
 	cursorLiveRuns,
 	drainCursorLiveRunTurn,
@@ -28,6 +29,9 @@ export async function emitCursorLiveTurn(emitParams: EmitCursorLiveTurnParams):
 	const { liveRun, turnCoordinator } = prepared.runtime;
 
 	const { options, model } = params;
+	// Drain and abort recovery write to the same partial. Keep its open text block
+	// and deferred message boundary together; a new Pi turn still gets a new emitter.
+	const emitter = new CursorPartialContentEmitter(params.stream, params.partial, -1, true);
 	try {
 		await cursorLiveRuns.withRunLease(liveRun, options?.signal, async () => {
 			await cursorLiveRuns.waitForProgress(liveRun, options?.signal);
@@ -35,6 +39,7 @@ export async function emitCursorLiveTurn(emitParams: EmitCursorLiveTurnParams):
 			turnCoordinator.closeTraceBlock();
 			await drainCursorLiveRunTurn(params.stream, params.partial, model, params.context, liveRun, 0, {
 				mode: "emit",
+				emitter,
 				signal: options?.signal,
 				debugRecorder: sdkEventDebug,
 			});
@@ -45,6 +50,7 @@ export async function emitCursorLiveTurn(emitParams: EmitCursorLiveTurnParams):
 			turnCoordinator.closeTraceBlock();
 			flushPendingCursorLiveRunTraceEventsToStream(params.stream, params.partial, liveRun, {
 				includeTracesBehindQueuedTools: true,
+				emitter,
 			});
 		}
 		throw caught;

package/src/cursor-provider-turn-finalize.ts

@@ -17,6 +17,7 @@ import {
 } from "./cursor-provider-run-outcome.js";
 import type { CursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.js";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { attachCursorSdkBilledTurnUsage } from "./cursor-sdk-billed-usage.js";
 
 export async function cacheSdkContextWindow(
 	agentId: string,
@@ -149,6 +150,16 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 		resolvedApiKey: params.resolvedApiKey,
 		optionsApiKey: params.optionsApiKey,
 	});
+	const billed = await attachCursorSdkBilledTurnUsage({
+		agent: params.prepared.agent,
+		agentId: params.run.agentId,
+		runtime: params.prepared.runtimeTarget,
+		runId: params.run.id,
+	});
+	params.prepared.runtime.billedTurnUsage = billed.turn;
+	if (params.prepared.runtime.liveRun) {
+		params.prepared.runtime.liveRun.billedTurnUsage = billed.turn;
+	}
 	let displayOnlyTraceBlock: string | undefined;
 	if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
 		let report: CursorCloudRunReport = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
@@ -158,6 +169,7 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 				run: params.run,
 				waitResult,
 				apiKey,
+				agentUsage: billed.agentUsage,
 			});
 		} catch (error) {
 			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);

package/src/cursor-provider-turn-prepare.ts

@@ -1,4 +1,5 @@
 import type { Context, SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { getCursorConversationMessages, resolveCursorPiContext } from "./cursor-pi-context.js";
 import type { AgentModeOption, ModelSelection, SDKAgent } from "@cursor/sdk";
 import { configureCursorSdkHttp1 } from "./cursor-http1.js";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
@@ -80,11 +81,15 @@ interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnPara
 
 function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "bootstrap" | "never"): Context {
 	if (handoff === "bootstrap") return context;
-	for (let index = context.messages.length - 1; index >= 0; index -= 1) {
-		const message = context.messages[index];
-		if (message.role === "user") return { ...context, messages: [message] };
+	// Fresh cloud runs omit history, not the current Pi instructions. Replay before
+	// selecting the user message, otherwise transcript-only inputs lose the prompt.
+	const current = resolveCursorPiContext(context);
+	const messages = getCursorConversationMessages(context);
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (message.role === "user") return { ...current, messages: [message] };
 	}
-	return { ...context, messages: context.messages.slice(-1) };
+	return { ...current, messages: messages.slice(-1) };
 }
 
 const CLOUD_SEND_PLAN: CursorSessionSendPlan = { mode: "bootstrap", resetAgent: false, reason: "initial" };
@@ -135,7 +140,7 @@ async function prepareCursorCloudProviderTurn(
 					repo: resolvedConfig.cloud.repo.value,
 					branch: resolvedConfig.cloud.branch.value,
 				}),
-			hasPriorContext: context.messages.length > 1,
+			hasPriorContext: getCursorConversationMessages(context).length > 1,
 		});
 		if (!preflight.ok) throw new Error(formatCursorCloudPreflightError(preflight));
 		if (getPendingCursorLiveRun(context) || getActiveCursorLiveRunForCurrentScope()) {

package/src/cursor-provider-turn-types.ts

@@ -14,6 +14,7 @@ import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import type { CursorPrompt } from "./context.js";
 import type { CursorResolvedSetting } from "./cursor-config.js";
+import type { CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
 
 export interface CursorProviderTurnRunnerParams {
 	model: Model<Api>;
@@ -44,6 +45,7 @@ export interface CursorProviderTurnSendMeta {
 
 interface CursorProviderTurnRuntimeBase {
 	turnCoordinator: CursorSdkTurnCoordinator;
+	billedTurnUsage?: CursorSdkTurnUsage;
 }
 
 /**

package/src/cursor-sdk-billed-usage.ts

@@ -0,0 +1,107 @@
+import type { SDKAgent } from "@cursor/sdk";
+import type { CursorRuntime } from "./cursor-config.js";
+import { asRecord, getArray, getString } from "./cursor-record-utils.js";
+import { readCursorSdkTurnUsage, type CursorSdkTurnUsage } from "./cursor-usage-accounting.js";
+
+const BILLED_USAGE_TIMEOUT_MS = 5000;
+
+// ponytail: process-lifetime watermark of billed usage UUIDs per agentId; reset on process exit.
+// Upgrade to session-scoped storage if multi-day processes retain enough agent IDs to matter.
+const seenBilledRunIdsByAgent = new Map<string, Set<string>>();
+
+export function isCursorSdkClientMintedRunId(runId: string): boolean {
+	return runId.startsWith("run-");
+}
+
+export function sumCursorSdkTurnUsage(usages: readonly CursorSdkTurnUsage[]): CursorSdkTurnUsage | undefined {
+	if (usages.length === 0) return undefined;
+	return usages.reduce(
+		(total, usage) => ({
+			inputTokens: total.inputTokens + usage.inputTokens,
+			outputTokens: total.outputTokens + usage.outputTokens,
+			cacheReadTokens: total.cacheReadTokens + usage.cacheReadTokens,
+			cacheWriteTokens: total.cacheWriteTokens + usage.cacheWriteTokens,
+		}),
+	);
+}
+
+export function peekCursorBilledUsageRunIds(agentId: string): ReadonlySet<string> {
+	return seenBilledRunIdsByAgent.get(agentId) ?? new Set();
+}
+
+export function rememberCursorBilledUsageRunIds(agentId: string, runIds: readonly string[]): void {
+	if (runIds.length === 0) return;
+	let seen = seenBilledRunIdsByAgent.get(agentId);
+	if (!seen) {
+		seen = new Set();
+		seenBilledRunIdsByAgent.set(agentId, seen);
+	}
+	for (const runId of runIds) seen.add(runId);
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs = BILLED_USAGE_TIMEOUT_MS): Promise<T | undefined> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<undefined>((resolve) => {
+		timer = setTimeout(() => resolve(undefined), timeoutMs);
+		timer.unref?.();
+	});
+	return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+export function selectCursorBilledTurnUsage(
+	agentUsage: unknown,
+	options: { runtime: CursorRuntime; runId?: string; seenRunIds?: ReadonlySet<string> },
+): { turn?: CursorSdkTurnUsage; runIds: string[] } {
+	const runs = (getArray(asRecord(agentUsage), "runs") ?? []).flatMap((item) => {
+		const record = asRecord(item);
+		const runId = getString(record, "runId");
+		const usage = readCursorSdkTurnUsage(record?.usage);
+		return runId && usage ? [{ runId, usage }] : [];
+	});
+	if (options.runtime === "cloud" && options.runId) {
+		const match = runs.find((run) => run.runId === options.runId);
+		return match ? { turn: match.usage, runIds: [match.runId] } : { runIds: [] };
+	}
+	const unseen = runs.filter((run) => !options.seenRunIds?.has(run.runId));
+	return { turn: sumCursorSdkTurnUsage(unseen.map((run) => run.usage)), runIds: unseen.map((run) => run.runId) };
+}
+
+export async function fetchCursorSdkAgentUsage(
+	agent: SDKAgent,
+	options: { runtime: CursorRuntime; runId?: string },
+): Promise<unknown | undefined> {
+	if (typeof agent.getUsage !== "function") return undefined;
+	const query =
+		options.runtime === "cloud" && options.runId && isCursorSdkClientMintedRunId(options.runId)
+			? { runId: options.runId }
+			: undefined;
+	return withTimeout(Promise.resolve(agent.getUsage(query)));
+}
+
+export async function attachCursorSdkBilledTurnUsage(options: {
+	agent: SDKAgent;
+	agentId: string;
+	runtime: CursorRuntime;
+	runId?: string;
+}): Promise<{ agentUsage?: unknown; turn?: CursorSdkTurnUsage }> {
+	const agentUsage = await fetchCursorSdkAgentUsage(options.agent, {
+		runtime: options.runtime,
+		runId: options.runId,
+	});
+	if (!agentUsage) return {};
+	const selected = selectCursorBilledTurnUsage(agentUsage, {
+		runtime: options.runtime,
+		runId: options.runtime === "cloud" ? options.runId : undefined,
+		seenRunIds: peekCursorBilledUsageRunIds(options.agentId),
+	});
+	rememberCursorBilledUsageRunIds(options.agentId, selected.runIds);
+	return { agentUsage, turn: selected.turn };
+}
+
+export const __testUtils = {
+	reset(): void {
+		seenBilledRunIdsByAgent.clear();
+	},
+};

package/src/cursor-sdk-process-error-guard.ts

@@ -75,10 +75,12 @@ function isCursorSdkAbortError(error: unknown): boolean {
 // The exact observed incident: the Cursor SDK 1.0.23 local shell executor writes a
 // spawned child's stdin without a stream 'error' listener, so a child exiting while
 // a write is in flight surfaces a raw `write EPIPE` uncaught exception whose stack
-// is exactly the single async pipe-write completion frame. Pi's own piped-stdout or
-// dead-terminal EPIPE normally surfaces through the synchronous write-dispatch path
-// with multiple frames (afterWriteDispatched/Socket._writeGeneric) and must stay
-// fatal per Unix convention, so anything beyond this one-frame contract is rejected.
+// is exactly the single async pipe-write completion frame. Installed 1.0.27 attaches
+// a no-op `error` listener before that write; keep this guard as defense in depth.
+// Pi's own piped-stdout or dead-terminal EPIPE normally surfaces through the
+// synchronous write-dispatch path with multiple frames (afterWriteDispatched /
+// Socket._writeGeneric) and must stay fatal per Unix convention, so anything beyond
+// this one-frame contract is rejected.
 const OBSERVED_CLOSED_PIPE_STACK_FRAME =
 	/^\s+at WriteWrap\.onWriteComplete \[as oncomplete\] \(node:internal\/stream_base_commons:\d+:\d+\)$/;