@yeaft/webchat-agent 0.1.1023 → 0.1.1024

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.1023",
+  "version": "0.1.1024",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/yeaft/config.js

@@ -54,8 +54,62 @@ const DEFAULTS = {
   // block is injected). Hand-edited values are NOT clamped — we let
   // power users opt into larger docs at their own context-window risk.
   projectDocMaxBytes: 32 * 1024,
+  // ─── LLM retry policy ──────────────────────────────────────
+  // How the engine reacts when adapter.stream()/call() throws a
+  // retryable error (429 / 529 / 5xx / transport failure). Each field
+  // is overridable from ~/.yeaft/config.json under "llmRetry": {…}.
+  //   • maxRetries: cap on CONSECUTIVE retryable failures per turn.
+  //     0 disables retry entirely (caller falls straight through to
+  //     fallbackModel / error). Default 3.
+  //   • baseDelayMs / maxDelayMs: exponential backoff bounds used when
+  //     the server didn't send a Retry-After header.
+  //   • jitterRatio: ± random fraction applied to backoff; 0 disables.
+  llmRetry: {
+    maxRetries: 3,
+    baseDelayMs: 1_000,
+    maxDelayMs: 30_000,
+    jitterRatio: 0.25,
+  },
 };
 
+// ─── llmRetry normalizer ────────────────────────────────────────
+
+/**
+ * Merge user-supplied retry overrides with DEFAULTS.llmRetry, clamping
+ * each field to its safe range. The output is always a fully-populated
+ * object so the engine never has to deal with `undefined`. Unknown keys
+ * in the input are dropped.
+ *
+ * Precedence: overrides > fileConfig > DEFAULTS.
+ *
+ * @param {object | null | undefined} fileConfig
+ * @param {object | null | undefined} overrides
+ * @returns {{ maxRetries: number, baseDelayMs: number, maxDelayMs: number, jitterRatio: number }}
+ */
+export function normalizeLlmRetry(fileConfig, overrides) {
+  const base = DEFAULTS.llmRetry;
+  const out = { ...base };
+  const apply = (src) => {
+    if (!src || typeof src !== 'object') return;
+    if (Number.isFinite(src.maxRetries) && src.maxRetries >= 0) {
+      out.maxRetries = Math.min(20, Math.floor(src.maxRetries));
+    }
+    if (Number.isFinite(src.baseDelayMs) && src.baseDelayMs >= 0) {
+      out.baseDelayMs = Math.min(60_000, Math.floor(src.baseDelayMs));
+    }
+    if (Number.isFinite(src.maxDelayMs) && src.maxDelayMs >= 0) {
+      out.maxDelayMs = Math.min(600_000, Math.floor(src.maxDelayMs));
+    }
+    if (Number.isFinite(src.jitterRatio) && src.jitterRatio >= 0) {
+      out.jitterRatio = Math.min(1, src.jitterRatio);
+    }
+  };
+  apply(fileConfig);
+  apply(overrides);
+  if (out.maxDelayMs < out.baseDelayMs) out.maxDelayMs = out.baseDelayMs;
+  return out;
+}
+
 // ─── config.json reader ─────────────────────────────────────────
 
 /**
@@ -220,6 +274,7 @@ function loadLegacyConfig(dir, overrides) {
   const config = {
     model: overrides.model || env.YEAFT_MODEL || fileConfig.model || 'claude-sonnet-4-20250514',
     fallbackModel: overrides.fallbackModel || env.YEAFT_FALLBACK_MODEL || fileConfig.fallbackModel || null,
+    llmRetry: normalizeLlmRetry(fileConfig.llmRetry, overrides.llmRetry),
     language: overrides.language || env.YEAFT_LANGUAGE || fileConfig.language || DEFAULTS.language,
     apiKey: overrides.apiKey || env.YEAFT_API_KEY || fileConfig.apiKey || null,
     openaiApiKey: overrides.openaiApiKey || env.YEAFT_OPENAI_API_KEY || fileConfig.openaiApiKey || null,
@@ -341,6 +396,7 @@ export function loadConfig(overrides = {}) {
     fastModel: overrides.fastModel || fastModel,
     fastModelId: fastModelId,
     fallbackModel: jsonConfig.fallbackModel || null,
+    llmRetry: normalizeLlmRetry(jsonConfig.llmRetry, overrides.llmRetry),
     modelInfo: modelInfo || null,
 
     // Providers

package/yeaft/engine.js

@@ -22,7 +22,7 @@ import { promises as fsp } from 'fs';
 import { join, resolve as resolvePath } from 'path';
 import { buildSystemPrompt, buildWorkerPrompt } from './prompts.js';
 import { getRuntimePlatformInfo } from './runtime-platform.js';
-import { LLMContextError, LLMAbortError } from './llm/adapter.js';
+import { LLMContextError, LLMAbortError, LLMRateLimitError, LLMServerError } from './llm/adapter.js';
 import { runMemoryPreflow, buildRelevantScopes } from './sessions/pre-flow.js';
 import { readProjectDoc, pickProjectDocFile, DEFAULT_PROJECT_DOC_MAX_BYTES } from './sessions/project-doc.js';
 import { partitionMessages } from './compact/partition.js';
@@ -76,6 +76,80 @@ import {
 /** Maximum auto-continue turns when stopReason is 'max_tokens'. */
 const MAX_CONTINUE_TURNS = 3;
 
