@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.84af65cd215b6ca1

package/dist/ai-service/llm/stream/orchestrator.js

@@ -0,0 +1,1291 @@
+import { metrics } from "@opentelemetry/api";
+import { getErrorMeta, } from "../../../util/logger.js";
+import { measureToolResultChars, recordToolExecutionResultChars, } from "../../agent/tool-result-metrics.js";
+import { degradationKeyLogAttribute, notePromptDegradationForKey, } from "../../state-machine/helpers/prompt-degradation-metrics.js";
+import { buildThinkingProviderOptions } from "../../util/llm-config-utils.js";
+import { LLMProviderError } from "../error.js";
+import { getServerCompactionTextBlockUpdate } from "./compaction-text-block.js";
+import { AbortedError, RetriesExhaustedError, ToolExecutionTimeoutError, } from "./errors.js";
+import { IdleMonitor } from "./idle-monitor.js";
+import { createManagedStream } from "./managed-stream.js";
+import { RetryEngine } from "./retry-engine.js";
+import { StreamSession } from "./session.js";
+import { classifyTerminalReason } from "./terminal-reason.js";
+import { WaitStateTracker } from "./wait-state-tracker.js";
+const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 60_000;
+const METER_NAME = "superblocks.clark.tool_execution";
+const TOOL_EXECUTION_TIMEOUTS_METRIC = "superblocks.clark.tool.execution.timeouts_total";
+const TOOL_EXECUTION_DURATION_METRIC = "superblocks.clark.tool.execution.duration_seconds";
+const STREAM_TERMINAL_TOTAL_METRIC = "superblocks.clark.stream.terminal.total";
+const STREAM_STALLS_TOTAL_METRIC = "superblocks.clark.stream.stalls.total";
+const STREAM_LOCAL_WAITS_TOTAL_METRIC = "superblocks.clark.stream.local_waits.total";
+const EMPTY_TOOL_CALLS_TOTAL_METRIC = "superblocks.clark.stream.empty_tool_calls.total";
+const streamIdentityAttributes = (streamId) => ({
+    ai_stream_request_id: streamId,
+    stream_id: streamId,
+});
+let cachedMeter;
+let cachedMetrics;
+function resolveStreamOrchestratorMetrics() {
+    const meter = metrics.getMeter(METER_NAME);
+    if (meter === cachedMeter && cachedMetrics) {
+        return cachedMetrics;
+    }
+    cachedMeter = meter;
+    cachedMetrics = {
+        durationHistogram: meter.createHistogram(TOOL_EXECUTION_DURATION_METRIC, {
+            description: "Duration of Clark tool executions guarded by the stream orchestrator.",
+            unit: "s",
+        }),
+        emptyToolCallsCounter: meter.createCounter(EMPTY_TOOL_CALLS_TOTAL_METRIC, {
+            description: "Number of provider tool calls that ended without usable input.",
+            unit: "{tool_call}",
+        }),
+        timeoutCounter: meter.createCounter(TOOL_EXECUTION_TIMEOUTS_METRIC, {
+            description: "Number of Clark tool executions that reached their orchestrator timeout.",
+            unit: "{timeout}",
+        }),
+        streamStallsCounter: meter.createCounter(STREAM_STALLS_TOTAL_METRIC, {
+            description: "Number of Clark stream stalls detected, classified by budget kind and wait state. Includes retried and terminal stalls.",
+            unit: "{stall}",
+        }),
+        streamLocalWaitsCounter: meter.createCounter(STREAM_LOCAL_WAITS_TOTAL_METRIC, {
+            description: "Number of Clark stream idle budgets suppressed because local work or a slow consumer was active.",
+            unit: "{wait}",
+        }),
+        streamTerminalCounter: meter.createCounter(STREAM_TERMINAL_TOTAL_METRIC, {
+            description: "Number of Clark streams that ended before normal completion, classified by boundary and reason.",
+            unit: "{stream}",
+        }),
+    };
+    return cachedMetrics;
+}
+function recordToolExecutionDuration(toolName, outcome, durationMs) {
+    resolveStreamOrchestratorMetrics().durationHistogram.record(durationMs / 1000, {
+        outcome,
+        tool_name: toolName,
+    });
+}
+function recordToolExecutionTimeout(toolName) {
+    resolveStreamOrchestratorMetrics().timeoutCounter.add(1, {
+        tool_name: toolName,
+    });
+}
+function recordStreamTerminal(provider, model, outcome, terminalReason, waitState) {
+    resolveStreamOrchestratorMetrics().streamTerminalCounter.add(1, {
+        model,
+        outcome,
+        provider,
+        terminal_reason: terminalReason,
+        wait_state: waitState,
+    });
+}
+function recordStreamStall(provider, model, budgetKind, stallReason, waitState, timeoutSource) {
+    resolveStreamOrchestratorMetrics().streamStallsCounter.add(1, {
+        budget_kind: budgetKind,
+        model,
+        provider,
+        stall_reason: stallReason,
+        timeout_source: timeoutSource,
+        wait_state: waitState,
+    });
+}
+// The wait tracker reports "provider" for anything that is not a running tool
+// or a step gap — including the consumer holding the stream, which it cannot
+// see. When the stall was classified consumer-blocked, that "provider" is
+// really the consumer, so relabel it before it lands on the stall metric/log
+// (they would otherwise contradict `stall_reason=consumer-blocked`). Genuine
+// network-dark provider silence stays "provider". Exported for unit testing.
+export function resolveStallWaitState(stallReason, waitState) {
+    return stallReason === "consumer-blocked" && waitState === "provider"
+        ? "consumer"
+        : waitState;
+}
+function recordStreamLocalWait(provider, model, waitState, timeoutSource) {
+    resolveStreamOrchestratorMetrics().streamLocalWaitsCounter.add(1, {
+        model,
+        provider,
+        timeout_source: timeoutSource,
+        wait_state: waitState,
+    });
+}
+function recordEmptyToolCalls(provider, model, count) {
+    resolveStreamOrchestratorMetrics().emptyToolCallsCounter.add(count, {
+        model,
+        provider,
+    });
+}
+function getToolExecutionTimeoutMs(tool) {
+    // Treat non-positive, non-finite, or absent values as "use default".
+    return typeof tool.timeoutMs === "number" &&
+        Number.isFinite(tool.timeoutMs) &&
+        tool.timeoutMs > 0
+        ? tool.timeoutMs
+        : DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+}
+async function executeToolWithTimeout(name, tool, execute, input, executeOptions, logger, getStepNumber, degradationKey) {
+    const timeoutMs = getToolExecutionTimeoutMs(tool);
+    const startedAtMs = Date.now();
+    const baseAttributes = {
+        timeout_ms: timeoutMs,
+        tool_call_id: executeOptions.toolCallId,
+        tool_name: name,
+    };
+    let timeoutId;
+    const toolAbortController = new AbortController();
+    const parentAbortSignal = executeOptions.abortSignal;
+    let removeParentAbortListener;
+    if (parentAbortSignal?.aborted) {
+        toolAbortController.abort();
+    }
+    else if (parentAbortSignal) {
+        const onParentAbort = () => toolAbortController.abort();
+        parentAbortSignal.addEventListener("abort", onParentAbort, { once: true });
+        removeParentAbortListener = () => parentAbortSignal.removeEventListener("abort", onParentAbort);
+    }
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            toolAbortController.abort();
+            reject(new ToolExecutionTimeoutError(name, timeoutMs, input));
+        }, timeoutMs);
+    });
+    const optionsWithTimeoutSignal = {
+        ...executeOptions,
+        abortSignal: toolAbortController.signal,
+    };
+    logger.info("[orchestrator] Tool execution started", {
+        ...baseAttributes,
+        event: "clark_tool_execution_start",
+    });
+    try {
+        const result = await Promise.race([
+            execute(input, optionsWithTimeoutSignal),
+            timeout,
+        ]);
+        const durationMs = Date.now() - startedAtMs;
+        recordToolExecutionDuration(name, "success", durationMs);
+        // How much text this result adds to the conversation. Measured here rather
+        // than in the output limiter, because that middleware returns early for the
+        // tools allowed to skip it — the browser tools, the SDK docs tool and the
+        // integration tool — which are the ones most likely to return something
+        // enormous (APPS-5576). A size observation must never fail a tool call that
+        // already succeeded, so it is guarded like the other stream metrics.
+        try {
+            recordToolExecutionResultChars(name, measureToolResultChars(tool, {
+                input,
+                output: result,
+                toolCallId: executeOptions.toolCallId,
+            }), getStepNumber());
+        }
+        catch {
+            // The duration metric above remains the per-execution source of truth.
+        }
+        logger.info("[orchestrator] Tool execution completed", {
+            ...baseAttributes,
+            duration_ms: durationMs,
+            event: "clark_tool_execution_complete",
+        });
+        return result;
+    }
+    catch (error) {
+        const durationMs = Date.now() - startedAtMs;
+        const outcome = error instanceof ToolExecutionTimeoutError ? "timeout" : "error";
+        recordToolExecutionDuration(name, outcome, durationMs);
+        if (error instanceof ToolExecutionTimeoutError) {
+            recordToolExecutionTimeout(name);
+            notePromptDegradationForKey(degradationKey, "tool_timeout");
+        }
+        const attributes = {
+            ...baseAttributes,
+            duration_ms: durationMs,
+            error_kind: error instanceof Error ? error.name : "unknown",
+            event: error instanceof ToolExecutionTimeoutError
+                ? "clark_tool_execution_timeout"
+                : "clark_tool_execution_error",
+            ...degradationKeyLogAttribute(degradationKey),
+        };
+        if (error instanceof ToolExecutionTimeoutError) {
+            logger.warn("[orchestrator] Tool execution timed out", attributes);
+        }
+        else {
+            logger.warn("[orchestrator] Tool execution failed", attributes);
+            logger.error("[orchestrator] Tool execution failed", {
+                ...attributes,
+                error: {
+                    kind: error instanceof Error ? error.name : "unknown",
+                    message: "Tool execution failed; raw error details omitted",
+                },
+            });
+        }
+        throw error;
+    }
+    finally {
+        removeParentAbortListener?.();
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/**
+ * Tracks the in-flight provider attempt for a single execute() call so a
+ * superseded attempt can be cut off the instant we decide to retry.
+ *
+ * Each attempt (the initial stream and every retry) gets its own AbortController
+ * chained to the execute-level parent signal. The Vercel AI SDK keeps draining a
+ * streamText() result and auto-executing tools regardless of whether we read its
+ * fullStream, so abandoning the stream is not enough — the only thing that stops
+ * a superseded attempt is aborting its signal. The orchestrator aborts the
+ * current attempt at the retry decision, before the backoff delay, so the loser
+ * can't race the winner to run terminal tools.
+ */
+class AttemptCoordinator {
+    parent;
+    current = null;
+    parentListener = null;
+    constructor(parent) {
+        this.parent = parent;
+    }
+    /**
+     * Begin a new attempt. Returns the attempt's abort signal and a predicate that
+     * is true only while this attempt is the live one and neither it nor the parent
+     * has been aborted. Used to fence tool execution and lifecycle callbacks so a
+     * superseded attempt's late, buffered events are ignored.
+     */
+    begin() {
+        // Drop the superseded attempt's parent listener so they don't accumulate on
+        // the session signal for the whole execute() lifetime.
+        this.detachParentListener();
+        const controller = new AbortController();
+        if (this.parent.aborted) {
+            controller.abort();
+        }
+        else {
+            const onParentAbort = () => controller.abort();
+            this.parentListener = onParentAbort;
+            this.parent.addEventListener("abort", onParentAbort, { once: true });
+        }
+        this.current = controller;
+        const isCurrent = () => this.current === controller && // still the most-recent begin() call
+            !controller.signal.aborted && // not superseded via abortCurrent()
+            !this.parent.aborted; // defensive: parent abort also cascades via listener
+        return { signal: controller.signal, isCurrent };
+    }
+    /**
+     * Abort the in-flight attempt. Called at the retry decision, before backoff,
+     * to close the window where a stale attempt could wake up and execute tools.
+     */
+    abortCurrent() {
+        this.current?.abort();
+    }
+    detachParentListener() {
+        if (this.parentListener) {
+            this.parent.removeEventListener("abort", this.parentListener);
+            this.parentListener = null;
+        }
+    }
+}
+/**
+ * The main coordinator for stream operations.
+ *
+ * Brings together all components:
+ * - StreamSession for state management
+ * - RetryEngine for retry/fallback decisions
+ * - ManagedStream for lifecycle tracking
+ * - Observers for side effects
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = new StreamOrchestrator({
+ *   provider: createVercelProvider(),
+ *   config: StreamConfig.create({ provider: "vertex", model: "claude-sonnet-4-5", retry: { maxAttempts: 3 } }),
+ *   observers: [new LoggingObserver()],
+ *   logger: getLogger(),
+ * });
+ *
+ * const result = await orchestrator.execute({
+ *   model,
+ *   messages,
+ *   tools,
+ * });
+ *
+ * for await (const chunk of result.fullStream) {
+ *   console.log(chunk);
+ * }
+ * ```
+ */
+export class StreamOrchestrator {
+    terminalSummariesObserved = new WeakSet();
+    terminalSummaryErrors = new WeakMap();
+    provider;
+    config;
+    observers;
+    logger;
+    organizationId;
+    applicationId;
+    getJwt;
+    degradationKey;
+    constructor(options) {
+        this.provider = options.provider;
+        this.config = options.config;
+        this.observers = options.observers ?? [];
+        this.logger = options.logger;
+        this.organizationId = options.organizationId;
+        this.applicationId = options.applicationId;
+        this.getJwt = options.getJwt;
+        this.degradationKey = options.degradationKey;
+    }
+    noteStreamDegradation(reason) {
+        notePromptDegradationForKey(this.degradationKey, reason);
+    }
+    async execute(options) {
+        if (options.abortSignal?.aborted) {
+            throw new Error("aborted");
+        }
+        const retryEngine = new RetryEngine(this.config);
+        const initialProvider = retryEngine.getInitialProvider();
+        const session = new StreamSession({
+            config: this.config,
+            initialProvider,
+            organizationId: this.organizationId,
+            applicationId: this.applicationId,
+            getJwt: this.getJwt,
+        });
+        // Start watching before any data flows so that, if the stream stalls, we
+        // can say what it was stuck on (the model vs. a local tool or step gap).
+        const waitStateTracker = new WaitStateTracker(session);
+        const internalAbortController = new AbortController();
+        const attempts = new AttemptCoordinator(internalAbortController.signal);
+        if (options.abortSignal) {
+            options.abortSignal.addEventListener("abort", () => {
+                internalAbortController.abort();
+            });
+        }
+        const optionsWithAbort = {
+            ...options,
+            abortSignal: internalAbortController.signal,
+        };
+        this.logger.info(`[orchestrator] Starting session ${session.id} with provider=${initialProvider.name} model=${initialProvider.model}`);
+        for (const observer of this.observers) {
+            observer.attach(session.events, this.config);
+        }
+        // Records the metric + structured warning when an attempt's stream ends with
+        // one or more unusable tool calls. The managed stream owns detection per
+        // attempt and surfaces a retryable error; this hook only reports it.
+        const reportEmptyToolCalls = (tracker) => this.logEmptyToolCalls(session, tracker);
+        session.events.on("session:error", (error, endedSession) => {
+            this.logTerminalStreamSummary(endedSession, waitStateTracker, "error", error);
+        });
+        session.events.on("session:abort", (endedSession) => {
+            if (endedSession.outcome !== "aborted") {
+                return;
+            }
+            this.logTerminalStreamSummary(endedSession, waitStateTracker, "aborted");
+        });
+        await session.events.emit("session:start", session, {
+            system: options.system,
+            messages: options.messages ?? [],
+            user: options.user,
+            tools: options.tools,
+        });
+        internalAbortController.signal.addEventListener("abort", () => {
+            // Only surface an abort while the session is still in flight. An abort
+            // racing natural completion (a consumer that early-exits just as the
+            // stream finalizes — APPS-5162) must not emit a spurious session:abort
+            // over an already completed/errored session.
+            if (!session.isPending()) {
+                this.logger.debug("[orchestrator] session:abort suppressed — session already finalized", { session_id: session.id, outcome: session.outcome });
+                return;
+            }
+            void session.events.emit("session:abort", session);
+        });
+        // Idle monitoring: aborts hung streams that stop sending chunks. Budgets
+        // are resolved per attempt from the CURRENT model (session.provider.model)
+        // so a fallback to a different model is monitored against its own budget,
+        // not the initial model's frozen one. See APPS-4775.
+        const idleMonitor = new IdleMonitor({
+            session,
+            maxIdleTimeMs: () => this.config.retry.budgetForModel(session.provider.model).idleTimeoutMs,
+            firstTokenTimeoutMs: () => this.config.retry.budgetForModel(session.provider.model)
+                .firstTokenTimeoutMs,
+            contentSilenceTimeoutMs: () => this.config.retry.budgetForModel(session.provider.model)
+                .contentSilenceTimeoutMs,
+            compactionSummaryTimeoutMs: () => this.config.retry.budgetForModel(session.provider.model)
+                .compactionSummaryTimeoutMs,
+            onServerCompactionStart: (blockId) => {
+                this.logger.debug("[orchestrator] Server-side compaction chunk detected", {
+                    sessionId: session.id,
+                    provider: session.provider.name,
+                    model: session.provider.model,
+                    attempt: session.attempt,
+                    blockId,
+                });
+            },
+            shouldPause: () => {
+                // Reads only plain in-memory state, so it should never throw. Guard it
+                // anyway and log if it does: a silent failure here would let a false
+                // stall through and rotate the provider — the exact bug this prevents —
+                // with no signal for oncall to find it. On error, return false so the
+                // stall still fires (failing safe toward surfacing a real stall).
+                try {
+                    // Only a genuine wait on the provider's next byte should count toward
+                    // a stall. If a tool is running or we're between steps, the gap is
+                    // local work — not the model going silent — so pause instead of
+                    // firing a false stall that would pointlessly rotate providers. See
+                    // APPS-4605.
+                    const waitState = waitStateTracker.getWaitState();
+                    if (waitState.state === "tool" ||
+                        waitState.state === "step-boundary") {
+                        return true;
+                    }
+                    // isAwaitingUpstream() is true only while the managed stream is
+                    // blocked waiting for the provider's next chunk. False means the
+                    // consumer took a chunk and hasn't asked for the next one yet (e.g.
+                    // it's busy on its own downstream call), so the silence is on the
+                    // consumer's side, not the provider's. Require at least one chunk to
+                    // have arrived first: before that the gap is real provider silence
+                    // (and the flag may not be set yet because the read happens lazily),
+                    // so it must never be mistaken for the consumer holding the stream.
+                    //
+                    // Trade-off: if the provider connection drops while the consumer is
+                    // holding a chunk, the dead connection is invisible until the
+                    // consumer pulls again, since we suppress the stall for the whole
+                    // consumer-hold window. That is acceptable because a slow consumer is
+                    // the intended case and the consumer (the dev server request) carries
+                    // its own request timeout that aborts the stream if it never resumes.
+                    return (!session.isAwaitingUpstream() && session.metrics.chunkCount > 0);
+                }
+                catch (err) {
+                    this.logger.error("[orchestrator] shouldPause check failed", {
+                        error: {
+                            kind: err instanceof Error ? err.name : "unknown",
+                            message: err instanceof Error ? err.message : String(err),
+                            stack: err instanceof Error ? err.stack : undefined,
+                        },
+                    });
+                    return false;
+                }
+            },
+            onPause: () => {
+                // One structured event at the start of each local-wait stretch (a tool
+                // running, a step gap, or the consumer holding the stream past the idle
+                // budget). No stream_stall fires for these, so without this a hung tool
+                // would be invisible to the stream layer until the request aborts. The
+                // idle monitor fires this once per stretch, so a healthy slow tool logs
+                // once, not once per re-arm. See APPS-4605.
+                const waitState = waitStateTracker.getWaitState();
+                const budget = this.config.retry.budgetForModel(session.provider.model);
+                const loggedWaitState = waitState.state === "provider" ? "consumer" : waitState.state;
+                try {
+                    recordStreamLocalWait(session.provider.name, session.provider.model, loggedWaitState, budget.timeoutSource);
+                }
+                catch {
+                    // The structured WARN below remains the diagnostic source of truth.
+                }
+                const message = `[orchestrator] Local wait suppressed idle stall`;
+                const attributes = {
+                    event: "stream_local_wait",
+                    session_id: session.id,
+                    ...streamIdentityAttributes(session.id),
+                    provider: session.provider.name,
+                    model: session.provider.model,
+                    attempt: session.attempt,
+                    elapsed_ms: session.getElapsedMs(),
+                    chunks_received: session.metrics.chunkCount,
+                    timeout_source: budget.timeoutSource,
+                    // "tool"/"step-boundary" come from the wait tracker; "consumer" is the
+                    // remaining case (consumer holding the stream), which the tracker
+                    // reports as "provider" since it does not track consumer-pull state.
+                    wait_state: loggedWaitState,
+                };
+                if (waitState.state === "tool") {
+                    attributes.tool_name = waitState.toolName;
+                    attributes.tool_call_id = waitState.toolCallId;
+                    attributes.pending_tool_count = waitState.pendingToolCount;
+                }
+                if (session.organizationId) {
+                    attributes.organization_id = session.organizationId;
+                }
+                if (session.applicationId) {
+                    attributes.application_id = session.applicationId;
+                }
+                if (this.logger.warnStructured) {
+                    this.logger.warnStructured(message, attributes);
+                }
+                else {
+                    this.logger.warn(message, attributes);
+                }
+            },
+            onStall: (error) => {
+                // budgetKind is carried on the error (set when the timer armed) because
+                // budgets are now per-model and can't be re-derived by numeric comparison.
+                const budgetKind = error.budgetKind;
+                const budget = this.config.retry.budgetForModel(session.provider.model);
+                const msSinceLastPull = session.getTimeSinceLastPull();
+                // Discriminate network-dark vs consumer-blocked (APPS-4729). The
+                // managed stream flips isAwaitingUpstream() around its
+                // `await iterator.next()`: true means the stall fired while we were
+                // blocked reading upstream (the wire went dark); false means the
+                // consumer is holding the stream without pulling (e.g. blocked on a
+                // downstream RPC). A boolean rather than an ms_since_last_pull
+                // comparison, which is unreliable near the idle-budget boundary. The
+                // flag read here is consistent because IdleMonitor runs this onStall
+                // callback synchronously, before the rejected waitForStall() propagates
+                // into the managed stream's catch and clears the flag (see idle-monitor).
+                //
+                // First-output stalls are upstream silence by definition: no useful
+                // content was delivered, so the consumer cannot be holding the stream.
+                // Force "network-dark" rather than trusting the flag — pull() is lazy.
+                const stallReason = budgetKind === "first-token" ||
+                    budgetKind === "content-silence" ||
+                    budgetKind === "compaction" ||
+                    session.isAwaitingUpstream()
+                    ? "network-dark"
+                    : "consumer-blocked";
+                const message = `[orchestrator] Idle timeout exceeded, triggering retry`;
+                // Emit as structured attributes (OTel log attributes -> Datadog facets)
+                // so stalls are queryable by provider/model/attempt and chartable,
+                // rather than buried in the message body. Keys are snake_case to match
+                // the OTel/Datadog facet convention used elsewhere (AiAttributes,
+                // awaiting-user.ts). budget_ms + budget_kind already capture which idle
+                // budget applied and its value, so the static config constants are not
+                // re-emitted per stall. See APPS-4643.
+                // wait_state says what the stall was stuck on: "provider" = the model
+                // went silent, "tool" = a local tool was still running (a slow tool,
+                // not the model), "step-boundary" = it was between steps, "consumer" =
+                // the consumer held the stream without pulling. See resolveStallWaitState
+                // for why "consumer" is derived rather than reported by the tracker.
+                // raw_reset_count is how many keep-alive pings arrived during this
+                // stretch of silence; a healthy-but-quiet model still pings, so 0 means
+                // no pings got through. Pairs with ms_since_last_pull (how recently the
+                // reader pulled).
+                const waitState = waitStateTracker.getWaitState();
+                const loggedWaitState = resolveStallWaitState(stallReason, waitState.state);
+                try {
+                    recordStreamStall(session.provider.name, session.provider.model, budgetKind, stallReason, loggedWaitState, budget.timeoutSource);
+                }
+                catch {
+                    // The structured WARN below remains the diagnostic source of truth.
+                }
+                this.noteStreamDegradation("stall_retried");
+                const attributes = {
+                    event: "stream_stall",
+                    session_id: session.id,
+                    ...streamIdentityAttributes(session.id),
+                    provider: session.provider.name,
+                    model: session.provider.model,
+                    attempt: session.attempt,
+                    budget_kind: budgetKind,
+                    idle_ms: error.idleTimeMs,
+                    budget_ms: error.maxIdleTimeMs,
+                    timeout_source: budget.timeoutSource,
+                    elapsed_ms: session.getElapsedMs(),
+                    chunks_received: session.metrics.chunkCount,
+                    stall_reason: stallReason,
+                    wait_state: loggedWaitState,
+                    raw_reset_count: waitStateTracker.getRawResetCount(),
+                    ...degradationKeyLogAttribute(this.degradationKey),
+                };
+                if (waitState.state === "tool") {
+                    attributes.tool_name = waitState.toolName;
+                    attributes.tool_call_id = waitState.toolCallId;
+                    attributes.pending_tool_count = waitState.pendingToolCount;
+                }
+                // Supporting numeric signal: how long since the consumer last pulled.
+                // stall_reason is the primary discriminator; this aids triage. Absent
+                // when the consumer never made a productive pull.
+                if (msSinceLastPull !== undefined) {
+                    attributes.ms_since_last_pull = msSinceLastPull;
+                }
+                // Customer-scoped facets let on-call triage stalls by org/app during an
+                // incident; only emitted when the session carries them.
+                if (session.organizationId) {
+                    attributes.organization_id = session.organizationId;
+                }
+                if (session.applicationId) {
+                    attributes.application_id = session.applicationId;
+                }
+                if (this.logger.warnStructured) {
+                    this.logger.warnStructured(message, attributes);
+                }
+                else {
+                    this.logger.warn(message, attributes);
+                }
+            },
+        });
+        const result = await this.startStreamWithRetry(optionsWithAbort, session, retryEngine, attempts, waitStateTracker);
+        // Start monitoring now that the stream is active
+        idleMonitor.start();
+        // wrapper order matters here. managed stream throws errors (error chunks), retry wrapper catches them.
+        // Pass the idle monitor so it can interrupt hung streams.
+        const managedStream = createManagedStream(result.fullStream, session, idleMonitor, reportEmptyToolCalls);
+        const retryableFullStream = this.wrapWithRetry(managedStream, (r) => createManagedStream(r.fullStream, session, idleMonitor, reportEmptyToolCalls), optionsWithAbort, session, retryEngine, internalAbortController, attempts, waitStateTracker);
+        // fullStream (typed parts) and textStream (text deltas only) are two views
+        // of the same retry-wrapped source. A plain `tee()` keeps both readable
+        // independently, but it buffers every chunk for any branch that is never
+        // read -- and in practice each caller reads exactly one view (the agent
+        // loop reads fullStream; summarizers read textStream). That left the unread
+        // branch pinning one part reference per chunk (including large tool
+        // results) for the whole generation.
+        //
+        // Instead, tee lazily: a lone consumer reads the source directly, and we
+        // only tee when both views are actually requested. The tee decision is made
+        // synchronously when the second view is accessed, while each view binds to
+        // the source on first read (highWaterMark 0, so no eager pull) -- so a
+        // second view requested before any read still gets a clean tee branch.
+        const source = retryableFullStream;
+        let teeBranches;
+        let firstView;
+        let readStarted = false;
+        let fullStreamView;
+        let textStreamView;
+        const noteViewAccess = (view) => {
+            if (firstView === undefined) {
+                firstView = view;
+            }
+            else if (firstView !== view && teeBranches === undefined) {
+                // Both views must be set up before either starts reading, so the tee
+                // splits off a source no one has consumed yet. Once the first view has
+                // read, the source is partially or fully drained: tee() would either
+                // throw "ReadableStream is locked" (mid-read) or silently return closed
+                // branches that read as empty (already drained). Both are worse than a
+                // clear error, so refuse once reading has started.
+                if (readStarted) {
+                    throw new Error("[StreamOrchestrator] cannot create a second stream view after reading has started: " +
+                        "access both fullStream and textStream before reading either.");
+                }
+                teeBranches = source.tee();
+            }
+        };
+        // Reads the shared parts for one view, choosing its tee branch when both
+        // views are live and the raw source when this is the only consumer. The
+        // branch is resolved on first read, after the tee decision is settled.
+        // tee() returns [branch0, branch1] in call order, so branch 0 feeds
+        // fullStream and branch 1 feeds textStream.
+        const readParts = (view) => (async function* () {
+            // Mark reading as begun so a late second-view access fails loudly
+            // instead of teeing an already-consumed source.
+            readStarted = true;
+            const branch = teeBranches
+                ? teeBranches[view === "full" ? 0 : 1]
+                : source;
+            const reader = branch.getReader();
+            let drained = false;
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        drained = true;
+                        return;
+                    }
+                    yield value;
+                }
+            }
+            finally {
+                reader.releaseLock();
+                // If the consumer stopped early (cancellation), stop generation and
+                // tear the branch down. Aborting is load-bearing, not just tidy:
+                // cancelling the stream alone leaves the provider generating (see
+                // AttemptCoordinator — abandoning the stream does not stop the Vercel
+                // SDK), which is the token-burn half of APPS-5162. Abort first so a
+                // provider blocked on a read unblocks and the branch cancel settles.
+                if (!drained) {
+                    internalAbortController.abort();
+                    await branch.cancel().catch(() => { });
+                }
+            }
+        })();
+        // Arrow builders capture `this` lexically and memoize each view, so the
+        // getters below stay thin and the tee decision happens once per view.
+        const buildFullStream = () => {
+            if (!fullStreamView) {
+                noteViewAccess("full");
+                fullStreamView = this.readableFromAsyncIterable(readParts("full"));
+            }
+            return fullStreamView;
+        };
+        const buildTextStream = () => {
+            if (!textStreamView) {
+                noteViewAccess("text");
+                textStreamView = this.readableFromAsyncIterable(this.extractTextDeltas(readParts("text")));
+            }
+            return textStreamView;
+        };
+        return {
+            ...result,
+            get fullStream() {
+                return buildFullStream();
+            },
+            get textStream() {
+                return buildTextStream();
+            },
+        };
+    }
+    asAsyncIterableStream(stream) {
+        const asyncIterableStream = stream;
+        if (asyncIterableStream[Symbol.asyncIterator]) {
+            return asyncIterableStream;
+        }
+        return Object.assign(stream, {
+            async *[Symbol.asyncIterator]() {
+                const reader = stream.getReader();
+                try {
+                    while (true) {
+                        const result = await reader.read();
+                        if (result.done) {
+                            return;
+                        }
+                        yield result.value;
+                    }
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            },
+        });
+    }
+    /**
+     * Wraps an async iterable as a ReadableStream that pulls one item per read.
+     * highWaterMark 0 keeps it from pulling eagerly, so binding to the underlying
+     * source is deferred until the consumer actually reads.
+     */
+    readableFromAsyncIterable(iterable) {
+        const iterator = iterable[Symbol.asyncIterator]();
+        const stream = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { done, value } = await iterator.next();
+                    if (done) {
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(value);
+                    }
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                // Returning the iterator runs the generator's finally block, which
+                // releases the reader and cancels the upstream branch/source so
+                // cancellation propagates all the way back to the provider.
+                await iterator.return?.(reason);
+            },
+        }, { highWaterMark: 0 });
+        return this.asAsyncIterableStream(stream);
+    }
+    /**
+     * Projects a stream of typed parts down to text deltas, dropping server-side
+     * compaction summary blocks so they never surface through textStream.
+     */
+    async *extractTextDeltas(parts) {
+        const compactionTextBlockIds = new Set();
+        for await (const chunk of parts) {
+            const compactionBlock = getServerCompactionTextBlockUpdate(chunk);
+            if (compactionBlock.kind === "start") {
+                compactionTextBlockIds.add(compactionBlock.id);
+                continue;
+            }
+            if (compactionBlock.kind === "part" &&
+                compactionTextBlockIds.has(compactionBlock.id)) {
+                if (compactionBlock.done) {
+                    compactionTextBlockIds.delete(compactionBlock.id);
+                }
+                continue;
+            }
+            if (chunk.type === "text-delta") {
+                yield chunk.text;
+            }
+        }
+    }
+    logTerminalStreamSummary(session, waitStateTracker, outcome, error) {
+        if (this.terminalSummariesObserved.has(session)) {
+            return;
+        }
+        this.terminalSummariesObserved.add(session);
+        const budget = this.config.retry.budgetForModel(session.provider.model);
+        const waitState = waitStateTracker.getWaitState();
+        const terminalError = this.terminalSummaryErrors.get(session) ?? error;
+        this.terminalSummaryErrors.delete(session);
+        const terminalReason = this.terminalReason(outcome, terminalError);
+        try {
+            recordStreamTerminal(session.provider.name, session.provider.model, outcome, terminalReason, waitState.state);
+        }
+        catch {
+            // The WARN summary below is the per-stream diagnostic source of truth.
+        }
+        const attributes = {
+            event: "stream_terminal_summary",
+            session_id: session.id,
+            ...streamIdentityAttributes(session.id),
+            provider: session.provider.name,
+            model: session.provider.model,
+            attempt: session.attempt,
+            outcome,
+            terminal_reason: terminalReason,
+            elapsed_ms: session.getElapsedMs(),
+            chunks_received: session.metrics.chunkCount,
+            raw_reset_count: waitStateTracker.getRawResetCount(),
+            wait_state: waitState.state,
+            idle_timeout_ms: budget.idleTimeoutMs,
+            first_token_timeout_ms: budget.firstTokenTimeoutMs,
+            content_silence_timeout_ms: budget.contentSilenceTimeoutMs,
+            timeout_source: budget.timeoutSource,
+            ms_since_last_activity: session.getTimeSinceLastActivity(),
+            ms_since_last_content: session.getTimeSinceLastContent(),
+        };
+        if (waitState.state === "tool") {
+            attributes.tool_name = waitState.toolName;
+            attributes.tool_call_id = waitState.toolCallId;
+            attributes.pending_tool_count = waitState.pendingToolCount;
+        }
+        if (session.organizationId) {
+            attributes.organization_id = session.organizationId;
+        }
+        if (session.applicationId) {
+            attributes.application_id = session.applicationId;
+        }
+        if (terminalError instanceof Error) {
+            attributes.error_name = terminalError.name;
+        }
+        const message = "[orchestrator] Stream terminal summary";
+        if (this.logger.warnStructured) {
+            this.logger.warnStructured(message, attributes);
+        }
+        else {
+            this.logger.warn(message, attributes);
+        }
+    }
+    terminalReason(outcome, error) {
+        return classifyTerminalReason(outcome, error);
+    }
+    /**
+     * Wraps a fullStream with retry logic. When an error occurs (either thrown or
+     * as an error chunk), makes a retry decision and either creates a new stream
+     * or throws the final error. It catches errors from the managed stream (inner)
+     * and decides whether to retry or give up. Session finalization happens here,
+     * not in the managed stream. If you add finalization to managed-stream.ts,
+     * retries will silently fail (the new stream will close immediately because
+     * session.isPending() returns false).
+     */
+    wrapWithRetry(initialStream, getNewStream, options, session, retryEngine, abortController, attempts, waitStateTracker) {
+        const handleRetry = this.handleRetryDecision.bind(this);
+        let currentStream = initialStream;
+        async function* createRetryIterator() {
+            while (true) {
+                try {
+                    for await (const chunk of currentStream) {
+                        // throw for the retry logic to take over
+                        if (chunk.type === "error") {
+                            throw chunk.error;
+                        }
+                        yield chunk;
+                    }
+                    return;
+                }
+                catch (error) {
+                    const retryResult = await handleRetry(error, options, session, retryEngine, attempts, waitStateTracker);
+                    if (!retryResult.shouldRetry) {
+                        // abort the internal signal so any in-flight stream processing stops.
+                        // without this, tools keep getting called in the background since the stream is not closed.
+                        abortController.abort();
+                        throw retryResult.error;
+                    }
+                    currentStream = getNewStream(retryResult.newResult);
+                }
+            }
+        }
+        const sharedIterator = createRetryIterator();
+        const readable = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const result = await sharedIterator.next();
+                    if (result.done) {
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(result.value);
+                    }
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            async cancel() {
+                await sharedIterator.return?.(undefined);
+            },
+        });
+        return readable;
+    }
+    /**
+     * Handle an error by making a retry decision. Returns either a new result to continue
+     * with, or the final error to throw.
+     */
+    async handleRetryDecision(error, options, session, retryEngine, attempts, waitStateTracker) {
+        const decision = retryEngine.getRetryDecision(error, session, options.abortSignal, waitStateTracker.getWaitState());
+        if (!decision.shouldRetry) {
+            this.logger.warn(`[orchestrator] Not retrying: reason=${decision.reason}`, getErrorMeta(error));
+            const finalError = this.wrapFinalError(error, decision.reason ?? "unknown", session);
+            this.terminalSummaryErrors.set(session, finalError);
+            session.finalize("error", finalError);
+            return {
+                shouldRetry: false,
+                error: finalError,
+            };
+        }
+        // Supersede the failed attempt now, before the backoff delay, so its
+        // abandoned stream can't keep executing tools while we wait to retry.
+        attempts.abortCurrent();
+        await session.events.emit("retry", error, session.attempt, decision.delayMs, session);
+        if (decision.newProvider) {
+            await this.switchProvider(session, decision.newProvider, decision.fastFallback === true, error);
+        }
+        session.recordRetry(decision.delayMs);
+        this.logger.warn(`[orchestrator] Retrying in ${decision.delayMs}ms (attempt ${session.attempt}) reason=${decision.reason ?? "retry"}`, getErrorMeta(error));
+        await this.delay(decision.delayMs, options.abortSignal);
+        const newResult = await this.startStreamWithRetry(options, session, retryEngine, attempts, waitStateTracker);
+        return { shouldRetry: true, newResult };
+    }
+    async startStreamWithRetry(options, session, retryEngine, attempts, waitStateTracker) {
+        while (true) {
+            try {
+                return await this.startStream(options, session, attempts);
+            }
+            catch (error) {
+                const decision = retryEngine.getRetryDecision(error, session, options.abortSignal, waitStateTracker.getWaitState());
+                if (!decision.shouldRetry) {
+                    this.logger.error(`[orchestrator] Startup error, not retrying: reason=${decision.reason}`, {
+                        error: {
+                            kind: error instanceof Error ? error.name : "unknown",
+                            message: error instanceof Error ? error.message : String(error),
+                            stack: error instanceof Error ? error.stack : undefined,
+                        },
+                    });
+                    const finalError = this.wrapFinalError(error, decision.reason ?? "unknown", session);
+                    this.terminalSummaryErrors.set(session, finalError);
+                    await session.events.emit("session:error", finalError, session);
+                    throw finalError;
+                }
+                // Supersede the failed attempt before backoff.
+                attempts.abortCurrent();
+                await session.events.emit("retry", error, session.attempt, decision.delayMs, session);
+                if (decision.newProvider) {
+                    await this.switchProvider(session, decision.newProvider, decision.fastFallback === true, error);
+                }
+                session.recordRetry(decision.delayMs);
+                this.logger.info(`[orchestrator] Startup retry in ${decision.delayMs}ms (attempt ${session.attempt}) reason=${decision.reason ?? "retry"}`);
+                await this.delay(decision.delayMs, options.abortSignal);
+            }
+        }
+    }
+    wrapFinalError(error, reason, session) {
+        if (reason === "aborted") {
+            return new AbortedError();
+        }
+        if (reason === "max-attempts" || reason === "max-time") {
+            return new RetriesExhaustedError(session.attempt, session.getElapsedMs(), error);
+        }
+        if (error instanceof LLMProviderError) {
+            const finalError = new LLMProviderError({
+                provider: error.provider,
+                message: error.message,
+                type: error.type,
+                isRetryable: false,
+                cause: error.cause,
+            });
+            finalError.statusCode = error.statusCode;
+            finalError.url = error.url;
+            finalError.data = error.data;
+            return finalError;
+        }
+        return new LLMProviderError({
+            provider: session.provider.name,
+            message: error instanceof Error ? error.message : "LLM stream failed",
+            isRetryable: false,
+            cause: error,
+        });
+    }
+    async startStream(options, session, attempts) {
+        if (options.abortSignal?.aborted) {
+            throw new AbortedError();
+        }
+        const providerOptions = this.applyProvider(options, session.provider, session);
+        this.logger.debug(`[orchestrator] Attempt ${session.attempt} with provider=${session.provider.name} model=${session.provider.model}`);
+        // Each attempt runs on its own abort signal so a superseded attempt can be
+        // aborted without killing the winning one. `isCurrent` fences tool execution
+        // and lifecycle callbacks: the Vercel AI SDK can still deliver buffered tool
+        // calls and callbacks from a superseded attempt after abort (abort is
+        // cooperative), so the live-attempt check is what prevents duplicate tool
+        // execution and duplicate finish events.
+        const { signal, isCurrent } = attempts.begin();
+        return this.provider.streamText({
+            ...providerOptions,
+            abortSignal: signal,
+            tools: this.guardToolsForAttempt(providerOptions.tools, isCurrent, () => session.currentStep),
+            prepareStep: async (step) => {
+                if (!isCurrent()) {
+                    throw new AbortedError();
+                }
+                const preparedStep = (await options.prepareStep?.(step)) ?? step;
+                session.currentStep = preparedStep.stepNumber;
+                await session.events.emit("step:start", {
+                    stepNumber: preparedStep.stepNumber,
+                    activeTools: preparedStep.activeTools,
+                }, session);
+                return preparedStep;
+            },
+            onStepFinish: async (step) => {
+                if (!isCurrent()) {
+                    return;
+                }
+                await session.events.emit("step:finish", step, session);
+                await options.onStepFinish?.(step);
+            },
+            onFinish: async (finalResult) => {
+                if (!isCurrent()) {
+                    return;
+                }
+                session.setTotalTokens(finalResult.totalUsage?.totalTokens ?? 0);
+                await session.events.emit("stream:finish", finalResult, session);
+                return options.onFinish?.(finalResult);
+            },
+            onChunk: (event) => {
+                if (!isCurrent()) {
+                    return;
+                }
+                return options.onChunk?.(event);
+            },
+        });
+    }
+    /**
+     * Record the metric + structured warning for an attempt that ended with one
+     * or more unusable tool calls. Called at the terminal finish chunk so the
+     * signal is captured whether or not the orchestrator goes on to retry.
+     */
+    logEmptyToolCalls(session, tracker) {
+        recordEmptyToolCalls(session.provider.name, session.provider.model, tracker.pendingCount);
+        this.noteStreamDegradation("empty_tool_call");
+        const attributes = {
+            event: "empty_tool_call",
+            empty_tool_call_count: tracker.pendingCount,
+            model: session.provider.model,
+            provider: session.provider.name,
+            tool_names: tracker.toolNames.join(","),
+            ...degradationKeyLogAttribute(this.degradationKey),
+        };
+        if (tracker.finishReason) {
+            attributes.finish_reason = tracker.finishReason;
+        }
+        if (typeof tracker.rawFinishReason === "string") {
+            attributes.raw_finish_reason = tracker.rawFinishReason;
+        }
+        if (session.organizationId) {
+            attributes.organization_id = session.organizationId;
+        }
+        if (session.applicationId) {
+            attributes.application_id = session.applicationId;
+        }
+        if (this.logger.warnStructured) {
+            this.logger.warnStructured("[orchestrator] Tool call ended without usable input", attributes);
+        }
+        else {
+            this.logger.warn("[orchestrator] Tool call ended without usable input", attributes);
+        }
+    }
+    /**
+     * Wraps each tool's execute so only the live attempt can run it. The Vercel AI
+     * SDK auto-executes tools as their calls arrive on the provider stream, and a
+     * superseded attempt's stream can still deliver buffered tool calls after we
+     * abort it. Throwing AbortedError here ensures a terminal tool's real side
+     * effect (e.g. build_finalize) runs once, for the winning attempt only.
+     */
+    guardToolsForAttempt(tools, isCurrent, getStepNumber) {
+        if (!tools) {
+            return tools;
+        }
+        const guarded = {};
+        for (const [name, tool] of Object.entries(tools)) {
+            if (typeof tool?.execute !== "function") {
+                guarded[name] = tool;
+                continue;
+            }
+            const execute = tool.execute.bind(tool);
+            guarded[name] = {
+                ...tool,
+                execute: async (input, executeOptions) => {
+                    if (!isCurrent()) {
+                        throw new AbortedError();
+                    }
+                    return executeToolWithTimeout(name, tool, execute, input, executeOptions, this.logger, getStepNumber, this.degradationKey);
+                },
+            };
+        }
+        // Each entry preserves the original tool (`...tool`) and only wraps
+        // `execute`, so the runtime shape still matches TOOLS; signal the deliberate
+        // widening so a reviewer doesn't read this as a checked narrowing.
+        return guarded;
+    }
+    applyProvider(options, provider, session) {
+        const baseOptions = this.config.fallback.enabled
+            ? {
+                ...options,
+                providerOptions: {
+                    ...options.providerOptions,
+                    unified: {
+                        ...(options.providerOptions?.unified ?? {}),
+                        forceProvider: provider.name,
+                        coreModel: provider.model,
+                    },
+                },
+            }
+            : options;
+        // The caller builds the initial providerOptions from the initial model.
+        // On retries, `provider.model` may have swapped (e.g. opus-4-7 →
+        // sonnet-4-6) and the thinking shape has to swap with it — `opus-4-7`
+        // rejects `thinking: { type: "enabled" }` while other models don't
+        // accept `output_config.effort`. Rebuild the thinking-related fields
+        // from the current model so every attempt emits an accepted shape.
+        const thinkingRebuilt = this.rebuildThinkingOptions(baseOptions, provider);
+        return {
+            ...thinkingRebuilt,
+            // `thinkingRebuilt.headers` is already authoritative for the
+            // interleaved-thinking beta header. Don't re-merge `options.headers`
+            // here or a disabled/adaptive rebuild would re-introduce the stale beta.
+            headers: {
+                ...thinkingRebuilt.headers,
+                // Stamp the per-attempt stream identity so the server proxy can join
+                // its egress frame counts to this stream's client-side stream_stall
+                // event. The value is the same session.id the stall event logs as
+                // `session_id`; the proxy logs it as `stream_id` (the server log
+                // pipeline redacts any field whose name contains "session", so the
+                // proxy cannot reuse the `session_id` name). That join is what lets a
+                // sampled stall be decided as upstream-silent (proxy wrote nothing) vs
+                // proxy->client drop (proxy wrote frames the client never saw). Rides
+                // the existing x-superblocks-* header path.
+                "x-superblocks-stream-id": session.id,
+                "x-superblocks-stream-attempt": String(session.attempt),
+            },
+            providerOptions: {
+                ...thinkingRebuilt.providerOptions,
+                billing: {
+                    retry_count: session.metrics.retryCount,
+                    workflow_failed: session.outcome === "error",
+                },
+            },
+        };
+    }
+    /**
+     * Replaces the thinking-related fields on `providerOptions.anthropic` and
+     * `providerOptions.bedrock.additionalModelRequestFields` with the shape
+     * the given model accepts. Any stale thinking keys (e.g. `budgetTokens`
+     * from a previous opus-4-6 attempt, or `effort` from a previous 4-7
+     * attempt) are dropped so the new shape isn't polluted.
+     */
+    rebuildThinkingOptions(options, provider) {
+        const thinkingConfig = this.config.thinking;
+        if (!thinkingConfig) {
+            return options;
+        }
+        const fresh = buildThinkingProviderOptions(provider.model, {
+            thinkingEnabled: thinkingConfig.enabled,
+            thinkingBudgetTokens: thinkingConfig.budgetTokens,
+            interleavedThinking: thinkingConfig.interleaved,
+        });
+        const existing = options.providerOptions ?? {};
+        const existingAnthropic = existing.anthropic ?? {};
+        const existingBedrock = existing.bedrock ?? {};
+        const existingBedrockFields = existingBedrock.additionalModelRequestFields ?? {};
+        const { thinking: _a, effort: _b, ...anthropicRest } = existingAnthropic;
+        const { thinking: _c, output_config: _d, anthropic_beta: _e, budget_tokens: _f, ...bedrockFieldsRest } = existingBedrockFields;
+        // `buildThinkingProviderOptions` is the sole source of the
+        // interleaved-thinking `anthropic-beta` HTTP header. Strip any stale value
+        // before applying the fresh headers so a disabled or adaptive-effort
+        // rebuild (both emit no header) stops advertising the beta.
+        const { "anthropic-beta": _staleBeta, ...headersWithoutThinkingBeta } = options.headers ?? {};
+        const anthropic = fresh.anthropic
+            ? { ...anthropicRest, ...fresh.anthropic }
+            : anthropicRest;
+        const bedrock = fresh.bedrock
+            ? {
+                ...existingBedrock,
+                additionalModelRequestFields: {
+                    ...bedrockFieldsRest,
+                    ...fresh.bedrock.additionalModelRequestFields,
+                },
+            }
+            : Object.keys(bedrockFieldsRest).length > 0
+                ? {
+                    ...existingBedrock,
+                    additionalModelRequestFields: bedrockFieldsRest,
+                }
+                : { ...existingBedrock, additionalModelRequestFields: {} };
+        return {
+            ...options,
+            headers: { ...headersWithoutThinkingBeta, ...fresh.headers },
+            providerOptions: {
+                ...existing,
+                anthropic: anthropic,
+                bedrock: bedrock,
+            },
+        };
+    }
+    getFallbackReason(error) {
+        if (error && typeof error === "object" && "type" in error) {
+            const errorType = error.type;
+            if (errorType === "no_output")
+                return "no_output";
+        }
+        return "error";
+    }
+    /**
+     * Switch the session to a fallback provider, emit the structured switch log,
+     * and fire the "fallback" event. `fastFallback` distinguishes the stall
+     * fast-fallback path (a stall left the provider early) from a normal
+     * provider-exhaustion fallback, surfaced as a queryable Datadog facet so the
+     * fast-fallback behavior is verifiable in production. Error context for the
+     * triggering error is carried by the retry log that follows this call.
+     */
+    async switchProvider(session, newProvider, fastFallback, error) {
+        const oldProvider = session.provider;
+        session.provider = newProvider;
+        session.hadProviderFallback = true;
+        const message = `[orchestrator] Switching provider: ${oldProvider.name}/${oldProvider.model} -> ` +
+            `${newProvider.name}/${newProvider.model}` +
+            (fastFallback ? " (stall fast-fallback)" : "");
+        const attributes = {
+            event: "provider_fallback",
+            session_id: session.id,
+            ...streamIdentityAttributes(session.id),
+            from_provider: oldProvider.name,
+            from_model: oldProvider.model,
+            to_provider: newProvider.name,
+            to_model: newProvider.model,
+            attempt: session.attempt,
+            fast_fallback: fastFallback,
+            error_kind: error instanceof Error ? error.name : "unknown",
+            ...degradationKeyLogAttribute(this.degradationKey),
+        };
+        if (this.logger.warnStructured) {
+            this.logger.warnStructured(message, attributes);
+        }
+        else {
+            this.logger.warn(message, attributes);
+        }
+        this.noteStreamDegradation("provider_fallback");
+        await session.events.emit("fallback", oldProvider, newProvider, this.getFallbackReason(error), session);
+    }
+    delay(ms, abortSignal) {
+        return new Promise((resolve) => {
+            if (abortSignal?.aborted) {
+                resolve();
+                return;
+            }
+            const timeoutId = setTimeout(resolve, ms);
+            abortSignal?.addEventListener("abort", () => {
+                clearTimeout(timeoutId);
+                resolve();
+            }, { once: true });
+        });
+    }
+}
+//# sourceMappingURL=orchestrator.js.map