mixdog 1.2.0 → 1.2.2

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state/response-events/terminal-frames.mjs

@@ -10,7 +10,8 @@ import {
   incompleteReasonFromEvent,
   isMaxOutputIncompleteReason,
 } from '../../lib/responses-terminal-fields.mjs';
-import { LABEL, toolInputPending } from '../response-state.mjs';
+import { applyErrorContract, markContentFilter } from '../../openai-error-contract.mjs';
+import { toolInputPending } from '../response-state.mjs';
 import { normalizeWsUsage } from '../../openai-ws-response-state/usage.mjs';
 
 // Typed status only — nothing is synthesized from text. The frame itself is
@@ -19,11 +20,14 @@ import { normalizeWsUsage } from '../../openai-ws-response-state/usage.mjs';
 function wireFailureError(message, event, detail, typedSources) {
   const err = new Error(message);
   err.responseFailed = event;
-  const typed = typedStatusFrom(...typedSources);
-  if (typed) err.httpStatus = typed;
   const code = detail?.code ?? detail?.type ?? null;
   if (typeof code === 'string' && code) err.providerErrorCode = code;
-  return err;
+  return applyErrorContract(err, {
+    status: typedStatusFrom(...typedSources),
+    code: typeof code === 'string' ? code : undefined,
+    error: detail,
+    event,
+  });
 }
 
 export function createTerminalFrameEvents({ state, items, text, outcome, meaningful }) {
@@ -89,7 +93,7 @@ export function createTerminalFrameEvents({ state, items, text, outcome, meaning
     absorbTerminalResponse(event.response || {});
     const reason = incompleteReasonFromEvent(event);
     if (!isMaxOutputIncompleteReason(reason)) {
-      const err = new Error(`${LABEL} ${frame}: ${reason}`);
+      const err = markContentFilter(new Error(`${state.label} ${frame}: ${reason}`), reason);
       // Still billed: the provider-boundary accounting records reported usage.
       if (state.usage) {
         err.partialUsage = state.usage;
@@ -98,7 +102,7 @@ export function createTerminalFrameEvents({ state, items, text, outcome, meaning
       throw err;
     }
     if (toolInputPending(state)) {
-      const err = outcome.stampToolSafety(new Error(`${LABEL} ${frame} (max_output_tokens) with tool call in flight`));
+      const err = outcome.stampToolSafety(new Error(`${state.label} ${frame} (max_output_tokens) with tool call in flight`));
       err.streamStalled = true;
       err.pendingToolUse = true;
       err.partialContent = state.content;
@@ -119,9 +123,12 @@ export function createTerminalFrameEvents({ state, items, text, outcome, meaning
       setEndTurn(event);
     } else if (event.response.status === 'failed') {
       const msg = event.response?.error?.message || 'response.done failed';
-      const err = new Error(`${LABEL} response.done failed: ${msg}`);
-      const typed = typedStatusFrom(event.response?.error, event.error, event);
-      if (typed) err.httpStatus = typed;
+      const err = new Error(`${state.label} response.done failed: ${msg}`);
+      applyErrorContract(err, {
+        status: typedStatusFrom(event.response?.error, event.error, event),
+        error: event.response?.error || event.error || null,
+        event,
+      });
       throw withFailedUsage(err, event);
     } else if (event.response.status === 'incomplete') {
       onIncomplete(event, 'response.done incomplete');
@@ -131,7 +138,7 @@ export function createTerminalFrameEvents({ state, items, text, outcome, meaning
   const failedFrameError = (event) =>
     withFailedUsage(
       wireFailureError(
-        `${LABEL} response.failed: ${event.response?.error?.message || event.error?.message || event.message || 'response.failed'}`,
+        `${state.label} response.failed: ${event.response?.error?.message || event.error?.message || event.message || 'response.failed'}`,
         event,
         event.response?.error || event.error || null,
         [event.response?.error, event.error, event]
@@ -142,7 +149,7 @@ export function createTerminalFrameEvents({ state, items, text, outcome, meaning
   // Same wire-error contract as response.failed.
   const errorFrameError = (event) =>
     wireFailureError(
-      `${LABEL} error: ${event.message || event.error?.message || 'unknown'}`,
+      `${state.label} error: ${event.message || event.error?.message || 'unknown'}`,
       event,
       { code: event.error?.code ?? event.error?.type ?? event.code ?? null },
       [event.error, event]

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state/response-outcome.mjs

@@ -8,7 +8,6 @@ import { traceAgentSse, traceAgentUsage } from '../../agent-trace.mjs';
 import { dedupeToolCallList } from '../lib/leaked-toolcall.mjs';
 import { _displayCodexModel } from '../openai-codex-model.mjs';
 import { createProviderReplay } from '../lib/provider-replay.mjs';
-import { LABEL } from './response-state.mjs';
 import { createResponseStamps } from './response-stamps.mjs';
 
 export function createResponseOutcome({ state }) {
@@ -50,7 +49,7 @@ export function createResponseOutcome({ state }) {
       throw stampOutcome(
         stampToolSafety(
           new Error(
-            `${LABEL} function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`
+            `${state.label} function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`
           )
         )
       );

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state/response-stamps.mjs

@@ -9,7 +9,7 @@
  */
 import { stampStreamOutcome, STREAM_TRANSPORTS } from '../lib/stream-outcome.mjs';
 import { createProviderReplay } from '../lib/provider-replay.mjs';
-import { LABEL, toolInputPending } from './response-state.mjs';
+import { toolInputPending } from './response-state.mjs';
 
 export function createResponseStamps({ state }) {
   const stampToolSafety = (err) => {
@@ -111,7 +111,7 @@ export function createResponseStamps({ state }) {
     const err = attachStreamPartial(
       stampToolSafety(
         new Error(
-          `${LABEL} ended before response.completed (text=${state.content.length} chars, toolCalls=${state.toolCalls.length})`
+          `${state.label} ended before response.completed (text=${state.content.length} chars, toolCalls=${state.toolCalls.length})`
         )
       )
     );

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

@@ -8,10 +8,9 @@
 import { createActiveToolItemTracker } from '../tool-stream-state.mjs';
 import { createToolCallDedupe } from '../lib/leaked-toolcall.mjs';
 
-export const LABEL = 'OpenAI OAuth HTTP fallback';
-
-export function createResponseState() {
+export function createResponseState(label) {
   return {
+    label,
     content: '',
     model: '',
     responseId: '',

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

@@ -26,8 +26,8 @@ import { createResponseEvents } from './openai-http-sse-response-state/response-
  * @param {(kind: string) => void} deps.meaningful  semantic progress (re-arms the idle watchdog)
  * @param {() => void} deps.onServerEvent  first-event → semantic-idle handover
  */
-export function createHttpSseResponseState({ body, onToolCall, onTextDelta, meaningful, onServerEvent }) {
-  const state = createResponseState();
+export function createHttpSseResponseState({ body, onToolCall, onTextDelta, meaningful, onServerEvent, label }) {
+  const state = createResponseState(label);
   const outcome = createResponseOutcome({ state });
   const items = createResponseItems({ state, onToolCall });
   const text = createTextRelay({ state, body, onTextDelta, meaningful, emitToolCall: items.emitToolCall });

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

@@ -20,8 +20,6 @@ import {
   streamStalledError,
 } from '../stall-policy.mjs';
 
-const LABEL = 'OpenAI OAuth HTTP fallback';
-
 function positiveOverride(value) {
   const ms = Number(value);
   return Number.isFinite(ms) && ms > 0 ? ms : 0;
@@ -34,7 +32,7 @@ function positiveOverride(value) {
  * @param {{ signal?: AbortSignal, cleanup(): void }} deps.totalTimeout
  * @param {() => object} deps.stallPartial  streamed partial state attached to a semantic-idle stall
  */
-export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartial }) {
+export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartial, label: LABEL }) {
   let abortReason = null;
   let pendingReadReject = null;
   const rejectPendingRead = (err) => {

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

@@ -13,6 +13,9 @@ import { codexCatalogHas } from './openai-oauth-catalog.mjs';
 import { _displayCodexModel } from './openai-codex-model.mjs';
 import { _envFlag, _shouldUseOpenAIHttpFallback } from './openai-oauth-http-sse.mjs';
 import { isWsMessageTooBigClose } from './retry-classifier.mjs';
+import { waitForRetryDeadline } from './openai-error-contract.mjs';
+import { isReplaySafe } from './lib/stream-outcome.mjs';
+import { noteErrorUsage } from './lib/note-error-usage.mjs';
 
 function openAiOAuthHandshakeErrorPolicy({ status }) {
   if (Number(status) === 404) {
@@ -130,6 +133,17 @@ export function createOpenAiOAuthDispatch({
       });
     } catch {}
   };
+  // A 401 is recoverable once per send, and only while nothing the turn
+  // produced could be duplicated by reissuing it.
+  const canReissueAfter401 = (err) =>
+    Number(err?.httpStatus || err?.status || 0) === 401 &&
+    authState.authRefreshed !== true &&
+    !externalSignal?.aborted &&
+    err?.liveTextEmitted !== true &&
+    err?.emittedToolCall !== true &&
+    err?.toolCallEmitted !== true &&
+    err?.unsafeToRetry !== true &&
+    isReplaySafe(err);
   const dispatchHttp = async (reason, originalErr = null, { sticky = false } = {}) => {
     // Transport switching is a session decision, not an HTTP-success
     // side effect. Persist it before the fallback can fail or abort.
@@ -158,9 +172,10 @@ export function createOpenAiOAuthDispatch({
       if (!process.env.MIXDOG_QUIET_PROVIDER_LOG)
         process.stderr.write(`[openai-oauth] WebSocket unhealthy (${reason}); falling back to HTTP/SSE\n`);
     }
-    let result;
-    try {
-      result = await sendHttp({
+    // The server's retry deadline outlives a transport switch.
+    if (originalErr && reason !== 'forced') await waitForRetryDeadline(originalErr, externalSignal, opts._sleepFn);
+    const sendHttpOnce = () =>
+      sendHttp({
         auth: authState.tokens,
         body,
         opts,
@@ -175,6 +190,22 @@ export function createOpenAiOAuthDispatch({
         useModel,
         fetchFn: opts._fetchFn,
       });
+    let result;
+    try {
+      try {
+        result = await sendHttpOnce();
+      } catch (firstErr) {
+        if (!canReissueAfter401(firstErr)) throw firstErr;
+        // Same bounded, replay-safe recovery the WS path applies: one forced
+        // refresh per send, one reissue of the identical request.
+        noteErrorUsage(firstErr);
+        traceTransportError(firstErr, 'primary', 'http');
+        process.stderr.write('[openai-oauth-http] 401 — forcing refresh and retrying once over HTTP/SSE\n');
+        authState.authRefreshed = true;
+        provider._refreshFallbackUntil = 0;
+        authState.tokens = await provider.ensureAuth({ forceRefresh: true, reason: '401' });
+        result = await sendHttpOnce();
+      }
     } catch (httpErr) {
       // The current transport owns the terminal decision, including
       // auth, rate limits, cancellation and output-safety markers.

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

@@ -16,6 +16,7 @@ import { CODEX_OAUTH_ORIGINATOR } from './openai-codex-endpoints.mjs';
 import { parseProviderJsonBatch } from './stream-json-pool.mjs';
 import { envFlag as _envFlag } from '../../../shared/env.mjs';
 import { activateCodexTurnState } from './openai-turn-state.mjs';
+import { httpLabel } from './openai-error-contract.mjs';
 import { openHttpSseResponse } from './openai-http-sse-request.mjs';
 import { createHttpSseWatchdogs } from './openai-http-sse-watchdogs.mjs';
 import { createHttpSseResponseState } from './openai-http-sse-response-state.mjs';
@@ -165,6 +166,7 @@ export async function sendViaHttpSse({
     onStageChange?.('streaming');
   } catch {}
   const sseStartedAt = Date.now();
+  const label = httpLabel(auth);
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let ttftMs = null;
@@ -173,6 +175,7 @@ export async function sendViaHttpSse({
     reader,
     totalTimeout,
     stallPartial: () => state.stallPartial(),
+    label,
   });
   const meaningful = (kind = 'semantic') => {
     if (ttftMs == null) ttftMs = Date.now() - sseStartedAt;
@@ -187,6 +190,7 @@ export async function sendViaHttpSse({
     onTextDelta,
     meaningful,
     onServerEvent: watchdogs.noteServerEvent,
+    label,
   });
   const foldFrames = async (text) => {
     const parsed = _sseEventsFromBuffer(text);
@@ -202,7 +206,7 @@ export async function sendViaHttpSse({
       if (totalTimeout.signal?.aborted) {
         watchdogs.clearSemanticIdle();
         const reason = totalTimeout.signal.reason;
-        throw reason instanceof Error ? reason : new Error('OpenAI OAuth HTTP fallback aborted');
+        throw reason instanceof Error ? reason : new Error(`${label} aborted`);
       }
       const abortReason = watchdogs.abortReason();
       if (abortReason) throw abortReason;

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

@@ -189,6 +189,7 @@ export function forgetOpenAIOAuthCredentials() {
 }
 
 // --- Token refresh ---
+const PERMANENT_REFRESH_FAILURE_RE = /invalid_grant|revoked|reused|refresh_token_(?:expired|invalidated)/i;
 async function exchangeRefreshToken(refreshToken, previousIdentity = null) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), TOKEN_REFRESH_TIMEOUT_MS);
@@ -214,10 +215,17 @@ async function exchangeRefreshToken(refreshToken, previousIdentity = null) {
       // CLI's single-use lineage) from transient failures, so the caller can
       // re-read disk and retry once with a newer token instead of
       // collapsing every failure to a generic null.
-      if (res.status === 400 || res.status === 401 || /invalid_grant|revoked|reused/i.test(text)) {
+      // Only a CONFIRMED permanent refusal sets reauthRequired: a 401, or a
+      // typed refresh-token code. A bare 400/5xx/429 is not evidence the
+      // refresh token is dead.
+      if (res.status === 401 || PERMANENT_REFRESH_FAILURE_RE.test(text)) {
         throw Object.assign(new Error(`OpenAI OAuth token refresh ${res.status} (invalid_grant)`), {
           isInvalidGrant: true,
           reauthRequired: true,
+          status: res.status,
+          httpStatus: res.status,
+          code: 'invalid_grant',
+          headers: res.headers,
         });
       }
       return null;
@@ -312,7 +320,19 @@ async function refreshUnderLock({ currentToken, force, reason, startingTokens })
       process.stderr.write(`[openai-oauth] Refresh failed (${msg}); using still-valid current token\n`);
       return { tokens: reusable, coastOnCurrent: true };
     }
-    throw new Error(`OpenAI OAuth token refresh failed (${msg}). Re-authenticate via provider login.`);
+    const failure = new Error(`OpenAI OAuth token refresh failed (${msg}). Re-authenticate via provider login.`);
+    // The wrapper must not hide a confirmed permanent refusal from the account pool.
+    if (err?.reauthRequired === true) {
+      Object.assign(failure, {
+        reauthRequired: true,
+        isInvalidGrant: true,
+        status: err.status,
+        httpStatus: err.httpStatus,
+        code: err.code,
+        headers: err.headers,
+      });
+    }
+    throw failure;
   }
 }
 

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

@@ -86,6 +86,9 @@ export class OpenAIOAuthProvider {
   // so input alone is the context footprint. See registry.mjs.
   static inputExcludesCache = false;
   name = 'openai-oauth';
+  // Loop retry policy (send-with-recovery loopRetryPolicy): a connect failure waits for
+  // the network, and a content_filter refusal is replayed under the budget.
+  retryPolicy = Object.freeze({ unboundedConnectionRetry: true, contentFilterRetryable: true });
   tokens = null;
   _refreshFallbackUntil = 0;
   // Sticky transport fallback is isolated by the WS pool/session key. A
@@ -277,6 +280,8 @@ export class OpenAIOAuthProvider {
           process.stderr.write(`[agent-trace] provider-${status}-retry attempt=1\n`);
         }
         this._refreshFallbackUntil = 0;
+        // One forced refresh per send, shared with the HTTP/SSE dispatch.
+        authState.authRefreshed = true;
         authState.tokens = await this.ensureAuth({ forceRefresh: true, reason: String(status) });
         try {
           const result = await dispatch.dispatchWs(true);

package/src/runtime/agent/orchestrator/providers/openai-responses-input.mjs

@@ -1,6 +1,7 @@
 // Transcript lowering is independent of request/turn metadata. A retained
 // message must have the same wire representation in every subsequent request.
 import { providerReplayItems } from './lib/provider-replay.mjs';
+import { responsesEffortUpdates } from './effort-configuration.mjs';
 import { ensureResponsesCallOutputs } from './lib/wire-pairing.mjs';
 import { normalizeContentForOpenAIResponses, splitToolContentForOpenAIResponses } from './media-normalization.mjs';
 import {
@@ -156,21 +157,16 @@ export function convertMessagesToResponsesInput(messages, opts = {}) {
     if (!pendingToolMedia.length) return;
     out.push(wireMessage('user', pendingToolMedia.splice(0)));
   };
-  // An update on a tool result applies after its whole batch; one on a user
-  // message before it. Adjacent updates are rejected, so a batch update that
-  // a user message directly follows yields to that message's own.
-  let afterBatch = null;
+  const effortUpdates = responsesEffortUpdates(opts.effortProjection);
   for (const m of messages) {
     if (!m || m.role === 'system') continue;
-    const changedEffort = opts.effortProjection?.updates.get(m);
+    const updates = effortUpdates.before(m);
     if (m.role === 'tool') {
       pushToolResult(m, { out, pendingToolMedia, pendingToolLoads, customToolCallNameById, nativeSearchCalls, opts });
-      if (changedEffort) afterBatch = changedEffort;
       continue;
     }
     flushToolMedia();
-    if (changedEffort || afterBatch) out.push({ type: 'configuration_update', reasoning: { effort: changedEffort || afterBatch } });
-    afterBatch = null;
+    out.push(...updates);
     // Preserve original assistant phases and item order even when encrypted
     // reasoning is explicitly disabled. Never replay another provider's data.
     const orderedReplay =
@@ -212,7 +208,7 @@ export function convertMessagesToResponsesInput(messages, opts = {}) {
     pushReasoningItems(m, 'after');
   }
   flushToolMedia();
-  if (afterBatch) out.push({ type: 'configuration_update', reasoning: { effort: afterBatch } });
+  out.push(...effortUpdates.end());
   // Wire-level pairing guard: replay envelopes can carry a call whose
   // result never committed (cancel/abort). The provider hard-rejects the
   // unpaired call, so synthesize the missing outputs here.

package/src/runtime/agent/orchestrator/providers/openai-retry-policy.mjs

@@ -0,0 +1,9 @@
+// OpenAI retry schedule: 200ms base, factor 2, ±10%.
+// Provider-owned values; the shared retry core only takes them as options.
+//   CODEX_STREAM_BACKOFF_MS        — indexed by the 1-based retry number
+//                                    (midstreamBackoffFor).
+//   CODEX_REQUEST_RETRY_BACKOFF_MS — leading duplicate for withRetry's
+//                                    sleep-before-attempt index.
+export const CODEX_STREAM_BACKOFF_MS = Object.freeze([200, 400, 800, 1600, 3200]);
+export const CODEX_REQUEST_RETRY_BACKOFF_MS = Object.freeze([200, ...CODEX_STREAM_BACKOFF_MS]);
+export const CODEX_RETRY_JITTER_RATIO = 0.1;

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

@@ -9,6 +9,11 @@
 import { appendFileSync, chmodSync } from 'node:fs';
 import { errText } from '../../../shared/err-text.mjs';
 import { _cfCookieCapture, _formatRedactedHeaders } from './openai-ws-headers.mjs';
+import { httpResponseError } from './openai-error-contract.mjs';
+
+// Enough of the handshake body to parse a typed JSON error; diagnostics are
+// truncated separately by the error message.
+const HANDSHAKE_BODY_LIMIT = 16 * 1024;
 
 /** CF cookie jar refresh plus the opt-in upgrade-header dump. */
 export function captureHandshakeUpgrade(auth, res) {
@@ -85,7 +90,7 @@ export function attachHandshakeFailureHandlers({ socket, errLabel, openStart, is
     const status = res?.statusCode || 0;
     let body = '';
     res.on('data', (c) => {
-      if (body.length < 2048) body += c.toString('utf-8');
+      if (body.length < HANDSHAKE_BODY_LIMIT) body += c.toString('utf-8');
     });
     res.on('end', () => {
       if (process.env.MIXDOG_DEBUG_AGENT) {
@@ -96,13 +101,16 @@ export function attachHandshakeFailureHandlers({ socket, errLabel, openStart, is
       try {
         socket.terminate();
       } catch {}
-      settle(
-        false,
-        Object.assign(new Error(`${errLabel} handshake ${status}: ${body.slice(0, 200)}`), {
-          httpStatus: status,
-          httpBody: body,
-        })
-      );
+      // Status, headers and the parsed body ride on the error; only the
+      // message is truncated.
+      const err = httpResponseError({
+        label: `${errLabel} handshake`,
+        status,
+        headers: res.headers,
+        text: body,
+      });
+      err.httpBody = body;
+      settle(false, err);
     });
   });
 }

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

@@ -3,7 +3,6 @@
  * WS send, plus the surface/backoff primitives both failure resolvers use.
  */
 import { performance } from 'node:perf_hooks';
-import { retryAfterMsFromError } from '../retry-classifier.mjs';
 import { _sleepWithAbort, MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT, midstreamBackoffFor, tag } from './policy.mjs';
 
 export function createAttemptContext(deps) {
@@ -35,7 +34,7 @@ export function createAttemptContext(deps) {
   const backoff = async (retryNumber, err = null) => {
     const sleepStart = performance.now();
     try {
-      await _sleepWithAbort(retryAfterMsFromError(err) ?? midstreamBackoffFor(retryNumber), externalSignal, sleepFn);
+      await _sleepWithAbort(midstreamBackoffFor(retryNumber, err), externalSignal, sleepFn);
     } catch (sleepErr) {
       sendSpan.retryBackoffMs += performance.now() - sleepStart;
       sendSpan.emit('error');

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

@@ -2,12 +2,13 @@
  * policy.mjs — the WS send retry budget, its backoff curves and the
  * classification wrappers shared by the handshake and stream resolvers.
  */
+import { CODEX_RETRY_JITTER_RATIO, CODEX_STREAM_BACKOFF_MS } from '../openai-retry-policy.mjs';
 import {
   classifyHandshakeError,
   classifyMidstreamError,
   isWsMessageTooBigClose,
-  jitterDelayMs,
   MIDSTREAM_RETRY_POLICY,
+  midstreamBackoffFor as sharedMidstreamBackoffFor,
   sleepWithAbort,
 } from '../retry-classifier.mjs';
 
@@ -15,23 +16,26 @@ import {
 // by connect/handshake and pre-output stream failures.
 export const MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.transientCloseRetries;
 const MIDSTREAM_DEFAULT_RETRY_LIMIT = MIDSTREAM_RETRY_POLICY.ws.defaultRetries;
-// The reference client uses a 200ms base, factor 2, and symmetric ±10%
-// jitter for each of its five stream retries.
-const MIDSTREAM_BACKOFF_MS = Object.freeze([200, 400, 800, 1600, 3200]);
-const CODEX_RETRY_JITTER_RATIO = 0.1;
+// The stream retry schedule (200ms base, factor 2, ±10%) lives in
+// openai-retry-policy.mjs, shared with the HTTP request loop.
+// Advice-gated retry (OAuth and API-key WS alike): an overload and an untyped 429
+// retry only when the server gave advice.
+const ADVICE_GATES = Object.freeze({
+  overloadRetryRequiresAdvice: true,
+  generic429RetryRequiresAdvice: true,
+});
 // 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,
+  ...ADVICE_GATES,
 };
 
 // Kept for the _acquireWithRetry test seam and non-Codex callers.
 // sendViaWebSocket deliberately invokes it with maxAttempts:1 so handshake
 // failures consume the same stream budget as pre-output disconnects.
 export const HANDSHAKE_MAX_ATTEMPTS = MIDSTREAM_WS_TRANSIENT_RETRY_LIMIT + 1;
-const HANDSHAKE_BACKOFF_BASE_MS = 200;
-const HANDSHAKE_BACKOFF_CAP_MS = 3200;
 // These statuses are decisions made by the CURRENT attempt. They must never
 // be replaced by a stale transient from an earlier retry: auth recovery,
 // transport fallback, and Retry-After handling all depend on the live error.
@@ -47,8 +51,15 @@ export function _mustSurfaceCurrentAttempt(err, externalSignal) {
   );
 }
 
-export function _classifyHandshakeError(err, { retry429 = true } = {}) {
-  return classifyHandshakeError(err, { retry429 });
+export function _classifyHandshakeError(
+  err,
+  {
+    retry429 = true,
+    overloadRetryRequiresAdvice = ADVICE_GATES.overloadRetryRequiresAdvice,
+    generic429RetryRequiresAdvice = ADVICE_GATES.generic429RetryRequiresAdvice,
+  } = {}
+) {
+  return classifyHandshakeError(err, { retry429, overloadRetryRequiresAdvice, generic429RetryRequiresAdvice });
 }
 
 /**
@@ -103,15 +114,15 @@ export function midstreamRetryLimit(classifier) {
     : MIDSTREAM_DEFAULT_RETRY_LIMIT;
 }
 
-export function midstreamBackoffFor(retryNumber) {
-  const raw = MIDSTREAM_BACKOFF_MS[Math.min(Math.max(retryNumber, 1), MIDSTREAM_BACKOFF_MS.length) - 1];
-  return jitterDelayMs(raw, CODEX_RETRY_JITTER_RATIO);
+// Passing the failure makes server advice replace the step for retryable
+// kinds only (midstreamRetryDelayMs).
+export function midstreamBackoffFor(retryNumber, err = null) {
+  return sharedMidstreamBackoffFor(retryNumber, CODEX_STREAM_BACKOFF_MS, err, CODEX_RETRY_JITTER_RATIO);
 }
 
 export function _backoffFor(attempt) {
   // attempt is 1-based; exponential backoff is capped before jitter.
-  const raw = HANDSHAKE_BACKOFF_BASE_MS * (1 << (attempt - 1));
-  return jitterDelayMs(Math.min(raw, HANDSHAKE_BACKOFF_CAP_MS), CODEX_RETRY_JITTER_RATIO);
+  return midstreamBackoffFor(attempt);
 }
 
 export const _defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));

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

@@ -4,6 +4,7 @@
  * builder returns a tagged Error the stream loop stores as terminalError.
  */
 import { typedStatusFrom } from './retry-classifier.mjs';
+import { applyErrorContract, markContentFilter } from './openai-error-contract.mjs';
 import { _httpStatusFromWsClose } from './openai-ws-events.mjs';
 
 /** A server `event.error` on any frame. Same wire-error contract as
@@ -17,10 +18,9 @@ export function serverErrorEventError(error, event) {
   try {
     err.payload = error;
     err.responseFailed = event;
-    const typed = typedStatusFrom(error, event);
-    if (typed) err.httpStatus = typed;
     const code = error.code ?? error.type ?? null;
     if (typeof code === 'string' && code) err.providerErrorCode = code;
+    applyErrorContract(err, { status: typedStatusFrom(error, event), error, event });
   } catch {}
   return err;
 }
@@ -32,23 +32,27 @@ export function serverErrorEventError(error, event) {
 export function responseFailedError(event, { label, fallbackMessage, providerErrorCode = false }) {
   const msg = event.response?.error?.message || event.error?.message || event.message || fallbackMessage;
   const err = Object.assign(new Error(`${label}: ${msg}`), { responseFailed: event });
-  const typed = typedStatusFrom(event.response?.error, event.error, event);
-  if (typed) err.httpStatus = typed;
+  const detail = event.response?.error || event.error || null;
   if (providerErrorCode) {
-    const detail = event.response?.error || event.error || null;
     const code = detail?.code ?? detail?.type ?? null;
     if (typeof code === 'string' && code) err.providerErrorCode = code;
   }
-  return err;
+  return applyErrorContract(err, {
+    status: typedStatusFrom(event.response?.error, event.error, event),
+    error: detail,
+    event,
+  });
 }
 
 /** response.incomplete (or response.done status 'incomplete') for a reason
- *  other than max_output_tokens. */
+ *  other than max_output_tokens. A content_filter stop is a typed policy
+ *  refusal (code 'content_filter'), not an untyped failure. */
 export function responseIncompleteError(event, reasonStr, label) {
-  return Object.assign(new Error(`${label}: ${reasonStr}`), {
+  const err = Object.assign(new Error(`${label}: ${reasonStr}`), {
     responseIncomplete: event,
     incompleteReason: reasonStr,
   });
+  return markContentFilter(err, reasonStr);
 }
 
 /** response.done with a status that is neither completed, failed nor incomplete. */
@@ -63,11 +67,14 @@ export function errorFrameError(event, label) {
   const errMsg = String(event.message || event.error?.message || 'unknown');
   const err = new Error(`${label}: ${errMsg}`);
   err.responseFailed = event;
-  const typed = typedStatusFrom(event.error, event);
-  if (typed) err.httpStatus = typed;
   const code = event.error?.code ?? event.error?.type ?? event.code ?? null;
   if (typeof code === 'string' && code) err.providerErrorCode = code;
-  return err;
+  return applyErrorContract(err, {
+    status: typedStatusFrom(event.error, event),
+    code: typeof code === 'string' ? code : undefined,
+    error: event.error,
+    event,
+  });
 }
 
 /** The socket closed before a terminal frame. */