pi-cursor-sdk 0.2.0 → 0.3.7

package/dist/cursor-provider-turn-finalize.js

@@ -0,0 +1,154 @@
+import { loadCursorTranscriptWebToolCallsAfterOffset } from "./cursor-agent-message-web-tools.js";
+import { collectCursorCloudRunReport, formatCursorCloudRunReport, } 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 { isCursorRunFinishedSuccessfully, resolveCursorRunOutcome, } from "./cursor-provider-run-outcome.js";
+import { loadCursorSdk } from "./cursor-sdk-runtime.js";
+import { attachCursorSdkBilledTurnUsage } from "./cursor-sdk-billed-usage.js";
+export async function cacheSdkContextWindow(agentId, modelId, cwd, store) {
+    try {
+        const { createAgentPlatform } = await loadCursorSdk();
+        const platform = await createAgentPlatform(cwd || store
+            ? {
+                ...(cwd ? { workspaceRef: cwd, scopedWorkspaceRef: cwd } : {}),
+                ...(store ? { localStore: store } : {}),
+            }
+            : undefined);
+        const checkpoint = await platform.checkpointStore.loadLatest(agentId);
+        const contextWindow = getCheckpointContextWindow(checkpoint);
+        if (contextWindow)
+            saveCachedContextWindow(modelId, contextWindow);
+    }
+    catch {
+        // Context-window cache failures must not affect response streaming.
+    }
+}
+export function buildCursorRunOutcomeFromWait(params) {
+    const { waitResult, prepared } = params;
+    const { turnCoordinator, liveRun } = prepared.runtime;
+    const { textDeltas } = prepared;
+    return resolveCursorRunOutcome({
+        waitResult,
+        signalAborted: params.signal?.aborted,
+        textDeltas: liveRun?.textDeltas ?? textDeltas,
+        emittedText: liveRun?.emittedText ?? textDeltas.join(""),
+        planTextCandidate: turnCoordinator.planTextCandidate,
+        selectFinalTextOptions: liveRun ? undefined : { allowPartialPrefix: true },
+        runResultFallback: params.runResultFallback,
+        runErrorFallback: params.runErrorFallback,
+        resolvedApiKey: params.resolvedApiKey,
+        optionsApiKey: params.optionsApiKey,
+        runtimeTarget: prepared.runtimeTarget,
+    });
+}
+async function replayCursorTranscriptWebToolCalls(agentId, cwd, messageOffset, turnStore, turnCoordinator, sdkEventDebug) {
+    try {
+        const transcriptToolCalls = await loadCursorTranscriptWebToolCallsAfterOffset({
+            agentId,
+            cwd,
+            offset: messageOffset,
+            store: turnStore,
+        });
+        if (transcriptToolCalls.length === 0)
+            return;
+        sdkEventDebug?.recordCoordinatorEvent("cursor-transcript-web-tools", {
+            agentId,
+            messageOffset,
+            count: transcriptToolCalls.length,
+        });
+        turnCoordinator.handleTranscriptCompletedToolCalls(transcriptToolCalls);
+    }
+    catch (error) {
+        sdkEventDebug?.recordError("cursor_transcript_web_tools", error);
+    }
+}
+function scrubCursorCloudReportingError(error, apiKey) {
+    return new Error(scrubSensitiveText(error instanceof Error ? error.message : String(error), apiKey));
+}
+function recordCursorCloudReportingError(sdkEventDebug, error, apiKey) {
+    try {
+        sdkEventDebug?.recordError("cloud_run_report", scrubCursorCloudReportingError(error, apiKey));
+    }
+    catch {
+        // Debug reporting must never affect provider execution.
+    }
+}
+/** Single wait/finalize path for SDK runs: wait, debug capture, transcript replay, incomplete tools, artifacts, context cache. */
+export async function awaitFinalizeCursorRunOutcome(params) {
+    const apiKey = params.resolvedApiKey ?? params.optionsApiKey;
+    const waitResult = params.waitResult ?? (await params.run.wait());
+    const outcome = buildCursorRunOutcomeFromWait({
+        waitResult,
+        prepared: params.prepared,
+        signal: params.signal,
+        runResultFallback: params.runResultFallback,
+        runErrorFallback: params.runErrorFallback,
+        resolvedApiKey: params.resolvedApiKey,
+        optionsApiKey: params.optionsApiKey,
+    });
+    const billed = await attachCursorSdkBilledTurnUsage({
+        agent: params.prepared.agent,
+        agentId: params.run.agentId,
+        runtime: params.prepared.runtimeTarget,
+        runId: params.run.id,
+    });
+    params.prepared.runtime.billedTurnUsage = billed.turn;
+    if (params.prepared.runtime.liveRun) {
+        params.prepared.runtime.liveRun.billedTurnUsage = billed.turn;
+    }
+    let displayOnlyTraceBlock;
+    if (params.prepared.runtimeTarget === "cloud" && isCursorRunFinishedSuccessfully(outcome)) {
+        let report = { agentId: params.run.agentId, runId: params.run.id, branches: [] };
+        try {
+            report = await collectCursorCloudRunReport({
+                agent: params.prepared.agent,
+                run: params.run,
+                waitResult,
+                apiKey,
+                agentUsage: billed.agentUsage,
+            });
+        }
+        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, params.cursorAgentMessageOffset, params.prepared.sessionAgentLease.store, params.prepared.runtime.turnCoordinator, params.sdkEventDebug);
+    }
+    params.prepared.runtime.turnCoordinator.discardIncompleteStartedToolCalls(outcome.incompleteTools);
+    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, params.prepared.sessionAgentLease.store);
+    }
+    return { outcome, displayOnlyTraceBlock };
+}

