mixdog 1.2.1 → 1.2.3

package/src/runtime/agent/orchestrator/providers/openai-compat-responses-parity.fixtures.mjs

@@ -0,0 +1,172 @@
+// Shared by openai-compat-responses-native.test.mjs and the one-off generator
+// that produced openai-compat-responses-head-parity.json by running these same
+// captures against the pre-change (HEAD) converters.
+import { sendCompatResponses } from './openai-compat-responses.mjs';
+import { OpenAICompatProvider } from './openai-compat.mjs';
+import { buildRequestBody } from './openai-responses-payload.mjs';
+import { createProviderReplay } from './lib/provider-replay.mjs';
+
+export const SERVER_CALL = {
+  type: 'tool_search_call',
+  id: 'ts_srv',
+  call_id: null,
+  execution: 'server',
+  arguments: { query: 'q' },
+};
+export const SERVER_OUTPUT = { type: 'tool_search_output', id: 'tso_srv', call_id: null, execution: 'server', tools: [] };
+export const REPLY = { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'ok' }] };
+
+export const ROUTES = [
+  ['opencode-go', 'gpt-5.5'],
+  ['muse-code', 'muse-spark'],
+  ['command-code', 'gpt-5.5'],
+  ['custom-cmd', 'openai/gpt-5.6-sol'],
+  ['openrouter', 'openai/gpt-5.5'],
+  ['xai', 'grok-4'],
+  ['opencode-go', 'grok-4'],
+];
+export const FIRST_PARTY = [
+  ['openai', 'gpt-5.5'],
+  ['openai-oauth', 'gpt-5.5'],
+];
+
+export const replayOwner = (name) => `compat-responses:${name}`;
+
+const search = (name) => ({
+  provider: name,
+  openaiTools: [{ type: 'function', name: 'x', description: 'd', parameters: { type: 'object', properties: {} } }],
+});
+
+export function nativeHistory() {
+  return [
+    { role: 'user', content: 'go' },
+    {
+      role: 'assistant',
+      content: '',
+      toolCalls: [
+        { id: 'ts1', name: 'load_tool', arguments: { names: ['x'] }, nativeType: 'tool_search_call' },
+        { id: 'cu1', name: 'apply_patch', arguments: { patch: 'P' }, nativeType: 'custom_tool_call' },
+        { id: 'fn1', name: 'Read', arguments: { path: 'a' } },
+      ],
+    },
+    { role: 'tool', toolCallId: 'ts1', content: 'loaded' },
+    { role: 'tool', toolCallId: 'cu1', content: 'patched' },
+    { role: 'tool', toolCallId: 'fn1', content: 'file' },
+    { role: 'user', content: 'next' },
+  ];
+}
+
+// Left by a previous openai-oauth route: native search/custom calls, native
+// search results carrying loaded tools, phase-tagged assistant turns, a Skill
+// result with loadable tools, and a foreign openai-responses replay.
+export function oauthHistory() {
+  return [
+    { role: 'system', content: 'sys' },
+    { role: 'user', content: 'go' },
+    { role: 'assistant', content: 'working', phase: 'commentary', toolCalls: [] },
+    {
+      role: 'assistant',
+      content: 'looking',
+      phase: 'commentary',
+      reasoningItems: [{ id: 'rs', encrypted_content: 'ENC', summary: [] }],
+      toolCalls: [
+        { id: 'ts1', name: 'load_tool', arguments: { names: ['x'] }, nativeType: 'tool_search_call' },
+        { id: 'cu1', name: 'apply_patch', arguments: { patch: 'P' }, nativeType: 'custom_tool_call' },
+        { id: 'sk1', name: 'Skill', arguments: { name: 's' } },
+      ],
+    },
+    { role: 'tool', toolCallId: 'ts1', content: 'loaded', nativeToolSearch: search('openai-oauth') },
+    { role: 'tool', toolCallId: 'cu1', content: 'patched' },
+    { role: 'tool', toolCallId: 'sk1', content: 'skill', nativeToolSearch: search('openai-oauth') },
+    {
+      role: 'assistant',
+      content: '',
+      toolCalls: [{ id: 'f2', name: 'Read', arguments: { path: 'a' } }],
+      providerReplay: createProviderReplay('openai-responses', [
+        { type: 'tool_search_call', call_id: 'ts9', execution: 'client', arguments: {} },
+      ]),
+    },
+    { role: 'tool', toolCallId: 'f2', content: 'file' },
+    { role: 'user', content: 'next' },
+  ];
+}
+
+// Same-owner replay envelope holding a server-executed search pair.
+export function serverSearchReplayHistory(owner) {
+  return [
+    { role: 'user', content: 'find tools' },
+    {
+      role: 'assistant',
+      content: 'done',
+      providerReplay: createProviderReplay(owner, [
+        { type: 'reasoning', id: 'rs_1', encrypted_content: 'ENC', summary: [] },
+        SERVER_CALL,
+        SERVER_OUTPUT,
+        { type: 'function_call', call_id: 'c1', name: 'Read', arguments: '{}' },
+      ]),
+      toolCalls: [{ id: 'c1', name: 'Read', arguments: {} }],
+    },
+    { role: 'tool', toolCallId: 'c1', content: 'ok' },
+    { role: 'user', content: 'next' },
+  ];
+}
+
+// Pre-change flag-off cases: [label, history(name), providerState?]
+export const COMPAT_CASES = [
+  ['native', () => nativeHistory()],
+  ['oauth', () => oauthHistory()],
+  ['own-search-output', (name) => {
+    const h = nativeHistory();
+    h[2] = { ...h[2], nativeToolSearch: search(name) };
+    return h;
+  }],
+  ['server-replay', (name, owner = replayOwner(name)) => serverSearchReplayHistory(owner)],
+];
+
+export function compatProvider(name, config = {}) {
+  const requests = [];
+  const provider = Object.assign(Object.create(OpenAICompatProvider.prototype), {
+    name,
+    config: { preconnect: false, ...config },
+    nativePdf: true,
+    client: {
+      responses: {
+        create: async (params) => {
+          requests.push(structuredClone(params));
+          return (async function* () {
+            yield {
+              type: 'response.completed',
+              response: { id: 'resp-1', model: params.model, status: 'completed', output: [REPLY] },
+            };
+          })();
+        },
+      },
+    },
+  });
+  return { provider, requests };
+}
+
+export async function captureCompat(name, model, history, opts = {}, config = {}) {
+  const { provider, requests } = compatProvider(name, config);
+  await sendCompatResponses(provider, history, model, [], { sessionId: 'sess-1', ...opts });
+  return requests[0];
+}
+
+export function captureFirstParty(name, model, history) {
+  return JSON.parse(JSON.stringify(buildRequestBody(history, model, [], { promptCacheProvider: name, sessionId: 'sess-1' })));
+}
+
+export async function captureAll() {
+  const out = {};
+  for (const [name, model] of ROUTES) {
+    for (const [label, build] of COMPAT_CASES) {
+      out[`compat/${name}/${model}/${label}`] = await captureCompat(name, model, build(name));
+    }
+  }
+  for (const [name, model] of FIRST_PARTY) {
+    for (const [label, build] of COMPAT_CASES) {
+      out[`first-party/${name}/${label}`] = captureFirstParty(name, model, build(name, 'openai-responses'));
+    }
+  }
+  return out;
+}

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

