pi-cursor-sdk 0.4.0 → 0.5.2

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
@@ -142,12 +145,12 @@ export class CursorRunFinalizer {
 		sendResult: CursorProviderTurnSendResult | undefined,
 		liveCompletion: CursorLiveRunCompletion | undefined,
 	): Promise<void> {
-		this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 		const abortRegistration = sendResult?.abortRegistration;
 		this.params.runnerParams.sdkEventDebugRef.current = undefined;
 		if (liveCompletion) {
 			void liveCompletion.waitCompletion
 				.finally(async () => {
+					this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 					if (abortRegistration) {
 						this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
 					}
@@ -157,6 +160,7 @@ export class CursorRunFinalizer {
 				.catch(() => {});
 			return;
 		}
+		this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
 		if (abortRegistration) {
 			this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
 		}
@@ -166,11 +170,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 +195,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 +204,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 +222,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

@@ -1,6 +1,6 @@
 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 type { AgentModeOption, AgentOptions, ModelSelection, SDKAgent } from "@cursor/sdk";
 import { configureCursorSdkHttp1 } from "./cursor-http1.js";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
 import { ensureCursorRipgrepPath } from "./cursor-ripgrep-path.js";
@@ -13,7 +13,7 @@ import {
 	type CursorSessionSendPlan,
 } from "./cursor-session-agent.js";
 import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
-import { buildCursorPrompt, estimateCursorPromptTokens } from "./context.js";
+import { buildCursorPrompt, estimateCursorPromptTokens, getCursorPendingInput } from "./context.js";
 import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
 import { getActiveContextToolNames } from "./cursor-context-tools.js";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
@@ -22,7 +22,6 @@ import {
 	createCursorNativeReplayId,
 	cursorLiveRuns,
 	getActiveCursorLiveRunForCurrentScope,
-	getPendingCursorLiveRun,
 } from "./cursor-provider-live-run-drain.js";
 import {
 	getCursorProviderAgentModeOrThrow,
@@ -30,6 +29,7 @@ import {
 } from "./cursor-state.js";
 import { resolveEffectiveCursorConfig } from "./cursor-runtime-state.js";
 import type { CursorResolvedSdkConfig } from "./cursor-config.js";
+import { buildCursorCustomSubagentDefinitions } from "./cursor-custom-subagent-definitions.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
 import {
@@ -38,17 +38,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 +59,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;
@@ -77,14 +75,20 @@ interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnPara
 	agentMode: AgentModeOption;
 	selection: ModelSelection;
 	fastEnabled: boolean | undefined;
+	agents: AgentOptions["agents"];
+	customSubagentNames: string[] | undefined;
 }
 
-function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "bootstrap" | "never"): Context {
+function buildCursorCloudPromptContext(context: Context, handoff: "fresh" | "bootstrap" | "never", nativeSourceRoles?: readonly string[]): Context {
 	if (handoff === "bootstrap") return context;
 	// 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);
+	if (nativeSourceRoles) {
+		const { start } = getCursorPendingInput(messages, nativeSourceRoles);
+		return { ...current, messages: messages.slice(start) };
+	}
 	for (let index = messages.length - 1; index >= 0; index -= 1) {
 		const message = messages[index];
 		if (message.role === "user") return { ...current, messages: [message] };
@@ -94,8 +98,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 {
@@ -124,7 +128,7 @@ function buildLocalCursorProviderTurnLifecycle(
 async function prepareCursorCloudProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<CloudCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -143,22 +147,22 @@ 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.");
 		}
 
 		const { Agent } = await loadCursorSdk();
 		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+		const promptContext = buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value, params.request.nativeSourceRoles);
+		const nativeSourceRoles = params.request.nativeSourceRoles;
 		const promptOptions = {
 			...getCursorPromptOptions(model),
+			nativeSourceRoles: nativeSourceRoles?.slice(nativeSourceRoles.length - getCursorConversationMessages(promptContext).length),
 			agentMode,
 			includePiBridgeGuidance: false,
 			includePiAskQuestionGuidance: false,
 		};
-		const prompt = buildCursorPrompt(
-			buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value),
-			promptOptions,
-		);
+		const prompt = buildCursorPrompt(promptContext, promptOptions);
 		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
 		const agent = await suppressCursorSdkOutput(() =>
 			Agent.create(buildCursorCloudAgentOptions({
@@ -166,11 +170,12 @@ async function prepareCursorCloudProviderTurn(
 				modelSelection: selection,
 				agentMode,
 				resolvedConfig,
-				name: getCursorSessionName(),
+				name: params.scope.sessionName,
+				agents,
 			})),
 		);
 		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" });
@@ -204,12 +209,15 @@ async function prepareCursorCloudProviderTurn(
 			promptOptions,
 			agentMode,
 			localForce: false,
+			...(customSubagentNames ? { customSubagentNames } : {}),
 		});
 
 		completed = true;
 		cloudAgentForCleanup = undefined;
 		return {
 			runtimeTarget: "cloud",
+			execution: "conversation",
+			recordCloudLifecycle: params.recordCloudLifecycle,
 			agent,
 			cwd,
 			payload: {
@@ -244,7 +252,7 @@ async function prepareCursorCloudProviderTurn(
 async function prepareCursorLocalProviderTurn(
 	prepareParams: PrepareCursorProviderTurnContext,
 ): Promise<LocalCursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled, agents, customSubagentNames } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -272,13 +280,17 @@ async function prepareCursorLocalProviderTurn(
 		let liveRunForBridgeQueue: CursorLiveRun | undefined;
 
 		const sessionAgentAcquireParams = {
+			scope: params.scope,
+			bridge: params.bridge,
 			apiKey: resolvedApiKey,
 			agentMode,
 			cwd,
 			modelSelection: selection,
 			settingSources,
 			localSafety,
+			agents,
 			localResume: resolvedConfig.local.resume.value,
+			storeRoot: resolvedConfig.local.storeRoot.value,
 			useHttp1ForAgent,
 			debugRecorder: sdkEventDebug,
 			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
@@ -300,9 +312,10 @@ async function prepareCursorLocalProviderTurn(
 		const buildPromptOptions = (plan: ReturnType<typeof planCursorSessionSend>) => {
 			const promptOptions = {
 				...getCursorPromptOptions(model),
+				nativeSourceRoles: params.request.nativeSourceRoles,
 				agentMode,
 				includePiBridgeGuidance,
-				includePiAskQuestionGuidance: bridgeToolNames.has("pi__cursor_ask_question"),
+				includePiAskQuestionGuidance: false,
 			};
 			if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
 				return promptOptions;
@@ -316,7 +329,7 @@ async function prepareCursorLocalProviderTurn(
 				}),
 			};
 		};
-		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
 		if (sessionAgentLease.created && sessionAgentLease.resumed && sendPlan.mode === "incremental") {
 			sendPlan = { mode: "bootstrap", resetAgent: false, reason: "process_resume" };
 		}
@@ -328,7 +341,7 @@ async function prepareCursorLocalProviderTurn(
 			sessionAgentScopeKey = sessionAgentLease.scopeKey;
 			bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
 			includePiBridgeGuidance = bridgeToolNames.size > 0;
-			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+			sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context, params.request.nativeSourceRoles);
 			promptOptions = buildPromptOptions(sendPlan);
 			prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
 		}
@@ -341,7 +354,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: {
@@ -364,6 +377,7 @@ async function prepareCursorLocalProviderTurn(
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
 			bridgeRunId: bridgeRun?.id,
+			...(customSubagentNames ? { customSubagentNames } : {}),
 		});
 		const nativeReplayId = createCursorNativeReplayId();
 		const textDeltas: string[] = [];
@@ -378,6 +392,7 @@ async function prepareCursorLocalProviderTurn(
 					promptInputTokens,
 					textDeltas,
 					debugRecorder: sdkEventDebug,
+					nativeDisplay: params.nativeDisplay,
 				})
 			: undefined;
 		if (liveRun) {
@@ -394,6 +409,7 @@ async function prepareCursorLocalProviderTurn(
 			liveRun,
 			useNativeToolReplay,
 			activeToolNames,
+			registeredToolNames: params.nativeDisplay ? new Set(params.nativeDisplay.registeredNativeToolSources.keys()) : undefined,
 			nativeReplayId,
 			textDeltas,
 			debugRecorder: sdkEventDebug,
@@ -402,6 +418,9 @@ async function prepareCursorLocalProviderTurn(
 		completed = true;
 		return {
 			runtimeTarget: "local",
+			execution: "conversation",
+			store: sessionAgentLease.store,
+			storeIdentity: sessionAgentLease.storeIdentity,
 			agent,
 			cwd,
 			payload: sendPayload,
@@ -449,10 +468,15 @@ 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);
-	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled };
+	if (resolvedConfig.runtime.value === "local" && params.request.purpose !== "normal") {
+		return prepareCursorSummaryProviderTurn(prepareParams, selection);
+	}
+	const agentMode = getCursorProviderAgentModeOrThrow(params.scope.scopeKey);
+	const agents = buildCursorCustomSubagentDefinitions(resolvedConfig.subagents.value);
+	const customSubagentNames = agents ? Object.keys(agents) : undefined;
+	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled, agents, customSubagentNames };
 
 	return resolvedConfig.runtime.value === "cloud"
 		? prepareCursorCloudProviderTurn(context)