pi-cursor-sdk 0.4.0 → 0.5.0

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

@@ -64,12 +64,12 @@ function getCursorNativeReplayIdFromToolCallId(toolCallId: string): string | und
 	return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
 }
 
-export function getPendingCursorLiveRun(context: Context): CursorLiveRun | undefined {
-	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
+export function getPendingCursorLiveRun(context: Context, scopeKey: string): CursorLiveRun | undefined {
+	return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId, scopeKey);
 }
 
-export function getActiveCursorLiveRunForCurrentScope(): CursorLiveRun | undefined {
-	return cursorLiveRuns.getActiveForScope();
+export function getActiveCursorLiveRunForCurrentScope(scopeKey?: string): CursorLiveRun | undefined {
+	return cursorLiveRuns.getActiveForScope(scopeKey);
 }
 
 function splitTextIntoReplayDeltas(text: string): string[] {
@@ -176,6 +176,7 @@ function emitCursorNativeToolUseTurn(
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
 	tools: CursorNativeToolDisplayItem[],
+	occupancyFloor: number | undefined,
 	debugRecorder?: CursorSdkEventDebugRecorder,
 ): void {
 	const shouldTerminate = run.done && !run.finalText?.trim() && !cursorLiveRuns.peekEvent(run);
@@ -193,7 +194,7 @@ function emitCursorNativeToolUseTurn(
 		stream.push({ type: "toolcall_delta", contentIndex, delta: serializedArgs, partial });
 		const block = partial.content[contentIndex];
 		if (block.type === "toolCall") stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
-		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate })) {
+		if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate }, run.nativeDisplay)) {
 			run.recordedToolDisplayIds.push(tool.id);
 			debugRecorder?.recordDrainEvent("native_tool_display_recorded", {
 				toolId: tool.id,
@@ -205,6 +206,7 @@ function emitCursorNativeToolUseTurn(
 	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 		runtime: "local",
 		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+		occupancyFloor,
 	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
@@ -236,6 +238,7 @@ function emitCursorBridgeToolUseTurn(
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
 	requests: CursorPiBridgeToolRequest[],
+	occupancyFloor: number | undefined,
 ): void {
 	for (const request of requests) {
 		const contentIndex = partial.content.length;
@@ -254,6 +257,7 @@ function emitCursorBridgeToolUseTurn(
 	applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 		runtime: "local",
 		turn: cursorLiveRuns.takeSdkTurnUsage(run),
+		occupancyFloor,
 	});
 	partial.stopReason = "toolUse";
 	stream.push({ type: "done", reason: "toolUse", message: partial });
@@ -268,7 +272,7 @@ async function emitCursorLiveRunPendingToolUseTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; occupancyFloor?: number },
 ): Promise<"tool_use" | "handled" | undefined> {
 	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	const eventType = cursorLiveRuns.peekEvent(run)?.type;
@@ -285,13 +289,13 @@ async function emitCursorLiveRunPendingToolUseTurn(
 		}
 		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
-		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, debugRecorder);
+		emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, options.occupancyFloor, debugRecorder);
 	} else {
 		const requests = cursorLiveRuns.collectBridgeToolBatch(run);
 		if (requests.length === 0) return "handled";
 		if (!sdkTurnEnded) cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
 		if (options.mode === "emit") turn.emitter.closeAll();
-		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests);
+		emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests, options.occupancyFloor);
 	}
 	return "tool_use";
 }
