mixdog 1.3.5 → 1.4.1

package/src/runtime/agent/orchestrator/providers/openai-http-sse-watchdogs.mjs

@@ -1,7 +1,15 @@
 /**
  * openai-http-sse-watchdogs.mjs — liveness gates of one HTTP/SSE fallback
  * stream: the total/external abort relay, the fixed first-server-event
- * deadline, the SEMANTIC idle watchdog, and the cancellable reader.read().
+ * deadline, the first-OUTPUT window, the SEMANTIC idle watchdog, and the
+ * cancellable reader.read().
+ *
+ * Until the model's first semantic output (reasoning, text, a tool call) only
+ * the first-server-event deadline and the first-output window run: server
+ * metadata (response.created / in_progress, an empty reasoning or message
+ * item) and keepalives neither end that phase nor start the semantic-idle
+ * clock, so a model may think silently longer than the idle window. From the
+ * first semantic output on, the semantic idle owns the stream.
  *
  * After headerTimeout.cleanup() the in-flight fetch no longer carries a live
  * signal, so a totalTimeout / external abort that fires during a pending
@@ -17,8 +25,10 @@ import {
   PROVIDER_FIRST_BYTE_TIMEOUT_MS,
   PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
   PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
+  providerFirstOutputTimeoutMs,
   streamStalledError,
 } from '../stall-policy.mjs';
+import { streamFirstOutputWindow } from './lib/first-output-window.mjs';
 
 function positiveOverride(value) {
   const ms = Number(value);
@@ -31,8 +41,18 @@ function positiveOverride(value) {
  * @param {ReadableStreamDefaultReader} deps.reader
  * @param {{ signal?: AbortSignal, cleanup(): void }} deps.totalTimeout
  * @param {() => object} deps.stallPartial  streamed partial state attached to a semantic-idle stall
+ * @param {string|null} [deps.sessionId]  the session whose logical request this stream serves
+ * @param {Function} [deps.onStreamDelta]  the stream's progress callback; without it the stream is a fork of the request
  */
