pi-cursor-sdk 0.1.56 → 0.1.57

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

@@ -38,7 +38,13 @@ export function takeCursorLiveSdkTurnUsage(state: CursorLiveRunAccountingState):
 	sdkTurnUsage?: CursorSdkTurnUsage;
 } {
 	const { sdkTurnUsage, ...nextState } = state;
-	return { state: { ...nextState, sdkTurnEnded: false }, sdkTurnUsage };
+	return {
+		state: {
+			...nextState,
+			sdkTurnEnded: false,
+		},
+		sdkTurnUsage,
+	};
 }
 
 function asToolResultMessage(message: Message): ToolResultMessage | undefined {

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

@@ -48,6 +48,7 @@ export interface CursorLiveRun {
 	emittedText: string;
 	recordedToolDisplayIds: string[];
 	finalText?: string;
+	resumeNotice?: string;
 	done: boolean;
 	cancelled: boolean;
 	disposed: boolean;

package/src/cursor-pi-tool-bridge-run.ts

@@ -150,6 +150,16 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		this.debugRecorder = recorder;
 	}
 
+	private recordBridgeRaw(
+		payload: Parameters<NonNullable<CursorPiToolBridgeRunOptions["debugRecorder"]>["recordBridgeRaw"]>[0],
+	): void {
+		try {
+			this.debugRecorder?.recordBridgeRaw(payload);
+		} catch {
+			// Debug capture must never block or strand a bridge call.
+		}
+	}
+
 	async resolveToolResults(toolResults: readonly ToolResultMessage[]): Promise<void> {
 		let resolvedCount = 0;
 		for (const toolResult of toolResults) {
@@ -298,11 +308,11 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 				}
 				this.queuedRequests.push(request);
 				this.emitRequestQueuedDiagnostic(request);
-				this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
+				this.recordBridgeRaw({ kind: "queued", request });
 				return;
 			}
 			this.emitRequestQueuedDiagnostic(request);
-			this.debugRecorder?.recordBridgeRaw({ kind: "queued", request });
+			this.recordBridgeRaw({ kind: "queued", request });
 			this.dispatchPendingToolRequest(pending, this.onToolRequest);
 		});
 	}
@@ -331,7 +341,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestResolvedDiagnostic(pending.request, result.isError === true);
-		this.debugRecorder?.recordBridgeRaw({ kind: "resolved", request: pending.request, result });
+		this.recordBridgeRaw({ kind: "resolved", request: pending.request, result });
 		pending.resolve(result);
 	}
 