package/dist/cursor-provider-turn-lifecycle-emitter.js

@@ -0,0 +1,126 @@
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
+import { CURSOR_TOOL_LIFECYCLE_DEFER_MS, formatCursorToolLifecycleProgressText, isCursorToolLifecycleEligible, } from "./cursor-tool-lifecycle.js";
+import { getNormalizedCursorToolName } from "./cursor-tool-visibility.js";
+import { getStartedToolCallFingerprint } from "./cursor-provider-turn-tool-ledger.js";
+export class CursorToolLifecycleEmitter {
+    liveRun;
+    resolvedApiKey;
+    contentEmitter;
+    debugRecorder;
+    hasStartedToolCall;
+    isBridgeMcpToolCall;
+    emittedLifecycleCallIds = new Set();
+    lifecycleTimers = new Map();
+    activeLifecycleFingerprintOwners = new Map();
+    lifecycleFingerprintByCallId = new Map();
+    activeLifecycleProgressTextOwners = new Map();
+    lifecycleProgressTextByCallId = new Map();
+    constructor(options) {
+        this.liveRun = options.liveRun;
+        this.resolvedApiKey = options.resolvedApiKey;
+        this.contentEmitter = options.contentEmitter;
+        this.debugRecorder = options.debugRecorder;
+        this.hasStartedToolCall = options.hasStartedToolCall;
+        this.isBridgeMcpToolCall = options.isBridgeMcpToolCall;
+    }
+    maybeSchedule(callId, toolCall) {
+        if (typeof callId !== "string" || this.emittedLifecycleCallIds.has(callId))
+            return;
+        if (this.isBridgeMcpToolCall(toolCall))
+            return;
+        if (!isCursorToolLifecycleEligible(toolCall))
+            return;
+        const progressText = formatCursorToolLifecycleProgressText(toolCall, this.resolvedApiKey);
+        if (!progressText)
+            return;
+        const fingerprint = getStartedToolCallFingerprint(toolCall);
+        const existingOwner = this.activeLifecycleFingerprintOwners.get(fingerprint);
+        if (existingOwner && existingOwner !== callId) {
+            this.debugRecorder?.recordCoordinatorEvent("tool_lifecycle_skip", {
+                callId,
+                ownerCallId: existingOwner,
+                toolName: getNormalizedCursorToolName(toolCall),
+                reason: "duplicate-active-fingerprint",
+            });
+            return;
+        }
+        this.cancel(callId);
+        this.activeLifecycleFingerprintOwners.set(fingerprint, callId);
+        this.lifecycleFingerprintByCallId.set(callId, fingerprint);
+        if (!this.activeLifecycleProgressTextOwners.has(progressText)) {
+            this.activeLifecycleProgressTextOwners.set(progressText, callId);
+        }
+        this.lifecycleProgressTextByCallId.set(callId, progressText);
+        const timer = setTimeout(() => {
+            this.lifecycleTimers.delete(callId);
+            if (!this.hasStartedToolCall(callId)) {
+                this.clearLifecycleIdentity(callId);
+                return;
+            }
+            if (this.emittedLifecycleCallIds.has(callId))
+                return;
+            const progressOwner = this.activeLifecycleProgressTextOwners.get(progressText);
+            if (progressOwner && progressOwner !== callId && this.hasStartedToolCall(progressOwner)) {
+                this.debugRecorder?.recordCoordinatorEvent("tool_lifecycle_skip", {
+                    callId,
+                    ownerCallId: progressOwner,
+                    toolName: getNormalizedCursorToolName(toolCall),
+                    reason: "duplicate-active-progress-text",
+                });
+                return;
+            }
+            this.activeLifecycleProgressTextOwners.set(progressText, callId);
+            this.emit(callId, toolCall, progressText);
+        }, CURSOR_TOOL_LIFECYCLE_DEFER_MS);
+        timer.unref?.();
+        this.lifecycleTimers.set(callId, timer);
+    }
+    cancel(callId) {
+        const timer = this.lifecycleTimers.get(callId);
+        if (timer) {
+            clearTimeout(timer);
+            this.lifecycleTimers.delete(callId);
+        }
+        this.clearLifecycleIdentity(callId);
+    }
+    clear() {
+        this.emittedLifecycleCallIds.clear();
+        for (const timer of this.lifecycleTimers.values())
+            clearTimeout(timer);
+        this.lifecycleTimers.clear();
+        this.activeLifecycleFingerprintOwners.clear();
+        this.lifecycleFingerprintByCallId.clear();
+        this.activeLifecycleProgressTextOwners.clear();
+        this.lifecycleProgressTextByCallId.clear();
+    }
+    clearLifecycleIdentity(callId) {
+        const fingerprint = this.lifecycleFingerprintByCallId.get(callId);
+        if (fingerprint && this.activeLifecycleFingerprintOwners.get(fingerprint) === callId) {
+            this.activeLifecycleFingerprintOwners.delete(fingerprint);
+        }
+        this.lifecycleFingerprintByCallId.delete(callId);
+        const progressText = this.lifecycleProgressTextByCallId.get(callId);
+        if (progressText && this.activeLifecycleProgressTextOwners.get(progressText) === callId) {
+            this.activeLifecycleProgressTextOwners.delete(progressText);
+        }
+        this.lifecycleProgressTextByCallId.delete(callId);
+    }
+    emit(callId, toolCall, progressText) {
+        this.emittedLifecycleCallIds.add(callId);
+        this.debugRecorder?.recordCoordinatorEvent("tool_lifecycle", {
+            callId,
+            toolName: getNormalizedCursorToolName(toolCall),
+            progressText,
+            liveRun: this.liveRun !== undefined,
+        });
+        if (this.liveRun) {
+            cursorLiveRuns.queueEvent(this.liveRun, { type: "thinking-delta", text: progressText });
+            return;
+        }
+        this.contentEmitter.appendThinkingDelta(progressText);
+    }
+}
+export function createTurnCoordinatorContentEmitter(stream, partial) {
+    return new CursorPartialContentEmitter(stream, partial, undefined, false);
+}

