mixdog 0.7.1

package/src/agent/orchestrator/providers/openai-oauth-ws.mjs

@@ -0,0 +1,1890 @@
+/**
+ * OpenAI Codex OAuth — WebSocket transport.
+ *
+ * Single dispatch path for the openai-oauth provider (SSE removed in
+ * v0.6.117). Uses the `responses_websockets=2026-02-06` beta WebSocket
+ * upgrade on chatgpt.com/backend-api/codex/responses. Per-session
+ * connections are pooled (5 min idle TTL, up to 8 parallel sockets per
+ * key) so subsequent tool-loop iterations can send only the incremental
+ * `input` delta plus `previous_response_id`, skipping the full
+ * tools/system/history prefix each turn.
+ *
+ * References:
+ * - pi-mono packages/ai/src/providers/openai-codex-responses.ts
+ *   (acquireWebSocket/release, get_incremental_items delta logic).
+ * - openai/codex codex-rs/core/src/client.rs (turn-state echo header).
+ *
+ * Exposes:
+ *   sendViaWebSocket({ auth, body, sendOpts, onStreamDelta, onToolCall,
+ *                      onStageChange, externalSignal, poolKey, cacheKey, iteration,
+ *                      useModel, traceCtx })
+ *
+ * The caller (openai-oauth.mjs) supplies a fully built request body and the
+ * auth bundle; this module handles connection caching, delta framing, event
+ * parsing, and tracing.
+ */
+import WebSocket from 'ws';
+import { errText } from '../../../shared/err-text.mjs';
+import { createHash, randomBytes } from 'crypto';
+import {
+    extractCachedTokens,
+    traceBridgeFetch,
+    traceBridgeSse,
+    traceBridgeUsage,
+    appendBridgeTrace,
+} from '../bridge-trace.mjs';
+import { jitterDelayMs, populateHttpStatusFromMessage } from './retry-classifier.mjs';
+import {
+    PROVIDER_RETRY_MAX_ATTEMPTS,
+    PROVIDER_WS_ACQUIRE_TIMEOUT_MS,
+    PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS,
+    PROVIDER_WS_HANDSHAKE_TIMEOUT_MS,
+    PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS,
+} from '../stall-policy.mjs';
+
+const CODEX_WS_URL = 'wss://chatgpt.com/backend-api/codex/responses';
+const OPENAI_WS_URL = 'wss://api.openai.com/v1/responses';
+const XAI_WS_URL = 'wss://api.x.ai/v1/responses';
+const WS_IDLE_MS = 5 * 60_000;
+const WS_HANDSHAKE_TIMEOUT_MS = PROVIDER_WS_HANDSHAKE_TIMEOUT_MS;
+const WS_ACQUIRE_TIMEOUT_MS = PROVIDER_WS_ACQUIRE_TIMEOUT_MS;
+// Pre-stream watchdog uses the shared provider deadline so it fails before
+// the 5-minute session slow warning.
+const WS_FIRST_MEANINGFUL_MS = PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS;
+// Pre-`response.created` deadline. Once the socket is open and the
+// response.create frame is sent, a healthy server emits response.created
+// within seconds. If it stalls past this short bound the socket has wedged
+// post-upgrade with zero server events — treat it as a fast, retryable
+// first-byte timeout rather than waiting the longer first-meaningful window.
+// Only this short window is shortened; the post-`response.created`
+// inter-chunk / reasoning span keeps the longer deadlines below.
+const WS_PRE_RESPONSE_CREATED_MS = (() => {
+    const raw = process.env.MIXDOG_PROVIDER_WS_PRE_RESPONSE_CREATED_TIMEOUT_MS;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) return Math.min(Math.max(n, 1_000), 120_000);
+    return 10_000;
+})();
+// Inter-chunk inactivity after first meaningful output.
+const WS_INTER_CHUNK_MS = PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS;
+const MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT = 2;
+const MIDSTREAM_DEFAULT_RETRY_LIMIT = 1;
+const MIDSTREAM_BACKOFF_MS = [250, 1000];
+
+// Handshake retry policy. The `ws` library surfaces a bare
+// `Opening handshake has timed out` Error after handshakeTimeout; transient
+// network blips (DNS, reset, 5xx) similarly produce single-shot failures that
+// waste the caller's turn when they'd succeed on retry. We wrap the acquire
+// step with bounded exponential backoff. Permanent auth/quota (4xx) must NOT
+// retry because a second attempt will hit the same deterministic server
+// decision and just double the user-visible latency.
+// Aligned to the cross-provider default (retry-classifier DEFAULT_MAX_ATTEMPTS=5,
+// anthropic-oauth MAX_ATTEMPTS=5, withRetry-using providers all default to 5).
+// Previously 3 — bumped for parity so every provider exhausts the same number
+// of transient-5xx attempts before surfacing failure to the caller.
+const HANDSHAKE_MAX_ATTEMPTS = PROVIDER_RETRY_MAX_ATTEMPTS;
+const HANDSHAKE_BACKOFF_BASE_MS = 500;
+const HANDSHAKE_BACKOFF_CAP_MS = 5000;
+// WS socket pool buckets are keyed by `poolKey` (the per-call sessionId)
+// to isolate parallel bridge invocations — each gets its own socket so
+// a second caller cannot grab a sibling's mid-turn entry (Codex would
+// otherwise reject the new response.create with "No tool output found
+// for function call ..."). The Codex handshake `session_id` header/URL
+// uses `cacheKey` — a provider-scoped unified key (e.g. 'mixdog-codex')
+// built in manager.mjs via providerCacheKey(). All orchestrator-internal
+// dispatches targeting this provider share the same cacheKey, so the
+// server-side prompt-cache shard is shared across every role/source.
+// Codex dedupes cache by handshake session_id, not by
+// body.prompt_cache_key alone (measured 2026-04-19 after the v0.6.151
+// regression).
+const MAX_POOLED_SOCKETS_PER_KEY = 8;
+
+// poolKey -> Entry[]
+// Entry: { socket, busy, idleTimer, lastResponseId, lastRequestSansInput,
+//          lastInputLen, turnState, closing, ephemeral }
+const _wsPool = new Map();
+
+function _getPoolArr(poolKey) {
+    if (!poolKey) return null;
+    let arr = _wsPool.get(poolKey);
+    if (!arr) {
+        arr = [];
+        _wsPool.set(poolKey, arr);
+    }
+    return arr;
+}
+
+function _removeFromPool(poolKey, entry) {
+    if (!poolKey) return;
+    const arr = _wsPool.get(poolKey);
+    if (!arr) return;
+    const idx = arr.indexOf(entry);
+    if (idx >= 0) arr.splice(idx, 1);
+    if (arr.length === 0) _wsPool.delete(poolKey);
+}
+
+function _scheduleIdleClose(poolKey, entry) {
+    if (!entry) return;
+    if (entry.idleTimer) clearTimeout(entry.idleTimer);
+    entry.idleTimer = setTimeout(() => {
+        if (entry.busy) return;
+        try { entry.socket.close(1000, 'idle_timeout'); } catch {}
+        _removeFromPool(poolKey, entry);
+    }, WS_IDLE_MS);
+    try { entry.idleTimer.unref?.(); } catch {}
+}
+
+function _clearIdle(entry) {
+    if (entry?.idleTimer) {
+        clearTimeout(entry.idleTimer);
+        entry.idleTimer = null;
+    }
+}
+
+function _isOpen(entry) {
+    return entry?.socket?.readyState === WebSocket.OPEN;
+}
+
+// Awaited frame send. Asserts the socket is OPEN and resolves only after
+// the underlying transport reports the buffered write succeeded (or fails)
+// via the WebSocket send callback. Raw `socket.send(JSON.stringify(...))`
+// is fire-and-forget — a wedged or half-closed socket silently queues the
+// payload and the caller assumes it landed, then later times out waiting
+// for a server event that will never arrive. Tag any failure with
+// `wsSendFailed=true` so _classifyMidstreamError routes the next attempt
+// through a fresh socket.
+function _sendFrame(entry, frame) {
+    return new Promise((resolve, reject) => {
+        const socket = entry?.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            const err = new Error(`WS send: socket not OPEN (readyState=${socket?.readyState ?? 'n/a'})`);
+            err.wsSendFailed = true;
+            reject(err);
+            return;
+        }
+        let payload;
+        try { payload = JSON.stringify(frame); }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            err.wsSendFailed = true;
+            reject(err);
+            return;
+        }
+        try {
+            // Do NOT await the send callback: on a wedged-but-OPEN socket the
+            // ws write callback may never fire, which would hang this Promise
+            // before _streamResponse arms its first-byte watchdog. Fire and
+            // resolve immediately; transport failures surface via the socket
+            // 'error'/'close' handlers and the first-byte watchdog.
+            socket.send(payload, () => {});
+            resolve();
+        } catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            err.wsSendFailed = true;
+            reject(err);
+        }
+    });
+}
+
+function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey }) {
+    // xAI WS: do NOT pin x-grok-conv-id. Measured parallel runs show that
+    // forcing a routing shard via that header alternates cold caches across
+    // parallel workers; the automatic prompt-prefix cache holds up better
+    // when each handshake is unpinned. Reference: vercel/ai xai provider.
+    const headers = auth.type === 'xai'
+        ? {
+            'Authorization': `Bearer ${auth.apiKey}`,
+        }
+        : auth.type === 'openai-direct'
+        ? {
+            'Authorization': `Bearer ${auth.apiKey}`,
+            'OpenAI-Beta': 'responses_websockets=2026-02-06',
+        }
+        : {
+            'Authorization': `Bearer ${auth.access_token}`,
+            'chatgpt-account-id': auth.account_id || '',
+            'originator': 'mixdog',
+            'OpenAI-Beta': 'responses_websockets=2026-02-06',
+        };
+    if (sessionToken) {
+        const sid = String(sessionToken);
+        headers['session_id'] = sid;
+    }
+    // x-client-request-id must be a per-request value so server-side request
+    // traces stay distinguishable across retries / reconnects sharing the same
+    // session_id. Reusing sessionToken (= cacheKey) collapsed every request
+    // for the same conversation onto one trace bucket.
+    headers['x-client-request-id'] = randomBytes(16).toString('hex');
+    if (turnState) headers['x-codex-turn-state'] = turnState;
+    return headers;
+}
+
+// handshake session_id is the conversation slot Codex uses for in-memory
+// prefix state. All orchestrator-internal dispatches for this provider share
+// the same cacheKey (built in manager.mjs via providerCacheKey()), so they
+// share the server-side prefix-cache shard across roles/sources.
+function _mintSessionToken(cacheKey, auth) {
+    // xAI's public WebSocket endpoint uses the open connection plus
+    // response ids for continuation; unlike Codex, it does not need the
+    // Codex-specific session_id handshake shard.
+    if (auth?.type === 'xai') return null;
+    return cacheKey || 'mixdog-default';
+}
+
+function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }) {
+    const headers = _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey });
+    const baseUrl = auth.type === 'xai'
+        ? XAI_WS_URL
+        : auth.type === 'openai-direct'
+            ? OPENAI_WS_URL
+            : CODEX_WS_URL;
+    const _wsOpenStart = Date.now();
+    if (process.env.MIXDOG_DEBUG_BRIDGE) {
+        process.stderr.write(`[bridge-trace] ws-open-start url=${baseUrl} tokenHash=${createHash('sha256').update(String(sessionToken)).digest('hex').slice(0, 8)} ts=${_wsOpenStart}\n`);
+    }
+    const url = baseUrl + (sessionToken ? `?session_id=${encodeURIComponent(String(sessionToken))}` : '');
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let abortListener = null;
+        let acquireTimer = null;
+        const settle = (ok, val) => {
+            if (settled) return;
+            settled = true;
+            if (acquireTimer) {
+                clearTimeout(acquireTimer);
+                acquireTimer = null;
+            }
+            if (abortListener && externalSignal) {
+                try { externalSignal.removeEventListener('abort', abortListener); } catch {}
+            }
+            (ok ? resolve : reject)(val);
+        };
+        const socket = new WebSocket(url, { headers, handshakeTimeout: WS_HANDSHAKE_TIMEOUT_MS });
+        acquireTimer = setTimeout(() => {
+            if (settled) return;
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] ws-open-fail kind=acquire_timeout timeoutMs=${WS_ACQUIRE_TIMEOUT_MS} elapsed=${Date.now() - _wsOpenStart}ms\n`);
+            }
+            try { socket.terminate(); } catch {}
+            settle(false, Object.assign(
+                new Error(`${_wsErrLabel(auth?.type === 'xai' ? 'xai' : auth?.type === 'openai-direct' ? 'openai-direct' : 'openai-oauth')} acquire timed out before open (${WS_ACQUIRE_TIMEOUT_MS}ms)`),
+                { code: 'EWSACQUIRETIMEOUT', acquireTimeoutMs: WS_ACQUIRE_TIMEOUT_MS },
+            ));
+        }, WS_ACQUIRE_TIMEOUT_MS);
+        try { acquireTimer.unref?.(); } catch {}
+        const capturedHeaders = { turnState: null };
+        socket.once('upgrade', (res) => {
+            try {
+                const ts = res?.headers?.['x-codex-turn-state'];
+                if (typeof ts === 'string' && ts.length) capturedHeaders.turnState = ts;
+            } catch {}
+        });
+        socket.once('open', () => {
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] ws-open-ok elapsed=${Date.now() - _wsOpenStart}ms\n`);
+            }
+            settle(true, { socket, turnState: capturedHeaders.turnState });
+        });
+        socket.once('error', (err) => {
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] ws-open-fail kind=error msg=${String(err?.message || err).slice(0, 120)} elapsed=${Date.now() - _wsOpenStart}ms\n`);
+            }
+            try { socket.terminate(); } catch {}
+            settle(false, err instanceof Error ? err : Object.assign(new Error(errText(err) || 'openai-oauth WS error'), { wsErrorEvent: true, original: err }));
+        });
+        socket.once('close', (code, reason) => {
+            // Half-open handshake: the peer closed before 'open'/'error' fired
+            // (TCP RST / TLS edge). Without this the connect Promise never
+            // settles and only the 600s outer watchdog can break the stall
+            // (observed stage=requesting 601s hang). Open-path closes are
+            // no-ops here because settle() has already flipped `settled`.
+            if (settled) return;
+            try { socket.terminate(); } catch {}
+            settle(false, Object.assign(
+                new Error(`${_wsErrLabel(auth?.type === 'xai' ? 'xai' : auth?.type === 'openai-direct' ? 'openai-direct' : 'openai-oauth')} handshake closed before open (code=${code})`),
+                { wsCloseCode: code, wsCloseReason: (reason && reason.toString) ? reason.toString('utf-8') : '' }));
+        });
+        socket.once('unexpected-response', (_req, res) => {
+            if (settled) return;
+            const status = res?.statusCode || 0;
+            let body = '';
+            res.on('data', c => { if (body.length < 2048) body += c.toString('utf-8'); });
+            res.on('end', () => {
+                if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                    process.stderr.write(`[bridge-trace] ws-open-fail kind=http status=${status} body=${body.slice(0, 120)} elapsed=${Date.now() - _wsOpenStart}ms\n`);
+                }
+                try { socket.terminate(); } catch {}
+                settle(false, Object.assign(new Error(`${_wsErrLabel(auth?.type === 'xai' ? 'xai' : auth?.type === 'openai-direct' ? 'openai-direct' : 'openai-oauth')} handshake ${status}: ${body.slice(0, 200)}`), { httpStatus: status, httpBody: body }));
+            });
+        });
+        if (externalSignal) {
+            const onAbort = () => {
+                try { socket.terminate(); } catch {}
+                const reason = externalSignal.reason;
+                settle(false, reason instanceof Error ? reason : new Error(`${_wsErrLabel(auth?.type === 'xai' ? 'xai' : auth?.type === 'openai-direct' ? 'openai-direct' : 'openai-oauth')} handshake aborted`));
+            };
+            if (externalSignal.aborted) { onAbort(); return; }
+            abortListener = onAbort;
+            externalSignal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+
+async function acquireWebSocket({ auth, poolKey, cacheKey, forceFresh, externalSignal }) {
+    const _acqStart = Date.now();
+    if (process.env.MIXDOG_DEBUG_BRIDGE) {
+        process.stderr.write(`[bridge-trace] acquire-start poolKey=${poolKey} cacheKey=${cacheKey} forceFresh=${forceFresh} externalAborted=${!!externalSignal?.aborted} ts=${_acqStart}\n`);
+    }
+    if (externalSignal?.aborted) {
+        const reason = externalSignal.reason;
+        throw reason instanceof Error ? reason : new Error('Codex WS acquire aborted');
+    }
+    if (poolKey && !forceFresh) {
+        const arr = _wsPool.get(poolKey) || [];
+        // Prune dead entries first.
+        for (let i = arr.length - 1; i >= 0; i--) {
+            if (!_isOpen(arr[i]) || arr[i].closing) {
+                _clearIdle(arr[i]);
+                arr.splice(i, 1);
+            }
+        }
+        if (arr.length === 0) _wsPool.delete(poolKey);
+        // Reuse any idle open entry (cache-warm path).
+        const idle = arr.find(e => !e.busy);
+        if (idle) {
+            _clearIdle(idle);
+            idle.busy = true;
+            // Defensive: pre-existing pooled entries created before the
+            // prefix-hash field was introduced may not have it set. Normalize
+            // to null so the first delta check reads a deterministic value
+            // (and falls back to full-create instead of silently passing).
+            if (idle.lastInputPrefixHash === undefined) idle.lastInputPrefixHash = null;
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] acquire-reuse poolKey=${poolKey} openSockets=${arr.length} elapsed=${Date.now() - _acqStart}ms\n`);
+            }
+            return { entry: idle, reused: true };
+        }
+        // All entries busy and bucket at cap: fall through to ephemeral socket.
+        if (arr.length >= MAX_POOLED_SOCKETS_PER_KEY) {
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] acquire-ephemeral cacheKey=${cacheKey} reason=cap elapsed=${Date.now() - _acqStart}ms\n`);
+            }
+            const ephSessionToken = _mintSessionToken(cacheKey, auth);
+            const { socket, turnState } = await _openSocket({ auth, sessionToken: ephSessionToken, turnState: null, externalSignal, cacheKey });
+            // Drain-complete fence: same invariant as the normal acquire path —
+            // if drain fired during the await, do NOT push an ephemeral entry
+            // back into the pool.
+            if (_drainComplete) {
+                try { socket.close(1000, 'drain-complete'); } catch {}
+                throw new Error('WS pool drained — process exiting');
+            }
+            const entry = {
+                socket,
+                busy: true,
+                idleTimer: null,
+                lastResponseId: null,
+                lastRequestSansInput: null,
+                lastInputLen: 0,
+                lastInputPrefixHash: null,
+                turnState: turnState || null,
+                closing: false,
+                ephemeral: true,
+                sessionToken: ephSessionToken,
+            };
+            socket.on('close', () => { entry.closing = true; });
+            return { entry, reused: false };
+        }
+    }
+    // Parallel sockets must not inherit sibling turnState or the Codex server
+    // treats the new request as a continuation of another in-flight turn and
+    // returns "No tool output found for function call …". turnState only
+    // propagates within a single entry across its own iterations.
+    const sessionToken = _mintSessionToken(cacheKey, auth);
+    if (process.env.MIXDOG_DEBUG_BRIDGE) {
+        process.stderr.write(`[bridge-trace] acquire-new tokenHash=${createHash('sha256').update(String(sessionToken)).digest('hex').slice(0, 8)} elapsed=${Date.now() - _acqStart}ms\n`);
+    }
+    const { socket, turnState } = await _openSocket({ auth, sessionToken, turnState: null, externalSignal, cacheKey });
+    const entry = {
+        socket,
+        busy: true,
+        idleTimer: null,
+        lastResponseId: null,
+        lastRequestSansInput: null,
+        lastInputLen: 0,
+        lastInputPrefixHash: null,
+        turnState: turnState || null,
+        closing: false,
+        ephemeral: false,
+        sessionToken,
+    };
+    if (poolKey && !forceFresh) _getPoolArr(poolKey).push(entry);
+    socket.on('close', () => {
+        entry.closing = true;
+        _removeFromPool(poolKey, entry);
+    });
+    return { entry, reused: false };
+}
+
+function releaseWebSocket({ entry, poolKey, keep }) {
+    if (!entry) return;
+    entry.busy = false;
+    if (!keep || !_isOpen(entry) || !poolKey || entry.ephemeral) {
+        try { entry.socket.close(1000, keep ? 'no_session' : 'release_no_keep'); } catch {}
+        _removeFromPool(poolKey, entry);
+        return;
+    }
+    _scheduleIdleClose(poolKey, entry);
+}
+
+// Port of pi-mono get_incremental_items: if the cached request (sans input)
+// matches the current one and the current input starts with the cached input,
+// return only the tail. Otherwise return the full input (fresh turn).
+function _sansInput(body) {
+    const { input: _ignored, ...rest } = body;
+    return rest;
+}
+
+function _stableStringify(obj) {
+    // Shallow stable-ish: JSON.stringify with sorted top-level keys. Nested
+    // arrays (tools, include) are order-sensitive and reflect intent, so we
+    // do not sort them.
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return JSON.stringify(obj);
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (const k of keys) parts.push(JSON.stringify(k) + ':' + _stableStringify(obj[k]));
+    return '{' + parts.join(',') + '}';
+}
+
+function _computeDelta({ entry, body }) {
+    if (!entry || !entry.lastRequestSansInput || !entry.lastResponseId) {
+        return { mode: 'full', frame: { type: 'response.create', ...body } };
+    }
+    const curSans = _stableStringify(_sansInput(body));
+    if (curSans !== entry.lastRequestSansInput) {
+        return { mode: 'full', frame: { type: 'response.create', ...body } };
+    }
+    const prevLen = entry.lastInputLen | 0;
+    const curInput = Array.isArray(body.input) ? body.input : [];
+    if (curInput.length < prevLen) {
+        return { mode: 'full', frame: { type: 'response.create', ...body } };
+    }
+    // Prefix integrity guard: the cached state on `entry` only stays valid
+    // if the current request's first `prevLen` items are byte-identical to
+    // the prior full input. If anything in the prefix mutated (a tool result
+    // got rewritten, a reasoning item dropped, a system note rotated) the
+    // server would mis-anchor the delta. Compare a sha256 of the serialized
+    // prefix against the hash captured on the previous success. Mismatch →
+    // fall back to a full create for this turn only; the entry itself stays
+    // in the pool so the next turn can retry the delta path after
+    // sendViaWebSocket refreshes the cache state.
+    // Without a hash baseline prefix integrity is unprovable — force full
+    // so sendViaWebSocket can seed the hash on success.
+    if (entry.lastInputPrefixHash == null) {
+        return { mode: 'full', frame: { type: 'response.create', ...body } };
+    }
+    const curPrefixHash = createHash('sha256')
+        .update(JSON.stringify(curInput.slice(0, prevLen)))
+        .digest('hex');
+    if (curPrefixHash !== entry.lastInputPrefixHash) {
+        return { mode: 'full', frame: { type: 'response.create', ...body } };
+    }
+    const tail = curInput.slice(prevLen);
+    return {
+        mode: 'delta',
+        frame: {
+            ...body,
+            type: 'response.create',
+            previous_response_id: entry.lastResponseId,
+            input: tail,
+        },
+    };
+}
+
+function _estimateFrameTokens(frame) {
+    try {
+        const s = JSON.stringify(frame);
+        return Math.ceil(s.length / 4);
+    } catch { return 0; }
+}
+
+function _usageNum(value) {
+    const n = Number(value || 0);
+    return Number.isFinite(n) ? n : 0;
+}
+
+function _combineUsageWithWarmup(actual, warmup) {
+    if (!warmup) return actual;
+    if (!actual) return warmup;
+    const actualRaw = actual.raw || {};
+    const warmupRaw = warmup.raw || {};
+    const actualTicks = _usageNum(actualRaw.cost_in_usd_ticks);
+    const warmupTicks = _usageNum(warmupRaw.cost_in_usd_ticks);
+    return {
+        ...actual,
+        inputTokens: _usageNum(actual.inputTokens) + _usageNum(warmup.inputTokens),
+        outputTokens: _usageNum(actual.outputTokens) + _usageNum(warmup.outputTokens),
+        cachedTokens: _usageNum(actual.cachedTokens) + _usageNum(warmup.cachedTokens),
+        promptTokens: _usageNum(actual.promptTokens) + _usageNum(warmup.promptTokens),
+        warmupInputTokens: _usageNum(warmup.inputTokens),
+        warmupCachedTokens: _usageNum(warmup.cachedTokens),
+        warmupOutputTokens: _usageNum(warmup.outputTokens),
+        raw: {
+            ...actualRaw,
+            warmup_usage: warmupRaw,
+            ...(actualTicks || warmupTicks ? { cost_in_usd_ticks: actualTicks + warmupTicks } : {}),
+        },
+    };
+}
+
+function _parseEvent(raw) {
+    try { return JSON.parse(raw); } catch { return null; }
+}
+
+function _httpStatusFromWsClose(code, reason) {
+    const n = Number(code || 0);
+    const r = String(reason || '').toLowerCase();
+    if (n === 4401
+        || /\b(?:unauthorized|unauthorised|authentication|auth(?:enticated?)?|not authenticated|token expired|access token)\b/.test(r)) {
+        return 401;
+    }
+    if (n === 4403 || /\b(?:forbidden|policy|permission denied)\b/.test(r)) return 403;
+    if (n === 4429 || /\b(?:rate limit|quota)\b/.test(r)) return 429;
+    return 0;
+}
+
+function _wsErrLabel(p) {
+    if (p === 'xai') return 'xAI WS';
+    if (p === 'openai-direct' || p === 'openai') return 'OpenAI WS';
+    return 'Codex WS';
+}
+async function _streamResponse({ entry, externalSignal, onStreamDelta, onToolCall, state, logSuppressedReasoningDeltas = true, traceProvider = 'openai-oauth' }) {
+    const errLabel = _wsErrLabel(traceProvider);
+    const socket = entry.socket;
+    const _streamingStart = Date.now();
+    let _firstDeltaEmitted = false;
+    let content = '';
+    let model = '';
+    let responseId = '';
+    let responseServiceTier = '';
+    const toolCalls = [];
+    const webSearchCalls = [];
+    const webSearchCallKeys = new Set();
+    const citations = [];
+    const citationKeys = new Set();
+    const pendingCalls = new Map();
+    // Reasoning items collected from response.output_item.done (or salvaged
+    // from response.completed.response.output). The request still includes
+    // `reasoning.encrypted_content` so the server keeps emitting the blobs,
+    // but explicit input-side replay is INTENTIONALLY OMITTED in
+    // convertMessagesToResponsesInput (openai-oauth.mjs:233-238) — Codex
+    // rejects the same `rs_*` id twice in one handshake session_id with a
+    // "Duplicate item" error. Server-side conversation state already carries
+    // the prefix forward across the WS_IDLE_MS window. The collected
+    // reasoningItems below are surfaced for trace/debugging only; they do
+    // not feed back into the next request body.
+    const reasoningItems = [];
+    let reasoningTextDeltaCount = 0;
+    let reasoningSummaryTextDeltaCount = 0;
+    let reasoningOtherDeltaCount = 0;
+    let reasoningDeltaLogEmitted = false;
+    const pushReasoningItem = (item) => {
+        if (!item || item.type !== 'reasoning') return;
+        if (!item.encrypted_content) return;
+        reasoningItems.push({
+            id: item.id || '',
+            encrypted_content: item.encrypted_content,
+            summary: Array.isArray(item.summary) ? item.summary : [],
+        });
+    };
+    const pushCitation = (raw, fallbackTitle = '') => {
+        const url = raw?.url || raw?.uri || raw?.href || '';
+        if (!url || citationKeys.has(url)) return;
+        citationKeys.add(url);
+        citations.push({
+            title: raw?.title || fallbackTitle || '',
+            url,
+            snippet: raw?.snippet || raw?.text || raw?.description || '',
+            source: 'openai-oauth',
+        });
+    };
+    const pushOutputTextAnnotations = (contentPart) => {
+        const annotations = Array.isArray(contentPart?.annotations) ? contentPart.annotations : [];
+        for (const annotation of annotations) pushCitation(annotation);
+    };
+    const pushWebSearchCall = (item) => {
+        if (!item || item.type !== 'web_search_call') return;
+        let key = item.id || '';
+        if (!key) {
+            try { key = JSON.stringify(item.action || item); } catch { key = `${webSearchCalls.length}`; }
+        }
+        if (webSearchCallKeys.has(key)) return;
+        webSearchCallKeys.add(key);
+        webSearchCalls.push({
+            id: item.id || '',
+            status: item.status || '',
+            action: item.action || null,
+        });
+        const action = item.action || {};
+        if (action.url) pushCitation({ url: action.url, title: action.query || '' });
+        if (Array.isArray(action.urls)) {
+            for (const url of action.urls) pushCitation({ url, title: action.query || '' });
+        }
+    };
+    const logReasoningDeltaSuppression = () => {
+        if (!logSuppressedReasoningDeltas) return;
+        const total = reasoningTextDeltaCount + reasoningSummaryTextDeltaCount + reasoningOtherDeltaCount;
+        if (reasoningDeltaLogEmitted || total === 0) return;
+        reasoningDeltaLogEmitted = true;
+        process.stderr.write(`[openai-oauth-ws] suppressed reasoning text deltas from user content count=${total} text=${reasoningTextDeltaCount} summary=${reasoningSummaryTextDeltaCount} other=${reasoningOtherDeltaCount}\n`);
+    };
+    let usage;
+    let done = false;
+    let terminalError = null;
+    // Mid-stream retry classifier needs to distinguish "stream died before we
+    // even saw response.created" from "stream died after we had a partial
+    // response but before completion". Mutate the shared state object so the
+    // caller can inspect flags on the error path without us having to attach
+    // them manually at every reject site.
+    const midState = state || {};
+    midState.sawResponseCreated = midState.sawResponseCreated || false;
+    midState.sawCompleted = midState.sawCompleted || false;
+    midState.wsCloseCode = null;
+    midState.responseFailedPayload = null;
+    let idleTimer = null;
+    let keepaliveTimer = null;
+    let abortHandler = null;
+    let messageHandler = null;
+    let closeHandler = null;
+    let errorHandler = null;
+
+    return new Promise((resolve, reject) => {
+        // Pre-stream watchdog: the timer fires if the server never sends a
+        // first event (response.created) within WS_PRE_RESPONSE_CREATED_MS
+        // after our last frame. The socket is open and the response.create
+        // frame was sent, but no server event has come back — a wedged
+        // post-upgrade socket. Healthy servers ack within seconds, so this
+        // window is intentionally short (~25s). Once response.created (or
+        // any other meaningful event) arrives, the timer is cancelled and
+        // the longer inter-chunk inactivity watchdog takes over — silent
+        // gaps mid-reasoning (Codex spending 50s+ producing reasoning
+        // tokens) are normal and should not abort the turn.
+        const armPreStreamWatchdog = () => {
+            if (idleTimer) clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                    process.stderr.write(`[bridge-trace] ws-timeout kind=first-byte afterMs=${WS_PRE_RESPONSE_CREATED_MS}\n`);
+                }
+                const err = new Error(`WS stream: no first server event within ${WS_PRE_RESPONSE_CREATED_MS}ms`);
+                // Tag the close code so _classifyMidstreamError sees a 4000
+                // (our local pre-stream watchdog code) and routes through
+                // the post-upgrade-no-first-event retryable bucket.
+                err.wsCloseCode = 4000;
+                // Tag the error object itself (not just midState): the warmup
+                // path streams under a separate warmupState and rethrows on
+                // timeout BEFORE it can copy flags to the outer midState, so the
+                // outer catch's _classifyMidstreamError would otherwise see
+                // sawResponseCreated=false + close 4000 and hit the pre-created
+                // deny gate. err.firstByteTimeout makes both paths retryable.
+                err.firstByteTimeout = true;
+                midState.firstByteTimeout = true;
+                terminalError = err;
+                try { socket.close(4000, 'first_byte_timeout'); } catch {}
+                // socket.close() may not settle a half-open WS (closeHandler never
+                // fires) — reject directly so the turn retries instead of hanging
+                // until the 600s watchdog. finish() is idempotent (Promise settles
+                // once; cleanup is null-safe).
+                finish();
+            }, WS_PRE_RESPONSE_CREATED_MS);
+        };
+        let interChunkTimer = null;
+        let firstMeaningfulSeen = false;
+        const resetInterChunk = () => {
+            if (interChunkTimer) clearTimeout(interChunkTimer);
+            interChunkTimer = setTimeout(() => {
+                if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                    process.stderr.write(`[bridge-trace] ws-timeout kind=inter-chunk afterMs=${WS_INTER_CHUNK_MS}\n`);
+                }
+                terminalError = new Error(`WS stream: inter-chunk inactivity for ${WS_INTER_CHUNK_MS}ms`);
+                try { socket.close(4000, 'inter_chunk_timeout'); } catch {}
+                // Same half-open guard as the pre-stream watchdog: reject directly
+                // so a stuck socket.close() cannot leave the Promise pending.
+                finish();
+            }, WS_INTER_CHUNK_MS);
+        };
+        // Called on every event that carries real output tokens or tool progress.
+        // Disarms the pre-stream watchdog on first occurrence; thereafter resets
+        // the rolling inter-chunk inactivity timer.
+        const onMeaningfulOutput = () => {
+            if (!firstMeaningfulSeen) {
+                firstMeaningfulSeen = true;
+                if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+            }
+            resetInterChunk();
+        };
+        // resetIdle kept for compat; metadata frames no longer disarm pre-stream watchdog.
+        const resetIdle = () => { /* noop — only onMeaningfulOutput() disarms */ };
+        const cleanup = () => {
+            if (idleTimer) clearTimeout(idleTimer);
+            if (interChunkTimer) { clearTimeout(interChunkTimer); interChunkTimer = null; }
+            if (keepaliveTimer) { clearInterval(keepaliveTimer); keepaliveTimer = null; }
+            if (messageHandler) socket.off('message', messageHandler);
+            if (closeHandler) socket.off('close', closeHandler);
+            if (errorHandler) socket.off('error', errorHandler);
+            if (abortHandler && externalSignal) externalSignal.removeEventListener('abort', abortHandler);
+        };
+        const finish = () => {
+            logReasoningDeltaSuppression();
+            cleanup();
+            if (terminalError) { reject(terminalError); return; }
+            resolve({
+                content,
+                model,
+                reasoningItems: reasoningItems.length ? reasoningItems : undefined,
+                toolCalls: toolCalls.length ? toolCalls : undefined,
+                citations: citations.length ? citations : undefined,
+                webSearchCalls: webSearchCalls.length ? webSearchCalls : undefined,
+                usage,
+                responseId: responseId || undefined,
+                serviceTier: responseServiceTier || undefined,
+            });
+        };
+
+        messageHandler = (data) => {
+            resetIdle();
+            // Do NOT call onStreamDelta for every frame — metadata/keepalive frames
+            // must not reset bridge-stall-watchdog's lastStreamDeltaAt. Only
+            // meaningful output (text delta / tool call) updates that timestamp.
+            const text = typeof data === 'string' ? data : data.toString('utf-8');
+            const event = _parseEvent(text);
+            if (!event) return;
+            if (event.error) {
+                const err = new Error(event.error.message || 'Responses WS error');
+                try {
+                    err.payload = event.error;
+                    populateHttpStatusFromMessage(err);
+                } catch {}
+                terminalError = err;
+                finish();
+                return;
+            }
+            if (typeof event.type !== 'string') return;
+            switch (event.type) {
+                case 'response.created':
+                    midState.sawResponseCreated = true;
+                    if (event.response?.model) model = event.response.model;
+                    if (event.response?.id) responseId = event.response.id;
+                    // Server ack — cancel the short pre-`response.created`
+                    // watchdog and arm the longer inter-chunk inactivity
+                    // timer for the remainder of the stream. Reasoning
+                    // silences post-ack are normal and must not trip the
+                    // 25s first-byte deadline.
+                    onMeaningfulOutput();
+                    break;
+                case 'response.output_text.delta':
+                    content += event.delta || '';
+                    try {
+                        if (!_firstDeltaEmitted) {
+                            _firstDeltaEmitted = true;
+                            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                                process.stderr.write(`[bridge-trace] ws-first-delta sinceStreaming=${Date.now() - _streamingStart}ms\n`);
+                            }
+                        }
+                        onStreamDelta?.();
+                    } catch {}
+                    onMeaningfulOutput();
+                    break;
+                case 'response.reasoning_text.delta':
+                case 'response.reasoning_summary_text.delta':
+                    if (event.type === 'response.reasoning_text.delta') reasoningTextDeltaCount += 1;
+                    else reasoningSummaryTextDeltaCount += 1;
+                    // Reasoning text is live model progress — refresh
+                    // lastStreamDeltaAt so stream-watchdog does not flag a
+                    // long reasoning span as a stall. It also counts as
+                    // liveness for the local pre-stream / inter-chunk
+                    // watchdogs: a long reasoning span without any
+                    // output_text delta would otherwise trip the
+                    // first-meaningful timer and abort an otherwise healthy
+                    // stream. Reasoning is still suppressed from user
+                    // content (no `content +=` here) — only the watchdog
+                    // timers are reset.
+                    try { onStreamDelta?.(); } catch {}
+                    onMeaningfulOutput();
+                    break;
+                case 'response.output_item.added':
+                    if (event.item?.type === 'function_call') {
+                        pendingCalls.set(event.item.id || '', {
+                            name: event.item.name || '',
+                            callId: event.item.call_id || '',
+                        });
+                    }
+                    break;
+                case 'response.function_call_arguments.delta':
+                    try { onStreamDelta?.(); } catch {}
+                    onMeaningfulOutput();
+                    break;
+                case 'response.function_call_arguments.done': {
+                    const itemId = event.item_id || '';
+                    const pending = pendingCalls.get(itemId);
+                    let args = {};
+                    try { args = JSON.parse(event.arguments || '{}'); } catch {}
+                    if (pending?.callId && pending?.name) {
+                        const call = { id: pending.callId, name: pending.name, arguments: args };
+                        toolCalls.push(call);
+                        midState.emittedToolCall = true;
+                        try { onToolCall?.(call); } catch {}
+                    } else {
+                        // Synthesizing a `tc_${Date.now()}` callId here would
+                        // make the next turn fail to match the model's
+                        // function_call_output reference. Defer instead and
+                        // salvage call_id/name from the final
+                        // response.completed.output bundle below. If salvage
+                        // also fails we fail the stream explicitly — masking
+                        // the gap with a synthetic id just shifts the failure
+                        // one turn later under a confusing "No tool output
+                        // found for function call" error.
+                        toolCalls.push({
+                            id: pending?.callId || '',
+                            name: pending?.name || '',
+                            arguments: args,
+                            _pendingItemId: itemId,
+                            _deferred: true,
+                        });
+                    }
+                    try { onStreamDelta?.(); } catch {}
+                    break;
+                }
+                case 'response.output_item.done':
+                    // function_call / output_text already captured via their
+                    // dedicated streaming events. The one shape we still need
+                    // here is `reasoning` — carries encrypted_content that
+                    // must be replayed on the next input to keep the Codex
+                    // server-side prompt cache prefix warm.
+                    if (event.item?.type === 'reasoning') pushReasoningItem(event.item);
+                    if (event.item?.type === 'web_search_call') pushWebSearchCall(event.item);
+                    break;
+                case 'response.completed': {
+                    const completedServiceTier = event.response?.service_tier || event.response?.serviceTier || '';
+                    if (completedServiceTier) responseServiceTier = String(completedServiceTier);
+                    if (event.response?.usage) {
+                        const u = event.response.usage;
+                        const rawUsage = responseServiceTier
+                            ? { ...u, service_tier: responseServiceTier }
+                            : u;
+                        usage = {
+                            inputTokens: u.input_tokens || 0,
+                            outputTokens: u.output_tokens || 0,
+                            cachedTokens: extractCachedTokens(u),
+                            // OpenAI Codex reports input_tokens as the total
+                            // prompt volume (cached portion is a subset, not
+                            // additive). Alias into the cross-provider
+                            // `promptTokens` field so downstream loggers have
+                            // uniform semantics.
+                            promptTokens: u.input_tokens || 0,
+                            raw: rawUsage,
+                        };
+                    }
+                    if (!model && event.response?.model) model = event.response.model;
+                    if (!responseId && event.response?.id) responseId = event.response.id;
+                    if (event.response?.output) {
+                        for (const item of event.response.output) {
+                            if (!content && item.type === 'message') {
+                                for (const c of item.content || []) {
+                                    if (c.type === 'output_text') {
+                                        content += c.text || '';
+                                        pushOutputTextAnnotations(c);
+                                    }
+                                }
+                            }
+                            if (item.type === 'message') {
+                                for (const c of item.content || []) {
+                                    if (c.type === 'output_text') pushOutputTextAnnotations(c);
+                                }
+                            }
+                            if (item.type === 'web_search_call') pushWebSearchCall(item);
+                            // Salvage path: some streams emit reasoning only
+                            // inside the final response.completed.output
+                            // bundle (no per-item .done event). Dedup by id.
+                            if (item.type === 'reasoning'
+                                && !reasoningItems.some(r => r.id === item.id)) {
+                                pushReasoningItem(item);
+                            }
+                            // Salvage path for function_call: when
+                            // arguments.done fired before (or without) a
+                            // matching output_item.added, the deferred tool
+                            // call placeholder has empty id/name. The
+                            // completed.output bundle carries the canonical
+                            // call_id/name; fill them in and emit onToolCall.
+                            if (item.type === 'function_call') {
+                                const tc = toolCalls.find(
+                                    (t) => t._deferred && t._pendingItemId === (item.id || ''),
+                                );
+                                if (tc) {
+                                    if (!tc.id && item.call_id) tc.id = item.call_id;
+                                    if (!tc.name && item.name) tc.name = item.name;
+                                    if (tc.id && tc.name) {
+                                        delete tc._deferred;
+                                        delete tc._pendingItemId;
+                                        midState.emittedToolCall = true;
+                                        try { onToolCall?.(tc); } catch {}
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    // Salvage validation. Any deferred call still missing
+                    // id/name would propagate to the next turn as a
+                    // function_call_output the server can't anchor. Fail the
+                    // stream now so the caller sees a deterministic error
+                    // instead of a cryptic mismatch one turn later.
+                    const unresolved = toolCalls.find((t) => t._deferred);
+                    if (unresolved) {
+                        terminalError = new Error(
+                            `${errLabel} function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`,
+                        );
+                        finish();
+                        break;
+                    }
+                    midState.sawCompleted = true;
+                    done = true;
+                    finish();
+                    break;
+                }
+                case 'response.done': {
+                    // response.done is the terminal frame for some Codex
+                    // streams that never emit a separate response.completed.
+                    // Route through the same completed/failed/incomplete
+                    // normalization based on event.response.status so a
+                    // server-side abort (incomplete / failed) does not slip
+                    // through as success. status === 'completed' falls
+                    // through to the success path with sawCompleted set;
+                    // anything else is converted into a terminal error.
+                    const status = event.response?.status || '';
+                    if (status === 'failed') {
+                        midState.responseFailedPayload = event;
+                        const msg = event.response?.error?.message
+                            || event.error?.message
+                            || event.message
+                            || 'response.done failed';
+                        terminalError = Object.assign(
+                            new Error(`${errLabel} response.done failed: ${msg}`),
+                            { responseFailed: event },
+                        );
+                        populateHttpStatusFromMessage(terminalError, msg);
+                        done = true;
+                        finish();
+                        break;
+                    }
+                    if (status === 'incomplete') {
+                        const reasonObj = event.response?.incomplete_details
+                            || event.incomplete_details
+                            || event.response?.status_details
+                            || null;
+                        const reasonStr = reasonObj?.reason
+                            || event.response?.status
+                            || 'incomplete';
+                        terminalError = Object.assign(
+                            new Error(`${errLabel} response.done incomplete: ${reasonStr}`),
+                            { responseIncomplete: event, incompleteReason: reasonStr },
+                        );
+                        done = true;
+                        finish();
+                        break;
+                    }
+                    if (status && status !== 'completed') {
+                        terminalError = Object.assign(
+                            new Error(`${errLabel} response.done unexpected status: ${status}`),
+                            { responseDoneStatus: status },
+                        );
+                        done = true;
+                        finish();
+                        break;
+                    }
+                    midState.sawCompleted = true;
+                    done = true;
+                    finish();
+                    break;
+                }
+                case 'response.incomplete': {
+                    // response.incomplete is a server-side abort (max_output_tokens,
+                    // content filter, length, etc.). Surfacing it as success silently
+                    // truncates the turn; convert to a terminal error so the caller
+                    // can decide whether to retry / surface to user.
+                    const reasonObj = event.response?.incomplete_details
+                        || event.incomplete_details
+                        || event.response?.status_details
+                        || null;
+                    const reasonStr = reasonObj?.reason
+                        || event.response?.status
+                        || 'incomplete';
+                    terminalError = Object.assign(
+                        new Error(`${errLabel} response.incomplete: ${reasonStr}`),
+                        { responseIncomplete: event, incompleteReason: reasonStr },
+                    );
+                    finish();
+                    break;
+                }
+                case 'response.failed': {
+                    // Stash the payload so the mid-stream classifier can sniff
+                    // network_error / stream_disconnected without re-parsing.
+                    midState.responseFailedPayload = event;
+                    const msg = event.response?.error?.message
+                        || event.error?.message
+                        || event.message
+                        || 'response.failed';
+                    terminalError = Object.assign(new Error(`${errLabel} response.failed: ${msg}`), {
+                        responseFailed: event,
+                    });
+                    // Sniff the server message for transient/auth/permanent
+                    // hints so the handshake / mid-stream retry classifiers
+                    // can route by httpStatus. Without this, server-side
+                    // events like "Our servers are currently overloaded"
+                    // surfaced as unclassified errors and skipped the
+                    // 5xx retry bucket entirely.
+                    populateHttpStatusFromMessage(terminalError, msg);
+                    finish();
+                    break;
+                }
+                case 'error': {
+                    const errMsg = String(event.message || event.error?.message || 'unknown');
+                    terminalError = new Error(`${errLabel} error: ${errMsg}`);
+                    populateHttpStatusFromMessage(terminalError, errMsg);
+                    finish();
+                    break;
+                }
+                default:
+                    // Catch any other reasoning-delta variants (e.g.
+                    // `response.reasoning.<sub>.delta`) so they are counted
+                    // and suppressed, never reaching the user content buffer.
+                    if (typeof event.type === 'string'
+                        && event.type.startsWith('response.reasoning')
+                        && event.type.endsWith('.delta')) {
+                        reasoningOtherDeltaCount += 1;
+                    }
+                    // Trace-only events (response.in_progress, etc.)
+                    break;
+            }
+        };
+        closeHandler = (code, reason) => {
+            if (done) return;
+            midState.wsCloseCode = code;
+            if (!terminalError) {
+                const r = reason?.toString?.('utf-8') || '';
+                const httpStatus = _httpStatusFromWsClose(code, r);
+                terminalError = Object.assign(
+                    new Error(`Codex WS closed before response.completed (code=${code}${r ? `, reason=${r}` : ''})`),
+                    { wsCloseCode: code, wsCloseReason: r, ...(httpStatus ? { httpStatus } : {}) },
+                );
+            } else if (terminalError && !terminalError.wsCloseCode) {
+                try { terminalError.wsCloseCode = code; } catch {}
+                try { terminalError.httpStatus = terminalError.httpStatus || _httpStatusFromWsClose(code, reason?.toString?.('utf-8') || ''); } catch {}
+            }
+            finish();
+        };
+        errorHandler = (err) => {
+            if (done) return;
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            if (terminalError) {
+                // Preserve the first terminalError; chain the later socket
+                // error in via `cause` (or `suppressed` if cause already set)
+                // so diagnostics keep the original failure visible.
+                try {
+                    if (!terminalError.cause) terminalError.cause = wrapped;
+                    else {
+                        const list = Array.isArray(terminalError.suppressed)
+                            ? terminalError.suppressed
+                            : [];
+                        list.push(wrapped);
+                        terminalError.suppressed = list;
+                    }
+                } catch {}
+            } else {
+                terminalError = wrapped;
+            }
+            try { socket.close(4001, 'stream_error'); } catch {}
+            finish();
+        };
+        if (externalSignal) {
+            abortHandler = () => {
+                if (done) return;
+                const reason = externalSignal.reason;
+                terminalError = reason instanceof Error ? reason : new Error('Codex WS aborted by session close');
+                // Tag: was this a user/caller abort, or a watchdog abort?
+                // Mid-stream retry must skip user aborts but may retry watchdog
+                // aborts. The caller-owned AbortController surfaces through
+                // externalSignal; bridge-stall-watchdog signals via a reason
+                // object whose name === 'BridgeStallAbortError'. stream-watchdog
+                // uses StreamStalledAbortError. Anything else → treat as user.
+                const reasonName = reason?.name || '';
+                if (reasonName === 'BridgeStallAbortError'
+                    || reasonName === 'StreamStalledAbortError') {
+                    midState.watchdogAbort = reasonName;
+                } else {
+                    midState.userAbort = true;
+                }
+                try { socket.close(4002, 'aborted'); } catch {}
+                finish();
+            };
+            if (externalSignal.aborted) { abortHandler(); return; }
+            externalSignal.addEventListener('abort', abortHandler, { once: true });
+        }
+        socket.on('message', messageHandler);
+        socket.on('close', closeHandler);
+        socket.on('error', errorHandler);
+        armPreStreamWatchdog();
+        // Periodic client-side WS ping while the stream is active. Codex's
+        // server closes with 1011 "keepalive ping timeout" when it thinks the
+        // peer is silent during long reasoning windows where no data frames
+        // flow. Sending a ping every 18s from our side keeps the socket warm.
+        // The interval is unref'd so it never holds the event loop open, and
+        // cleanup() clears it on every terminal path (completed / close /
+        // error / abort / mid-stream retry teardown).
+        keepaliveTimer = setInterval(() => {
+            try {
+                if (socket.readyState !== WebSocket.OPEN) return;
+                socket.ping();
+            } catch {}
+        }, 18_000);
+        try { keepaliveTimer.unref?.(); } catch {}
+    });
+}
+
+/**
+ * Classify a handshake error for retry eligibility.
+ *
+ * Default-deny: anything we don't recognize as transient returns null (treat
+ * as permanent). Permanent buckets (401/403/404/429) also return null — the
+ * server has made a deterministic decision that a retry can't change.
+ *
+ * Returns one of:
+ *   'timeout' — `ws` handshakeTimeout fired
+ *   'reset'   — ECONNRESET / socket hang up
+ *   'dns'     — EAI_AGAIN / ENOTFOUND / EAI_NODATA
+ *   'refused' — ECONNREFUSED
+ *   'network' — ENETUNREACH / EHOSTUNREACH / EPIPE
+ *   'acquire_timeout' — hard client-side open/acquire deadline fired
+ *   'http_5xx' (with specific status e.g. 'http_503') — server overload
+ *   null      — not retryable
+ */
+export function _classifyHandshakeError(err) {
+    if (!err) return null;
+    const code = err.code || '';
+    const msg = String(err.message || '');
+    const status = Number(err.httpStatus || 0);
+
+    // Permanent HTTP (auth / quota / not-found) short-circuits.
+    if (status === 401 || status === 403 || status === 404 || status === 429) {
+        return null;
+    }
+    // 5xx transient.
+    if (status >= 500 && status < 600) {
+        return `http_${status}`;
+    }
+
+    // Node errno codes.
+    if (code === 'ECONNRESET') return 'reset';
+    if (code === 'EAI_AGAIN' || code === 'ENOTFOUND' || code === 'EAI_NODATA') return 'dns';
+    if (code === 'ECONNREFUSED') return 'refused';
+    if (code === 'ETIMEDOUT' || code === 'ESOCKETTIMEDOUT') return 'timeout';
+    if (code === 'EWSACQUIRETIMEOUT') return 'acquire_timeout';
+    if (code === 'ENETUNREACH' || code === 'EHOSTUNREACH' || code === 'EPIPE') return 'network';
+
+    // `ws` library's handshake-timeout path: thrown as a bare Error.
+    if (/opening handshake has timed out/i.test(msg)) return 'timeout';
+    if (/socket hang up/i.test(msg)) return 'reset';
+
+    return null;
+}
+
+/**
+ * Classify a mid-stream error for bounded retry eligibility.
+ *
+ * Only fires AFTER `response.created` is observed and BEFORE
+ * `response.completed`. The window is narrow on purpose: retrying a handshake
+ * or a pre-create connect failure is owned by _acquireWithRetry; retrying
+ * after completion would replay a finished turn.
+ *
+ * Retry buckets:
+ *   'bridge_stall'       — BridgeStallAbortError from bridge-stall-watchdog
+ *   'stream_stalled'     — StreamStalledAbortError from stream-watchdog
+ *   'ws_1006'            — abnormal close (connection lost)
+ *   'ws_1011'            — server unexpected condition
+ *   'ws_1012'            — service restart
+ *   'ws_4000'            — our armPreStreamWatchdog close with idle_timeout
+ *   'ws_1000'            — server-side normal close fired after response.created
+ *                          but before response.completed (truncated stream)
+ *   'first_byte_timeout' — post-upgrade-no-first-event: socket opened, our
+ *                          response.create frame sent, but the server never
+ *                          emitted response.created within the short
+ *                          pre-stream deadline. Fast-fail retryable.
+ *   'response_failed_network'       — response.failed with network_error
+ *   'response_failed_disconnected'  — response.failed with stream_disconnected
+ *
+ * Deny buckets (return null):
+ *   - externalSignal aborted by user (state.userAbort)
+ *   - state.sawCompleted === true (already done)
+ *   - state.sawResponseCreated === false (still pre-stream; handshake retry
+ *     owns that window) — EXCEPT for WS close 1011/1012, which can fire
+ *     after the 101 upgrade but before the first response.created event,
+ *     AND the pre-`response.created` first-byte timeout
+ *     (state.firstByteTimeout), which is permitted a bounded retry here
+ *   - HTTP 401 / 403 / 429 surfaced on the error
+ *   - state.attemptIndex has reached the classifier-specific retry budget
+ */
+export function _classifyMidstreamError(err, state) {
+    if (!state) return null;
+    const attemptIndex = state.attemptIndex | 0;
+    // Already completed (shouldn't throw, but defensive).
+    if (state.sawCompleted) return null;
+    // Any tool call already surfaced to the caller — retrying would
+    // normally duplicate the side effect. EXCEPTION: ws_1000 truncation
+    // (server-side normal close after response.created, before completion)
+    // leaves the caller with an orphaned tool_use that the next turn cannot
+    // pair to a tool_result, which the provider rejects with a hard 400.
+    // The duplicate-side-effect risk is preferable to deterministic worker
+    // death, especially for detached bridges that re-dispatch idempotently.
+    if (state.emittedToolCall) {
+        const _cc = Number(err?.wsCloseCode || state.wsCloseCode || 0);
+        if (!(_cc === 1000 && state.sawResponseCreated && !state.sawCompleted)) return null;
+    }
+    // Post-upgrade-no-first-event: the socket opened, our response.create
+    // frame was sent, but the server never emitted a single event before
+    // the short pre-`response.created` watchdog fired. The handshake retry
+    // layer only sees pre-upgrade failures and the legacy pre-stream gate
+    // below would deny this case (sawResponseCreated === false). Tag it
+    // here as a fast retryable bucket so the worker reconnects within
+    // seconds instead of stalling for the full first-meaningful window.
+    if (state.firstByteTimeout || err?.firstByteTimeout) {
+        return _allowMidstreamRetry('first_byte_timeout', attemptIndex);
+    }
+    // _sendFrame failure (socket not OPEN, send callback errored, JSON
+    // serialize threw). Always retryable: caller will forceFresh next
+    // attempt so the wedged socket is dropped.
+    if (err?.wsSendFailed || state.wsSendFailed) {
+        return _allowMidstreamRetry('ws_send_failed', attemptIndex);
+    }
+    // Pre-stream failures normally belong to the handshake retry layer. BUT
+    // WS close 1011 / 1012 can fire after the 101 upgrade but BEFORE the
+    // first response.created event when the server's keepalive times out or
+    // the service restarts. Neither the handshake retry layer (it only sees
+    // pre-upgrade failures) nor the existing mid-stream gate covers this
+    // window, so permit bounded retry here for those two codes only.
+    if (!state.sawResponseCreated) {
+        const closeCode = Number(err?.wsCloseCode || state.wsCloseCode || 0);
+        if (closeCode !== 1011 && closeCode !== 1012) return null;
+    }
+    // User/caller abort — never retry.
+    if (state.userAbort) return null;
+
+    if (!err) return null;
+    const status = Number(err?.httpStatus || 0);
+    if (status === 401 || status === 403 || status === 429) return null;
+    // Transient 5xx surfaced via populateHttpStatusFromMessage (case 'error'
+    // and case 'response.failed' branches sniff server-supplied text like
+    // "Our servers are currently overloaded" and assign httpStatus=503).
+    // Allow one bounded mid-stream retry on the same budget as the WS close-
+    // code buckets above so server-side overload no longer leaks straight
+    // to the caller without a single retry attempt.
+    if (status >= 500 && status < 600) {
+        return _allowMidstreamRetry(`http_${status}`, attemptIndex);
+    }
+
+    const name = err?.name || '';
+    if (name === 'BridgeStallAbortError') return _allowMidstreamRetry('bridge_stall', attemptIndex);
+    if (name === 'StreamStalledAbortError') return _allowMidstreamRetry('stream_stalled', attemptIndex);
+
+    // Watchdog abort surfaced via externalSignal handler → err is the reason
+    // itself. state.watchdogAbort captures the class name when the error
+    // shape was preserved but the name was stripped by some wrapper.
+    if (state.watchdogAbort === 'BridgeStallAbortError') return _allowMidstreamRetry('bridge_stall', attemptIndex);
+    if (state.watchdogAbort === 'StreamStalledAbortError') return _allowMidstreamRetry('stream_stalled', attemptIndex);
+
+    // WS close codes: prefer the decorated property, fall back to state.
+    const closeCode = Number(err?.wsCloseCode || state.wsCloseCode || 0);
+    if (closeCode === 1006) return _allowMidstreamRetry('ws_1006', attemptIndex);
+    if (closeCode === 1011) return _allowMidstreamRetry('ws_1011', attemptIndex);
+    if (closeCode === 1012) return _allowMidstreamRetry('ws_1012', attemptIndex);
+    // Private 4xxx codes from a server/proxy are auth/policy/application closes;
+    // never treat them as transient. 4000 is our local pre-stream watchdog code.
+    if (closeCode >= 4000 && closeCode < 5000 && closeCode !== 4000) return null;
+    if (closeCode === 4000) return _allowMidstreamRetry('ws_4000', attemptIndex);
+    // Server-side normal close (1000) AFTER response.created but BEFORE
+    // response.completed = truncated stream; legitimate transient. The
+    // pre-stream gate above already rejects 1000 before sawResponseCreated
+    // (handshake retry layer owns that window).
+    if (closeCode === 1000 && state.sawResponseCreated && !state.sawCompleted) return _allowMidstreamRetry('ws_1000', attemptIndex);
+
+    // response.failed payload mentioning network_error / stream_disconnected.
+    // xAI's gRPC backend periodically rotates auth context (server-side TTL)
+    // and surfaces "Auth context expired" as a response.failed event. The
+    // attemptIndex > 0 path in sendViaWebSocket forces a fresh WS handshake,
+    // which re-authenticates — so a single bounded retry recovers the turn
+    // instead of letting the worker die mid-session.
+    const failed = err?.responseFailed || state.responseFailedPayload;
+    if (failed) {
+        try {
+            const blob = JSON.stringify(failed).toLowerCase();
+            if (blob.includes('stream_disconnected')) return _allowMidstreamRetry('response_failed_disconnected', attemptIndex);
+            if (blob.includes('network_error')) return _allowMidstreamRetry('response_failed_network', attemptIndex);
+            if (blob.includes('auth context expired')) return _allowMidstreamRetry('response_failed_auth_expired', attemptIndex);
+        } catch {}
+    }
+
+    // Unknown → default-deny (don't risk a second full-cost turn for an error
+    // class we haven't proven is transient).
+    return null;
+}
+
+function _midstreamRetryLimit(classifier) {
+    return classifier === 'ws_1006' || classifier === 'ws_1011'
+        ? MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT
+        : MIDSTREAM_DEFAULT_RETRY_LIMIT;
+}
+
+function _allowMidstreamRetry(classifier, attemptIndex) {
+    return attemptIndex < _midstreamRetryLimit(classifier) ? classifier : null;
+}
+
+function _midstreamBackoffFor(retryNumber) {
+    return MIDSTREAM_BACKOFF_MS[Math.min(Math.max(retryNumber, 1), MIDSTREAM_BACKOFF_MS.length) - 1];
+}
+
+function _backoffFor(attempt) {
+    // attempt is 1-based. retry 1 → 500, retry 2 → 1000, retry 3 → 2000 … capped.
+    const raw = HANDSHAKE_BACKOFF_BASE_MS * (1 << (attempt - 1));
+    return jitterDelayMs(Math.min(raw, HANDSHAKE_BACKOFF_CAP_MS));
+}
+
+const _defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function _sleepWithAbort(ms, externalSignal, sleepFn = _defaultSleep) {
+    if (!ms) return;
+    if (!externalSignal) {
+        await sleepFn(ms);
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+            externalSignal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            const reason = externalSignal.reason;
+            reject(reason instanceof Error ? reason : new Error('Codex WS retry backoff aborted'));
+        };
+        if (externalSignal.aborted) { onAbort(); return; }
+        externalSignal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+/**
+ * Run `_acquire({auth, poolKey, cacheKey})` with bounded exponential-backoff
+ * retry on transient handshake failures. The injection seams (`_acquire`,
+ * `_sleepFn`, `onRetry`) let unit tests drive the state machine without
+ * opening real sockets.
+ *
+ * On exhaustion the thrown error is tagged with:
+ *   err.attempts         — 1..HANDSHAKE_MAX_ATTEMPTS
+ *   err.retryClassifier  — final classifier string, or null for permanent
+ */
+export async function _acquireWithRetry({
+    auth,
+    poolKey,
+    cacheKey,
+    forceFresh,
+    onRetry,
+    externalSignal,
+    _acquire = acquireWebSocket,
+    _sleepFn = _defaultSleep,
+} = {}) {
+    let lastErr = null;
+    let lastClassifier = null;
+    for (let attempt = 1; attempt <= HANDSHAKE_MAX_ATTEMPTS; attempt++) {
+        if (externalSignal?.aborted) {
+            const reason = externalSignal.reason;
+            throw reason instanceof Error ? reason : new Error('Codex WS acquire aborted');
+        }
+        try {
+            if (attempt > 1) {
+                if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                    process.stderr.write(`[bridge-trace] ws-handshake-attempt n=${attempt}\n`);
+                }
+            }
+            return await _acquire({ auth, poolKey, cacheKey, forceFresh, externalSignal });
+        } catch (err) {
+            lastErr = err;
+            const classifier = _classifyHandshakeError(err);
+            lastClassifier = classifier;
+            // Permanent (or unknown → default-deny): stop immediately.
+            if (!classifier) {
+                if (err && typeof err === 'object') {
+                    try { err.attempts = attempt; } catch {}
+                    try { err.retryClassifier = null; } catch {}
+                }
+                throw err;
+            }
+            // Transient but exhausted: surface with tagging.
+            if (attempt >= HANDSHAKE_MAX_ATTEMPTS) {
+                if (err && typeof err === 'object') {
+                    try { err.attempts = attempt; } catch {}
+                    try { err.retryClassifier = classifier; } catch {}
+                }
+                try {
+                    process.stderr.write(
+                        `[openai-oauth-ws] handshake failed after ${attempt}/${HANDSHAKE_MAX_ATTEMPTS} attempts: ${err?.message || err}\n`,
+                    );
+                } catch {}
+                throw err;
+            }
+            // Schedule backoff and emit progress.
+            const backoff = _backoffFor(attempt);
+            try {
+                process.stderr.write(
+                    `[openai-oauth-ws] worker retry ${attempt}/${HANDSHAKE_MAX_ATTEMPTS} (transient: ${classifier}, backoff ${backoff}ms)\n`,
+                );
+            } catch {}
+            try {
+                onRetry?.({
+                    attempt,
+                    max: HANDSHAKE_MAX_ATTEMPTS,
+                    classifier,
+                    backoffMs: backoff,
+                    error: err,
+                });
+            } catch {}
+            // Sleep is abort-aware: an abort during backoff rejects immediately
+            // instead of burning the remaining wait.
+            if (externalSignal) {
+                await new Promise((resolve, reject) => {
+                    const t = setTimeout(() => {
+                        externalSignal.removeEventListener('abort', onAbort);
+                        resolve();
+                    }, backoff);
+                    const onAbort = () => {
+                        clearTimeout(t);
+                        const reason = externalSignal.reason;
+                        reject(reason instanceof Error ? reason : new Error('Codex WS acquire aborted'));
+                    };
+                    if (externalSignal.aborted) { onAbort(); return; }
+                    externalSignal.addEventListener('abort', onAbort, { once: true });
+                });
+            } else {
+                await _sleepFn(backoff);
+            }
+        }
+    }
+    // Unreachable — the loop either returns or throws above — but keep the
+    // typing honest.
+    if (lastErr && typeof lastErr === 'object') {
+        try { lastErr.attempts = HANDSHAKE_MAX_ATTEMPTS; } catch {}
+        try { lastErr.retryClassifier = lastClassifier; } catch {}
+    }
+    throw lastErr || new Error('acquireWithRetry: unreachable');
+}
+
+/**
+ * Dispatch one tool-loop iteration over a per-session cached WebSocket.
+ * Returns the same shape as the SSE path: { content, model, toolCalls, usage }.
+ */
+export async function sendViaWebSocket({
+    auth,
+    body,
+    sendOpts,
+    onStreamDelta,
+    onToolCall,
+    onStageChange,
+    externalSignal,
+    poolKey,
+    cacheKey,
+    iteration,
+    useModel,
+    displayModel,
+    forceFresh = false,
+    includeResponseId = false,
+    traceProvider = 'openai-oauth',
+    logSuppressedReasoningDeltas = true,
+    warmupBody = null,
+    // Test seams (undefined in production). Let the unit test drive the
+    // retry state machine without opening real sockets or touching the
+    // handshake-retry layer.
+    _acquireWithRetryFn = _acquireWithRetry,
+    _streamFn = _streamResponse,
+    _sendFrameFn = _sendFrame,
+    _sleepFn = _defaultSleep,
+}) {
+    // Bounded mid-stream retry: if an attempt's stream dies after
+    // response.created but before response.completed from a transient cause
+    // (watchdog abort / ws 1006/1011/1012/4000 / response.failed with network
+    // error), tear down the socket and reissue the full request from scratch
+    // with a classifier-specific budget. ws_1006/ws_1011 get two retries with
+    // 250ms/1s backoff; other legacy transient buckets keep the prior one retry.
+    // No delta resume — content restarts, which is the accepted tradeoff for
+    // reviewer/worker flows that need the complete answer.
+    // Retries are layered ABOVE the handshake retry loop (_acquireWithRetry
+    // owns connect-level transience); the two never interleave because we
+    // force a brand-new acquire for the retry attempt.
+    const MAX_MIDSTREAM_RETRIES = MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT;
+    let firstAttemptError = null;
+    let firstAttemptClassifier = null;
+    // Server-side xAI conversation anchor preserved across mid-stream
+    // retries. xAI keys its conversation by previous_response_id alone
+    // (sessionToken is null for xAI in _mintSessionToken); a forceFresh
+    // socket on retry would otherwise drop prev_id and cold-start a new
+    // server-side conversation, evicting every prefix the prior attempts
+    // warmed. Codex / openai-direct anchor by per-socket session_id, where
+    // this carry-forward would not help and is therefore gated to xAI.
+    let carryForwardCache = null;
+    const emittedProgress = [];
+
+    for (let attemptIndex = 0; attemptIndex <= MAX_MIDSTREAM_RETRIES; attemptIndex++) {
+        const handshakeStart = Date.now();
+        let acquired;
+        let handshakeRetries = 0;
+        const handshakeRetryClassifiers = [];
+        try { onStageChange?.('requesting'); } catch {}
+        try {
+            acquired = await _acquireWithRetryFn({
+                auth,
+                poolKey,
+                cacheKey,
+                // Retry attempt must not reuse a pooled socket — the prior
+                // one is either torn down or in an unknown state.
+                forceFresh: forceFresh || attemptIndex > 0,
+                externalSignal,
+                onRetry: (info) => {
+                    handshakeRetries += 1;
+                    if (info?.classifier) handshakeRetryClassifiers.push(info.classifier);
+                },
+            });
+        } catch (err) {
+            const classifier = err?.retryClassifier || (err?.code === 'EWSACQUIRETIMEOUT' ? 'acquire_timeout' : null);
+            const classifiers = [...handshakeRetryClassifiers];
+            if (classifier && !classifiers.includes(classifier)) classifiers.push(classifier);
+            if (err?.httpStatus != null || classifier || handshakeRetries > 0 || classifiers.length > 0) {
+                traceBridgeFetch({
+                    sessionId: poolKey,
+                    headersMs: Date.now() - handshakeStart,
+                    httpStatus: Number(err?.httpStatus || 0),
+                    provider: traceProvider,
+                    model: useModel,
+                    transport: 'websocket',
+                    handshakeRetries: err?.attempts ? Math.max(Number(err.attempts) - 1, 0) : handshakeRetries,
+                    handshakeRetryClassifiers: classifiers,
+                });
+            }
+            // Handshake-layer failure. Don't double-wrap: if this is the retry
+            // attempt, surface the ORIGINAL first-attempt error (which is what
+            // the caller's turn actually tripped on).
+            if (attemptIndex > 0 && firstAttemptError) {
+                try { firstAttemptError.midstreamRetries = attemptIndex; } catch {}
+                throw firstAttemptError;
+            }
+            throw err;
+        }
+        const { entry, reused } = acquired;
+        // Re-seed the retry attempt's fresh entry with the prior attempt's
+        // last successful anchor so _computeDelta sees a non-null
+        // lastInputPrefixHash and prev_response_id, keeping the same xAI
+        // conversation slot warm instead of cold-starting one per retry.
+        if (carryForwardCache && auth?.type === 'xai' && !reused) {
+            entry.lastResponseId = carryForwardCache.lastResponseId;
+            entry.lastInputPrefixHash = carryForwardCache.lastInputPrefixHash;
+            entry.lastInputLen = carryForwardCache.lastInputLen;
+            entry.lastRequestSansInput = carryForwardCache.lastRequestSansInput;
+        }
+        traceBridgeFetch({
+            sessionId: poolKey,
+            headersMs: Date.now() - handshakeStart,
+            httpStatus: reused ? 0 : 101,
+            provider: traceProvider,
+            model: useModel,
+            transport: 'websocket',
+            handshakeRetries,
+            handshakeRetryClassifiers,
+        });
+
+        let requestBody = body;
+        // Mid-stream retry: pin prev_id in the body so _computeDelta's
+        // mode='full' fallback (triggered when the carried prefix hash no
+        // longer matches the current input) still carries the conversation
+        // anchor. The delta path overwrites this from entry.lastResponseId,
+        // which equals the carried value, so the two paths agree.
+        if (carryForwardCache && auth?.type === 'xai' && attemptIndex > 0 && !body.previous_response_id) {
+            requestBody = { ...body, previous_response_id: carryForwardCache.lastResponseId };
+        }
+        let warmupResult = null;
+        // midState is shared between warmup and the main stream so warmup
+        // failures (first-byte timeout, send-failure, ws_4000) flow through
+        // the SAME mid-stream classifier as the main send. A wedged warmup
+        // socket must not bypass the retry loop and surface raw to the
+        // caller — release the entry, force a fresh acquire, and retry.
+        const midState = {
+            attemptIndex,
+            sawResponseCreated: false,
+            sawCompleted: false,
+        };
+        const sseStart = Date.now();
+        let mode = 'full';
+        let frame = null;
+        let deltaTokens = 0;
+        let result;
+        try {
+            if (warmupBody && typeof warmupBody === 'object' && attemptIndex === 0) {
+                const warmupFrame = { type: 'response.create', ...warmupBody };
+                await _sendFrameFn(entry, warmupFrame);
+                const warmupStart = Date.now();
+                const warmupState = {
+                    attemptIndex,
+                    sawResponseCreated: false,
+                    sawCompleted: false,
+                };
+                warmupResult = await _streamFn({
+                    entry,
+                    externalSignal,
+                    onStreamDelta: null,
+                    onToolCall: null,
+                    state: warmupState,
+                    logSuppressedReasoningDeltas,
+                    traceProvider,
+                });
+                // Surface warmup-time first-event timeout / send-failure
+                // flags onto the shared midState so the outer catch's
+                // classifier sees them. (warmupResult itself only resolves
+                // on success; failures throw and skip this block.)
+                if (warmupState.firstByteTimeout) midState.firstByteTimeout = true;
+                if (warmupState.wsSendFailed) midState.wsSendFailed = true;
+                if (!warmupResult?.responseId) {
+                    throw new Error('Responses WS warmup completed without response id');
+                }
+                entry.lastResponseId = warmupResult.responseId;
+                entry.lastRequestSansInput = _stableStringify(_sansInput(warmupBody));
+                const warmupInputArr = Array.isArray(warmupBody.input) ? warmupBody.input : [];
+                entry.lastInputLen = warmupInputArr.length;
+                entry.lastInputPrefixHash = createHash('sha256')
+                    .update(JSON.stringify(warmupInputArr))
+                    .digest('hex');
+                try {
+                    const warmupPayload = {
+                        provider: traceProvider,
+                        transport: 'websocket',
+                        event: 'warmup_completed',
+                        response_id: warmupResult.responseId,
+                        elapsed_ms: Date.now() - warmupStart,
+                        input_tokens: warmupResult.usage?.inputTokens || 0,
+                        cached_tokens: warmupResult.usage?.cachedTokens || 0,
+                        output_tokens: warmupResult.usage?.outputTokens || 0,
+                        prompt_tokens: warmupResult.usage?.promptTokens || 0,
+                    };
+                    appendBridgeTrace({
+                        sessionId: poolKey,
+                        iteration,
+                        kind: 'cache_warmup',
+                        ...warmupPayload,
+                        payload: warmupPayload,
+                    });
+                } catch {}
+                requestBody = { ...body, previous_response_id: warmupResult.responseId };
+                delete requestBody.instructions;
+                delete requestBody.generate;
+            }
+
+            ({ mode, frame } = _computeDelta({ entry, body: requestBody }));
+            deltaTokens = _estimateFrameTokens(frame);
+
+            // Re-check abort after acquire/warmup — narrow window where
+            // externalSignal could fire between successful acquire and
+            // send(). Without this gate an aborted request could still
+            // emit one frame to the provider.
+            if (externalSignal?.aborted) {
+                throw new Error('Aborted');
+            }
+            await _sendFrameFn(entry, frame);
+
+            if (process.env.MIXDOG_DEBUG_BRIDGE) {
+                process.stderr.write(`[bridge-trace] ws-streaming-start sinceAcquire=${Date.now() - handshakeStart}ms\n`);
+            }
+            try { onStageChange?.('streaming'); } catch {}
+            result = await _streamFn({
+                entry,
+                externalSignal,
+                onStreamDelta,
+                onToolCall,
+                state: midState,
+                logSuppressedReasoningDeltas,
+                traceProvider,
+            });
+        } catch (err) {
+            // Snapshot the xAI conversation anchor BEFORE releasing the
+            // entry. release closes the socket but leaves state fields
+            // intact; the next forceFresh acquire creates a new entry into
+            // which we manually carry the anchor so the retry continues the
+            // same conversation instead of cold-starting one.
+            if (auth?.type === 'xai' && entry.lastResponseId) {
+                carryForwardCache = {
+                    lastResponseId: entry.lastResponseId,
+                    lastInputPrefixHash: entry.lastInputPrefixHash,
+                    lastInputLen: entry.lastInputLen,
+                    lastRequestSansInput: entry.lastRequestSansInput,
+                };
+            }
+            releaseWebSocket({ entry, poolKey, keep: false });
+            // Mid-stream classification.
+            const classifier = _classifyMidstreamError(err, midState);
+            const retryLimit = classifier ? _midstreamRetryLimit(classifier) : 0;
+            if (classifier && attemptIndex < retryLimit) {
+                // Retry-eligible: stash the first-attempt error, emit progress,
+                // and loop. The subsequent acquire uses forceFresh so no socket
+                // is shared between attempts.
+                firstAttemptError = err;
+                firstAttemptClassifier = classifier;
+                try { err.midstreamClassifier = classifier; } catch {}
+                const retryNumber = attemptIndex + 1;
+                const backoff = _midstreamBackoffFor(retryNumber);
+                try {
+                    const line = `[openai-oauth-ws] mid-stream recovered: retry ${retryNumber}/${retryLimit} (cause: ${classifier}, backoff ${backoff}ms)\n`;
+                    process.stderr.write(line);
+                    emittedProgress.push(line);
+                } catch {}
+                await _sleepWithAbort(backoff, externalSignal, _sleepFn);
+                continue;
+            }
+            // Not retryable, OR we've already exhausted the retry budget.
+            if (attemptIndex > 0 && firstAttemptError) {
+                // Exhausted path: surface the first-attempt error (the one
+                // the user's turn actually tripped on), tag actual retry count.
+                try { firstAttemptError.midstreamRetries = attemptIndex; } catch {}
+                try { firstAttemptError.midstreamClassifier = firstAttemptClassifier; } catch {}
+                // Attach the retry attempt's error so post-mortem diagnostics
+                // can see WHY the retry also failed instead of silently
+                // dropping it. Use `cause` if free, else `suppressed`.
+                try {
+                    if (!firstAttemptError.cause) firstAttemptError.cause = err;
+                    else {
+                        const list = Array.isArray(firstAttemptError.suppressed)
+                            ? firstAttemptError.suppressed
+                            : [];
+                        list.push(err);
+                        firstAttemptError.suppressed = list;
+                    }
+                } catch {}
+                throw firstAttemptError;
+            }
+            throw err;
+        }
+        const liveModel = result.model || useModel;
+        traceBridgeSse({
+            sessionId: poolKey,
+            sseParseMs: Date.now() - sseStart,
+            provider: traceProvider,
+            model: liveModel,
+            transport: 'websocket',
+        });
+
+        // Update cache state for the next iteration in this session.
+        if (result.responseId) {
+            entry.lastResponseId = result.responseId;
+            entry.lastRequestSansInput = _stableStringify(_sansInput(requestBody));
+            const inputArr = Array.isArray(requestBody.input) ? requestBody.input : [];
+            entry.lastInputLen = inputArr.length;
+            // Capture the prefix hash for the next turn's delta integrity
+            // check. Serialize the full input (matching what _computeDelta
+            // will hash on the next turn's first prevLen items, where
+            // prevLen === inputArr.length).
+            entry.lastInputPrefixHash = createHash('sha256')
+                .update(JSON.stringify(inputArr))
+                .digest('hex');
+        }
+
+        if (warmupResult?.usage) {
+            result.usage = _combineUsageWithWarmup(result.usage, warmupResult.usage);
+        }
+
+        const requestedServiceTier = body?.service_tier || null;
+        const responseServiceTier = result.serviceTier || result.usage?.raw?.service_tier || null;
+        traceBridgeUsage({
+            sessionId: poolKey,
+            iteration,
+            inputTokens: result.usage?.inputTokens || 0,
+            outputTokens: result.usage?.outputTokens || 0,
+            cachedTokens: result.usage?.cachedTokens || 0,
+            promptTokens: result.usage?.promptTokens || 0,
+            model: liveModel,
+            modelDisplay: displayModel ? displayModel(liveModel) : liveModel,
+            responseId: result.responseId || null,
+            rawUsage: result.usage?.raw || null,
+            provider: traceProvider,
+            serviceTier: responseServiceTier,
+        });
+        // Extra WS-specific observability: transport + per-iteration delta bytes.
+        try {
+            const transportPayload = {
+                provider: traceProvider,
+                transport: 'websocket',
+                ws_mode: mode,
+                iteration_delta_tokens: deltaTokens,
+                reused_connection: reused,
+                requested_service_tier: requestedServiceTier,
+                response_service_tier: responseServiceTier,
+                handshake_retries: handshakeRetries,
+                handshake_retry_classifiers: handshakeRetryClassifiers,
+                midstream_retries: attemptIndex,
+                response_id: result.responseId || null,
+                request_has_previous_response_id: typeof frame.previous_response_id === 'string' && frame.previous_response_id.length > 0,
+                body_input_items: Array.isArray(requestBody.input) ? requestBody.input.length : null,
+                frame_input_items: Array.isArray(frame.input) ? frame.input.length : null,
+                frame_has_instructions: typeof frame.instructions === 'string' && frame.instructions.length > 0,
+                warmup_used: !!warmupResult,
+                warmup_response_id: warmupResult?.responseId || null,
+            };
+            appendBridgeTrace({
+                sessionId: poolKey,
+                iteration,
+                kind: 'transport',
+                ...transportPayload,
+                payload: transportPayload,
+            });
+        } catch {}
+
+        releaseWebSocket({ entry, poolKey, keep: true });
+        const { responseId: _ignored, ...out } = result;
+        if (includeResponseId && result.responseId) out.responseId = result.responseId;
+        if (warmupResult) {
+            try {
+                Object.defineProperty(out, '__warmup', {
+                    value: {
+                        requestBody,
+                        responseId: warmupResult.responseId,
+                        usage: warmupResult.usage,
+                    },
+                    enumerable: false,
+                });
+            } catch {}
+        }
+        // Leave a breadcrumb on the result so downstream callers can observe
+        // that a retry was used (0 = first-try success, up to 2 for ws_1006/1011).
+        try { Object.defineProperty(out, '__midstreamRetries', { value: attemptIndex, enumerable: false }); } catch {}
+        return out;
+    }
+    // Unreachable — the loop either returns or throws above.
+    throw firstAttemptError || new Error('sendViaWebSocket: unreachable');
+}
+
+// Drain-complete fence — set true once _closeAllPooledSockets runs so any
+// in-flight acquire that resumes after drain throws instead of pushing a
+// fresh socket into the cleared pool. Single-set, mirrors drain-registry's
+// process-lifetime atomic invariant.
+let _drainComplete = false;
+
+// Drain hook — registered in drain-registry external-resource bucket.
+// Force-closes pooled sockets and fences subsequent acquires.
+// `drainOpenaiWsPool` alias matches the registry's `drain*` naming convention;
+// `_closeAllPooledSockets` kept for backward compat with existing call sites.
+export function _closeAllPooledSockets(reason = 'shutdown') {
+    _drainComplete = true;
+    for (const arr of _wsPool.values()) {
+        for (const entry of arr) {
+            try { entry.socket.close(1000, reason); } catch {}
+        }
+    }
+    _wsPool.clear();
+}
+export const drainOpenaiWsPool = _closeAllPooledSockets;