+// ─── LLM retry policy defaults ──────────────────────────────────
+// Hard-coded floor / ceiling for retry behaviour. The engine reads the
+// effective policy from `config.llmRetry` so users can dial these via
+// ~/.yeaft/config.json without touching code; the constants here are the
+// fallback when the config is missing or partial.
+//   • maxRetries:     how many times we re-issue the same turn on a
+//                     retryable failure before giving up / falling back
+//   • baseDelayMs:    starting backoff for transient (5xx / network) errors
+//   • maxDelayMs:     ceiling we never exceed regardless of backoff growth
+//   • jitterRatio:    ± random fraction of the delay (0.25 = ±25 %)
+// Rate-limit waits prefer the server's Retry-After header; we only fall
+// back to exponential backoff when the header is missing.
+const RETRY_DEFAULTS = Object.freeze({
+  maxRetries: 3,
+  baseDelayMs: 1_000,
+  maxDelayMs: 30_000,
+  jitterRatio: 0.25,
+});
+
+function resolveRetryPolicy(config) {
+  const raw = config?.llmRetry || {};
+  const num = (v, d) => (Number.isFinite(v) && v >= 0 ? v : d);
+  return {
+    maxRetries: Math.max(0, Math.floor(num(raw.maxRetries, RETRY_DEFAULTS.maxRetries))),
+    baseDelayMs: Math.max(0, Math.floor(num(raw.baseDelayMs, RETRY_DEFAULTS.baseDelayMs))),
+    maxDelayMs: Math.max(0, Math.floor(num(raw.maxDelayMs, RETRY_DEFAULTS.maxDelayMs))),
+    jitterRatio: Math.min(1, Math.max(0, num(raw.jitterRatio, RETRY_DEFAULTS.jitterRatio))),
+  };
+}
+
+/**
+ * Compute the next backoff delay (ms) for a transient error.
+ * Exponential growth (base * 2^attempt) capped at maxDelayMs, with optional
+ * +/- jitter to avoid synchronized retry stampedes.
+ *
+ * @param {{ baseDelayMs: number, maxDelayMs: number, jitterRatio: number }} policy
+ * @param {number} attempt - 0-indexed retry attempt (0 = first retry)
+ * @returns {number} milliseconds to sleep
+ */
+export function computeBackoffDelay(policy, attempt) {
+  const safeAttempt = Math.max(0, Math.floor(attempt));
+  const grown = policy.baseDelayMs * Math.pow(2, safeAttempt);
+  const capped = Math.min(policy.maxDelayMs, grown);
+  if (policy.jitterRatio <= 0) return capped;
+  const jitter = capped * policy.jitterRatio;
+  const offset = (Math.random() * 2 - 1) * jitter; // [-jitter, +jitter]
+  return Math.max(0, Math.round(capped + offset));
+}
+
+/**
+ * Promise-based sleep that resolves early if the caller's AbortSignal fires.
+ * Returns true when the sleep completed normally, false when aborted.
+ *
+ * @param {number} ms
+ * @param {AbortSignal | undefined} signal
+ * @returns {Promise<boolean>}
+ */
+function sleepWithAbort(ms, signal) {
+  if (ms <= 0) return Promise.resolve(true);
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve(true);
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve(false);
+    };
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
 /**
  * task-331 — Map a conversationMessages entry into the snapshot shape used
  * by `debug_turn.messages`. Preserves the function-calling metadata that
@@ -226,8 +300,9 @@ export function shouldAllowGroupReflection({
  * @typedef {{ type: 'consolidate', archivedCount: number, extractedCount: number }} ConsolidateEvent
  * @typedef {{ type: 'recall', entryCount: number, cached: boolean }} RecallEvent
  * @typedef {{ type: 'fallback', from: string, to: string, reason: string }} FallbackEvent
+ * @typedef {{ type: 'llm_retry', attempt: number, maxRetries: number, delayMs: number, reason: 'rate_limit_retry_after'|'rate_limit_backoff'|'transient_backoff', errorName: string, statusCode: number|null, message: string }} LlmRetryEvent
  *
- * @typedef {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent | ConsolidateEvent | RecallEvent | FallbackEvent} EngineEvent
+ * @typedef {import('./llm/adapter.js').StreamEvent | TurnStartEvent | TurnEndEvent | ToolStartEvent | ToolEndEvent | ConsolidateEvent | RecallEvent | FallbackEvent | LlmRetryEvent} EngineEvent
  */
 
 // ─── Engine ──────────────────────────────────────────────────────
