import { completeIncrementalFrame, recordIncrementalDispatch, type IncrementalPlan } from "./codex-ws-incremental";
import { NativeSteeringError } from "./native-steering";
import { NativeContinuationRefusalError } from "./native-continuation-refusal";
import { mergeSteeringContinuation } from "./native-steering-settings";
import { markNativeControlResponse } from "./native-response-control";
import type { NativeResponseControl } from "./native-response-control";
import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
import { isSafeResponseHeader, type ResponseMetadataContext } from "../safe-response-headers";
import { CodexWsMetadata, type CodexWsQuotaObserver } from "./codex-ws-metadata";
import { CODEX_RESPONSES_HTTP_URL, type PreparedCodexWsRequest } from "./codex-ws-request";
import { CodexWsCorrelation } from "./codex-ws-correlation";
import type { CodexWsSession } from "./codex-ws-session";
import { UPGRADE_DEADLINE_MS, CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
  CODEX_WS_COMMITTED_SILENT_INTERVALS, MAX_CODEX_WS_FRAME_BYTES,
  MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, markCodexWsPreludeProjection, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
  codexWsCreateFrameExceedsLimit, codexWsFailureDetail, codexWsPreResponseFailure, markCodexWsStage, codexWsOcxVersion,
  markCodexWsSocketDeath, codexWsWrapperStatus, isCodexWsTerminalEvent, type CodexWsFailureStage, type CodexWsStageRecord,
  type CodexWsTerminalEvent, codexWsPreOutputRefusalStatus, isEmptyCodexWsLifecycleEvent, codexWsFrameResponseIds,
  markCodexWsPreOutputRefusal, responsesFrameIsReplayUnsafe, type CodexWsPreOutputRefusalHold } from "./codex-ws-wire";

interface ExchangeOptions {
  incrementalPlan?: IncrementalPlan;
  nativeControl?: NativeResponseControl;
  beforeContinuation?: () => Promise<void>;
  session: CodexWsSession;
  url: string;
  init: RequestInit;
  prepared: PreparedCodexWsRequest;
  sseFallback: typeof globalThis.fetch;
  onQuota?: CodexWsQuotaObserver;
  beforeDispatch?: (headers: Headers) => void;
  /**
   * Physical-send admission, handed the frame text that actually leaves on this send: the delta
   * frame for an incremental send, the full create for its cache-miss recovery (#8453 replay guard).
   */
  onPhysicalDispatch?: (frameText: string) => void;
  recoverPhysicalSend?: (send: () => Promise<void>) => Promise<boolean>;
  onContinuationDispatch?: (frame: { body: Record<string, unknown>; text: string }) => void;
  /** Bun version string the caller gated on; stamped onto the stage record. */
  bunVersion?: string;
  /**
   * Opt-in (#6969): how long empty lifecycle frames may be held so an authoritative upstream
   * refusal that follows them, before any output, can settle as a replayable gateway status instead
   * of a committed 200. Absent or zero keeps the exchange exactly as it was. Ignored on native
   * control exchanges and on transports without the metadata channel.
   */
  preOutputRefusalHold?: CodexWsPreOutputRefusalHold;
  /** Turn-state binding and known models for the metadata this exchange relays. */
  metadataContext?: ResponseMetadataContext;
}

const HTTP_HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i;