-export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartial, label: LABEL }) {
+export function createHttpSseWatchdogs({
+  opts,
+  reader,
+  totalTimeout,
+  stallPartial,
+  label: LABEL,
+  sessionId = null,
+  onStreamDelta,
+}) {
   let abortReason = null;
   let pendingReadReject = null;
   const rejectPendingRead = (err) => {
@@ -58,9 +78,46 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
     else totalTimeout.signal.addEventListener('abort', onTotalAbort, { once: true });
   }
 
-  // Initial wait is governed only by the fixed first-server-event policy.
-  // Semantic idle begins after a parsed server event, so a lower
-  // semantic-idle override cannot shorten this first-event wait.
+  // SEMANTIC idle watchdog: reset ONLY on meaningful() (text/reasoning/tool
+  // deltas), never on raw bytes/keepalive frames, so a stream that emits some
+  // deltas then goes silent trips a short, named terminal failure instead of
+  // hanging until the 30-min agent watchdog. Disablable via the shared env.
+  let semanticIdleTimer = null;
+  const semanticIdleOverrideMs = positiveOverride(opts?._semanticIdleTimeoutMs);
+  const semanticIdleMs = semanticIdleOverrideMs || PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
+  const semanticIdleEnabled = semanticIdleOverrideMs > 0 || PROVIDER_SSE_IDLE_WATCHDOG_ENABLED;
+  // FIRST-OUTPUT window of the logical request this stream serves, retired by
+  // the first semantic output. Metadata-only streams (repeated
+  // response.in_progress, keepalive/ping frames, unknown event types) cannot
+  // refresh it, so a wedge that never produces a token still ends here.
+  const firstOutputOverrideMs = positiveOverride(opts?._firstOutputTimeoutMs);
+  const firstOutput = streamFirstOutputWindow({
+    sessionId,
+    onStreamDelta,
+    timeoutMs: firstOutputOverrideMs || providerFirstOutputTimeoutMs(semanticIdleMs),
+  });
+  const firstOutputEnabled = firstOutputOverrideMs > 0 || semanticIdleEnabled;
+
+  // A stalled stream fails with the named stall error, carrying the streamed
+  // partial state so the agent loop can accept a wedged FINAL no-tool summary
+  // as a successful partial-final instead of dropping the result.
+  // pendingToolUse gates out any mid-flight tool call.
+  const abortStalled = (timeoutMs) => {
+    const partial = stallPartial();
+    const err = streamStalledError(LABEL, timeoutMs, { emittedToolCall: partial.emittedToolCall });
+    try {
+      err.partialContent = partial.content;
+      err.partialToolCalls = partial.toolCalls;
+      err.pendingToolUse = partial.pendingToolUse;
+      err.partialModel = partial.model;
+    } catch {
+      /* best-effort enrichment */
+    }
+    abortStream(err);
+  };
+
+  // Initial wait for any server event is governed by the fixed
+  // first-server-event policy; a lower semantic-idle override cannot shorten it.
   let firstServerEventTimer = null;
   const firstServerEventMs = positiveOverride(opts?._firstServerEventTimeoutMs) || PROVIDER_FIRST_BYTE_TIMEOUT_MS;
   const clearFirstServerEvent = () => {
@@ -82,15 +139,15 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
       firstServerEventTimer.unref?.();
     } catch {}
   };
+  // Until the stream's first output the request's first-output window bounds
+  // it. A request that already had output has none: its stream runs under the
+  // semantic idle from its first server event (noteServerEvent).
+  const armFirstOutput = () => {
+    if (!firstOutput.outputSeen && firstOutputEnabled && firstOutput.timeoutMs > 0) {
+      firstOutput.arm(() => abortStalled(firstOutput.timeoutMs));
+    }
+  };
 
-  // SEMANTIC idle watchdog: reset ONLY on meaningful() (text/reasoning/tool
-  // deltas), never on raw bytes/keepalive frames, so a stream that emits some
-  // deltas then goes silent trips a short, named terminal failure instead of
-  // hanging until the 30-min agent watchdog. Disablable via the shared env.
-  let semanticIdleTimer = null;
-  const semanticIdleOverrideMs = positiveOverride(opts?._semanticIdleTimeoutMs);
-  const semanticIdleMs = semanticIdleOverrideMs || PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
-  const semanticIdleEnabled = semanticIdleOverrideMs > 0 || PROVIDER_SSE_IDLE_WATCHDOG_ENABLED;
   const clearSemanticIdle = () => {
     if (semanticIdleTimer) {
       clearTimeout(semanticIdleTimer);
@@ -100,43 +157,22 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   const armSemanticIdle = () => {
     if (!semanticIdleEnabled || !(semanticIdleMs > 0)) return;
     clearSemanticIdle();
-    semanticIdleTimer = setTimeout(() => {
-      const partial = stallPartial();
-      const err = streamStalledError(LABEL, semanticIdleMs, { emittedToolCall: partial.emittedToolCall });
-      // Partial-final recovery: attach the streamed partial state so the
-      // agent loop can accept a wedged FINAL no-tool summary as a successful
-      // partial-final instead of dropping the result. pendingToolUse gates
-      // out any mid-flight tool call.
-      try {
-        err.partialContent = partial.content;
-        err.partialToolCalls = partial.toolCalls;
-        err.pendingToolUse = partial.pendingToolUse;
-        err.partialModel = partial.model;
-      } catch {
-        /* best-effort enrichment */
-      }
-      abortStream(err);
-    }, semanticIdleMs);
+    semanticIdleTimer = setTimeout(() => abortStalled(semanticIdleMs), semanticIdleMs);
     try {
       semanticIdleTimer.unref?.();
     } catch {}
   };
-  // One-shot latch for the first-server-event → semantic-idle handover. Once
-  // the FIRST real SSE server event arrives, the fixed initial deadline is
-  // satisfied and semantic-idle ownership begins. Arming on every parsed event
-  // let a metadata-only stream (repeated response.in_progress, keepalive/ping
-  // frames, unknown event types) refresh the watchdog forever without
-  // producing a single token. Only meaningful progress re-arms it from then on.
-  let semanticIdleArmed = false;
+  // A parsed server event satisfies the first-server-event deadline and, for a
+  // request that already had output, starts the semantic idle (once: only
+  // output re-arms it).
   const noteServerEvent = () => {
     clearFirstServerEvent();
-    if (!semanticIdleArmed) {
-      semanticIdleArmed = true;
-      armSemanticIdle();
-    }
+    if (firstOutput.outputSeen && !semanticIdleTimer) armSemanticIdle();
   };
+  // Semantic output: the first one ends the first-output phase; every one
+  // re-arms the semantic idle.
   const noteMeaningful = () => {
-    semanticIdleArmed = true;
+    firstOutput.noteOutput();
     armSemanticIdle();
   };
 
@@ -151,6 +187,7 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   const dispose = () => {
     pendingReadReject = null;
     clearFirstServerEvent();
+    firstOutput.clear();
     clearSemanticIdle();
     try {
       reader.releaseLock?.();
@@ -165,9 +202,11 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   return {
     abortReason: () => abortReason,
     armFirstServerEvent,
+    armFirstOutput,
     clearSemanticIdle,
     noteServerEvent,
     noteMeaningful,
+    semanticSeen: () => firstOutput.outputSeen,
     read,
     dispose,
   };

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

@@ -183,6 +183,8 @@ export async function sendViaHttpSse({
     totalTimeout,
     stallPartial: () => state.stallPartial(),
     label,
+    sessionId: opts?.sessionId,
+    onStreamDelta,
   });
   const meaningful = (kind = 'semantic') => {
     if (ttftMs == null) ttftMs = Date.now() - sseStartedAt;
@@ -191,12 +193,17 @@ export async function sendViaHttpSse({
       onStreamDelta?.(kind);
     } catch {}
   };
+  // An empty reasoning or message item added: progress only after output.
+  const lifecycle = (kind = 'semantic') => {
+    if (watchdogs.semanticSeen()) meaningful(kind);
+  };
   const state = createHttpSseResponseState({
     body,
     onToolCall,
     onTextDelta,
     onStreamItemStart: typeof opts?.onStreamItemStart === 'function' ? opts.onStreamItemStart : null,
     meaningful,
+    lifecycle,
     onServerEvent: watchdogs.noteServerEvent,
     label,
   });
@@ -210,6 +217,7 @@ export async function sendViaHttpSse({
   let buffer = '';
   try {
     watchdogs.armFirstServerEvent();
+    watchdogs.armFirstOutput();
     while (true) {
       if (totalTimeout.signal?.aborted) {
         watchdogs.clearSemanticIdle();

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

@@ -13,8 +13,9 @@ import { randomBytes } from 'node:crypto';
 import { createOAuthPkce, parseOAuthCodeInput } from './lib/oauth-pkce.mjs';
 import { OAUTH_PAGE_CONTENT_TYPE, oauthErrorHtml, oauthSuccessHtml } from './lib/oauth-page.mjs';
 import { openLoginUrl } from './lib/open-login-url.mjs';
+import { sleepWithAbort } from './retry-backoff.mjs';
 
-const TOKEN_URL = 'https://auth.openai.com/oauth/token';
+const DEFAULT_ISSUER = 'https://auth.openai.com';
 const AUTHORIZE_URL = 'https://auth.openai.com/oauth/authorize';
 const CODEX_OAUTH_SCOPE = 'openid profile email offline_access api.connectors.read api.connectors.invoke';
 const CALLBACK_HOST = '127.0.0.1';
@@ -23,6 +24,9 @@ const CALLBACK_PATH = '/auth/callback';
 const REDIRECT_URI = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
 const TOKEN_TIMEOUT_MS = 30_000;
+// Codex device-code login: the user has 15 minutes to enter the code.
+const DEVICE_LOGIN_TIMEOUT_MS = 15 * 60_000;
+const DEFAULT_DEVICE_INTERVAL_S = 5;
 
 function _scrubOAuthLoginBody(text) {
   return String(text || '')
@@ -40,21 +44,41 @@ function _scrubOAuthLoginBody(text) {
  * @param {(...tokens:string[])=>(object|null)} deps.identityFromTokens
  * @param {(token:string)=>number} deps.expiryFromAccessToken
  * @param {(tokens:object)=>void} deps.saveTokens
+ * @param {string} [deps.issuer] auth server base URL (tests point it at a fake server)
+ * @param {(ms:number, signal?:AbortSignal)=>Promise<void>} [deps.sleep] device-poll wait (tests inject a fast one)
+ * @param {()=>number} [deps.now]
+ * @param {number} [deps.deviceTimeoutMs] device-code login deadline (tests shorten it)
+ * @param {number} [deps.requestTimeoutMs] deadline of the device-code start request (tests shorten it)
  */
 export function createOpenAIOAuthLogin(deps) {
-  const { clientId, originator, extractAccountId, identityFromTokens, expiryFromAccessToken, saveTokens } = deps;
+  const {
+    clientId,
+    originator,
+    extractAccountId,
+    identityFromTokens,
+    expiryFromAccessToken,
+    saveTokens,
+    issuer = DEFAULT_ISSUER,
+    sleep = sleepWithAbort,
+    now = Date.now,
+    deviceTimeoutMs = DEVICE_LOGIN_TIMEOUT_MS,
+    requestTimeoutMs = TOKEN_TIMEOUT_MS,
+  } = deps;
+  const issuerBase = issuer.replace(/\/+$/, '');
+  const tokenUrl = `${issuerBase}/oauth/token`;
+  const deviceApiBase = `${issuerBase}/api/accounts`;
 
-  async function exchangeAuthorizationCode({ pkce, code, signal = null }) {
+  async function exchangeAuthorizationCode({ pkce, code, redirectUri = REDIRECT_URI, signal = null }) {
     signal?.throwIfAborted();
     const cleanCode = String(code || '').trim();
     if (!cleanCode) throw new Error('[openai-oauth] authorization code is required');
-    const tokenRes = await fetch(TOKEN_URL, {
+    const tokenRes = await fetch(tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
       body: new URLSearchParams({
         grant_type: 'authorization_code',
         code: cleanCode,
-        redirect_uri: REDIRECT_URI,
+        redirect_uri: redirectUri,
         client_id: clientId,
         code_verifier: pkce.verifier,
       }),
@@ -87,7 +111,114 @@ export function createOpenAIOAuthLogin(deps) {
     return tokens;
   }
 
+  const postJson = (path, body, signal) =>
+    fetch(`${deviceApiBase}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal,
+    });
+
+  // Codex device-code flow (`codex login --device-auth`): the user enters a
+  // short code at the verification URL on any machine; this host polls until
+  // the server hands back an authorization code, then exchanges it with the
+  // deviceauth redirect URI. Resolves null when the server has no device flow.
+  async function beginDeviceLogin() {
+    // No login deadline or cancel handle exists yet, so the start request
+    // carries its own timeout; it also bounds reading the response body.
+    const startSignal = AbortSignal.timeout(requestTimeoutMs);
+    const res = await postJson('/deviceauth/usercode', { client_id: clientId }, startSignal);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`[openai-oauth] device code request failed with status ${res.status}`);
+    const started = await res.json();
+    const userCode = started.user_code || started.usercode;
+    const deviceAuthId = started.device_auth_id;
+    if (!userCode || !deviceAuthId)
+      throw new Error('[openai-oauth] device code response missing user_code or device_auth_id');
+    const interval = Number(String(started.interval ?? '').trim());
+    const intervalMs = (Number.isFinite(interval) && interval > 0 ? interval : DEFAULT_DEVICE_INTERVAL_S) * 1000;
+    const url = `${issuerBase}/codex/device`;
+
+    const controller = new AbortController();
+    const { signal } = controller;
+    const timedOut = () => new Error('[openai-oauth] device auth timed out after 15 minutes');
+    // One poll, aborted at the login deadline so a stalled request cannot
+    // outlive it. A reply that arrives in time is honoured whatever the clock
+    // says afterwards (the user did authorize).
+    const pollOnce = async (left) => {
+      const deadlineController = new AbortController();
+      const timer = setTimeout(() => deadlineController.abort(), left);
+      try {
+        const poll = await postJson(
+          '/deviceauth/token',
+          { device_auth_id: deviceAuthId, user_code: userCode },
+          AbortSignal.any([signal, deadlineController.signal])
+        );
+        if (poll.ok) return { granted: await poll.json() };
+        // 403/404: the user has not approved the code yet.
+        if (poll.status !== 403 && poll.status !== 404) {
+          throw new Error(`[openai-oauth] device auth failed with status ${poll.status}`);
+        }
+        return { granted: null };
+      } catch (err) {
+        if (!signal.aborted && deadlineController.signal.aborted) throw timedOut();
+        throw err;
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    const pollForCode = async () => {
+      const deadline = now() + deviceTimeoutMs;
+      for (;;) {
+        const left = deadline - now();
+        if (left <= 0) throw timedOut();
+        const { granted } = await pollOnce(left);
+        if (granted) return granted;
+        await sleep(Math.min(intervalMs, Math.max(0, deadline - now())), signal);
+      }
+    };
+    const waitForCallback = (async () => {
+      try {
+        const granted = await pollForCode();
+        return await exchangeAuthorizationCode({
+          pkce: { verifier: granted.code_verifier },
+          code: granted.authorization_code,
+          redirectUri: `${issuerBase}/deviceauth/callback`,
+          signal,
+        });
+      } catch (err) {
+        // A cancelled login settles empty, as the browser flow does.
+        if (signal.aborted) return null;
+        throw err;
+      }
+    })();
+    // A cancelled or expired login may reject before a host attaches a listener.
+    waitForCallback.catch(() => {});
+    process.stderr.write(
+      `\n[openai-oauth] To log in to ChatGPT (OpenAI OAuth), open:\n${url}\nand enter this code: ${userCode}\n\n`
+    );
+    return {
+      provider: 'openai-oauth',
+      url,
+      userCode,
+      waitForCallback,
+      cancel: () => controller.abort(),
+    };
+  }
+
+  // Without a browser on this host (headless/SSH) the device-code flow is used;
+  // like Codex, a server that has none (404) falls back to the browser flow.
   async function beginOAuthLogin({ openBrowser = true } = {}) {
+    if (!openBrowser) {
+      const device = await beginDeviceLogin();
+      if (device) return device;
+      process.stderr.write('\n[openai-oauth] Device code login is not enabled; falling back to browser login.\n');
+    }
+    return await beginBrowserLogin({ openBrowser });
+  }
+
+  async function beginBrowserLogin({ openBrowser }) {
     const pkce = createOAuthPkce(64);
     const state = randomBytes(16).toString('hex');
     const url = new URL(AUTHORIZE_URL);

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

@@ -18,12 +18,15 @@ import { getPluginData } from '../config.mjs';
 import { writeJsonAtomicSync, withFileLock } from '../../../shared/atomic-file.mjs';
 import { boundProviderAuthPath } from '../../../shared/provider-auth-binding.mjs';
 import { getLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
+import { TIMEOUT_PHASE } from '../../../shared/provider-timeout-phase.mjs';
 import { modelProxyClientMode, serverModelCredentialsDisabledError } from '../../../shared/model-proxy-mode.mjs';
 import {
   accountIdentityFields,
   decodeJwtPayload,
   expiryFromAccessToken,
+  isSignedInTokenDocument,
   normalizeAccountIdentity,
+  normalizeExpiresAtMs,
   oauthCredentialStatus,
 } from './lib/oauth-token-utils.mjs';
 import { createOpenAIOAuthLogin } from './openai-oauth-login.mjs';
@@ -60,11 +63,8 @@ function getRefreshLockPath() {
   return `${getOwnTokenPath()}.refresh.lock`;
 }
 
-function _normalizeExpiresAt(value) {
-  const n = Number(value || 0);
-  if (!Number.isFinite(n) || n <= 0) return 0;
-  return n < 1e12 ? n * 1000 : n;
-}
+// One normalizer for the store and the sign-in predicate (isSignedInTokenDocument).
+const _normalizeExpiresAt = normalizeExpiresAtMs;
 
 export function extractAccountId(token) {
   return decodeJwtPayload(token)?.['https://api.openai.com/auth']?.chatgpt_account_id;
@@ -117,7 +117,7 @@ export function loadTokens() {
   try {
     const stat = statSync(ownPath);
     const own = JSON.parse(readFileSync(ownPath, 'utf-8'));
-    if (own.access_token && own.refresh_token) {
+    if (isSignedInTokenDocument(own)) {
       const identity = identityFromTokens(own.id_token, own.access_token);
       return {
         ...own,
@@ -144,8 +144,7 @@ export function saveTokens(tokens) {
 // same loader the runtime uses (loadTokens), no parallel hard-coded path probe.
 export function hasOpenAIOAuthCredentials() {
   try {
-    const tokens = loadTokens();
-    return !!(tokens?.access_token && tokens?.refresh_token);
+    return !!loadTokens()?.access_token;
   } catch {
     return false;
   }
@@ -256,7 +255,9 @@ async function exchangeRefreshToken(refreshToken, previousIdentity = null) {
     return tokens;
   } catch (err) {
     if (err?.name === 'AbortError')
-      throw new Error(`OpenAI OAuth token refresh timed out after ${TOKEN_REFRESH_TIMEOUT_MS}ms`);
+      throw Object.assign(new Error(`OpenAI OAuth token refresh timed out after ${TOKEN_REFRESH_TIMEOUT_MS}ms`), {
+        timeoutPhase: TIMEOUT_PHASE.AUTH,
+      });
     throw err;
   } finally {
     clearTimeout(timeout);

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

@@ -7,13 +7,17 @@ import { createStreamSafetyStamps, resolveStallRetryBudget } from '../retry-clas
 import { _codexWsCompatibilityHeaders } from '../openai-codex-metadata.mjs';
 import { createWsSendAttempts } from '../openai-ws-send-attempts.mjs';
 import { createWsSendSpan } from '../openai-ws-send-span.mjs';
+import { emitProviderRetryStage } from '../retry-executor.mjs';
+import { retryReasonClass } from '../provider-error-kind.mjs';
 
 /** Stage callbacks are observers; a throwing one never fails the send. */
 export function notifyStage(onStageChange, stage, detail) {
   try {
     if (detail === undefined) onStageChange?.(stage);
     else onStageChange?.(stage, detail);
-  } catch {}
+  } catch {
+    // the stage observer is advisory
+  }
 }
 
 export function createWsSendContext(opts) {
@@ -81,10 +85,24 @@ export function createWsSendContext(opts) {
   // Single caller-visible recovery path for both handshake/acquire retries
   // and retryable stream failures. The session/TUI stage bridge renders this
   // as non-terminal reconnect progress; transport code must not also print it
-  // to stderr.
-  const emitReconnectProgress = ({ attempt, max, classifier }) => {
+  // to stderr. A retry that knows its failure carries the reason and the wait
+  // (retryAt), so a long server-advised wait counts down with its cause
+  // instead of sitting silently at "n/max".
+  const emitReconnectProgress = ({ attempt, max, classifier, error = null, waitMs = 0 }) => {
     const retryAttempt = Number(attempt) || 1;
     const retryMax = Number(max) || 1;
+    if (error) {
+      // The reason shown is the fixed class, never the server's own text.
+      emitProviderRetryStage(onStageChange, {
+        attempt: retryAttempt,
+        maxAttempts: retryMax,
+        lastErr: error,
+        delayMs: waitMs,
+        classifier,
+        reasonClass: retryReasonClass(error),
+      });
+      return;
+    }
     notifyStage(onStageChange, 'reconnecting', {
       attempt: retryAttempt,
       max: retryMax,
@@ -105,6 +123,7 @@ export function createWsSendContext(opts) {
     retry429,
     stallRetryBudget,
     trace: { poolKey, traceProvider, useModel },
+    traceFn: _agentTraceFn,
     auth,
     body,
   });

package/src/runtime/agent/orchestrator/providers/openai-ws-send-attempts/attempt-context.mjs

@@ -3,7 +3,34 @@
  * WS send, plus the surface/backoff primitives both failure resolvers use.
  */
 import { performance } from 'node:perf_hooks';
+import { appendAgentTrace } from '../../agent-trace.mjs';
 import { _sleepWithAbort, MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT, midstreamBackoffFor, tag } from './policy.mjs';
+import { retryReasonClass, safeRetryErrorCode } from '../provider-error-kind.mjs';
+
+/** One row per WS retry: the server's typed verdict (status, close code, an
+ *  identifier-shaped code, the reason class) and the wait it bought, so a
+ *  long advised wait is diagnosable after the fact. Never the server's free
+ *  text: it can echo request content. Diagnostics only; never throws. */
+function traceRetry(traceFn, trace, err, { attempt, max, classifier, waitMs }) {
+  try {
+    const payload = {
+      provider: trace?.traceProvider || null,
+      model: trace?.useModel || null,
+      transport: 'websocket',
+      attempt,
+      max,
+      classifier: classifier || null,
+      reason: retryReasonClass(err),
+      wait_ms: Math.round(Number(waitMs) || 0),
+      http_status: Number(err?.httpStatus || err?.status || 0) || null,
+      code: safeRetryErrorCode(err),
+      ws_close_code: Number(err?.wsCloseCode || 0) || null,
+    };
+    traceFn({ sessionId: trace?.poolKey || null, kind: 'ws_retry', ...payload, payload });
+  } catch {
+    // the retry trace sink is advisory
+  }
+}
 
 export function createAttemptContext(deps) {
   const { sendSpan, externalSignal, sleepFn, safetyStamps } = deps;
@@ -31,10 +58,13 @@ export function createAttemptContext(deps) {
   };
   // Server advice (Retry-After, or a typed rate limit's "try again in")
   // replaces the local curve, like the reference client's retry deadline.
-  const backoff = async (retryNumber, err = null) => {
+  // Resolved before the retry is announced so the reconnect stage can name
+  // the wait it is about to sit through.
+  const retryWaitMs = (retryNumber, err = null) => midstreamBackoffFor(retryNumber, err);
+  const backoff = async (waitMs) => {
     const sleepStart = performance.now();
     try {
-      await _sleepWithAbort(midstreamBackoffFor(retryNumber, err), externalSignal, sleepFn);
+      await _sleepWithAbort(waitMs, externalSignal, sleepFn);
     } catch (sleepErr) {
       sendSpan.retryBackoffMs += performance.now() - sleepStart;
       sendSpan.emit('error');
@@ -53,14 +83,21 @@ export function createAttemptContext(deps) {
     }
     return first;
   };
-  /** Stash the error a retry is about to leave behind and announce the retry. */
-  const scheduleRetry = (err, { attemptIndex, classifier, retryLimit, remember }) => {
+  /** Stash the error a retry is about to leave behind and announce the retry
+   *  with its cause and the wait before the next attempt. */
+  const scheduleRetry = (err, { attemptIndex, classifier, retryLimit, remember, waitMs = 0 }) => {
     if (remember) {
       state.firstAttemptError = err;
       state.firstAttemptClassifier = classifier;
     }
     tag(err, { midstreamClassifier: classifier });
-    deps.emitReconnectProgress({ attempt: attemptIndex + 1, max: retryLimit, classifier });
+    deps.emitReconnectProgress({ attempt: attemptIndex + 1, max: retryLimit, classifier, error: err, waitMs });
+    traceRetry(deps.traceFn || appendAgentTrace, deps.trace, err, {
+      attempt: attemptIndex + 1,
+      max: retryLimit,
+      classifier,
+      waitMs,
+    });
   };
 
   return {
@@ -69,6 +106,7 @@ export function createAttemptContext(deps) {
     maxMidstreamRetries: MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT,
     stampAll,
     surface,
+    retryWaitMs,
     backoff,
     surfaceFirstAttempt,
     scheduleRetry,

package/src/runtime/agent/orchestrator/providers/openai-ws-send-attempts/handshake-failure.mjs

@@ -81,13 +81,15 @@ export async function resolveHandshakeFailure(
   const retryable =
     classifier && status !== 401 && status !== 426 && err?.unsafeToRetry !== true && !externalSignal?.aborted;
   if (retryable && attemptIndex < ctx.maxMidstreamRetries) {
+    const waitMs = ctx.retryWaitMs(attemptIndex + 1, err);
     ctx.scheduleRetry(err, {
       attemptIndex,
       classifier,
       retryLimit: ctx.maxMidstreamRetries,
       remember: !state.firstAttemptError,
+      waitMs,
     });
-    await ctx.backoff(attemptIndex + 1, err);
+    await ctx.backoff(waitMs);
     return true;
   }
   // A later auth/upgrade decision must win over an earlier transient

package/src/runtime/agent/orchestrator/providers/openai-ws-send-attempts/stream-failure.mjs

@@ -77,7 +77,9 @@ export async function resolveStreamFailure(ctx, err, { attemptIndex, entry, midS
       process.stderr.write(
         `[openai-oauth] stall retry budget exhausted (${STREAM_STALL_RETRY_BUDGET_MS}ms since first stall) — surfacing provider-terminal failure\n`
       );
-    } catch {}
+    } catch {
+      // diagnostic write only; the provider-terminal failure is thrown next
+    }
     throw ctx.surface(markProviderRecoveryExhausted(err, { owner: 'openai-oauth-ws-stall-budget' }));
   }
   const retryLimit = classifier ? midstreamRetryLimit(classifier) : 0;
@@ -89,8 +91,9 @@ export async function resolveStreamFailure(ctx, err, { attemptIndex, entry, midS
       state.carryForwardCache = null;
       tag(entry, { lastResponseId: null });
     }
-    ctx.scheduleRetry(err, { attemptIndex, classifier, retryLimit, remember: true });
-    await ctx.backoff(attemptIndex + 1, err);
+    const waitMs = ctx.retryWaitMs(attemptIndex + 1, err);
+    ctx.scheduleRetry(err, { attemptIndex, classifier, retryLimit, remember: true, waitMs });
+    await ctx.backoff(waitMs);
     return true;
   }
   // Not retryable, OR we've already exhausted the retry budget. Do not