@@ -1760,6 +1835,16 @@ export class Engine {
     // outer-loop iteration so the flag never carries across turns.
     let endTurnRequested = null;
 
+    // LLM retry bookkeeping (rate-limit / 5xx / transient network errors).
+    // Counts CONSECUTIVE retryable failures on the same turn — reset to 0
+    // on any successful stream() iteration, and also on a fallback-model
+    // switch (the new model gets a fresh budget). Reaching maxRetries
+    // gives up: we either fall back to a backup model or surface the
+    // error to the user. LLMContextError has its own compact-retry path
+    // and does NOT count against this budget.
+    const retryPolicy = resolveRetryPolicy(this.#config);
+    let consecutiveRetryableErrors = 0;
+
     while (true) {
       turnNumber++;
 
@@ -2011,6 +2096,11 @@ export class Engine {
               break;
           }
         }
+        // Stream completed without throwing — reset the retry counter so
+        // the next turn starts with a clean budget. Note: this includes
+        // stream() that emitted an in-band `error` event (server didn't
+        // throw), since those are policy-specific and not transport-level.
+        consecutiveRetryableErrors = 0;
       } catch (err) {
         const latencyMs = Date.now() - startTime;
         this.#trace.endTurn(turnId, {
@@ -2087,12 +2177,64 @@ export class Engine {
           }
         }
 
+        // ─── Rate-limit / transient retry ─────────────────
+        // Honour server-supplied Retry-After for 429/529; fall back to
+        // exponential backoff for 5xx and transport failures wrapped as
+        // LLMServerError. Counts against retryPolicy.maxRetries; on
+        // exhaustion we fall through to the fallback-model path (and
+        // ultimately the error event) without further waiting.
+        const isRateLimit = err instanceof LLMRateLimitError;
+        const isTransient = err instanceof LLMServerError;
+        if (isRateLimit || isTransient) {
+          if (consecutiveRetryableErrors < retryPolicy.maxRetries) {
+            consecutiveRetryableErrors += 1;
+            let delayMs;
+            let reason;
+            if (isRateLimit && Number.isFinite(err.retryAfterMs) && err.retryAfterMs > 0) {
+              // Server told us exactly when to come back. Respect it,
+              // but still cap to maxDelayMs so a misconfigured upstream
+              // can't make us hang forever on one turn.
+              delayMs = Math.min(retryPolicy.maxDelayMs, err.retryAfterMs);
+              reason = 'rate_limit_retry_after';
+            } else if (isRateLimit) {
+              // No header — use backoff but start one step higher so the
+              // first retry isn't immediate (rate-limit windows are
+              // usually >= 1s wide).
+              delayMs = computeBackoffDelay(retryPolicy, consecutiveRetryableErrors);
+              reason = 'rate_limit_backoff';
+            } else {
+              delayMs = computeBackoffDelay(retryPolicy, consecutiveRetryableErrors - 1);
+              reason = 'transient_backoff';
+            }
+            yield {
+              type: 'llm_retry',
+              attempt: consecutiveRetryableErrors,
+              maxRetries: retryPolicy.maxRetries,
+              delayMs,
+              reason,
+              errorName: err.name,
+              statusCode: err.statusCode ?? null,
+              message: String(err.message || '').slice(0, 300),
+            };
+            const slept = await sleepWithAbort(delayMs, signal);
+            if (!slept || signal?.aborted) {
+              yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
+              yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+              break;
+            }
+            yield { type: 'turn_end', turnNumber, stopReason: 'llm_retry', threadId };
+            continue; // retry the same turn with the same model
+          }
+          // Exhausted — fall through to fallback-model / error paths.
+        }
+
         // ─── Fallback model ──────────────────────────────
         const fallbackModel = this.#config.fallbackModel;
         if (fallbackModel && fallbackModel !== currentModel &&
             (err.name === 'LLMRateLimitError' || err.name === 'LLMServerError')) {
           yield { type: 'fallback', from: currentModel, to: fallbackModel, reason: err.message };
           currentModel = fallbackModel;
+          consecutiveRetryableErrors = 0; // new model, fresh retry budget
           yield { type: 'turn_end', turnNumber, stopReason: 'fallback_retry', threadId };
           continue; // retry with fallback model
         }

package/yeaft/llm/adapter.js

@@ -108,6 +108,112 @@ export class LLMAbortError extends Error {
   }
 }
 
