mixdog 0.8.1 → 0.9.1

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

@@ -1,5 +1,5 @@
 /**
- * OpenAI Codex OAuth — WebSocket transport.
+ * OpenAI OAuth subscription — 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
@@ -28,12 +28,21 @@ 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';
+    traceAgentFetch,
+    traceAgentSse,
+    traceAgentUsage,
+    appendAgentTrace,
+} from '../agent-trace.mjs';
+import {
+    classifyHandshakeError,
+    classifyMidstreamError,
+    createStreamSafetyStamps,
+    jitterDelayMs,
+    MIDSTREAM_RETRY_POLICY,
+    populateHttpStatusFromMessage,
+    sleepWithAbort,
+} from './retry-classifier.mjs';
+import { makeInvalidToolArgsMarker } from './openai-compat-stream.mjs';
 import {
     PROVIDER_RETRY_MAX_ATTEMPTS,
     PROVIDER_WS_ACQUIRE_TIMEOUT_MS,
@@ -41,6 +50,7 @@ import {
     PROVIDER_WS_HANDSHAKE_TIMEOUT_MS,
     PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS,
 } from '../stall-policy.mjs';
+import { customToolCallFromResponseItem } from './custom-tool-wire.mjs';
 
 globalThis.__mixdogOpenaiWsRuntimeLoaded = true;
 
@@ -69,9 +79,18 @@ const WS_PRE_RESPONSE_CREATED_MS = (() => {
 })();
 // 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];
+// Mid-stream retry budgets + backoff now live in the shared MIDSTREAM_RETRY_POLICY
+// table (retry-classifier.mjs). These aliases keep the local call sites readable
+// and ensure the numbers exist in exactly ONE place.
+const MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.transientCloseRetries;
+const MIDSTREAM_DEFAULT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.defaultRetries;
+const MIDSTREAM_BACKOFF_MS = MIDSTREAM_RETRY_POLICY.ws.backoff;
+// Policy object passed to the shared classifyMidstreamError for the WS path.
+const WS_MIDSTREAM_POLICY = {
+    mode: 'ws',
+    transientCloseRetries: MIDSTREAM_RETRY_POLICY.ws.transientCloseRetries,
+    defaultRetries: MIDSTREAM_RETRY_POLICY.ws.defaultRetries,
+};
 
 // Handshake retry policy. The `ws` library surfaces a bare
 // `Opening handshake has timed out` Error after handshakeTimeout; transient
@@ -88,14 +107,14 @@ 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
+// to isolate parallel agent invocations — each gets its own socket so
+// a second caller cannot grab a sibling's mid-turn entry (openai-oauth would
 // otherwise reject the new response.create with "No tool output found
-// for function call ..."). The Codex handshake `session_id` header/URL
+// for function call ..."). The handshake `session_id` header/URL
 // uses `cacheKey` — a prefix-scoped cache key derived from the configured
 // provider namespace plus model/system/tools hash. Same-prefix sessions share
 // server-side prompt cache, while unrelated main/worker prefixes no longer
-// evict each other inside one static provider lane. Codex dedupes cache by
+// evict each other inside one static provider lane. The backend 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;
@@ -106,10 +125,10 @@ const MAX_POOLED_SOCKETS_PER_KEY = 8;
 //          closing, ephemeral }
 const _wsPool = new Map();
 
-// Final prompt_cache_key/session_id lane guard for OpenAI/Codex transports.
+// Final prompt_cache_key/session_id lane guard for OpenAI OAuth transports.
 // The provider code may shard one logical prefix into N cache keys for 10+
 // total parallelism; inside each final key we still serialize requests because
-// live Codex probes show same-key concurrent WebSockets can randomly miss the
+// Live probes show same-key concurrent WebSockets can randomly miss the
 // server prompt cache even after warm-up.
 const _openAiPromptCacheLanes = new Map();
 const _openAiPromptCacheLaneRates = new Map();
@@ -121,6 +140,11 @@ function _positiveInt(value, fallback = 0) {
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
 
+function _nonNegativeInt(value, fallback = 0) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
 function _cacheLaneHash(value) {
     return createHash('sha256').update(String(value || '')).digest('hex').slice(0, 12);
 }
@@ -146,7 +170,7 @@ function _openAiPromptCacheLaneQueueTimeoutMs(sendOpts = {}) {
 }
 
 function _openAiPromptCacheLaneRateLimitPerMin(sendOpts = {}) {
-    return _positiveInt(
+    return _nonNegativeInt(
         sendOpts?.openaiCacheLaneRateLimitPerMin
             ?? sendOpts?.promptCacheLaneRateLimitPerMin
             ?? process.env.MIXDOG_OPENAI_CACHE_LANE_RPM
@@ -155,6 +179,45 @@ function _openAiPromptCacheLaneRateLimitPerMin(sendOpts = {}) {
     );
 }
 
+function _openAiPromptCacheLaneDeltaRateLimitPerMin(sendOpts = {}) {
+    return _nonNegativeInt(
+        sendOpts?.openaiCacheLaneDeltaRateLimitPerMin
+            ?? sendOpts?.promptCacheLaneDeltaRateLimitPerMin
+            ?? process.env.MIXDOG_OPENAI_CACHE_LANE_DELTA_RPM
+            ?? process.env.MIXDOG_OPENAI_CACHE_DELTA_RPM,
+        60,
+    );
+}
+
+function _openAiPromptCacheLaneDeltaMaxItems(sendOpts = {}) {
+    return _nonNegativeInt(
+        sendOpts?.openaiCacheLaneDeltaMaxItems
+            ?? sendOpts?.promptCacheLaneDeltaMaxItems
+            ?? process.env.MIXDOG_OPENAI_CACHE_LANE_DELTA_MAX_ITEMS
+            ?? process.env.MIXDOG_OPENAI_CACHE_DELTA_MAX_ITEMS,
+        8,
+    );
+}
+
+function _openAiPromptCacheLaneDeltaMaxTokens(sendOpts = {}) {
+    return _nonNegativeInt(
+        sendOpts?.openaiCacheLaneDeltaMaxTokens
+            ?? sendOpts?.promptCacheLaneDeltaMaxTokens
+            ?? process.env.MIXDOG_OPENAI_CACHE_LANE_DELTA_MAX_TOKENS
+            ?? process.env.MIXDOG_OPENAI_CACHE_DELTA_MAX_TOKENS,
+        20_000,
+    );
+}
+
+function _openAiPromptCacheLaneSlowTraceMs(sendOpts = {}) {
+    return _positiveInt(
+        sendOpts?.openaiCacheLaneSlowTraceMs
+            ?? sendOpts?.promptCacheLaneSlowTraceMs
+            ?? process.env.MIXDOG_OPENAI_CACHE_LANE_SLOW_MS,
+        3000,
+    );
+}
+
 function _isOpenAiPromptCacheLaneAuth(auth) {
     return auth?.type !== 'xai';
 }
@@ -229,12 +292,13 @@ function _sleepWithSignal(ms, signal) {
     });
 }
 
-async function _reserveOpenAiPromptCacheLaneRate({ key, limitPerMin, signal }) {
+async function _reserveOpenAiPromptCacheLaneRate({ key, limitPerMin, signal, beforeWait }) {
     if (!limitPerMin || limitPerMin <= 0) {
         return { rateLimitPerMin: 0, rateWaitMs: 0, rateWindowCount: 0 };
     }
     const state = _getOpenAiPromptCacheLaneRateState(key);
     const startedAt = Date.now();
+    let beforeWaitCalled = false;
     while (true) {
         const now = Date.now();
         _pruneOpenAiPromptCacheLaneRateState(state, now);
@@ -247,10 +311,57 @@ async function _reserveOpenAiPromptCacheLaneRate({ key, limitPerMin, signal }) {
             };
         }
         const waitMs = Math.max(25, state.starts[0] + OPENAI_PROMPT_CACHE_LANE_RATE_WINDOW_MS - now);
+        if (!beforeWaitCalled && typeof beforeWait === 'function') {
+            beforeWaitCalled = true;
+            await beforeWait({
+                waitMs,
+                rateLimitPerMin: limitPerMin,
+                rateWindowCount: state.starts.length,
+            });
+        }
         await _sleepWithSignal(waitMs, signal);
     }
 }
 
+export function _resolveOpenAiPromptCacheRatePolicy(sendOpts = {}, info = {}) {
+    const mode = String(info?.mode || '').toLowerCase();
+    const frameInputItems = Number(info?.frameInputItems);
+    const deltaTokens = Number(info?.deltaTokens);
+    const hasPreviousResponseId = info?.hasPreviousResponseId === true;
+    const fullLimitPerMin = _openAiPromptCacheLaneRateLimitPerMin(sendOpts);
+    const deltaLimitPerMin = _openAiPromptCacheLaneDeltaRateLimitPerMin(sendOpts);
+    const deltaMaxItems = _openAiPromptCacheLaneDeltaMaxItems(sendOpts);
+    const deltaMaxTokens = _openAiPromptCacheLaneDeltaMaxTokens(sendOpts);
+    const itemCount = Number.isFinite(frameInputItems) ? frameInputItems : null;
+    const tokenCount = Number.isFinite(deltaTokens) ? deltaTokens : null;
+    const smallDeltaItems = itemCount == null || deltaMaxItems <= 0 || itemCount <= deltaMaxItems;
+    const smallDeltaTokens = tokenCount == null || deltaMaxTokens <= 0 || tokenCount <= deltaMaxTokens;
+
+    if (mode === 'delta' && hasPreviousResponseId && smallDeltaItems && smallDeltaTokens) {
+        return {
+            policy: deltaLimitPerMin > 0 ? 'delta_relaxed' : 'delta_unlimited',
+            limitPerMin: deltaLimitPerMin,
+            fullLimitPerMin,
+            deltaLimitPerMin,
+            deltaMaxItems,
+            deltaMaxTokens,
+            frameInputItems: itemCount,
+            deltaTokens: tokenCount,
+        };
+    }
+
+    return {
+        policy: mode === 'delta' ? 'delta_guarded' : 'full_guard',
+        limitPerMin: fullLimitPerMin,
+        fullLimitPerMin,
+        deltaLimitPerMin,
+        deltaMaxItems,
+        deltaMaxTokens,
+        frameInputItems: itemCount,
+        deltaTokens: tokenCount,
+    };
+}
+
 function _removeQueuedOpenAiPromptCacheLaneRequest(state, request) {
     const index = state.queue.indexOf(request);
     if (index >= 0) state.queue.splice(index, 1);
@@ -332,29 +443,10 @@ async function _withOpenAiPromptCacheLane({ auth, cacheKey, sendOpts, poolKey, i
     }
     const laneKey = `openai-prompt:${traceProvider || 'openai'}:${useModel || 'default'}:${cacheKey}`;
     const laneKeyHash = _cacheLaneHash(laneKey);
-    const rateMeta = await _reserveOpenAiPromptCacheLaneRate({
-        key: laneKey,
-        limitPerMin: _openAiPromptCacheLaneRateLimitPerMin(sendOpts),
-        signal: externalSignal,
-    });
-    if (rateMeta.rateWaitMs > 0) {
-        appendBridgeTrace({
-            sessionId: poolKey,
-            iteration,
-            kind: 'cache_lane',
-            provider: traceProvider,
-            model: useModel,
-            event: 'rate_wait',
-            lane_key_hash: laneKeyHash,
-            rate_limit_per_min: rateMeta.rateLimitPerMin,
-            rate_wait_ms: rateMeta.rateWaitMs,
-            rate_window_count: rateMeta.rateWindowCount,
-        });
-    }
     const state = _getOpenAiPromptCacheLaneState(laneKey, maxInFlight);
     const queued = state.active >= state.maxInFlight;
     if (queued) {
-        appendBridgeTrace({
+        appendAgentTrace({
             sessionId: poolKey,
             iteration,
             kind: 'cache_lane',
@@ -368,23 +460,139 @@ async function _withOpenAiPromptCacheLane({ auth, cacheKey, sendOpts, poolKey, i
         });
     }
     const timeoutMs = _openAiPromptCacheLaneQueueTimeoutMs(sendOpts);
-    const handle = await _acquireOpenAiPromptCacheLane({ key: laneKey, maxInFlight, signal: externalSignal, timeoutMs });
+    let handle = await _acquireOpenAiPromptCacheLane({ key: laneKey, maxInFlight, signal: externalSignal, timeoutMs });
+    let handleActive = true;
     const laneMeta = {
         enabled: true,
         laneKeyHash,
         maxInFlight,
-        rateLimitPerMin: rateMeta.rateLimitPerMin,
-        rateWaitMs: rateMeta.rateWaitMs,
-        rateWindowCount: rateMeta.rateWindowCount,
+        ratePolicy: 'pending',
+        rateLimitPerMin: 0,
+        rateWaitMs: 0,
+        rateWindowCount: 0,
+        rateReleasedForWait: false,
+        rateReacquireWaitMs: 0,
         queued: queued || handle.queued === true,
         waitMs: handle.waitedMs,
         activeAfterAcquire: handle.activeCount,
         queueDepthAfterAcquire: handle.queueDepth,
+        async reserveRate(info = {}) {
+            if (laneMeta.ratePolicy !== 'pending') return laneMeta;
+            const policy = _resolveOpenAiPromptCacheRatePolicy(sendOpts, info);
+            let releasedForRateWait = false;
+            const rateMeta = await _reserveOpenAiPromptCacheLaneRate({
+                key: laneKey,
+                limitPerMin: policy.limitPerMin,
+                signal: externalSignal,
+                beforeWait: () => {
+                    if (!handleActive) return;
+                    handle.release();
+                    handleActive = false;
+                    releasedForRateWait = true;
+                },
+            });
+            let reacquireWaitMs = 0;
+            if (releasedForRateWait) {
+                const reacquired = await _acquireOpenAiPromptCacheLane({
+                    key: laneKey,
+                    maxInFlight,
+                    signal: externalSignal,
+                    timeoutMs,
+                });
+                handle = reacquired;
+                handleActive = true;
+                reacquireWaitMs = reacquired.waitedMs;
+                laneMeta.queued = laneMeta.queued || reacquired.queued === true;
+                laneMeta.waitMs = (Number(laneMeta.waitMs) || 0) + reacquireWaitMs;
+                laneMeta.activeAfterAcquire = reacquired.activeCount;
+                laneMeta.queueDepthAfterAcquire = reacquired.queueDepth;
+            }
+            Object.assign(laneMeta, {
+                ratePolicy: policy.policy,
+                rateLimitPerMin: rateMeta.rateLimitPerMin,
+                rateWaitMs: rateMeta.rateWaitMs,
+                rateWindowCount: rateMeta.rateWindowCount,
+                rateReleasedForWait: releasedForRateWait,
+                rateReacquireWaitMs: reacquireWaitMs,
+                rateFullLimitPerMin: policy.fullLimitPerMin,
+                rateDeltaLimitPerMin: policy.deltaLimitPerMin,
+                rateDeltaMaxItems: policy.deltaMaxItems,
+                rateDeltaMaxTokens: policy.deltaMaxTokens,
+                ratePolicyFrameInputItems: policy.frameInputItems,
+                ratePolicyDeltaTokens: policy.deltaTokens,
+            });
+            if (rateMeta.rateWaitMs > 0) {
+                appendAgentTrace({
+                    sessionId: poolKey,
+                    iteration,
+                    kind: 'cache_lane',
+                    provider: traceProvider,
+                    model: useModel,
+                    event: 'rate_wait',
+                    lane_key_hash: laneKeyHash,
+                    rate_policy: laneMeta.ratePolicy,
+                    rate_limit_per_min: rateMeta.rateLimitPerMin,
+                    rate_wait_ms: rateMeta.rateWaitMs,
+                    rate_window_count: rateMeta.rateWindowCount,
+                    released_for_rate_wait: releasedForRateWait,
+                    reacquire_wait_ms: reacquireWaitMs,
+                    frame_input_items: policy.frameInputItems,
+                    delta_tokens: policy.deltaTokens,
+                });
+            }
+            return laneMeta;
+        },
     };
     try {
         return await fn(laneMeta);
     } finally {
-        handle.release();
+        const slowTraceMs = _openAiPromptCacheLaneSlowTraceMs(sendOpts);
+        const slowWaitMs = Math.max(Number(laneMeta.rateWaitMs) || 0, Number(laneMeta.waitMs) || 0);
+        if (slowTraceMs > 0 && slowWaitMs >= slowTraceMs) {
+            appendAgentTrace({
+                sessionId: poolKey,
+                iteration,
+                kind: 'cache_lane_slow',
+                provider: traceProvider,
+                model: useModel,
+                event: laneMeta.rateWaitMs > 0 && laneMeta.waitMs > 0
+                    ? 'rate_and_queue_wait'
+                    : laneMeta.rateWaitMs > 0
+                        ? 'rate_wait'
+                        : 'queue_wait',
+                lane_key_hash: laneKeyHash,
+                payload: {
+                    event: laneMeta.rateWaitMs > 0 && laneMeta.waitMs > 0
+                        ? 'rate_and_queue_wait'
+                        : laneMeta.rateWaitMs > 0
+                            ? 'rate_wait'
+                            : 'queue_wait',
+                    provider: traceProvider,
+                    model: useModel,
+                    lane_key_hash: laneKeyHash,
+                    threshold_ms: slowTraceMs,
+                    max_wait_ms: slowWaitMs,
+                    rate_policy: laneMeta.ratePolicy,
+                    rate_limit_per_min: laneMeta.rateLimitPerMin,
+                    rate_wait_ms: laneMeta.rateWaitMs,
+                    rate_window_count: laneMeta.rateWindowCount,
+                    released_for_rate_wait: laneMeta.rateReleasedForWait,
+                    reacquire_wait_ms: laneMeta.rateReacquireWaitMs,
+                    rate_full_limit_per_min: laneMeta.rateFullLimitPerMin,
+                    rate_delta_limit_per_min: laneMeta.rateDeltaLimitPerMin,
+                    rate_delta_max_items: laneMeta.rateDeltaMaxItems,
+                    rate_delta_max_tokens: laneMeta.rateDeltaMaxTokens,
+                    rate_policy_frame_input_items: laneMeta.ratePolicyFrameInputItems,
+                    rate_policy_delta_tokens: laneMeta.ratePolicyDeltaTokens,
+                    max_in_flight: laneMeta.maxInFlight,
+                    queued: laneMeta.queued,
+                    wait_ms: laneMeta.waitMs,
+                    active_after_acquire: laneMeta.activeAfterAcquire,
+                    queue_depth_after_acquire: laneMeta.queueDepthAfterAcquire,
+                },
+            });
+        }
+        if (handleActive) handle.release();
     }
 }
 
@@ -503,14 +711,14 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
     return headers;
 }
 
-// handshake session_id is the conversation slot Codex uses for in-memory
+// handshake session_id is the conversation slot openai-oauth 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.
+    // response ids for continuation; unlike openai-oauth, it does not need the
+    // OAuth-specific session_id handshake shard.
     if (auth?.type === 'xai') return null;
     return cacheKey || 'mixdog-default';
 }
@@ -523,8 +731,8 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }
             ? 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`);
+    if (process.env.MIXDOG_DEBUG_AGENT) {
+        process.stderr.write(`[agent-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) => {
@@ -546,8 +754,8 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }
         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`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-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(
@@ -564,14 +772,14 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }
             } catch {}
         });
         socket.once('open', () => {
-            if (process.env.MIXDOG_DEBUG_BRIDGE) {
-                process.stderr.write(`[bridge-trace] ws-open-ok elapsed=${Date.now() - _wsOpenStart}ms\n`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-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`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-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 }));
@@ -594,8 +802,8 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }
             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`);
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-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 }));
@@ -616,12 +824,12 @@ function _openSocket({ auth, sessionToken, turnState, externalSignal, cacheKey }
 
 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 (process.env.MIXDOG_DEBUG_AGENT) {
+        process.stderr.write(`[agent-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');
+        throw reason instanceof Error ? reason : new Error('OpenAI OAuth WS acquire aborted');
     }
     if (poolKey && !forceFresh) {
         const arr = _wsPool.get(poolKey) || [];
@@ -645,15 +853,15 @@ async function acquireWebSocket({ auth, poolKey, cacheKey, forceFresh, externalS
             if (idle.lastInputPrefixHash === undefined) idle.lastInputPrefixHash = null;
             if (idle.lastRequestInput === undefined) idle.lastRequestInput = null;
             if (idle.lastResponseItems === undefined) idle.lastResponseItems = 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`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-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`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-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 });
@@ -683,13 +891,13 @@ async function acquireWebSocket({ auth, poolKey, cacheKey, forceFresh, externalS
             return { entry, reused: false };
         }
     }
-    // Parallel sockets must not inherit sibling turnState or the Codex server
+    // Parallel sockets must not inherit sibling turnState or the openai-oauth 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`);
+    if (process.env.MIXDOG_DEBUG_AGENT) {
+        process.stderr.write(`[agent-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 = {
@@ -780,16 +988,41 @@ function _contentPartsEqual(a, b) {
     return _stableStringify(aa) === _stableStringify(bb);
 }
 
-function _logicalResponseItemMatch(inputItem, responseItem) {
+export function _logicalResponseItemMatch(inputItem, responseItem) {
     if (!inputItem || !responseItem) return false;
     const inputType = inputItem.type || (inputItem.role === 'assistant' ? 'message' : '');
     const responseType = responseItem.type || '';
     if (responseType === 'function_call') {
-        return inputType === 'function_call'
-            && String(inputItem.call_id || '') === String(responseItem.call_id || '')
-            && String(inputItem.name || '') === String(responseItem.name || '')
+        if (inputType !== 'function_call') return false;
+        const inputCallId = String(inputItem.call_id || '');
+        const responseCallId = String(responseItem.call_id || '');
+        const inputName = String(inputItem.name || '');
+        const responseName = String(responseItem.name || '');
+        if (inputCallId && responseCallId) {
+            // call_id is the server-side anchor. The replayed history may carry
+            // locally compacted arguments, but previous_response_id already
+            // points at the canonical output item.
+            return inputCallId === responseCallId && inputName === responseName;
+        }
+        return inputName === responseName
             && _normalizeArguments(inputItem.arguments) === _normalizeArguments(responseItem.arguments);
     }
+    if (responseType === 'tool_search_call') {
+        if (inputType !== 'tool_search_call') return false;
+        const inputCallId = String(inputItem.call_id || '');
+        const responseCallId = String(responseItem.call_id || '');
+        if (inputCallId && responseCallId) return inputCallId === responseCallId;
+        return _normalizeArguments(inputItem.arguments) === _normalizeArguments(responseItem.arguments);
+    }
+    if (responseType === 'custom_tool_call') {
+        if (inputType !== 'custom_tool_call') return false;
+        const inputCallId = String(inputItem.call_id || '');
+        const responseCallId = String(responseItem.call_id || '');
+        const inputName = String(inputItem.name || '');
+        const responseName = String(responseItem.name || '');
+        if (inputCallId && responseCallId) return inputCallId === responseCallId && inputName === responseName;
+        return inputName === responseName && String(inputItem.input || '') === String(responseItem.input || '');
+    }
     if (responseType === 'message') {
         const inputRole = inputItem.role || (inputType === 'message' ? 'assistant' : '');
         const responseRole = responseItem.role || 'assistant';
@@ -838,6 +1071,7 @@ function _isReplayLikeHead(item, responseItem) {
     const responseType = responseItem.type || '';
     if (responseType === 'message') return inputType === 'message';
     if (responseType === 'function_call') return inputType === 'function_call';
+    if (responseType === 'tool_search_call') return inputType === 'tool_search_call';
     return inputType === responseType;
 }
 
@@ -969,7 +1203,25 @@ function _httpStatusFromWsClose(code, reason) {
 function _wsErrLabel(p) {
     if (p === 'xai') return 'xAI WS';
     if (p === 'openai-direct' || p === 'openai') return 'OpenAI WS';
-    return 'Codex WS';
+    return 'OpenAI OAuth WS';
+}
+// tool_search_call.arguments parse. Module-scope (exported) for direct test
+// coverage. Native convergence (openai-oauth / anthropic-oauth / opencode): same policy
+// as the function_call_arguments.done path and openai-oauth _parseJsonObject —
+// object passes through; null/non-string/empty/whitespace → {} (no args); a
+// non-empty string that fails JSON.parse is deterministic bad JSON, surfaced
+// as an invalid-args MARKER (not silently swallowed to {}) so the dispatch
+// loop returns an is_error tool_result and the model self-corrects in the same
+// turn.
+export function parseToolSearchArgs(value) {
+    if (value && typeof value === 'object') return value;
+    if (typeof value !== 'string' || !value.trim()) return {};
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch (err) {
+        return makeInvalidToolArgsMarker(value, err instanceof Error ? err.message : String(err));
+    }
 }
 export async function _streamResponse({
     entry,
@@ -996,7 +1248,6 @@ export async function _streamResponse({
     const toolCalls = [];
     const webSearchCalls = [];
     const webSearchCallKeys = new Set();
-    const compactionItems = [];
     const responseItemsAdded = [];
     const responseItemKeys = new Set();
     const citations = [];
@@ -1006,7 +1257,7 @@ export async function _streamResponse({
     // 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
+    // convertMessagesToResponsesInput (openai-oauth.mjs:233-238) — openai-oauth
     // 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
@@ -1085,10 +1336,26 @@ export async function _streamResponse({
             for (const url of action.urls) pushCitation({ url, title: action.query || '' });
         }
     };
-    const pushCompactionItem = (item) => {
-        if (!item || !['compaction', 'compaction_summary', 'context_compaction'].includes(item.type)) return;
-        if (!item.encrypted_content) return;
-        compactionItems.push(item);
+    const pushCustomToolCall = (item) => {
+        const call = customToolCallFromResponseItem(item);
+        if (!call || toolCalls.some((existing) => existing.id === call.id)) return;
+        toolCalls.push(call);
+        midState.emittedToolCall = true;
+        try { onToolCall?.(call); } catch {}
+    };
+    const pushToolSearchCall = (item) => {
+        if (!item || item.type !== 'tool_search_call') return;
+        const callId = item.call_id || item.id || '';
+        if (!callId || toolCalls.some((call) => call.id === callId)) return;
+        const call = {
+            id: callId,
+            name: 'tool_search',
+            arguments: parseToolSearchArgs(item.arguments),
+            nativeType: 'tool_search_call',
+        };
+        toolCalls.push(call);
+        midState.emittedToolCall = true;
+        try { onToolCall?.(call); } catch {}
     };
     const logReasoningDeltaSuppression = () => {
         if (!logSuppressedReasoningDeltas) return;
@@ -1128,13 +1395,13 @@ export async function _streamResponse({
         // 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
+        // gaps mid-reasoning (openai-oauth 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=${preResponseCreatedMs}\n`);
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-trace] ws-timeout kind=first-byte afterMs=${preResponseCreatedMs}\n`);
                 }
                 traceWsTimeout('first_byte_timeout', preResponseCreatedMs);
                 const err = new Error(`WS stream: no first server event within ${preResponseCreatedMs}ms`);
@@ -1178,7 +1445,7 @@ export async function _streamResponse({
                     saw_response_created: midState.sawResponseCreated === true,
                     first_meaningful_seen: firstMeaningfulSeen === true,
                 };
-                appendBridgeTrace({
+                appendAgentTrace({
                     sessionId: midState.sessionId || null,
                     iteration: Number.isFinite(iteration) ? iteration : null,
                     kind: 'ws_timeout',
@@ -1203,8 +1470,8 @@ export async function _streamResponse({
             if (firstMeaningfulSeen || firstMeaningfulMs <= 0) return;
             clearFirstMeaningfulWatchdog();
             firstMeaningfulTimer = setTimeout(() => {
-                if (process.env.MIXDOG_DEBUG_BRIDGE) {
-                    process.stderr.write(`[bridge-trace] ws-timeout kind=first-meaningful afterMs=${firstMeaningfulMs}\n`);
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-trace] ws-timeout kind=first-meaningful afterMs=${firstMeaningfulMs}\n`);
                 }
                 traceWsTimeout('first_meaningful_timeout', firstMeaningfulMs);
                 const err = new Error(`WS stream: no meaningful output within ${firstMeaningfulMs}ms after response.created`);
@@ -1219,8 +1486,8 @@ export async function _streamResponse({
         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=${interChunkMs}\n`);
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-trace] ws-timeout kind=inter-chunk afterMs=${interChunkMs}\n`);
                 }
                 traceWsTimeout('inter_chunk_timeout', interChunkMs);
                 terminalError = new Error(`WS stream: inter-chunk inactivity for ${interChunkMs}ms`);
@@ -1237,7 +1504,7 @@ export async function _streamResponse({
         };
         // Called on every event that carries real output tokens or tool
         // progress. `response.created` is only an ACK and must not count here:
-        // a wedged Codex stream can ACK immediately and then never produce
+        // a wedged openai-oauth stream can ACK immediately and then never produce
         // text/reasoning/tool deltas, holding the prompt-cache lane for the
         // full inter-chunk window.
         const onMeaningfulOutput = () => {
@@ -1263,19 +1530,12 @@ export async function _streamResponse({
         const finish = () => {
             logReasoningDeltaSuppression();
             cleanup();
-            if (!terminalError && midState.expectCompaction === true && compactionItems.length !== 1) {
-                terminalError = new Error(
-                    `${errLabel} remote compaction expected exactly one compaction output item, got ${compactionItems.length}`,
-                );
-            }
             if (terminalError) { reject(terminalError); return; }
             resolve({
                 content,
                 model,
                 reasoningItems: reasoningItems.length ? reasoningItems : undefined,
                 responseItems: responseItemsAdded.length ? responseItemsAdded : undefined,
-                compactionItem: compactionItems.length === 1 ? compactionItems[0] : undefined,
-                compactionItems: compactionItems.length ? compactionItems : undefined,
                 toolCalls: toolCalls.length ? toolCalls : undefined,
                 citations: citations.length ? citations : undefined,
                 webSearchCalls: webSearchCalls.length ? webSearchCalls : undefined,
@@ -1290,7 +1550,7 @@ export async function _streamResponse({
         messageHandler = (data) => {
             resetIdle();
             // Do NOT call onStreamDelta for every frame — metadata/keepalive frames
-            // must not reset bridge-stall-watchdog's lastStreamDeltaAt. Only
+            // must not reset the agent 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);
@@ -1321,8 +1581,8 @@ export async function _streamResponse({
                     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`);
+                            if (process.env.MIXDOG_DEBUG_AGENT) {
+                                process.stderr.write(`[agent-trace] ws-first-delta sinceStreaming=${Date.now() - _streamingStart}ms\n`);
                             }
                         }
                         onStreamDelta?.();
@@ -1370,11 +1630,30 @@ export async function _streamResponse({
                     try { onStreamDelta?.(); } catch {}
                     onMeaningfulOutput();
                     break;
+                case 'response.custom_tool_call_input.delta':
+                    try { onStreamDelta?.(); } catch {}
+                    onMeaningfulOutput();
+                    break;
                 case 'response.function_call_arguments.done': {
                     const itemId = event.item_id || '';
                     const pending = pendingCalls.get(itemId);
+                    // function_call_arguments.done is a completion signal:
+                    // empty/whitespace → no args ({}); a non-empty string that
+                    // fails JSON.parse is deterministic bad JSON. Native
+                    // convergence: surface an invalid-args MARKER (not silent
+                    // {}) so the dispatch loop returns an is_error tool_result
+                    // and the model re-issues valid JSON in the same turn.
                     let args = {};
-                    try { args = JSON.parse(event.arguments || '{}'); } catch {}
+                    {
+                        const _argText = typeof event.arguments === 'string' ? event.arguments : '';
+                        if (_argText.trim() !== '') {
+                            try {
+                                args = JSON.parse(_argText);
+                            } catch (err) {
+                                args = makeInvalidToolArgsMarker(_argText, err instanceof Error ? err.message : String(err));
+                            }
+                        }
+                    }
                     enrichFunctionCallResponseItem({
                         itemId,
                         callId: pending?.callId || event.call_id || '',
@@ -1413,12 +1692,16 @@ export async function _streamResponse({
                     // 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
+                    // must be replayed on the next input to keep the openai-oauth
                     // server-side prompt cache prefix warm.
                     if (event.item?.type === 'reasoning') pushReasoningItem(event.item);
                     if (event.item?.type === 'web_search_call') pushWebSearchCall(event.item);
-                    if (['compaction', 'compaction_summary', 'context_compaction'].includes(event.item?.type)) {
-                        pushCompactionItem(event.item);
+                    if (event.item?.type === 'tool_search_call') {
+                        pushToolSearchCall(event.item);
+                        onMeaningfulOutput();
+                    }
+                    if (event.item?.type === 'custom_tool_call') {
+                        pushCustomToolCall(event.item);
                         onMeaningfulOutput();
                     }
                     break;
@@ -1434,7 +1717,7 @@ export async function _streamResponse({
                             inputTokens: u.input_tokens || 0,
                             outputTokens: u.output_tokens || 0,
                             cachedTokens: extractCachedTokens(u),
-                            // OpenAI Codex reports input_tokens as the total
+                            // openai-oauth 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
@@ -1462,9 +1745,8 @@ export async function _streamResponse({
                                 }
                             }
                             if (item.type === 'web_search_call') pushWebSearchCall(item);
-                            if (['compaction', 'compaction_summary', 'context_compaction'].includes(item.type)) {
-                                pushCompactionItem(item);
-                            }
+                            if (item.type === 'tool_search_call') pushToolSearchCall(item);
+                            if (item.type === 'custom_tool_call') pushCustomToolCall(item);
                             // Salvage path: some streams emit reasoning only
                             // inside the final response.completed.output
                             // bundle (no per-item .done event). Dedup by id.
@@ -1514,7 +1796,7 @@ export async function _streamResponse({
                     break;
                 }
                 case 'response.done': {
-                    // response.done is the terminal frame for some Codex
+                    // response.done is the terminal frame for some openai-oauth
                     // streams that never emit a separate response.completed.
                     // Route through the same completed/failed/incomplete
                     // normalization based on event.response.status so a
@@ -1638,7 +1920,7 @@ export async function _streamResponse({
                 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}` : ''})`),
+                    new Error(`OpenAI OAuth WS closed before response.completed (code=${code}${r ? `, reason=${r}` : ''})`),
                     { wsCloseCode: code, wsCloseReason: r, ...(httpStatus ? { httpStatus } : {}) },
                 );
             } else if (terminalError && !terminalError.wsCloseCode) {
@@ -1674,15 +1956,15 @@ export async function _streamResponse({
             abortHandler = () => {
                 if (done) return;
                 const reason = externalSignal.reason;
-                terminalError = reason instanceof Error ? reason : new Error('Codex WS aborted by session close');
+                terminalError = reason instanceof Error ? reason : new Error('OpenAI OAuth 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
+                // externalSignal; the agent stall watchdog signals via a reason
+                // object whose name === 'AgentStallAbortError'. stream-watchdog
                 // uses StreamStalledAbortError. Anything else → treat as user.
                 const reasonName = reason?.name || '';
-                if (reasonName === 'BridgeStallAbortError'
+                if (reasonName === 'AgentStallAbortError'
                     || reasonName === 'StreamStalledAbortError') {
                     midState.watchdogAbort = reasonName;
                 } else {
@@ -1698,10 +1980,10 @@ export async function _streamResponse({
         socket.on('close', closeHandler);
         socket.on('error', errorHandler);
         armPreStreamWatchdog();
-        // Periodic client-side WS ping while the stream is active. Codex's
+        // Periodic client-side WS ping while the stream is active. The server'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.
+        // flow. Sending a ping every 10s 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).
@@ -1710,7 +1992,7 @@ export async function _streamResponse({
                 if (socket.readyState !== WebSocket.OPEN) return;
                 socket.ping();
             } catch {}
-        }, 18_000);
+        }, 10_000);
         try { keepaliveTimer.unref?.(); } catch {}
     });
 }
@@ -1732,34 +2014,12 @@ export async function _streamResponse({
  *   'http_5xx' (with specific status e.g. 'http_503') — server overload
  *   null      — not retryable
  */
