mixdog 1.2.0 → 1.2.2

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';
@@ -24,6 +25,8 @@ import {
 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 +56,65 @@ 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 };
+}
+
+/**
+ * A custom route's session identity: its prompt_cache_key and 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 (!isCustomProviderName(provider.name)) 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,
@@ -71,14 +130,19 @@ function buildCompatResponsesParams({ provider, useModel, input, previousRespons
     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 +154,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 +194,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 {
@@ -145,9 +210,17 @@ async function streamCompatResponses({ provider, params, label, signal, opts })
 /**
  * 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,7 +229,10 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
   }
   const label = `${provider.name}:responses`;
   messages = await preparePdfTextForProvider(messages, provider);
+  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,
@@ -165,8 +241,7 @@ export async function sendCompatResponses(provider, messages, useModel, tools, o
     // 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 +250,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
+    ? { '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);

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;
+    }
+  };
+}

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

@@ -1,6 +1,8 @@
 import { randomBytes } from 'node:crypto';
 import { PROVIDER_FIRST_BYTE_TIMEOUT_MS, providerTimeoutError, streamStalledError } from '../stall-policy.mjs';
 import { typedStatusFrom } from './retry-classifier.mjs';
+import { applyCompatErrorContract } from './openai-compat-error-contract.mjs';
+import { truncatedCompatStreamError } from './lib/openai-tool-args.mjs';
 
 // Shared lifecycle and replay boundaries for both OpenAI-compatible protocols.
 
@@ -22,10 +24,68 @@ function markInBandWireError(err) {
     if (typed && !err.httpStatus) err.httpStatus = typed;
     const code = detail.code ?? detail.type ?? null;
     if (code != null && code !== '' && !err.providerErrorCode) err.providerErrorCode = String(code);
+    applyCompatErrorContract(err, detail);
   } catch {}
   return err;
 }
 
+/**
+ * A frame the SDK failed to JSON-decode. Raised only at the wire-decoding
+ * boundary (the iterator's own next()); consumers stamp the exposure evidence
+ * (partial output, replay safety) on it in their failure path.
+ */
+export function malformedCompatStreamError(label, cause) {
+  const err = new Error(`${label || 'compat SSE'} malformed stream frame: ${cause?.message || 'invalid JSON'}`, {
+    cause,
+  });
+  err.name = 'MalformedStreamError';
+  err.code = 'malformed_stream';
+  err.malformedStream = true;
+  return err;
+}
+
+/**
+ * A chat `finish_reason: network_error` is an interruption the gateway reports
+ * in-band, never a completion. Typed as a truncated stream so the shared
+ * classifier treats it as transient; exposure gates decide replay.
+ */
+export function networkInterruptedCompatStreamError(label) {
+  const err = truncatedCompatStreamError(label, 'finish_reason=network_error');
+  err.name = 'StreamInterruptedError';
+  err.streamInterrupted = true;
+  err.finishReason = 'network_error';
+  return err;
+}
+
+export function isNetworkErrorFinishReason(finishReason) {
+  return typeof finishReason === 'string' && finishReason.trim().toLowerCase() === 'network_error';
+}
+
+/**
+ * A chat `finish_reason: error` means the upstream failed the generation
+ * (gateways surface it as a 502 upstream_error). Typed like the network interruption, with the gateway status.
+ */
+export function upstreamErrorCompatStreamError(label) {
+  const err = truncatedCompatStreamError(label, 'finish_reason=error');
+  err.name = 'StreamInterruptedError';
+  err.streamInterrupted = true;
+  err.finishReason = 'error';
+  err.status = 502;
+  err.code = 'upstream_error';
+  return err;
+}
+
+export function isErrorFinishReason(finishReason) {
+  return typeof finishReason === 'string' && finishReason.trim().toLowerCase() === 'error';
+}
+
+/** The typed interruption for a failing chat finish_reason, or null for any other value. */
+export function failingFinishReasonError(finishReason, label) {
+  if (isNetworkErrorFinishReason(finishReason)) return networkInterruptedCompatStreamError(label);
+  if (isErrorFinishReason(finishReason)) return upstreamErrorCompatStreamError(label);
+  return null;
+}
+
 export function synthLeakedOpenAICall(recovered) {
   let args = recovered?.arguments;
   if (args === null || typeof args !== 'object' || Array.isArray(args)) args = {};
@@ -59,7 +119,7 @@ export function closeCompatStream(stream, iterator) {
 
 export async function nextAsyncWithWatchdog(
   iterator,
-  { signal, idleMs, idleDeadlineAt, idleEnabled, idleLabel, emittedToolCall } = {}
+  { signal, idleMs, idleDeadlineAt, idleEnabled, idleLabel, streamLabel, emittedToolCall } = {}
 ) {
   let idleTimer = null;
   let idleReject = null;
@@ -106,7 +166,11 @@ export async function nextAsyncWithWatchdog(
         };
         signal.addEventListener('abort', onAbort, { once: true });
       }
-      iterator.next().then(resolve, reject);
+      // The SDK JSON-decodes each frame inside next(): a SyntaxError here is a
+      // malformed wire frame, typed at this boundary and nowhere else.
+      iterator.next().then(resolve, (error) =>
+        reject(error instanceof SyntaxError ? malformedCompatStreamError(streamLabel || idleLabel, error) : error)
+      );
     });
   } catch (err) {
     if (idleTimedOut)

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

@@ -99,6 +99,7 @@ export async function consumeCompatResponsesStream(
         idleDeadlineAt: state.semanticIdleDeadlineAt,
         idleEnabled: sawFirstEvent && idleEnabled && state.semanticIdleDeadlineAt > 0,
         idleLabel: `${label} SSE idle`,
+        streamLabel: label,
         // Unsafe-to-retry once any tool call (native or recovered-leaked)
         // has been emitted this stream — avoid a double side-effect.
         emittedToolCall: () => state.emittedToolCall || leakedCalls.length > 0,
@@ -144,7 +145,7 @@ export async function consumeCompatResponsesStream(
     }
     throw stampOutcome(err);
   }
-  const unresolved = unresolvedSalvageError(state);
+  const unresolved = unresolvedSalvageError(state, label);
   if (unresolved) {
     attachPartialState(unresolved, state, leakedCalls);
     throw stampOutcome(unresolved);

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

@@ -18,6 +18,7 @@ import {
 import { customToolCallFromResponseItem, nativeToolSearchCallFromArguments } from './custom-tool-wire.mjs';
 import { providerReplayItems } from './lib/provider-replay.mjs';
 import { ensureResponsesCallOutputs } from './lib/wire-pairing.mjs';
+import { responsesEffortUpdates } from './effort-configuration.mjs';
 
 function positiveTokenInt(value) {
   const n = Number(value);
@@ -423,10 +424,14 @@ export function toXaiResponsesInput(messages, providerState, options = {}) {
     if (!pendingToolMedia.length) return;
     input.push({ role: 'user', content: pendingToolMedia.splice(0) });
   };
+  // `options.effortProjection` (custom GPT-6+ routes) carries wire-ready effort updates.
+  const effortUpdates = responsesEffortUpdates(options.effortProjection);
   for (let messageIndex = startIndex; messageIndex < messages.length; messageIndex += 1) {
     const m = messages[messageIndex];
     if (!includeSystem && m.role === 'system') continue;
+    const updates = effortUpdates.before(m);
     if (m.role !== 'tool') flushToolMedia();
+    input.push(...updates);
     const orderedReplay = m.role === 'assistant' ? providerReplayItems(m, replayProvider) : undefined;
     if (orderedReplay?.length) {
       input.push(...orderedReplay);
@@ -444,6 +449,7 @@ export function toXaiResponsesInput(messages, providerState, options = {}) {
   flushToolMedia();
   const trailingReasoning = reasoningByMessageIndex.get(messages.length);
   if (trailingReasoning) input.push(...trailingReasoning);
+  input.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-compat-xai-send.mjs

@@ -1,4 +1,6 @@
+import { resolveProviderApiKey } from '../../../shared/provider-api-key.mjs';
 import { markProviderRecoveryExhausted, withRetry } from './retry-classifier.mjs';
+import { compatRetryOptions, withCompatRetryProfile } from './openai-compat-retry-profile.mjs';
 import { consumeCompatResponsesStream } from './openai-compat-stream.mjs';
 import { PROVIDER_FIRST_BYTE_TIMEOUT_MS, createPassthroughSignal } from '../stall-policy.mjs';
 import {
@@ -90,7 +92,7 @@ export async function sendXaiResponses(provider, messages, useModel, tools, opts
   let streamed;
   try {
     streamed = await withRetry(
-      async ({ signal: attemptSignal }) => {
+      withCompatRetryProfile(provider.name, async ({ signal: attemptSignal }) => {
         const stream = await withRetry(
           ({ signal: openSignal }) => provider.client.responses.create(params, { signal: openSignal }),
           {
@@ -126,11 +128,12 @@ export async function sendXaiResponses(provider, messages, useModel, tools, opts
           }
           throw error;
         }
-      },
+      }),
       {
         signal: totalSignal.signal,
         onRetry: compatStreamRetryReporter('xai:responses', opts),
         retry529: opts.retry529,
+        ...compatRetryOptions(provider.name),
       }
     );
   } finally {
@@ -158,7 +161,7 @@ export async function sendXaiResponsesWebSocket(provider, messages, useModel, to
     const reason = signal.reason;
     throw reason instanceof Error ? reason : new Error('xAI Responses WebSocket request aborted by session close');
   }
-  const apiKey = provider.config?.apiKey || process.env.XAI_API_KEY;
+  const apiKey = resolveProviderApiKey('xai', provider.config);
   if (!apiKey) throw new Error('xAI API key not configured');
   messages = await preparePdfTextForProvider(messages, provider);
   const chatMessagesForTrace = toOpenAIMessages(messages, provider.name, { nativePdf: provider.nativePdf });

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

@@ -14,7 +14,7 @@ import { appendAgentTrace } from '../agent-trace.mjs';
 import { resolveProviderCacheKey, resolveProviderPromptCacheLane } from '../agent-runtime/cache-strategy.mjs';
 import { shouldFallbackTransport } from './retry-classifier.mjs';
 import { envFlag as _envFlag } from '../../../shared/env.mjs';
-import { getModelsDevRowSync } from '../../../shared/llm/model-catalog.mjs';
+import { getModelMetadataSync, getModelsDevRowSync } from '../../../shared/llm/model-catalog.mjs';
 import {
   traceHash,
   stableTraceStringify,
@@ -166,26 +166,35 @@ export function normalizeXaiReasoningEffort(value) {
   return ['low', 'medium', 'high', 'xhigh'].includes(effort) ? effort : null;
 }
 
-// grok-3, grok-4 and grok-4-fast REJECT reasoning_effort outright (HTTP 400
-// "does not support parameter reasoningEffort"), so the parameter ships only
-// for the families that document it. An unknown/absent model id keeps the
-// parameter — a custom xAI-compatible deployment that never saw the 400 must
-// not silently lose the caller's effort choice.
+const hasEffortValues = (modelOptions) =>
+  (modelOptions || []).some((option) => option?.type === 'effort' && option.values?.length > 0);
+
+// The first Grok generations (grok-3, grok-4, grok-4-fast, grok-code-fast)
+// REJECT reasoning_effort outright (HTTP 400 "does not support parameter
+// reasoningEffort"). That generation is closed: it is told apart by a bare
+// major with no minor version, so a later release never matches.
+const LEGACY_NO_EFFORT_GROK = /^grok[-_]?(?:[123]|4|code)(?![.\d])/;
+
+// The parameter ships when the catalog says the model takes it. A model the
+// catalog does not list yet is sent the caller's effort (the server decides),
+// as is an unknown/absent model id — a custom xAI-compatible deployment that
+// never saw the 400 must not silently lose the caller's effort choice. Only
+// the closed legacy generation above is held back offline, because sending to
+// it hard-fails.
 export function xaiModelSupportsReasoningEffort(model) {
   const id = String(model || '')
     .trim()
     .toLowerCase();
   if (!id) return true;
   if (!id.startsWith('grok')) return true;
-  // The catalog answers first: a listed model takes the parameter exactly
-  // when it publishes effort values (grok-4.3 does, grok-4.20-*-reasoning
-  // does not), so a new release needs no edit here.
+  // The catalog answers first, from the live roster and the pricing catalogs:
+  // a model that publishes effort values takes the parameter.
+  if (hasEffortValues(getModelMetadataSync(id, 'xai')?.reasoningOptions)) return true;
+  // A listed model takes the parameter exactly when it publishes effort
+  // values (grok-4.3 does, grok-4.20-*-reasoning does not).
   const listed = getModelsDevRowSync(id, 'xai');
-  if (listed) {
-    return (listed.reasoning_options || []).some((option) => option?.type === 'effort' && option.values?.length > 0);
-  }
-  // grok-4.5 / grok-4.6 and anything newer in that line.
-  return /grok[-_]?4\.(?:[5-9]|\d{2,})/.test(id);
+  if (listed) return hasEffortValues(listed.reasoning_options);
+  return !LEGACY_NO_EFFORT_GROK.test(id);
 }
 
 function opencodeGoReasoningEffortValues(modelInfo) {