pi-cursor-sdk 0.1.56 → 0.1.57

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

@@ -1,4 +1,5 @@
-import type { SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import type { Context, SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import type { AgentModeOption, ModelSelection, SDKAgent } from "@cursor/sdk";
 import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
 import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
 import {
@@ -6,9 +7,10 @@ import {
 	buildCursorSessionSendPrompt,
 	planCursorSessionSend,
 	resetSessionCursorAgent,
+	type CursorSessionSendPlan,
 } from "./cursor-session-agent.js";
 import type { CursorPiBridgeToolRequest } from "./cursor-pi-tool-bridge.js";
-import { estimateCursorPromptTokens } from "./context.js";
+import { buildCursorPrompt, estimateCursorPromptTokens } 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";
@@ -16,25 +18,47 @@ import {
 	abandonSessionCursorAgent,
 	createCursorNativeReplayId,
 	cursorLiveRuns,
+	getActiveCursorLiveRunForCurrentScope,
+	getPendingCursorLiveRun,
 } from "./cursor-provider-live-run-drain.js";
-import { getCursorProviderAgentModeOrThrow, getEffectiveFastForModelId } from "./cursor-state.js";
+import {
+	getCursorProviderAgentModeOrThrow,
+	getEffectiveFastForModelId,
+} from "./cursor-state.js";
+import { resolveEffectiveCursorConfig } from "./cursor-runtime-state.js";
+import type { CursorResolvedSdkConfig } from "./cursor-config.js";
 import { buildCursorModelSelection } from "./model-discovery.js";
 import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
+import {
+	formatCursorCloudPreflightError,
+	buildCursorCloudAgentOptions,
+	inspectCursorCloudLocalState,
+	preflightCursorCloudRuntime,
+} from "./cursor-cloud-options.js";
+import { getCursorSessionName, 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 { 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";
 import { loadCursorSdk } from "./cursor-sdk-runtime.js";
 import type {
+	CloudCursorProviderTurnPrepareResult,
+	CursorProviderTurnLifecycle,
 	CursorProviderTurnPrepareResult,
 	CursorProviderTurnRunnerParams,
+	LocalCursorProviderTurnPrepareResult,
 } from "./cursor-provider-turn-types.js";
 import type { CursorSdkEventDebugSink } from "./cursor-sdk-event-debug.js";
+import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
 
 export interface PrepareCursorProviderTurnParams {
 	params: CursorProviderTurnRunnerParams;
@@ -42,12 +66,173 @@ export interface PrepareCursorProviderTurnParams {
 	resolvedApiKey: string;
 	sdkEventDebug: CursorSdkEventDebugSink | undefined;
 	throwIfAborted: () => void;
+	/** Snapshot resolved once by the runner before draining; reused unchanged through prepare. */
+	resolvedConfig: CursorResolvedSdkConfig;
 }
 
-export async function prepareCursorProviderTurn(
-	prepareParams: PrepareCursorProviderTurnParams,
-): Promise<CursorProviderTurnPrepareResult> {
-	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted } = prepareParams;
+interface PrepareCursorProviderTurnContext extends PrepareCursorProviderTurnParams {
+	agentMode: AgentModeOption;
+	selection: ModelSelection;
+	fastEnabled: boolean | undefined;
+}
+
+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] };
+	}
+	return { ...context, messages: context.messages.slice(-1) };
+}
+
+const CLOUD_SEND_PLAN: CursorSessionSendPlan = { mode: "bootstrap", resetAgent: false, reason: "initial" };
+
+export function resolveCursorProviderTurnConfig(cwd: string) {
+	return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+}
+
+function buildCloudCursorProviderTurnLifecycle(agent: SDKAgent): CursorProviderTurnLifecycle {
+	return {
+		trackRunCompletion: () => {},
+		commitSend: () => {},
+		abandon: async () => {},
+		dispose: async () => {
+			await agent[Symbol.asyncDispose]?.();
+		},
+	};
+}
+
+function buildLocalCursorProviderTurnLifecycle(
+	lease: SessionCursorAgentLease,
+	scopeKey: string,
+): CursorProviderTurnLifecycle {
+	return {
+		trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
+		commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
+		abandon: () => abandonSessionCursorAgent(scopeKey),
+		dispose: async () => {},
+	};
+}
+
+async function prepareCursorCloudProviderTurn(
+	prepareParams: PrepareCursorProviderTurnContext,
+): Promise<CloudCursorProviderTurnPrepareResult> {
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+	const { model, context, options } = params;
+
+	let restoreCursorSdkOutputFilter: (() => void) | undefined;
+	let cloudAgentForCleanup: SDKAgent | undefined;
+	let completed = false;
+
+	try {
+		const preflight = preflightCursorCloudRuntime({
+			resolvedConfig,
+			localState: inspectCursorCloudLocalState(cwd),
+			hasPriorContext: context.messages.length > 1,
+		});
+		if (!preflight.ok) throw new Error(formatCursorCloudPreflightError(preflight));
+		if (getPendingCursorLiveRun(context) || getActiveCursorLiveRunForCurrentScope()) {
+			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 promptOptions = {
+			...getCursorPromptOptions(model),
+			agentMode,
+			includePiBridgeGuidance: false,
+			includePiAskQuestionGuidance: false,
+		};
+		const prompt = buildCursorPrompt(
+			buildCursorCloudPromptContext(context, resolvedConfig.cloud.contextHandoff.value),
+			promptOptions,
+		);
+		const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
+		const agent = await suppressCursorSdkOutput(() =>
+			Agent.create(buildCursorCloudAgentOptions({
+				apiKey: resolvedApiKey,
+				modelSelection: selection,
+				agentMode,
+				resolvedConfig,
+				name: getCursorSessionName(),
+			})),
+		);
+		cloudAgentForCleanup = agent;
+		if (!recordCursorCloudLifecycleSafely({ agentId: agent.agentId }, resolvedApiKey)) {
+			throw createCursorCloudLifecyclePersistenceError(agent.agentId, "intent", undefined, resolvedApiKey);
+		}
+		sdkEventDebug?.recordProviderMeta({ runtime: "cloud", cloudAgentId: agent.agentId, phase: "agent_created" });
+		throwIfAborted();
+
+		const textDeltas: string[] = [];
+		const nativeReplayId = createCursorNativeReplayId();
+		const turnCoordinator = new CursorSdkTurnCoordinator({
+			stream: params.stream,
+			partial: params.partial,
+			cwd,
+			resolvedApiKey,
+			useNativeToolReplay: false,
+			nativeReplayId,
+			textDeltas,
+			debugRecorder: sdkEventDebug,
+		});
+		sdkEventDebug?.recordProviderMeta({
+			runtime: "cloud",
+			cloudAgentId: agent.agentId,
+			model: {
+				id: model.id,
+				provider: model.provider,
+				api: model.api,
+				reasoning: options?.reasoning ?? "off",
+				fastEnabled,
+				selection,
+			},
+			contextHandoff: resolvedConfig.cloud.contextHandoff.value,
+			sendPlan: CLOUD_SEND_PLAN,
+			promptOptions,
+			agentMode,
+			localForce: false,
+		});
+
+		completed = true;
+		cloudAgentForCleanup = undefined;
+		return {
+			runtimeTarget: "cloud",
+			agent,
+			cwd,
+			payload: {
+				text: prompt.text,
+				images: prompt.images.length > 0 ? prompt.images : undefined,
+			},
+			meta: {
+				sendPlan: CLOUD_SEND_PLAN,
+				prompt,
+				bootstrap: true,
+				promptInputTokens,
+				useNativeToolReplay: false,
+				bridgeEnabled: false,
+				nativeReplayId,
+				agentMode,
+				modelSelection: selection,
+			},
+			contextWindowAgentId: agent.agentId,
+			textDeltas,
+			restoreCursorSdkOutputFilter,
+			lifecycle: buildCloudCursorProviderTurnLifecycle(agent),
+			runtime: { kind: "direct", turnCoordinator },
+		};
+	} finally {
+		if (!completed) {
+			await cloudAgentForCleanup?.[Symbol.asyncDispose]?.().catch(() => {});
+			restoreCursorSdkOutputFilter?.();
+		}
+	}
+}
+
+async function prepareCursorLocalProviderTurn(
+	prepareParams: PrepareCursorProviderTurnContext,
+): Promise<LocalCursorProviderTurnPrepareResult> {
+	const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
 	const { model, context, options } = params;
 
 	let restoreCursorSdkOutputFilter: (() => void) | undefined;
@@ -56,14 +241,15 @@ export async function prepareCursorProviderTurn(
 	let completed = false;
 
 	try {
-		const fastEnabled = getEffectiveFastForModelId(model.id);
-		const agentMode = getCursorProviderAgentModeOrThrow();
-		const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
-		const settingSources = getEffectiveCursorSettingSources();
+		const localSafety = {
+			autoReview: resolvedConfig.local.autoReview.value,
+			sandboxEnabled: resolvedConfig.local.sandboxEnabled.value,
+		};
 		const { Agent } = await loadCursorSdk();
 
 		installCursorMcpToolTimeoutOverride();
 		restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+		const settingSources = getEffectiveCursorSettingSources();
 		const queuedBridgeRequestsBeforeLiveRun: CursorPiBridgeToolRequest[] = [];
 		let liveRunForBridgeQueue: CursorLiveRun | undefined;
 
@@ -73,6 +259,8 @@ export async function prepareCursorProviderTurn(
 			cwd,
 			modelSelection: selection,
 			settingSources,
+			localSafety,
+			localResume: resolvedConfig.local.resume.value,
 			debugRecorder: sdkEventDebug,
 			onBridgeToolRequest: (request: CursorPiBridgeToolRequest) => {
 				if (liveRunForBridgeQueue && !liveRunForBridgeQueue.disposed) {
@@ -110,11 +298,14 @@ export async function prepareCursorProviderTurn(
 			};
 		};
 		let sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+		if (sessionAgentLease.created && sessionAgentLease.resumed && sendPlan.mode === "incremental") {
+			sendPlan = { mode: "bootstrap", resetAgent: false, reason: "process_resume" };
+		}
 		let promptOptions = buildPromptOptions(sendPlan);
 		let prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
 		if (sendPlan.resetAgent) {
 			await resetSessionCursorAgent(sessionAgentScopeKey);
-			sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
+			sessionAgentLease = await acquireSessionCursorAgent({ ...sessionAgentAcquireParams, forceCreate: true });
 			sessionAgentScopeKey = sessionAgentLease.scopeKey;
 			bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
 			includePiBridgeGuidance = bridgeToolNames.size > 0;
@@ -148,6 +339,9 @@ export async function prepareCursorProviderTurn(
 			promptOptions,
 			toolManifestEnabled: resolveCursorToolManifestEnabled(),
 			agentMode,
+			localForce: resolvedConfig.local.force.value,
+			localResume: resolvedConfig.local.resume.value,
+			resumedAgent: sessionAgentLease.resumed,
 			activeToolNames: activeToolNames ? [...activeToolNames] : [],
 			sessionAgentScopeKey,
 			bridgeRunId: bridgeRun?.id,
@@ -188,6 +382,7 @@ export async function prepareCursorProviderTurn(
 
 		completed = true;
 		return {
+			runtimeTarget: "local",
 			agent,
 			cwd,
 			payload: sendPayload,
@@ -200,12 +395,16 @@ export async function prepareCursorProviderTurn(
 				bridgeEnabled: bridgeRun !== undefined,
 				nativeReplayId,
 				agentMode,
+				modelSelection: selection,
+				...(sessionAgentLease.resumeNotice ? { resumeNotice: sessionAgentLease.resumeNotice } : {}),
 			},
 			contextWindowAgentId: agent.agentId,
 			textDeltas,
 			sessionAgentScopeKey,
 			sessionAgentLease,
+			localForce: resolvedConfig.local.force,
 			restoreCursorSdkOutputFilter,
+			lifecycle: buildLocalCursorProviderTurnLifecycle(sessionAgentLease, sessionAgentScopeKey),
 			runtime: liveRun
 				? { kind: "live", liveRun, turnCoordinator }
 				: { kind: "direct", turnCoordinator },
@@ -224,6 +423,23 @@ export async function prepareCursorProviderTurn(
 	}
 }
 
+/** Resolves the runtime target from the caller-supplied snapshot and dispatches to the owning branch. */
+export async function prepareCursorProviderTurn(
+	prepareParams: PrepareCursorProviderTurnParams,
+): Promise<CursorProviderTurnPrepareResult> {
+	const { params, resolvedConfig } = prepareParams;
+	const { model, options } = params;
+
+	const agentMode = getCursorProviderAgentModeOrThrow();
+	const fastEnabled = resolvedConfig.runtime.value === "cloud" ? undefined : getEffectiveFastForModelId(model.id);
+	const selection = buildCursorModelSelection(model.id, options?.reasoning ?? "off", fastEnabled);
+	const context: PrepareCursorProviderTurnContext = { ...prepareParams, agentMode, selection, fastEnabled };
+
+	return resolvedConfig.runtime.value === "cloud"
+		? prepareCursorCloudProviderTurn(context)
+		: prepareCursorLocalProviderTurn(context);
+}
+
 export function requireCursorApiKey(options: SimpleStreamOptions | undefined): string {
 	const apiKey = resolveCursorApiKey(options?.apiKey);
 	if (!apiKey) throw new Error(MISSING_CURSOR_API_KEY_MESSAGE);

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

@@ -9,16 +9,31 @@ import {
 	emitCursorLiveTurn,
 } from "./cursor-provider-turn-emit.js";
 import { CursorRunFinalizer, type CursorLiveRunCompletion } from "./cursor-provider-run-finalizer.js";
-import { prepareCursorProviderTurn, requireCursorApiKey } from "./cursor-provider-turn-prepare.js";
+import {
+	prepareCursorProviderTurn,
+	requireCursorApiKey,
+	resolveCursorProviderTurnConfig,
+} from "./cursor-provider-turn-prepare.js";
 import { sendCursorProviderTurn } from "./cursor-provider-turn-send.js";
 import type {
 	CursorProviderTurnPrepareResult,
 	CursorProviderTurnRunnerParams,
 	CursorProviderTurnSendResult,
+	LiveCursorProviderTurnRuntime,
+	LocalCursorProviderTurnPrepareResult,
 } from "./cursor-provider-turn-types.js";
 
 export type { CursorProviderTurnRunnerParams } from "./cursor-provider-turn-types.js";
 
+type LocalLivePreparedTurn = LocalCursorProviderTurnPrepareResult & { runtime: LiveCursorProviderTurnRuntime };
+
+function requireLocalLivePreparedTurn(prepared: CursorProviderTurnPrepareResult): LocalLivePreparedTurn {
+	if (prepared.runtimeTarget !== "local" || prepared.runtime.kind !== "live") {
+		throw new Error("Cursor live run requires a local live prepared turn");
+	}
+	return prepared as LocalLivePreparedTurn;
+}
+
 export class CursorProviderTurnRunner {
 	private sdkEventDebug: CursorSdkEventDebugSink | undefined;
 	private resolvedApiKey: string | undefined;
@@ -55,11 +70,16 @@ export class CursorProviderTurnRunner {
 			});
 			sdkEventDebugRef.current = this.sdkEventDebug;
 			this.sdkEventDebug?.recordContextSnapshot(context);
-			if (
-				(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
-				"stream_ended"
-			) {
-				return;
+			// Resolved once here, before any drain await, so the drain decision and the
+			// prepare dispatch below always act on the same config snapshot.
+			const resolvedConfig = resolveCursorProviderTurnConfig(cwd);
+			if (resolvedConfig.runtime.value === "local") {
+				if (
+					(await drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, options?.signal, this.sdkEventDebug)) ===
+					"stream_ended"
+				) {
+					return;
+				}
 			}
 			this.throwIfAborted();
 
@@ -70,6 +90,7 @@ export class CursorProviderTurnRunner {
 				resolvedApiKey: this.resolvedApiKey,
 				sdkEventDebug: this.sdkEventDebug,
 				throwIfAborted: () => this.throwIfAborted(),
+				resolvedConfig,
 			});
 
 			sendResult = await sendCursorProviderTurn({
@@ -78,21 +99,23 @@ export class CursorProviderTurnRunner {
 				sdkEventDebug: this.sdkEventDebug,
 				sdkProcessErrorGuard,
 				throwIfAborted: () => this.throwIfAborted(),
+				resolvedApiKey: this.resolvedApiKey,
 			});
 			const { send } = sendResult;
 
 			if (prepared.runtime.kind === "live") {
+				const livePrepared = requireLocalLivePreparedTurn(prepared);
 				liveCompletion = runFinalizer.startLiveRunCompletion({
 					send,
-					prepared,
+					prepared: livePrepared,
 					modelId: model.id,
-					discardIncompleteTools: (outcome) => discardIncompleteToolsFromPrepared(prepared, outcome),
+					discardIncompleteTools: (outcome) => discardIncompleteToolsFromPrepared(livePrepared, outcome),
 				});
 				await emitCursorLiveTurn({
 					params: this.params,
-					prepared,
+					prepared: livePrepared,
 					sdkEventDebug: this.sdkEventDebug,
-					discardIncompleteTools: (outcome) => discardIncompleteToolsFromPrepared(prepared, outcome),
+					discardIncompleteTools: (outcome) => discardIncompleteToolsFromPrepared(livePrepared, outcome),
 				});
 				return;
 			}
@@ -110,9 +133,14 @@ export class CursorProviderTurnRunner {
 				sdkEventDebug: this.sdkEventDebug,
 				contextWindowAgentId: prepared.contextWindowAgentId,
 			});
-			prepared.sessionAgentLease.trackRunCompletion(outcomePromise);
-			const outcome = await outcomePromise;
-			await runFinalizer.applyTerminalEvent({ kind: "direct", prepared, outcome });
+			prepared.lifecycle.trackRunCompletion(outcomePromise);
+			const finalized = await outcomePromise;
+			await runFinalizer.applyTerminalEvent({
+				kind: "direct",
+				prepared,
+				outcome: finalized.outcome,
+				displayOnlyTraceBlock: finalized.displayOnlyTraceBlock,
+			});
 		} catch (error) {
 			await runFinalizer.applyTerminalEvent({ kind: "error", prepared, error });
 		} finally {

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

@@ -1,7 +1,12 @@
 import type { SendOptions } from "@cursor/sdk";
 import { countCursorAgentMessages } from "./cursor-agent-message-web-tools.js";
+import {
+	createCursorCloudLifecyclePersistenceError,
+	recordCursorCloudLifecycleSafely,
+} from "./cursor-cloud-lifecycle.js";
 import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
 import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { consumeCursorLocalForceOverride } from "./cursor-runtime-state.js";
 import type { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 import type {
 	CursorProviderTurnRunnerParams,
@@ -16,10 +21,37 @@ export interface SendCursorProviderTurnParams {
 	sdkEventDebug: CursorSdkEventDebugSink | undefined;
 	sdkProcessErrorGuard: ReturnType<typeof installCursorSdkProcessErrorGuard>;
 	throwIfAborted: () => void;
+	resolvedApiKey?: string;
+}
+
+const CLOUD_LEDGER_CANCEL_TIMEOUT_MS = 5000;
+
+async function requestBoundedCloudRunCancellation(run: Awaited<ReturnType<CursorProviderTurnPrepareResult["agent"]["send"]>>): Promise<boolean> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<false>((resolve) => {
+		timer = setTimeout(() => resolve(false), CLOUD_LEDGER_CANCEL_TIMEOUT_MS);
+		timer.unref?.();
+	});
+	try {
+		return await Promise.race([
+			Promise.resolve().then(() => run.cancel()).then(() => true, () => false),
+			timeout,
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+function recordDebug(action: () => void): void {
+	try {
+		action();
+	} catch {
+		// Debug capture is optional and must never change provider execution.
+	}
 }
 
 export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnParams): Promise<CursorProviderTurnSendResult> {
-	const { params, prepared, sdkEventDebug, sdkProcessErrorGuard, throwIfAborted } = sendParams;
+	const { params, prepared, sdkEventDebug, sdkProcessErrorGuard, throwIfAborted, resolvedApiKey } = sendParams;
 	const { options } = params;
 	const { agent, cwd, payload, meta, runtime } = prepared;
 	const { turnCoordinator, liveRun } = runtime;
@@ -42,13 +74,15 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 		abortRegistration?.signal.addEventListener("abort", abortListener, { once: true });
 		throwIfAborted();
 		let cursorAgentMessageOffset: number | undefined;
-		try {
-			cursorAgentMessageOffset = await countCursorAgentMessages(agent.agentId, cwd);
-		} catch (error) {
-			sdkEventDebug?.recordError("cursor_agent_message_count", error);
+		if (prepared.runtimeTarget === "local") {
+			try {
+				cursorAgentMessageOffset = await countCursorAgentMessages(agent.agentId, cwd);
+			} catch (error) {
+				recordDebug(() => sdkEventDebug?.recordError("cursor_agent_message_count", error));
+			}
 		}
 		throwIfAborted();
-		sdkEventDebug?.recordSendMeta({
+		recordDebug(() => sdkEventDebug?.recordSendMeta({
 			mode: meta.sendPlan.mode,
 			reason: meta.sendPlan.reason,
 			resetAgent: meta.sendPlan.resetAgent,
@@ -60,35 +94,44 @@ export async function sendCursorProviderTurn(sendParams: SendCursorProviderTurnP
 			nativeReplayId: meta.nativeReplayId,
 			promptInputTokens: meta.promptInputTokens,
 			agentMode: meta.agentMode,
-		});
-		sdkEventDebug?.recordSendPayload(payload);
-		sdkEventDebug?.recordProviderEvent("agent_send_start", payload);
+		}));
+		recordDebug(() => sdkEventDebug?.recordSendPayload(payload));
+		recordDebug(() => sdkEventDebug?.recordProviderEvent("agent_send_start", payload));
 		const sendOptions: SendOptions = {
 			mode: meta.agentMode,
+			model: meta.modelSelection,
 			onDelta: (args) => {
-				sdkEventDebug?.recordOnDelta(args.update);
+				recordDebug(() => sdkEventDebug?.recordOnDelta(args.update));
 				turnCoordinator.handleDelta(args.update);
 			},
 			onStep: (args) => {
-				sdkEventDebug?.recordOnStep(args.step);
+				recordDebug(() => sdkEventDebug?.recordOnStep(args.step));
 				turnCoordinator.handleStep(args.step);
 			},
 		};
+		throwIfAborted();
+		if (prepared.runtimeTarget === "local" && consumeCursorLocalForceOverride(prepared.localForce)) {
+			sendOptions.local = { force: true };
+		}
 		const run = await agent.send(payload, sendOptions);
 		sdkRun = run;
-		sdkEventDebug?.recordRunMeta({
+		if (prepared.runtimeTarget === "cloud" && !recordCursorCloudLifecycleSafely({ agentId: run.agentId, runId: run.id }, resolvedApiKey)) {
+			const cancellationConfirmed = await requestBoundedCloudRunCancellation(run);
+			throw createCursorCloudLifecyclePersistenceError(run.agentId, "run", cancellationConfirmed, resolvedApiKey);
+		}
+		recordDebug(() => sdkEventDebug?.recordRunMeta({
 			runId: run.id,
 			requestId: run.requestId,
 			agentId: run.agentId,
 			status: run.status,
-		});
-		sdkEventDebug?.attachRunStream(run);
-		sdkEventDebug?.recordProviderEvent("agent_send_returned", {
+		}));
+		recordDebug(() => sdkEventDebug?.attachRunStream(run));
+		recordDebug(() => sdkEventDebug?.recordProviderEvent("agent_send_returned", {
 			runId: run.id,
 			requestId: run.requestId,
 			agentId: run.agentId,
 			status: run.status,
-		});
+		}));
 		if (liveRun) cursorLiveRuns.attachSdkRun(liveRun, run);
 		if (options?.signal?.aborted) {
 			sdkProcessErrorGuard.suppressAbortErrors();

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

@@ -6,13 +6,14 @@ import type {
 	Model,
 	SimpleStreamOptions,
 } from "@earendil-works/pi-ai/compat";
-import type { AgentModeOption, SDKAgent, SDKImage } from "@cursor/sdk";
+import type { AgentModeOption, ModelSelection, SDKAgent, SDKImage } from "@cursor/sdk";
 import type { CursorLiveRun } from "./cursor-live-run-coordinator.js";
 import type { SessionCursorAgentLease } from "./cursor-session-agent.js";
 import type { planCursorSessionSend } from "./cursor-session-agent.js";
 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";
 
 export interface CursorProviderTurnRunnerParams {
 	model: Model<Api>;
@@ -37,12 +38,28 @@ export interface CursorProviderTurnSendMeta {
 	bridgeEnabled: boolean;
 	nativeReplayId: string;
 	agentMode: AgentModeOption;
+	modelSelection: ModelSelection;
+	resumeNotice?: string;
 }
 
 interface CursorProviderTurnRuntimeBase {
 	turnCoordinator: CursorSdkTurnCoordinator;
 }
 
+/**
+ * Runtime-agnostic lifecycle operations for a prepared turn.
+ *
+ * Local implementations delegate to the session agent lease; cloud
+ * implementations no-op the local-only operations (commitSend,
+ * trackRunCompletion, abandon) and dispose the cloud agent instead.
+ */
+export interface CursorProviderTurnLifecycle {
+	trackRunCompletion(completion: Promise<unknown>): void;
+	commitSend(context: Context, bootstrapped: boolean): void;
+	abandon(): Promise<void>;
+	dispose(): Promise<void>;
+}
+
 export interface DirectCursorProviderTurnRuntime extends CursorProviderTurnRuntimeBase {
 	kind: "direct";
 	liveRun?: undefined;
@@ -55,25 +72,42 @@ export interface LiveCursorProviderTurnRuntime extends CursorProviderTurnRuntime
 
 export type CursorProviderTurnRuntime = DirectCursorProviderTurnRuntime | LiveCursorProviderTurnRuntime;
 
-/**
- * Single owned model for a prepared provider turn.
- *
- * Send, finalize, and cleanup phases receive this immutable object instead of
- * keeping parallel liveRun/turnCoordinator/resource bags in sync by convention.
- */
-export interface CursorProviderTurnPrepareResult {
+interface CursorProviderTurnPrepareResultBase {
 	agent: SDKAgent;
 	cwd: string;
 	payload: CursorProviderTurnSendPayload;
 	meta: CursorProviderTurnSendMeta;
 	contextWindowAgentId: string;
 	textDeltas: string[];
-	sessionAgentScopeKey: string;
-	sessionAgentLease: SessionCursorAgentLease;
 	restoreCursorSdkOutputFilter: () => void;
+	lifecycle: CursorProviderTurnLifecycle;
+}
+
+export interface LocalCursorProviderTurnPrepareResult extends CursorProviderTurnPrepareResultBase {
+	runtimeTarget: "local";
 	runtime: CursorProviderTurnRuntime;
+	sessionAgentScopeKey: string;
+	sessionAgentLease: SessionCursorAgentLease;
+	localForce: CursorResolvedSetting<boolean>;
 }
 
+export interface CloudCursorProviderTurnPrepareResult extends CursorProviderTurnPrepareResultBase {
+	runtimeTarget: "cloud";
+	runtime: DirectCursorProviderTurnRuntime;
+	sessionAgentScopeKey?: undefined;
+	sessionAgentLease?: undefined;
+}
+
+/**
+ * Single owned model for a prepared provider turn.
+ *
+ * Send, finalize, and cleanup phases receive this immutable object instead of
+ * keeping parallel liveRun/turnCoordinator/resource bags in sync by convention.
+ */
+export type CursorProviderTurnPrepareResult =
+	| LocalCursorProviderTurnPrepareResult
+	| CloudCursorProviderTurnPrepareResult;
+
 export interface CursorProviderTurnSend {
 	run: Awaited<ReturnType<SDKAgent["send"]>>;
 	cursorAgentMessageOffset: number | undefined;