mixdog 0.9.94 → 0.9.96

package/src/runtime/agent/orchestrator/providers/gemini-stream.mjs

@@ -23,6 +23,7 @@ import {
     collectGeminiGroundingSources,
     parseGeminiTextPartMetadata,
 } from './gemini-schema.mjs';
+import { parseProviderJsonBatch } from './stream-json-pool.mjs';
 
 export const GEMINI_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_GEMINI_FIRST_BYTE_TIMEOUT_MS',
@@ -131,6 +132,19 @@ function geminiChunkHasFunctionCall(chunk) {
     return parts.some((p) => p && p.functionCall);
 }
 
+export function geminiChunkProgressKind(chunk) {
+    const parts = chunk?.candidates?.[0]?.content?.parts;
+    if (!Array.isArray(parts)) return 'transport';
+    if (parts.some((part) => part?.functionCall)) return 'tool';
+    if (parts.some((part) => part?.thought === true && typeof part.text === 'string' && part.text)) {
+        return 'reasoning';
+    }
+    if (parts.some((part) => part?.thought !== true && typeof part?.text === 'string' && part.text)) {
+        return 'text';
+    }
+    return 'transport';
+}
+
 /**
  * Aggregate streamed GenerateContentResponse chunks into one response object
  * (same shape as a non-streaming generateContent JSON body).
@@ -256,7 +270,7 @@ export function createGeminiTextLeakGuard({ knownToolNames, onTextDelta, onToolC
         };
         leakedCalls.push(call);
         try { onToolCall?.(call); } catch {}
-        try { onStreamDelta?.(); } catch {}
+        try { onStreamDelta?.('tool'); } catch {}
     };
 
     const pumpLeakBuffer = (final) => {
@@ -407,6 +421,7 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
             if (done) break;
             resetIdleTimer();
             buffer += decoder.decode(value, { stream: true });
+            const payloads = [];
             let lineEnd;
             while ((lineEnd = buffer.indexOf('\n')) >= 0) {
                 let line = buffer.slice(0, lineEnd);
@@ -415,18 +430,24 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
                 if (!line.startsWith('data: ')) continue;
                 const data = line.slice(6).trim();
                 if (!data || data === '[DONE]') continue;
-                let parsed;
-                try {
-                    parsed = JSON.parse(data);
-                } catch (cause) {
-                    throw geminiStreamCorruptionError(`${label} corrupt SSE JSON`, cause);
-                }
+                payloads.push(data);
+            }
+            let parsedChunks;
+            try {
+                // Preserve the established delivery boundary: once read()
+                // returned the bytes, parse and relay them before the next
+                // iteration observes cancellation.
+                parsedChunks = await parseProviderJsonBatch(payloads);
+            } catch (cause) {
+                throw geminiStreamCorruptionError(`${label} corrupt SSE JSON`, cause);
+            }
+            for (const parsed of parsedChunks) {
                 if (!sawStreamChunk) {
                     sawStreamChunk = true;
                     clearFirstByteTimer();
                 }
                 allChunks.push(parsed);
-                try { onStreamDelta?.(); } catch {}
+                try { onStreamDelta?.(geminiChunkProgressKind(parsed)); } catch {}
                 if (!sawFunctionCall && geminiChunkHasFunctionCall(parsed)) sawFunctionCall = true;
                 if (onTextDelta || textLeakGuard) {
                     const t = geminiChunkText(parsed);
@@ -440,13 +461,13 @@ export async function consumeGeminiRestStreamResponse(response, { signal, onStre
                 const data = line.slice(6).trim();
                 if (data && data !== '[DONE]') {
                     try {
-                        const parsed = JSON.parse(data);
+                        const [parsed] = await parseProviderJsonBatch([data]);
                         if (!sawStreamChunk) {
                             sawStreamChunk = true;
                             clearFirstByteTimer();
                         }
                         allChunks.push(parsed);
-                        try { onStreamDelta?.(); } catch {}
+                        try { onStreamDelta?.(geminiChunkProgressKind(parsed)); } catch {}
                         if (!sawFunctionCall && geminiChunkHasFunctionCall(parsed)) sawFunctionCall = true;
                         if (onTextDelta || textLeakGuard) {
                             const t = geminiChunkText(parsed);
@@ -677,7 +698,7 @@ export async function consumeGeminiSdkStream(streamResult, {
             }
             resetIdleTimer();
             if (step.value) collectedChunks.push(step.value);
-            try { onStreamDelta?.(); } catch {}
+            try { onStreamDelta?.(geminiChunkProgressKind(step.value)); } catch {}
             if (!sawFunctionCall && geminiChunkHasFunctionCall(step.value)) sawFunctionCall = true;
             if (onTextDelta || textLeakGuard) {
                 const t = geminiChunkText(step.value);

package/src/runtime/agent/orchestrator/providers/gemini.mjs

@@ -1,6 +1,6 @@
 import { GoogleGenerativeAI } from '@google/generative-ai';
 import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
-import { withRetry } from './retry-classifier.mjs';
+import { canFallbackNonStreaming, withRetry } from './retry-classifier.mjs';
 import { traceAgentUsage, appendAgentTrace } from '../agent-trace.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
@@ -158,6 +158,53 @@ export class GeminiProvider {
         return this.config?.apiKey || process.env.GEMINI_API_KEY || '';
     }
 
+    /**
+     * cc parity (claude.ts:2504): re-issue a dead stream ONCE as a
+     * non-streaming generateContent call instead of failing the turn.
+     * Narrower than cc by design — canFallbackNonStreaming() clears only a
+     * stream that exposed nothing, so rendered text is never duplicated and a
+     * dispatched tool can never run twice. Returns the aggregated response, or
+     * null when the failure is ineligible or the fallback itself fails.
+     */
+    async _recoverGeminiNonStreaming({ streamErr, signal, opts, model, generate }) {
+        if (!canFallbackNonStreaming(streamErr, { signal })) return null;
+        let aggregated;
+        try {
+            try { opts?.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
+            aggregated = await generate(signal || undefined);
+        } catch {
+            return null;
+        }
+        if (!aggregated || !Array.isArray(aggregated.candidates) || aggregated.candidates.length === 0) {
+            return null;
+        }
+        try {
+            process.stderr.write(
+                `[gemini] stream failed (${streamErr?.code || streamErr?.message || 'unknown'}); `
+                + `recovered via non-streaming generateContent\n`,
+            );
+        } catch { /* best-effort */ }
+        try {
+            appendAgentTrace({
+                sessionId: opts?.sessionId || opts?.session?.id || null,
+                iteration: Number.isFinite(Number(opts?.iteration)) ? Number(opts.iteration) : null,
+                kind: 'transport_fallback',
+                provider: 'gemini',
+                model,
+                transport: 'non-streaming',
+                payload: {
+                    from: 'stream',
+                    to: 'non-streaming',
+                    reason: streamErr?.retryClassifier || streamErr?.code || streamErr?.message || 'stream_failed',
+                    error_code: streamErr?.code || null,
+                    error_http_status: Number(streamErr?.httpStatus || streamErr?.status || 0) || null,
+                    error_classifier: streamErr?.retryClassifier || streamErr?.midstreamClassifier || null,
+                },
+            });
+        } catch { /* best-effort */ }
+        return aggregated;
+    }
+
     // Explicit cachedContents API. The implicit cache layer on Gemini 3.x
     // does not surface cachedContentTokenCount in usageMetadata, so the only
     // way to obtain measurable + billable cache savings is to register the
@@ -655,7 +702,30 @@ export class GeminiProvider {
                     }
                     return await this._doSend(messages, model, tools, opts, { skipExplicitCache: true });
                 }
