pi-cursor-sdk 0.2.0 → 0.3.7

package/dist/cursor-provider-live-run-drain.js

@@ -0,0 +1,420 @@
+import { scheduler } from "node:timers/promises";
+import { CursorLiveRunAbortError, createCursorLiveRunCoordinator, hasTrailingUserMessagesAfterToolResults, } from "./cursor-live-run-coordinator.js";
+import { deleteCursorNativeToolDisplay, recordCursorNativeToolDisplay, } from "./cursor-native-tool-display-state.js";
+import { resetSessionCursorAgent } from "./cursor-session-agent.js";
+import { applyCursorUsage } from "./cursor-usage-accounting.js";
+import { CURSOR_TEXT_MESSAGE_SEPARATOR, CursorPartialContentEmitter } from "./cursor-partial-content-emitter.js";
+import { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
+import { trimCurrentTurnAlreadyEmittedCursorText } from "./cursor-run-final-text.js";
+import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause } from "./cursor-provider-errors.js";
+import { formatInactiveCursorReplayTrace } from "./cursor-native-replay-trace.js";
+import { partitionNativeToolsByActiveContext } from "./cursor-native-replay-routing.js";
+export const DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS = 5 * 60 * 1000;
+const CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN = /^(cursor-replay-\d+-\d+)-tool-\d+$/;
+let cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+let cursorNativeReplayCounter = 0;
+export async function abandonSessionCursorAgent(scopeKey) {
+    if (!scopeKey)
+        return;
+    await resetSessionCursorAgent(scopeKey);
+}
+export const cursorLiveRuns = createCursorLiveRunCoordinator({
+    getIdleDisposeMs: () => cursorNativeReplayIdleDisposeMs,
+    deleteNativeToolDisplay: deleteCursorNativeToolDisplay,
+    abandonSessionAgent: (scopeKey) => abandonSessionCursorAgent(scopeKey),
+});
+export function createCursorNativeReplayId() {
+    cursorNativeReplayCounter += 1;
+    return `cursor-replay-${Date.now()}-${cursorNativeReplayCounter}`;
+}
+function getCursorNativeReplayIdFromToolCallId(toolCallId) {
+    return CURSOR_NATIVE_REPLAY_TOOL_ID_PATTERN.exec(toolCallId)?.[1];
+}
+export function getPendingCursorLiveRun(context) {
+    return cursorLiveRuns.getPendingFromContext(context, getCursorNativeReplayIdFromToolCallId);
+}
+export function getActiveCursorLiveRunForCurrentScope() {
+    return cursorLiveRuns.getActiveForScope();
+}
+function splitTextIntoReplayDeltas(text) {
+    const deltas = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= 96) {
+            deltas.push(remaining);
+            break;
+        }
+        const boundary = Math.max(48, remaining.lastIndexOf(" ", 96));
+        deltas.push(remaining.slice(0, boundary));
+        remaining = remaining.slice(boundary);
+    }
+    return deltas;
+}
+async function emitTextDeltas(emitter, deltas) {
+    for (const delta of deltas) {
+        emitter.appendTextDelta(delta);
+        await Promise.resolve();
+    }
+    return emitter.closeText();
+}
+export async function settleCursorLiveToolBatch(run) {
+    const eventType = cursorLiveRuns.peekEvent(run)?.type;
+    if (eventType !== "tool" && eventType !== "bridge-tool")
+        return;
+    await scheduler.wait(75);
+}
+async function waitForCursorLiveSdkTurnEnded(run, signal) {
+    const deadline = Date.now() + 125;
+    while (!cursorLiveRuns.hasSdkTurnEnded(run) && !run.done && !run.disposed && !run.cancelled && !run.errorMessage) {
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            return false;
+        await scheduler.wait(Math.min(25, remainingMs));
+        if (signal?.aborted)
+            throw new CursorLiveRunAbortError();
+    }
+    return cursorLiveRuns.hasSdkTurnEnded(run);
+}
+export function flushPendingCursorLiveRunTraceEventsToStream(stream, partial, run, options) {
+    if (run.disposed)
+        return;
+    const turn = {
+        emitter: options?.emitter ?? new CursorPartialContentEmitter(stream, partial, -1, true),
+        emittedText: "",
+    };
+    while (true) {
+        const event = cursorLiveRuns.peekEvent(run);
+        if (!event || event.type === "tool" || event.type === "bridge-tool")
+            break;
+        cursorLiveRuns.shiftEvent(run);
+        emitCursorLiveQueuedEvent(turn, event, run);
+    }
+    if (options?.includeTracesBehindQueuedTools && run.pendingEvents.length > 0) {
+        const preserved = [];
+        for (const event of run.pendingEvents) {
+            if (event.type === "tool" || event.type === "bridge-tool") {
+                preserved.push(event);
+                continue;
+            }
+            emitCursorLiveQueuedEvent(turn, event, run);
+        }
+        run.pendingEvents = preserved;
+    }
+    turn.emitter.closeAll();
+}
+function emitCursorLiveQueuedEvent(turn, event, run) {
+    if (event.type === "thinking-delta") {
+        turn.emitter.appendThinkingDelta(event.text);
+    }
+    else if (event.type === "thinking-completed") {
+        turn.emitter.closeThinking();
+    }
+    else if (event.type === "text-completed") {
+        turn.emitter.completeTextMessage();
+        // Logical separators also keep suffix/prefix dedup aware of SDK messages,
+        // including boundaries queued across Pi tool-use turns.
+        if (turn.emittedText)
+            turn.emittedText += CURSOR_TEXT_MESSAGE_SEPARATOR;
+        if (run?.emittedText)
+            run.emittedText += CURSOR_TEXT_MESSAGE_SEPARATOR;
+    }
+    else if (event.type === "text-delta") {
+        turn.emittedText += event.text;
+        if (run)
+            run.emittedText += event.text;
+        turn.emitter.appendTextDelta(event.text);
+    }
+}
+function emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, tools, debugRecorder) {
+    const shouldTerminate = run.done && !run.finalText?.trim() && !cursorLiveRuns.peekEvent(run);
+    for (const tool of tools) {
+        const contentIndex = partial.content.length;
+        partial.content.push({
+            type: "toolCall",
+            id: tool.id,
+            name: tool.toolName,
+            arguments: tool.args,
+        });
+        stream.push({ type: "toolcall_start", contentIndex, partial });
+        stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(tool.args), partial });
+        const block = partial.content[contentIndex];
+        if (block.type === "toolCall")
+            stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
+        if (recordCursorNativeToolDisplay({ ...tool, terminate: shouldTerminate })) {
+            run.recordedToolDisplayIds.push(tool.id);
+            debugRecorder?.recordDrainEvent("native_tool_display_recorded", {
+                toolId: tool.id,
+                toolName: tool.toolName,
+                terminate: shouldTerminate,
+            });
+        }
+    }
+    applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+        runtime: "local",
+        turn: cursorLiveRuns.takeSdkTurnUsage(run),
+    });
+    partial.stopReason = "toolUse";
+    stream.push({ type: "done", reason: "toolUse", message: partial });
+    cursorLiveRuns.requestIdleDispose(run);
+}
+function emitInactiveCursorReplayTrace(turn, tools, debugRecorder) {
+    if (tools.length === 0)
+        return;
+    for (const tool of tools) {
+        const traceText = formatInactiveCursorReplayTrace(tool);
+        debugRecorder?.recordDrainEvent("inactive_replay_trace", {
+            toolId: tool.id,
+            toolName: tool.toolName,
+            traceText,
+        });
+        turn.emitter.appendThinkingBlock(traceText);
+    }
+}
+function emitCursorBridgeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, requests) {
+    for (const request of requests) {
+        const contentIndex = partial.content.length;
+        partial.content.push({
+            type: "toolCall",
+            id: request.piToolCallId,
+            name: request.piToolName,
+            arguments: request.args,
+        });
+        stream.push({ type: "toolcall_start", contentIndex, partial });
+        stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(request.args), partial });
+        const block = partial.content[contentIndex];
+        if (block.type === "toolCall")
+            stream.push({ type: "toolcall_end", contentIndex, toolCall: block, partial });
+    }
+    applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+        runtime: "local",
+        turn: cursorLiveRuns.takeSdkTurnUsage(run),
+    });
+    partial.stopReason = "toolUse";
+    stream.push({ type: "done", reason: "toolUse", message: partial });
+    cursorLiveRuns.requestIdleDispose(run);
+}
+async function emitCursorLiveRunPendingToolUseTurn(turn, stream, partial, model, context, run, toolResultInputTokens, options) {
+    const debugRecorder = options.debugRecorder ?? run.debugRecorder;
+    const eventType = cursorLiveRuns.peekEvent(run)?.type;
+    if (eventType !== "tool" && eventType !== "bridge-tool")
+        return undefined;
+    await settleCursorLiveToolBatch(run);
+    const sdkTurnEnded = await waitForCursorLiveSdkTurnEnded(run, options.signal);
+    if (options.signal?.aborted)
+        throw new CursorLiveRunAbortError();
+    if (eventType === "tool") {
+        const { active, inactive } = partitionNativeToolsByActiveContext(context, cursorLiveRuns.collectNativeToolBatch(run));
+        if (options.mode === "emit")
+            emitInactiveCursorReplayTrace(turn, inactive, debugRecorder);
+        if (active.length === 0) {
+            // Inactive-only batch: trace was emitted above; do not emit toolUse.
+            return "handled";
+        }
+        if (!sdkTurnEnded)
+            cursorLiveRuns.ignoreFutureSdkTurnUsage(run);
+        if (options.mode === "emit")
+            turn.emitter.closeAll();
+        emitCursorNativeToolUseTurn(stream, partial, model, context, run, toolResultInputTokens, active, 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);
+    }
+    return "tool_use";
+}
+export async function drainCursorLiveRunTurn(stream, partial, model, context, run, toolResultInputTokens, options) {
+    const debugRecorder = options.debugRecorder ?? run.debugRecorder;
+    debugRecorder?.recordDrainEvent("turn_start", {
+        mode: options.mode,
+        runId: run.id,
+        pendingEventCount: run.pendingEvents.length,
+        done: run.done,
+    });
+    let outcome;
+    let outcomeDetails = {};
+    const turn = {
+        emitter: options.emitter ?? new CursorPartialContentEmitter(stream, partial, -1, true),
+        emittedText: "",
+    };
+    try {
+        while (true) {
+            if (options.mode === "chain_user_input" && cursorLiveRuns.isReady(run)) {
+                await cursorLiveRuns.release(run);
+                outcome = "chain_user_input";
+                return outcome;
+            }
+            while (cursorLiveRuns.peekEvent(run)) {
+                const toolUse = await emitCursorLiveRunPendingToolUseTurn(turn, stream, partial, model, context, run, toolResultInputTokens, options);
+                if (toolUse === "tool_use") {
+                    outcome = "tool_use";
+                    return outcome;
+                }
+                if (toolUse === "handled")
+                    continue;
+                const event = cursorLiveRuns.shiftEvent(run);
+                if (!event || event.type === "tool" || event.type === "bridge-tool")
+                    continue;
+                if (options.mode === "emit")
+                    emitCursorLiveQueuedEvent(turn, event, run);
+            }
+            if (run.disposed) {
+                partial.stopReason = "aborted";
+                partial.errorMessage = formatCursorSdkAbortMessage(resolveCursorSdkAbortCause({ liveRunDisposed: true }));
+                stream.push({ type: "error", reason: "aborted", error: partial });
+                outcome = "aborted";
+                outcomeDetails = { reason: "disposed" };
+                return outcome;
+            }
+            if (run.cancelled) {
+                partial.stopReason = "aborted";
+                if (run.abortMessage)
+                    partial.errorMessage = run.abortMessage;
+                stream.push({ type: "error", reason: "aborted", error: partial });
+                await cursorLiveRuns.release(run);
+                outcome = "aborted";
+                outcomeDetails = { reason: "cancelled" };
+                return outcome;
+            }
+            if (run.errorMessage) {
+                partial.stopReason = "error";
+                partial.errorMessage = run.errorMessage;
+                stream.push({ type: "error", reason: "error", error: partial });
+                await cursorLiveRuns.release(run);
+                outcome = "error";
+                return outcome;
+            }
+            if (run.done) {
+                if (options.mode === "chain_user_input") {
+                    await cursorLiveRuns.release(run);
+                    outcome = "chain_user_input";
+                    outcomeDetails = { reason: "run_done" };
+                    return outcome;
+                }
+                turn.emitter.closeAll();
+                const finalText = trimCurrentTurnAlreadyEmittedCursorText(run.finalText ?? run.textDeltas.join(""), turn.emittedText, run.emittedText);
+                if (finalText) {
+                    await emitTextDeltas(turn.emitter, splitTextIntoReplayDeltas(finalText));
+                }
+                applyCursorUsage(partial, model, context, cursorLiveRuns.takeTurnInputTokens(run, toolResultInputTokens), {
+                    runtime: "local",
+                    turn: cursorLiveRuns.takeSdkTurnUsage(run),
+                    billed: run.billedTurnUsage,
+                });
+                if (run.resumeNotice) {
+                    emitDisplayOnlyTraceBlock(stream, partial, run.resumeNotice);
+                    run.resumeNotice = undefined;
+                }
+                partial.stopReason = "stop";
+                stream.push({ type: "done", reason: "stop", message: partial });
+                await cursorLiveRuns.release(run);
+                outcome = "stop";
+                outcomeDetails = { finalTextLength: finalText.length };
+                return outcome;
+            }
+            await cursorLiveRuns.waitForProgress(run, options.signal);
+        }
+    }
+    catch (error) {
+        if (!outcome) {
+            if (error instanceof CursorLiveRunAbortError) {
+                outcome = "aborted";
+                outcomeDetails = { reason: "signal_aborted" };
+            }
+            else {
+                outcome = "error";
+                outcomeDetails = {
+                    reason: "drain_error",
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        throw error;
+    }
+    finally {
+        debugRecorder?.recordDrainEvent("turn_end", {
+            outcome: outcome ?? "error",
+            runId: run.id,
+            pendingEventCount: run.pendingEvents.length,
+            done: run.done,
+            ...outcomeDetails,
+        });
+    }
+}
+export async function drainExistingCursorLiveRunBeforeSend(stream, partial, model, context, signal, turnDebugRecorder) {
+    turnDebugRecorder?.recordDrainEvent("pre_send_start", {});
+    while (true) {
+        const run = getPendingCursorLiveRun(context) ?? getActiveCursorLiveRunForCurrentScope();
+        if (!run || run.disposed) {
+            turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome: "continue_send", reason: "no_pending_run" });
+            return "continue_send";
+        }
+        try {
+            const outcome = await cursorLiveRuns.withRunLease(run, signal, async () => {
+                if (run.disposed)
+                    return "continue_send";
+                const consumed = cursorLiveRuns.consumeToolResults(run, context, getCursorNativeReplayIdFromToolCallId);
+                await run.bridgeRun?.resolveToolResults(consumed.toolResults);
+                const shouldChainUserInput = run.chainUserInputAfterCompletion || hasTrailingUserMessagesAfterToolResults(context);
+                if (shouldChainUserInput)
+                    run.chainUserInputAfterCompletion = true;
+                while (!cursorLiveRuns.isReady(run)) {
+                    await cursorLiveRuns.waitForProgress(run, signal);
+                }
+                if (run.disposed)
+                    return "continue_send";
+                const drainOutcome = await drainCursorLiveRunTurn(stream, partial, model, context, run, consumed.toolResultInputTokens, {
+                    mode: shouldChainUserInput ? "chain_user_input" : "emit",
+                    signal,
+                    debugRecorder: turnDebugRecorder,
+                });
+                const mapped = drainOutcome === "chain_user_input" ? "continue_send" : "stream_ended";
+                turnDebugRecorder?.recordDrainEvent("pre_send_iteration", {
+                    runId: run.id,
+                    drainOutcome,
+                    outcome: mapped,
+                    shouldChainUserInput,
+                });
+                return mapped;
+            });
+            if (outcome === "continue_send" && !run.disposed && cursorLiveRuns.getActiveForScope(run.sessionAgentScopeKey) === run) {
+                continue;
+            }
+            turnDebugRecorder?.recordDrainEvent("pre_send_end", { outcome, runId: run.id });
+            return outcome;
+        }
+        catch (error) {
+            turnDebugRecorder?.recordDrainEvent("pre_send_end", {
+                outcome: error instanceof CursorLiveRunAbortError ? "aborted" : "error",
+                runId: run.id,
+                reason: error instanceof CursorLiveRunAbortError ? "signal_aborted" : "drain_error",
+            });
+            if (error instanceof CursorLiveRunAbortError)
+                await cursorLiveRuns.release(run);
+            throw error;
+        }
+    }
+}
+export function setCursorNativeReplayIdleDisposeMs(value) {
+    cursorNativeReplayIdleDisposeMs = value;
+}
+export function resetCursorNativeReplayIdleDisposeMs() {
+    cursorNativeReplayIdleDisposeMs = DEFAULT_CURSOR_NATIVE_REPLAY_IDLE_DISPOSE_MS;
+}
+export async function releaseAllPendingCursorLiveRunsForTests() {
+    while (cursorLiveRuns.count() > 0) {
+        const run = cursorLiveRuns.getActiveForScope();
+        if (!run)
+            break;
+        const before = cursorLiveRuns.count();
+        await cursorLiveRuns.release(run);
+        if (cursorLiveRuns.count() >= before)
+            break;
+    }
+}
+export { hasTrailingUserMessagesAfterToolResults };

package/dist/cursor-provider-overflow.js

@@ -0,0 +1,90 @@
+import { CURSOR_PROVIDER } from "./cursor-model.js";
+/**
+ * Pi recognizes `context_length_exceeded` (its `OVERFLOW_PATTERNS` includes
+ * `/context[_ ]length[_ ]exceeded/i`) as a context-overflow signal and, on
+ * detecting it, drops the failed assistant message, compacts, and retries once.
+ *
+ * The Cursor provider sanitizes SDK failures into auth/network/generic messages
+ * that pi does NOT treat as overflow, so a genuine Cursor context-overflow
+ * failure would otherwise surface as a plain provider error and bypass pi's
+ * auto-compact-retry recovery. This handler rewrites only Cursor context-window
+ * failures into the `context_length_exceeded` form pi recognizes.
+ *
+ * See pi `docs/custom-provider.md` -> "Context Overflow Errors".
+ */
+export const CURSOR_OVERFLOW_MARKER = "context_length_exceeded";
+/**
+ * Context-overflow phrases. These overlap pi's own `OVERFLOW_PATTERNS` so the
+ * false-positive surface matches pi's built-in detection for other providers.
+ *
+ * ponytail: intentionally narrow and textual. We do NOT match bare gRPC
+ * `resource_exhausted` (code 8) or `too many tokens` because pi documents those
+ * can false-match throttling/quota errors and trigger an unwanted compaction.
+ * If a live Cursor probe reveals a distinct overflow phrase, add it here; this
+ * pattern set is the single place to extend without touching the handler.
+ */
+const CURSOR_OVERFLOW_PATTERNS = [
+    /context[_ ]?length/i,
+    /context[_ ]?window/i,
+    /maximum context/i,
+    /prompt is too long/i,
+    /too large for model/i,
+    /exceed(?:s|ed).{0,30}context/i,
+];
+/** Never treat rate-limit/throttle signals as overflow (pi retries those separately). */
+const CURSOR_THROTTLE_PATTERN = /too many requests|rate.?limit|throttl|retry.?after/i;
+/**
+ * Map a finalized Cursor assistant `errorMessage` to pi's overflow form.
+ * Returns `undefined` when the message is not a Cursor context-overflow failure.
+ *
+ * Pure and idempotent so it is safe to call repeatedly and unit-test in isolation.
+ */
+export function normalizeCursorOverflowErrorMessage(errorMessage) {
+    const message = errorMessage?.trim();
+    if (!message)
+        return undefined;
+    // Idempotent: never double-prefix an already-normalized message.
+    if (message.includes(CURSOR_OVERFLOW_MARKER))
+        return undefined;
+    if (CURSOR_THROTTLE_PATTERN.test(message))
+        return undefined;
+    if (CURSOR_OVERFLOW_PATTERNS.some((pattern) => pattern.test(message))) {
+        return `${CURSOR_OVERFLOW_MARKER}: ${message}`;
+    }
+    return undefined;
+}
+/**
+ * Rewrite a finalized assistant message into pi's overflow form when it is a
+ * Cursor context-overflow failure. Returns the replacement message (for the
+ * `message_end` result) or `undefined` to leave it unchanged.
+ *
+ * `isCursorProvider` carries the provider scoping decision out of the handler so
+ * the full logic is unit-testable without a pi event harness.
+ */
+export function rewriteCursorOverflowAssistantMessage(message, isCursorProvider) {
+    if (!isCursorProvider || message.stopReason !== "error")
+        return undefined;
+    const rewritten = normalizeCursorOverflowErrorMessage(message.errorMessage);
+    if (!rewritten)
+        return undefined;
+    return { ...message, errorMessage: rewritten };
+}
+/**
+ * Register a `message_end` handler that rewrites Cursor context-overflow
+ * failures into the `context_length_exceeded` form pi auto-compacts on.
+ *
+ * Guarded exactly as pi's provider docs require: scoped to the Cursor provider,
+ * only for `stopReason === "error"`, never for throttling, and idempotent.
+ */
+export function registerCursorOverflowNormalization(pi) {
+    pi.on("message_end", (event, ctx) => {
+        const message = event.message;
+        if (message.role !== "assistant")
+            return undefined;
+        const isCursorProvider = message.provider === CURSOR_PROVIDER || ctx.model?.provider === CURSOR_PROVIDER;
+        const rewritten = rewriteCursorOverflowAssistantMessage(message, isCursorProvider);
+        if (!rewritten)
+            return undefined;
+        return { message: rewritten };
+    });
+}

package/dist/cursor-provider-run-finalizer.js

@@ -0,0 +1,176 @@
+import { cursorLiveRuns } from "./cursor-provider-live-run-drain.js";
+import { classifyCursorRunEmission, getCursorRunAbortMessage, } from "./cursor-provider-run-outcome.js";
+import { formatCursorSdkAbortMessage, resolveCursorSdkAbortCause, sanitizeCursorProviderError, } from "./cursor-provider-errors.js";
+import { CursorLiveRunAbortError } from "./cursor-live-run-coordinator.js";
+import { buildIncompleteCursorToolRunOutcome, } from "./cursor-incomplete-tool-visibility.js";
+import { awaitFinalizeCursorRunOutcome } from "./cursor-provider-turn-finalize.js";
+import { applyCursorUsage } from "./cursor-usage-accounting.js";
+import { hasUsableText } from "./cursor-record-utils.js";
+import { emitDisplayOnlyTraceBlock } from "./cursor-display-only-trace.js";
+function applyLiveRunOutcome(outcome, prepared, context) {
+    if (prepared.runtime.liveRun.disposed)
+        return;
+    const { liveRun } = prepared.runtime;
+    switch (classifyCursorRunEmission(outcome)) {
+        case "finished":
+            prepared.lifecycle.commitSend(context, prepared.meta.bootstrap);
+            if (prepared.meta.resumeNotice)
+                liveRun.resumeNotice = prepared.meta.resumeNotice;
+            cursorLiveRuns.markFinished(liveRun, outcome.kind === "finished" ? outcome.finalText : "");
+            break;
+        case "cancelled":
+            cursorLiveRuns.markCancelled(liveRun, getCursorRunAbortMessage(outcome));
+            break;
+        case "failed":
+            cursorLiveRuns.markError(liveRun, outcome.kind === "error" ? outcome.errorMessage : "Cursor SDK run failed.");
+            break;
+    }
+}
+export class CursorRunFinalizer {
+    params;
+    terminalApplied = false;
+    constructor(params) {
+        this.params = params;
+    }
+    startLiveRunCompletion(startParams) {
+        const { runnerParams } = this.params;
+        const sdkEventDebug = this.params.sdkEventDebug();
+        const { send, prepared, modelId, discardIncompleteTools } = startParams;
+        const { run, cursorAgentMessageOffset } = send;
+        const { liveRun } = prepared.runtime;
+        const waitCompletion = awaitFinalizeCursorRunOutcome({
+            run,
+            prepared,
+            cursorAgentMessageOffset,
+            modelId,
+            signal: runnerParams.options?.signal,
+            runResultFallback: run.result,
+            runErrorFallback: run.error,
+            resolvedApiKey: this.params.resolvedApiKey(),
+            optionsApiKey: runnerParams.options?.apiKey,
+            sdkEventDebug,
+            cacheContextWindow: true,
+            contextWindowAgentId: liveRun.agent.agentId,
+        })
+            .then(async (finalized) => {
+            applyLiveRunOutcome(finalized.outcome, prepared, runnerParams.context);
+        })
+            .catch((error) => {
+            this.safeCleanup(() => discardIncompleteTools({ status: "error" }));
+            if (!liveRun.disposed) {
+                cursorLiveRuns.markError(liveRun, sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? runnerParams.options?.apiKey, "local"));
+            }
+            this.safeCleanup(() => sdkEventDebug?.recordWaitResult({ status: "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
+        // (and other concurrent acquires) wait for run.wait() instead of hitting AgentBusyError.
+        prepared.lifecycle.trackRunCompletion(waitCompletion);
+        return { waitCompletion, prepared };
+    }
+    async applyTerminalEvent(event) {
+        if (this.terminalApplied)
+            return;
+        if (event.kind === "direct") {
+            await this.applyDirectOutcome(event.prepared, event.outcome, event.displayOnlyTraceBlock);
+            this.terminalApplied = true;
+            return;
+        }
+        await this.applyErrorOutcome(event.prepared, event.error);
+        this.terminalApplied = true;
+    }
+    async cleanup(prepared, sendResult, liveCompletion) {
+        this.safeCleanup(() => prepared?.restoreCursorSdkOutputFilter());
+        const abortRegistration = sendResult?.abortRegistration;
+        if (abortRegistration) {
+            this.safeCleanup(() => abortRegistration.signal.removeEventListener("abort", abortRegistration.listener));
+        }
+        this.params.runnerParams.sdkEventDebugRef.current = undefined;
+        if (liveCompletion) {
+            void liveCompletion.waitCompletion
+                .finally(async () => {
+                await this.finalizeSdkEventDebugBestEffort();
+                this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
+            })
+                .catch(() => { });
+            return;
+        }
+        await prepared?.lifecycle.dispose().catch(() => { });
+        await this.finalizeSdkEventDebugBestEffort();
+        this.safeCleanup(() => this.params.sdkProcessErrorGuard.dispose());
+    }
+    async applyDirectOutcome(prepared, outcome, displayOnlyTraceBlock) {
+        const { stream, partial, model, context } = this.params.runnerParams;
+        prepared.runtime.turnCoordinator.closeTraceBlock();
+        switch (classifyCursorRunEmission(outcome)) {
+            case "cancelled":
+                await prepared.lifecycle.abandon();
+                this.pushTerminalError(partial, "aborted", getCursorRunAbortMessage(outcome));
+                break;
+            case "failed":
+                await prepared.lifecycle.abandon();
+                this.pushTerminalError(partial, "error", outcome.kind === "error" ? outcome.errorMessage : "Cursor SDK run failed.");
+                break;
+            case "finished":
+                prepared.lifecycle.commitSend(context, prepared.meta.bootstrap);
+                prepared.runtime.turnCoordinator.flushText(outcome.kind === "finished" && hasUsableText(outcome.finalText) ? [outcome.finalText] : []);
+                applyCursorUsage(partial, model, context, prepared.meta.promptInputTokens, {
+                    runtime: prepared.runtimeTarget,
+                    turn: prepared.runtime.turnCoordinator.lastSdkTurnUsage,
+                    billed: prepared.runtime.billedTurnUsage,
+                });
+                if (prepared.meta.resumeNotice)
+                    emitDisplayOnlyTraceBlock(stream, partial, prepared.meta.resumeNotice);
+                if (displayOnlyTraceBlock)
+                    emitDisplayOnlyTraceBlock(stream, partial, displayOnlyTraceBlock);
+                stream.push({ type: "done", reason: "stop", message: partial });
+                break;
+        }
+    }
+    async applyErrorOutcome(prepared, error) {
+        this.safeCleanup(() => prepared?.runtime.turnCoordinator.discardIncompleteStartedToolCalls(buildIncompleteCursorToolRunOutcome({
+            status: error instanceof CursorLiveRunAbortError ? "cancelled" : "error",
+            signalAborted: error instanceof CursorLiveRunAbortError,
+        })));
+        const activeLiveRun = prepared?.runtime.liveRun;
+        if (activeLiveRun && !activeLiveRun.disposed) {
+            await cursorLiveRuns.release(activeLiveRun);
+        }
+        else {
+            await prepared?.lifecycle.abandon();
+        }
+        this.safeCleanup(() => this.params.sdkEventDebug()?.recordError("provider_stream", error));
+        if (error instanceof CursorLiveRunAbortError) {
+            this.params.sdkProcessErrorGuard.suppressAbortErrors();
+            this.pushTerminalError(this.params.runnerParams.partial, "aborted", this.abortMessage());
+        }
+        else {
+            this.pushTerminalError(this.params.runnerParams.partial, "error", sanitizeCursorProviderError(error, this.params.resolvedApiKey() ?? this.params.runnerParams.options?.apiKey, prepared?.runtimeTarget ?? this.params.runtimeTarget()));
+        }
+    }
+    pushTerminalError(partial, reason, message) {
+        partial.stopReason = reason;
+        partial.errorMessage = message;
+        this.params.runnerParams.stream.push({ type: "error", reason, error: partial });
+    }
+    abortMessage() {
+        return formatCursorSdkAbortMessage(resolveCursorSdkAbortCause({ signalAborted: this.params.runnerParams.options?.signal?.aborted }));
+    }
+    safeCleanup(cleanup) {
+        try {
+            cleanup();
+        }
+        catch {
+            // Cleanup must not reclassify an already-emitted provider turn.
+        }
+    }
+    async finalizeSdkEventDebugBestEffort() {
+        try {
+            this.params.sdkEventDebug()?.recordFinalPartial(this.params.runnerParams.partial);
+            await this.params.sdkEventDebug()?.finalize();
+        }
+        catch {
+            // Debug artifact IO is best-effort and must not emit a second terminal event.
+        }
+    }
+}