@@ -303,7 +307,7 @@ export async function drainCursorLiveRunTurn(
 	context: Context,
 	run: CursorLiveRun,
 	toolResultInputTokens: number,
-	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; emitter?: CursorPartialContentEmitter },
+	options: { mode: CursorLiveRunDrainMode; signal?: AbortSignal; debugRecorder?: CursorSdkEventDebugRecorder; emitter?: CursorPartialContentEmitter; occupancyFloor?: number },
 ): Promise<CursorLiveRunDrainOutcome> {
 	const debugRecorder = options.debugRecorder ?? run.debugRecorder;
 	debugRecorder?.recordDrainEvent("turn_start", {
@@ -390,7 +394,7 @@ export async function drainCursorLiveRunTurn(
 				applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
 					runtime: "local",
 					turn: cursorLiveRuns.takeSdkTurnUsage(run),
-					billed: run.billedTurnUsage,
+					occupancyFloor: options.occupancyFloor,
 				});
 				if (run.resumeNotice) {
 					emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);
@@ -436,12 +440,14 @@ export async function drainExistingCursorLiveRunBeforeSend(
 	partial: AssistantMessage,
 	model: Model<Api>,
 	context: Context,
-	signal?: AbortSignal,
-	turnDebugRecorder?: CursorSdkEventDebugRecorder,
+	signal: AbortSignal | undefined,
+	turnDebugRecorder: CursorSdkEventDebugRecorder | undefined,
+	scopeKey: string,
+	occupancyFloor?: number,
 ): Promise<LiveRunPreSendOutcome> {
 	turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
 	while (true) {
-		const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+		const run = getPendingCursorLiveRun(context, scopeKey) ?? getActiveCursorLiveRunForCurrentScope(scopeKey);
 		if (!run || run.disposed) {
 			turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
 			return "continue_send";
@@ -462,6 +468,7 @@ export async function drainExistingCursorLiveRunBeforeSend(
 					mode: shouldChainUserInput ? "chain_user_input" : "emit",
 					signal,
 					debugRecorder: turnDebugRecorder,
+					occupancyFloor,
 				});
 				const mapped = drainOutcome === "chain_user_input" ? "continue_send" : "stream_ended";
 				turnDebugRecorder?.recordDrainEvent("pre_send_iteration", {

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

@@ -18,7 +18,7 @@ import {
 } from "./cursor-incomplete-tool-visibility.js";
 import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
-import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
+import { awaitFinalizeCursorRunOutcome, recordCursorProviderTerminalUsage } from "./cursor-provider-turn-finalize.js";
 import type {
 	CursorProviderTurnPrepareResult,
 	CursorProviderTurnRunnerParams,
@@ -26,6 +26,7 @@ import type {
 	CursorProviderTurnSendResult,
 	LiveCursorProviderTurnRuntime,
 	LocalCursorProviderTurnPrepareResult,
+	StartedCursorProviderTurn,
 } from "./cursor-provider-turn-types.js";
 import { applyCursorUsage } from "./cursor-usage-accounting.js";
 import { hasUsableText } from "./cursor-record-utils.js";
@@ -33,15 +34,15 @@ import { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
 export type CursorTurnTerminalEvent =
 	| {
 			kind: "direct";
-			prepared: CursorProviderTurnPrepareResult;
+			prepared: StartedCursorProviderTurn;
 			outcome: CursorRunOutcome;
 			displayOnlyTraceBlock?: string;
 	  }
-	| { kind: "error"; prepared: CursorProviderTurnPrepareResult | undefined; error: unknown };
+	| { kind: "error"; prepared: CursorProviderTurnPrepareResult | StartedCursorProviderTurn | undefined; error: unknown };
 
 function applyLiveRunOutcome(
 	outcome: CursorRunOutcome,
-	prepared: LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime },
+	prepared: StartedCursorProviderTurn & LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime },
 	context: CursorProviderTurnRunnerParams["context"],
 ): void {
 	if (prepared.runtime.liveRun.disposed) return;
@@ -63,7 +64,7 @@ function applyLiveRunOutcome(
 
 export interface CursorLiveRunCompletion {
 	waitCompletion: Promise<void>;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: StartedCursorProviderTurn;
 }
 
 export interface CursorRunFinalizerParams {
@@ -76,7 +77,7 @@ export interface CursorRunFinalizerParams {
 
 export interface StartCursorLiveRunCompletionParams {
 	send: CursorProviderTurnSend;
-	prepared: LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
+	prepared: StartedCursorProviderTurn & LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
 	modelId: string;
 	discardIncompleteTools: (outcome: IncompleteCursorToolRunOutcomeInput) => void;
 }
@@ -110,14 +111,16 @@ export class CursorRunFinalizer {
 				applyLiveRunOutcome(finalized.outcome, prepared, runnerParams.context);
 			})
 			.catch((error: unknown) => {
-				this.safeCleanup(() => discardIncompleteTools({ status: "error" }));
+				const aborted = error instanceof CursorLiveRunAbortError || runnerParams.options?.signal?.aborted === true;
+				this.safeCleanup(() => discardIncompleteTools({ status: aborted ? "cancelled" : "error" }));
 				if (!liveRun.disposed) {
-					cursorLiveRuns.markError(
+					if (aborted) cursorLiveRuns.markCancelled(liveRun, this.abortMessage());
+					else cursorLiveRuns.markError(
 						liveRun,
 						sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? runnerParams.options?.apiKey, "local"),
 					);
 				}
-				this.safeCleanup(() => sdkEventDebug?.recordWaitResult({ status: "error", error: String(error) }));
+				this.safeCleanup(() => sdkEventDebug?.recordWaitResult({ status: aborted ? "cancelled" : "error", error: String(error) }));
 				this.safeCleanup(() => sdkEventDebug?.recordError("run_wait", error));
 			});
 		// Mark the pooled local agent busy as soon as the SDK run exists so auto-compaction summarization
@@ -166,11 +169,13 @@ export class CursorRunFinalizer {
 	}
 
 	private async applyDirectOutcome(
-		prepared: CursorProviderTurnPrepareResult,
+		prepared: StartedCursorProviderTurn,
 		outcome: CursorRunOutcome,
 		displayOnlyTraceBlock: string | undefined,
 	): Promise<void> {
 		const { stream, partial, model, context } = this.params.runnerParams;
+		// Native summaries return at terminal emission, so release their temporary resources first.
+		if (prepared.execution === "summary") await prepared.lifecycle.dispose().catch(() => {});
 		prepared.runtime.turnCoordinator.closeTraceBlock();
 		switch (classifyCursorRunEmission(outcome)) {
 			case "cancelled":
@@ -189,7 +194,7 @@ export class CursorRunFinalizer {
 				applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
 					runtime: prepared.runtimeTarget,
 					turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
-					billed: prepared.runtime.billedTurnUsage,
+					occupancyFloor: this.params.runnerParams.request.occupancyFloor,
 				});
 				if (prepared.meta.resumeNotice) emitDisplayOnlyTraceBlock(stream, partial, prepared.meta.resumeNotice);
 				if (displayOnlyTraceBlock) emitDisplayOnlyTraceBlock(stream, partial, displayOnlyTraceBlock);
@@ -198,11 +203,15 @@ export class CursorRunFinalizer {
 		}
 	}
 
-	private async applyErrorOutcome(prepared: CursorProviderTurnPrepareResult | undefined, error: unknown): Promise<void> {
+	private async applyErrorOutcome(prepared: CursorProviderTurnPrepareResult | StartedCursorProviderTurn | undefined, error: unknown): Promise<void> {
+		const aborted = error instanceof CursorLiveRunAbortError || this.params.runnerParams.options?.signal?.aborted === true;
+		if (prepared && "usage" in prepared && (!prepared.runtime.sdkRun || prepared.runtime.kind !== "live")) {
+			await recordCursorProviderTerminalUsage(prepared, aborted ? "abort" : "error");
+		}
 		this.safeCleanup(() => prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(
 			buildIncompleteCursorToolRunOutcome({
-				status: error instanceof CursorLiveRunAbortError ? "cancelled" : "error",
-				signalAborted: error instanceof CursorLiveRunAbortError,
+				status: aborted ? "cancelled" : "error",
+				signalAborted: aborted,
 			}),
 		));
 		const activeLiveRun = prepared?.runtime.liveRun;
@@ -212,7 +221,7 @@ export class CursorRunFinalizer {
 			await prepared?.lifecycle.abandon();
 		}
 		this.safeCleanup(() => this.params.sdkEventDebug()?.recordError("provider_stream", error));
-		if (error instanceof CursorLiveRunAbortError) {
+		if (aborted) {
 			this.params.sdkProcessErrorGuard.suppressAbortErrors();
 			this.pushTerminalError(this.params.runnerParams.partial, "aborted", this.abortMessage());
 		} else {

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

@@ -43,6 +43,7 @@ export interface CursorSdkTurnCoordinatorOptions {
 	liveRun?: CursorLiveRun;
 	useNativeToolReplay: boolean;
 	activeToolNames?: ReadonlySet<string>;
+	registeredToolNames?: ReadonlySet<string>;
 	nativeReplayId: string;
 	textDeltas: string[];
 	debugRecorder?: CursorSdkEventDebugRecorder;
@@ -86,6 +87,7 @@ export class CursorSdkTurnCoordinator {
 			liveRun: options.liveRun,
 			useNativeToolReplay: options.useNativeToolReplay,
 			activeToolNames: options.activeToolNames,
+			registeredToolNames: options.registeredToolNames,
 			nativeReplayId: options.nativeReplayId,
 			contentEmitter: this.contentEmitter,
 			debugRecorder: options.debugRecorder,

package/src/cursor-provider-turn-display-router.ts

@@ -29,6 +29,7 @@ export interface CursorTurnDisplayRouterOptions {
 	liveRun?: CursorLiveRun;
 	useNativeToolReplay: boolean;
 	activeToolNames?: ReadonlySet<string>;
+	registeredToolNames?: ReadonlySet<string>;
 	nativeReplayId: string;
 	contentEmitter: CursorPartialContentEmitter;
 	debugRecorder?: CursorSdkEventDebugRecorder;
@@ -44,6 +45,7 @@ export class CursorTurnDisplayRouter {
 	private readonly liveRun?: CursorLiveRun;
 	private readonly useNativeToolReplay: boolean;
 	private readonly activeToolNames?: ReadonlySet<string>;
+	private readonly registeredToolNames?: ReadonlySet<string>;
 	private readonly nativeReplayId: string;
 	private readonly contentEmitter: CursorPartialContentEmitter;
 	private readonly debugRecorder?: CursorSdkEventDebugRecorder;
@@ -57,6 +59,7 @@ export class CursorTurnDisplayRouter {
 		this.liveRun = options.liveRun;
 		this.useNativeToolReplay = options.useNativeToolReplay;
 		this.activeToolNames = options.activeToolNames;
+		this.registeredToolNames = options.registeredToolNames;
 		this.nativeReplayId = options.nativeReplayId;
 		this.contentEmitter = options.contentEmitter;
 		this.debugRecorder = options.debugRecorder;
@@ -75,6 +78,7 @@ export class CursorTurnDisplayRouter {
 			toolName: display.toolName,
 			useNativeToolReplay: this.useNativeToolReplay,
 			activeToolNames: this.activeToolNames,
+			registeredToolNames: this.registeredToolNames,
 			hasLiveRun: this.liveRun !== undefined,
 		});
 
@@ -122,6 +126,7 @@ export class CursorTurnDisplayRouter {
 			toolName: display.toolName,
 			useNativeToolReplay: this.useNativeToolReplay,
 			activeToolNames: this.activeToolNames,
+			registeredToolNames: this.registeredToolNames,
 			hasLiveRun: this.liveRun !== undefined,
 		});
 

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

@@ -13,12 +13,13 @@ import {
 import type {
 	CursorProviderTurnPrepareResult,
 	CursorProviderTurnRunnerParams,
+	StartedCursorProviderTurn,
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 
 export interface EmitCursorLiveTurnParams {
 	params: CursorProviderTurnRunnerParams;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: StartedCursorProviderTurn;
 	sdkEventDebug: CursorSdkEventDebugSink | undefined;
 	discardIncompleteTools: (outcome: IncompleteCursorToolRunOutcomeInput) => void;
 }
@@ -42,6 +43,7 @@ export async function emitCursorLiveTurn(emitParams: EmitCursorLiveTurnParams):
 				emitter,
 				signal: options?.signal,
 				debugRecorder: sdkEventDebug,
+				occupancyFloor: params.request.occupancyFloor,
 			});
 		});
 	} catch (caught) {

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

@@ -5,7 +5,6 @@ import {
 	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";
@@ -15,9 +14,8 @@ import {
 	resolveCursorRunOutcome,
 	type CursorRunOutcome,
 } from "./cursor-provider-run-outcome.js";
-import type { CursorProviderTurnPrepareResult } from "./cursor-provider-turn-types.js";
+import type { StartedCursorProviderTurn } 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,
@@ -45,7 +43,7 @@ export async function cacheSdkContextWindow(
 
 export interface BuildCursorRunOutcomeParams {
 	waitResult: Awaited<ReturnType<Awaited<ReturnType<SDKAgent["send"]>>["wait"]>>;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: StartedCursorProviderTurn;
 	signal?: AbortSignal;
 	runResultFallback?: string;
 	runErrorFallback?: RunError;
@@ -117,7 +115,7 @@ function recordCursorCloudReportingError(
 
 export interface AwaitFinalizeCursorRunOutcomeParams {
 	run: Awaited<ReturnType<SDKAgent["send"]>>;
-	prepared: CursorProviderTurnPrepareResult;
+	prepared: StartedCursorProviderTurn;
 	cursorAgentMessageOffset: number | undefined;
 	modelId: string;
 	signal?: AbortSignal;
@@ -137,10 +135,32 @@ export interface FinalizedCursorRunOutcome {
 	displayOnlyTraceBlock?: string;
 }
 
-/** Single wait/finalize path for SDK runs: wait, debug capture, transcript replay, incomplete tools, artifacts, context cache. */
+export async function recordCursorProviderTerminalUsage(
+	prepared: StartedCursorProviderTurn,
+	status: "success" | "error" | "abort",
+	waitUsage?: unknown,
+) {
+	if (prepared.runtime.usageTerminalRecorded) return undefined;
+	prepared.runtime.usageTerminalRecorded = true;
+	try {
+		return await prepared.usage.recordTerminal({ status, waitUsage, handleUsage: prepared.runtime.sdkRun?.usage });
+	} catch (error) {
+		prepared.usage.notePersistenceFailure(error);
+		return undefined;
+	}
+}
+
+/** Single wait/finalize path for SDK runs: accounting, replay, incomplete tools, artifacts, context cache. */
 export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorRunOutcomeParams): Promise<FinalizedCursorRunOutcome> {
 	const apiKey = params.resolvedApiKey ?? params.optionsApiKey;
-	const waitResult = params.waitResult ?? (await params.run.wait());
+	params.prepared.runtime.sdkRun = params.run;
+	let waitResult: Awaited<ReturnType<typeof params.run.wait>>;
+	try {
+		waitResult = params.waitResult ?? (await params.run.wait());
+	} catch (error) {
+		await recordCursorProviderTerminalUsage(params.prepared, params.signal?.aborted ? "abort" : "error");
+		throw error;
+	}
 	const outcome = buildCursorRunOutcomeFromWait({
 		waitResult,
 		prepared: params.prepared,
@@ -150,16 +170,11 @@ 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;
-	}
+	const billing = await recordCursorProviderTerminalUsage(
+		params.prepared,
+		outcome.kind === "finished" ? "success" : outcome.kind === "cancelled" ? "abort" : "error",
+		waitResult.usage,
+	);
 	let displayOnlyTraceBlock: string | undefined;
 	if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
 		let report: CursorCloudRunReport = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
@@ -169,13 +184,13 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 				run: params.run,
 				waitResult,
 				apiKey,
-				agentUsage: billed.agentUsage,
+				agentUsage: billing ? billing.status === "observed-pending-settlement" ? billing.snapshot : null : undefined,
 			});
 		} catch (error) {
 			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
 		}
 		try {
-			recordCursorCloudLifecycleRun(report, { apiKey });
+			params.prepared.recordCloudLifecycle(report, apiKey);
 		} catch (error) {
 			recordCursorCloudReportingError(params.sdkEventDebug, error, apiKey);
 		}
@@ -195,12 +210,12 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 	} catch {
 		// Debug reporting must never affect provider execution.
 	}
-	if (params.prepared.runtimeTarget === "local" && isCursorRunFinishedSuccessfully(outcome)) {
+	if (params.prepared.runtimeTarget === "local" && params.prepared.execution === "conversation" && isCursorRunFinishedSuccessfully(outcome)) {
 		await replayCursorTranscriptWebToolCalls(
 			params.run.agentId,
 			params.prepared.cwd,
 			params.cursorAgentMessageOffset,
-			params.prepared.sessionAgentLease.store,
+			params.prepared.store,
 			params.prepared.runtime.turnCoordinator,
 			params.sdkEventDebug,
 		);
@@ -211,12 +226,12 @@ export async function awaitFinalizeCursorRunOutcome(params: AwaitFinalizeCursorR
 	} catch {
 		// Debug artifact failures must never affect provider execution.
 	}
-	if (params.prepared.runtimeTarget === "local" && params.cacheContextWindow !== false) {
+	if (params.prepared.runtimeTarget === "local" && params.prepared.execution === "conversation" && params.cacheContextWindow !== false) {
 		await cacheSdkContextWindow(
 			params.contextWindowAgentId ?? params.run.agentId,
 			params.modelId,
 			params.prepared.cwd,
-			params.prepared.sessionAgentLease.store,
+			params.prepared.store,
 		);
 	}
 	return { outcome, displayOnlyTraceBlock };

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

@@ -22,7 +22,6 @@ import {
 	createCursorNativeReplayId,
 	cursorLiveRuns,
 	getActiveCursorLiveRunForCurrentScope,
-	getPendingCursorLiveRun,
 } from "./cursor-provider-live-run-drain.js";
 import {
 	getCursorProviderAgentModeOrThrow,
@@ -38,17 +37,14 @@ import {
 	preflightCursorCloudRuntime,
 } from "./cursor-cloud-options.js";
 import { inspectCursorCloudLocalState } from "./cursor-cloud-local-state.js";
-import { getCursorSessionName, getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
+import { getCursorSessionProjectTrusted } from "./cursor-session-scope.js";
 import { resolveCursorPiToolBridgeEnabled } from "./cursor-pi-tool-bridge-env.js";
 import {
 	buildCursorToolManifestText,
 	resolveCursorToolManifestEnabled,
 } from "./cursor-tool-manifest.js";
 import { isCursorNativeToolDisplayRuntimeEnabled } from "./cursor-native-tool-display-state.js";
-import {
-	createCursorCloudLifecyclePersistenceError,
-	recordCursorCloudLifecycleSafely,
-} from "./cursor-cloud-lifecycle.js";
+import { createCursorCloudLifecyclePersistenceError } from "./cursor-cloud-lifecycle.js";
 import { MISSING_CURSOR_API_KEY_MESSAGE } from "./cursor-provider-errors.js";
 import { CursorSdkTurnCoordinator } from "./cursor-provider-turn-coordinator.js";
 import { resolveCursorApiKey } from "./cursor-api-key.js";
@@ -62,6 +58,7 @@ import type {
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
 import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
+import { prepareCursorSummaryProviderTurn } from "./cursor-provider-turn-summary.js";
 
 export interface PrepareCursorProviderTurnParams {
 	params: CursorProviderTurnRunnerParams;
@@ -94,8 +91,8 @@ function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "boo
 
 const CLOUD_SEND_PLAN: CursorSessionSendPlan = { mode: "bootstrap", resetAgent: false, reason: "initial" };
 
-export function resolveCursorProviderTurnConfig(cwd: string) {
-	return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+export function resolveCursorProviderTurnConfig(cwd: string, projectTrusted = getCursorSessionProjectTrusted(), scopeKey?: string) {
+	return resolveEffectiveCursorConfig({ cwd, projectTrusted, scopeKey });
 }
 
 function buildCloudCursorProviderTurnLifecycle(agent: SDKAgent): CursorProviderTurnLifecycle {
@@ -143,7 +140,7 @@ async function prepareCursorCloudProviderTurn(
 			hasPriorContext: getCursorConversationMessages(context).length > 1,
 		});
 		if (!preflight.ok) throw new Error(formatCursorCloudPreflightError(preflight));
-		if (getPendingCursorLiveRun(context) || getActiveCursorLiveRunForCurrentScope()) {
+		if (getActiveCursorLiveRunForCurrentScope(params.scope.scopeKey)) {
 			throw new Error("Cursor cloud runtime cannot start while a local Cursor live run is pending; finish or abort the local run, then retry.");
 		}
 
@@ -166,11 +163,11 @@ async function prepareCursorCloudProviderTurn(
 				modelSelection: selection,
 				agentMode,
 				resolvedConfig,
-				name: getCursorSessionName(),
+				name: params.scope.sessionName,
 			})),
 		);
 		cloudAgentForCleanup = agent;
-		if (!recordCursorCloudLifecycleSafely({ agentId: agent.agentId }, resolvedApiKey)) {
+		if (!params.recordCloudLifecycle({ agentId: agent.agentId }, resolvedApiKey)) {
 			throw createCursorCloudLifecyclePersistenceError(agent.agentId, "intent", undefined, resolvedApiKey);
 		}
 		sdkEventDebug?.recordProviderMeta({ runtime: "cloud", cloudAgentId: agent.agentId, phase: "agent_created" });
@@ -210,6 +207,8 @@ async function prepareCursorCloudProviderTurn(
 		cloudAgentForCleanup = undefined;
 		return {
 			runtimeTarget: "cloud",
+			execution: "conversation",
+			recordCloudLifecycle: params.recordCloudLifecycle,
 			agent,
 			cwd,
 			payload: {
@@ -272,6 +271,8 @@ async function prepareCursorLocalProviderTurn(
 		let liveRunForBridgeQueue: CursorLiveRun | undefined;
 
 		const sessionAgentAcquireParams = {
+			scope: params.scope,
+			bridge: params.bridge,
 			apiKey: resolvedApiKey,
 			agentMode,
 			cwd,
@@ -341,7 +342,7 @@ async function prepareCursorLocalProviderTurn(
 		};
 		const sessionBridgeRun = bridgeRun;
 		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
-		const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+		const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled(params.nativeDisplay);
 		const activeToolNames = getActiveContextToolNames(context);
 		sdkEventDebug?.recordProviderMeta({
 			model: {
@@ -378,6 +379,7 @@ async function prepareCursorLocalProviderTurn(
 					promptInputTokens,
 					textDeltas,
 					debugRecorder: sdkEventDebug,
+					nativeDisplay: params.nativeDisplay,
 				})
 			: undefined;
 		if (liveRun) {
@@ -394,6 +396,7 @@ async function prepareCursorLocalProviderTurn(
 			liveRun,
 			useNativeToolReplay,
 			activeToolNames,
+			registeredToolNames: params.nativeDisplay ? new Set(params.nativeDisplay.registeredNativeToolSources.keys()) : undefined,
 			nativeReplayId,
 			textDeltas,
 			debugRecorder: sdkEventDebug,
@@ -402,6 +405,9 @@ async function prepareCursorLocalProviderTurn(
 		completed = true;
 		return {
 			runtimeTarget: "local",
+			execution: "conversation",
+			store: sessionAgentLease.store,
+			storeIdentity: sessionAgentLease.storeIdentity,
 			agent,
 			cwd,
 			payload: sendPayload,
@@ -449,9 +455,12 @@ export async function prepareCursorProviderTurn(
 	const { params, resolvedConfig } = prepareParams;
 	const { model, options } = params;
 
-	const agentMode = getCursorProviderAgentModeOrThrow();
-	const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id);
+	const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id, params.scope.scopeKey);
 	const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
+	if (resolvedConfig.runtime.value === "local" && params.request.purpose !== "normal") {
+		return prepareCursorSummaryProviderTurn(prepareParams, selection);
+	}
+	const agentMode = getCursorProviderAgentModeOrThrow(params.scope.scopeKey);
 	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled };
 
 	return resolvedConfig.runtime.value === "cloud"