mixdog 1.2.1 → 1.2.3

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

@@ -12,6 +12,41 @@ function normalizeReasoningEffort(value, allowed) {
   return allowed.includes(effort) ? effort : null;
 }
 
+/**
+ * OpenRouter's unified `reasoning` field, shared by its Chat and Responses
+ * wires: `openRouterReasoningEffort`, else the turn effort, else the configured
+ * effort; `none` disables reasoning. Null when no effort applies.
+ */
+export function openRouterReasoning(opts = {}, config = {}) {
+  const effort = normalizeReasoningEffort(opts.openRouterReasoningEffort ?? opts.effort ?? config?.reasoningEffort, [
+    'none',
+    'minimal',
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+    'max',
+  ]);
+  if (effort === 'none') return { enabled: false };
+  return effort ? { enabled: true, effort } : null;
+}
+
+function deepseekRawEffort(opts, config) {
+  return opts.deepseekReasoningEffort ?? opts.effort ?? config?.reasoningEffort;
+}
+
+/** 'enabled' | 'disabled' as the DeepSeek request will carry it, or null when nothing sets it. */
+export function deepseekThinkingMode(opts = {}, config = {}) {
+  const rawThinking = opts.deepseekThinking ?? opts.thinking ?? config?.thinking;
+  const rawEffort = deepseekRawEffort(opts, config);
+  if (rawThinking === undefined && rawEffort === undefined) return null;
+  const thinkingMode = String(rawThinking?.type ?? rawThinking ?? rawEffort)
+    .trim()
+    .toLowerCase();
+  const disabled = rawThinking === false || thinkingMode === 'disabled' || thinkingMode === 'none';
+  return disabled ? 'disabled' : 'enabled';
+}
+
 // Keep provider extensions isolated: fields accepted by one OpenAI-compatible
 // backend are frequently rejected by another even when the core Chat schema
 // is shared.
