UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,534 lines • 86.9 kB
import type { AnthropicImageRecovery } from "../server/responses/image-context-recovery";
import { bindAnthropicRejectionResponse } from "../adapters/anthropic-rejection-memo";
import { anthropicDeclaredTools } from "../adapters/anthropic-tool-catalog";
import { enableAnthropicReplayCapture, takeAnthropicReplay, bindAnthropicReplay, type AnthropicReplaySnapshot } from "../adapters/anthropic-replay";
import { anthropicSearchAssistantContent } from "./anthropic-history";
import type { createAnthropicThinkingRecovery } from "../server/responses/anthropic-thinking-recovery";
import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "../adapters/base";
import type { AdapterEvent, OcxConfig, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxProviderOpaqueToolCallMetadata, OcxThinkingContent, OcxUsage, RateLimitRetryPolicy } from "../types";
import { namespacedToolName, toolChoiceToolPredicate } from "../types";
import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
import type { AttemptRecoveryKind } from "../usage/log";
import { isTruncatedStopReason } from "../responses/truncated-stop-reason";
import { bridgeToResponsesSSE } from "../bridge";
import { guardEmptyToolCatalogStream, type ClientToolCatalogRestriction } from "../lib/empty-tool-catalog";
import { emptyCompletionRetryFailedEvent, mergeUsage } from "../server/responses/empty-completion-guard";
import { analyzeTerminalTurn, buildContinuationRequest } from "../server/responses/terminal-guard";
import { withMissingCreditReading } from "../usage/credit-billing";
import { markSidecarContextOverflow, sidecarLoopTerminalEvent, upstreamErrorCode, type SidecarLoopFailure } from "../server/responses/context-overflow";
import { markVerifiedModelNotInPlanResponse, MODEL_NOT_IN_PLAN_CODE, UNDECLARED_TOOL_CALL_ERROR_CODE, verifiedPlanRefusalMessage } from "../lib/errors";
import { runWebSearch, type SidecarOutcome, type SidecarOutcomeRecorder, type SidecarSettings } from "./executor";
import { runAnthropicWebSearch } from "./anthropic-executor";
import type { AuxiliaryModelSend } from "../lib/request-execution-budget";
import { runXaiWebSearch, type XaiSearchOptions } from "./xai-executor";
import { runGeminiWebSearch } from "./gemini-executor";
import { runExaWebSearch } from "./exa-executor";
import type { WebSearchBackendId } from "./index";
import { pacingHeaderDeadline } from "./header-deadline";
import { redactSecretString } from "../lib/redact";
import { recordLocalFailureDetail, type FailureDetail } from "../server/request-log-failure-detail";
import { readBoundedResponseBody } from "../lib/bounded-body";
import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait, isNonReplayableResponse, isSameTargetRetryHold, RESET_RETRY_MAX_ATTEMPTS, SendBudgetExhaustedError } from "../lib/upstream-retry";
import { unwrapUpstreamRetryEvidenceError } from "../codex/auth-context";
import { HostedAdvisorSpendRefusal } from "../server/responses/policy-request-scope";
import { rateLimitRetryDelayMs } from "../providers/key-failover";
import { RequestPacingQueueOverloadError } from "../providers/request-pacing";
import {
  isTranslatorBudgetExceededError,
  TRANSLATOR_MAX_TURN_BYTES,
  TranslatorBudgetExceededError,
} from "../lib/translator-budget";
import { formatWebSearchResults } from "./format-result";
import { parseStreamWithProgress, withHeartbeats, RoutedModelInactivityError, WebSearchConsumerInactivityError, WebSearchStreamProtocolError, WebSearchAdapterEventError } from "./progress-stream";
import { WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
import { newSidecarSearchCellId, rememberSidecarSearch, restoreSidecarSearchResults } from "./sidecar-search-replay";
import {
  ADVISOR_TOOL_NAME,
  advisorToolAllowed,
  createAdvisorCallResolver,
  MAX_ADVISOR_CONTINUATIONS_PER_REQUEST,
  parseAdvisorQuestionArgs,
  type AdvisorSidecarStep,
} from "../server/responses/advisor-slot";

const SSE_HEADERS = {
  "Content-Type": "text/event-stream",
  "Cache-Control": "no-cache",
  "Connection": "keep-alive",
  "X-Accel-Buffering": "no",
};

interface WebSearchCall {
  id: string;
  kind?: "advisor";
  question?: string;
  // One or more queries the model batched into a single web_search call. Always length >= 0; an
  // empty array means the model called the tool with neither `query` nor `queries` (handled as an
  // empty-query placeholder).
  queries: string[];
  /**
   * Provider-opaque metadata from the originating part (issue #1735). Stored PER CALL so a
   * signature can never migrate to a different call when the model batches several.
   */
  providerMetadata?: OcxProviderOpaqueToolCallMetadata;
}

/**
 * Normalize a web_search tool call's raw JSON args into a canonical `queries[]`. Accepts native
 * plural `queries: string[]` or singular `query: string` (the model may send either). Non-string /
 * empty entries are dropped; malformed JSON yields `[]` (handled downstream as an empty-query call).
 */
function parseQueries(argsBuf: string): string[] {
  try {
    const o: unknown = JSON.parse(argsBuf || "{}");
    if (!o || typeof o !== "object") return [];
    const obj = o as { query?: unknown; queries?: unknown };
    if (Array.isArray(obj.queries)) {
      const qs = obj.queries.filter((q): q is string => typeof q === "string" && q.trim() !== "");
      if (qs.length > 0) return qs;
    }
    if (typeof obj.query === "string" && obj.query.trim() !== "") return [obj.query];
  } catch { /* malformed args → empty */ }
  return [];
}

/**
 * Split a non-streaming turn's adapter events into (a) the web_search calls to intercept and (b) the
 * events to pass through to Codex. A web_search tool-call's own start/delta/end events are dropped
 * (Codex never sees the synthetic tool); every other event — text, thinking, real tool calls, done —
 * is preserved in order.
 */
export function scanEventsForWebSearch(
  events: AdapterEvent[],
  resolveAdvisorCall: ReturnType<typeof createAdvisorCallResolver> = name => name === ADVISOR_TOOL_NAME ? "refused" : undefined,
): {
  calls: WebSearchCall[];
  passthrough: AdapterEvent[];
  hasRealToolCall: boolean;
  hasMalformedToolCall: boolean;
} {
  const calls: WebSearchCall[] = [];
  const passthrough: AdapterEvent[] = [];
  let hasRealToolCall = false;
  let hasMalformedToolCall = false;
  let refusal: Extract<AdapterEvent, { type: "error" }> | undefined;
  let pending: { name: string; id: string; argsBuf: string; closed: boolean; advisor: boolean; events: AdapterEvent[]; providerMetadata?: OcxProviderOpaqueToolCallMetadata } | null = null;
  const isBlank = (value: string): boolean => value.trim().length === 0;
  const flushPending = (): void => {
    // A pending call that never saw tool_call_end is structurally malformed.
    if (pending && !pending.closed) hasMalformedToolCall = true;
    if (pending && pending.name !== WEB_SEARCH_TOOL_NAME && !pending.advisor) {
      passthrough.push(...pending.events);
      if (pending.closed && !isBlank(pending.id) && !isBlank(pending.name)) hasRealToolCall = true;
    }
    pending = null;
  };
  for (const e of events) {
    if (refusal) {
      if ((e.type === "done" || e.type === "incomplete" || e.type === "error") && e.usage) refusal.usage = e.usage;
      continue;
    }
    if (e.type === "tool_call_start") {
      flushPending();
      const disposition = resolveAdvisorCall(e.name);
      if (disposition === "refused") {
        refusal = { type: "error", status: 502, errorType: "upstream_error", code: UNDECLARED_TOOL_CALL_ERROR_CODE,
          message: "routed provider emitted advisor outside the current iteration's permitted tool catalog" };
        passthrough.push(refusal);
        continue;
      }
      if (isBlank(e.id) || isBlank(e.name)) hasMalformedToolCall = true;
      const start = typeof disposition === "object" && disposition.clientWireName !== e.name
        ? { ...e, name: disposition.clientWireName } : e;
      pending = { name: start.name, id: e.id, argsBuf: "", closed: false, advisor: disposition === "synthetic", events: [start], providerMetadata: e.providerMetadata };
    } else if (e.type === "tool_call_delta") {
      // Orphan delta (no open call) is malformed.
      if (!pending) hasMalformedToolCall = true;
      else {
        pending.argsBuf += e.arguments;
        pending.events.push(e);
      }
    } else if (e.type === "tool_call_end") {
      // Orphan end (no open call) is malformed.
      if (!pending) {
        hasMalformedToolCall = true;
      } else {
        pending.events.push(e);
        pending.closed = true;
        if (e.incomplete) {
          hasMalformedToolCall = true;
          if (!pending.advisor) passthrough.push(...pending.events);
        } else if (pending.name === WEB_SEARCH_TOOL_NAME) {
          calls.push({ id: pending.id, queries: parseQueries(pending.argsBuf), providerMetadata: pending.providerMetadata });
        } else if (pending.advisor) {
          calls.push({
            id: pending.id,
            kind: "advisor",
            queries: [],
            question: parseAdvisorQuestionArgs(pending.argsBuf).question,
            providerMetadata: pending.providerMetadata,
          });
        } else {
          passthrough.push(...pending.events);
          if (!isBlank(pending.id) && !isBlank(pending.name)) hasRealToolCall = true;
        }
        pending = null;
      }
    } else {
      passthrough.push(e);
    }
  }
  flushPending();
  return { calls, passthrough, hasRealToolCall, hasMalformedToolCall };
}

/**
 * Visible final-answer text: a non-whitespace text_delta that is NOT commentary
 * (#1001). Commentary streams early for progress and must not satisfy the
 * forced-answer output check; thinking alone never counts either.
 */
export function hasVisibleAssistantText(events: AdapterEvent[]): boolean {
  return events.some(event =>
    event.type === "text_delta"
    && event.phase !== "commentary"
    && event.text.trim().length > 0);
}

async function* replay(events: AdapterEvent[]): AsyncGenerator<AdapterEvent> {
  for (const e of events) yield e;
}

function terminalUsage(events: AdapterEvent[]): OcxUsage | undefined {
  for (const e of events) if (e.type === "done" || e.type === "incomplete") return e.usage;
  return undefined;
}

/** Hidden iterations add counters only: their checkpoint and raw wire usage are not the final terminal's. */
function countersOnly(usage: OcxUsage | undefined): OcxUsage | undefined {
  if (!usage) return undefined;
  const { contextTotalTokens: _context, rawUsage: _raw, ...counters } = usage;
  return counters;
}

function withTerminalUsageMetadata(cumulative: OcxUsage, terminal: OcxUsage | undefined): OcxUsage {
  const { contextTotalTokens: _context, rawUsage: _raw, ...counters } = cumulative;
  return {
    ...counters,
    ...(terminal?.contextTotalTokens !== undefined ? { contextTotalTokens: terminal.contextTotalTokens } : {}),
    ...(terminal?.rawUsage !== undefined ? { rawUsage: terminal.rawUsage } : {}),
  };
}

/**
 * Collect the thinking block that preceded a web_search call in this iteration's events, so the
 * replayed assistant turn can carry it. Anthropic extended thinking REQUIRES the assistant
 * message that contains tool_use to start with its signed thinking/redacted_thinking blocks —
 * replaying a bare toolCall 400s ("Expected `thinking` or `redacted_thinking`, but found
 * `tool_use`"). The signature validity gate stays in the anthropic adapter; other adapters
 * ignore or serialize the part harmlessly.
 *
 * Each signed block keeps its OWN signature and text, mirroring src/images/loop.ts: a signature
 * authenticates the exact block it closed, so flattening two blocks under the last signature
 * 400s on replay just as it does there.
 *
 * Raw reasoning (`reasoning_raw_delta`, what OpenAI-compatible providers emit instead of signed
 * thinking) accumulates into a SEPARATE UNSIGNED part. It must never join a signed block: the
 * anthropic serializer skips signature-less parts, while openai-chat serializes their text as
 * `reasoning_content` — which DeepSeek V4 thinking mode requires back alongside the replayed
 * tool_calls, and whose absence ended the turn as a provider 400 (issue #688).
 *
 * This assumes raw reasoning never interleaves INSIDE an unfinished signed block: Anthropic-family
 * adapters emit thinking_delta/signature and OpenAI-compatible ones emit reasoning_raw_delta, and
 * the two never share a stream. Honoring a genuinely mixed stream would need per-segment state,
 * not another accumulator.
 */
function extractIterationThinking(events: AdapterEvent[]): OcxThinkingContent[] {
  const parts: OcxThinkingContent[] = [];
  let thinking = "";
  let signature: string | undefined;
  let rawReasoning = "";

  const flushVisible = () => {
    if (!thinking && !signature) return;
    parts.push({
      type: "thinking",
      thinking,
      ...(signature ? { signature } : {}),
    });
    thinking = "";
    signature = undefined;
  };
  const flushRaw = () => {
    if (!rawReasoning) return;
    parts.push({ type: "thinking", thinking: rawReasoning });
    rawReasoning = "";
  };

  for (const e of events) {
    // Match the bridge: consecutive signature snapshots update one block. The next
    // semantic event (including an empty thinking-block start) closes that block.
    if (signature !== undefined && e.type !== "thinking_signature" && e.type !== "heartbeat") flushVisible();
    if (e.type === "text_delta" && e.anthropicThinkingSignature) {
      flushVisible();
      flushRaw();
      parts.push({ type: "thinking", thinking: e.text, signature: e.anthropicThinkingSignature });
    } else if (e.type === "thinking_delta") {
      flushRaw();
      thinking += e.thinking;
    } else if (e.type === "reasoning_raw_delta") {
      flushVisible();
      rawReasoning += e.text;
    } else if (e.type === "thinking_signature") {
      signature = e.signature;
    } else if (e.type === "redacted_thinking") {
      flushVisible();
      flushRaw();
      parts.push({ type: "thinking", thinking: "", redacted: [e.data] });
    }
  }
  flushVisible();
  flushRaw();
  return parts;
}

/** Normalize a query for failed-query de-duplication (case/whitespace-insensitive). */
function normalizeQuery(q: string): string {
  return q.trim().toLowerCase().replace(/\s+/g, " ");
}

/**
 * Developer nudge for the forced-answer pass. Anthropic keeps its first sent position in the
 * request-local history; other providers append it only for that iteration. It tells the model to ground its final answer in the web results already
 * gathered this turn. Citation wording is conditional — a failed/empty search still wants an answer,
 * just without fabricated sources.
 */
function forcedAnswerNudge(): OcxMessage {
  return {
    role: "developer",
    content:
      "Answer the user's question now using the web search results already gathered above. " +
      "Ground your answer in what those results actually say, and reference the relevant sources " +
      "when they are available. Do not claim you lack information that the results contain, and do " +
      "not invent sources that were not returned.",
    timestamp: Date.now(),
  };
}

/**
 * Developer nudge for the ONE recovery pass after an empty forced answer. Tool calls are disabled;
 * Anthropic retains its declared catalog and this nudge in request-local history for prefix fidelity.
 */
function forcedAnswerRetryNudge(): OcxMessage {
  return {
    role: "developer",
    content:
      "Your previous response contained no usable answer. Web search has finished for this turn and " +
      "no tools are available for this response. Answer the user's question now in assistant text, " +
      "using the web search results already gathered above. If those results are insufficient, say " +
      "what is missing instead of returning an empty response.",
    timestamp: Date.now(),
  };
}

function jsonError(status: number, message: string, event?: Extract<AdapterEvent, { type: "error" }>): Response {
  return new Response(JSON.stringify({ error: { message, type: event?.errorType ?? "upstream_error", code: event?.code ?? null, ...(event?.retryable === false ? { retryable: false } : {}) } }), {
    status,
    headers: { "Content-Type": "application/json", ...(event?.retryable === false ? { "x-should-retry": "false" } : {}) },
  });
}

/** Hard provider/parse failure inside an iteration. The eager first iteration converts it to a
 *  non-200 jsonError; later (already-streaming) iterations surface it as an in-stream error event. */
class LoopError extends Error {
  constructor(
    readonly status: number,
    message: string,
    readonly event?: Extract<AdapterEvent, { type: "error" }>,
    readonly detail?: Pick<SidecarLoopFailure, "upstreamCode" | "nonReplayable" | "verifiedPlanRefusal">,
    /** A deadline this proxy enforced; logged as local failure detail, never as upstream evidence. */
    readonly localFailure?: FailureDetail,
  ) {
    super(message);
    this.name = "LoopError";
  }
}

/** The response-header deadline verdict; the wire status and text are the pre-existing ones. */
function headerDeadlineError(connectTimeoutMs: number): LoopError {
  return new LoopError(504, `Provider response-header timeout after ${connectTimeoutMs}ms during web-search`,
    undefined, undefined, { code: "header_timeout", value: connectTimeoutMs });
}

function loopFailure(e: LoopError): SidecarLoopFailure {
  return { status: e.status, message: e.message, ...(e.event ? { event: e.event } : {}), ...e.detail };
}

/**
 * Dependencies for one web-search loop iteration: parsed request, active adapter,
 * incoming metadata, and the configured search executor.
 */
export interface WebSearchLoopDeps {
  parsed: OcxParsedRequest;
  /** The global emptyCompletionRetry opt-in; the loop applies it only to final openai-chat iterations. */
  emptyCompletionRetry?: boolean;
  terminalContinuationGuard?: boolean;
  advisor?: AdvisorSidecarStep;
  /** Chat delivery only; never copied into parsed generation options. */
  chatRawReasoningVisible?: boolean;
  clientToolCatalogRestriction?: ClientToolCatalogRestriction;
  adapter: ProviderAdapter;
  incomingMeta: IncomingMeta;
  /**
   * Which executor runs searches. Defaults to "openai" so existing callers keep the ChatGPT path
   * (audit F4). The widened ids (xai/gemini/exa) cannot reach the loop yet: planWebSearch returns
   * no plan for them (inert 060 arms), and the dispatch below only branches on "anthropic".
   */
  backend?: WebSearchBackendId;
  /** Required for the openai backend; unused (and typically undefined) for the anthropic backend. */
  forwardProvider?: OcxProviderConfig;
  /** Required for the anthropic backend: the stored-OAuth provider that runs web_search_20250305. */
  anthropicSidecar?: { providerName: string; provider: OcxProviderConfig; config: OcxConfig };
  dispatchSidecarSend?: AuxiliaryModelSend;
  /** Required for the xai backend: the stored Grok OAuth provider (L7). */
  xaiSidecar?: { providerName: string; provider: OcxProviderConfig };
  /** Required for the gemini backend: the stored Antigravity CCA provider (L8). */
  geminiSidecar?: { providerName: string; provider: OcxProviderConfig };
  /** Required for the exa backend: the operator key, read from config at plan unpack (L9). */
  exaApiKey?: string;
  /** Opt-in x_search options for the xai backend. */
  xaiSearchOptions?: XaiSearchOptions;
  hostedTool: Record<string, unknown>;
  selectedForwardHeaders: Headers;
  settings: SidecarSettings;
  maxSearches: number;
  forceEmptyResponseId?: boolean;
  /** Responses inbound only: deliver a non-retryable upstream refusal as `response.failed`. */
  terminalRefusalAsFailed?: boolean;
  /** False for Chat/Messages inbound: their clients never parse `<oai-mem-citation>`, so text stays raw. */
  escapeMemoryCitationTags?: boolean;
  abortSignal?: AbortSignal;
  recordSidecarOutcome?: SidecarOutcomeRecorder;
  beforeSidecarDispatch?: () => void;
  /** Cumulative per-iteration deadline for DNS/TCP/TLS and final response headers only. */
  connectTimeoutMs?: number;
  /** Continuous routed-model response-body raw-byte inactivity deadline. Default 200000ms. */
  routedModelStallTimeoutMs?: number;
  /** Best-effort notification before publication. Observer exceptions leave the timeout response intact. */
  onLocalFailure?: () => void;
  /**
   * Effective bridge stall deadline for this turn (seconds). Computed by planWebSearch
   * (webSearchStallTimeoutSec) to cover response-header wait, routed-model body inactivity, and one
   * sidecar search, so a legitimately slow-but-progressing unit never trips the bridge watchdog.
   */
  stallTimeoutSec?: number;
  /**
   * Opt-in: stream the routed model's leading text/thinking deltas live instead of holding the whole
   * iteration back. The live window closes at the first buffer-only event (tool calls above all) so
   * the web_search interception decision stays atomic; everything after replays in order at the end.
   */
  streamRoutedModelOutput?: boolean;
  /** One-shot TTFT callback: first non-empty model output observed (WP4). */
  onFirstOutput?: () => void;
  /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
  onUsage?: (usage: OcxUsage | undefined) => void;
  proxyErrorContext?: object;
  /** Sizes the ingress-owned model-send allowance before the first dispatch. */
  configureModelSendAllowance?: (baseSends: number) => void;
  /**
   * After an `on429` rotation, offered the usage of the hidden iterations the left credential
   * served, including undefined when no usage arrived. Returning true hands off the old attempt,
   * so `onUsage` will not
   * report it again.
   */
  onRotatedUsage?: (usage: OcxUsage | undefined) => boolean;
  /** Observe the exact adapter request selected for each routed-model iteration. */
  onRequestBuilt?: (request: AdapterRequest) => void;
  /** Request-scoped executor retains the core's selection binding across loop retries. */
  thinkingRecovery?: ReturnType<typeof createAnthropicThinkingRecovery>;
  imageRecovery?: AnthropicImageRecovery;
  /** A receipt-aware executor calls onPhysicalDispatch after final local admission, once per send. */
  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest, adapter: ProviderAdapter,
    recovery: AttemptRecoveryKind | undefined, onPhysicalDispatch: () => void) =>
      typeof globalThis.fetch & { reportsPhysicalDispatch?: true };
  /** Observe finalized worker sends from both generic and adapter-owned transports. */
  onPhysicalSend?: IncomingMeta["onPhysicalSend"];
  /** Called before each routed-model dispatch in the loop, for attempt telemetry. Same-target 429 replays pass the `rate-limit-429` recovery kind. */
  onAttemptSend?: (recovery?: AttemptRecoveryKind) => void;
  /**
   * Account/key failover hook (429, plus provider-classified pre-output refusals): rotate the provider's active credential and return a rebuilt adapter,
   * or null when the pool is exhausted. Async hooks support OAuth refresh; existing synchronous
   * key-pool hooks remain valid.
   *
   * `responseHeaders` carries the whole refusal, not just Retry-After, because an Anthropic
   * 429 states the window's reset epoch even when it omits Retry-After -- and a rotation that
   * cannot see it cools the drained account for the short default instead of until the window
   * actually reopens. Optional so existing callers keep compiling.
   *
   * `retryParsed` is the exact iteration-local request the retry will be built from. The loop
   * sends a shallow copy of the outer parsed request, so a rotation that rebinds only the outer
   * object never reaches the wire. Optional so existing callers keep compiling.
   *
   * A rotation may cross ACCOUNTS, not just keys, and the attempt row is where an operator reads
   * which one happened. A rotator that knows which kind it performed returns it alongside the
   * adapter -- the same `{ adapter, recoveryKind }` shape `onCredentialError` already uses below.
   * The usage snapshot includes any dispatched refusal before this hook can seal the attempt.
   */
  on429?: (
    retryAfterHeader: string | null,
    responseHeaders?: Headers,
    retryParsed?: OcxParsedRequest,
    // A 403 requires this complete response; status-only callbacks retain 429 semantics.
    originalResponse?: Response,
    hiddenUsage?: OcxUsage,
  ) =>
    | { adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind }
    | null
    | Promise<{ adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind } | null>;
  /** Release a credential-hop permit if this iteration ended before the adapter used it. */
  onIterationEnd?: () => void;
  /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
  retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
  /** Called only when the final bridged Responses stream reaches completed or incomplete. */
  onCompletedResponse?: (response: Record<string, unknown>) => void;
}