+// ─── Retry helpers ─────────────────────────────────────────────
+
+/**
+ * Parse an HTTP `Retry-After` header value into milliseconds.
+ *
+ * The header may be either:
+ *   • An integer number of seconds (delta-seconds) — `"30"`
+ *   • An HTTP-date — `"Fri, 31 Dec 1999 23:59:59 GMT"`
+ *
+ * Returns null when the header is missing, malformed, or yields a non-positive
+ * delay. Callers should treat null as "no server hint" and fall back to their
+ * own backoff schedule.
+ *
+ * @param {string | null | undefined} headerValue
+ * @returns {number | null} milliseconds to wait, or null
+ */
+export function parseRetryAfterMs(headerValue) {
+  if (!headerValue) return null;
+  const trimmed = String(headerValue).trim();
+  if (!trimmed) return null;
+  // Integer seconds path
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    if (!Number.isFinite(seconds) || seconds < 0) return null;
+    return Math.round(seconds * 1000);
+  }
+  // HTTP-date path
+  const ts = Date.parse(trimmed);
+  if (!Number.isFinite(ts)) return null;
+  const delta = ts - Date.now();
+  return delta > 0 ? delta : null;
+}
+
+/**
+ * Read the `retry-after` header from a fetch Response in a case-insensitive
+ * way that tolerates both real `Headers` instances and the plain object
+ * stand-ins our tests sometimes hand us.
+ *
+ * @param {Response | { headers?: Record<string, string> | Headers } | null | undefined} response
+ * @returns {number | null} milliseconds, or null when not present
+ */
+export function retryAfterFromResponse(response) {
+  const headers = response?.headers;
+  if (!headers) return null;
+  let raw = null;
+  if (typeof headers.get === 'function') {
+    raw = headers.get('retry-after');
+  } else {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === 'retry-after') {
+        raw = headers[key];
+        break;
+      }
+    }
+  }
+  return parseRetryAfterMs(raw);
+}
+
+/**
+ * Classify a raw error thrown by `fetch()` (or while reading a streaming
+ * body) into one of the unified LLM error types when it represents a
+ * retryable transport-level failure (DNS, ECONN*, socket reset, fetch
+ * `TypeError`, undici `UND_ERR_*`, …).
+ *
+ * Returns:
+ *   • LLMAbortError      — caller-initiated abort; engine short-circuits.
+ *   • LLMServerError     — transient transport failure; engine should retry.
+ *   • the original error — anything that doesn't match a known transient
+ *                          pattern. We never invent retryability we can't
+ *                          prove from the error shape.
+ *
+ * @param {unknown} err
+ * @param {{ providerLabel?: string }} [opts]
+ * @returns {Error}
+ */
+export function classifyFetchError(err, opts = {}) {
+  if (!(err instanceof Error)) return err instanceof Object ? err : new Error(String(err));
+  if (err.name === 'AbortError' || err.name === 'LLMAbortError') return new LLMAbortError();
+  // Anything already classified: keep as-is.
+  if (err instanceof LLMRateLimitError
+    || err instanceof LLMAuthError
+    || err instanceof LLMContextError
+    || err instanceof LLMServerError
+    || err instanceof LLMAbortError) {
+    return err;
+  }
+  const label = opts.providerLabel ? `${opts.providerLabel}: ` : '';
+  const code = err.cause?.code || err.code || null;
+  const transientCodes = new Set([
+    'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ETIMEDOUT',
+    'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'EHOSTUNREACH', 'ENETUNREACH',
+    'UND_ERR_SOCKET', 'UND_ERR_CLOSED', 'UND_ERR_BODY_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_CONNECT_TIMEOUT',
+  ]);
+  if (code && transientCodes.has(code)) {
+    return new LLMServerError(`${label}network error (${code}): ${err.message}`, 0);
+  }
+  // Node 20+ fetch surfaces network problems as a plain TypeError
+  // with `cause` set to the underlying undici error. We treat any
+  // such TypeError as transient — abort already returned above.
+  if (err.name === 'TypeError' && /fetch failed|terminated|network|socket/i.test(err.message || '')) {
+    return new LLMServerError(`${label}fetch failed: ${err.message}`, 0);
+  }
+  return err;
+}
+
 // ─── Raw payload redaction helper ──────────────────────────────
 
 /**

package/yeaft/llm/anthropic.js

@@ -9,6 +9,8 @@
 import {
   LLMAdapter,
   LLMRateLimitError,
+  classifyFetchError,
+  retryAfterFromResponse,
   LLMAuthError,
   LLMContextError,
   LLMServerError,
@@ -175,18 +177,22 @@ export class AnthropicAdapter extends LLMAdapter {
    * Classify HTTP errors into our typed errors.
    * @param {number} status
    * @param {string} body
+   * @param {Response | { headers?: Record<string, string> } | null} [response] -
+   *   When provided, reads the `retry-after` header so the engine can honor
+   *   the server hint instead of guessing a backoff delay.
    */