+// Thin re-export wrapper: handshake classification now lives in the shared
+// retry-classifier (classifyHandshakeError). Kept here as a named export so
+// internal call sites (_acquireWithRetry) and any external importer keep
+// resolving the same symbol.
 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;
+    return classifyHandshakeError(err);
 }
 
 /**
@@ -1771,7 +2031,7 @@ export function _classifyHandshakeError(err) {
  * after completion would replay a finished turn.
  *
  * Retry buckets:
- *   'bridge_stall'       — BridgeStallAbortError from bridge-stall-watchdog
+ *   'agent_stall'        — AgentStallAbortError from agent stall watchdog
  *   'stream_stalled'     — StreamStalledAbortError from stream-watchdog
  *   'ws_1006'            — abnormal close (connection lost)
  *   'ws_1011'            — server unexpected condition
@@ -1800,130 +2060,28 @@ export function _classifyHandshakeError(err) {
  *   - HTTP 401 / 403 / 429 surfaced on the error
  *   - state.attemptIndex has reached the classifier-specific retry budget
  */
+// Thin wrapper: the full WS mid-stream decision tree now lives in the shared
+// classifyMidstreamError (retry-classifier.mjs, policy.mode='ws'). Kept as a
+// named export so internal call sites and any external importer keep resolving
+// the same symbol. Behavior is byte-identical — the shared function is the
+// relocated original, with the per-classifier budget gating supplied by
+// WS_MIDSTREAM_POLICY (transientCloseRetries=4, defaultRetries=2).
 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;
