@superblocksteam/vite-plugin-file-sync 2.0.130-next.1 → 2.0.130-next.3

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

@@ -1,11 +1,71 @@
 import { getErrorMeta, } from "../../../util/logger.js";
 import { buildThinkingProviderOptions } from "../../util/llm-config-utils.js";
 import { LLMProviderError } from "../error.js";
+import { getServerCompactionTextBlockUpdate } from "./compaction-text-block.js";
 import { AbortedError, RetriesExhaustedError } 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 { WaitStateTracker } from "./wait-state-tracker.js";
+/**
+ * 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.
  *
@@ -65,7 +125,11 @@ export class StreamOrchestrator {
             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();
@@ -88,28 +152,142 @@ export class StreamOrchestrator {
         internalAbortController.signal.addEventListener("abort", () => {
             void session.events.emit("session:abort", session);
         });
-        // Idle monitoring: aborts hung streams that stop sending chunks
+        // 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.idleTimeoutMs,
-            firstChunkTimeoutMs: this.config.retry.firstChunkTimeoutMs,
+            maxIdleTimeMs: () => this.config.retry.budgetForModel(session.provider.model).idleTimeoutMs,
+            firstChunkTimeoutMs: () => this.config.retry.budgetForModel(session.provider.model)
+                .firstChunkTimeoutMs,
             onServerCompactionStart: (blockId) => {
+                // firstChunkTimeoutMs is re-resolved here from the current model rather
+                // than read from the armed timer. The model only changes on fallback
+                // events (never mid-stream), so at compaction-start time it matches the
+                // budget the first-chunk timer was actually armed with.
                 this.logger.debug("[orchestrator] Server-side compaction chunk detected; holding first-chunk idle budget", {
                     sessionId: session.id,
                     provider: session.provider.name,
                     model: session.provider.model,
                     attempt: session.attempt,
                     blockId,
-                    firstChunkTimeoutMs: this.config.retry.firstChunkTimeoutMs,
+                    firstChunkTimeoutMs: this.config.retry.budgetForModel(session.provider.model).firstChunkTimeoutMs,
                 });
             },
+            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 message = `[orchestrator] Local wait suppressed idle stall`;
+                const attributes = {
+                    event: "stream_local_wait",
+                    session_id: session.id,
+                    provider: session.provider.name,
+                    model: session.provider.model,
+                    attempt: session.attempt,
+                    elapsed_ms: session.getElapsedMs(),
+                    chunks_received: session.metrics.chunkCount,
+                    // "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: waitState.state === "provider" ? "consumer" : waitState.state,
+                };
+                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 the keepalive-vs-content discriminator: "first-chunk"
                 // means the model never sent content (only silence/keep-alives) before
                 // the stall; "inter-chunk" means content was flowing and then stopped.
-                const budgetKind = error.maxIdleTimeMs === this.config.retry.firstChunkTimeoutMs
-                    ? "first-chunk"
-                    : "inter-chunk";
+                // It 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 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).
+                //
+                // A first-chunk stall is upstream silence by definition: no chunk was
+                // delivered, so the consumer cannot be holding the stream. Force
+                // "network-dark" rather than trusting the flag — pull() is lazy, so a
+                // first-chunk timer can fire before the loop's first await ever set it.
+                // budget_kind still separates a first-chunk network-dark from an
+                // inter-chunk one.
+                const stallReason = budgetKind === "first-chunk" || 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,
@@ -118,6 +296,14 @@ export class StreamOrchestrator {
                 // 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.
+                // 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 attributes = {
                     event: "stream_stall",
                     session_id: session.id,
@@ -129,7 +315,21 @@ export class StreamOrchestrator {
                     budget_ms: error.maxIdleTimeMs,
                     elapsed_ms: session.getElapsedMs(),
                     chunks_received: session.metrics.chunkCount,
+                    stall_reason: stallReason,
+                    wait_state: waitState.state,
+                    raw_reset_count: waitStateTracker.getRawResetCount(),
                 };
+                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) {
@@ -146,19 +346,67 @@ export class StreamOrchestrator {
                 }
             },
         });
-        const result = await this.startStreamWithRetry(optionsWithAbort, session, retryEngine);
+        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);
-        const retryableFullStream = this.wrapWithRetry(managedStream, (r) => createManagedStream(r.fullStream, session, idleMonitor), optionsWithAbort, session, retryEngine, internalAbortController);
+        const retryableFullStream = this.wrapWithRetry(managedStream, (r) => createManagedStream(r.fullStream, session, idleMonitor), optionsWithAbort, session, retryEngine, internalAbortController, attempts, waitStateTracker);
+        // `tee()` preserves the public contract that fullStream and textStream can
+        // be consumed independently; the slower branch may buffer response chunks.
+        const [fullStream, textSourceStream] = retryableFullStream.tee();
         return {
             ...result,
-            fullStream: retryableFullStream,
-            textStream: result.textStream,
+            fullStream: this.asAsyncIterableStream(fullStream),
+            textStream: this.textStreamFromFullStream(this.asAsyncIterableStream(textSourceStream)),
         };
     }
+    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();
+                }
+            },
+        });
+    }
+    textStreamFromFullStream(stream) {
+        const compactionTextBlockIds = new Set();
+        return this.asAsyncIterableStream(stream.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                const compactionBlock = getServerCompactionTextBlockUpdate(chunk);
+                if (compactionBlock.kind === "start") {
+                    compactionTextBlockIds.add(compactionBlock.id);
+                    return;
+                }
+                if (compactionBlock.kind === "part" &&
+                    compactionTextBlockIds.has(compactionBlock.id)) {
+                    if (compactionBlock.done) {
+                        compactionTextBlockIds.delete(compactionBlock.id);
+                    }
+                    return;
+                }
+                if (chunk.type === "text-delta") {
+                    controller.enqueue(chunk.text);
+                }
+            },
+        })));
+    }
     /**
      * 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
@@ -168,7 +416,7 @@ export class StreamOrchestrator {
      * retries will silently fail (the new stream will close immediately because
      * session.isPending() returns false).
      */