-  #classifyError(status, body) {
+  #classifyError(status, body, response = null) {
     const authHint = `auth=${this.#authHeaderMode}`;
     if (status === 401 || status === 403) {
       return new LLMAuthError(`Anthropic auth error (${authHint}): ${body}`, status);
     }
     if (status === 429) {
-      const retryAfter = null; // Could parse retry-after header
+      const retryAfter = retryAfterFromResponse(response);
       return new LLMRateLimitError(`Anthropic rate limit (${authHint}): ${body}`, status, retryAfter);
     }
     if (status === 529) {
-      return new LLMRateLimitError(`Anthropic overloaded (${authHint}): ${body}`, status);
+      const retryAfter = retryAfterFromResponse(response);
+      return new LLMRateLimitError(`Anthropic overloaded (${authHint}): ${body}`, status, retryAfter);
     }
     if (body.includes('prompt is too long') || body.includes('max_tokens')) {
       return new LLMContextError(`Anthropic context error (${authHint}): ${body}`);
@@ -231,12 +237,17 @@ export class AnthropicAdapter extends LLMAdapter {
     // exactly what we POST to the LLM.
     const rawRequest = redactRawRequest({ url, method: 'POST', headers, body });
 
-    const response = await fetch(url, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(body),
-      signal,
-    });
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (err) {
+      throw classifyFetchError(err, { providerLabel: 'Anthropic' });
+    }
 
     if (!response.ok) {
       const errorBody = await response.text();
@@ -253,7 +264,7 @@ export class AnthropicAdapter extends LLMAdapter {
           });
         } catch { /* ignore */ }
       }