-                throw err;
+                const recovered = await this._recoverGeminiNonStreaming({
+                    streamErr: err,
+                    signal: totalSignal,
+                    opts,
+                    model: useModel,
+                    generate: async (fallbackSignal) => {
+                        const nonStreamUrl = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(useModel)}:generateContent?key=${encodeURIComponent(apiKey)}`;
+                        const res = await this._fetch(nonStreamUrl, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify(body),
+                            signal: fallbackSignal,
+                            dispatcher: getLlmDispatcher(),
+                        });
+                        if (!res.ok) {
+                            const text = await res.text().catch(() => '');
+                            throw geminiRestError(res, text, 'Gemini REST generateContent');
+                        }
+                        return await res.json();
+                    },
+                });
+                if (!recovered) throw err;
+                textLeakGuard = null;
+                response = recovered;
             } finally {
                 restPassthrough.cleanup();
             }
@@ -749,6 +819,23 @@ export class GeminiProvider {
                         },
                     },
                 );
+            } catch (err) {
+                const recovered = await this._recoverGeminiNonStreaming({
+                    streamErr: err,
+                    signal: totalSignal,
+                    opts,
+                    model: useModel,
+                    generate: async (fallbackSignal) => {
+                        const result = await genModel.generateContent(
+                            { contents },
+                            { signal: fallbackSignal },
+                        );
+                        return result?.response ?? null;
+                    },
+                });
+                if (!recovered) throw err;
+                textLeakGuard = null;
+                response = recovered;
             } finally {
                 sdkPassthrough.cleanup();
             }

package/src/runtime/agent/orchestrator/providers/grok-oauth.mjs

@@ -23,7 +23,7 @@ import { boundProviderAuthPath } from '../../../shared/provider-auth-binding.mjs
 import { enrichModels, getModelMetadataSync } from './model-catalog.mjs';
 import { sanitizeModelList } from './model-list-sanitize.mjs';
 import { makeModelCache } from './model-cache.mjs';
-import { OpenAICompatProvider } from './openai-compat.mjs';
+import { OpenAICompatProvider, preloadOpenAICompatRuntime } from './openai-compat.mjs';
 import { createTimeoutSignal } from '../stall-policy.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import { normalizeGrokToolSchemas } from './lib/grok-tool-schema.mjs';
@@ -205,6 +205,17 @@ export class GrokOAuthProvider {
     constructor(config) {
         this.config = config || {};
         this.tokens = loadTokens();
+        // The credential/header-bound inner provider is created lazily, but its
+        // heavy SDK + undici graph and proxy socket are not request-specific.
+        // Pay both during the daemon's process-wide provider warmup so first
+        // Grok send only builds the cheap inner client.
+        try { preloadOpenAICompatRuntime(); } catch { /* authoritative send surfaces load failures */ }
+        if (this.config?.preconnect !== false) {
+            const warm = typeof this.config?.preconnectFn === 'function'
+                ? this.config.preconnectFn
+                : preconnect;
+            try { warm(PROXY_BASE_URL); } catch { /* best-effort */ }
+        }
     }
 
     async ensureAuth({ forceRefresh = false } = {}) {

package/src/runtime/agent/orchestrator/providers/lib/stream-outcome.mjs

@@ -50,7 +50,7 @@
  *                        || toolCallsComplete > 0 || toolCallsDispatched > 0
  *   sideEffectDispatched = toolCallsDispatched > 0
  *   replayUnsafe       = the ONE architecture-specific deny MixDog adds on top
- *                        of the Codex retry rules, because it streams UI text
+ *                        of the standard retry rules, because it streams UI text
  *                        and dispatches tools eagerly:
  *                        visibleOutput || sideEffectDispatched
  *                        || dispatchAmbiguous || unsafe marker

package/src/runtime/agent/orchestrator/providers/openai-codex-metadata.mjs

@@ -35,8 +35,8 @@ function _codexInstallationId(sendOpts) {
         || `mixdog-${_hashText(`${process.env.USERPROFILE || process.env.HOME || ''}:${process.cwd()}`, 32)}`;
 }
 
-// The identity block codex rebuilds per request (responses_metadata.rs
-// client_metadata()): never cached on the pooled socket, or a later turn would
+// The identity block is rebuilt per request: never cached on the pooled
+// socket, or a later turn would
 // replay the first turn's identity.
 function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = false } = {}) {
     const sessionId = _cleanMetaString(sendOpts?.codexSessionId || sendOpts?.session?.codexSessionId || poolKey || cacheKey)
@@ -49,8 +49,8 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = fa
         : _sessionStartedAtUnixMs(sessionId);
     const requestKind = _codexRequestKind(sendOpts, sessionId);
     const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
-    // codex opens the WS with a prewarm (empty turn_id) BEFORE the real turn
-    // (client.rs). Under wire parity the handshake IS that prewarm, so its
+    // The reference client opens the WS with a prewarm (empty turn_id) BEFORE
+    // the real turn. Under wire parity the handshake IS that prewarm, so its
     // turn_id empties and its request_kind becomes 'prewarm' instead of
     // presenting the handshake as a live turn. Parity off is unchanged.
     const isPrewarm = requestKind === 'prewarm' || handshake === true;
@@ -66,7 +66,7 @@ function _codexMetadataBase(entry, { poolKey, cacheKey, sendOpts, handshake = fa
         turn_id: turnId,
         window_id: windowId,
         request_kind: effectiveRequestKind,
-        // Richer codex turn-metadata (responses_metadata.rs:264-280). A/B
+        // Richer turn-metadata. A/B
         // 2026-07-04 showed no effect, so it stays behind a knob for future
         // probes; wire parity implies it.
         ...((process.env.MIXDOG_OAI_TURN_METADATA_RICH === '1' || wireParity) ? {
@@ -98,8 +98,8 @@ export function _metadataTrace(metadata) {
     };
 }
 
-// Handshake projection of the same identity. codex attaches these on every
-// request (client.rs:582-584, responses_metadata.rs:227-252); A/B 2026-07-04
+// Handshake projection of the same identity. These ride on every
+// request; A/B 2026-07-04
 // showed the turn-metadata blob alone lifts prefix-cache hits, so it is ON by
 // default. MIXDOG_OAI_TURN_METADATA overrides:
 //   unset|1|turn-metadata : window-id + turn-metadata + installation-id
@@ -141,7 +141,7 @@ export function _withCodexWsClientMetadata(frame, entry, enabled, context = {})
         'x-codex-ws-stream-request-start-ms': String(Date.now()),
     };
     if (entry && typeof entry === 'object') {
-        // codex scopes x-codex-turn-state to ONE turn (client.rs:263-279) while
+        // x-codex-turn-state is scoped to ONE turn while
         // pooled sockets span turns: attribute a captured token to the FIRST
         // turn that observes it, then drop it once turn_id moves on. An empty
         // turn_id (parity prewarm) is a valid owner, so the check is against

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

@@ -59,6 +59,22 @@ export function xaiResponsesCacheRouting(opts, params, rawTools, model) {
     const scope = String(opts?.xaiResponsesCacheScope || process.env.MIXDOG_XAI_RESPONSES_CACHE_SCOPE || 'prefix')
         .trim()
         .toLowerCase();
+    // 'none' omits prompt_cache_key entirely, matching xAI's own reference
+    // sampler (grok-build sends prompt_cache_key: None) and zed's xAI provider
+    // (supports_prompt_cache_key() == false): the service falls back to
+    // automatic prompt-prefix caching with no client-supplied lane. Callers
+    // must treat a null key as "do not send the field".
+    if (scope === 'none' || scope === 'off' || scope === 'omit') {
+        const sessionId = String(opts?.sessionId || opts?.session?.id || '').trim();
+        const prefixHash = traceHash(xaiPrefixSeed({ opts, params, rawTools, model }));
+        return {
+            key: null,
+            mode: 'none',
+            seedHash: null,
+            prefixHash,
+            ownerSessionHash: sessionId ? traceHash(sessionId) : null,
+        };
+    }
     if (scope !== 'prefix') {
         return xaiCacheRouting(opts, params, rawTools, model);
     }
@@ -183,7 +199,9 @@ export function useXaiResponsesWebSocketWarmup(opts, config, { previousResponseI
         if (['0', 'false', 'off', 'none', 'disabled'].includes(mode)) return false;
         if (['1', 'true', 'on', 'always', 'force'].includes(mode)) return true;
     }
-    return String(instructions || '').length >= 2048 || (Array.isArray(rawTools) && rawTools.length >= 10);
+    // A generate:false response can still carry provider usage/quota. Keep it
+    // strictly opt-in; transport-only HTTP/WS preconnect remains cost-free.
+    return false;
 }
 
 // Codex-aligned default: no compat cache lane/serialization. Keep the override

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

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { getAgentApiKey } from '../../../shared/provider-api-key.mjs';
-import { withRetry } from './retry-classifier.mjs';
+import { canFallbackNonStreaming, withRetry } from './retry-classifier.mjs';
 import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
 import { sendViaWebSocket } from './openai-oauth-ws.mjs';
 import { _combineUsageWithWarmup } from './openai-ws-events.mjs';
@@ -69,6 +69,16 @@ function loadOpenAI() {
     return _OpenAI;
 }
 
+// Grok OAuth creates its credential-bound inner provider only when send() has
+// the final token and request headers. Let the process-wide provider warmup pay
+// the OpenAI SDK + undici pool load before that first request reaches the hot
+// path, without constructing a fake credential-bound client.
+export function preloadOpenAICompatRuntime() {
+    const OpenAI = loadOpenAI();
+    getLlmDispatcher();
+    return OpenAI;
+}
+
 function attachCompletedWarmup(err, warmup) {
     if (!err || !warmup?.usage) return err;
     try {
@@ -238,7 +248,8 @@ export class OpenAICompatProvider {
         // extraHeaders behave exactly as before.
         this.defaultHeaders = { ...(preset?.extraHeaders || {}), ...(config.extraHeaders || {}) };
         this.defaultModel = preset?.defaultModel || 'default';
-        this.client = new (loadOpenAI())({
+        const OpenAI = preloadOpenAICompatRuntime();
+        this.client = new OpenAI({
             baseURL,
             apiKey,
             defaultHeaders: this.defaultHeaders,
@@ -253,6 +264,12 @@ export class OpenAICompatProvider {
             // a harmless no-op then.
             fetchOptions: { dispatcher: getLlmDispatcher() },
         });
+        // Provider registry initialization normally runs during daemon warmup.
+        // Start the origin handshake there; the per-send call below remains as
+        // the TTL-gated rewarm after long idle gaps.
+        if (this.config?.preconnect !== false) {
+            try { this._preconnectFn(this.baseURL); } catch { /* best-effort */ }
+        }
     }
     get _preconnectFn() {
         return typeof this.config?.preconnectFn === 'function'
@@ -420,44 +437,52 @@ export class OpenAICompatProvider {
         params.stream_options = { include_usage: true };
         let assembled;
         try {
-            assembled = await withRetry(
-                async ({ signal: attemptSignal }) => {
-                    try { opts.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
-                    const stream = await withRetry(
-                        ({ signal: openSignal }) => this.client.chat.completions.create(params, { signal: openSignal }),
-                        {
+            try {
+                assembled = await withRetry(
+                    async ({ signal: attemptSignal }) => {
+                        try { opts.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
+                        const stream = await withRetry(
+                            ({ signal: openSignal }) => this.client.chat.completions.create(params, { signal: openSignal }),
+                            {
+                                signal: attemptSignal,
+                                // Single attempt: this inner wrapper exists only to
+                                // apply the first-byte per-attempt timeout. Retry is
+                                // owned by the outer withRetry — nesting retry loops
+                                // here multiplied tail latency (5x5).
+                                maxAttempts: 1,
+                                perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+                                perAttemptLabel: `${this.name} first byte`,
+                            },
+                        );
+                        try { opts.onStageChange?.('streaming'); } catch { /* heartbeat best-effort */ }
+                        return consumeCompatChatCompletionStream(stream, {
                             signal: attemptSignal,
-                            // Single attempt: this inner wrapper exists only to
-                            // apply the first-byte per-attempt timeout. Retry is
-                            // owned by the outer withRetry — nesting retry loops
-                            // here multiplied tail latency (5x5).
-                            maxAttempts: 1,
-                            perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
-                            perAttemptLabel: `${this.name} first byte`,
+                            label: this.name,
+                            onStreamDelta: opts.onStreamDelta,
+                            onToolCall: opts.onToolCall,
+                            onTextDelta: opts.onTextDelta,
+                            parseToolCalls,
+                            // Known tool names for the leaked-tool-call guard:
+                            // recovered leaked calls only synthesize when they name
+                            // a tool actually offered to this request.
+                            knownToolNames: knownToolNamesFromOpenAITools(params.tools),
+                        });
+                    },
+                    {
+                        signal: totalSignal.signal,
+                        onRetry: ({ attempt, lastErr, delayMs, delayReason }) => {
+                            const delayLabel = Number.isFinite(Number(delayMs)) ? `, delay ${delayMs}ms${delayReason ? ` (${delayReason})` : ''}` : '';
+                            process.stderr.write(`[${this.name}] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}${delayLabel}\n`);
                         },
-                    );
-                    try { opts.onStageChange?.('streaming'); } catch { /* heartbeat best-effort */ }
-                    return consumeCompatChatCompletionStream(stream, {
-                        signal: attemptSignal,
-                        label: this.name,
-                        onStreamDelta: opts.onStreamDelta,
-                        onToolCall: opts.onToolCall,
-                        onTextDelta: opts.onTextDelta,
-                        parseToolCalls,
-                        // Known tool names for the leaked-tool-call guard:
-                        // recovered leaked calls only synthesize when they name
-                        // a tool actually offered to this request.
-                        knownToolNames: knownToolNamesFromOpenAITools(params.tools),
-                    });
-                },
-                {
-                    signal: totalSignal.signal,
-                    onRetry: ({ attempt, lastErr, delayMs, delayReason }) => {
-                        const delayLabel = Number.isFinite(Number(delayMs)) ? `, delay ${delayMs}ms${delayReason ? ` (${delayReason})` : ''}` : '';
-                        process.stderr.write(`[${this.name}] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}${delayLabel}\n`);
                     },
-                },
-            );
+                );
+            } catch (streamErr) {
+                const recovered = await this._recoverCompatNonStreaming({
+                    streamErr, params, opts, signal: totalSignal.signal, useModel,
+                });
+                if (!recovered) throw streamErr;
+                assembled = recovered;
+            }
         } finally {
             totalSignal.cleanup();
         }
@@ -567,6 +592,83 @@ export class OpenAICompatProvider {
             })() : undefined,
         };
     }
+    /**
+     * cc parity (claude.ts:2504): when a stream dies, re-issue the SAME request
+     * with `stream:false` rather than failing the turn. Narrower than cc on
+     * purpose — canFallbackNonStreaming() clears only a stream that exposed
+     * NOTHING, so an eagerly dispatched tool can never run twice and rendered
+     * text is never duplicated (that case belongs to the loop's retraction
+     * replay). Returns the same assembled shape the stream consumer produces,
+     * or null when the failure is ineligible or the fallback itself fails.
+     */
+    async _recoverCompatNonStreaming({ streamErr, params, opts, signal, useModel }) {
+        if (!canFallbackNonStreaming(streamErr, { signal })) return null;
+        const nonStreamParams = { ...params, stream: false };
+        delete nonStreamParams.stream_options;
+        let response;
+        try {
+            try { opts.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
+            response = await withRetry(
+                ({ signal: attemptSignal }) => this.client.chat.completions.create(
+                    nonStreamParams,
+                    { signal: attemptSignal },
+                ),
+                {
+                    signal,
+                    maxAttempts: 1,
+                    // A non-streaming call returns only when generation is done,
+                    // so the first-byte bound would false-abort it.
+                    perAttemptTimeoutMs: PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
+                    perAttemptLabel: `${this.name} non-streaming fallback`,
+                },
+            );
+        } catch {
+            return null;
+        }
+        const choice = response?.choices?.[0] || null;
+        if (!choice) return null;
+        const message = choice.message || {};
+        let toolCalls;
+        try {
+            toolCalls = parseToolCalls(choice, this.name);
+        } catch {
+            return null;
+        }
+        try {
+            process.stderr.write(
+                `[${this.name}] stream failed (${streamErr?.code || streamErr?.message || 'unknown'}); `
+                + `recovered via non-streaming request\n`,
+            );
+        } catch { /* best-effort */ }
+        try {
+            appendAgentTrace({
+                sessionId: opts?.sessionId || opts?.session?.id || null,
+                iteration: Number.isFinite(Number(opts?.iteration)) ? Number(opts.iteration) : null,
+                kind: 'transport_fallback',
+                provider: this.name,
+                model: useModel,
+                transport: 'non-streaming',
+                payload: {
+                    from: 'stream',
+                    to: 'non-streaming',
+                    reason: streamErr?.retryClassifier || streamErr?.code || streamErr?.message || 'stream_failed',
+                    error_code: streamErr?.code || null,
+                    error_http_status: Number(streamErr?.httpStatus || streamErr?.status || 0) || null,
+                    error_classifier: streamErr?.retryClassifier || streamErr?.midstreamClassifier || null,
+                },
+            });
+        } catch { /* best-effort */ }
+        return {
+            response,
+            model: response.model || useModel,
+            content: typeof message.content === 'string' ? message.content : '',
+            toolCalls,
+            stopReason: choice.finish_reason || null,
+            reasoningContent: typeof message.reasoning_content === 'string' ? message.reasoning_content : null,
+            rawUsage: response.usage || null,
+        };
+    }
+
     async _doSendXaiResponses(messages, useModel, tools, opts) {
         const signal = opts.signal || null;
         if (signal?.aborted) {
@@ -589,8 +691,11 @@ export class OpenAICompatProvider {
             // existing request bodies.
             store: false,
             include: ['reasoning.encrypted_content'],
-            prompt_cache_key: cacheRouting.key,
         };
+        // A null routing key means "omit the field" (cache scope 'none'):
+        // xAI's own client sends no prompt_cache_key and relies on the
+        // service's automatic prefix caching.
+        if (cacheRouting.key) params.prompt_cache_key = cacheRouting.key;
         if (previousResponseId) params.previous_response_id = previousResponseId;
         const nativeTools = nativeResponsesTools(opts);
         if (tools?.length || nativeTools.length) params.tools = [...nativeTools, ...toResponsesTools(tools || [], { provider: 'xai' })];
@@ -797,8 +902,8 @@ export class OpenAICompatProvider {
             input,
             store: false,
             include: ['reasoning.encrypted_content'],
-            prompt_cache_key: cacheRouting.key,
         };
+        if (cacheRouting.key) params.prompt_cache_key = cacheRouting.key;
         const instructions = xaiSystemInstructions(messages);
         if (previousResponseId) params.previous_response_id = previousResponseId;
         // xAI rejects instructions together with previous_response_id; the