-    wrapWithRetry(initialStream, getNewStream, options, session, retryEngine, abortController) {
+    wrapWithRetry(initialStream, getNewStream, options, session, retryEngine, abortController, attempts, waitStateTracker) {
         const handleRetry = this.handleRetryDecision.bind(this);
         let currentStream = initialStream;
         async function* createRetryIterator() {
@@ -184,7 +432,7 @@ export class StreamOrchestrator {
                     return;
                 }
                 catch (error) {
-                    const retryResult = await handleRetry(error, options, session, retryEngine);
+                    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.
@@ -221,8 +469,8 @@ export class StreamOrchestrator {
      * 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) {
-        const decision = retryEngine.getRetryDecision(error, session, options.abortSignal);
+    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));
             session.finalize("error", error);
@@ -231,26 +479,26 @@ export class StreamOrchestrator {
                 error: this.wrapFinalError(error, decision.reason ?? "unknown", session),
             };
         }
+        // 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) {
-            const oldProvider = session.provider;
-            session.provider = decision.newProvider;
-            this.logger.warn(`[orchestrator] Switching provider: ${oldProvider.name}/${oldProvider.model} -> ${decision.newProvider.name}/${decision.newProvider.model}`, getErrorMeta(error));
-            await session.events.emit("fallback", oldProvider, decision.newProvider, this.getFallbackReason(error), session);
+            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})`, getErrorMeta(error));
+        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);
+        const newResult = await this.startStreamWithRetry(options, session, retryEngine, attempts, waitStateTracker);
         return { shouldRetry: true, newResult };
     }
-    async startStreamWithRetry(options, session, retryEngine) {
+    async startStreamWithRetry(options, session, retryEngine, attempts, waitStateTracker) {
         while (true) {
             try {
-                return await this.startStream(options, session);
+                return await this.startStream(options, session, attempts);
             }
             catch (error) {
-                const decision = retryEngine.getRetryDecision(error, session, options.abortSignal);
+                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: {
@@ -262,15 +510,14 @@ export class StreamOrchestrator {
                     await session.events.emit("session:error", error, session);
                     throw this.wrapFinalError(error, decision.reason ?? "unknown", session);
                 }
+                // Supersede the failed attempt before backoff.
+                attempts.abortCurrent();
                 await session.events.emit("retry", error, session.attempt, decision.delayMs, session);
                 if (decision.newProvider) {
-                    const oldProvider = session.provider;
-                    session.provider = decision.newProvider;
-                    this.logger.warn(`[orchestrator] Switching provider: ${oldProvider.name}/${oldProvider.model} -> ${decision.newProvider.name}/${decision.newProvider.model}`, getErrorMeta(error));
-                    await session.events.emit("fallback", oldProvider, decision.newProvider, this.getFallbackReason(error), session);
+                    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})`);
+                this.logger.info(`[orchestrator] Startup retry in ${decision.delayMs}ms (attempt ${session.attempt}) reason=${decision.reason ?? "retry"}`);
                 await this.delay(decision.delayMs, options.abortSignal);
             }
         }
@@ -293,15 +540,27 @@ export class StreamOrchestrator {
             cause: error,
         });
     }
-    async startStream(options, session) {
+    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),
             prepareStep: async (step) => {
+                if (!isCurrent()) {
+                    throw new AbortedError();
+                }
                 const preparedStep = (await options.prepareStep?.(step)) ?? step;
                 await session.events.emit("step:start", {
                     stepNumber: preparedStep.stepNumber,
@@ -310,17 +569,61 @@ export class StreamOrchestrator {
                 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: options.onChunk,
+            onChunk: (event) => {
+                if (!isCurrent()) {
+                    return;
+                }
+                return options.onChunk?.(event);
+            },
         });
     }
+    /**
+     * 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) {
+        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 execute(input, executeOptions);
+                },
+            };
+        }
+        // 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
             ? {
@@ -344,9 +647,22 @@ export class StreamOrchestrator {
         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: {
-                ...options.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,
@@ -380,6 +696,11 @@ export class StreamOrchestrator {
         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;
@@ -399,7 +720,7 @@ export class StreamOrchestrator {
                 : { ...existingBedrock, additionalModelRequestFields: {} };
         return {
             ...options,
-            headers: { ...options.headers, ...fresh.headers },
+            headers: { ...headersWithoutThinkingBeta, ...fresh.headers },
             providerOptions: {
                 ...existing,
                 anthropic: anthropic,
@@ -415,6 +736,39 @@ export class StreamOrchestrator {
         }
         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;
+        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,
+            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",
+        };
+        if (this.logger.warnStructured) {
+            this.logger.warnStructured(message, attributes);
+        }
+        else {
+            this.logger.warn(message, attributes);
+        }
+        await session.events.emit("fallback", oldProvider, newProvider, this.getFallbackReason(error), session);
+    }
     delay(ms, abortSignal) {
         return new Promise((resolve) => {
             if (abortSignal?.aborted) {