/**
 * Run the main (non-OpenAI) model in a small agentic loop. Each upstream iteration is streamed and
 * fully buffered internally so raw byte progress is observable without leaking a synthetic tool or
 * preliminary assistant output. If the model invokes web_search, run it via the hosted sidecar,
 * inject the answer as a tool_result, and loop (bounded by `maxSearches`).
 */
export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Response> {
  const translatorBudget = deps.incomingMeta.translatorBudget;
  const routedProviderFetch = deps.incomingMeta.providerFetch ?? globalThis.fetch;
  const { parsed, selectedForwardHeaders, forwardProvider, hostedTool, settings, maxSearches, abortSignal, recordSidecarOutcome } = deps;
  const backend = deps.backend ?? "openai";
  const anthropicSidecar = deps.anthropicSidecar;
  // Mutable: 429 key-failover (deps.on429) can swap in a rebuilt adapter mid-loop.
  let adapter = deps.adapter;

  // Bridge stall budget (seconds of silence before upstream_stall_timeout); the retry backoff
  // heartbeat interval is derived from it so the watchdog is always fed during deliberate waits.
  const stallTimeoutMs = typeof deps.stallTimeoutSec === "number" && Number.isFinite(deps.stallTimeoutSec) && deps.stallTimeoutSec > 0
    ? Math.floor(deps.stallTimeoutSec * 1000)
    : 300_000;

  // Put recorded results back into replayed search pairs before the first iteration (#7269).
  restoreSidecarSearchResults(parsed);
  const messages: OcxMessage[] = [...parsed.context.messages];
  const replaySnapshots = new Set<AnthropicReplaySnapshot>();
  const loopT0 = Date.now();
  // A deadline this proxy enforced ends the turn: the row keeps its closed detail and the same text
  // is no longer read as upstream evidence. The context text is the one the wire carries, so the
  // status-derived error code and every retry decision read exactly what they read before.
  const recordLocalLoopFailure = (e: unknown): void => {
    if (!(e instanceof LoopError) || !e.localFailure || !deps.proxyErrorContext) return;
    recordLocalFailureDetail(deps.proxyErrorContext as { upstreamError?: string; failureDetail?: FailureDetail }, e.message, e.localFailure);
    try { deps.onLocalFailure?.(); } catch { /* Keep the original timeout response. */ }
  };
  let allTools = adapter.name === "anthropic" ? anthropicDeclaredTools(parsed) : parsed.context.tools ?? [];
  let activeToolChoice = parsed.options.toolChoice;
  let forcedNudgeAdded = false;
  let emptyNudgeAdded = false;
  let searchesExecuted = 0;
  let executedSearchCount = 0;
  // Queries whose search already failed this turn — repeats are short-circuited so a model that keeps
  // re-asking the same failing query doesn't burn the whole search budget on it.
  const failedQueries = new Set<string>();

  // Link an internal AbortController to the turn signal so a client cancel of the SSE body (bridge
  // `onCancel`) aborts in-flight model fetches AND the sidecar — the work now runs INSIDE the stream,
  // so without this a cancelled turn would leak fetches and keep draining tokens.
  const internalAbort = new AbortController();
  const linkAbort = (): void => internalAbort.abort(abortSignal?.reason);
  if (abortSignal) {
    if (abortSignal.aborted) linkAbort();
    else abortSignal.addEventListener("abort", linkAbort, { once: true });
  }
  const signal = internalAbort.signal;

  // Hard iteration bound (termination safety net); forceAnswer normally ends the loop sooner.
  // One iteration beyond the forced answer is reserved for its empty-answer recovery below.
  // Each authorized Chat recovery adds its own iteration. Ordinary iterations, including repeat
  // placeholders for a failed query, cannot use up either recovery's slot.
  const forcedAnswerRetries = 1;
  const HARD_CAP = maxSearches + 2 + forcedAnswerRetries + (deps.advisor ? MAX_ADVISOR_CONTINUATIONS_PER_REQUEST : 0);
  let emptyAnswerRetries = 0;
  let completionRetries = 0;
  let terminalContinuations = 0;
  let pendingContinuationMessages: OcxMessage[] | undefined;
  // Every iteration re-sends the full context, but only the last one's terminal reaches the bridge.
  // Search-calling passes and the discarded empty forced answer are summed here and added to what
  // onUsage reports, so the request log meters what was actually sent. The client-facing terminal
  // keeps the last iteration's usage: Codex and Claude Code size the context window from it, and
  // a sum would read as a context several times larger and trigger early auto-compaction.
  let hiddenUsage: OcxUsage | undefined;
  let hiddenLegs = 0;
  let pendingLegs = 0;
  let errorUsage: OcxUsage | undefined;
  const mergePendingUsage = (previous: OcxUsage | undefined, usage: OcxUsage | undefined): OcxUsage | undefined => {
    if (pendingLegs === 0) return previous;
    const reading = pendingLegs > 1 ? withMissingCreditReading(usage) : usage;
    return mergeUsage(previous, reading, hiddenLegs > 0);
  };
  const takeUsage = (usage: OcxUsage | undefined): void => {
    if (pendingLegs === 0) return;
    hiddenUsage = mergePendingUsage(countersOnly(hiddenUsage), usage);
    hiddenLegs += pendingLegs;
    pendingLegs = 0;
  };
  // After a terminal re-ask an incomplete or failed terminal carries the summed usage, like the
  // plain guard (#8877). Taking the final leg first leaves the bridge's onUsage one sum to report.
  const withReaskSum = (events: AdapterEvent[]): AdapterEvent[] => {
    if (terminalContinuations === 0) return events;
    const index = events.findIndex(event => event.type === "incomplete" || event.type === "error"
      || (event.type === "done" && isTruncatedStopReason(event.stopReason)));
    const terminal = events[index];
    if (terminal?.type !== "incomplete" && terminal?.type !== "error" && terminal?.type !== "done") return events;
    takeUsage(terminal.usage);
    if (!hiddenUsage) return events;
    const summed = [...events];
    summed[index] = { ...terminal, usage: withTerminalUsageMetadata(hiddenUsage, terminal.usage) };
    return summed;
  };
  let accountRefusalOutputStarted = false;
  const connectTimeoutMs = deps.connectTimeoutMs ?? 200_000;
  const routedModelStallTimeoutMs = deps.routedModelStallTimeoutMs ?? 200_000;

  interface IterationResponse {
    parsed: OcxParsedRequest;
    response: Response;
    responseAdapter: ProviderAdapter;
    resolveAdvisorCall: ReturnType<typeof createAdvisorCallResolver>;
    recover?: (error: WebSearchAdapterEventError) => Promise<IterationResponse | undefined>;
  }
  type IterationSplit = ReturnType<typeof scanEventsForWebSearch> & {
    events: AdapterEvent[];
    anthropicReplay?: AnthropicReplaySnapshot;
    /**
     * How many leading passthrough events were already delivered live this iteration. They are
     * exactly the first N passthrough entries (live delivery stops before the first event that
     * scanEventsForWebSearch could group or reorder), so the terminal replay skips them by count.
     */
    streamedPassthroughCount: number;
  };

  // Same-target 429 budget is per REQUEST, not per model iteration: later search rounds inherit
  // what earlier rounds left of `attempts`, so a bounded multi-round turn can never exceed the
  // configured replay count in total (a per-round reset would multiply it by maxSearches).
  const rateLimitRetryPolicy = deps.retryOn429Policy ?? null;
  let rateLimitRetries = 0;
  // The 429 ladder and thinking-signature recovery are request-scoped. Each
  // model dispatch can use its transport's full retry ladder.
  // An authorized Chat terminal re-ask is one more loop iteration (terminalContinuations in the
  // loop bound), so the default allowance funds it; explicit and Combo caps never expand.
  deps.configureModelSendAllowance?.((deps.adapter.hostedIterationSendLimit ?? RESET_RETRY_MAX_ATTEMPTS) * (
    HARD_CAP + Number(Boolean(deps.emptyCompletionRetry))
    + Number(deps.terminalContinuationGuard === true && deps.adapter.name === "openai-chat")
    + (rateLimitRetryPolicy?.attempts ?? 0) + Number(Boolean(deps.thinkingRecovery))
  ));

  const requireSuccessfulHeaders = async (prepared: IterationResponse): Promise<void> => {
    if (!prepared.response.ok) {
      if (deps.thinkingRecovery && prepared.responseAdapter.name === "anthropic") {
        const event = await deps.thinkingRecovery.projectHttpFailure(prepared.response, signal);
        throw new LoopError(event.status ?? prepared.response.status, event.message, event);
      }
      let body: Awaited<ReturnType<typeof readBoundedResponseBody>>;
      try {
        body = await readBoundedResponseBody(prepared.response, { signal });
      } catch {
        // The response status is authoritative even when its untrusted error body fails while
        // being read (including a synchronous getReader() failure). Never route that failure
        // through the adapter formatter or the generic transport error, which could expose its
        // raw message. A parent/client cancellation still owns the request lifecycle as 499.
        if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
        throw new LoopError(prepared.response.status, `Provider error ${prepared.response.status}`, undefined,
          { nonReplayable: isNonReplayableResponse(prepared.response) });
      }
      let formatted = "";
      let upstreamCode: string | undefined;
      if (body.displaySafe && !body.truncated && body.text.trim() && prepared.responseAdapter.formatErrorBody) {
        try {
          formatted = prepared.responseAdapter.formatErrorBody(
            prepared.response.status,
            prepared.response.headers,
            body.text,
          ).trim();
        } catch { /* formatter hooks are best-effort; unsafe raw text is never the fallback */ }
      }
      if (body.displaySafe && !body.truncated) upstreamCode = upstreamErrorCode(body.text);
      // A verified plan refusal keeps its fixed copy, code and provenance through this envelope, so a
      // combo or policy can still move past it; an unverified echo of the code stays an ordinary failure.
      const planMessage = body.displaySafe && !body.truncated ? verifiedPlanRefusalMessage(prepared.response, body.text) : undefined;
      if (planMessage !== undefined) {
        throw new LoopError(400, `Provider error 400: ${planMessage}`,
          { type: "error", status: 400, message: planMessage, errorType: "invalid_request_error", code: MODEL_NOT_IN_PLAN_CODE },
          { upstreamCode: MODEL_NOT_IN_PLAN_CODE, nonReplayable: isNonReplayableResponse(prepared.response), verifiedPlanRefusal: true });
      }
      const suffix = formatted ? `: ${formatted.slice(0, 400)}` : "";
      throw new LoopError(prepared.response.status, `Provider error ${prepared.response.status}${suffix}`, undefined,
        { upstreamCode, nonReplayable: isNonReplayableResponse(prepared.response) });
    }
  };

  // Acquire one iteration's final response headers. The first call is drained eagerly so an initial
  // connect/header/HTTP failure stays a non-2xx JSON response. Its successful BODY is deliberately
  // left unread until the downstream Responses SSE bridge exists.
  /**
   * Fetch one web-search iteration's final response headers, applying the response-header
   * deadline and the same-target 429 retry policy (with awaited body release and deadline
   * restart) before the `on429` key rotation.
   */
  const prepareIterationEvents = async function* (forceAnswer: boolean): AsyncGenerator<AdapterEvent, IterationResponse> {
    const recoveringEmptyAnswer = forceAnswer && emptyAnswerRetries > 0;
    const preserveAnthropicPrefix = adapter.name === "anthropic";
    let iterMessages = messages;
    if (preserveAnthropicPrefix) {
      // Once sent, each nudge is part of subsequent signatures' bound prefix. Keep its
      // original position even when a forced-answer response makes another tool call.
      if (forceAnswer && executedSearchCount > 0 && !forcedNudgeAdded) {
        const nudge = forcedAnswerNudge();
        if (nudge.role === "developer" && typeof nudge.content === "string") nudge.content = [{ type: "text", text: nudge.content }];
        messages.push(nudge); forcedNudgeAdded = true;
      }
      if (recoveringEmptyAnswer && !emptyNudgeAdded) {
        const nudge = forcedAnswerRetryNudge();
        if (nudge.role === "developer" && typeof nudge.content === "string") nudge.content = [{ type: "text", text: nudge.content }];
        messages.push(nudge); emptyNudgeAdded = true;
      }
    } else {
      if (forceAnswer && executedSearchCount > 0) iterMessages = [...messages, forcedAnswerNudge()];
      if (recoveringEmptyAnswer) iterMessages = [...iterMessages, forcedAnswerRetryNudge()];
    }
    if (pendingContinuationMessages) {
      iterMessages = [...iterMessages, ...pendingContinuationMessages];
      messages.push(...pendingContinuationMessages);
      pendingContinuationMessages = undefined;
    }
    const iterParsed: OcxParsedRequest = {
      ...parsed, stream: true,
      options: recoveringEmptyAnswer
        ? { ...parsed.options, toolChoice: "none" as const }
        : { ...parsed.options, toolChoice: activeToolChoice },
      context: { ...parsed.context, messages: iterMessages, tools: recoveringEmptyAnswer && !preserveAnthropicPrefix ? [] : allTools },
    };
    // One cumulative header deadline spans key rotations and reset sends, excluding local pacing.
    // clear() stops only its timer after final headers; the direct turn signal remains attached to
    // the returned response body through AbortSignal.any().
    let headerDeadline = pacingHeaderDeadline(connectTimeoutMs, signal);
    try {
      /**
       * Build and fetch one web-search iteration on the given adapter, under the iteration
       * header deadline. The caller owns same-target 429 replays and key rotation around it.
       * The outbound request is cached per adapter so a same-target replay reuses the EXACT
       * URL, serialized body, and headers (builder runs once per target sequence).
       */
      let cachedRequest: AdapterRequest | undefined;
      let cachedAdapter: ProviderAdapter | undefined;
      /**
       * Build and fetch one web-search iteration on the given adapter, under the iteration
       * header deadline. The caller owns same-target 429 replays and key rotation around it.
       */
      const fetchOnce = async (requestAdapter: ProviderAdapter, recovery?: AttemptRecoveryKind): Promise<IterationResponse> => {
        errorUsage = undefined;
        let request: AdapterRequest;
        if (cachedRequest !== undefined && cachedAdapter === requestAdapter) {
          request = cachedRequest;
        } else {
          request = await requestAdapter.buildRequest(iterParsed, {
            ...deps.incomingMeta,
            headers: selectedForwardHeaders,
            abortSignal: headerDeadline.signal,
            translatorBudget,
          });
          try {
            deps.onRequestBuilt?.(request);
          } catch {
            // Diagnostics are best-effort and must never abort a web-search iteration.
          }
          cachedRequest = request;
          cachedAdapter = requestAdapter;
        }
        let response: Response;
        let awaitingHeaders = true;
        let physicalSends = 0;
        let dispatchCandidate: { recovery?: AttemptRecoveryKind } | undefined;
        const onPhysicalDispatch = () => {
          if (!dispatchCandidate) return;
          const send = dispatchCandidate;
          dispatchCandidate = undefined;
          // An adapter-owned stream retry's usage is already combined by its parser.
          if (awaitingHeaders) pendingLegs++;
          const receipt = { ...send, ordinal: ++physicalSends };
          if (requestAdapter.fetchResponse) deps.incomingMeta.onPhysicalSend?.(receipt);
          deps.onPhysicalSend?.(receipt);
        };
        const routedExecutor = deps.fetchForRequest?.(request, iterParsed, requestAdapter, recovery, onPhysicalDispatch);
        const executor = routedExecutor ?? routedProviderFetch;
        const noteDispatchCandidate = (recovery?: AttemptRecoveryKind) => {
          dispatchCandidate = recovery ? { recovery } : {};
          if (!routedExecutor?.reportsPhysicalDispatch) onPhysicalDispatch();
        };
        try {
          if (requestAdapter.fetchResponse) {
            response = await requestAdapter.fetchResponse(request, {
              abortSignal: headerDeadline.signal,
              timeoutMs: connectTimeoutMs,
              returnRawErrors: true,
              stream: true,
              sendBudget: deps.incomingMeta.sendBudget,
              onPhysicalSend: send => {
                if (awaitingHeaders && send.ordinal === 1) deps.onAttemptSend?.(recovery);
                noteDispatchCandidate(send.recovery ?? recovery);
              },
              executor: headerDeadline.pacedFetch(executor),
              onRecoveryWithheld: deps.incomingMeta.onRecoveryWithheld,
            });
          } else {
            response = await fetchWithResetRetry(
              (retryRecovery) => {
                // Record every helper-driven send (the callback runs for the first attempt and
                // each connection-reset replay); preserve the caller's recovery kind
                // (rate-limit-429 / key-429) when the retry layer supplies none.
                const requestFetch = headerDeadline.pacedFetch(executor, () => {
                  const attemptRecovery = retryRecovery ?? recovery;
                  deps.onAttemptSend?.(attemptRecovery);
                  noteDispatchCandidate(attemptRecovery);
                });
                const h = new Headers(request.headers);
                if (!h.has("accept-encoding")) h.set("accept-encoding", "identity");
                // A connection-reset replay must leave the half-closed pooled socket, not just
                // ask politely: Bun has ignored a bare `Connection: close` (oven-sh/bun#20492),
                // so the transport-level `keepalive: false` this helper adds is what actually
                // opens a new connection. Spending `retryRecovery` on telemetry alone left every
                // replay on this leg eligible for the same dead socket the reset came from.
                return requestFetch(request.url, applyUpstreamRecoveryInit({
                  method: request.method,
                  redirect: "manual",
                  headers: h,
                  body: request.body,
                  signal: headerDeadline.signal,
                }, retryRecovery));
              },
              { replaySafe: true, abortSignal: headerDeadline.signal, label: "web-search-loop" },
            );
          }
        } finally {
          awaitingHeaders = false;
          request.releaseBodyObservation?.();
        }
        bindAnthropicRejectionResponse(request, response);
        const iterTools = iterParsed.context.tools ?? [];
        const declaredAdvisor = iterTools.find(tool => tool.advisor && tool.name === ADVISOR_TOOL_NAME);
        // Exhaustion removes the declaration, but its paired limit result still belongs
        // to the sidecar. A tools-disabled recovery revokes that permission too.
        const syntheticAdvisorAllowed = !!deps.advisor && !recoveringEmptyAnswer
          && (!!declaredAdvisor || deps.advisor.exhausted())
          && advisorToolAllowed(iterParsed, declaredAdvisor);
        return { parsed: iterParsed, response, responseAdapter: requestAdapter,
          resolveAdvisorCall: createAdvisorCallResolver(iterParsed, syntheticAdvisorAllowed, parsed.context.tools) };
      };

      const recover = async (error: WebSearchAdapterEventError): Promise<IterationResponse | undefined> => {
        if (signal.aborted || !error.replaySafe || isNonReplayableResponse(prepared.response)
          || !deps.thinkingRecovery?.prepareEvent(error.event.message, prepared.responseAdapter.name, iterParsed, prepared.response)) return;
        cachedRequest = undefined;
        cachedAdapter = undefined;
        // The successful headers ended the previous timer; the replacement owns a fresh deadline.
        headerDeadline = pacingHeaderDeadline(connectTimeoutMs, signal);
        try {
          const replacement = await fetchOnce(prepared.responseAdapter, "opaque-blob-rejection");
          headerDeadline.clear();
          await requireSuccessfulHeaders(replacement);
          return replacement;
        } catch (error) {
          if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
          if (headerDeadline.didExpire()) throw headerDeadlineError(connectTimeoutMs);
          const refusal = unwrapUpstreamRetryEvidenceError(error);
          if (refusal instanceof HostedAdvisorSpendRefusal) throw new LoopError(400, refusal.message, refusal.event());
          if (error instanceof LoopError || error instanceof SendBudgetExhaustedError || isTranslatorBudgetExceededError(error)) throw error;
          throw new LoopError(502, `Provider unreachable: ${error instanceof Error ? error.message : String(error)}`);
        } finally {
          headerDeadline.clear();
          deps.onIterationEnd?.();
        }
      };
      let prepared = await fetchOnce(adapter);
      // Same-target 429 wait-and-retry (opt-in `retryOn429`) BEFORE key rotation: a primary-key
      // rate-limit blip replays on the SAME key; rotation only runs after attempts exhaust.
      while (
        prepared.response.status === 429 && !isSameTargetRetryHold(prepared.response)
        && rateLimitRetryPolicy !== null
        && rateLimitRetries < rateLimitRetryPolicy.attempts
      ) {
        rateLimitRetries += 1;
        // Release unread body + heartbeat-fed wait via the shared same-target helper.
        const retryAfterHeader = prepared.response.headers.get("retry-after");
        // The old header deadline must not stay armed across the deliberate wait: clear it
        // before sleeping so a stale expiry can never race the client-cancel path.
        headerDeadline.clear();
        try {
          yield* prepareSameTarget429Wait({
            body: prepared.response.body,
            signal,
            delayMs: rateLimitRetryDelayMs(rateLimitRetryPolicy, retryAfterHeader, Date.now()),
            heartbeatIntervalMs: Math.min(10_000, Math.max(250, stallTimeoutMs / 2)),
          });
        } catch {
          throw new LoopError(499, "client closed request during web-search");
        }
        // Client cancellation wins over any stale-deadline edge: re-check before telemetry/replay.
        if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
        // The deliberate backoff must not consume the cumulative response-header deadline:
        // start a fresh one so the replay gets a new connect budget (504 stays reserved for real
        // upstream latency).
        headerDeadline = pacingHeaderDeadline(connectTimeoutMs, signal);
        // Stall-watchdog seam between bounded retry fetches.
        yield { type: "heartbeat" };
        prepared = await fetchOnce(adapter, "rate-limit-429");
      }
      // 429 key-failover parity with the normal routed path: rotate pool keys until one responds
      // or the pool is exhausted (deps.on429 returns null — cooldown map guarantees termination).
      while ((prepared.response.status === 429
        || (prepared.response.status === 401 && isAnthropicInstanceId(deps.incomingMeta?.providerName)
          && !accountRefusalOutputStarted)
        || (prepared.response.status === 403
          && (isAnthropicInstanceId(deps.incomingMeta?.providerName) || deps.incomingMeta?.providerName === "google-antigravity")
          && !accountRefusalOutputStarted)
        || (iterParsed._kiroAuthContext && (prepared.response.status === 400 || prepared.response.status === 403))) && deps.on429) {
        const refusalUsage = mergePendingUsage(countersOnly(hiddenUsage), undefined);
        const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers,
          iterParsed, prepared.response, refusalUsage);
        if (!rotated) break;
        takeUsage(undefined);
        if (hiddenLegs > 0 && deps.onRotatedUsage?.(hiddenUsage)) {
          hiddenUsage = undefined;
          hiddenLegs = 0;
        }
        const retainRefusal = prepared.response.status === 403
          && deps.incomingMeta?.providerName === "google-antigravity" && rotated.recoveryKind === "oauth-account-403";
        // Keep the bounded refusal readable until the sibling actually returns headers.
        // Other rotation paths retain their existing cancellation boundary.
        if (!retainRefusal) {
          try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
        }
        adapter = rotated.adapter;
        // Stall-watchdog seam between bounded retry fetches (audit 011 B3).
        yield { type: "heartbeat" };
        let replacement: IterationResponse;
        try {
          replacement = await fetchOnce(adapter, rotated.recoveryKind);
        } catch (error) {
          if (!retainRefusal || signal.aborted || headerDeadline.didExpire() || isTranslatorBudgetExceededError(error)) throw error;
          break; // Format the original 403 safely; replacement diagnostics are not client errors.
        }
        if (retainRefusal) {
          try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
        }
        prepared = replacement;
      }

      let imageReplacement: AdapterRequest | undefined;
      if (deps.imageRecovery && prepared.response.status === 413) {
        headerDeadline.clear();
        const recovered = yield* withHeartbeats(deps.imageRecovery(prepared.response, iterParsed, prepared.responseAdapter, signal), signal);
        prepared.response = recovered.response;
        imageReplacement = recovered.request;
        if (recovered.response.ok && imageReplacement) {
          messages.splice(0, messages.length, ...iterParsed.context.messages);
          parsed._anthropicImageOwner = iterParsed._anthropicImageOwner;
          cachedRequest = imageReplacement;
        }
      }
      if (!imageReplacement && await deps.thinkingRecovery?.prepareHttp(prepared.response, prepared.responseAdapter.name, iterParsed)) {
        try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* closed */ }
        cachedRequest = undefined;
        cachedAdapter = undefined;
        prepared = await fetchOnce(adapter, "opaque-blob-rejection");
      }


      // Final headers have arrived. Clear only the deadline timer before ANY body read.
      headerDeadline.clear();
      await requireSuccessfulHeaders(prepared);
      return { ...prepared, recover };
    } catch (error) {
      if (isTranslatorBudgetExceededError(error) || error instanceof SendBudgetExhaustedError) throw error;
      if (headerDeadline.didExpire()) throw headerDeadlineError(connectTimeoutMs);
      if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
      const refusal = unwrapUpstreamRetryEvidenceError(error);
      if (refusal instanceof HostedAdvisorSpendRefusal) throw new LoopError(400, refusal.message, refusal.event());
      if (error instanceof LoopError || error instanceof RequestPacingQueueOverloadError) throw error;
      throw new LoopError(502, `Provider unreachable: ${error instanceof Error ? error.message : String(error)}`);
    } finally {
      headerDeadline.clear();
      deps.onIterationEnd?.();
    }
  };

  const prepareIterationDrained = async (forceAnswer: boolean): Promise<IterationResponse> => {
    const it = prepareIterationEvents(forceAnswer);
    let r = await it.next();
    while (!r.done) r = await it.next();
    return r.value;
  };

  // Event types that may leave the live window before the first tool-call boundary: pure
  // text/thinking output the native (sidecar-less) path would deliver identically. Everything
  // else — tool calls above all, and any type scanEventsForWebSearch could group or a future
  // adapter could add — closes the window so live delivery can never reorder against the replay.
  const LIVE_STREAMABLE = new Set<AdapterEvent["type"]>([
    "text_delta", "thinking_delta", "reasoning_raw_delta",
    "thinking_signature", "redacted_thinking", "kiro_redacted_reasoning",
  ]);

  // Consume and validate one successful response body under a resettable raw-byte inactivity guard.
  // By default only invisible heartbeat events escape while semantic output remains buffered for
  // safe scanning; with `streamRoutedModelOutput` the leading text/thinking deltas stream live and
  // the live window closes permanently at the first buffer-only event (see LIVE_STREAMABLE).
  const consumeIterationEvents = async function* (prepared: IterationResponse): AsyncGenerator<AdapterEvent, IterationSplit> {
    const events: AdapterEvent[] = [];
    let liveWindowOpen = deps.streamRoutedModelOutput === true;
    let streamedPassthroughCount = 0;
    let anthropicReplay: AnthropicReplaySnapshot | undefined;
    let releaseCapture = () => {};
    try {
      const parse: ProviderAdapter["parseStream"] = (response, budget) => {
        if (prepared.responseAdapter.name === "anthropic") releaseCapture = enableAnthropicReplayCapture(response);
        return prepared.responseAdapter.parseStream(response, budget);
      };
      for await (const event of parseStreamWithProgress(prepared.response, parse, {
        signal,
        inactivityTimeoutMs: routedModelStallTimeoutMs,
        translatorBudget,
        preserveAdapterError: deps.thinkingRecovery !== undefined,
        // A pass that fails was still billed; the error path reports it with the hidden passes.
        onErrorUsage: usage => {
          errorUsage = usage;
          takeUsage(usage);
        },
      })) {
        if (event.type === "done") {
          anthropicReplay = takeAnthropicReplay(event);
          if (anthropicReplay) replaySnapshots.add(anthropicReplay);
        }
        if (event.type === "heartbeat") yield event;
        // Kiro's explicit-completion protocol marks ordinary assistant text as commentary while
        // it performs a bounded final-answer retry. That text is safe to surface immediately and
        // is exactly what the native Kiro transport streams. Keeping it in the search scanner made
        // Codex show only `Working` until both Kiro attempts had finished (often 30-40 seconds).
        // Tool events remain buffered below, so the decision to invoke the hosted sidecar is still
        // atomic and no search call can escape before its stream has validated successfully.
        else if (event.type === "text_delta" && event.phase === "commentary" && !event.anthropicThinkingSignature) { accountRefusalOutputStarted = true; yield event; }
        else if (liveWindowOpen && LIVE_STREAMABLE.has(event.type)) {
          // Live events are ALSO buffered: the scanner still needs them for thinking extraction
          // and the forced-answer output check; only the terminal replay skips them (by count).
          accountRefusalOutputStarted = true;
          yield event;
          streamedPassthroughCount++;
          events.push(event);
        } else {
          liveWindowOpen = false;
          events.push(event);
        }
      }
    } catch (error) {
      if (isTranslatorBudgetExceededError(error) || error instanceof SendBudgetExhaustedError) throw error;
      if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
      if (error instanceof WebSearchAdapterEventError) {
        const replacement = await prepared.recover?.(error);
        if (replacement) return yield* consumeIterationEvents(replacement);
        const event = isNonReplayableResponse(prepared.response)
          ? { ...error.event, message: "Provider stream error: upstream diagnostic withheld for a non-replayable failure", retryable: false as const }
          : error.event;
        throw new LoopError(event.status ?? 502, event.message, event);
      }
      if (error instanceof LoopError) throw error;
      if (error instanceof RoutedModelInactivityError) throw new LoopError(504, error.message, undefined, undefined,
        { code: "generation_timeout", value: error.timeoutMs });
      if (error instanceof WebSearchConsumerInactivityError) throw new LoopError(504, error.message, undefined, undefined,
        { code: "turn_inactivity", value: error.timeoutMs });
      if (error instanceof WebSearchStreamProtocolError) throw new LoopError(502, error.message);
      throw new LoopError(502, `Provider stream error: ${error instanceof Error ? error.message : String(error)}`);
    } finally { releaseCapture(); }

    const terminalIndexes = events.flatMap((event, index) =>
      event.type === "done" || event.type === "incomplete" || event.type === "error" ? [index] : []);
    if (terminalIndexes.length !== 1 || terminalIndexes[0] !== events.length - 1) {
      throw new LoopError(502, `Web-search adapter stream protocol error: expected one final terminal event, received ${terminalIndexes.length}`);
    }
    const terminal = events[terminalIndexes[0]!];
    if (terminal.type === "error") {
      if (terminal.code === "translation_buffer_limit") {
        throw new TranslatorBudgetExceededError("retained_collectors", TRANSLATOR_MAX_TURN_BYTES);
      }
      // Keep an adapter's own overflow verdict; every other terminal stays a generic 502.
      throw new LoopError(502, terminal.message, terminal.code === "context_length_exceeded" ? terminal : undefined);
    }
    deps.thinkingRecovery?.observeIteration(events);
    return { ...scanEventsForWebSearch(events, prepared.resolveAdvisorCall), streamedPassthroughCount, events, anthropicReplay };
  };

  /**
   * Consults through the shared Advisor step and appends the paired result to the worker history.
   * The synthetic call stays private, and the loop's abort signal prevents a cancelled result from
   * being replayed. Anthropic reuses its lossless assistant message instead of appending another.
   */
  async function* runAdvisorCall(call: WebSearchCall, precedingThinking: OcxThinkingContent[], appendAssistant: boolean): AsyncGenerator<AdapterEvent> {
    const advisor = deps.advisor;
    if (!advisor) throw new LoopError(502, "advisor call arrived without an advisor sidecar");
    if (appendAssistant) messages.push({
      role: "assistant",
      content: [
        ...precedingThinking,
        {
          type: "toolCall" as const,
          id: call.id,
          name: ADVISOR_TOOL_NAME,
          arguments: call.question === undefined ? {} : { question: call.question },
          ...(cloneProviderOpaqueToolCallMetadata(call.providerMetadata)
            ? { providerMetadata: cloneProviderOpaqueToolCallMetadata(call.providerMetadata) }
            : {}),
        },
      ],
      timestamp: Date.now(),
    });
    const consultParsed: OcxParsedRequest = {
      ...parsed,
      context: { ...parsed.context, messages },
    };
    const consulted = yield* withHeartbeats(advisor.consultCall(
      consultParsed,
      { ...call, name: ADVISOR_TOOL_NAME },
      signal,
    ));
    if (signal.aborted) throw new LoopError(499, "client closed request during advisor consultation");
    messages.push(consulted.message);
    if (advisor.exhausted()) {
      allTools = allTools.filter(tool => !tool.advisor && tool.name !== ADVISOR_TOOL_NAME);
      if ((typeof activeToolChoice === "object" && activeToolChoice !== null
        && "name" in activeToolChoice && activeToolChoice.name === ADVISOR_TOOL_NAME)
        || (activeToolChoice === "required" && allTools.length === 0)) activeToolChoice = "auto";
    }
  }

  // Execute one model-requested web_search call. The call may batch several queries (native
  // `action.search.queries`); each query runs as its own sidecar search (budget-aware), but they are
  // paired as ONE assistant toolCall + ONE aggregated toolResult so function-call pairing stays
  // valid, and surface as ONE search cell carrying every attempted query. A real search (one that
  // hits the sidecar) shows the spinner WHILE the batch runs. Empty/limit/repeat placeholders never
  // emit a cell (matching the prior single-query behavior).
  async function* runSearchCall(call: WebSearchCall, precedingThinking: OcxThinkingContent[] = [], appendAssistant = true): AsyncGenerator<AdapterEvent> {
    const results: { query: string; outcome: SidecarOutcome }[] = [];
    let beganCell = false;
    const cellItemId = newSidecarSearchCellId();
    if (call.queries.length === 0) {
      // The model called web_search with neither query nor queries — count it against the budget
      // (loop-bounding) exactly as the old empty-query placeholder did, but emit no cell.
      searchesExecuted++;
      results.push({ query: "", outcome: { text: "", sources: [], error: "the model called web_search with an empty query" } });
    }
    for (const query of call.queries) {
      // Stall-watchdog seam: batched queries run sequentially inside ONE begin/end cell, and
      // placeholder outcomes (repeat/limit) emit no cell at all — without this, consecutive
      // bounded units chain into one silent span past the stall deadline (audit 011 B1).
      yield { type: "heartbeat" };
      let outcome: SidecarOutcome;
      if (failedQueries.has(normalizeQuery(query))) {
        // Already failed this turn — don't spend another real search on it.
        outcome = { text: "", sources: [], error: "this query already failed earlier in the turn — do not call web_search again for it; answer from existing context" };
      } else if (searchesExecuted >= maxSearches) {
        outcome = { text: "", sources: [], error: "web search limit reached for this turn — answer from results already gathered" };
      } else {
        // Real sidecar search. Open the cell once, before the first real query runs.
        if (!beganCell) {
          beganCell = true;
          yield { type: "web_search_call_begin", id: call.id, itemId: cellItemId };
        }
        // F5: the anthropic sidecar authenticates with its own stored OAuth — it never touches the
        // ChatGPT forward headers and must NOT record a Codex/OpenAI pool outcome.
        // #398: the executors are "never throws", but enforce the contract defensively so a future
        // throw degrades to a failed tool result instead of aborting the whole turn. A genuine
        // parent abort MUST stay 499 — the executors catch abort and RETURN {error}, so check
        // signal.aborted both after the await and in the catch (a fulfilled {error} on an aborted
        // signal would otherwise look like an ordinary degradable failure).
        try {
          if (backend === "anthropic" && anthropicSidecar) {
            outcome = await runAnthropicWebSearch(query, anthropicSidecar.providerName, anthropicSidecar.provider, settings, signal, anthropicSidecar.config, deps.dispatchSidecarSend);
          } else if (backend === "xai") {
            // L7: stored Grok OAuth to the pinned api.x.ai Responses endpoint; same
            // never-throws contract and no Codex/OpenAI pool outcome recording (F5 parity).
            // A missing xaiSidecar is an invariant violation — fail CLOSED with an error
            // outcome rather than falling through to the forward-header OpenAI executor
            // (review High: that fallthrough would be credential-sensitive).
            outcome = deps.xaiSidecar
              ? await runXaiWebSearch(query, deps.xaiSidecar.providerName, deps.xaiSidecar.provider, settings, deps.xaiSearchOptions ?? {}, signal)
              : { text: "", sources: [], error: "xai backend selected without a resolved Grok OAuth provider" };
          } else if (backend === "gemini") {
            // L8: Antigravity CCA grounding; same fail-closed invariant stance as xai.
            outcome = deps.geminiSidecar
              ? await runGeminiWebSearch(query, deps.geminiSidecar.providerName, deps.geminiSidecar.provider, settings, signal)
              : { text: "", sources: [], error: "gemini backend selected without a resolved Antigravity provider" };
          } else if (backend === "exa") {
            // L9: non-LLM lane; key comes from the loop deps, never the plan. Fail closed.
            outcome = deps.exaApiKey
              ? await runExaWebSearch(query, deps.exaApiKey, settings, signal)
              : { text: "", sources: [], error: "exa backend selected without an exaApiKey" };
          } else {
            outcome = await runWebSearch(query, hostedTool, forwardProvider!, selectedForwardHeaders, settings, signal, recordSidecarOutcome, deps.beforeSidecarDispatch);
          }
          if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
        } catch (e) {
          if (e instanceof LoopError) throw e;
          if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
          // Unexpected executor throw: degrade this query to a failed tool result (redacted).
          outcome = { text: "", sources: [], error: `sidecar failed: ${redactSecretString(e instanceof Error ? e.message : String(e))}` };
        }
        searchesExecuted++;
        executedSearchCount++;
        if (outcome.error) failedQueries.add(normalizeQuery(query));
      }
      results.push({ query, outcome });
    }
    const now = Date.now();
    // Preserve the singular `{query}` arg shape for a single-query call (avoids prompt-history drift);
    // use `{queries}` only when the model actually batched several.
    const callArgs: Record<string, unknown> = call.queries.length > 1
      ? { queries: call.queries }
      : { query: call.queries[0] ?? "" };
    if (appendAssistant) messages.push({
      role: "assistant",
      content: [
        // Signed thinking must precede tool_use on replay (Anthropic extended thinking), and
        // unsigned raw reasoning has to ride along for providers that require it back (#688).
        ...precedingThinking,
        {
          type: "toolCall" as const,
          id: call.id,
          name: WEB_SEARCH_TOOL_NAME,
          arguments: callArgs,
          // Re-attach the signature to the rebuilt call so a sidecar turn keeps Gemini
          // reasoning continuity instead of relying on the same-process replay cache.
          ...(cloneProviderOpaqueToolCallMetadata(call.providerMetadata)
            ? { providerMetadata: cloneProviderOpaqueToolCallMetadata(call.providerMetadata) }
            : {}),
        },
      ],
      timestamp: now,
    });
    // One aggregated tool result. isError only when EVERY query failed (a partial success is usable).
    const allFailed = results.every(r => !!r.outcome.error);
    const resultText = formatWebSearchResults(results, !!parsed._structuredOutput);
    messages.push({
      role: "toolResult", toolCallId: call.id, toolName: WEB_SEARCH_TOOL_NAME,
      content: resultText,
      isError: allFailed, timestamp: now,
    });
    if (beganCell) {
      // The client sees only the cell; keep the result so its replay can carry it (#7269).
      rememberSidecarSearch(parsed, cellItemId, { id: call.id, arguments: callArgs }, resultText);
      // The cell is "completed" if any query produced a usable result, else "failed". `queries`
      // carries every attempted query so Codex renders the native plural label.
      const anySuccess = results.some(r => !r.outcome.error);
      // Collect the citations backing this batch (dedup by URL), so the bridge can attach them as
      // url_citation annotations on the following assistant message → the app's Sources chip.
      const sources: { url: string; title?: string }[] = [];
      const seenSrc = new Set<string>();
      for (const r of results) {
        for (const s of r.outcome.sources) {
          if (seenSrc.has(s.url)) continue;
          seenSrc.add(s.url);
          sources.push(s.title ? { url: s.url, title: s.title } : { url: s.url });
        }
      }
      yield {
        type: "web_search_call_end", id: call.id, itemId: cellItemId,
        queries: call.queries,
        status: anySuccess ? "completed" : "failed",
        ...(sources.length > 0 ? { sources } : {}),
      };
    }
  }

  // Eagerly acquire only the FIRST iteration's final headers so connect/header/HTTP failures remain
  // non-2xx JSON. A successful body is consumed inside the bridge, where byte progress can keep the
  // downstream turn alive and body failures are correctly in-stream.
  let firstPrepared: IterationResponse;
  try {
    firstPrepared = await prepareIterationDrained(false);
  } catch (e) {
    if (abortSignal) abortSignal.removeEventListener("abort", linkAbort);
    if (e instanceof LoopError) {
      recordLocalLoopFailure(e);
      const failure = loopFailure(e);
      const failed = markSidecarContextOverflow(jsonError(e.status, e.message, e.event), failure);
      if (failure.verifiedPlanRefusal) markVerifiedModelNotInPlanResponse(failed);
      return failed;
    }
    if (e instanceof SendBudgetExhaustedError) return jsonError(429, e.message,
      { type: "error", message: e.message, errorType: "rate_limit_error", code: e.code, retryable: false });
    throw e;
  }

  const toolNsMap = new Map<string, { namespace: string; name: string; freeform?: true }>();
  const freeform = new Set<string>();
  const toolSearch = new Set<string>();
  const requestedTools = parsed.context.tools ?? [];
  const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice, requestedTools);
  for (const t of requestedTools) {
    if (!toolAllowed(t)) continue;
    if (t.namespace) {
      toolNsMap.set(namespacedToolName(t.namespace, t.name), {
        namespace: t.namespace,
        name: t.name,
        ...(t.freeform ? { freeform: true } : {}),
      });
    }
    if (t.freeform) freeform.add(t.name);
    if (t.toolSearch) toolSearch.add(t.name);
  }

  // Drive the remaining iterations live. Search cells (begin/end) are yielded interleaved with the
  // real sidecar timing, the final answer's passthrough events come last — matching native ordering
  // (search cell BEFORE the assistant message). Iteration 2+ failures surface as an in-stream error.
  async function* produce(): AsyncGenerator<AdapterEvent> {
    let prepared = firstPrepared;
    try {
      for (let i = 0; i < HARD_CAP + completionRetries + terminalContinuations; i++) {
        const forceAnswer = searchesExecuted >= maxSearches;
        try {
          // First loop turn reuses the eager HEADERS. Subsequent header acquisitions run here.
          if (i > 0) {
            yield { type: "heartbeat" };
            prepared = yield* prepareIterationEvents(forceAnswer);
          }
          // Raw-byte progress heartbeats reach the bridge; semantic events remain buffered.
          const split = yield* consumeIterationEvents(prepared);

          // Loop (search + re-ask) ONLY when the model's actionable output is purely web_search. A real
          // tool call (e.g. shell/apply_patch) means this turn is terminal for Codex — finalize so those
          // calls reach Codex.
          // The budget check happens per query inside runSearchCall, so a
          // forced pass that emits one more web_search call is served the
          // limit-reached result instead of failing the turn (#6464: stripping
          // the declaration makes some models emit the raw call as visible
          // text).
          // A refused iteration ends the turn even when it carried a search call: running the
          // search would send the refused context back to the model (#7148).
          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !split.hasMalformedToolCall
            && !split.passthrough.some(event => event.type === "incomplete" || event.type === "error"
              || (event.type === "done" && isTruncatedStopReason(event.stopReason)));
          if (!shouldLoop) {
            // Validate every final Chat iteration, even when no search was called. Retry
            // only this model leg: already executed search results stay in messages.
            const final = split.passthrough.find(event => event.type === "done");
            if (deps.emptyCompletionRetry && !forceAnswer && adapter.name === "openai-chat"
              && final?.type === "done" && !isTruncatedStopReason(final.stopReason)
              && !split.passthrough.some(event => event.type === "error" || event.type === "incomplete")
              && !signal.aborted && !split.hasMalformedToolCall && !split.hasRealToolCall
              && split.streamedPassthroughCount === 0 && !hasVisibleAssistantText(split.passthrough)) {
              takeUsage(final.usage);
              if (completionRetries++ === 0) { yield { type: "heartbeat" }; continue; }
              throw new LoopError(502, "Provider completed without usable output after one retry", emptyCompletionRetryFailedEvent());
            }
            // Use the existing action/plan classifier and keep all hosted tool results.
            const currentParsed = prepared.parsed;
            if (deps.terminalContinuationGuard && adapter.name === "openai-chat"
              && final?.type === "done" && !isTruncatedStopReason(final.stopReason)
              && !signal.aborted && !split.hasMalformedToolCall && split.calls.length === 0
              && analyzeTerminalTurn(currentParsed, split.passthrough).decision === "continue") {
              takeUsage(final.usage);
              if (terminalContinuations > 0) {
                throw new LoopError(502, "Provider announced work again without calling a tool", {
                  type: "error", status: 502, code: "terminal_continuation_failed",
                  message: "Provider announced work again without calling a tool", errorType: "server_error" });
              }
              terminalContinuations++;
              // Save only the continuation's additions. Iteration-only nudges are rebuilt for the re-ask.
              const continuation = buildContinuationRequest({
                ...currentParsed, context: { ...currentParsed.context, messages },
              }, split.passthrough);
              pendingContinuationMessages = continuation.context.messages.slice(messages.length);
              yield { type: "assistant_boundary" };
              continue;
            }
            // #1001: a forced-answer pass that ends `done` must have produced
            // usable output — never a malformed tool call, and never silence.
            if (forceAnswer) {
              // An unterminated call flushes AFTER the terminal event, so find
              // the terminal rather than assuming it is last (#1001).
              const terminalEvent = split.passthrough.find(event => event.type === "done");
              if (terminalEvent?.type === "done" && !split.hasMalformedToolCall
                && isTruncatedStopReason(terminalEvent.stopReason)) {
                // A provider refusal or truncation is authoritative, even without text.
                // Preserve it once; neither an empty-answer retry nor a generic 502 applies.
                yield* replay(withReaskSum(split.passthrough.slice(split.streamedPassthroughCount)));
                return;
              }
              if (terminalEvent?.type === "done"
                && (split.hasMalformedToolCall
                  || (!split.hasRealToolCall && !hasVisibleAssistantText(split.passthrough)))) {
                // #1001 fixed the silent success by failing here. A malformed call still fails: it
                // reports a protocol problem, and replaying it would only re-ask an unwell upstream.
                // Silence is different — it is recoverable, so retry exactly once with the results
                // already gathered before failing the turn.
                console.warn("[web-search-loop] unusable forced answer", JSON.stringify({
                  model: parsed.modelId,
                  recoveryAttempt: emptyAnswerRetries,
                  searchCalls: split.calls.length,
                  malformed: split.hasMalformedToolCall,
                  stopReason: terminalEvent.stopReason,
                  eventTypes: [...new Set(split.passthrough.map(event => event.type))],
                }));
                takeUsage(terminalEvent.usage);
                if (!split.hasMalformedToolCall && !split.hasRealToolCall && emptyAnswerRetries < forcedAnswerRetries) {
                  emptyAnswerRetries++;
                  console.warn("[web-search-loop] empty forced answer — retrying once with tool calls disabled");
                  yield { type: "heartbeat" };
                  continue;
                }
                throw new LoopError(502, "forced-answer pass produced no usable assistant output");
              }
            }
            if (executedSearchCount > 0) {
              const failedCount = failedQueries.size;
              console.warn(
                `[web-search-loop] done — ${executedSearchCount} search${executedSearchCount > 1 ? "es" : ""}`
                + (failedCount > 0 ? ` (${failedCount} failed)` : "")
                + `, ${i + 1} iteration${i > 0 ? "s" : ""}, ${Date.now() - loopT0}ms`,
              );
            }
            // Live-streamed leading events are exactly the first N passthrough entries — replay
            // only the buffered tail so nothing reaches the client twice.
            yield* replay(withReaskSum(split.passthrough.slice(split.streamedPassthroughCount)));
            return;
          }
          takeUsage(terminalUsage(split.passthrough));
          if (split.calls.some(call => call.kind === "advisor")) {
            const continuationError = deps.advisor!.beginLeg();
            if (continuationError) {
              // All legs are already in hiddenUsage; attaching it to the error would
              // make the bridge's onUsage callback add and report those legs again.
              if (hiddenUsage) deps.onUsage?.(hiddenUsage);
              yield continuationError;
              return;
            }
          }
          // The thinking that led to the search belongs to the FIRST call's assistant replay turn.
          for (const event of split.passthrough.slice(split.streamedPassthroughCount)) {
            if (event.type === "text_delta" && event.anthropicThinkingSignature) yield event;
          }
          const preserveAnthropicHistory = prepared.responseAdapter.name === "anthropic";
          if (preserveAnthropicHistory) {
            if (!split.anthropicReplay) throw new LoopError(502, "Anthropic search history cannot be replayed losslessly");
            const message = { role: "assistant" as const,
              content: anthropicSearchAssistantContent(split.events), timestamp: Date.now() };
            const originalCalls = split.anthropicReplay.content.filter(block => block.type === "tool_use");
            const priorIds = new Set(messages.flatMap(message => message.role === "assistant"
              ? message.content.filter(part => part.type === "toolCall").map(part => part.id)
              : message.role === "toolResult" ? [message.toolCallId] : []));
            if (originalCalls.some(block => priorIds.has(block.id as string))) {
              throw new LoopError(502, "Anthropic search replay tool identity changed");
            }
            const calls = message.content.filter(part => part.type === "toolCall");
            if (originalCalls.length !== calls.length || originalCalls.some((block, index) => block.id !== calls[index]?.id)) {
              throw new LoopError(502, "Anthropic search replay tool identity changed");
            }
            // The raw input is authoritative, including non-empty content_block_start input.
            for (const [index, call] of calls.entries()) call.arguments = originalCalls[index]!.input as Record<string, unknown>;
            for (const call of split.calls) {
              const original = originalCalls.find(block => block.id === call.id);
              if (!original) throw new LoopError(502, "Anthropic search replay tool identity changed");
              if (call.kind === "advisor") call.question = parseAdvisorQuestionArgs(JSON.stringify(original.input)).question;
              else call.queries = parseQueries(JSON.stringify(original.input));
            }
            bindAnthropicReplay(message, split.anthropicReplay);
            messages.push(message);
          }
          const iterationThinking = preserveAnthropicHistory ? [] : extractIterationThinking(split.passthrough);
          for (const [callIndex, call] of split.calls.entries()) {
            accountRefusalOutputStarted = true;
            if (call.kind === "advisor") yield* runAdvisorCall(call, callIndex === 0 ? iterationThinking : [], !preserveAnthropicHistory);
            else yield* runSearchCall(call, callIndex === 0 ? iterationThinking : [], !preserveAnthropicHistory);
          }
          if (split.calls.some(call => call.kind === "advisor")) yield { type: "assistant_boundary" };
        } catch (e) {
          recordLocalLoopFailure(e);
          takeUsage(e instanceof LoopError ? e.event?.usage : undefined);
          const event: AdapterEvent = isTranslatorBudgetExceededError(e)
            ? {
              type: "error",
              status: 502,
              errorType: "upstream_error",
              code: e.code,
              message: "upstream translation buffer exceeded the safe limit",
            }
            : e instanceof SendBudgetExhaustedError
              ? { type: "error", status: 429, errorType: "rate_limit_error", code: e.code, message: e.message, retryable: false }
            // A later iteration's overflow ends the turn as the main path's terminal
            // context_length_exceeded, so Codex compacts instead of resending (#7316).
            : (e instanceof LoopError ? sidecarLoopTerminalEvent(loopFailure(e)) : undefined)
              ?? (e instanceof LoopError && e.event ? e.event
              : e instanceof LoopError && deps.thinkingRecovery
                ? { type: "error", status: e.status, errorType: "upstream_error", message: e.message }
                : { type: "error", message: e instanceof Error ? e.message : String(e) });
          // The bridge reports an error only if it carries usage. Settle exactly once: after a
          // terminal re-ask the failed terminal itself carries the sum (#8877), and the bridge
          // reports it; otherwise the hidden legs are reported here.
          if (!event.usage && hiddenUsage && terminalContinuations > 0 && event.type === "error") {
            yield { ...event, usage: withTerminalUsageMetadata(hiddenUsage, errorUsage) };
            return;
          }
          if (!event.usage && hiddenUsage) deps.onUsage?.(withTerminalUsageMetadata(hiddenUsage, errorUsage));
          yield event;
          return;
        }
      }
      if (hiddenUsage) deps.onUsage?.(hiddenUsage);
      yield { type: "error", message: "web-search loop exceeded its iteration cap" };
    } finally {
      for (const snapshot of replaySnapshots) snapshot.release();
      replaySnapshots.clear();
      if (abortSignal) abortSignal.removeEventListener("abort", linkAbort);
    }
  }

  const sse = bridgeToResponsesSSE(
    guardEmptyToolCatalogStream(produce(), deps.clientToolCatalogRestriction, translatorBudget), parsed._responseModelId ?? parsed.modelId, toolNsMap, freeform, toolSearch, () => {
      const elapsed = Date.now() - loopT0;
      if (executedSearchCount > 0 || searchesExecuted > 0) {
        console.warn(`[web-search-loop] cancelled — ${executedSearchCount} real searches, ${searchesExecuted - executedSearchCount} placeholders, ${elapsed}ms`);
      }
      internalAbort.abort("client closed responses stream");
    }, undefined,
    {
      translatorBudget, proxyErrorContext: deps.proxyErrorContext,
      replayCacheScope: parsed._reasoningReplayScope,
      ...(deps.clientToolCatalogRestriction ? { ...deps.clientToolCatalogRestriction, enforceDeclaredToolNames: false } : {}),
      ...(deps.forceEmptyResponseId ? { responseId: "" } : {}),
      ...(deps.terminalRefusalAsFailed ? { terminalRefusalAsFailed: true } : {}),
      ...(deps.escapeMemoryCitationTags === false ? { escapeMemoryCitationTags: false } : {}),
      hideThinkingSummary: parsed.options.hideThinkingSummary,
      chatRawReasoningVisible: deps.chatRawReasoningVisible,
      hideRawReasoning: parsed.options.hideRawReasoning,
      rawReasoningAsSummary: parsed.options.rawReasoningAsSummary,
      ...(deps.stallTimeoutSec !== undefined ? { stallTimeoutSec: deps.stallTimeoutSec } : {}),
      ...(deps.onFirstOutput ? { onFirstOutput: deps.onFirstOutput } : {}),
      ...(deps.onUsage ? {
        onUsage: (usage: OcxUsage | undefined) => {
          if (pendingLegs > 0) {
            deps.onUsage?.(mergePendingUsage(countersOnly(hiddenUsage), usage));
            return;
          }
          // The error path already settled this leg's counters; retain only its terminal metadata.
          deps.onUsage?.(hiddenUsage ? withTerminalUsageMetadata(hiddenUsage, usage) : usage);
        },
      } : {}),
      ...(deps.onCompletedResponse ? { onCompletedResponse: deps.onCompletedResponse } : {}),
    },
  );
  return new Response(sse, { headers: SSE_HEADERS });
}