@@ -23,22 +58,14 @@ export function applyCompatProviderChatOptions(params, providerName, opts = {},
       protocol: 'openai-chat',
       model: modelInfo,
       effort: opts.effort ?? config?.reasoningEffort,
+      baseURL: config?.baseURL,
     });
     Object.assign(params, fields);
     return params;
   }
   if (providerName === 'openrouter') {
-    const effort = normalizeReasoningEffort(opts.openRouterReasoningEffort ?? opts.effort ?? config?.reasoningEffort, [
-      'none',
-      'minimal',
-      'low',
-      'medium',
-      'high',
-      'xhigh',
-      'max',
-    ]);
-    if (effort === 'none') params.reasoning = { enabled: false };
-    else if (effort) params.reasoning = { enabled: true, effort };
+    const reasoning = openRouterReasoning(opts, config);
+    if (reasoning) params.reasoning = reasoning;
     return params;
   }
   if (providerName === 'xai') {
@@ -53,22 +80,17 @@ export function applyCompatProviderChatOptions(params, providerName, opts = {},
     return params;
   }
   if (providerName === 'deepseek') {
-    const rawThinking = opts.deepseekThinking ?? opts.thinking ?? config?.thinking;
-    const rawEffort = opts.deepseekReasoningEffort ?? opts.effort ?? config?.reasoningEffort;
-    if (rawThinking !== undefined || rawEffort !== undefined) {
-      const thinkingMode = String(rawThinking?.type ?? rawThinking ?? rawEffort)
-        .trim()
-        .toLowerCase();
-      const disabled = rawThinking === false || thinkingMode === 'disabled' || thinkingMode === 'none';
-      params.thinking = { type: disabled ? 'disabled' : 'enabled' };
-      if (!disabled) {
-        const effort = String(rawEffort ?? '')
+    const mode = deepseekThinkingMode(opts, config);
+    if (mode) {
+      params.thinking = { type: mode };
+      if (mode === 'enabled') {
+        const effort = String(deepseekRawEffort(opts, config) ?? '')
           .trim()
           .toLowerCase();
-        if (effort === 'max') params.reasoning_effort = 'max';
-        // DeepSeek documents low/high/max; `medium` is its own alias for
-        // high, and `low` is a real level that must not be promoted.
-        else if (effort === 'low') params.reasoning_effort = 'low';
+        // DeepSeek documents low/high/max; `ultra` is its alias for max,
+        // `minimal` for low, `medium`/`xhigh` for high; `low` must not be promoted.
+        if (effort === 'max' || effort === 'ultra') params.reasoning_effort = 'max';
+        else if (effort === 'low' || effort === 'minimal') params.reasoning_effort = 'low';
         else if (['medium', 'high', 'xhigh'].includes(effort)) params.reasoning_effort = 'high';
       }
     }

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

@@ -11,12 +11,16 @@ export const OPENAI_COMPAT_PRESETS = {
   },
   // OpenCode Go - low-cost coding-model subscription gateway.
   'opencode-go': {
-    baseURL: 'https://opencode.ai/zen/go/v1',
+    baseURL: 'https://opencode.ai/inference/go/v1',
     defaultModel: 'glm-5.2',
+    // The gateway expects an application User-Agent (not the SDK default).
+    extraHeaders: { 'User-Agent': 'mixdog' },
   },
   openrouter: {
     baseURL: 'https://openrouter.ai/api/v1',
     defaultModel: 'openrouter/auto',
+    // OpenRouter documents cache_control on Chat content blocks.
+    chatCacheControl: true,
     extraHeaders: {
       'HTTP-Referer': 'https://github.com/tribgames/mixdog',
       'X-OpenRouter-Title': 'mixdog',

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

@@ -0,0 +1,151 @@
+/**
+ * openai-compat-reasoning-field.mjs — provider-specific reasoning shapes on the
+ * Chat Completions wire that the plain `reasoning_content` string path misses.
+ *
+ * Together AI (docs.together.ai/docs/inference/chat/reasoning): the chain of
+ * thought arrives on `reasoning` OR `reasoning_content` (model dependent), on
+ * the message and on each streaming delta, and must be passed back "under the
+ * same key" on prior assistant turns. vLLM reports it on `reasoning` (formerly
+ * `reasoning_content`), Groq on `message.reasoning` (reasoning_format parsed).
+ * OpenRouter reports plain text on `reasoning` next to `reasoning_details`.
+ *
+ * Mistral (docs.mistral.ai/studio/conversations/reasoning): with reasoning on,
+ * `message.content` / `delta.content` is a list of typed chunks —
+ * `{type:'thinking', thinking:[{type:'text', text}]}` and `{type:'text', text}`
+ * — and the full assistant message, thinking chunk included, goes back in the
+ * history. Receiving is by the response shape (an array), never by model name.
+ */
+
+/** `message.providerMetadata[key].reasoningField`: the key a reply's reasoning arrived on. */
+export const COMPAT_REASONING_METADATA_KEY = 'openaiCompat';
+
+const TOGETHER_HOSTS = ['together.xyz', 'together.ai'];
+const GROQ_HOSTS = ['groq.com'];
+const MISTRAL_HOSTS = ['mistral.ai'];
+
+function hostMatches(baseURL, domains) {
+  let host;
+  try {
+    host = new URL(String(baseURL || '')).hostname.toLowerCase();
+  } catch {
+    return false;
+  }
+  return domains.some((domain) => host === domain || host.endsWith(`.${domain}`));
+}
+
+export function isTogetherBaseURL(baseURL) {
+  return hostMatches(baseURL, TOGETHER_HOSTS);
+}
+
+/**
+ * Where an endpoint family reports reasoning and how a prior turn's reasoning
+ * goes back. `readsReasoningAlias`: the `reasoning` key is a reasoning field
+ * (otherwise only `reasoning_content` is). `resend`:
+ *   same_key        — back under the key it arrived on (Together, vLLM)
+ *   reasoning       — plain text as `reasoning`; reasoning_details win (OpenRouter)
+ *   content_chunks  — as a `thinking` chunk in the assistant content (Mistral)
+ *   none            — never echoed; the docs do not ask for it (Groq)
+ */
+const SHAPES = Object.freeze({
+  together: Object.freeze({ id: 'together', readsReasoningAlias: true, resend: 'same_key' }),
+  vllm: Object.freeze({ id: 'vllm', readsReasoningAlias: true, resend: 'same_key' }),
+  groq: Object.freeze({ id: 'groq', readsReasoningAlias: true, resend: 'none' }),
+  mistral: Object.freeze({ id: 'mistral', readsReasoningAlias: false, resend: 'content_chunks' }),
+  openrouter: Object.freeze({ id: 'openrouter', readsReasoningAlias: true, resend: 'reasoning' }),
+});
+
+/**
+ * The reasoning shape of a provider, or null for the plain `reasoning_content`
+ * path. OpenRouter is by provider name, Together/Groq/Mistral by the provider's
+ * own base URL, vLLM (no fixed host) by the model row's `vllm` wire format.
+ */
+export function compatReasoningShape({ providerName, baseURL, wireFormat } = {}) {
+  if (providerName === 'openrouter') return SHAPES.openrouter;
+  if (wireFormat === 'together' || isTogetherBaseURL(baseURL)) return SHAPES.together;
+  if (wireFormat === 'vllm') return SHAPES.vllm;
+  if (hostMatches(baseURL, GROQ_HOSTS)) return SHAPES.groq;
+  if (hostMatches(baseURL, MISTRAL_HOSTS)) return SHAPES.mistral;
+  return null;
+}
+
+/**
+ * The receive field worth recording for replay: `reasoning` (non-default key)
+ * or `content_chunks` (Mistral), per shape; `reasoning_content` is the default
+ * and needs no record. Null when nothing needs remembering.
+ */
+export function replayReasoningField(shape, source) {
+  if (!shape) return null;
+  if (shape.resend === 'same_key' && source === 'reasoning') return 'reasoning';
+  if (shape.resend === 'content_chunks' && source === 'content_chunks') return 'content_chunks';
+  return null;
+}
+
+/** Whether a reply's reasoning source is captured under this shape. */
+export function capturesShapeReasoning(shape, source) {
+  if (!shape) return source === 'content_chunks';
+  if (source === 'content_chunks') return true;
+  return source === 'reasoning_content' || (shape.readsReasoningAlias && source === 'reasoning');
+}
+
+/** Assistant content with the prior reasoning replayed as a leading `thinking` chunk. */
+export function contentWithThinkingChunk(content, reasoning) {
+  const thinking = { type: 'thinking', thinking: [{ type: 'text', text: reasoning }] };
+  if (Array.isArray(content)) return [thinking, ...content];
+  return typeof content === 'string' && content ? [thinking, { type: 'text', text: content }] : [thinking];
+}
+
+function thinkingText(thinking) {
+  if (typeof thinking === 'string') return thinking;
+  if (!Array.isArray(thinking)) return '';
+  return thinking
+    .map((inner) => (typeof inner === 'string' ? inner : typeof inner?.text === 'string' ? inner.text : ''))
+    .join('');
+}
+
+/**
+ * Ordered `{kind:'reasoning'|'text', text}` parts of an array-shaped `content`,
+ * or null when `content` is not an array (the plain string/absent shape).
+ */
+export function chatContentParts(content) {
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const chunk of content) {
+    if (typeof chunk === 'string') {
+      parts.push({ kind: 'text', text: chunk });
+    } else if (chunk?.type === 'thinking') {
+      parts.push({ kind: 'reasoning', text: thinkingText(chunk.thinking) });
+    } else if (chunk?.type === 'text' && typeof chunk.text === 'string') {
+      parts.push({ kind: 'text', text: chunk.text });
+    }
+  }
+  return parts;
+}
+
+/**
+ * Content text, reasoning and reasoning source of one non-streaming message.
+ * `reasoning_content` keeps priority; the `reasoning` alias is read only under
+ * a shape that reports reasoning there; thinking chunks fill in when no field
+ * carried reasoning.
+ */
+export function readChatMessage(message, { shape = null } = {}) {
+  const parts = chatContentParts(message?.content);
+  const content = parts
+    ? parts
+        .filter((part) => part.kind === 'text')
+        .map((part) => part.text)
+        .join('')
+    : typeof message?.content === 'string'
+      ? message.content
+      : '';
+  if (typeof message?.reasoning_content === 'string') {
+    return { content, reasoningContent: message.reasoning_content, reasoningSource: 'reasoning_content' };
+  }
+  if (shape?.readsReasoningAlias && typeof message?.reasoning === 'string') {
+    return { content, reasoningContent: message.reasoning, reasoningSource: 'reasoning' };
+  }
+  const thinking = parts?.filter((part) => part.kind === 'reasoning');
+  if (thinking?.length) {
+    return { content, reasoningContent: thinking.map((part) => part.text).join(''), reasoningSource: 'content_chunks' };
+  }
+  return { content, reasoningContent: null, reasoningSource: null };
+}

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

@@ -7,18 +7,20 @@ import {
   writeXaiResponsesCacheTrace,
 } from './openai-compat-xai.mjs';
 import { createProviderReplay } from './lib/provider-replay.mjs';
-
-const reportedNumber = (value) =>
-  value == null || (typeof value === 'string' && value.trim() === '') ? Number.NaN : Number(value);
+import { reportedCostUsd } from './lib/usage-primitives.mjs';
+import { stampStreamOutcome, STREAM_TRANSPORTS } from './lib/stream-outcome.mjs';
+import { failingFinishReasonError } from './openai-compat-stream-common.mjs';
+import {
+  COMPAT_REASONING_METADATA_KEY,
+  capturesShapeReasoning,
+  replayReasoningField,
+} from './openai-compat-reasoning-field.mjs';
 
 export function compatReportedCostUsd(providerName, usage) {
-  if (providerName === 'openrouter') {
-    const cost = reportedNumber(usage?.cost);
-    return Number.isFinite(cost) && cost >= 0 ? cost : undefined;
-  }
+  if (providerName === 'openrouter') return reportedCostUsd(usage?.cost);
   if (providerName === 'xai') {
-    const ticks = reportedNumber(usage?.cost_in_usd_ticks);
-    return Number.isFinite(ticks) && ticks >= 0 ? Number((ticks * 1e-10).toFixed(8)) : undefined;
+    const ticks = reportedCostUsd(usage?.cost_in_usd_ticks);
+    return ticks === undefined ? undefined : Number((ticks * 1e-10).toFixed(8));
   }
   return undefined;
 }
@@ -77,12 +79,11 @@ export function traceCompatResponseUsage({
   });
 }
 
-// Responses-wire reported cost: a gateway `cost` (decimal USD) when present,
-// else xAI ticks. null/empty/negative is "not reported", never a reported $0.
+// Responses-wire reported cost: xAI `cost_in_usd_ticks` when present, else a
+// gateway `cost` (decimal USD). null/empty/negative is "not reported", never a
+// reported $0.
 export function responsesReportedCostUsd(usage) {
-  const cost = reportedNumber(usage?.cost);
-  if (Number.isFinite(cost) && cost >= 0) return cost;
-  return costUsdFromTicks(usage?.cost_in_usd_ticks);
+  return costUsdFromTicks(usage?.cost_in_usd_ticks) ?? reportedCostUsd(usage?.cost);
 }
 
 export function chatCompletionUsage(providerName, usage) {
@@ -136,11 +137,33 @@ export function normalizeCompatChatResponse({
   cacheRoutingKey,
   cacheRouting,
   replaysReasoningContent,
+  reasoningShape = null,
 }) {
   const response = assembled.response;
   const choice = response.choices[0];
   const toolCalls = assembled.toolCalls;
   const stopReason = choice?.finish_reason || null;
+  const failingFinish = failingFinishReasonError(stopReason, providerName);
+  if (failingFinish) {
+    const err = failingFinish;
+    const partialContent = assembled.content || '';
+    Object.assign(err, {
+      partialContent,
+      partialToolCalls: Array.isArray(toolCalls) && toolCalls.length ? toolCalls : undefined,
+      pendingToolUse: false,
+      partialModel: response.model || useModel,
+      ...(response.usage ? { partialUsage: chatCompletionUsage(providerName, response.usage) } : {}),
+    });
+    stampStreamOutcome(err, {
+      transport: STREAM_TRANSPORTS.NON_STREAMING,
+      provider: 'openai-compat',
+      terminalObserved: false,
+      continuation: true,
+      textObservedChars: partialContent.length,
+      toolCallsComplete: err.partialToolCalls?.length || 0,
+    });
+    throw err;
+  }
   if (
     (stopReason === 'length' && Array.isArray(toolCalls) && toolCalls.length > 0) ||
     stopReason === 'content_filter'
@@ -150,7 +173,7 @@ export function normalizeCompatChatResponse({
       code: 'PROVIDER_INCOMPLETE',
       providerIncomplete: true,
       finishReason: stopReason,
-      partialContent: choice?.message?.content || '',
+      partialContent: assembled.content || '',
       partialToolCalls: toolCalls,
       model: response.model || useModel,
       responseId: response.id || null,
@@ -182,14 +205,30 @@ export function normalizeCompatChatResponse({
       cachedTokens: extractCompatCachedTokens(response.usage),
     });
   }
+  // Together/vLLM/Groq/OpenRouter report reasoning on `reasoning` or
+  // `reasoning_content`; Mistral reports it as thinking chunks inside
+  // `content`. Both are captured by the provider's own shape / the response
+  // shape, whatever the replay flag says.
+  const reasoningField = replayReasoningField(reasoningShape, assembled.reasoningSource);
   const capturesReasoningContent =
-    providerName === 'deepseek' || providerName === 'xai' || providerName === 'mixdog-local' || replaysReasoningContent;
+    providerName === 'deepseek' ||
+    providerName === 'xai' ||
+    providerName === 'mixdog-local' ||
+    replaysReasoningContent ||
+    capturesShapeReasoning(reasoningShape, assembled.reasoningSource);
   const reasoningContent =
     capturesReasoningContent && typeof assembled.reasoningContent === 'string' ? assembled.reasoningContent : null;
   const reasoningDetails =
     providerName === 'openrouter' && Array.isArray(choice?.message?.reasoning_details)
       ? choice.message.reasoning_details
       : null;
+  // Replay sends reasoning back under the field it arrived on.
+  const providerMetadata = {
+    ...(reasoningDetails?.length ? { openrouter: { reasoning_details: reasoningDetails } } : {}),
+    ...(reasoningContent !== null && reasoningField
+      ? { [COMPAT_REASONING_METADATA_KEY]: { reasoningField } }
+      : {}),
+  };
   return {
     content: assembled.content || '',
     // Streamed chunks can omit `model`; fall back to the requested
@@ -205,11 +244,7 @@ export function normalizeCompatChatResponse({
     // instead of silently treating a truncated answer as complete.
     ...(stopReason === 'length' && (assembled.content || '').length > 0 ? { truncated: true } : {}),
     ...(reasoningContent !== null ? { reasoningContent } : {}),
-    ...(reasoningDetails?.length
-      ? {
-          providerMetadata: { openrouter: { reasoning_details: reasoningDetails } },
-        }
-      : {}),
+    ...(Object.keys(providerMetadata).length ? { providerMetadata } : {}),
     usage: response.usage ? chatCompletionUsage(providerName, response.usage) : undefined,
   };
 }
@@ -309,8 +344,14 @@ export function normalizeXaiResponsesWebSocket({
   cacheLane,
 }) {
   const responseId = result.responseId || previousResponseId || null;
-  const encryptedReasoningItems = encryptedXaiReasoningItems(result.responseItems);
-  const providerReplay = createProviderReplay('xai-responses', result.responseItems);
+  // The WS send result drops the collector's `responseItems`; its own
+  // owner-tagged `providerReplay` (traceProvider 'xai') still carries every
+  // output item in order: encrypted reasoning and server-executed tool_search
+  // call/output pairs. Always taken, so they survive to the next turn as xAI
+  // requires.
+  const responseItems = result.responseItems ?? result.providerReplay?.items;
+  const encryptedReasoningItems = encryptedXaiReasoningItems(responseItems);
+  const providerReplay = createProviderReplay('xai-responses', responseItems);
   const encryptedReasoningHistory = xaiEncryptedReasoningHistory(opts, messages, encryptedReasoningItems);
   const rawUsage = result.usage?.raw || result.usage || null;
   const response = {

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

@@ -2,11 +2,18 @@
 // wire event type maps to one handler over the shared stream `state`; `ctx`
 // carries the label, the caller callbacks and the leaked-text relay.
 import { typedStatusFrom } from './retry-classifier.mjs';
-import { customToolCallFromResponseItem, nativeToolSearchCallFromArguments } from './custom-tool-wire.mjs';
+import { applyCompatErrorContract } from './openai-compat-error-contract.mjs';
+import {
+  customToolCallFromResponseItem,
+  nativeToolSearchCallFromArguments,
+  withToolCallNamespace,
+} from './custom-tool-wire.mjs';
+import { createRefusals } from './openai-ws-response-state/refusals.mjs';
 import { emitCompatToolCallOnce } from './openai-compat-stream-common.mjs';
 import { truncatedCompatStreamError, parseCompletedToolCallArgumentsJson } from './lib/openai-tool-args.mjs';
 import { incompleteReasonFromEvent, isMaxOutputIncompleteReason } from './lib/responses-terminal-fields.mjs';
 import { responsesUsage } from './openai-compat-response-normalization.mjs';
+import { normalizeGatewayErrorDetail } from './provider-error-kind.mjs';
 
 // An incomplete response was still billed: carry its reported usage on the
 // error so the provider-boundary accounting records it.
@@ -34,16 +41,20 @@ function signal(ctx, kind) {
 // through the fatal-code deny-list / default-retry classification.
 function typedResponsesFailure(message, event) {
   const err = new Error(message);
-  const detail = event?.response?.error || event?.error || null;
+  // A gateway's canonical error_type (OpenRouter's top-level `error_type`)
+  // replaces the lossy native code before anything classifies it.
+  const detail = normalizeGatewayErrorDetail(event?.response?.error || event?.error || null, event);
   const typed = typedStatusFrom(detail, event);
   if (typed) err.httpStatus = typed;
   const code = detail?.code ?? detail?.type ?? event?.code ?? null;
   if (code != null && code !== '') err.providerErrorCode = String(code);
   if (detail) err.providerError = detail;
   err.providerWireError = true;
-  return err;
+  return applyCompatErrorContract(err, detail || (event?.code != null ? { code: event.code } : null));
 }
 
+const streamLabel = (ctx) => ctx?.label || 'compat Responses';
+
 // Reconcile a COMPLETED function_call item into state.toolCalls: fill in the
 // id/name a streamed call may still be missing, or adopt the item as a new
 // call. `response.output_item.done` and the `response.completed` sweep see the
@@ -58,18 +69,22 @@ function reconcileCompatFunctionCallItem(state, item, label, onToolCall) {
   if (tc) {
     if (!tc.id && item.call_id) tc.id = item.call_id;
     if (!tc.name && item.name) tc.name = item.name;
+    withToolCallNamespace(tc, item);
     if (tc.id && tc.name) delete tc._pendingItemId;
     emitCompatToolCallOnce(state, tc, onToolCall);
   } else if (item.call_id && item.name) {
-    const call = {
-      id: item.call_id,
-      name: item.name,
-      arguments: parseCompletedToolCallArgumentsJson(item.arguments, label, {
+    const call = withToolCallNamespace(
+      {
         id: item.call_id,
         name: item.name,
-        finishReason: 'done',
-      }),
-    };
+        arguments: parseCompletedToolCallArgumentsJson(item.arguments, label, {
+          id: item.call_id,
+          name: item.name,
+          finishReason: 'done',
+        }),
+      },
+      item
+    );
     state.toolCalls.push(call);
     emitCompatToolCallOnce(state, call, onToolCall);
   }
@@ -78,6 +93,9 @@ function reconcileCompatFunctionCallItem(state, item, label, onToolCall) {
 
 function pushToolSearchCall(state, item, ctx) {
   if (item?.type !== 'tool_search_call') return;
+  // Server-executed search already ran inside the response; it stays in
+  // providerReplay only and is never a local load_tool dispatch.
+  if (item.execution === 'server') return;
   const callId = item.call_id || item.id || '';
   if (!callId || state.toolCalls.some((call) => call.id === callId)) return;
   const searchArgs =
@@ -162,10 +180,10 @@ function onReasoningDelta(event, state, ctx) {
 function onOutputItemAdded(event, state, ctx) {
   const type = event.item?.type;
   if (type === 'function_call') {
-    state.pendingCalls.set(event.item.id || '', {
-      name: event.item.name || '',
-      callId: event.item.call_id || '',
-    });
+    state.pendingCalls.set(
+      event.item.id || '',
+      withToolCallNamespace({ name: event.item.name || '', callId: event.item.call_id || '' }, event.item)
+    );
     state.toolTracker?.mark(event.item);
     state.toolInFlight = true;
   } else if (type === 'custom_tool_call' || type === 'tool_search_call') {
@@ -191,26 +209,47 @@ function onToolInputDelta(event, state, ctx) {
 function onFunctionCallArgumentsDone(event, state, ctx) {
   const itemId = event.item_id || '';
   const pending = state.pendingCalls.get(itemId);
-  const call = {
-    id: pending?.callId || event.call_id || '',
-    name: pending?.name || event.name || '',
-    // `*.done` ⇒ arguments are complete; a parse failure is
-    // deterministic bad JSON (permanent), not stream truncation.
-    arguments: parseCompletedToolCallArgumentsJson(event.arguments, ctx.label, {
-      id: pending?.callId || event.call_id,
-      name: pending?.name || event.name,
-      finishReason: 'done',
-    }),
-    _pendingItemId: itemId,
-  };
+  const call = withToolCallNamespace(
+    {
+      id: pending?.callId || event.call_id || '',
+      name: pending?.name || event.name || '',
+      // `*.done` ⇒ arguments are complete; a parse failure is
+      // deterministic bad JSON (permanent), not stream truncation.
+      arguments: parseCompletedToolCallArgumentsJson(event.arguments, ctx.label, {
+        id: pending?.callId || event.call_id,
+        name: pending?.name || event.name,
+        finishReason: 'done',
+      }),
+      _pendingItemId: itemId,
+    },
+    pending
+  );
   state.toolCalls.push(call);
   if (call.id && call.name) delete call._pendingItemId;
   emitCompatToolCallOnce(state, call, ctx.onToolCall);
   signal(ctx, 'tool');
 }
 
+// Refusal parts (streamed deltas, done text, final message parts) fold into
+// one typed refusal on state.refusals; the stream collector turns it into a
+// `stopReason:'refusal'` result instead of an empty success.
+const refusalsOf = (state) => (state.refusals ||= createRefusals());
+
+function onRefusalDelta(event, state, ctx) {
+  state.sawOutput = true;
+  refusalsOf(state).delta(event);
+  signal(ctx, 'semantic');
+}
+
+function onRefusalDone(event, state, ctx) {
+  state.sawOutput = true;
+  refusalsOf(state).done(event);
+  signal(ctx, 'semantic');
+}
+
 function onOutputItemDone(event, state, ctx) {
   const item = event.item || {};
+  if (item.type === 'message') refusalsOf(state).absorbMessage(item);
   if (item.type === 'function_call') {
     const itemId = reconcileCompatFunctionCallItem(state, item, ctx.label, ctx.onToolCall);
     // Drop the resolved function item from pendingCalls before
@@ -289,6 +328,7 @@ function onCompleted(event, state, ctx) {
 }
 
 function onDone(event, state, ctx) {
+  const label = streamLabel(ctx);
   if (!event.response || event.response.status === 'completed') {
     state.completed = true;
     // A stream that never emits response.completed: this frame carries usage.
@@ -298,7 +338,7 @@ function onDone(event, state, ctx) {
   if (event.response.status === 'failed') {
     const msg = event.response?.error?.message || 'response.done failed';
     throw withIncompleteUsage(
-      typedResponsesFailure(`xAI Responses stream response.done failed: ${msg}`, event),
+      typedResponsesFailure(`${label} stream response.done failed: ${msg}`, event),
       event,
       state
     );
@@ -306,27 +346,31 @@ function onDone(event, state, ctx) {
   if (event.response.status === 'incomplete') {
     const reason = incompleteReasonFromEvent(event);
     if (isMaxOutputIncompleteReason(reason)) return settleMaxOutputIncomplete(event, state, ctx, reason);
-    throw withIncompleteUsage(new Error(`xAI Responses stream response.done incomplete: ${reason}`), event, state);
+    throw withIncompleteUsage(new Error(`${label} stream response.done incomplete: ${reason}`), event, state);
   }
 }
 
-function onFailed(event, state) {
+function onFailed(event, state, ctx) {
   const msg = event.response?.error?.message || event.error?.message || event.message || 'response.failed';
   // The wire event's OWN typed status/code is preserved verbatim. A
   // forbidden/unknown failure is never coerced into a synthetic 500:
   // without typed evidence it stays unclassified and is surfaced.
-  throw withIncompleteUsage(typedResponsesFailure(`xAI Responses stream response.failed: ${msg}`, event), event, state);
+  throw withIncompleteUsage(
+    typedResponsesFailure(`${streamLabel(ctx)} stream response.failed: ${msg}`, event),
+    event,
+    state
+  );
 }
 
 function onIncomplete(event, state, ctx) {
   const reason = incompleteReasonFromEvent(event);
   if (isMaxOutputIncompleteReason(reason)) return settleMaxOutputIncomplete(event, state, ctx, reason);
-  throw withIncompleteUsage(new Error(`xAI Responses stream response.incomplete: ${reason}`), event, state);
+  throw withIncompleteUsage(new Error(`${streamLabel(ctx)} stream response.incomplete: ${reason}`), event, state);
 }
 
-function onError(event) {
+function onError(event, _state, ctx) {
   const msg = event.message || event.error?.message || 'unknown';
-  throw typedResponsesFailure(`xAI Responses stream error: ${msg}`, event);
+  throw typedResponsesFailure(`${streamLabel(ctx)} stream error: ${msg}`, event);
 }
 
 const RESPONSES_EVENT_HANDLERS = new Map([
@@ -334,6 +378,8 @@ const RESPONSES_EVENT_HANDLERS = new Map([
   ['response.output_text.delta', onOutputTextDelta],
   ['response.reasoning_text.delta', onReasoningDelta],
   ['response.reasoning_summary_text.delta', onReasoningDelta],
+  ['response.refusal.delta', onRefusalDelta],
+  ['response.refusal.done', onRefusalDone],
   ['response.output_item.added', onOutputItemAdded],
   ['response.function_call_arguments.delta', onToolInputDelta],
   ['response.custom_tool_call_input.delta', onToolInputDelta],