function record(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

/** Rebuild only permitted metadata: upstream framing describes a different body. */
function rejectionHeaders(source: Record<string, unknown>, prelude: Headers, context: ResponseMetadataContext): Headers {
  const connectionHeaders = new Set<string>();
  for (const [name, value] of Object.entries(source)) {
    if (name.toLowerCase() !== "connection" || typeof value !== "string") continue;
    for (const token of value.split(",")) {
      const lower = token.trim().toLowerCase();
      if (HTTP_HEADER_TOKEN.test(lower)) connectionHeaders.add(lower);
    }
  }
  // Reuse the metadata owner's count/value/family budgets and window freshness
  // rules, without publishing quota twice. Pool bookkeeping consumes the HTTP
  // projection; plain-main publication belongs only to the WS observer.
  const projected = new CodexWsMetadata(undefined, context);
  try {
    for (const values of [Object.fromEntries(prelude), source]) {
      const headers = Object.fromEntries(Object.entries(values).filter(([name, value]) => {
        if (!HTTP_HEADER_TOKEN.test(name) || !isSafeResponseHeader(name)
          || connectionHeaders.has(name.toLowerCase())) return false;
        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return false;
        return !(typeof value === "number" && !Number.isFinite(value)) && !/[\r\n\0]/.test(String(value));
      }));
      if (Object.keys(headers).length === 0) continue;
      const event = { type: "codex.response.metadata", headers };
      // Bound the combined serialized seed and updates, even for replacements.
      projected.consume(event, Buffer.byteLength(JSON.stringify(event)));
    }
    const headers = projected.snapshot();
    headers.set("content-type", "application/json");
    headers.set("cache-control", "no-store");
    return headers;
  } finally {
    projected.finish();
  }
}

/**
 * Carry #3740's refused-create status back to the HTTP recovery path. Codex's
 * responses_websocket.rs accepts status/status_code and scalar header values;
 * unlike its native client, this relay converts only precommit 4xx. Returning a
 * post-send 5xx or fetch rejection could cause the outer retry wrapper to resend.
 * The one 5xx exception is the opt-in pre-output refusal below (#6969): a structured upstream
 * refusal with nothing relayed but empty lifecycle frames, which the caller may replay.
 */
function wrappedRejectionResponse(payload: Record<string, unknown>, prelude: Headers, context: ResponseMetadataContext): Response | null {
  if (payload.type !== "error" || payload.stream_id !== undefined) return null;
  // The native typed wrapper has one aliased field, not two competing statuses.
  if (Object.hasOwn(payload, "status_code") && Object.hasOwn(payload, "status")) return null;
  const status = Object.hasOwn(payload, "status_code") ? payload.status_code : payload.status;
  if (typeof status !== "number" || !Number.isInteger(status) || status < 400 || status > 499) return null;
  const error = payload.error;
  if (error != null && (!record(error)
    || [error.code, error.message].some(value => value != null && typeof value !== "string"))) return null;
  if (payload.headers != null && !record(payload.headers)) return null;
  const headers = rejectionHeaders(record(payload.headers) ? payload.headers : {}, prelude, context);
  return new Response(JSON.stringify({
    error: error ?? { type: "upstream_error", message: "Upstream rejected the request" },
  }), { status, headers });
}

/** The client-facing error of a pre-output refusal projection, from the refusal's own error object. */
function refusalErrorBody(source: unknown): Record<string, string> {
  const error = record(source) ? source : {};
  return {
    type: typeof error.type === "string" ? error.type : "server_error",
    ...(typeof error.code === "string" ? { code: error.code } : {}),
    message: typeof error.message === "string" ? error.message : "Upstream declined the request before any output",
  };
}

/** The sole SSE exchange state machine for both one-shot and retained sockets. */
export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
  const { session, url, init, prepared, sseFallback, onQuota, beforeDispatch, bunVersion, nativeControl, beforeContinuation,
    preOutputRefusalHold } = options;
  const metadataContext = options.metadataContext ?? {};
  const { headers } = prepared;
  let frameText = prepared.frameText;
  let incrementalPlan = options.incrementalPlan;
  let recoveryAdmissionPending = false;
  const signal = init.signal ?? undefined;
  return new Promise<Response>((resolve, reject) => {
    const ws = session.socket;

    let opened = session.opened;
    let settledPreOpen = false;
    let sent = false;
    let received = false;
    let responseCommitted = false;
    let terminal = false;
    // #4191: the counters behind the failure classification. A user whose long
    // thread died here could not tell an unanswered socket from one that carried
    // only quota frames, because both arrived as the same one-line message.
    let upstreamFrames = 0;
    let controlFrames = 0;
    let relayedEvents = 0;
    let pings = 0;
    let pongs = 0;
    let sentAt: number | null = null;
    let firstFrameAt: number | null = null;
    let firstResponseAt: number | null = null;
    // Numeric close code for the durable stage record; the reason string stays
    // out of it on purpose (#4191 content-free contract).
    let closeCode: number | null = null;
    // #6740: which terminal frame the upstream itself sent, before any synthetic tail.
    let terminalEvent: CodexWsTerminalEvent | null = null;
    let terminalErrorStatus: number | null = null;
    let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
    const encoder = new TextEncoder();
    const metadata = url === CODEX_RESPONSES_HTTP_URL ? new CodexWsMetadata(onQuota, metadataContext) : null;
    const correlation = session.retainable ? new CodexWsCorrelation(session.reused, id => session.hasCompleted(id)) : null;
    let detachOwner = () => {};
    let detachSteering = () => {};
    let continuationBase: Record<string, unknown> | undefined;
    // Liveness while waiting for the first response event (metadata path only): the
    // silence timer is re-armed by every inbound frame or pong; the pinger runs on a fixed
    // interval so a peer that answers pings can never trip the silence bound while alive.
    // After the commit, each ping tick checks whether any frame or pong arrived since the last.
    let silenceTimer: ReturnType<typeof setTimeout> | undefined;
    let pingTimer: ReturnType<typeof setTimeout> | undefined;
    let inboundAtLastTick = 0;
    let silentIntervals = 0;
    // The resolved 200, retained so a later body failure can replace its
    // success-shaped stage record with the failure-shaped one (#4191).
    let committedResponse: Response | null = null;
    // #6969: the pre-output refusal hold. While it is open, empty lifecycle frames are queued on the
    // not-yet-exposed stream without resolving it. Every settle other than an eligible refusal
    // commits first (deferredCommit), so the outcome is exactly what the exchange produced before.
    const holdEnabled = (preOutputRefusalHold?.maxMs ?? 0) > 0 && metadata !== null && !nativeControl;
    // Drops for good on any identity the exchange cannot tie to one response: a stream id, two
    // different ids in one frame, or an id that differs from the first one seen. Independent of
    // socket reuse, so a cold one-shot socket is held to the same rule as a pooled one.
    let refusalEligible = holdEnabled;
    let refusalResponseId: string | null = null;
    let heldHeaders: Headers | null = null;
    let deferredCommit = false;
    let holdTimer: ReturnType<typeof setTimeout> | undefined;
    const stream = new ReadableStream<Uint8Array>({
      start(c) { controller = c; },
      cancel() {
        if (terminal) return;
        terminal = true;
        cleanup();
        session.dispose();
      },
    }, new ByteLengthQueuingStrategy({ highWaterMark: MAX_CODEX_WS_QUEUE_BYTES }));

    const cleanup = () => {
      clearTimeout(upgradeTimer);
      clearTimeout(silenceTimer);
      clearTimeout(pingTimer);
      clearTimeout(holdTimer);
      signal?.removeEventListener("abort", onAbort);
      metadata?.finish();
      correlation?.finish();
      detachOwner();
      detachSteering();
      ws.removeEventListener("open", onOpen);
      ws.removeEventListener("message", onMessage);
      ws.removeEventListener("close", onClose);
      ws.removeEventListener("error", onError);
      ws.removeEventListener("pong", onPong);
    };

    /**
     * Snapshot the stage for a failure message. Measuring the frame is deferred
     * to here so the happy path never pays for it: a full-replay thread's frame
     * runs to megabytes, and this is the only place its size is worth knowing.
     */
    const failureStage = (): CodexWsFailureStage => ({
      requestBytes: Buffer.byteLength(frameText, "utf8"),
      sent,
      upstreamFrames,
      controlFrames,
      relayedEvents,
      firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
      firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null,
      elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
      pings,
      pongs,
    });

    /**
     * The durable twin of failureStage (#4191). `requestBytes` is an explicit
     * parameter so the committed-success path can pass null instead of paying
     * the UTF-8 walk of a megabyte replay frame; failure callers pass
     * `failureStage().requestBytes`, which measures exactly once.
     */
    const stageRecord = (requestBytes: number | null): CodexWsStageRecord => ({
      requestBytes,
      sent,
      upstreamFrames,
      controlFrames,
      relayedEvents,
      firstFrameMs: sentAt !== null && firstFrameAt !== null ? Math.max(0, firstFrameAt - sentAt) : null,
      firstResponseMs: sentAt !== null && firstResponseAt !== null ? Math.max(0, firstResponseAt - sentAt) : null,
      elapsedMs: sentAt !== null ? Math.max(0, Date.now() - sentAt) : null,
      pings,
      pongs,
      closeCode,
      reused: session.reused,
      ocxVersion: codexWsOcxVersion(),
      bunVersion: bunVersion ?? "unknown",
      terminalEvent,
      terminalErrorStatus,
    });

    const commitResponse = () => {
      if (responseCommitted) return;
      responseCommitted = true;
      deferredCommit = false;
      clearTimeout(holdTimer);
      clearTimeout(silenceTimer);
      clearTimeout(pingTimer);
      // A held preamble froze the prelude headers at the first Responses event, which is the moment
      // they were frozen before the hold existed.
      const responseHeaders = heldHeaders ? new Headers(heldHeaders) : metadata?.snapshot() ?? new Headers();
      responseHeaders.set("content-type", "text/event-stream; charset=utf-8");
      const response = new Response(stream, { status: 200, headers: responseHeaders });
      metadata?.commit();
      markCodexWsResponse(response, Boolean(metadata && onQuota));
      if (nativeControl) markNativeControlResponse(response);
      markCodexWsStage(response, stageRecord(null));
      committedResponse = response;
      resolve(response);
      startCommittedLiveness();
    };

    /**
     * Open the hold at the first empty lifecycle frame: freeze the prelude and bound the wait by
     * both the hold's own maximum and its absolute end. False when no time is left, so the frame
     * commits exactly as it would without the hold.
     */
    const beginHold = (): boolean => {
      if (heldHeaders) return true;
      if (!metadata || !preOutputRefusalHold) return false;
      const waitMs = Math.min(preOutputRefusalHold.maxMs, preOutputRefusalHold.until - Date.now());
      if (waitMs <= 0) return false;
      heldHeaders = metadata.snapshot();
      metadata.commit();
      holdTimer = setTimeout(() => {
        if (!terminal && !responseCommitted) commitResponse();
      }, waitMs);
      return true;
    };

    const noteRefusalIdentity = (payload: Record<string, unknown>) => {
      const ids = codexWsFrameResponseIds(payload);
      if (payload.stream_id !== undefined || ids === null || ids.length > 1) {
        refusalEligible = false;
        return;
      }
      const id = ids[0];
      if (id === undefined) return;
      if (refusalResponseId === null) refusalResponseId = id;
      else if (id !== refusalResponseId) refusalEligible = false;
    };

    /**
     * Settle an authoritative pre-output refusal (#6969) as the gateway status the upstream stated,
     * without the non-replayable marker: nothing but empty lifecycle frames was relayed, and the
     * upstream ended that response itself. The caller's transient ladder and pool move may send the
     * turn again; if neither does, the registered restore hands the client the original stream,
     * which is already complete on `stream`.
     */
    const resolveRefusal = (status: number, payload: Record<string, unknown>, headers: Headers, prelude: Headers) => {
      responseCommitted = true;
      deferredCommit = false;
      clearTimeout(holdTimer);
      const stage = stageRecord(null);
      const source = payload.type === "error"
        ? payload.error
        : record(payload.response) ? payload.response.error : undefined;
      const projection = new Response(JSON.stringify({ error: refusalErrorBody(source) }), { status, headers });
      markCodexWsPreludeProjection(projection);
      markCodexWsStage(projection, stage);
      const observed = Boolean(metadata && onQuota);
      markCodexWsPreOutputRefusal(projection, () => {
        const restoredHeaders = new Headers(prelude);
        restoredHeaders.set("content-type", "text/event-stream; charset=utf-8");
        const restored = new Response(stream, { status: 200, headers: restoredHeaders });
        markCodexWsResponse(restored, observed);
        // The same record object, so the attempt that adopted it keeps reading one stage.
        markCodexWsStage(restored, stage);
        return restored;
      });
      resolve(projection);
    };

    const failStream = (error: unknown, status: 502 | 504 = 502, { socketDied = false } = {}) => {
      if (terminal) return;
      terminal = true;
      // A held preamble or refusal was a commit deferred, not avoided: settle as the committed
      // body failure it would have been, never as a new pre-response gateway status.
      if (deferredCommit) commitResponse();
      if (sent && !responseCommitted && metadata) {
        // Nothing has been promised to the client yet, so the honest answer is a gateway
        // status, not a 200 whose body then fails. The frame may already be executing
        // upstream: the response is marked non-replayable so no retry layer of this process
        // sends it again, and the client applies its own retry policy as it would on the direct
        // path. Same settle order as a refused create: snapshot, detach, close, dispose.
        const prelude = metadata.snapshot();
        // Claim the commit slot so no later path can resolve a second, 200 Response.
        responseCommitted = true;
        cleanup();
        try { controller?.close(); } catch { /* unused stream already closed */ }
        session.dispose();
        const message = error instanceof Error ? error.message : String(error);
        const failureResponse = codexWsPreResponseFailure(status, message, prelude);
        const stage = failureStage();
        markCodexWsStage(failureResponse, stageRecord(stage.requestBytes));
        // #4191: a socket that died under the send is the one settle the dispatch may replace,
        // once, and only under the operator's `retryOnReset` grant. Native steering and injection
        // are left out: their channel may already have sent continuation frames on this socket, so
        // the create frame alone no longer describes the turn.
        if (socketDied && !nativeControl) markCodexWsSocketDeath(failureResponse, stage);
        markCodexWsPreludeProjection(failureResponse);
        resolve(failureResponse);
        return;
      }
      // A response is already flowing (or this transport has no metadata channel and
      // committed at send). Settle as a body failure, never a fetch rejection/5xx that the
      // pre-stream wrapper could resend.
      if (sent) commitResponse();
      cleanup();
      try { controller?.error(typeof error === "string" ? new Error(error) : error); } catch { /* stream already done */ }
      session.dispose();
      // A body failure replaces the success-shaped record commitResponse wrote:
      // this settle is a failure, and the frame size is evidence again.
      if (committedResponse) {
        markCodexWsStage(committedResponse, stageRecord(Buffer.byteLength(frameText, "utf8")));
      }
    };

    /** (Re)start the silence bound; every inbound frame or pong is proof of life. */
    const armSilence = () => {
      clearTimeout(silenceTimer);
      if (responseCommitted || terminal) return;
      silenceTimer = setTimeout(
        () => failStream(`codex websocket response prelude timed out${codexWsFailureDetail(failureStage())}`, 504),
        CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS,
      );
    };
    const pingable = () => typeof (ws as WebSocket & { ping?: unknown }).ping === "function";
    /** False when ping() threw. It may also close the socket and settle the exchange. */
    const sendPing = (): boolean => {
      if (!pingable()) return false;
      try { (ws as WebSocket & { ping: (data?: string) => void }).ping(); } catch { return false; }
      pings += 1;
      return true;
    };
    /** Ping on a fixed interval for the life of the exchange; a socket without ping() is never pinged. */
    const schedulePing = () => {
      if (!pingable() || terminal) return;
      pingTimer = setTimeout(() => {
        if (terminal) return;
        if (responseCommitted && pongs > 0) {
          const inbound = upstreamFrames + pongs;
          silentIntervals = inbound === inboundAtLastTick ? silentIntervals + 1 : 0;
          inboundAtLastTick = inbound;
          if (silentIntervals >= CODEX_WS_COMMITTED_SILENT_INTERVALS) {
            failStream(`codex websocket stopped answering after the response started${codexWsFailureDetail(failureStage())}`);
            return;
          }
        }
        sendPing();
        if (!terminal) schedulePing();
      }, CODEX_WS_LIVENESS_PING_INTERVAL_MS);
    };
    /** Only a peer that has ponged is judged by its silence, so probe again if none has yet. */
    const startCommittedLiveness = () => {
      if (!metadata || terminal || !pingable()) return;
      inboundAtLastTick = upstreamFrames + pongs;
      silentIntervals = 0;
      if (pongs === 0) sendPing();
      if (!terminal) schedulePing();
    };
    const onPong = () => {
      if (terminal) return;
      pongs += 1;
      if (!responseCommitted) armSilence();
    };

    const upgradeTimer = setTimeout(() => {
      if (opened || settledPreOpen) return;
      settledPreOpen = true;
      cleanup();
      session.dispose();
      resolve(sseFallback(url, init));
    }, UPGRADE_DEADLINE_MS);

    const cancelExchange = (reason: unknown) => {
      if (terminal || settledPreOpen) return;
      if (!sent) {
        settledPreOpen = true;
        terminal = true;
        cleanup();
        session.dispose();
        reject(reason);
        return;
      }
      if (!responseCommitted && metadata && !deferredCommit) {
        // Sent, unacknowledged. The proxy's own connect deadline is an origin-silence
        // verdict and settles like one; a caller abort is the caller's decision, so the
        // exchange rejects with that reason and disposing the socket cancels the turn.
        // Both arrive on the same composite signal (fetchWithHeaderTimeout joins the
        // caller's controller with its own), so the reason is the only discriminator: the
        // deadline aborts with a TimeoutError DOMException, and every caller abort in this
        // process (upstream.abort() in core.ts) carries the default AbortError. A future
        // proxy-side deadline that aborts with TimeoutError would still be honestly a 504.
        if ((reason as { name?: unknown } | null)?.name === "TimeoutError") {
          failStream(`codex websocket response did not start before the connect deadline${codexWsFailureDetail(failureStage())}`, 504);
          return;
        }
        terminal = true;
        cleanup();
        session.dispose();
        reject(reason);
        return;
      }
      failStream(reason);
    };
    const onAbort = () => cancelExchange(signal?.reason ?? new DOMException("The operation was aborted.", "AbortError"));
    signal?.addEventListener("abort", onAbort, { once: true });

    const onOpen = () => {
      if (settledPreOpen) return;
      clearTimeout(upgradeTimer);
      opened = true;
      try {
        beforeDispatch?.(new Headers(headers));
      } catch (error) {
        // Settle and detach before close: a synchronous close event must not resend over SSE.
        settledPreOpen = true;
        terminal = true;
        cleanup();
        ws.removeEventListener("open", onOpen);
        ws.removeEventListener("message", onMessage);
        ws.removeEventListener("close", onClose);
        ws.removeEventListener("error", onError);
        ws.removeEventListener("pong", onPong);
        session.dispose();
        reject(error);
        return;
      }
      if (terminal || settledPreOpen || signal?.aborted) return;
      // New sockets have just validated their upgrade; retained sockets carry the
      // same connection signal into a fresh exchange, never its predecessor's frames.
      metadata?.seed(session.upgradeHeaders());
      sent = true;
      try {
        if (nativeControl) {
          // Parsed once: the base body is immutable for this exchange, and a
          // full-replay frame runs to megabytes. It seeds continuationBase on
          // the first create frame.
          let base: Record<string, unknown> | undefined;
          detachSteering = nativeControl.attach(frame => {
            // Build, serialize and bound-check the reconstructed frame synchronously in the
            // channel callback: a typed refusal must reach the channel's synchronous rollback
            // (continuation slot released, journal unwritten) rather than the asynchronous
            // failStream path, so a corrected continuation can still retry on this channel.
            const prepare = () => {
              let outgoing = frame;
              if (frame.type === "response.create") {
                // Generation overrides have passed route policy; identity/tools remain pinned.
                // Keep the last explicit wire settings for later explicit and automatic successors.
                base ??= JSON.parse(frameText) as Record<string, unknown>;
                continuationBase ??= base;
                outgoing = nativeControl.kind === "steering"
                  ? mergeSteeringContinuation(continuationBase, frame)
                  : { ...continuationBase, input: frame.input, previous_response_id: frame.previous_response_id };
              }
              const text = JSON.stringify(outgoing);
              nativeControl.assertOutboundFrame?.(text);
              if (codexWsCreateFrameExceedsLimit(text)) {
                throw new Error("Native steering frame exceeds the transport byte limit");
              }
              return { outgoing, text };
            };
            const prepared = prepare();
            const sendControl = () => {
              if (terminal || signal?.aborted || session.closed || ws.readyState !== WebSocket.OPEN) {
                throw new Error("Native steering connection is no longer available");
              }
              beforeDispatch?.(new Headers(headers));
              if (frame.type === "response.create") {
                // The exact serialized successor and its body, so admission can price the
                // reconstructed input and the successor's own output ceiling — never the
                // opening request's stale estimate.
                options.onContinuationDispatch?.({ body: prepared.outgoing, text: prepared.text });
                continuationBase = prepared.outgoing;
              }
              try { ws.send(prepared.text); } catch {
                // A send failure has unknown delivery. Never replay or fall back.
                failStream("Native steering send failed; delivery is unknown");
                throw new Error("Native steering send failed; delivery is unknown");
              }
            };
            if (frame.type === "response.create") {
              // Explicit tool-result continuations are physical request starts;
              // they keep provider pacing and revalidate auth AFTER the wait.
              // A typed pre-send refusal (e.g. the configured upstream body limit) is a
              // known non-delivery and keeps its own message; every other failure keeps
              // the unknown-delivery wording.
              // Keep known refusals on this stream even when no pacing hook is installed.
              void Promise.resolve().then(beforeContinuation).then(sendControl).catch(error => failStream(
                error instanceof NativeSteeringError || error instanceof NativeContinuationRefusalError ? error
                  : new Error("Native steering continuation could not be dispatched; do not automatically replay queued input"),
              ));
            } else sendControl();
          }, error => failStream(error));
        }
      } catch (error) {
        // An attach failure is an ownership conflict, not a failed send: no frame
        // left the process, but the channel can never bind, so resolving the HTTP
        // fallback here would silently degrade a multi-agent turn into an ordinary
        // one. Fail the turn visibly instead.
        failStream(error);
        return;
      }
      try { options.onPhysicalDispatch?.(frameText); } catch (error) {
        // Admission refused before the frame left. This is a pre-open rejection,
        // not a transport failure and not an authorization to replay over SSE.
        settledPreOpen = true;
        sent = false;
        terminal = true;
        cleanup();
        session.dispose();
        reject(error);
        return;
      }
      try {
        ws.send(frameText);
        if (incrementalPlan) recordIncrementalDispatch(incrementalPlan);
        sentAt = Date.now();
      } catch {
        if (received || responseCommitted) {
          if (terminal) session.dispose();
          failStream("codex websocket send failed after response activity");
          return;
        }
        // send() throwing means the frame never left, so no upstream turn
        // started and the SSE resend cannot double-generate. Falling back
        // (instead of erroring a synthetic 200 body) keeps the pre-stream
        // HTTP error/refresh/failover machinery in charge.
        settledPreOpen = true;
        sent = false;
        cleanup();
        session.dispose();
        resolve(sseFallback(url, init));
        return;
      }
      if (!metadata) commitResponse();
      else if (!responseCommitted && !terminal) {
        armSilence();
        // Probe now, not one interval in: the path can die seconds after the send, before a
        // held commit, and the committed check needs a pong from before that.
        sendPing();
        if (!terminal) schedulePing();
      }
    };

    const onMessage = (event: MessageEvent) => {
      if (!controller || terminal) return;
      if (recoveryAdmissionPending) {
        failStream("codex websocket received data during cache-miss recovery admission");
        return;
      }
      received = true;
      if (!responseCommitted) armSilence();
      upstreamFrames += 1;
      if (firstFrameAt === null) firstFrameAt = Date.now();
      const text = typeof event.data === "string" ? event.data : "";
      if (!text) return;
      // UTF-8 byte length is always at least the JS string length. Reject this
      // cheap lower bound before parsing so an obviously oversized frame does
      // not create another large object graph.
      if (text.length > MAX_CODEX_WS_FRAME_BYTES) {
        failStream("codex websocket frame exceeds the response size limit");
        return;
      }
      const rawEncodedText = encoder.encode(text);
      if (rawEncodedText.byteLength > MAX_CODEX_WS_FRAME_BYTES) {
        failStream("codex websocket frame exceeds the response size limit");
        return;
      }
      let replayUnsafe = false;
      const normalized = normalizeResponsesWsRelayEvent(text, (refusalEligible || incrementalPlan?.delta) && sent && !responseCommitted
        ? payload => { replayUnsafe = responsesFrameIsReplayUnsafe(payload); }
        : undefined);
      if (!normalized) {
        if (replayUnsafe) commitResponse();
        return;
      }
      const { type } = normalized;
      let relayText = normalized.text;
      let controlFrame = false;
      if (metadata) {
        try {
          const sanitized = metadata.consume(normalized.payload, rawEncodedText.byteLength);
          if (sanitized !== null) {
            relayText = sanitized;
            controlFrame = true;
            controlFrames += 1;
          }
        } catch (error) {
          failStream(error);
          return;
        }
      }
      const encodedText = relayText === text ? rawEncodedText : encoder.encode(relayText);
      if (encodedText.byteLength > MAX_CODEX_WS_FRAME_BYTES) {
        failStream("codex websocket frame exceeds the response size limit");
        return;
      }
      if (!controlFrame && !type.startsWith("response.") && type !== "error") {
        if (replayUnsafe) commitResponse();
        return;
      }
      let steeringEnded = false;
      let refusalStatus: number | undefined;
      let refusalHeaders: Headers | undefined;
      let refusalPrelude: Headers | undefined;
      if (controlFrame) {
        if (replayUnsafe) commitResponse();
      } else {
        firstResponseAt ??= Date.now();
        try {
          if (nativeControl) steeringEnded = nativeControl.observe(normalized.payload);
          else correlation?.accept(normalized.payload);
        } catch (error) { failStream(error); return; }
        if (replayUnsafe) commitResponse();
        // An authoritative refusal before any response activity means the synthesized ID was
        // not accepted. The retained full create belongs to this exchange's admitted caller.
        // Never replay caller-owned IDs, committed output, foreign identities or unknown sends.
        const cacheMissStatus = codexWsWrapperStatus(normalized.payload);
        if (incrementalPlan?.delta && sent && !responseCommitted && !deferredCommit && relayedEvents === 0
          && type === "error" && normalized.payload.stream_id === undefined
          && normalized.payload.response_id === undefined && normalized.payload.response === undefined
          && record(normalized.payload.error) && normalized.payload.error.code === "previous_response_not_found"
          && ((!Object.hasOwn(normalized.payload, "status") && !Object.hasOwn(normalized.payload, "status_code"))
            || (cacheMissStatus !== undefined && cacheMissStatus >= 400 && cacheMissStatus < 500))) {
          frameText = incrementalPlan.fullFrameText;
          incrementalPlan = { ...incrementalPlan, frameText, delta: false, sentBytes: incrementalPlan.fullBytes };
          if (signal?.aborted) { onAbort(); return; }
          recoveryAdmissionPending = true;
          void (async () => {
            await beforeContinuation?.();
            if (terminal || responseCommitted) return;
            if (signal?.aborted) { onAbort(); return; }
            const send = async () => {
              if (codexWsCreateFrameExceedsLimit(frameText)) {
                terminal = true;
                cleanup();
                session.dispose();
                try { controller!.close(); } catch { /* unused stream already closed */ }
                // Await the physical HTTP admission before committing its result.
                resolve(await sseFallback(url, init));
                return;
              }
              beforeDispatch?.(new Headers(headers));
              if (signal?.aborted) { onAbort(); return; }
              // The recovery is the full create, so that is the frame the replay guard records.
              options.onPhysicalDispatch?.(frameText);
              if (terminal || signal?.aborted) return;
              recoveryAdmissionPending = false;
              ws.send(frameText);
              recordIncrementalDispatch(incrementalPlan!);
              sentAt = Date.now();
            };
            const allowed = options.recoverPhysicalSend ? await options.recoverPhysicalSend(send) : (await send(), true);
            if (!allowed) {
              terminal = true;
              cleanup();
              session.dispose();
              try { controller.close(); } catch { /* unused stream already closed */ }
              const rejection = wrappedRejectionResponse({ type: "error", status: cacheMissStatus ?? 400,
                error: normalized.payload.error, headers: normalized.payload.headers }, metadata?.snapshot() ?? new Headers(), metadataContext);
              if (!rejection) throw new Error("Invalid cache-miss refusal");
              markCodexWsPreludeProjection(rejection);
              resolve(rejection);
            }
          })().catch(error => { if (terminal && !responseCommitted) reject(error); else failStream(error); });
          return;
        }
        const holdOpen = refusalEligible && sent && !responseCommitted;
        if (holdOpen) noteRefusalIdentity(normalized.payload);
        // Correlation must run first: a reused socket's foreign-stream error settles as a
        // non-replayable 502 above, never as the refused-create 4xx projection below, which
        // is the one status family that could authorize an account replay.
        // Only before anything was held: after an empty preamble a 4xx frame keeps today's
        // in-body delivery, so a held 429 can never become a quota rotation it was not before.
        if (metadata && sent && !responseCommitted && !deferredCommit && type === "error") {
          let rejection: Response | null;
          try { rejection = wrappedRejectionResponse(normalized.payload, metadata.snapshot(), metadataContext); }
          catch (error) { failStream(error); return; }
          if (rejection) {
            terminal = true;
            cleanup();
            try { controller.close(); } catch { /* unused stream already closed */ }
            session.dispose();
            markCodexWsPreludeProjection(rejection);
            resolve(rejection);
            return;
          }
        }
        let holdFrame = false;
        if (holdOpen && refusalEligible) {
          refusalStatus = codexWsPreOutputRefusalStatus(normalized.payload);
          if (refusalStatus !== undefined) {
            // Built before anything settles: a refusal whose metadata cannot be projected within the
            // header bounds is delivered the way it was before, in the committed body.
            try {
              refusalPrelude = heldHeaders ?? metadata?.snapshot() ?? new Headers();
              const declared = normalized.payload.headers;
              refusalHeaders = rejectionHeaders(record(declared) ? declared : {}, refusalPrelude, metadataContext);
            } catch {
              refusalStatus = undefined;
            }
          }
          holdFrame = refusalStatus === undefined && isEmptyCodexWsLifecycleEvent(normalized.payload) && beginHold();
        }
        if (refusalStatus === undefined && !holdFrame) commitResponse();
        else deferredCommit = true;
        // Record the terminal the upstream sent as soon as it is accepted, before the relay-size and
        // queue checks below: a body failure that follows is still an exchange that received it.
        if (!nativeControl && isCodexWsTerminalEvent(type)) {
          terminalEvent = type;
          terminalErrorStatus = type === "error" ? (codexWsWrapperStatus(normalized.payload) ?? null) : null;
        }
      }
      const prefix = encoder.encode(`event: ${type}\ndata: `);
      const suffix = encoder.encode("\n\n");
      const frameBytes = prefix.byteLength + encodedText.byteLength + suffix.byteLength;
      if (frameBytes > MAX_CLIENT_SSE_FRAME_BYTES) {
        failStream("codex websocket frame exceeds the response size limit");
        return;
      }
      const availableBytes = controller.desiredSize ?? 0;
      if (frameBytes > availableBytes) {
        failStream("codex websocket response exceeded the buffered queue limit");
        return;
      }
      const sseFrame = new Uint8Array(frameBytes);
      sseFrame.set(prefix);
      sseFrame.set(encodedText, prefix.byteLength);
      sseFrame.set(suffix, prefix.byteLength + encodedText.byteLength);
      try {
        controller.enqueue(sseFrame);
      } catch {
        failStream("codex websocket response stream closed while enqueueing");
        return;
      }
      if (!controlFrame) relayedEvents += 1;
      if (nativeControl ? steeringEnded : (type === "response.completed" || type === "response.failed" || type === "response.incomplete" || type === "error")) {
        const completedId = correlation?.completed(normalized.payload) ?? null;
        terminal = true;
        cleanup();
        try { controller.close(); } catch { /* already closed */ }
        // Refresh the success record with the final counters: the commit-time
        // snapshot predates every relayed event, and the record is more useful
        // when it says what the exchange actually delivered. Still no byte
        // count — the happy path never pays it.
        if (committedResponse) {
          markCodexWsStage(committedResponse, stageRecord(null));
        }
        if (completedId && incrementalPlan && type === "response.completed") {
          completeIncrementalFrame(incrementalPlan, (normalized.payload as { response?: unknown }).response);
        }
        session.release(completedId);
        if (refusalStatus !== undefined && refusalHeaders && refusalPrelude && !responseCommitted) {
          resolveRefusal(refusalStatus, normalized.payload, refusalHeaders, refusalPrelude);
        }
      }
    };

    const onClose = (event: unknown) => {
      cleanup();
      const code = (event as { code?: unknown } | null)?.code;
      if (typeof code === "number") closeCode = code;
      if (!opened) {
        if (settledPreOpen) return;
        settledPreOpen = true;
        // Upgrade rejected (401/403/429/5xx). Retry over plain SSE so the real
        // HTTP status reaches the existing refresh/rotation handlers. No turn
        // started upstream, so the resend cannot double-generate.
        resolve(sseFallback(url, init));
        return;
      }
      if (sent && !terminal) {
        failStream(closedBeforeTerminalMessage(event, failureStage()), 502, { socketDied: true });
      }
    };

    const onError = () => {
      if (terminal || settledPreOpen) return;
      if (!opened && !sent) {
        settledPreOpen = true;
        terminal = true;
        cleanup();
        session.dispose();
        resolve(sseFallback(url, init));
      } else {
        const message = `codex websocket transport error${codexWsFailureDetail(failureStage())}`;
        failStream(message, 502, { socketDied: true });
      }
    };
    detachOwner = session.bindOwner(reason => cancelExchange(reason));
    ws.addEventListener("open", onOpen);
    ws.addEventListener("message", onMessage);
    ws.addEventListener("close", onClose);
    ws.addEventListener("error", onError);
    ws.addEventListener("pong", onPong);
    if (signal?.aborted) onAbort();
    else if (session.opened) onOpen();
  });
}