@@ -340,7 +350,7 @@ export class CursorPiToolBridgeRunImpl implements CursorPiToolBridgeRun {
 		pending.settled = true;
 		this.removePending(pending);
 		this.emitRequestRejectedDiagnostic(pending.request, kind);
-		this.debugRecorder?.recordBridgeRaw({
+		this.recordBridgeRaw({
 			kind: "rejected",
 			request: pending.request,
 			error: error.message,

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

@@ -22,6 +22,7 @@ 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 { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
 import { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text.js";
 import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
 import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
@@ -379,6 +380,10 @@ export async function drainCursorLiveRunTurn(
 				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 					turn: cursorLiveRuns.takeSdkTurnUsage(run),
 				});
+				if (run.resumeNotice) {
+					emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);
+					run.resumeNotice = undefined;
+				}
 				partial.stopReason = "stop";
 				stream.push({ type: "done", reason: "stop", message: partial });
 				await cursorLiveRuns.release(run);

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

@@ -1,5 +1,5 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai/compat";
-import { abandonSessionCursorAgent, cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
 import {
 	classifyCursorRunEmission,
 	getCursorRunAbortMessage,
@@ -23,27 +23,32 @@ import type {
 	CursorProviderTurnRunnerParams,
 	CursorProviderTurnSend,
 	CursorProviderTurnSendResult,
+	LiveCursorProviderTurnRuntime,
+	LocalCursorProviderTurnPrepareResult,
 } from "./cursor-provider-turn-types.js";
 import { applyCursorUsage } from "./cursor-usage-accounting.js";
 import { hasUsableText } from "./cursor-record-utils.js";
+import { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
 export type CursorTurnTerminalEvent =
 	| {
 			kind: "direct";
 			prepared: CursorProviderTurnPrepareResult;
 			outcome: CursorRunOutcome;
+			displayOnlyTraceBlock?: string;
 	  }
 	| { kind: "error"; prepared: CursorProviderTurnPrepareResult | undefined; error: unknown };
 
 function applyLiveRunOutcome(
 	outcome: CursorRunOutcome,
-	prepared: CursorProviderTurnPrepareResult,
+	prepared: LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime },
 	context: CursorProviderTurnRunnerParams["context"],
 ): void {
-	if (prepared.runtime.kind !== "live" || prepared.runtime.liveRun.disposed) return;
+	if (prepared.runtime.liveRun.disposed) return;
 	const { liveRun } = prepared.runtime;
 	switch (classifyCursorRunEmission(outcome)) {
 		case "finished":
-			prepared.sessionAgentLease.commitSend(context, prepared.meta.bootstrap);
+			prepared.lifecycle.commitSend(context, prepared.meta.bootstrap);
+			if (prepared.meta.resumeNotice) liveRun.resumeNotice = prepared.meta.resumeNotice;
 			cursorLiveRuns.markFinished(liveRun, outcome.kind === "finished" ? outcome.finalText : "");
 			break;
 		case "cancelled":
@@ -69,7 +74,7 @@ export interface CursorRunFinalizerParams {
 
 export interface StartCursorLiveRunCompletionParams {
 	send: CursorProviderTurnSend;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
 	modelId: string;
 	discardIncompleteTools: (outcome: IncompleteCursorToolRunOutcomeInput) => void;
 }
@@ -84,7 +89,6 @@ export class CursorRunFinalizer {
 		const sdkEventDebug = this.params.sdkEventDebug();
 		const { send, prepared, modelId, discardIncompleteTools } = startParams;
 		const { run, cursorAgentMessageOffset } = send;
-		if (prepared.runtime.kind !== "live") throw new Error("startLiveRunCompletion requires a live run");
 		const { liveRun } = prepared.runtime;
 		const waitCompletion = awaitFinalizeCursorRunOutcome({
 			run,
@@ -100,30 +104,30 @@ export class CursorRunFinalizer {
 			cacheContextWindow: true,
 			contextWindowAgentId: liveRun.agent.agentId,
 		})
-			.then(async (outcome) => {
-				applyLiveRunOutcome(outcome, prepared, runnerParams.context);
+			.then(async (finalized) => {
+				applyLiveRunOutcome(finalized.outcome, prepared, runnerParams.context);
 			})
-			.catch(async (error: unknown) => {
-				sdkEventDebug?.recordWaitResult({ status: "error", error: String(error) });
-				sdkEventDebug?.recordError("run_wait", error);
-				discardIncompleteTools({ status: "error" });
-				await sdkEventDebug?.captureRunArtifacts(run);
-				if (liveRun.disposed) return;
-				cursorLiveRuns.markError(
-					liveRun,
-					sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? runnerParams.options?.apiKey),
-				);
+			.catch((error: unknown) => {
+				this.safeCleanup(() => discardIncompleteTools({ status: "error" }));
+				if (!liveRun.disposed) {
+					cursorLiveRuns.markError(
+						liveRun,
+						sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? runnerParams.options?.apiKey),
+					);
+				}
+				this.safeCleanup(() => sdkEventDebug?.recordWaitResult({ status: "error", error: String(error) }));
+				this.safeCleanup(() => sdkEventDebug?.recordError("run_wait", error));
 			});
-		// Mark the pooled agent busy as soon as the SDK run exists so auto-compaction summarization
+		// Mark the pooled local agent busy as soon as the SDK run exists so auto-compaction summarization
 		// (and other concurrent acquires) wait for run.wait() instead of hitting AgentBusyError.
-		prepared.sessionAgentLease.trackRunCompletion(waitCompletion);
+		prepared.lifecycle.trackRunCompletion(waitCompletion);
 		return { waitCompletion, prepared };
 	}
 
 	async applyTerminalEvent(event: CursorTurnTerminalEvent): Promise<void> {
 		if (this.terminalApplied) return;
 		if (event.kind === "direct") {
-			await this.applyDirectOutcome(event.prepared, event.outcome);
+			await this.applyDirectOutcome(event.prepared, event.outcome, event.displayOnlyTraceBlock);
 			this.terminalApplied = true;
 			return;
 		}
@@ -151,6 +155,7 @@ export class CursorRunFinalizer {
 				.catch(() => {});
 			return;
 		}
+		await prepared?.lifecycle.dispose().catch(() => {});
 		await this.finalizeSdkEventDebugBestEffort();
 		this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
 	}
@@ -158,45 +163,48 @@ export class CursorRunFinalizer {
 	private async applyDirectOutcome(
 		prepared: CursorProviderTurnPrepareResult,
 		outcome: CursorRunOutcome,
+		displayOnlyTraceBlock: string | undefined,
 	): Promise<void> {
 		const { stream, partial, model, context } = this.params.runnerParams;
 		prepared.runtime.turnCoordinator.closeTraceBlock();
 		switch (classifyCursorRunEmission(outcome)) {
 			case "cancelled":
-				await abandonSessionCursorAgent(prepared.sessionAgentScopeKey);
+				await prepared.lifecycle.abandon();
 				this.pushTerminalError(partial, "aborted", getCursorRunAbortMessage(outcome));
 				break;
 			case "failed":
-				await abandonSessionCursorAgent(prepared.sessionAgentScopeKey);
+				await prepared.lifecycle.abandon();
 				this.pushTerminalError(partial, "error", outcome.kind === "error" ? outcome.errorMessage : "Cursor SDK run failed.");
 				break;
 			case "finished":
-				prepared.sessionAgentLease.commitSend(context, prepared.meta.bootstrap);
+				prepared.lifecycle.commitSend(context, prepared.meta.bootstrap);
 				prepared.runtime.turnCoordinator.flushText(
 					outcome.kind === "finished" && hasUsableText(outcome.finalText) ? [outcome.finalText] : [],
 				);
 				applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
 					turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
 				});
+				if (prepared.meta.resumeNotice) emitDisplayOnlyTraceBlock(stream, partial, prepared.meta.resumeNotice);
+				if (displayOnlyTraceBlock) emitDisplayOnlyTraceBlock(stream, partial, displayOnlyTraceBlock);
 				stream.push({ type: "done", reason: "stop", message: partial });
 				break;
 		}
 	}
 
 	private async applyErrorOutcome(prepared: CursorProviderTurnPrepareResult | undefined, error: unknown): Promise<void> {
-		this.params.sdkEventDebug()?.recordError("provider_stream", error);
-		prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(
+		this.safeCleanup(() => prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(
 			buildIncompleteCursorToolRunOutcome({
 				status: error instanceof CursorLiveRunAbortError ? "cancelled" : "error",
 				signalAborted: error instanceof CursorLiveRunAbortError,
 			}),
-		);
+		));
 		const activeLiveRun = prepared?.runtime.liveRun;
 		if (activeLiveRun && !activeLiveRun.disposed) {
 			await cursorLiveRuns.release(activeLiveRun);
 		} else {
-			await abandonSessionCursorAgent(prepared?.sessionAgentScopeKey);
+			await prepared?.lifecycle.abandon();
 		}
+		this.safeCleanup(() => this.params.sdkEventDebug()?.recordError("provider_stream", error));
 		if (error instanceof CursorLiveRunAbortError) {
 			this.params.sdkProcessErrorGuard.suppressAbortErrors();
 			this.pushTerminalError(this.params.runnerParams.partial, "aborted", this.abortMessage());

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

@@ -1,6 +1,13 @@
 import type { RunError, SDKAgent } from "@cursor/sdk";
 import { loadCursorTranscriptWebToolCallsAfterOffset } from "./cursor-agent-message-web-tools.js";
+import {
+	collectCursorCloudRunReport,
+	formatCursorCloudRunReport,
+	type CursorCloudRunReport,
+} from "./cursor-cloud-reporting.js";
+import { recordCursorCloudLifecycleRun } from "./cursor-cloud-lifecycle.js";
 import { getCheckpointContextWindow, saveCachedContextWindow } from "./context-window-cache.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import {
@@ -78,6 +85,22 @@ async function replayCursorTranscriptWebToolCalls(
 	}
 }
 
+function scrubCursorCloudReportingError(error: unknown, apiKey: string | undefined): Error {
+	return new Error(scrubSensitiveText(error instanceof Error ? error.message : String(error), apiKey));
+}
+
+function recordCursorCloudReportingError(
+	sdkEventDebug: CursorSdkEventDebugSink | undefined,
+	error: unknown,
+	apiKey: string | undefined,
+): void {
+	try {
+		sdkEventDebug?.recordError("cloud_run_report", scrubCursorCloudReportingError(error, apiKey));
+	} catch {
+		// Debug reporting must never affect provider execution.
+	}
+}
+
 export interface AwaitFinalizeCursorRunOutcomeParams {
 	run: Awaited<ReturnType<SDKAgent["send"]>>;
 	prepared: CursorProviderTurnPrepareResult;
@@ -95,10 +118,15 @@ export interface AwaitFinalizeCursorRunOutcomeParams {
 	contextWindowAgentId?: string;
 }
 
+export interface FinalizedCursorRunOutcome {
+	outcome: CursorRunOutcome;
+	displayOnlyTraceBlock?: string;
+}
+
 /** Single wait/finalize path for SDK runs: wait, debug capture, transcript replay, incomplete tools, artifacts, context cache. */
-export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorRunOutcomeParams): Promise<CursorRunOutcome> {
+export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorRunOutcomeParams): Promise<FinalizedCursorRunOutcome> {
+	const apiKey = params.resolvedApiKey ?? params.optionsApiKey;
 	const waitResult = params.waitResult ?? (await params.run.wait());
-	params.sdkEventDebug?.recordWaitResult(waitResult);
 	const outcome = buildCursorRunOutcomeFromWait({
 		waitResult,
 		prepared: params.prepared,
@@ -108,7 +136,41 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 		resolvedApiKey: params.resolvedApiKey,
 		optionsApiKey: params.optionsApiKey,
 	});
-	if (isCursorRunFinishedSuccessfully(outcome)) {
+	let displayOnlyTraceBlock: string | undefined;
+	if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
+		let report: CursorCloudRunReport = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
+		try {
+			report = await collectCursorCloudRunReport({
+				agent: params.prepared.agent,
+				run: params.run,
+				waitResult,
+				apiKey,
+			});
+		} catch (error) {
+			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
+		}
+		try {
+			recordCursorCloudLifecycleRun(report, { apiKey });
+		} catch (error) {
+			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
+		}
+		try {
+			params.sdkEventDebug?.recordProviderEvent("cloud_run_report", report);
+		} catch (error) {
+			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
+		}
+		try {
+			displayOnlyTraceBlock = formatCursorCloudRunReport(report, { apiKey });
+		} catch (error) {
+			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
+		}
+	}
+	try {
+		params.sdkEventDebug?.recordWaitResult(waitResult);
+	} catch {
+		// Debug reporting must never affect provider execution.
+	}
+	if (params.prepared.runtimeTarget === "local" && isCursorRunFinishedSuccessfully(outcome)) {
 		await replayCursorTranscriptWebToolCalls(
 			params.run.agentId,
 			params.prepared.cwd,
@@ -118,9 +180,13 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 		);
 	}
 	params.prepared.runtime.turnCoordinator.discardIncompleteStartedToolCalls(outcome.incompleteTools);
-	await params.sdkEventDebug?.captureRunArtifacts(params.run);
-	if (params.cacheContextWindow !== false) {
+	try {
+		await params.sdkEventDebug?.captureRunArtifacts(params.run);
+	} catch {
+		// Debug artifact failures must never affect provider execution.
+	}
+	if (params.prepared.runtimeTarget === "local" && params.cacheContextWindow !== false) {
 		await cacheSdkContextWindow(params.contextWindowAgentId ?? params.run.agentId, params.modelId, params.prepared.cwd);
 	}
-	return outcome;
+	return { outcome, displayOnlyTraceBlock };
 }