mixdog 1.2.2 → 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.mjs

@@ -22,6 +22,7 @@ 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';
@@ -87,15 +88,38 @@ function customEffortProjection(provider, useModel, messages, opts) {
   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 custom route's session identity: its prompt_cache_key and session
+ * 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 (!isCustomProviderName(provider.name)) return '';
+  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
@@ -126,7 +150,11 @@ function buildCompatResponsesParams({
   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);
@@ -207,6 +235,22 @@ async function streamCompatResponses({ provider, params, label, signal, opts, he
   }
 }
 
+// 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
@@ -229,6 +273,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
   }
   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, {
@@ -237,6 +282,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
     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,
@@ -254,7 +300,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
     sessionCacheKey,
   });
   // The session identity also travels as headers; caller headers win.
-  const headers = sessionCacheKey
+  const headers = sessionCacheKey && isCustomProviderName(provider.name)
     ? { 'session-id': sessionCacheKey, 'x-client-request-id': sessionCacheKey, ...opts.requestHeaders }
     : opts.requestHeaders;
 
@@ -287,7 +333,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
   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;
@@ -296,6 +342,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
     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,
@@ -306,6 +353,7 @@ async function sendCompatResponsesOnce(provider, messages, useModel, tools, opts
         previousResponseId: null,
         responseId: response?.id || null,
         store: false,
+        owner: replayProvider,
         encryptedReasoningItems: reasoningItems,
         encryptedReasoningHistory,
         seenMessageCount: messageIndex,

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';
 
@@ -151,7 +152,12 @@ export async function consumeCompatResponsesStream(
     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,8 +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);
@@ -39,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 = [];
@@ -62,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 = ' ';
@@ -104,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);
   }
@@ -113,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',
@@ -146,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) => {
@@ -170,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);
   });
 }
@@ -237,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
@@ -409,16 +461,41 @@ 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;

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

@@ -5,6 +5,7 @@ import { consumeCompatResponsesStream } from './openai-compat-stream.mjs';
 import { PROVIDER_FIRST_BYTE_TIMEOUT_MS, createPassthroughSignal } from '../stall-policy.mjs';
 import {
   nativeResponsesTools,
+  resolveCompatMaxOutputTokens,
   toOpenAIMessages,
   toResponsesTools,
   toXaiResponsesInput,
@@ -26,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 ??
@@ -201,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

@@ -235,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

@@ -78,6 +78,9 @@ export class OpenAICompatProvider {
     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
@@ -256,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);