@@ -139,11 +139,11 @@ export function createResponsesOutcomeStamper(state, leakedCalls) {
 }
 
 /** A streamed function_call whose id/name never arrived cannot be dispatched. */
-export function unresolvedSalvageError(state) {
+export function unresolvedSalvageError(state, label) {
   const unresolved = state.toolCalls.find((t) => t._pendingItemId);
   if (!unresolved) return null;
   return new Error(
-    `xAI Responses stream function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`
+    `${label || 'compat Responses'} stream function_call salvage failed: missing call_id/name for item_id=${unresolved._pendingItemId || '?'}`
   );
 }
 
@@ -169,5 +169,6 @@ export function finalizeResponsesStream(state, { leakedCalls, parseResponsesTool
     model: state.model || response.model || null,
     responseId: state.responseId || response.id || null,
     stopReason: state.stopReason || null,
+    reasoningEmitted: state.emittedReasoning === true,
   };
 }

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

@@ -7,6 +7,7 @@
 // turn tool loops keep the model's reasoning chain without server storage.
 
 import { markProviderRecoveryExhausted, withRetry } from './retry-classifier.mjs';
+import { compatRetryOptions, withCompatRetryProfile } from './openai-compat-retry-profile.mjs';
 import { consumeCompatResponsesStream } from './openai-compat-stream.mjs';
 import { getModelMetadataSync } from './model-catalog.mjs';
 import { PROVIDER_FIRST_BYTE_TIMEOUT_MS, createPassthroughSignal } from '../stall-policy.mjs';
@@ -21,9 +22,12 @@ import {
   toXaiResponsesInput,
   xaiSystemInstructions,
 } from './openai-compat-wire.mjs';
+import { nativeDeferredFamilyForRoute } from './wire-route.mjs';
 import { preparePdfTextForProvider } from './media-normalization.mjs';
 import { normalizeOpencodeGoReasoningEffort } from './openai-compat-xai.mjs';
 import { isCustomProviderName, resolveCustomReasoning } from './custom-reasoning.mjs';
+import { projectEffortConfiguration, withEffortConfigurationFallback } from './effort-configuration.mjs';
+import { normalizeCacheKey } from '../agent-runtime/cache-strategy.mjs';
 import { createProviderReplay } from './lib/provider-replay.mjs';
 import {
   applyCompatToolChoice,
@@ -53,9 +57,88 @@ function resolveReasoning(provider, useModel, opts) {
   return reasoningEffort ? { effort: reasoningEffort } : null;
 }
 
+/**
+ * A custom route's mid-conversation effort projection (GPT-6+ on this wire)
+ * with every effort in the row's wire value, or null for the per-request
+ * effort. Consecutive efforts sharing one wire value collapse into none; an
+ * effort the row cannot serve falls back to the per-request effort.
+ */
+function customEffortProjection(provider, useModel, messages, opts) {
+  if (!isCustomProviderName(provider.name)) return null;
+  const projection = projectEffortConfiguration(messages, provider.name, useModel, {
+    ...opts,
+    protocol: 'openai-responses',
+  });
+  if (!projection) return null;
+  const model = provider.getCachedModelInfo?.(useModel) || null;
+  const wire = (effort) =>
+    resolveCustomReasoning({ protocol: 'openai-responses', model, effort }).fields.reasoning?.effort || null;
+  const initialEffort = wire(projection.initialEffort);
+  if (!initialEffort) return null;
+  const updates = new Map();
+  let current = initialEffort;
+  for (const [message, effort] of projection.updates) {
+    const value = wire(effort);
+    if (!value) return null;
+    if (value !== current) {
+      current = value;
+      updates.set(message, value);
+    }
+  }
+  return { ...projection, initialEffort, effort: current, updates };
+}
+
+// Whether the endpoint takes `prompt_cache_key`. An explicit
+// `opts.responsesPromptCacheKey` / `config.responsesPromptCacheKey` boolean
+// decides; otherwise only custom routes (which always had it) send it.
+function supportsPromptCacheKey(provider, opts) {
+  const declared = opts.responsesPromptCacheKey ?? provider.config?.responsesPromptCacheKey;
+  return typeof declared === 'boolean' ? declared : isCustomProviderName(provider.name);
+}
+
+// Native Responses items (tool_search_call/output, custom_tool_call/output) in
+// replayed history are strictly opt-in: only a route that declares
+// `responsesNativeItems: true` (opts or config) gets the first-party lowering.
+// Every other route keeps the function-only lowering byte for byte.
+function supportsNativeResponsesItems(provider, opts) {
+  return (opts.responsesNativeItems ?? provider.config?.responsesNativeItems) === true || hasNativeDeferredTools(provider, opts);
+}
+
+// A session whose pinned route verified native deferred tools on the Responses
+// wire (flag off in every PROFILES entry today): tool_search is declared
+// natively and loaded tools replay as tool_search_output.
+function hasNativeDeferredTools(provider, opts) {
+  return nativeDeferredFamilyForRoute(provider.name, opts.wireRoute ?? opts.session?.wireRoute) === 'openai';
+}
+
+/**
+ * A route's session identity: its prompt_cache_key and (custom routes) session
+ * headers, '' without a session. The session wins over the provider-scoped
+ * cache key, so parallel sessions never evict each other; a one-shot role
+ * ('shared' scope, a fresh session per call) keys on the provider key instead.
+ * Never the effort, so an effort change keeps the cache routing.
+ */
+function customSessionCacheKey(provider, opts) {
+  if (!supportsPromptCacheKey(provider, opts)) return '';
+  const explicit = opts.promptCacheKey || opts.providerCacheKey || opts.session?.promptCacheKey;
+  return normalizeCacheKey(
+    opts.promptCacheScope === 'shared' ? explicit || opts.sessionId : opts.sessionId || explicit
+  );
+}
+
 /** The request body: lowered transcript plus the per-turn knobs (output cap,
- *  tools and tool choice, reasoning effort). */
-function buildCompatResponsesParams({ provider, useModel, input, previousResponseId, tools, opts, instructions }) {
+ *  tools and tool choice, reasoning effort, session cache key). */
+function buildCompatResponsesParams({
+  provider,
+  useModel,
+  input,
+  previousResponseId,
+  tools,
+  opts,
+  instructions,
+  effortProjection,
+  sessionCacheKey,
+}) {
   const params = {
     model: useModel,
     input,
@@ -67,18 +150,27 @@ function buildCompatResponsesParams({ provider, useModel, input, previousRespons
   const maxOutputTokens = resolveCompatMaxOutputTokens(opts);
   if (maxOutputTokens) params.max_output_tokens = maxOutputTokens;
   if (tools?.length) {
-    params.tools = toResponsesTools(tools, { provider: provider.name });
+    params.tools = toResponsesTools(tools, {
+      provider: provider.name,
+      onToolExcluded: opts.onToolExcluded,
+      ...(hasNativeDeferredTools(provider, opts) ? { nativeDeferredTools: true } : {}),
+    });
     params.parallel_tool_calls = true;
   }
   applyCompatToolChoice(params, opts);
-  const reasoning = resolveReasoning(provider, useModel, opts);
+  // A projected conversation keeps its initial effort on top; changes ride as input items.
+  const reasoning = effortProjection
+    ? { effort: effortProjection.initialEffort }
+    : resolveReasoning(provider, useModel, opts);
   if (reasoning) params.reasoning = reasoning;
   // Opt-in system-as-instructions: set before the hook so the hook can override it.
   if (instructions) params.instructions = instructions;
+  if (sessionCacheKey) params.prompt_cache_key = sessionCacheKey;
   // Opt-in per-provider final shaping (a provider passes the hook in its config).
   const hook = provider.config?.responsesParamsHook;
   if (typeof hook === 'function') {
-    const modelInfo = (typeof provider.getCachedModelInfo === 'function' && provider.getCachedModelInfo(useModel)) || null;
+    const modelInfo =
+      (typeof provider.getCachedModelInfo === 'function' && provider.getCachedModelInfo(useModel)) || null;
     hook(params, { useModel, opts, modelInfo });
   }
   return params;
@@ -90,16 +182,16 @@ function buildCompatResponsesParams({ provider, useModel, input, previousRespons
  * that re-opens the request. A content-idle stall is terminal for this
  * transport, so it is marked recovery-exhausted rather than retried.
  */
-async function streamCompatResponses({ provider, params, label, signal, opts }) {
+async function streamCompatResponses({ provider, params, label, signal, opts, headers }) {
   const totalSignal = createPassthroughSignal(signal);
   try {
     return await withRetry(
-      async ({ signal: attemptSignal }) => {
+      withCompatRetryProfile(provider.name, async ({ signal: attemptSignal }) => {
         const stream = await withRetry(
           ({ signal: openSignal }) =>
             provider.client.responses.create(params, {
               signal: openSignal,
-              ...(opts.requestHeaders ? { headers: opts.requestHeaders } : {}),
+              ...(headers ? { headers } : {}),
             }),
           {
             signal: attemptSignal,
@@ -130,11 +222,12 @@ async function streamCompatResponses({ provider, params, label, signal, opts })
           }
           throw error;
         }
-      },
+      }),
       {
         signal: totalSignal.signal,
         onRetry: compatStreamRetryReporter(label, opts),
         retry529: opts.retry529,
+        ...compatRetryOptions(provider.name),
       }
     );
   } finally {
@@ -142,12 +235,36 @@ async function streamCompatResponses({ provider, params, label, signal, opts })
   }
 }
 
+// OpenRouter's Responses endpoint is stateless: it does not store responses or
+// resolve `previous_response_id`. Imported server-side continuation state (a
+// previous id, or a stored response) is rejected up front rather than sent.
+function assertOpenRouterStateless(provider, opts) {
+  if (provider.name !== 'openrouter') return;
+  const imported = opts.providerState?.[COMPAT_RESPONSES_STATE_KEY];
+  const previous = typeof imported?.previousResponseId === 'string' && imported.previousResponseId !== '';
+  if (!previous && imported?.store !== true) return;
+  throw Object.assign(
+    new Error(
+      'openrouter Responses is stateless: imported previous_response_id / store:true continuation state is not supported'
+    ),
+    { code: 'OPENROUTER_RESPONSES_STATELESS_ONLY', provider: provider.name }
+  );
+}
+
 /**
  * Send one turn over `POST {baseURL}/responses` (streaming) using the
  * provider's existing OpenAI SDK client. Returns the same result shape as
- * the chat/completions path so the agent loop stays wire-agnostic.
+ * the chat/completions path so the agent loop stays wire-agnostic. A custom
+ * route whose model rejects the mid-conversation effort update is replayed
+ * once with the per-request effort.
  */
-export async function sendCompatResponses(provider, messages, useModel, tools, opts = {}) {
+export function sendCompatResponses(provider, messages, useModel, tools, opts = {}) {
+  const send = (sendOpts) => sendCompatResponsesOnce(provider, messages, useModel, tools, sendOpts);
+  if (!isCustomProviderName(provider.name)) return send(opts);
+  return withEffortConfigurationFallback(provider.name, useModel, opts, send);
+}
+
+async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts) {
   const replayProvider = compatResponsesReplayProvider(provider.name);
   const signal = opts.signal || null;
   if (signal?.aborted) {
@@ -156,17 +273,21 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
   }
   const label = `${provider.name}:responses`;
   messages = await preparePdfTextForProvider(messages, provider);
+  assertOpenRouterStateless(provider, opts);
+  const effortProjection = customEffortProjection(provider, useModel, messages, opts);
+  const sessionCacheKey = customSessionCacheKey(provider, opts);
   const { input, previousResponseId, continuationResetReason } = toXaiResponsesInput(messages, opts.providerState, {
+    effortProjection,
     model: useModel,
     stateKey: COMPAT_RESPONSES_STATE_KEY,
     replayProvider,
     providerName: provider.name,
+    nativeLowering: supportsNativeResponsesItems(provider, opts),
     nativePdf: provider.nativePdf,
     // Opt-in: system prompts travel as top-level `instructions`, not input items.
     includeSystem: provider.config?.responsesSystemAsInstructions !== true,
   });
-  const instructions =
-    provider.config?.responsesSystemAsInstructions === true ? xaiSystemInstructions(messages) : '';
+  const instructions = provider.config?.responsesSystemAsInstructions === true ? xaiSystemInstructions(messages) : '';
   const params = buildCompatResponsesParams({
     provider,
     useModel,
@@ -175,14 +296,20 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
     tools,
     opts,
     instructions,
+    effortProjection,
+    sessionCacheKey,
   });
+  // The session identity also travels as headers; caller headers win.
+  const headers = sessionCacheKey && isCustomProviderName(provider.name)
+    ? { 'session-id': sessionCacheKey, 'x-client-request-id': sessionCacheKey, ...opts.requestHeaders }
+    : opts.requestHeaders;
 
   try {
     opts.onStageChange?.('requesting');
   } catch {
     /* heartbeat best-effort */
   }
-  const streamed = await streamCompatResponses({ provider, params, label, signal, opts });
+  const streamed = await streamCompatResponses({ provider, params, label, signal, opts, headers });
   const response = streamed.response;
   const usage = response?.usage || null;
   const inputTokens = Number(usage?.input_tokens ?? usage?.prompt_tokens ?? 0);
@@ -206,7 +333,7 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
   const messageIndex = Array.isArray(messages) ? messages.length : 0;
   const encryptedReasoningHistory = [
     ...(Array.isArray(priorState?.encryptedReasoningHistory) ? priorState.encryptedReasoningHistory : []),
-    ...(reasoningItems.length ? [{ messageIndex, items: reasoningItems }] : []),
+    ...(reasoningItems.length ? [{ messageIndex, items: reasoningItems, owner: replayProvider }] : []),
   ];
   const searchSources = collectCompatResponseSearchSources(response);
   const usageSummary = usage ? responsesUsage(usage) : undefined;
@@ -215,6 +342,7 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
     model: response?.model || useModel,
     toolCalls: streamed.toolCalls,
     stopReason: streamed.stopReason || null,
+    ...(streamed.refusal ? { refusal: streamed.refusal } : {}),
     ...(streamed.stopReason === 'length' && (streamed.content || '').length > 0 ? { truncated: true } : {}),
     citations: searchSources.citations.length ? searchSources.citations : undefined,
     webSearchCalls: searchSources.webSearchCalls.length ? searchSources.webSearchCalls : undefined,
@@ -225,6 +353,7 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
         previousResponseId: null,
         responseId: response?.id || null,
         store: false,
+        owner: replayProvider,
         encryptedReasoningItems: reasoningItems,
         encryptedReasoningHistory,
         seenMessageCount: messageIndex,

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

@@ -0,0 +1,193 @@
+// Per-provider request retry profile for the OpenAI-compatible family. Each
+// provider carries its own retry constants; the
+// shared withRetry still owns classification, the exposure/replay veto,
+// quota refusals, x-should-retry and Retry-After. Providers with no profile
+// keep the shared defaults.
+//
+// `backoffMs[n]` is the base wait before retry n (index 0 is never read, so
+// the first value is the duplicate the withRetry schedule expects).
+//   statusRetryCaps — retries allowed for one status (for example a
+//     429 stops after a single retry, whatever the overall budget).
+//   terminalStatuses — statuses that are terminal although the
+//     shared classifier would retry them.
+//   retryOnlyStatuses — the complete retryable error set: any other 4xx/5xx
+//     status surfaces.
+//   maxRetryAfterMs — give up instead of waiting longer than this.
+//   maxFailedAttemptMs — a 5xx that took longer than this is not replayed.
+//   retryEmptyResponse — a completed turn with no text, tool call or
+//     reasoning is re-asked inside the ladder (nothing was exposed); a number
+//     bounds how many times per send, true leaves it to the ladder.
+//   adviceWindow - outside exceptStatuses, Retry-After is clamped to maxMs
+//     and jittered by jitterRatio (the advice of the excepted statuses stays raw).
+//   recycleDispatcherOn5xx — a retried 5xx rebuilds the shared HTTP pool.
+//   adviceAtLeastBackoff — the advice is a floor under the jittered backoff step.
+// Every stop is provider-terminal: the profile's limits are final, so the
+// agent loop never re-runs a stopped or exhausted request (see
+// COMPAT_RETRY_POLICY).
+import { markProviderRecoveryExhausted } from './retry-classifier.mjs';
+import { retryAfterMsFromError } from './provider-error-kind.mjs';
+import { STREAM_TRANSPORTS, stampStreamOutcome } from './lib/stream-outcome.mjs';
+import { jitterDelayMs } from './retry-backoff.mjs';
+
+const statusOf = (err) => Number(err?.httpStatus || err?.status || err?.response?.status || 0);
+
+/** Loop retry policy of every profiled provider: no recovery cycles on top of the profile. */
+export const COMPAT_RETRY_POLICY = Object.freeze({ recoveryCycles: false });
+
+/** xAI additionally treats an in-band invalid-request error as retryable. */
+export const XAI_COMPAT_RETRY_POLICY = Object.freeze({ ...COMPAT_RETRY_POLICY, inBandInvalidRequestRetryable: true });
+
+export const COMPAT_RETRY_PROFILES = Object.freeze({
+  // A budget of 15 sends (the retry limit is reached when the next retry number
+  // equals it, so 14 waits), 2s doubling to 30s, ±20% jitter, one retry for a
+  // 429. Outside a 429, Retry-After is capped at 30s and jittered.
+  xai: Object.freeze({
+    maxAttempts: 15,
+    backoffMs: [2000, 2000, 4000, 8000, 16000, 30000],
+    retryJitterRatio: 0.2,
+    statusRetryCaps: { 429: 1 },
+    terminalStatuses: [408, 409, 425],
+    retryEmptyResponse: true,
+    adviceWindow: Object.freeze({ maxMs: 30_000, jitterRatio: 0.2, exceptStatuses: [429] }),
+    recycleDispatcherOn5xx: true,
+  }),
+  // 5 retries, 500ms doubling to 10s, ±10% jitter;
+  // a Retry-After beyond the 10s ceiling is not waited out.
+  deepseek: Object.freeze({
+    maxAttempts: 6,
+    backoffMs: [500, 500, 1000, 2000, 4000, 8000],
+    retryJitterRatio: 0.1,
+    maxRetryAfterMs: 10_000,
+    terminalStatuses: [408, 409, 425],
+    retryEmptyResponse: true,
+  }),
+  // The HTTP transport layer governs one request: 6 sends, 500ms doubling, no
+  // jitter, a Retry-After beyond 60s is not waited out; only 408, 429 and 5xx
+  // are transient, every other 4xx is terminal. A benign empty completion is
+  // re-asked at most twice.
+  'muse-code-oauth': Object.freeze({
+    maxAttempts: 6,
+    backoffMs: [500, 500, 1000, 2000, 4000, 8000],
+    retryJitterRatio: 0,
+    terminalStatuses: [409, 425],
+    maxRetryAfterMs: 60_000,
+    retryEmptyResponse: 2,
+  }),
+  // server budget 8 retries (2s doubling to 30s,
+  // ±10%), rate-limit budget 5 retries; 408, 409, 501 and 505 are terminal
+  // (425 stays retryable); a Retry-After beyond 300s is not waited out.
+  'mimo-oauth': Object.freeze({
+    maxAttempts: 9,
+    backoffMs: [2000, 2000, 4000, 8000, 16000, 30000],
+    retryJitterRatio: 0.1,
+    statusRetryCaps: { 429: 5 },
+    terminalStatuses: [408, 409, 501, 505],
+    maxRetryAfterMs: 300_000,
+  }),
+  // 3 sends (400ms doubling to 5s) for exactly
+  // 500/502/503/504/520/521/522 — every 4xx (429 included) and every other
+  // 5xx is terminal; a failed attempt slower than 15s is returned.
+  'command-code-oauth': Object.freeze({
+    maxAttempts: 3,
+    backoffMs: [400, 400, 800],
+    retryOnlyStatuses: [500, 502, 503, 504, 520, 521, 522],
+    maxFailedAttemptMs: 15_000,
+    maxRetryAfterMs: 60_000,
+    adviceAtLeastBackoff: true,
+  }),
+});
+
+/** withRetry options (attempt budget, schedule, jitter) for a provider; {} for the shared defaults. */
+export function compatRetryOptions(providerName) {
+  const profile = COMPAT_RETRY_PROFILES[providerName];
+  if (!profile) return {};
+  return {
+    maxAttempts: profile.maxAttempts,
+    backoffMs: profile.backoffMs,
+    retryJitterRatio: profile.retryJitterRatio,
+    finalOnExhaust: true,
+    ...(profile.adviceAtLeastBackoff ? { adviceAtLeastBackoff: true } : {}),
+    ...(profile.recycleDispatcherOn5xx ? { recycleDispatcherOn5xx: true } : {}),
+    ...(profile.retryJitterMode ? { retryJitterMode: profile.retryJitterMode } : {}),
+  };
+}
+
+function profileStops(profile, err, { attempt, elapsedMs }) {
+  const status = statusOf(err);
+  if (profile.terminalStatuses?.includes(status)) return true;
+  const cap = profile.statusRetryCaps?.[status];
+  if (cap !== undefined && attempt >= cap) return true;
+  if (profile.retryOnlyStatuses && status >= 400 && status < 600 && !profile.retryOnlyStatuses.includes(status)) {
+    return true;
+  }
+  if (profile.maxFailedAttemptMs && status >= 500 && status < 600 && elapsedMs > profile.maxFailedAttemptMs) {
+    return true;
+  }
+  const advice = retryAfterMsFromError(err);
+  return profile.maxRetryAfterMs !== undefined && advice != null && advice > profile.maxRetryAfterMs;
+}
+
+// Restamps the advice as a deadline (the highest-precedence source) so the
+// shared loop waits the clamped, jittered value instead of the raw one.
+function shapeAdvice(window, err) {
+  if (!window || !err || typeof err !== 'object' || window.exceptStatuses?.includes(statusOf(err))) return;
+  const advice = retryAfterMsFromError(err);
+  if (advice == null) return;
+  err.retryAfterAt = Date.now() + jitterDelayMs(Math.min(advice, window.maxMs), window.jitterRatio);
+}
+
+// A completed turn that produced nothing: no text, tool call or reasoning, and
+// a normal finish (a Responses turn carries no stop reason when it completes).
+function isEmptyNormalFinish(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (result.stopReason != null && result.stopReason !== 'stop') return false;
+  return (
+    !String(result.content ?? '').trim() &&
+    !result.toolCalls?.length &&
+    !result.reasoningContent &&
+    !result.reasoningDetails?.length &&
+    result.reasoningEmitted !== true
+  );
+}
+
+function emptyResponseError(providerName) {
+  const err = Object.assign(new Error(`${providerName} returned an empty response`), {
+    code: 'server_error',
+    emptyResponse: true,
+  });
+  // The turn finished: a failed ladder must not reopen it as a non-streaming request.
+  stampStreamOutcome(err, { transport: STREAM_TRANSPORTS.SSE, terminalObserved: true });
+  return err;
+}
+
+/**
+ * Wrap one withRetry attempt with the provider's profile: a failure the
+ * profile treats as final is marked recovery-exhausted and provider-terminal
+ * (withRetry then surfaces it unchanged and no outer layer replays it), and a
+ * profiled empty response is raised as a retryable failure.
+ */
+export function withCompatRetryProfile(providerName, attemptFn) {
+  const profile = COMPAT_RETRY_PROFILES[providerName];
+  if (!profile) return attemptFn;
+  let emptyRetries = 0;
+  return async (ctx) => {
+    const startedAt = Date.now();
+    try {
+      const result = await attemptFn(ctx);
+      if (profile.retryEmptyResponse && isEmptyNormalFinish(result)) {
+        const bound = profile.retryEmptyResponse === true ? Infinity : profile.retryEmptyResponse;
+        if (emptyRetries < bound) {
+          emptyRetries += 1;
+          throw emptyResponseError(providerName);
+        }
+      }
+      return result;
+    } catch (err) {
+      if (profileStops(profile, err, { attempt: ctx?.attempt | 0, elapsedMs: Date.now() - startedAt })) {
+        throw markProviderRecoveryExhausted(err, { owner: `${providerName}-retry-profile`, terminal: true });
+      }
+      shapeAdvice(profile.adviceWindow, err);
+      throw err;
+    }
+  };
+}