-      throw this.#classifyError(response.status, errorBody);
+      throw this.#classifyError(response.status, errorBody, response);
     }
 
     // Parse SSE stream
@@ -469,16 +480,21 @@ export class AnthropicAdapter extends LLMAdapter {
       applyAnthropicThinking(body, model, normEffort);
     }
 
-    const response = await fetch(`${this.#baseUrl}/v1/messages`, {
-      method: 'POST',
-      headers: this.#headers(),
-      body: JSON.stringify(body),
-      signal,
-    });
+    let response;
+    try {
+      response = await fetch(`${this.#baseUrl}/v1/messages`, {
+        method: 'POST',
+        headers: this.#headers(),
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (err) {
+      throw classifyFetchError(err, { providerLabel: 'Anthropic' });
+    }
 
     if (!response.ok) {
       const errorBody = await response.text();
-      throw this.#classifyError(response.status, errorBody);
+      throw this.#classifyError(response.status, errorBody, response);
     }
 
     const result = await response.json();

package/yeaft/llm/openai-responses.js

@@ -32,6 +32,8 @@ import {
   LLMContextError,
   LLMServerError,
   LLMAbortError,
+  classifyFetchError,
+  retryAfterFromResponse,
   redactRawRequest,
   safeHeaders,
 } from './adapter.js';
@@ -187,15 +189,17 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
 
   // ─── Error classification ───────────────────────────────
 
-  #classifyError(status, body) {
+  #classifyError(status, body, response = null) {
     if (status === 401 || status === 403) {
       return new LLMAuthError(`Auth error: ${body}`, status);
     }
     if (status === 429) {
-      return new LLMRateLimitError(`Rate limit: ${body}`, status);
+      const retryAfter = retryAfterFromResponse(response);
+      return new LLMRateLimitError(`Rate limit: ${body}`, status, retryAfter);
     }
     if (status === 529) {
-      return new LLMRateLimitError(`Overloaded: ${body}`, status);
+      const retryAfter = retryAfterFromResponse(response);
+      return new LLMRateLimitError(`Overloaded: ${body}`, status, retryAfter);
     }
     if (status === 413 || body.includes('context_length_exceeded') || body.includes('maximum context length')) {
       return new LLMContextError(`Context too long: ${body}`);
@@ -286,7 +290,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
       });
     } catch (err) {
       if (err.name === 'AbortError') throw new LLMAbortError();
-      throw err;
+      throw classifyFetchError(err, { providerLabel: 'OpenAI' });
     }
 
     if (!response.ok) {
@@ -304,7 +308,7 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
           });
         } catch { /* ignore */ }
       }
-      throw this.#classifyError(response.status, errorBody);
+      throw this.#classifyError(response.status, errorBody, response);
     }
 
     const reader = response.body.getReader();
@@ -512,12 +516,12 @@ export class OpenAIResponsesAdapter extends LLMAdapter {
       });
     } catch (err) {
       if (err.name === 'AbortError') throw new LLMAbortError();
-      throw err;
+      throw classifyFetchError(err, { providerLabel: 'OpenAI' });
     }
 
     if (!response.ok) {
       const errorBody = await response.text();
-      throw this.#classifyError(response.status, errorBody);
+      throw this.#classifyError(response.status, errorBody, response);
     }
 
     const result = await response.json();

package/yeaft/web-bridge.js

@@ -2264,6 +2264,23 @@ function handleEngineEvent(event, hctx) {
       }, envelope);
       break;
 
+    case 'llm_retry':
+      // Engine paused before re-issuing the same turn because the LLM
+      // returned a retryable error (rate limit / 5xx / transient network).
+      // Surface to the client so the UI can show "retrying in Xs (1/3)"
+      // instead of looking frozen mid-turn.
+      sendSessionEvent({
+        type: 'llm_retry',
+        attempt: event.attempt,
+        maxRetries: event.maxRetries,
+        delayMs: event.delayMs,
+        reason: event.reason,
+        errorName: event.errorName,
+        statusCode: event.statusCode,
+        message: event.message,
+      }, envelope);
+      break;
+
     case 'reflection':
       sendSessionEvent({
         type: 'reflection',