package/dist/cursor-provider-turn-prepare.js

@@ -0,0 +1,379 @@
+import { getCursorConversationMessages, resolveCursorPiContext } from "./cursor-pi-context.js";
+import { configureCursorSdkHttp1 } from "./cursor-http1.js";
+import { installCursorMcpToolTimeoutOverride } from "./cursor-mcp-timeout-override.js";
+import { ensureCursorRipgrepPath } from "./cursor-ripgrep-path.js";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./cursor-sdk-output-filter.js";
+import { acquireSessionCursorAgent, buildCursorSessionSendPrompt, planCursorSessionSend, resetSessionCursorAgent, } from "./cursor-session-agent.js";
+import { buildCursorPrompt, estimateCursorPromptTokens } from "./context.js";
+import { getCursorPromptOptions } from "./cursor-usage-accounting.js";
+import { getActiveContextToolNames } from "./cursor-context-tools.js";
+import { abandonSessionCursorAgent, createCursorNativeReplayId, cursorLiveRuns, getActiveCursorLiveRunForCurrentScope, getPendingCursorLiveRun, } from "./cursor-provider-live-run-drain.js";
+import { getCursorProviderAgentModeOrThrow, getEffectiveFastForModelId, } from "./cursor-state.js";
+import { resolveEffectiveCursorConfig } from "./cursor-runtime-state.js";
+import { buildCursorModelSelection } from "./model-discovery.js";
+import { getEffectiveCursorSettingSources } from "./cursor-setting-sources.js";
+import { formatCursorCloudPreflightError, buildCursorCloudAgentOptions, preflightCursorCloudRuntime, } from "./cursor-cloud-options.js";
+import { inspectCursorCloudLocalState } from "./cursor-cloud-local-state.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";
+function buildCursorCloudPromptContext(context, handoff) {
+    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);
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === "user")
+            return { ...current, messages: [message] };
+    }
+    return { ...current, messages: messages.slice(-1) };
+}
+const CLOUD_SEND_PLAN = { mode: "bootstrap", resetAgent: false, reason: "initial" };
+export function resolveCursorProviderTurnConfig(cwd) {
+    return resolveEffectiveCursorConfig({ cwd, projectTrusted: getCursorSessionProjectTrusted() });
+}
+function buildCloudCursorProviderTurnLifecycle(agent) {
+    return {
+        trackRunCompletion: () => { },
+        commitSend: () => { },
+        abandon: async () => { },
+        dispose: async () => {
+            await agent[Symbol.asyncDispose]?.();
+        },
+    };
+}
+function buildLocalCursorProviderTurnLifecycle(lease, scopeKey) {
+    return {
+        trackRunCompletion: (completion) => lease.trackRunCompletion(completion),
+        commitSend: (context, bootstrapped) => lease.commitSend(context, bootstrapped),
+        abandon: () => abandonSessionCursorAgent(scopeKey),
+        dispose: async () => { },
+    };
+}
+async function prepareCursorCloudProviderTurn(prepareParams) {
+    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+    const { model, context, options } = params;
+    let restoreCursorSdkOutputFilter;
+    let cloudAgentForCleanup;
+    let completed = false;
+    try {
+        const preflight = preflightCursorCloudRuntime({
+            resolvedConfig,
+            localState: resolvedConfig.cloud.allowLocalState.value
+                ? { insideGitRepo: false }
+                : inspectCursorCloudLocalState(cwd, {
+                    repo: resolvedConfig.cloud.repo.value,
+                    branch: resolvedConfig.cloud.branch.value,
+                }),
+            hasPriorContext: getCursorConversationMessages(context).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 = [];
+        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) {
+    const { params, cwd, resolvedApiKey, sdkEventDebug, throwIfAborted, resolvedConfig, agentMode, selection, fastEnabled } = prepareParams;
+    const { model, context, options } = params;
+    let restoreCursorSdkOutputFilter;
+    let sessionAgentScopeKey;
+    let liveRun;
+    let completed = false;
+    try {
+        ensureCursorRipgrepPath();
+        const localSafety = {
+            autoReview: resolvedConfig.local.autoReview.value,
+            sandboxEnabled: resolvedConfig.local.sandboxEnabled.value,
+        };
+        const sdk = await loadCursorSdk();
+        const { Agent } = sdk;
+        const useHttp1ForAgent = configureCursorSdkHttp1(sdk, resolvedConfig.local.useHttp1ForAgent);
+        installCursorMcpToolTimeoutOverride();
+        restoreCursorSdkOutputFilter = installCursorSdkOutputFilter();
+        const settingSources = getEffectiveCursorSettingSources();
+        const queuedBridgeRequestsBeforeLiveRun = [];
+        let liveRunForBridgeQueue;
+        const sessionAgentAcquireParams = {
+            apiKey: resolvedApiKey,
+            agentMode,
+            cwd,
+            modelSelection: selection,
+            settingSources,
+            localSafety,
+            localResume: resolvedConfig.local.resume.value,
+            useHttp1ForAgent,
+            debugRecorder: sdkEventDebug,
+            onBridgeToolRequest: (request) => {
+                if (liveRunForBridgeQueue && !liveRunForBridgeQueue.disposed) {
+                    cursorLiveRuns.queueEvent(liveRunForBridgeQueue, { type: "bridge-tool", request });
+                }
+                else {
+                    queuedBridgeRequestsBeforeLiveRun.push(request);
+                }
+            },
+            createAgent: (createOptions) => suppressCursorSdkOutput(() => Agent.create(createOptions)),
+        };
+        let sessionAgentLease = await acquireSessionCursorAgent(sessionAgentAcquireParams);
+        sessionAgentScopeKey = sessionAgentLease.scopeKey;
+        throwIfAborted();
+        let bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
+        let includePiBridgeGuidance = bridgeToolNames.size > 0;
+        const buildPromptOptions = (plan) => {
+            const promptOptions = {
+                ...getCursorPromptOptions(model),
+                agentMode,
+                includePiBridgeGuidance,
+                includePiAskQuestionGuidance: bridgeToolNames.has("pi__cursor_ask_question"),
+            };
+            if (plan.mode !== "bootstrap" || !resolveCursorToolManifestEnabled()) {
+                return promptOptions;
+            }
+            return {
+                ...promptOptions,
+                toolManifest: buildCursorToolManifestText({
+                    bridgeSnapshot: sessionAgentLease.bridgeRun?.snapshot,
+                    piBridgeEnabled: resolveCursorPiToolBridgeEnabled(),
+                    includePiBridgeGuidance,
+                }),
+            };
+        };
+        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, forceCreate: true });
+            sessionAgentScopeKey = sessionAgentLease.scopeKey;
+            bridgeToolNames = new Set(sessionAgentLease.bridgeRun?.snapshot.tools.map((tool) => tool.mcpToolName) ?? []);
+            includePiBridgeGuidance = bridgeToolNames.size > 0;
+            sendPlan = planCursorSessionSend(sessionAgentLease.sendState, context);
+            promptOptions = buildPromptOptions(sendPlan);
+            prompt = buildCursorSessionSendPrompt(context, promptOptions, sendPlan);
+        }
+        const bootstrap = sendPlan.mode === "bootstrap";
+        const agent = sessionAgentLease.agent;
+        const bridgeRun = sessionAgentLease.bridgeRun;
+        const sendPayload = {
+            text: prompt.text,
+            images: prompt.images.length > 0 ? prompt.images : undefined,
+        };
+        const sessionBridgeRun = bridgeRun;
+        const promptInputTokens = estimateCursorPromptTokens(prompt, promptOptions);
+        const useNativeToolReplay = isCursorNativeToolDisplayRuntimeEnabled();
+        const activeToolNames = getActiveContextToolNames(context);
+        sdkEventDebug?.recordProviderMeta({
+            model: {
+                id: model.id,
+                provider: model.provider,
+                api: model.api,
+                reasoning: options?.reasoning ?? "off",
+                fastEnabled,
+                selection,
+            },
+            settingSources: settingSources ?? null,
+            sendState: sessionAgentLease.sendState,
+            sendPlan,
+            promptOptions,
+            toolManifestEnabled: resolveCursorToolManifestEnabled(),
+            agentMode,
+            localForce: resolvedConfig.local.force.value,
+            localResume: resolvedConfig.local.resume.value,
+            resumedAgent: sessionAgentLease.resumed,
+            activeToolNames: activeToolNames ? [...activeToolNames] : [],
+            sessionAgentScopeKey,
+            bridgeRunId: bridgeRun?.id,
+        });
+        const nativeReplayId = createCursorNativeReplayId();
+        const textDeltas = [];
+        const useLiveRun = useNativeToolReplay || bridgeRun !== undefined;
+        liveRun = useLiveRun
+            ? cursorLiveRuns.start({
+                id: useNativeToolReplay ? nativeReplayId : bridgeRun?.id ?? nativeReplayId,
+                agent,
+                bridgeRun,
+                sessionBridgeRun,
+                sessionAgentScopeKey,
+                promptInputTokens,
+                textDeltas,
+                debugRecorder: sdkEventDebug,
+            })
+            : undefined;
+        if (liveRun) {
+            liveRunForBridgeQueue = liveRun;
+            for (const request of queuedBridgeRequestsBeforeLiveRun.splice(0)) {
+                cursorLiveRuns.queueEvent(liveRun, { type: "bridge-tool", request });
+            }
+        }
+        const turnCoordinator = new CursorSdkTurnCoordinator({
+            stream: params.stream,
+            partial: params.partial,
+            cwd,
+            resolvedApiKey,
+            liveRun,
+            useNativeToolReplay,
+            activeToolNames,
+            nativeReplayId,
+            textDeltas,
+            debugRecorder: sdkEventDebug,
+        });
+        completed = true;
+        return {
+            runtimeTarget: "local",
+            agent,
+            cwd,
+            payload: sendPayload,
+            meta: {
+                sendPlan,
+                prompt,
+                bootstrap,
+                promptInputTokens,
+                useNativeToolReplay,
+                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 },
+        };
+    }
+    finally {
+        if (!completed) {
+            if (liveRun && !liveRun.disposed) {
+                await cursorLiveRuns
+                    .release(liveRun)
+                    .catch(() => abandonSessionCursorAgent(sessionAgentScopeKey).catch(() => { }));
+            }
+            else {
+                await abandonSessionCursorAgent(sessionAgentScopeKey).catch(() => { });
+            }
+            restoreCursorSdkOutputFilter?.();
+        }
+    }
+}
+/** Resolves the runtime target from the caller-supplied snapshot and dispatches to the owning branch. */
+export async function prepareCursorProviderTurn(prepareParams) {
+    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 = { ...prepareParams, agentMode, selection, fastEnabled };
+    return resolvedConfig.runtime.value === "cloud"
+        ? prepareCursorCloudProviderTurn(context)
+        : prepareCursorLocalProviderTurn(context);
+}
+export function requireCursorApiKey(options) {
+    const apiKey = resolveCursorApiKey(options?.apiKey);
+    if (!apiKey)
+        throw new Error(MISSING_CURSOR_API_KEY_MESSAGE);
+    return apiKey;
+}