-    }
-    // Live-text invariant: once a non-empty text chunk has been relayed to the
-    // client (gateway live mode), the rendered output cannot be withdrawn and a
-    // retry would concatenate a second attempt. Treat every subsequent
-    // mid-stream/truncated failure as final — never retry.
-    if (state.emittedText || err?.liveTextEmitted) 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);
-    }
-    if (state.firstMeaningfulTimeout || err?.firstMeaningfulTimeout) {
-        return _allowMidstreamRetry('first_meaningful_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;
+    return classifyMidstreamError(err, state, WS_MIDSTREAM_POLICY);
 }
 
+// Per-classifier retry budget, used by the sendViaWebSocket loop to bound the
+// attempt count once classifyMidstreamError returns a bucket. Mirrors the
+// shared _midstreamLimitFor(ws) — the numbers come from MIDSTREAM_RETRY_POLICY.
 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];
+    const raw = MIDSTREAM_BACKOFF_MS[Math.min(Math.max(retryNumber, 1), MIDSTREAM_BACKOFF_MS.length) - 1];
+    return jitterDelayMs(raw);
 }
 
 function _backoffFor(attempt) {
@@ -1934,25 +2092,11 @@ function _backoffFor(attempt) {
 
 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 });
-    });
+// Abort-aware backoff sleep → shared sleepWithAbort (retry-classifier.mjs). The
+// abortMessage preserves the prior fallback text when the abort reason is not an
+// Error; _sleepFn (test seam) is threaded through as the no-signal sleep impl.
+function _sleepWithAbort(ms, externalSignal, sleepFn = _defaultSleep) {
+    return sleepWithAbort(ms, externalSignal, sleepFn, 'OpenAI OAuth WS retry backoff aborted');
 }
 
 /**
@@ -1980,12 +2124,12 @@ export async function _acquireWithRetry({
     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');
+            throw reason instanceof Error ? reason : new Error('OpenAI OAuth WS acquire aborted');
         }
         try {
             if (attempt > 1) {
-                if (process.env.MIXDOG_DEBUG_BRIDGE) {
-                    process.stderr.write(`[bridge-trace] ws-handshake-attempt n=${attempt}\n`);
+                if (process.env.MIXDOG_DEBUG_AGENT) {
+                    process.stderr.write(`[agent-trace] ws-handshake-attempt n=${attempt}\n`);
                 }
             }
             return await _acquire({ auth, poolKey, cacheKey, forceFresh, externalSignal });
@@ -2041,7 +2185,7 @@ export async function _acquireWithRetry({
                     const onAbort = () => {
                         clearTimeout(t);
                         const reason = externalSignal.reason;
-                        reject(reason instanceof Error ? reason : new Error('Codex WS acquire aborted'));
+                        reject(reason instanceof Error ? reason : new Error('OpenAI OAuth WS acquire aborted'));
                     };
                     if (externalSignal.aborted) { onAbort(); return; }
                     externalSignal.addEventListener('abort', onAbort, { once: true });
@@ -2113,20 +2257,21 @@ export async function sendViaWebSocket({
     // already-rendered output. A text-emitting attempt is never retry-eligible
     // (_classifyMidstreamError returns null on emittedText), so the surfaced
     // error is frequently an EARLIER attempt's firstAttemptError that never saw
-    // the marker; _stampLiveText re-applies it on every throw path.
-    let liveTextEmittedAcrossAttempts = false;
-    const _stampLiveText = (e) => {
-        if (liveTextEmittedAcrossAttempts && e) {
-            try { e.liveTextEmitted = true; e.unsafeToRetry = true; } catch {}
-        }
-        return e;
-    };
+    // the marker; stampText re-applies it on every throw path. The latch state
+    // + stamp semantics now come from the shared createStreamSafetyStamps()
+    // factory (retry-classifier.mjs) — identical to the former _stampLiveText /
+    // _stampTool closures. markText()/markTool() set the latch (replacing the
+    // liveTextEmittedAcrossAttempts / toolEmittedAcrossAttempts booleans);
+    // stampText/stampTool re-apply the markers on every throw.
+    const _safetyStamps = createStreamSafetyStamps();
+    const _stampLiveText = _safetyStamps.stampText;
+    const _stampTool = _safetyStamps.stampTool;
     // 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
+    // warmed. openai-oauth / 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 = [];
@@ -2166,7 +2311,7 @@ export async function sendViaWebSocket({
             const classifiers = [...handshakeRetryClassifiers];
             if (classifier && !classifiers.includes(classifier)) classifiers.push(classifier);
             if (err?.httpStatus != null || classifier || handshakeRetries > 0 || classifiers.length > 0) {
-                traceBridgeFetch({
+                traceAgentFetch({
                     sessionId: poolKey,
                     headersMs: Date.now() - handshakeStart,
                     httpStatus: Number(err?.httpStatus || 0),
@@ -2182,9 +2327,9 @@ export async function sendViaWebSocket({
             // the caller's turn actually tripped on).
             if (attemptIndex > 0 && firstAttemptError) {
                 try { firstAttemptError.midstreamRetries = attemptIndex; } catch {}
-                throw _stampLiveText(firstAttemptError);
+                throw _stampTool(_stampLiveText(firstAttemptError));
             }
-            throw _stampLiveText(err);
+            throw _stampTool(_stampLiveText(err));
         }
         const { entry, reused } = acquired;
         // Re-seed the retry attempt's fresh entry with the prior attempt's
@@ -2199,7 +2344,7 @@ export async function sendViaWebSocket({
             entry.lastRequestInput = carryForwardCache.lastRequestInput;
             entry.lastResponseItems = carryForwardCache.lastResponseItems;
         }
-        traceBridgeFetch({
+        traceAgentFetch({
             sessionId: poolKey,
             headersMs: Date.now() - handshakeStart,
             httpStatus: reused ? 0 : 101,
@@ -2245,14 +2390,15 @@ export async function sendViaWebSocket({
         let strippedResponseItems = 0;
         let skippedResponseItems = 0;
         let result;
-        const streamTimeouts = sendOpts?.expectCompaction === true
-            ? {
-                firstMeaningfulMs: WS_INTER_CHUNK_MS,
-                interChunkMs: WS_INTER_CHUNK_MS,
-            }
-            : null;
+        const streamTimeouts = null;
         try {
             if (warmupBody && typeof warmupBody === 'object' && attemptIndex === 0) {
+                await promptCacheLane?.reserveRate?.({
+                    mode: 'full',
+                    frameInputItems: Array.isArray(warmupBody.input) ? warmupBody.input.length : null,
+                    deltaTokens: _estimateFrameTokens({ type: 'response.create', ...warmupBody }),
+                    hasPreviousResponseId: false,
+                });
                 const warmupFrame = { type: 'response.create', ...warmupBody };
                 await _sendFrameFn(entry, warmupFrame);
                 const warmupStart = Date.now();
@@ -2306,7 +2452,7 @@ export async function sendViaWebSocket({
                         output_tokens: warmupResult.usage?.outputTokens || 0,
                         prompt_tokens: warmupResult.usage?.promptTokens || 0,
                     };
-                    appendBridgeTrace({
+                    appendAgentTrace({
                         sessionId: poolKey,
                         iteration,
                         kind: 'cache_warmup',
@@ -2329,6 +2475,12 @@ export async function sendViaWebSocket({
             strippedResponseItems = delta.strippedResponseItems || 0;
             skippedResponseItems = delta.skippedResponseItems || 0;
             deltaTokens = _estimateFrameTokens(frame);
+            await promptCacheLane?.reserveRate?.({
+                mode,
+                frameInputItems: Array.isArray(frame.input) ? frame.input.length : null,
+                deltaTokens,
+                hasPreviousResponseId: typeof frame.previous_response_id === 'string' && frame.previous_response_id.length > 0,
+            });
 
             // Re-check abort after acquire/warmup — narrow window where
             // externalSignal could fire between successful acquire and
@@ -2343,8 +2495,8 @@ export async function sendViaWebSocket({
             }
             await _sendFrameFn(entry, frame);
 
-            if (process.env.MIXDOG_DEBUG_BRIDGE) {
-                process.stderr.write(`[bridge-trace] ws-streaming-start sinceAcquire=${Date.now() - handshakeStart}ms\n`);
+            if (process.env.MIXDOG_DEBUG_AGENT) {
+                process.stderr.write(`[agent-trace] ws-streaming-start sinceAcquire=${Date.now() - handshakeStart}ms\n`);
             }
             try { onStageChange?.('streaming'); } catch {}
             result = await _streamFn({
@@ -2383,9 +2535,13 @@ export async function sendViaWebSocket({
                 // Latch across attempts: even though THIS error is never
                 // retry-eligible once text is out, a later/earlier surfaced
                 // error (firstAttemptError) must still carry the marker.
-                liveTextEmittedAcrossAttempts = true;
+                _safetyStamps.markText();
+            }
+            if (midState.emittedToolCall) {
+                _safetyStamps.markTool();
             }
             _stampLiveText(err);
+            _stampTool(err);
             const classifier = _classifyMidstreamError(err, midState);
             const retryLimit = classifier ? _midstreamRetryLimit(classifier) : 0;
             if (classifier && attemptIndex < retryLimit) {
@@ -2424,12 +2580,12 @@ export async function sendViaWebSocket({
                         firstAttemptError.suppressed = list;
                     }
                 } catch {}
-                throw _stampLiveText(firstAttemptError);
+                throw _stampTool(_stampLiveText(firstAttemptError));
             }
-            throw _stampLiveText(err);
+            throw _stampTool(_stampLiveText(err));
         }
         const liveModel = result.model || useModel;
-        traceBridgeSse({
+        traceAgentSse({
             sessionId: poolKey,
             sseParseMs: Date.now() - sseStart,
             provider: traceProvider,
@@ -2438,10 +2594,21 @@ export async function sendViaWebSocket({
         });
 
         const resultToolCallCount = Array.isArray(result.toolCalls) ? result.toolCalls.length : 0;
-        const keepResponseChain = !!result.responseId && !result.incompleteReason;
+        // Keep the conversation chain whenever the server gave us a response id.
+        // `incompleteReason` is ONLY ever set for max_output_tokens-class
+        // truncation (every other incomplete status throws upstream), and in
+        // that case the response IS valid and the server preserves its
+        // response_id as a continuation anchor. Dropping the chain here forced
+        // the NEXT turn to cold-start (no_anchor → full resend), which the
+        // trace logs showed repeating 50-78x in long max-output sessions. If a
+        // truncated turn's response items don't line up next turn,
+        // _stripResponseItemsFromHead still falls back to a full send on its
+        // own, so retaining the anchor cannot corrupt the cache — it only adds
+        // a delta fast-path when the items DO match.
+        const keepResponseChain = !!result.responseId;
         const keepSocket = true;
 
-        // Update cache state for the next iteration in this session. Codex
+        // Update cache state for the next iteration in this session. openai-oauth
         // keeps the previous response anchor even when the model emitted tool
         // calls: the next request is previous input + server output items
         // + tool results, and _computeDelta strips the first two parts so the
@@ -2473,7 +2640,7 @@ export async function sendViaWebSocket({
 
         const requestedServiceTier = body?.service_tier || null;
         const responseServiceTier = result.serviceTier || result.usage?.raw?.service_tier || null;
-        traceBridgeUsage({
+        traceAgentUsage({
             sessionId: poolKey,
             iteration,
             inputTokens: result.usage?.inputTokens || 0,
@@ -2489,6 +2656,9 @@ export async function sendViaWebSocket({
         });
         // Extra WS-specific observability: transport + per-iteration delta bytes.
         try {
+            const transportCacheKeyHash = cacheKey
+                ? createHash('sha256').update(String(cacheKey)).digest('hex').slice(0, 12)
+                : null;
             const transportPayload = {
                 provider: traceProvider,
                 transport: 'websocket',
@@ -2504,15 +2674,18 @@ export async function sendViaWebSocket({
                 handshake_retry_classifiers: handshakeRetryClassifiers,
                 midstream_retries: attemptIndex,
                 response_id: result.responseId || null,
-                cache_key_hash: cacheKey
-                    ? createHash('sha256').update(String(cacheKey)).digest('hex').slice(0, 12)
-                    : null,
+                cache_key_hash: transportCacheKeyHash,
                 cache_lane_enabled: promptCacheLane?.enabled === true,
                 cache_lane_key_hash: promptCacheLane?.laneKeyHash || null,
+                cache_lane_rate_policy: promptCacheLane?.ratePolicy || null,
                 cache_lane_max_in_flight: Number.isFinite(Number(promptCacheLane?.maxInFlight)) ? Number(promptCacheLane.maxInFlight) : null,
                 cache_lane_rate_limit_per_min: Number.isFinite(Number(promptCacheLane?.rateLimitPerMin)) ? Number(promptCacheLane.rateLimitPerMin) : null,
+                cache_lane_rate_full_limit_per_min: Number.isFinite(Number(promptCacheLane?.rateFullLimitPerMin)) ? Number(promptCacheLane.rateFullLimitPerMin) : null,
+                cache_lane_rate_delta_limit_per_min: Number.isFinite(Number(promptCacheLane?.rateDeltaLimitPerMin)) ? Number(promptCacheLane.rateDeltaLimitPerMin) : null,
                 cache_lane_rate_wait_ms: Number.isFinite(Number(promptCacheLane?.rateWaitMs)) ? Number(promptCacheLane.rateWaitMs) : null,
                 cache_lane_rate_window_count: Number.isFinite(Number(promptCacheLane?.rateWindowCount)) ? Number(promptCacheLane.rateWindowCount) : null,
+                cache_lane_rate_released_for_wait: promptCacheLane?.rateReleasedForWait === true,
+                cache_lane_rate_reacquire_wait_ms: Number.isFinite(Number(promptCacheLane?.rateReacquireWaitMs)) ? Number(promptCacheLane.rateReacquireWaitMs) : null,
                 cache_lane_wait_ms: Number.isFinite(Number(promptCacheLane?.waitMs)) ? Number(promptCacheLane.waitMs) : null,
                 cache_lane_queued: promptCacheLane?.queued === true,
                 cache_lane_active: Number.isFinite(Number(promptCacheLane?.activeAfterAcquire)) ? Number(promptCacheLane.activeAfterAcquire) : null,
@@ -2531,13 +2704,40 @@ export async function sendViaWebSocket({
                 keep_socket: keepSocket,
                 keep_response_chain: keepResponseChain,
             };
-            appendBridgeTrace({
+            appendAgentTrace({
                 sessionId: poolKey,
                 iteration,
                 kind: 'transport',
                 ...transportPayload,
                 payload: transportPayload,
             });
+            if (mode !== 'delta' || deltaReason) {
+                appendAgentTrace({
+                    sessionId: poolKey,
+                    iteration,
+                    kind: 'cache_break',
+                    provider: traceProvider,
+                    model: liveModel,
+                    payload: {
+                        provider: traceProvider,
+                        model: liveModel,
+                        transport: 'websocket',
+                        ws_mode: mode,
+                        reason: mode === 'delta' ? deltaReason : (deltaReason || 'full_frame'),
+                        cache_key_hash: transportCacheKeyHash,
+                        cache_lane_key_hash: promptCacheLane?.laneKeyHash || null,
+                        request_has_previous_response_id: transportPayload.request_has_previous_response_id,
+                        chain_stripped_response_items: strippedResponseItems,
+                        chain_skipped_response_items: skippedResponseItems,
+                        chain_response_items: Array.isArray(result.responseItems) ? result.responseItems.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: transportPayload.frame_has_instructions,
+                        keep_response_chain: keepResponseChain,
+                        tool_call_count: resultToolCallCount,
+                    },
+                });
+            }
         } catch {}
 
         releaseWebSocket({ entry, poolKey, keep: keepSocket });
@@ -2561,7 +2761,7 @@ export async function sendViaWebSocket({
         return out;
     }
     // Unreachable — the loop either returns or throws above.
-    throw _stampLiveText(firstAttemptError || new Error('sendViaWebSocket: unreachable'));
+    throw _stampTool(_stampLiveText(firstAttemptError || new Error('sendViaWebSocket: unreachable')));
     });
 }