mixdog 0.7.1

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

@@ -0,0 +1,1467 @@
+import OpenAI from 'openai';
+import { createHash } from 'crypto';
+import { loadConfig } from '../config.mjs';
+import { withRetry } from './retry-classifier.mjs';
+import { sendViaWebSocket } from './openai-oauth-ws.mjs';
+import { appendBridgeTrace, traceBridgeUsage } from '../bridge-trace.mjs';
+import { resolveProviderCacheKey } from '../smart-bridge/cache-strategy.mjs';
+import {
+    PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+    PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
+    createTimeoutSignal,
+    resolveTimeoutMs,
+} from '../stall-policy.mjs';
+// OPENAI_COMPAT_PRESETS — self-declaring list of compat provider names and
+// their base URLs / defaults. registry.mjs imports this export so there is no
+// parallel OPENAI_COMPAT_PROVIDERS list to maintain separately.
+export const OPENAI_COMPAT_PRESETS = {
+    deepseek: {
+        baseURL: 'https://api.deepseek.com',
+        defaultModel: 'deepseek-v4-pro',
+    },
+    xai: {
+        baseURL: 'https://api.x.ai/v1',
+        defaultModel: 'grok-4.3',
+    },
+    nvidia: {
+        baseURL: 'https://integrate.api.nvidia.com/v1',
+        defaultModel: 'meta/llama-3.3-70b-instruct',
+    },
+    ollama: {
+        baseURL: 'http://localhost:11434/v1',
+        defaultModel: 'llama3.3:latest',
+    },
+    lmstudio: {
+        baseURL: 'http://localhost:1234/v1',
+        defaultModel: 'default',
+    },
+};
+const PRESETS = OPENAI_COMPAT_PRESETS;
+const MODEL_LIST_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_COMPAT_MODEL_LIST_TIMEOUT_MS',
+    10_000,
+    { minMs: 1_000, maxMs: PROVIDER_GENERATE_TOTAL_TIMEOUT_MS },
+);
+
+// SSRF guard for provider baseURL. config.baseURL comes from user JSON;
+// reject non-http(s) schemes (file:/data:/ftp:/etc.) and require https for
+// any non-localhost host. Localhost-only presets (ollama, lmstudio) and
+// loopback hosts may use http. Throws a clear config error — no silent
+// fallback — so misconfig surfaces immediately instead of leaking apiKey.
+function assertSafeBaseURL(rawURL, providerName) {
+    let parsed;
+    try {
+        parsed = new URL(String(rawURL));
+    } catch {
+        throw new Error(`[provider:${providerName}] invalid baseURL: ${rawURL}`);
+    }
+    const scheme = parsed.protocol.toLowerCase();
+    if (scheme !== 'https:' && scheme !== 'http:') {
+        throw new Error(`[provider:${providerName}] baseURL scheme not allowed: ${parsed.protocol} (only http/https)`);
+    }
+    if (scheme === 'http:') {
+        const host = parsed.hostname.toLowerCase();
+        const isLocal = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+        if (!isLocal) {
+            throw new Error(`[provider:${providerName}] baseURL must use https for non-localhost host (got ${parsed.protocol}//${parsed.hostname})`);
+        }
+    }
+    return rawURL;
+}
+
+function traceHash(value) {
+    return createHash('sha256')
+        .update(String(value ?? ''))
+        .digest('hex')
+        .slice(0, 16);
+}
+
+function stableTraceStringify(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object') {
+        if (typeof value === 'bigint') return JSON.stringify(String(value));
+        if (typeof value === 'undefined' || typeof value === 'function') return 'null';
+        return JSON.stringify(value);
+    }
+    if (seen.has(value)) return JSON.stringify('[Circular]');
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const serialized = '[' + value.map(v => stableTraceStringify(v, seen)).join(',') + ']';
+        seen.delete(value);
+        return serialized;
+    }
+    const parts = [];
+    for (const key of Object.keys(value).sort()) {
+        const v = value[key];
+        if (typeof v === 'undefined' || typeof v === 'function') continue;
+        parts.push(JSON.stringify(key) + ':' + stableTraceStringify(v, seen));
+    }
+    seen.delete(value);
+    return '{' + parts.join(',') + '}';
+}
+
+function traceTextShape(text) {
+    const value = String(text ?? '');
+    return { chars: value.length, hash: traceHash(value) };
+}
+
+function summarizeTraceMessages(messages) {
+    const summaries = (messages || []).map((m, index) => {
+        const content = typeof m?.content === 'string'
+            ? { type: 'text', ...traceTextShape(m.content) }
+            : { type: m?.content == null ? 'null' : typeof m.content, hash: traceHash(stableTraceStringify(m?.content ?? null)) };
+        const toolCalls = Array.isArray(m?.tool_calls)
+            ? m.tool_calls.map(tc => ({
+                name: tc?.function?.name || null,
+                argsHash: traceHash(tc?.function?.arguments || ''),
+            }))
+            : [];
+        return {
+            index,
+            role: m?.role || null,
+            content,
+            ...(typeof m?.reasoning_content === 'string'
+                ? { reasoningContent: traceTextShape(m.reasoning_content) }
+                : {}),
+            toolCallCount: toolCalls.length,
+            ...(toolCalls.length ? { toolCalls } : {}),
+        };
+    });
+    if (summaries.length <= 12) return summaries;
+    return [
+        ...summaries.slice(0, 8),
+        { omittedTurns: summaries.length - 12 },
+        ...summaries.slice(-4),
+    ];
+}
+
+function summarizeTraceTools(tools) {
+    return (tools || []).map(t => ({
+        name: t?.name || null,
+        description: t?.description || '',
+        inputSchema: t?.inputSchema || null,
+    }));
+}
+
+function extractCompatCachedTokens(usage) {
+    const candidates = [
+        usage?.prompt_tokens_details?.cached_tokens,
+        usage?.input_tokens_details?.cached_tokens,
+        usage?.prompt_cache_hit_tokens,
+        usage?.cached_prompt_text_tokens,
+    ];
+    for (const v of candidates) {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0) return n;
+    }
+    for (const v of candidates) {
+        const n = Number(v);
+        if (Number.isFinite(n)) return n;
+    }
+    return 0;
+}
+
+function xaiPrefixSeed({ opts, params, rawTools, model }) {
+    const providerKey = resolveProviderCacheKey(opts, 'xai');
+    const systemMessages = (params?.messages || [])
+        .filter(m => m?.role === 'system')
+        .map(m => String(m?.content ?? ''));
+    return stableTraceStringify({
+        scope: 'xai-prefix-model-system-tools',
+        providerKey: String(providerKey),
+        model: model || null,
+        systemMessages,
+        tools: summarizeTraceTools(rawTools),
+    });
+}
+
+function xaiCacheRouting(opts, params, rawTools, model) {
+    const sessionId = String(opts?.sessionId || opts?.session?.id || '').trim();
+    const providerKey = resolveProviderCacheKey(opts, 'xai');
+    const prefixSeed = xaiPrefixSeed({ opts, params, rawTools, model });
+    const prefixHash = traceHash(prefixSeed);
+    const routingSeed = stableTraceStringify({
+        scope: 'xai-chat-session-v1',
+        providerKey: String(providerKey),
+        model: model || null,
+        sessionId: sessionId || `ephemeral:${process.pid}`,
+    });
+    return {
+        key: deterministicUuidFromKey(routingSeed),
+        mode: sessionId ? 'session' : 'ephemeral',
+        seedHash: traceHash(routingSeed),
+        prefixHash,
+        ownerSessionHash: sessionId ? traceHash(sessionId) : null,
+    };
+}
+
+function xaiResponsesCacheRouting(opts, params, rawTools, model) {
+    // Default to 'prefix' so parallel workers sharing the same model + system
+    // + tools land on a common prompt_cache_key, letting xAI's server-side
+    // prefix cache hit across sessions instead of cold-starting per worker.
+    // Override with 'session' (env or opts) for legacy session-isolated lanes.
+    const scope = String(opts?.xaiResponsesCacheScope || process.env.MIXDOG_XAI_RESPONSES_CACHE_SCOPE || 'prefix')
+        .trim()
+        .toLowerCase();
+    if (scope !== 'prefix') {
+        return xaiCacheRouting(opts, params, rawTools, model);
+    }
+    const sessionId = String(opts?.sessionId || opts?.session?.id || '').trim();
+    const providerKey = resolveProviderCacheKey(opts, 'xai');
+    const prefixSeed = xaiPrefixSeed({ opts, params, rawTools, model });
+    const prefixHash = traceHash(prefixSeed);
+    const routingSeed = stableTraceStringify({
+        scope: 'xai-responses-prefix-v1',
+        providerKey: String(providerKey),
+        model: model || null,
+        prefixHash,
+    });
+    return {
+        key: deterministicUuidFromKey(routingSeed),
+        mode: 'prefix',
+        seedHash: traceHash(routingSeed),
+        prefixHash,
+        ownerSessionHash: sessionId ? traceHash(sessionId) : null,
+    };
+}
+
+function normalizeXaiReasoningEffort(value) {
+    const effort = String(value || '').trim().toLowerCase();
+    return ['none', 'low', 'medium', 'high'].includes(effort) ? effort : null;
+}
+
+function useXaiResponsesApi(opts, config) {
+    const raw = opts?.xaiApiMode
+        ?? config?.apiMode
+        ?? config?.xaiApiMode
+        ?? process.env.MIXDOG_XAI_API_MODE
+        ?? process.env.MIXDOG_XAI_RESPONSES;
+    if (raw == null || raw === '') return true;
+    const mode = String(raw).trim().toLowerCase();
+    return !['0', 'false', 'off', 'chat', 'chat-completions', 'chat_completions'].includes(mode);
+}
+
+function useXaiResponsesWebSocket(opts, config) {
+    const raw = opts?.xaiResponsesTransport
+        ?? opts?.xaiTransport
+        ?? config?.responsesTransport
+        ?? config?.transport
+        ?? process.env.MIXDOG_XAI_RESPONSES_TRANSPORT
+        ?? process.env.MIXDOG_XAI_TRANSPORT;
+    if (raw == null || raw === '') return true;
+    const transport = String(raw).trim().toLowerCase();
+    return !['0', 'false', 'off', 'http', 'https', 'responses-http', 'sdk'].includes(transport);
+}
+
+function useXaiResponsesWebSocketWarmup(opts, config, { previousResponseId, instructions, rawTools }) {
+    if (previousResponseId) return false;
+    const raw = opts?.xaiResponsesWarmup
+        ?? opts?.xaiWsWarmup
+        ?? config?.responsesWarmup
+        ?? config?.wsWarmup
+        ?? process.env.MIXDOG_XAI_RESPONSES_WARMUP
+        ?? process.env.MIXDOG_XAI_WS_WARMUP;
+    if (raw != null && raw !== '') {
+        const mode = String(raw).trim().toLowerCase();
+        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);
+}
+
+const XAI_RESPONSES_CACHE_LANE_DEFAULT_MAX_IN_FLIGHT = 2;
+const xaiResponsesCacheLanes = new Map();
+
+function parseXaiPositiveInt(value, fallback) {
+    if (value == null || value === '') return fallback;
+    const text = String(value).trim().toLowerCase();
+    if (['0', 'false', 'off', 'none', 'disabled', 'unlimited'].includes(text)) return 0;
+    const n = Number(text);
+    if (!Number.isFinite(n)) return fallback;
+    return Math.max(0, Math.floor(n));
+}
+
+function xaiResponsesCacheLaneMaxInFlight(opts, config) {
+    return parseXaiPositiveInt(
+        opts?.xaiCacheMaxInFlight
+            ?? opts?.xaiResponsesCacheMaxInFlight
+            ?? config?.xaiCacheMaxInFlight
+            ?? config?.xaiResponsesCacheMaxInFlight
+            ?? process.env.MIXDOG_XAI_CACHE_MAX_INFLIGHT
+            ?? process.env.MIXDOG_XAI_RESPONSES_CACHE_MAX_INFLIGHT,
+        XAI_RESPONSES_CACHE_LANE_DEFAULT_MAX_IN_FLIGHT,
+    );
+}
+
+function xaiResponsesCacheLaneQueueTimeoutMs(opts, config) {
+    return parseXaiPositiveInt(
+        opts?.xaiCacheQueueTimeoutMs
+            ?? opts?.xaiResponsesCacheQueueTimeoutMs
+            ?? config?.xaiCacheQueueTimeoutMs
+            ?? config?.xaiResponsesCacheQueueTimeoutMs
+            ?? process.env.MIXDOG_XAI_CACHE_QUEUE_TIMEOUT_MS
+            ?? process.env.MIXDOG_XAI_RESPONSES_CACHE_QUEUE_TIMEOUT_MS,
+        0,
+    );
+}
+
+function xaiResponsesCacheLaneShard(opts, cacheRouting) {
+    const shardCount = parseXaiPositiveInt(
+        opts?.xaiCacheLaneShards
+            ?? opts?.xaiResponsesCacheLaneShards
+            ?? process.env.MIXDOG_XAI_CACHE_LANE_SHARDS
+            ?? process.env.MIXDOG_XAI_RESPONSES_CACHE_LANE_SHARDS,
+        1,
+    );
+    if (shardCount <= 1) return 0;
+    const seed = String(opts?.sessionId || opts?.session?.id || cacheRouting?.ownerSessionHash || cacheRouting?.key || '');
+    const hex = traceHash(seed || 'xai-cache-lane');
+    return Number.parseInt(hex.slice(0, 8), 16) % shardCount;
+}
+
+function xaiResponsesCacheLaneKey({ model, cacheRouting, opts }) {
+    const prefix = cacheRouting?.prefixHash || cacheRouting?.seedHash || cacheRouting?.key || 'unknown-prefix';
+    const shard = xaiResponsesCacheLaneShard(opts, cacheRouting);
+    return {
+        key: `xai-responses:${model || 'default'}:${prefix}:shard-${shard}`,
+        shard,
+    };
+}
+
+function getXaiResponsesCacheLaneState(key, maxInFlight) {
+    let state = xaiResponsesCacheLanes.get(key);
+    if (!state) {
+        state = { key, active: 0, queue: [], maxInFlight, nextId: 0 };
+        xaiResponsesCacheLanes.set(key, state);
+    }
+    state.maxInFlight = maxInFlight;
+    return state;
+}
+
+function cleanupXaiResponsesCacheLane(state) {
+    if (state.active === 0 && state.queue.length === 0) {
+        xaiResponsesCacheLanes.delete(state.key);
+    }
+}
+
+function removeQueuedXaiCacheLaneRequest(state, request) {
+    const index = state.queue.indexOf(request);
+    if (index >= 0) state.queue.splice(index, 1);
+    cleanupXaiResponsesCacheLane(state);
+}
+
+function makeXaiCacheLaneHandle(state, requestId, enqueuedAt) {
+    let released = false;
+    return {
+        requestId,
+        waitedMs: Date.now() - enqueuedAt,
+        activeCount: state.active,
+        queueDepth: state.queue.length,
+        release() {
+            if (released) return;
+            released = true;
+            releaseXaiResponsesCacheLane(state);
+        },
+    };
+}
+
+function releaseXaiResponsesCacheLane(state) {
+    state.active = Math.max(0, state.active - 1);
+    while (state.queue.length > 0 && state.active < state.maxInFlight) {
+        const next = state.queue.shift();
+        next.cleanup?.();
+        state.active += 1;
+        next.resolve(makeXaiCacheLaneHandle(state, next.requestId, next.enqueuedAt));
+    }
+    cleanupXaiResponsesCacheLane(state);
+}
+
+function acquireXaiResponsesCacheLane({ key, maxInFlight, signal, timeoutMs }) {
+    const state = getXaiResponsesCacheLaneState(key, maxInFlight);
+    const requestId = ++state.nextId;
+    const enqueuedAt = Date.now();
+    if (state.active < state.maxInFlight) {
+        state.active += 1;
+        return Promise.resolve(makeXaiCacheLaneHandle(state, requestId, enqueuedAt));
+    }
+    return new Promise((resolve, reject) => {
+        const request = {
+            requestId,
+            enqueuedAt,
+            resolve,
+            reject,
+            cleanup: null,
+        };
+        const cleanup = () => {
+            if (request.timer) clearTimeout(request.timer);
+            if (signal && request.abortListener) signal.removeEventListener('abort', request.abortListener);
+        };
+        request.cleanup = cleanup;
+        request.abortListener = () => {
+            cleanup();
+            removeQueuedXaiCacheLaneRequest(state, request);
+            const reason = signal?.reason;
+            reject(reason instanceof Error ? reason : new Error('xAI cache lane wait aborted'));
+        };
+        if (signal?.aborted) {
+            request.abortListener();
+            return;
+        }
+        if (signal) signal.addEventListener('abort', request.abortListener, { once: true });
+        if (timeoutMs > 0) {
+            request.timer = setTimeout(() => {
+                cleanup();
+                removeQueuedXaiCacheLaneRequest(state, request);
+                reject(new Error(`xAI cache lane wait timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+        }
+        state.queue.push(request);
+    });
+}
+
+function traceXaiCacheLane(opts, payload) {
+    if (!compatCacheTraceEnabled('xai')) return;
+    try {
+        appendBridgeTrace({
+            sessionId: opts?.sessionId || opts?.session?.id || null,
+            iteration: Number.isFinite(Number(opts?.iteration)) ? Number(opts.iteration) : null,
+            kind: 'cache_lane',
+            ...payload,
+            payload,
+        });
+    } catch {}
+}
+
+async function withXaiResponsesCacheLane({ opts, config, cacheRouting, model, transport, previousResponseId, inputCount, signal }, fn) {
+    const maxInFlight = xaiResponsesCacheLaneMaxInFlight(opts, config);
+    if (maxInFlight <= 0) {
+        const laneMeta = { enabled: false, maxInFlight: 0 };
+        return { value: await fn(laneMeta), laneMeta };
+    }
+    const { key: laneKey, shard } = xaiResponsesCacheLaneKey({ model, cacheRouting, opts });
+    const timeoutMs = xaiResponsesCacheLaneQueueTimeoutMs(opts, config);
+    const state = getXaiResponsesCacheLaneState(laneKey, maxInFlight);
+    const queued = state.active >= state.maxInFlight;
+    if (queued) {
+        traceXaiCacheLane(opts, {
+            provider: 'xai',
+            api: 'responses',
+            transport,
+            event: 'queued',
+            lane_key_hash: traceHash(laneKey),
+            lane_shard: shard,
+            max_in_flight: maxInFlight,
+            active: state.active,
+            queue_depth: state.queue.length,
+            previous_response_used: !!previousResponseId,
+            input_count: inputCount,
+        });
+    }
+    const handle = await acquireXaiResponsesCacheLane({ key: laneKey, maxInFlight, signal, timeoutMs });
+    const laneMeta = {
+        enabled: true,
+        laneKeyHash: traceHash(laneKey),
+        shard,
+        maxInFlight,
+        queued,
+        waitMs: handle.waitedMs,
+        activeAfterAcquire: handle.activeCount,
+        queueDepthAfterAcquire: handle.queueDepth,
+    };
+    traceXaiCacheLane(opts, {
+        provider: 'xai',
+        api: 'responses',
+        transport,
+        event: 'acquired',
+        lane_key_hash: laneMeta.laneKeyHash,
+        lane_shard: shard,
+        max_in_flight: maxInFlight,
+        wait_ms: laneMeta.waitMs,
+        active: laneMeta.activeAfterAcquire,
+        queue_depth: laneMeta.queueDepthAfterAcquire,
+        previous_response_used: !!previousResponseId,
+        input_count: inputCount,
+    });
+    const startedAt = Date.now();
+    try {
+        return { value: await fn(laneMeta), laneMeta };
+    } finally {
+        handle.release();
+        traceXaiCacheLane(opts, {
+            provider: 'xai',
+            api: 'responses',
+            transport,
+            event: 'released',
+            lane_key_hash: laneMeta.laneKeyHash,
+            lane_shard: shard,
+            max_in_flight: maxInFlight,
+            held_ms: Date.now() - startedAt,
+            previous_response_used: !!previousResponseId,
+            input_count: inputCount,
+        });
+    }
+}
+
+function deterministicUuidFromKey(key) {
+    const hex = createHash('sha256').update(String(key ?? '')).digest('hex');
+    const variant = ((Number.parseInt(hex[16], 16) & 0x3) | 0x8).toString(16);
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        '4' + hex.slice(13, 16),
+        variant + hex.slice(17, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}
+
+function compatCacheTraceEnabled(provider) {
+    return process.env.MIXDOG_COMPAT_CACHE_TRACE === '1'
+        || process.env.MIXDOG_PROVIDER_CACHE_TRACE === '1'
+        || (provider === 'xai' && process.env.MIXDOG_XAI_CACHE_TRACE === '1');
+}
+
+function writeCompatCacheTrace({ provider, model, opts, params, rawTools, response, cacheRoutingKey, cacheRouting }) {
+    if (!compatCacheTraceEnabled(provider)) return;
+    try {
+        const usage = response?.usage || {};
+        const inputTokens = Number(usage.prompt_tokens ?? usage.input_tokens ?? 0);
+        const cachedTokens = extractCompatCachedTokens(usage);
+        const toolShape = summarizeTraceTools(rawTools);
+        const traceMessages = Array.isArray(params?.messages) ? params.messages : [];
+        const trace = {
+            event: 'chat.completions',
+            provider,
+            model,
+            responseModel: response?.model || null,
+            owner: opts?.session?.owner || null,
+            role: opts?.session?.role || opts?.role || null,
+            permission: opts?.session?.permission || null,
+            toolPermission: opts?.session?.toolPermission || null,
+            profileId: opts?.session?.profileId || null,
+            sourceType: opts?.session?.sourceType || null,
+            sourceName: opts?.session?.sourceName || null,
+            sessionIdHash: opts?.sessionId ? traceHash(opts.sessionId) : null,
+            providerCacheKeyHash: opts?.providerCacheKey ? traceHash(opts.providerCacheKey) : null,
+            promptCacheKeyHash: opts?.promptCacheKey ? traceHash(opts.promptCacheKey) : null,
+            xGrokConvIdHash: provider === 'xai' && cacheRoutingKey ? traceHash(cacheRoutingKey) : null,
+            xGrokConvIdSeedHash: provider === 'xai' ? cacheRouting?.seedHash || null : null,
+            xGrokPromptPrefixHash: provider === 'xai' ? cacheRouting?.prefixHash || null : null,
+            xGrokConvIdMode: provider === 'xai' ? cacheRouting?.mode || null : null,
+            xGrokConvIdLaneIndex: provider === 'xai' ? cacheRouting?.laneIndex ?? null : null,
+            xGrokConvIdActiveLanes: provider === 'xai' ? cacheRouting?.activeLanes ?? null : null,
+            xGrokConvIdIdleLanes: provider === 'xai' ? cacheRouting?.idleLanes ?? null : null,
+            xGrokConvIdOwnerSessionHash: provider === 'xai' ? cacheRouting?.ownerSessionHash || null : null,
+            xaiReasoningEffort: provider === 'xai' ? params?.reasoning_effort || null : null,
+            messageCount: traceMessages.length,
+            messageFullHash: traceHash(stableTraceStringify(traceMessages)),
+            messagePrefixHash: traceHash(stableTraceStringify(traceMessages.slice(0, -1))),
+            lastMessageHash: traceMessages.length ? traceHash(stableTraceStringify(traceMessages.at(-1))) : null,
+            messages: summarizeTraceMessages(traceMessages),
+            toolCount: Array.isArray(rawTools) ? rawTools.length : 0,
+            toolSchemaHash: traceHash(stableTraceStringify(toolShape)),
+            usageKeys: Object.keys(usage || {}).sort(),
+            promptTokenDetailsKeys: Object.keys(usage?.prompt_tokens_details || {}).sort(),
+            inputTokenDetailsKeys: Object.keys(usage?.input_tokens_details || {}).sort(),
+            choiceMessageKeys: Object.keys(response?.choices?.[0]?.message || {}).sort(),
+            responseReasoningContent: typeof response?.choices?.[0]?.message?.reasoning_content === 'string'
+                ? traceTextShape(response.choices[0].message.reasoning_content)
+                : null,
+            responseReasoningTokens: Number(usage?.completion_tokens_details?.reasoning_tokens ?? 0),
+            inputTokens,
+            outputTokens: Number(usage.completion_tokens ?? usage.output_tokens ?? 0),
+            cachedTokens,
+            cacheHitRate: inputTokens > 0 ? Number((cachedTokens / inputTokens).toFixed(6)) : null,
+            costInUsdTicks: typeof usage.cost_in_usd_ticks === 'number' ? usage.cost_in_usd_ticks : null,
+        };
+        process.stderr.write(`[compat-cache-trace] ${JSON.stringify(trace)}\n`);
+    } catch (err) {
+        process.stderr.write(`[compat-cache-trace] failed: ${err?.message || err}\n`);
+    }
+}
+
+function summarizeResponsesInput(input) {
+    return (input || []).map((item, index) => ({
+        index,
+        type: item?.type || null,
+        role: item?.role || null,
+        callIdHash: item?.call_id ? traceHash(item.call_id) : null,
+        name: item?.name || null,
+        content: typeof item?.content === 'string'
+            ? { type: 'text', ...traceTextShape(item.content) }
+            : { type: item?.content == null ? 'null' : typeof item.content, hash: traceHash(stableTraceStringify(item?.content ?? null)) },
+        output: typeof item?.output === 'string' ? traceTextShape(item.output) : null,
+    }));
+}
+
+function xaiUsageStats(usage) {
+    const inputTokens = Number(usage?.input_tokens ?? usage?.prompt_tokens ?? 0);
+    const outputTokens = Number(usage?.output_tokens ?? usage?.completion_tokens ?? 0);
+    const cachedTokens = extractCompatCachedTokens(usage);
+    const hitRate = inputTokens > 0 ? Number((cachedTokens / inputTokens).toFixed(6)) : null;
+    return { inputTokens, outputTokens, cachedTokens, hitRate };
+}
+
+function xaiSanitizedRequestSansInput(params) {
+    const { input: _input, ...rest } = params || {};
+    const out = { ...rest };
+    if (out.prompt_cache_key) out.prompt_cache_key = traceHash(out.prompt_cache_key);
+    if (out.previous_response_id) out.previous_response_id = traceHash(out.previous_response_id);
+    if (typeof out.instructions === 'string') out.instructions = traceHash(out.instructions);
+    return out;
+}
+
+function xaiResponsesFingerprintPayload({ model, opts, params, rawTools, response, cacheRouting, previousResponseId, inputStartIndex, transport, cacheLane }) {
+    const usage = response?.usage || {};
+    const { inputTokens, outputTokens, cachedTokens, hitRate } = xaiUsageStats(usage);
+    const toolShape = summarizeTraceTools(rawTools);
+    const instructions = typeof params?.instructions === 'string' ? params.instructions : '';
+    const requestSansInput = xaiSanitizedRequestSansInput(params);
+    const contextShape = {
+        provider: 'xai',
+        api: 'responses',
+        model: model || null,
+        promptCacheKeyHash: params?.prompt_cache_key ? traceHash(params.prompt_cache_key) : null,
+        instructions,
+        tools: toolShape,
+        reasoning: params?.reasoning || null,
+        store: params?.store ?? null,
+    };
+    const previousResponseUsed = Boolean(previousResponseId);
+    const midTurnCold = previousResponseUsed
+        && inputTokens >= 1024
+        && (cachedTokens <= 512 || (hitRate != null && hitRate < 0.1));
+    return {
+        provider: 'xai',
+        api: 'responses',
+        transport: transport || null,
+        model: model || null,
+        response_model: response?.model || null,
+        session_id_hash: opts?.sessionId ? traceHash(opts.sessionId) : null,
+        provider_cache_key_hash: opts?.providerCacheKey ? traceHash(opts.providerCacheKey) : null,
+        prompt_cache_key_option_hash: opts?.promptCacheKey ? traceHash(opts.promptCacheKey) : null,
+        prompt_cache_key_hash: params?.prompt_cache_key ? traceHash(params.prompt_cache_key) : null,
+        xai_prompt_prefix_hash: cacheRouting?.prefixHash || null,
+        xai_cache_mode: cacheRouting?.mode || null,
+        xai_cache_seed_hash: cacheRouting?.seedHash || null,
+        owner_session_hash: cacheRouting?.ownerSessionHash || null,
+        response_id_hash: response?.id ? traceHash(response.id) : null,
+        previous_response_id_hash: previousResponseId ? traceHash(previousResponseId) : null,
+        previous_response_used: previousResponseUsed,
+        input_start_index: inputStartIndex,
+        input_count: Array.isArray(params?.input) ? params.input.length : 0,
+        input_hash: traceHash(stableTraceStringify(params?.input || [])),
+        request_sans_input_hash: traceHash(stableTraceStringify(requestSansInput)),
+        context_prefix_hash: traceHash(stableTraceStringify(contextShape)),
+        has_instructions: instructions.length > 0,
+        instructions_chars: instructions.length,
+        instructions_hash: instructions ? traceHash(instructions) : null,
+        reasoning_effort: params?.reasoning?.effort || null,
+        tool_count: Array.isArray(rawTools) ? rawTools.length : 0,
+        tool_schema_hash: traceHash(stableTraceStringify(toolShape)),
+        tool_names_hash: traceHash(stableTraceStringify(toolShape.map(t => t?.name || null))),
+        xai_cache_lane_enabled: cacheLane?.enabled === true,
+        xai_cache_lane_hash: cacheLane?.laneKeyHash || null,
+        xai_cache_lane_shard: Number.isFinite(Number(cacheLane?.shard)) ? Number(cacheLane.shard) : null,
+        xai_cache_lane_max_in_flight: Number.isFinite(Number(cacheLane?.maxInFlight)) ? Number(cacheLane.maxInFlight) : null,
+        xai_cache_lane_wait_ms: Number.isFinite(Number(cacheLane?.waitMs)) ? Number(cacheLane.waitMs) : null,
+        xai_cache_lane_queued: cacheLane?.queued === true,
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cached_tokens: cachedTokens,
+        cache_hit_rate: hitRate,
+        mid_turn_cold: midTurnCold,
+    };
+}
+
+function traceXaiResponsesCacheContext(args) {
+    if (!compatCacheTraceEnabled('xai')) return;
+    try {
+        const payload = xaiResponsesFingerprintPayload(args);
+        const sessionId = args?.opts?.sessionId || args?.opts?.session?.id || null;
+        const iteration = Number.isFinite(Number(args?.opts?.iteration)) ? Number(args.opts.iteration) : null;
+        appendBridgeTrace({
+            sessionId,
+            iteration,
+            kind: 'cache_context',
+            ...payload,
+            payload,
+        });
+        if (payload.mid_turn_cold) {
+            const anomalyPayload = {
+                ...payload,
+                anomaly: 'xai_mid_turn_cold_cache',
+                reason: 'previous_response_id_present_but_cached_tokens_low',
+            };
+            appendBridgeTrace({
+                sessionId,
+                iteration,
+                kind: 'cache_anomaly',
+                ...anomalyPayload,
+                payload: anomalyPayload,
+            });
+        }
+    } catch (err) {
+        process.stderr.write(`[compat-cache-trace] xai context trace failed: ${err?.message || err}\n`);
+    }
+}
+
+function writeXaiResponsesCacheTrace({ model, opts, params, rawTools, response, cacheRouting, previousResponseId, inputStartIndex, transport, cacheLane }) {
+    if (!compatCacheTraceEnabled('xai')) return;
+    try {
+        const usage = response?.usage || {};
+        const fingerprint = xaiResponsesFingerprintPayload({
+            model,
+            opts,
+            params,
+            rawTools,
+            response,
+            cacheRouting,
+            previousResponseId,
+            inputStartIndex,
+            transport,
+            cacheLane,
+        });
+        const inputTokens = fingerprint.input_tokens;
+        const cachedTokens = fingerprint.cached_tokens;
+        const toolShape = summarizeTraceTools(rawTools);
+        const trace = {
+            event: 'responses',
+            provider: 'xai',
+            transport: transport || null,
+            model,
+            responseModel: response?.model || null,
+            responseIdHash: response?.id ? traceHash(response.id) : null,
+            previousResponseIdHash: previousResponseId ? traceHash(previousResponseId) : null,
+            owner: opts?.session?.owner || null,
+            role: opts?.session?.role || opts?.role || null,
+            permission: opts?.session?.permission || null,
+            toolPermission: opts?.session?.toolPermission || null,
+            profileId: opts?.session?.profileId || null,
+            sourceType: opts?.session?.sourceType || null,
+            sourceName: opts?.session?.sourceName || null,
+            sessionIdHash: opts?.sessionId ? traceHash(opts.sessionId) : null,
+            promptCacheKeyHash: params?.prompt_cache_key ? traceHash(params.prompt_cache_key) : null,
+            xGrokPromptPrefixHash: cacheRouting?.prefixHash || null,
+            xGrokConvIdMode: cacheRouting?.mode || null,
+            xaiReasoningEffort: params?.reasoning?.effort || null,
+            previousResponseUsed: Boolean(previousResponseId),
+            inputStartIndex,
+            inputCount: Array.isArray(params?.input) ? params.input.length : 0,
+            cacheLaneEnabled: fingerprint.xai_cache_lane_enabled,
+            cacheLaneHash: fingerprint.xai_cache_lane_hash,
+            cacheLaneShard: fingerprint.xai_cache_lane_shard,
+            cacheLaneMaxInFlight: fingerprint.xai_cache_lane_max_in_flight,
+            cacheLaneWaitMs: fingerprint.xai_cache_lane_wait_ms,
+            cacheLaneQueued: fingerprint.xai_cache_lane_queued,
+            input: summarizeResponsesInput(params?.input || []),
+            toolCount: Array.isArray(rawTools) ? rawTools.length : 0,
+            toolSchemaHash: traceHash(stableTraceStringify(toolShape)),
+            toolNamesHash: fingerprint.tool_names_hash,
+            requestSansInputHash: fingerprint.request_sans_input_hash,
+            contextPrefixHash: fingerprint.context_prefix_hash,
+            instructionsHash: fingerprint.instructions_hash,
+            instructionsChars: fingerprint.instructions_chars,
+            usageKeys: Object.keys(usage || {}).sort(),
+            inputTokenDetailsKeys: Object.keys(usage?.input_tokens_details || {}).sort(),
+            outputTokenDetailsKeys: Object.keys(usage?.output_tokens_details || {}).sort(),
+            outputTypes: (response?.output || []).map(item => item?.type || null),
+            inputTokens,
+            outputTokens: fingerprint.output_tokens,
+            cachedTokens,
+            cacheHitRate: fingerprint.cache_hit_rate,
+            midTurnCold: fingerprint.mid_turn_cold,
+            costInUsdTicks: typeof usage.cost_in_usd_ticks === 'number' ? usage.cost_in_usd_ticks : null,
+        };
+        process.stderr.write(`[compat-cache-trace] ${JSON.stringify(trace)}\n`);
+    } catch (err) {
+        process.stderr.write(`[compat-cache-trace] failed: ${err?.message || err}\n`);
+    }
+}
+
+function toOpenAIMessages(messages, providerName) {
+    // NOTE: chat.completions has no equivalent slot for replaying reasoning
+    // encrypted_content the way the Responses API does (no `type:'reasoning'`
+    // input item). Whatever reasoningItems may be attached to assistant
+    // messages by the openai-oauth provider is intentionally dropped here —
+    // strict providers (xai) reject unknown roles/types and would 400 the
+    // request. Documented in v0.1.160 (GPT reasoning replay).
+    //
+    // DeepSeek thinking models require the prior turn's `reasoning_content`
+    // string to be echoed back inside the assistant message, otherwise the API
+    // returns 400. xAI reasoning models also preserve their official multi-turn
+    // shape and cache prefix stability when prior assistant reasoning_content
+    // is replayed; reasoning_effort itself remains caller/user-selected.
+    const replaysReasoningContent = providerName === 'deepseek' || providerName === 'xai';
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'tool') {
+            out.push({
+                role: 'tool',
+                tool_call_id: m.toolCallId || '',
+                content: m.content,
+            });
+            continue;
+        }
+        if (m.role === 'assistant' && m.toolCalls?.length) {
+            const msg = {
+                role: 'assistant',
+                content: m.content || null,
+                tool_calls: m.toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+                })),
+            };
+            if (replaysReasoningContent && m.reasoningContent) msg.reasoning_content = m.reasoningContent;
+            out.push(msg);
+            continue;
+        }
+        if (m.role === 'assistant' && replaysReasoningContent && m.reasoningContent) {
+            out.push({ role: m.role, content: m.content, reasoning_content: m.reasoningContent });
+            continue;
+        }
+        out.push({ role: m.role, content: m.content });
+    }
+    return out;
+}
+function toOpenAITools(tools) {
+    return tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema,
+        },
+    }));
+}
+function toResponsesTools(tools) {
+    return tools.map((t) => ({
+        type: 'function',
+        name: t.name,
+        description: t.description,
+        parameters: t.inputSchema,
+    }));
+}
+function parseToolCalls(choice) {
+    const calls = choice.message?.tool_calls;
+    if (!calls?.length)
+        return undefined;
+    return calls
+        .filter((tc) => tc.type === 'function')
+        .map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: JSON.parse(tc.function.arguments || '{}'),
+    }));
+}
+function parseJsonObject(value) {
+    try {
+        const parsed = JSON.parse(value || '{}');
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+        return {};
+    }
+}
+function parseResponsesToolCalls(response) {
+    const out = [];
+    for (const item of response?.output || []) {
+        if (item?.type !== 'function_call') continue;
+        out.push({
+            id: item.call_id || item.id,
+            name: item.name,
+            arguments: parseJsonObject(item.arguments),
+        });
+    }
+    return out.length ? out : undefined;
+}
+function responseOutputText(response) {
+    if (typeof response?.output_text === 'string') return response.output_text;
+    const chunks = [];
+    for (const item of response?.output || []) {
+        if (item?.type !== 'message' || !Array.isArray(item.content)) continue;
+        for (const part of item.content) {
+            if (part?.type === 'output_text' && typeof part.text === 'string') chunks.push(part.text);
+        }
+    }
+    return chunks.join('');
+}
+function toResponsesInputMessage(m) {
+    if (m.role === 'tool') {
+        return {
+            type: 'function_call_output',
+            call_id: m.toolCallId || '',
+            output: typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? ''),
+        };
+    }
+    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+        const items = [];
+        if (m.content) items.push({ role: 'assistant', content: m.content });
+        for (const tc of m.toolCalls) {
+            items.push({
+                type: 'function_call',
+                call_id: tc.id,
+                name: tc.name,
+                arguments: JSON.stringify(tc.arguments || {}),
+            });
+        }
+        return items;
+    }
+    return { role: m.role, content: m.content || '' };
+}
+function xaiSystemInstructions(messages) {
+    const instructions = (messages || [])
+        .filter(m => m?.role === 'system')
+        .map(m => String(m.content || ''))
+        .filter(Boolean)
+        .join('\n\n');
+    return instructions || undefined;
+}
+function toXaiResponsesInput(messages, providerState, options = {}) {
+    const includeSystem = options.includeSystem !== false;
+    const state = providerState?.xaiResponses || null;
+    let startIndex = 0;
+    const previousResponseId = typeof state?.previousResponseId === 'string' ? state.previousResponseId : null;
+    if (previousResponseId) {
+        const seen = Number.isInteger(state?.seenMessageCount) ? state.seenMessageCount : messages.length;
+        startIndex = Math.max(0, Math.min(seen, messages.length));
+        if (messages[startIndex]?.role === 'assistant') startIndex += 1;
+    }
+    const input = [];
+    for (const m of messages.slice(startIndex)) {
+        if (!includeSystem && m.role === 'system') continue;
+        const converted = toResponsesInputMessage(m);
+        if (Array.isArray(converted)) input.push(...converted);
+        else input.push(converted);
+    }
+    return { input, previousResponseId, startIndex };
+}
+export class OpenAICompatProvider {
+    // Chat Completions prompt_tokens is already the total (includes cached).
+    // Covers grok-oauth and all OPENAI_COMPAT_PRESETS. See registry.mjs.
+    static inputExcludesCache = false;
+    name;
+    client;
+    defaultModel;
+    config;
+    baseURL;
+    apiKey;
+    defaultHeaders;
+    constructor(name, config) {
+        const preset = PRESETS[name];
+        const baseURL = assertSafeBaseURL(config.baseURL || preset?.baseURL || 'http://localhost:8080/v1', name);
+        const apiKey = config.apiKey || 'no-key';
+        this.name = name;
+        this.config = config;
+        this.baseURL = baseURL;
+        this.apiKey = apiKey;
+        // 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
+        // extraHeaders behave exactly as before.
+        this.defaultHeaders = { ...(preset?.extraHeaders || {}), ...(config.extraHeaders || {}) };
+        this.defaultModel = preset?.defaultModel || 'default';
+        this.client = new OpenAI({
+            baseURL,
+            apiKey,
+            defaultHeaders: this.defaultHeaders,
+        });
+    }
+    reloadApiKey() {
+        try {
+            const freshConfig = loadConfig();
+            const cfg = freshConfig.providers?.[this.name];
+            const preset = PRESETS[this.name];
+            const newKey = cfg?.apiKey || this.config.apiKey;
+            const baseURL = assertSafeBaseURL(cfg?.baseURL || this.config.baseURL || preset?.baseURL || 'http://localhost:8080/v1', this.name);
+            if (newKey) {
+                this.config = { ...(this.config || {}), ...(cfg || {}), apiKey: newKey, baseURL };
+                this.baseURL = baseURL;
+                this.apiKey = newKey;
+                this.defaultHeaders = { ...(preset?.extraHeaders || {}), ...(this.config.extraHeaders || {}) };
+                this.client = new OpenAI({
+                    baseURL,
+                    apiKey: newKey,
+                    defaultHeaders: this.defaultHeaders,
+                });
+            }
+        } catch { /* best effort */ }
+    }
+    async send(messages, model, tools, sendOpts) {
+        try {
+            return await this._doSend(messages, model, tools, sendOpts);
+        } catch (err) {
+            if (err.message && (err.message.includes('401') || err.message.includes('403'))) {
+                process.stderr.write(`[provider] Auth error, re-reading config...\n`);
+                this.reloadApiKey();
+                return await this._doSend(messages, model, tools, sendOpts);
+            }
+            throw err;
+        }
+    }
+    async _doSend(messages, model, tools, sendOpts) {
+        const useModel = model || this.defaultModel;
+        const opts = sendOpts || {};
+        if (this.name === 'xai' && useXaiResponsesApi(opts, this.config)) {
+            if (useXaiResponsesWebSocket(opts, this.config)) {
+                return await this._doSendXaiResponsesWebSocket(messages, useModel, tools, opts);
+            }
+            return await this._doSendXaiResponses(messages, useModel, tools, opts);
+        }
+        const signal = opts.signal || null;
+        if (signal?.aborted) {
+            const reason = signal.reason;
+            throw reason instanceof Error ? reason : new Error('OpenAI-compat request aborted by session close');
+        }
+        const params = {
+            model: useModel,
+            messages: toOpenAIMessages(messages, this.name),
+        };
+        if (tools?.length) {
+            params.tools = toOpenAITools(tools);
+        }
+        if (this.name === 'xai') {
+            const reasoningEffort = normalizeXaiReasoningEffort(opts.xaiReasoningEffort
+                ?? opts.effort
+                ?? this.config?.reasoningEffort
+                ?? process.env.MIXDOG_XAI_REASONING_EFFORT);
+            if (reasoningEffort) params.reasoning_effort = reasoningEffort;
+        }
+        const totalSignal = createTimeoutSignal(signal, PROVIDER_GENERATE_TOTAL_TIMEOUT_MS, `${this.name} total`);
+        const cacheRouting = this.name === 'xai'
+            ? xaiCacheRouting(opts, params, tools || [], useModel)
+            : null;
+        const cacheRoutingKey = cacheRouting?.key || null;
+        // Note: x-grok-conv-id is documented as a routing hint, but in our
+        // measured parallel-worker traffic it caused alternating cold caches
+        // (server-side per-conv shard isolation). Vercel ai-sdk and other
+        // reference clients omit it entirely and rely on xAI's automatic
+        // prompt-prefix caching, which holds up to 95%+ hit even across
+        // parallel workers. Keep the header off by default.
+        // Shared retry: deepseek / xai / other compat backends all sit behind
+        // their own load balancers and emit 5xx / "overloaded" under burst
+        // traffic. The withRetry wrapper preserves abort behavior via
+        // mergedSignal and only retries when classifyError() says transient.
+        let response;
+        try {
+            response = await withRetry(
+                ({ signal: attemptSignal }) => this.client.chat.completions.create(params, { signal: attemptSignal }),
+                {
+                    signal: totalSignal.signal,
+                    perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+                    perAttemptLabel: `${this.name} first byte`,
+                    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`);
+                    },
+                },
+            );
+        } finally {
+            totalSignal.cleanup();
+        }
+        const choice = response.choices[0];
+        const toolCalls = choice ? parseToolCalls(choice) : undefined;
+        // Capture finish_reason early so we can refuse to return an
+        // incomplete completion as final content. OpenAI-compat backends use
+        // `length` (max_tokens / model context overflow) and `content_filter`
+        // (moderation cutoff) to flag responses that were terminated before
+        // the model finished its turn — treating those as success silently
+        // surfaces truncated text and lets the loop accept a partial answer.
+        const stopReason = choice?.finish_reason || null;
+        if (stopReason === 'length' || stopReason === 'content_filter') {
+            const err = Object.assign(
+                new Error(`${this.name} response incomplete: finish_reason=${stopReason}`),
+                {
+                    name: 'ProviderIncompleteError',
+                    code: 'PROVIDER_INCOMPLETE',
+                    providerIncomplete: true,
+                    finishReason: stopReason,
+                    partialContent: choice?.message?.content || '',
+                    partialToolCalls: toolCalls,
+                    model: response.model || useModel,
+                    responseId: response.id || null,
+                    rawUsage: response.usage || null,
+                },
+            );
+            throw err;
+        }
+        writeCompatCacheTrace({
+            provider: this.name,
+            model: useModel,
+            opts,
+            params,
+            rawTools: tools || [],
+            response,
+            cacheRoutingKey,
+            cacheRouting,
+        });
+        if (response.usage) {
+            const inputTokens = Number(response.usage.prompt_tokens ?? response.usage.input_tokens ?? 0);
+            const cachedTokens = extractCompatCachedTokens(response.usage);
+            traceBridgeUsage({
+                sessionId: opts.sessionId || opts.session?.id || null,
+                iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
+                inputTokens,
+                outputTokens: Number(response.usage.completion_tokens ?? response.usage.output_tokens ?? 0),
+                cachedTokens,
+                cacheWriteTokens: 0,
+                promptTokens: inputTokens,
+                model: response.model || useModel,
+                modelDisplay: response.model || useModel,
+                responseId: response.id || null,
+                rawUsage: response.usage,
+                provider: this.name,
+            });
+        }
+        // Capture provider reasoning_content so loop.mjs can attach it to the
+        // assistant message and echo it back next turn for providers that
+        // require or benefit from that official multi-turn shape.
+        const capturesReasoningContent = this.name === 'deepseek' || this.name === 'xai';
+        const reasoningContent = (capturesReasoningContent && typeof choice?.message?.reasoning_content === 'string')
+            ? choice.message.reasoning_content
+            : null;
+        return {
+            content: choice?.message?.content || '',
+            model: response.model,
+            toolCalls,
+            stopReason,
+            ...(reasoningContent ? { reasoningContent } : {}),
+            usage: response.usage ? (() => {
+                const input = response.usage.prompt_tokens ?? response.usage.input_tokens ?? 0;
+                const cached = extractCompatCachedTokens(response.usage);
+                // xAI Grok returns the actual billed amount in `cost_in_usd_ticks`
+                // (1 tick = $1e-10, per docs.x.ai). Surface it as costUsd so the
+                // session manager skips the catalog-rate fallback and records the
+                // provider-billed value verbatim.
+                const ticks = response.usage.cost_in_usd_ticks;
+                const costUsd = typeof ticks === 'number' && ticks >= 0
+                    ? Number((ticks * 1e-10).toFixed(8))
+                    : undefined;
+                return {
+                    inputTokens: input,
+                    outputTokens: response.usage.completion_tokens ?? response.usage.output_tokens ?? 0,
+                    cachedTokens: cached,
+                    // Chat Completions prompt_tokens is already the total prompt
+                    // the model ingested (cached is a subset) — alias directly.
+                    promptTokens: input,
+                    raw: { ...response.usage },
+                    ...(costUsd != null ? { costUsd } : {}),
+                };
+            })() : undefined,
+        };
+    }
+    async _doSendXaiResponses(messages, useModel, tools, opts) {
+        const signal = opts.signal || null;
+        if (signal?.aborted) {
+            const reason = signal.reason;
+            throw reason instanceof Error ? reason : new Error('xAI Responses request aborted by session close');
+        }
+        const chatMessagesForTrace = toOpenAIMessages(messages, this.name);
+        const cacheRouting = xaiResponsesCacheRouting(opts, { messages: chatMessagesForTrace }, tools || [], useModel);
+        const { input, previousResponseId, startIndex } = toXaiResponsesInput(messages, opts.providerState);
+        const params = {
+            model: useModel,
+            input,
+            store: true,
+            prompt_cache_key: cacheRouting.key,
+        };
+        if (previousResponseId) params.previous_response_id = previousResponseId;
+        if (tools?.length) params.tools = toResponsesTools(tools);
+        // Non-streaming transport: there are no deltas to report, so without
+        // an explicit stage the session sits on the loop's per-iteration
+        // 'connecting' reset for the whole generation (bridge list shows a
+        // working session as stuck). Report 'requesting' for the in-flight
+        // window and fire one delta on arrival to feed the stall watchdog.
+        try { opts.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
+        const reasoningEffort = normalizeXaiReasoningEffort(opts.xaiReasoningEffort
+            ?? opts.effort
+            ?? this.config?.reasoningEffort
+            ?? process.env.MIXDOG_XAI_REASONING_EFFORT);
+        if (reasoningEffort) params.reasoning = { effort: reasoningEffort };
+        let response;
+        let cacheLane = null;
+        const scheduled = await withXaiResponsesCacheLane({
+            opts,
+            config: this.config,
+            cacheRouting,
+            model: useModel,
+            transport: 'http',
+            previousResponseId,
+            inputCount: Array.isArray(input) ? input.length : 0,
+            signal,
+        }, async (laneMeta) => {
+            cacheLane = laneMeta;
+            const totalSignal = createTimeoutSignal(signal, PROVIDER_GENERATE_TOTAL_TIMEOUT_MS, 'xai responses total');
+            try {
+                return await withRetry(
+                    ({ signal: attemptSignal }) => this.client.responses.create(params, { signal: attemptSignal }),
+                    {
+                        signal: totalSignal.signal,
+                        perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
+                        perAttemptLabel: 'xai responses first byte',
+                        onRetry: ({ attempt, lastErr, delayMs, delayReason }) => {
+                            const delayLabel = Number.isFinite(Number(delayMs)) ? `, delay ${delayMs}ms${delayReason ? ` (${delayReason})` : ''}` : '';
+                            process.stderr.write(`[xai:responses] retry attempt ${attempt + 1} after ${lastErr?.message || lastErr?.code || 'transient error'}${delayLabel}\n`);
+                        },
+                    },
+                );
+            } finally {
+                totalSignal.cleanup();
+            }
+        });
+        response = scheduled.value;
+        cacheLane = cacheLane || scheduled.laneMeta;
+        try { opts.onStreamDelta?.(); } catch { /* heartbeat best-effort */ }
+        const toolCalls = parseResponsesToolCalls(response);
+        writeXaiResponsesCacheTrace({
+            model: useModel,
+            opts,
+            params,
+            rawTools: tools || [],
+            response,
+            cacheRouting,
+            previousResponseId,
+            inputStartIndex: startIndex,
+            transport: 'http',
+            cacheLane,
+        });
+        traceXaiResponsesCacheContext({
+            model: useModel,
+            opts,
+            params,
+            rawTools: tools || [],
+            response,
+            cacheRouting,
+            previousResponseId,
+            inputStartIndex: startIndex,
+            transport: 'http',
+            cacheLane,
+        });
+        if (response.usage) {
+            const inputTokens = Number(response.usage.input_tokens ?? response.usage.prompt_tokens ?? 0);
+            const cachedTokens = extractCompatCachedTokens(response.usage);
+            traceBridgeUsage({
+                sessionId: opts.sessionId || opts.session?.id || null,
+                iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
+                inputTokens,
+                outputTokens: Number(response.usage.output_tokens ?? response.usage.completion_tokens ?? 0),
+                cachedTokens,
+                cacheWriteTokens: 0,
+                promptTokens: inputTokens,
+                model: response.model || useModel,
+                modelDisplay: response.model || useModel,
+                responseId: response.id || null,
+                rawUsage: response.usage,
+                provider: 'xai',
+            });
+        }
+        return {
+            content: responseOutputText(response),
+            model: response.model || useModel,
+            toolCalls,
+            providerState: {
+                ...(opts.providerState || {}),
+                xaiResponses: {
+                    previousResponseId: response.id,
+                    seenMessageCount: Array.isArray(messages) ? messages.length : 0,
+                    model: response.model || useModel,
+                    updatedAt: Date.now(),
+                },
+            },
+            usage: response.usage ? (() => {
+                const inputTokens = response.usage.input_tokens ?? response.usage.prompt_tokens ?? 0;
+                const ticks = response.usage.cost_in_usd_ticks;
+                const costUsd = typeof ticks === 'number' && ticks >= 0
+                    ? Number((ticks * 1e-10).toFixed(8))
+                    : undefined;
+                return {
+                    inputTokens,
+                    outputTokens: response.usage.output_tokens ?? response.usage.completion_tokens ?? 0,
+                    cachedTokens: extractCompatCachedTokens(response.usage),
+                    promptTokens: inputTokens,
+                    raw: { ...response.usage },
+                    ...(costUsd != null ? { costUsd } : {}),
+                };
+            })() : undefined,
+        };
+    }
+    async _doSendXaiResponsesWebSocket(messages, useModel, tools, opts) {
+        const signal = opts.signal || null;
+        if (signal?.aborted) {
+            const reason = signal.reason;
+            throw reason instanceof Error ? reason : new Error('xAI Responses WebSocket request aborted by session close');
+        }
+        const apiKey = this.config?.apiKey || process.env.XAI_API_KEY;
+        if (!apiKey) throw new Error('xAI API key not configured');
+        const chatMessagesForTrace = toOpenAIMessages(messages, this.name);
+        const cacheRouting = xaiResponsesCacheRouting(opts, { messages: chatMessagesForTrace }, tools || [], useModel);
+        const { input, previousResponseId, startIndex } = toXaiResponsesInput(messages, opts.providerState, { includeSystem: false });
+        const params = {
+            model: useModel,
+            input,
+            // xAI's WebSocket continuation is documented for store=false, but
+            // the public endpoint currently returns previous_response_not_found
+            // in our live probes unless the chain is stored.
+            store: true,
+            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
+        // first response already anchors instructions for the continuation.
+        else if (instructions) params.instructions = instructions;
+        if (tools?.length) params.tools = toResponsesTools(tools);
+        const reasoningEffort = normalizeXaiReasoningEffort(opts.xaiReasoningEffort
+            ?? opts.effort
+            ?? this.config?.reasoningEffort
+            ?? process.env.MIXDOG_XAI_REASONING_EFFORT);
+        if (reasoningEffort) params.reasoning = { effort: reasoningEffort };
+        const warmupBody = useXaiResponsesWebSocketWarmup(opts, this.config, {
+            previousResponseId,
+            instructions,
+            rawTools: tools || [],
+        })
+            ? { ...params, generate: false, input: [] }
+            : null;
+        const iteration = Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null;
+        let cacheLane = null;
+        const scheduled = await withXaiResponsesCacheLane({
+            opts,
+            config: this.config,
+            cacheRouting,
+            model: useModel,
+            transport: 'websocket',
+            previousResponseId,
+            inputCount: Array.isArray(input) ? input.length : 0,
+            signal,
+        }, async (laneMeta) => {
+            cacheLane = laneMeta;
+            return await sendViaWebSocket({
+                auth: { type: 'xai', apiKey },
+                body: params,
+                sendOpts: opts,
+                onStreamDelta: typeof opts.onStreamDelta === 'function' ? opts.onStreamDelta : null,
+                onToolCall: typeof opts.onToolCall === 'function' ? opts.onToolCall : null,
+                onStageChange: typeof opts.onStageChange === 'function' ? opts.onStageChange : null,
+                externalSignal: signal,
+                poolKey: opts.sessionId || opts.session?.id || null,
+                cacheKey: cacheRouting.key,
+                iteration,
+                useModel,
+                displayModel: (id) => id,
+                includeResponseId: true,
+                traceProvider: 'xai',
+                logSuppressedReasoningDeltas: false,
+                warmupBody,
+            });
+        });
+        const result = scheduled.value;
+        cacheLane = cacheLane || scheduled.laneMeta;
+        const responseId = result.responseId || previousResponseId || null;
+        const rawUsage = result.usage?.raw || result.usage || null;
+        const traceParams = result.__warmup?.requestBody || params;
+        writeXaiResponsesCacheTrace({
+            model: useModel,
+            opts,
+            params: traceParams,
+            rawTools: tools || [],
+            response: {
+                id: responseId,
+                model: result.model || useModel,
+                output: [],
+                usage: rawUsage,
+            },
+            cacheRouting,
+            previousResponseId,
+            inputStartIndex: startIndex,
+            transport: 'websocket',
+            cacheLane,
+        });
+        traceXaiResponsesCacheContext({
+            model: useModel,
+            opts,
+            params: traceParams,
+            rawTools: tools || [],
+            response: {
+                id: responseId,
+                model: result.model || useModel,
+                output: [],
+                usage: rawUsage,
+            },
+            cacheRouting,
+            previousResponseId,
+            inputStartIndex: startIndex,
+            transport: 'websocket',
+            cacheLane,
+        });
+        const ticks = rawUsage?.cost_in_usd_ticks;
+        const costUsd = typeof ticks === 'number' && ticks >= 0
+            ? Number((ticks * 1e-10).toFixed(8))
+            : undefined;
+        return {
+            content: result.content || '',
+            model: result.model || useModel,
+            toolCalls: result.toolCalls,
+            providerState: {
+                ...(opts.providerState || {}),
+                xaiResponses: {
+                    previousResponseId: responseId,
+                    seenMessageCount: Array.isArray(messages) ? messages.length : 0,
+                    model: result.model || useModel,
+                    updatedAt: Date.now(),
+                    transport: 'websocket',
+                },
+            },
+            usage: result.usage ? {
+                ...result.usage,
+                ...(costUsd != null ? { costUsd } : {}),
+            } : undefined,
+        };
+    }
+    async _fetchModelItems() {
+        const timeout = createTimeoutSignal(null, MODEL_LIST_TIMEOUT_MS, `${this.name} model list`);
+        try {
+            const res = await fetch(`${String(this.baseURL || '').replace(/\/+$/, '')}/models`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey || 'no-key'}`,
+                    ...(this.defaultHeaders || {}),
+                },
+                signal: timeout.signal,
+            });
+            if (!res.ok) throw new Error(`${this.name} models ${res.status}`);
+            const data = await res.json();
+            if (Array.isArray(data?.data)) return data.data;
+            if (Array.isArray(data)) return data;
+            return [];
+        } finally {
+            timeout.cleanup();
+        }
+    }
+    async listModels() {
+        try {
+            const list = await this._fetchModelItems();
+            const models = [];
+            for (const m of list) {
+                models.push({
+                    id: m?.id,
+                    name: m?.id,
+                    provider: this.name,
+                    contextWindow: 0,
+                    created: typeof m?.created === 'number' ? m.created : null,
+                });
+            }
+            return models.filter(m => m.id);
+        }
+        catch {
+            return [];
+        }
+    }
+    async isAvailable() {
+        try {
+            await this._fetchModelItems();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}