mixdog 1.2.1 → 1.2.3

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

@@ -31,6 +31,7 @@ import {
   finalizeResponsesStream,
   unresolvedSalvageError,
 } from './openai-compat-responses-state.mjs';
+import { createRefusals, refusalResultFields } from './openai-ws-response-state/refusals.mjs';
 import { responsesUsage } from './openai-compat-response-normalization.mjs';
 import { noteAbandonedUsage } from '../../../shared/llm/usage-context.mjs';
 
@@ -99,6 +100,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,13 +146,18 @@ 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);
   }
   try {
-    return finalizeResponsesStream(state, { leakedCalls, parseResponsesToolCalls, responseOutputText, label });
+    const result = finalizeResponsesStream(state, { leakedCalls, parseResponsesToolCalls, responseOutputText, label });
+    // The terminal output bundle's refusal parts join the streamed ones (keyed
+    // by item id + content index, so copies of one part fold into one text).
+    state.refusals ||= createRefusals();
+    for (const item of result.response?.output || []) state.refusals.absorbMessage(item);
+    return { ...result, ...refusalResultFields(state.refusals, result.content) };
   } catch (err) {
     attachPartialState(err, state, leakedCalls);
     throw stampOutcome(err);

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

@@ -37,6 +37,8 @@ export function extractCompatCachedTokens(usage) {
     usage?.input_tokens_details?.cached_tokens,
     usage?.prompt_cache_hit_tokens,
     usage?.cached_prompt_text_tokens,
+    // Together reports it top-level; first-positive wins, so it never stacks on a nested count.
+    usage?.cached_tokens,
   ];
   for (const v of candidates) {
     const n = Number(v);

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

@@ -17,7 +17,11 @@ import {
 } from './media-normalization.mjs';
 import { customToolCallFromResponseItem, nativeToolSearchCallFromArguments } from './custom-tool-wire.mjs';
 import { providerReplayItems } from './lib/provider-replay.mjs';
+import { acceptedWireTools } from './lib/claude-bridge-schema.mjs';
 import { ensureResponsesCallOutputs } from './lib/wire-pairing.mjs';
+import { responsesEffortUpdates } from './effort-configuration.mjs';
+import { convertMessagesToResponsesInput } from './openai-responses-input.mjs';
+import { COMPAT_REASONING_METADATA_KEY, contentWithThinkingChunk } from './openai-compat-reasoning-field.mjs';
 
 function positiveTokenInt(value) {
   const n = Number(value);
@@ -38,19 +42,23 @@ export function toOpenAIMessages(messages, providerName, options = {}) {
   // strict providers (xai) reject unknown roles/types and would 400 the
   // request. Documented in v0.1.160 (GPT reasoning replay).
   //
-  // DeepSeek splits by model: thinking-mode models with tools REQUIRE the
-  // prior turn's `reasoning_content` echoed back (400 without it), while
-  // `deepseek-reasoner` REJECTS it with a 400. The caller decides per model
-  // through options.replaysReasoningContent — see
-  // deepseekReplaysReasoningContent below. xAI reasoning models preserve
-  // their official multi-turn shape and cache prefix stability when prior
-  // assistant reasoning_content is replayed; reasoning_effort itself remains
-  // caller/user-selected.
+  // DeepSeek thinking-mode models with tools REQUIRE the prior turn's
+  // `reasoning_content` echoed back (400 without it); without tools it is
+  // ignored, so the caller (options.replaysReasoningContent) always replays it.
+  // xAI reasoning models preserve their official multi-turn shape and cache
+  // prefix stability when prior assistant reasoning_content is replayed;
+  // reasoning_effort itself remains caller/user-selected.
   //
   // Custom providers pass options.customReplay (custom-reasoning.mjs replay
   // eligibility). When it is a boolean it alone decides; a replaying custom
   // endpoint also needs a non-empty reasoning_content on every assistant
   // tool-call turn, so missing/empty reasoning there is padded with " ".
+  //
+  // options.reasoningShape (openai-compat-reasoning-field.mjs) names the
+  // endpoint families with their own reasoning fields; they decide the resend
+  // key and win over the flags above. options.developerRole keeps the
+  // `developer` role for endpoints that document it; every other chat endpoint
+  // only knows `system`, so developer instructions go out as system messages.
   const customReplay = typeof options.customReplay === 'boolean' ? options.customReplay : null;
   const replaysReasoningContent = customReplay ?? (options.replaysReasoningContent === true || providerName === 'xai');
   const out = [];
@@ -61,8 +69,25 @@ export function toOpenAIMessages(messages, providerName, options = {}) {
     const details = metadata?.reasoning_details ?? metadata?.reasoningDetails;
     return Array.isArray(details) && details.length ? details : null;
   };
+  const shape = options.reasoningShape || null;
+  // Receive and resend fields differ per endpoint family: the key a reply's
+  // reasoning arrived on is recorded in providerMetadata at receive time.
+  const receivedField = (message) => message?.providerMetadata?.[COMPAT_REASONING_METADATA_KEY]?.reasoningField;
+  const attachShapeReasoning = (msg, message, stored) => {
+    if (!stored) return;
+    if (shape.resend === 'same_key') {
+      msg[receivedField(message) === 'reasoning' ? 'reasoning' : 'reasoning_content'] = stored;
+    } else if (shape.resend === 'reasoning') {
+      // OpenRouter: reasoning_details replace the text when present.
+      if (!openRouterReasoningDetails(message)) msg.reasoning = stored;
+    } else if (shape.resend === 'content_chunks' && receivedField(message) === 'content_chunks') {
+      msg.content = contentWithThinkingChunk(msg.content, stored);
+    }
+  };
   const attachAssistantReasoning = (msg, message) => {
-    if (customReplay) {
+    if (shape) {
+      attachShapeReasoning(msg, message, typeof message.reasoningContent === 'string' ? message.reasoningContent : '');
+    } else if (customReplay) {
       const stored = typeof message.reasoningContent === 'string' ? message.reasoningContent : '';
       if (stored) msg.reasoning_content = stored;
       else if (Array.isArray(msg.tool_calls) && msg.tool_calls.length) msg.reasoning_content = ' ';
@@ -103,8 +128,12 @@ export function toOpenAIMessages(messages, providerName, options = {}) {
       continue;
     }
     const msg = {
-      role: m.role,
-      content: normalizeContentForOpenAIChat(m.content, { role: m.role, nativePdf: options.nativePdf }),
+      role: m.role === 'developer' && options.developerRole !== true ? 'system' : m.role,
+      content: normalizeContentForOpenAIChat(m.content, {
+        role: m.role,
+        nativePdf: options.nativePdf,
+        cacheControl: options.cacheControl === true,
+      }),
     };
     out.push(m.role === 'assistant' ? attachAssistantReasoning(msg, m) : msg);
   }
@@ -112,18 +141,6 @@ export function toOpenAIMessages(messages, providerName, options = {}) {
   return out;
 }
 
-// deepseek-reasoner returns 400 when `reasoning_content` appears in the input
-// messages; every other DeepSeek thinking model needs it back once tools are in
-// play. Unknown DeepSeek ids default to replaying: a missing echo breaks the
-// tool loop, while a stray field on a non-thinking model is ignored.
-export function deepseekReplaysReasoningContent(model) {
-  return !/reasoner/.test(
-    String(model || '')
-      .trim()
-      .toLowerCase()
-  );
-}
-
 export function toOpenAITools(tools) {
   return tools.map((t) => ({
     type: 'function',
@@ -145,9 +162,42 @@ function functionToolFromSessionTool(t, name = t?.name) {
   };
 }
 
-export function toResponsesTools(tools, options = {}) {
+// xAI hosts tool search itself (docs.x.ai progressive tool disclosure): a
+// `{type:'tool_search'}` server tool loads the definitions of function tools
+// marked `defer_loading: true`, and the server returns the search as
+// tool_search_call / tool_search_output items. The client loader (`load_tool`)
+// is therefore replaced by that one server tool; with deferred tools but no
+// loader the server tool is still added, or the deferred tools could never load.
+function toServerToolSearchTools(tools) {
+  let hasSearch = false;
+  let hasDeferred = false;
+  const out = tools.map((t) => {
+    if (t?.name === 'load_tool' || t?.name === 'tool_search') {
+      if (hasSearch) return null;
+      hasSearch = true;
+      return { type: 'tool_search' };
+    }
+    if (t?.deferLoading === true || t?.defer_loading === true) {
+      hasDeferred = true;
+      return { ...functionToolFromSessionTool(t), defer_loading: true };
+    }
+    return functionToolFromSessionTool(t);
+  });
+  if (hasDeferred && !hasSearch) out.push({ type: 'tool_search' });
+  return out.filter(Boolean);
+}
+
+export function toResponsesTools(allTools, options = {}) {
   const provider = String(options?.provider || '').toLowerCase();
+  // A Responses endpoint rejects the whole request for one invalid
+  // `parameters`; a tool broken even after lowering is left out and reported.
+  const tools = acceptedWireTools(allTools, 'openai', options?.onToolExcluded, `[${provider || 'responses'}] tool`);
+  if (options?.serverToolSearch === true) return toServerToolSearchTools(tools);
+  // A route pinned with verified native deferred tools declares the native
+  // client tool_search tool and marks deferred definitions `defer_loading`.
+  const nativeDeferred = options?.nativeDeferredTools === true;
   const allowNativeToolSearch =
+    nativeDeferred ||
     options?.nativeToolSearch === true ||
     (options?.nativeToolSearch !== false && (provider === 'openai' || provider === 'openai-oauth'));
   return tools.map((t) => {
@@ -169,6 +219,9 @@ export function toResponsesTools(tools, options = {}) {
     // tools (e.g. apply_patch) as ordinary function tools instead. Grammar
     // tools may carry no usable inputSchema, so fall back to a permissive
     // object schema so grok still registers a valid function tool.
+    if (nativeDeferred && (t?.deferLoading === true || t?.defer_loading === true)) {
+      return { ...functionToolFromSessionTool(t), defer_loading: true };
+    }
     return functionToolFromSessionTool(t);
   });
 }
@@ -236,7 +289,7 @@ export function parseResponsesToolCalls(response, label) {
     } else if (item?.type === 'custom_tool_call') {
       const call = customToolCallFromResponseItem(item);
       if (call) out.push(call);
-    } else if (item?.type === 'tool_search_call') {
+    } else if (item?.type === 'tool_search_call' && item.execution !== 'server') {
       const searchArgs =
         item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
           ? item.arguments
@@ -408,25 +461,54 @@ export function toXaiResponsesInput(messages, providerState, options = {}) {
     let history = [];
     if (Array.isArray(state?.encryptedReasoningHistory)) history = state.encryptedReasoningHistory;
     else if (Array.isArray(state?.encryptedReasoningItems)) {
-      history = [{ messageIndex: seen, items: state.encryptedReasoningItems }];
+      history = [{ messageIndex: seen, items: state.encryptedReasoningItems, owner: state.owner }];
     }
     for (const entry of history) {
       const index = Number(entry?.messageIndex);
       if (!Number.isInteger(index) || index < 0 || !Array.isArray(entry?.items)) continue;
+      // Owner-tagged reasoning (compat routes) never replays under another
+      // owner, even when a caller passes provider state across providers.
+      if (entry.owner !== undefined && entry.owner !== replayProvider) continue;
       const bucket = reasoningByMessageIndex.get(index) || [];
       bucket.push(...entry.items.map((item) => ({ ...item })));
       reasoningByMessageIndex.set(index, bucket);
     }
   }
+  if (options.nativeLowering === true) {
+    // Native-item-capable Responses routes share the first-party lowering:
+    // native tool_search / custom calls keep their own output type, and only
+    // this route's own replay tag and reasoning state are replayed.
+    return {
+      input: convertMessagesToResponsesInput(messages, {
+        startIndex,
+        includeSystem,
+        nativePdf: options.nativePdf,
+        replayProvider,
+        // Compat-owned tool_search payloads are tagged with the route name.
+        nativeToolSearchProvider: options.providerName,
+        replayOwnedReasoning: true,
+        reasoningByMessageIndex,
+        effortProjection: options.effortProjection,
+        splitToolContent: (content) => splitToolContentForXaiResponses(content, { nativePdf: options.nativePdf }),
+      }),
+      previousResponseId,
+      startIndex,
+      continuationResetReason: resetReason,
+    };
+  }
   const pendingToolMedia = [];
   const flushToolMedia = () => {
     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 +526,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,9 +1,11 @@
 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 {
   nativeResponsesTools,
+  resolveCompatMaxOutputTokens,
   toOpenAIMessages,
   toResponsesTools,
   toXaiResponsesInput,
@@ -25,17 +27,34 @@ import { applyCompatToolChoice, compatStreamRetryReporter } from './compat-reque
 import { envFlag as _envFlag } from '../../../shared/env.mjs';
 import { resolveResponsesTransportPolicy, RESPONSES_TRANSPORT_CAPABILITIES } from './openai-transport-policy.mjs';
 
+// Server-side tool search is strictly opt-in, from the provider's own config
+// (`xaiServerToolSearch`, shared by grok-oauth's inner xai provider) or the
+// request opts. Unset, every xAI request body is unchanged: deferred tools go
+// out as plain function tools and the client `load_tool` stays a function.
+// Server-executed search items replay through the owner-tagged providerReplay
+// envelope in either mode and are never dispatched locally.
+function xaiServerToolSearchEnabled(provider, opts) {
+  return (opts.xaiServerToolSearch ?? provider.config?.xaiServerToolSearch) === true;
+}
+
 // Tool list, parallel tool calls, tool choice and reasoning effort shared by
 // the HTTP/SSE and WebSocket Responses bodies.
 function applyXaiResponsesToolsAndEffort(params, { provider, tools, opts, useModel }) {
   const nativeTools = nativeResponsesTools(opts);
   if (tools?.length || nativeTools.length) {
-    params.tools = [...nativeTools, ...toResponsesTools(tools || [], { provider: 'xai' })];
+    const toolOptions = xaiServerToolSearchEnabled(provider, opts)
+      ? { provider: 'xai', serverToolSearch: true, onToolExcluded: opts.onToolExcluded }
+      : { provider: 'xai', onToolExcluded: opts.onToolExcluded };
+    params.tools = [...nativeTools, ...toResponsesTools(tools || [], toolOptions)];
   }
   // Explicit parallel tool calls, matching the OpenAI Responses
   // reference shape. Probe-verified accepted by api.x.ai (HTTP 200,
-  // 2026-08-16); absent, the service default decides per turn.
-  if (params.tools?.length) params.parallel_tool_calls = true;
+  // 2026-08-16); absent, the service default decides per turn. An explicit
+  // caller `parallelToolCalls:false` is honored (docs.x.ai function-calling).
+  if (params.tools?.length) params.parallel_tool_calls = opts.parallelToolCalls !== false;
+  // Caller output cap (docs.x.ai text best-practices): max_output_tokens.
+  const maxOutputTokens = resolveCompatMaxOutputTokens(opts);
+  if (maxOutputTokens) params.max_output_tokens = maxOutputTokens;
   applyCompatToolChoice(params, opts);
   const reasoningEffort = normalizeXaiReasoningEffort(
     opts.xaiReasoningEffort ??
@@ -91,7 +110,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 }),
           {
@@ -127,11 +146,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 {
@@ -199,7 +219,8 @@ export async function sendXaiResponsesWebSocket(provider, messages, useModel, to
     onTextDelta: typeof opts.onTextDelta === 'function' ? opts.onTextDelta : null,
     onStageChange: typeof opts.onStageChange === 'function' ? opts.onStageChange : null,
     externalSignal: signal,
-    poolKey: opts.sessionId || opts.session?.id || null,
+    // A forked request runs in its own transport scope (transport-scope.mjs).
+    poolKey: opts.transportScope || opts.sessionId || opts.session?.id || null,
     cacheKey: cacheRouting.key,
     iteration,
     useModel,

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) {
@@ -226,13 +235,18 @@ export function useXaiResponsesApi(opts, config) {
 }
 
 export function useXaiResponsesWebSocket(opts, config) {
+  // A pinned route (grok-oauth's cli-chat-proxy) takes its transport from the
+  // config alone: the xAI WebSocket connector targets api.x.ai, so no request
+  // option or env override may carry the OAuth bearer there.
   const raw =
-    opts?.xaiResponsesTransport ??
-    opts?.xaiTransport ??
-    config?.responsesTransport ??
-    config?.transport ??
-    process.env.MIXDOG_XAI_RESPONSES_TRANSPORT ??
-    process.env.MIXDOG_XAI_TRANSPORT;
+    config?.transportPinned === true
+      ? config.responsesTransport
+      : (opts?.xaiResponsesTransport ??
+        opts?.xaiTransport ??
+        config?.responsesTransport ??
+        config?.transport ??
+        process.env.MIXDOG_XAI_RESPONSES_TRANSPORT ??
+        process.env.MIXDOG_XAI_TRANSPORT);
   // Reference xAI/Grok parity is HTTP/SSE. WebSocket remains available only
   // when a caller explicitly selects a WS transport.
   if (raw == null || raw === '') return false;

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

@@ -13,7 +13,9 @@ import {
   _shouldFallbackXaiWsToHttp,
 } from './openai-compat-xai.mjs';
 import { withEffortRejectionFallback } from './effort-rejection.mjs';
+import { applyCompatErrorContract } from './openai-compat-error-contract.mjs';
 import { sendCompatResponses } from './openai-compat-responses.mjs';
+import { COMPAT_RETRY_POLICY, COMPAT_RETRY_PROFILES, XAI_COMPAT_RETRY_POLICY } from './openai-compat-retry-profile.mjs';
 import { sendCompatChat, recoverCompatNonStreaming } from './openai-compat-chat-send.mjs';
 import { sendXaiResponses, sendXaiResponsesWebSocket } from './openai-compat-xai-send.mjs';
 import {
@@ -71,9 +73,14 @@ export class OpenAICompatProvider {
     const baseURL = assertSafeBaseURL(config.baseURL || preset?.baseURL || 'http://localhost:8080/v1', name);
     const apiKey = resolveProviderApiKey(name, config) || 'no-key';
     this.name = name;
+    // A profiled provider's limits are final: no loop-level recovery cycles on top.
+    if (COMPAT_RETRY_PROFILES[name]) this.retryPolicy = name === 'xai' ? XAI_COMPAT_RETRY_POLICY : COMPAT_RETRY_POLICY;
     this.config = config;
     this.baseURL = baseURL;
     this.apiKey = apiKey;
+    // Whether Chat content blocks keep their Anthropic-style `cache_control`
+    // (OpenRouter documents it); a gateway that does not ignores or rejects it.
+    this.chatCacheControl = (config.chatCacheControl ?? preset?.chatCacheControl) === true;
     // Merge caller-supplied headers (config.extraHeaders) over the preset's.
     // Used e.g. by grok-oauth to inject the Grok CLI client headers for the
     // grok-build proxy. Backward-compatible: providers that pass no
@@ -168,9 +175,19 @@ export class OpenAICompatProvider {
   }
   async _doSend(messages, model, tools, sendOpts) {
     const useModel = model || this.defaultModel;
-    return withEffortRejectionFallback(this.name, useModel, sendOpts || {}, this.config?.reasoningEffort, (opts) =>
-      this._sendWithOpts(messages, useModel, tools, opts)
-    );
+    try {
+      return await withEffortRejectionFallback(
+        this.name,
+        useModel,
+        sendOpts || {},
+        this.config?.reasoningEffort,
+        (opts) => this._sendWithOpts(messages, useModel, tools, opts)
+      );
+    } catch (err) {
+      // Every provider built on this transport (custom, grok, muse, mimo,
+      // command-code, local) leaves through here with the boundary contract.
+      throw applyCompatErrorContract(err);
+    }
   }
   async _sendWithOpts(messages, useModel, tools, opts) {
     // Re-warm a kept-alive socket to the provider origin before the turn so
@@ -242,7 +259,9 @@ export class OpenAICompatProvider {
     return fetchCompatModelItems(this);
   }
   async listModels() {
-    return listCompatModels(this);
+    // A failed /models request must surface; an empty list would be cached as
+    // a complete catalog by the shared catalog loader.
+    return listCompatModels(this, { throwOnError: true });
   }
   async isAvailable() {
     return isCompatProviderAvailable(this);