mixdog 0.7.17 → 0.8.0

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

@@ -1,1511 +0,0 @@
-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 {
-    consumeCompatChatCompletionStream,
-    consumeCompatResponsesStream,
-    parseCompletedToolCallArgumentsJson,
-} from './openai-compat-stream.mjs';
-import { appendBridgeTrace, traceBridgeUsage } from '../bridge-trace.mjs';
-import { resolveProviderCacheKey } from '../smart-bridge/cache-strategy.mjs';
-import {
-    PROVIDER_FIRST_BYTE_TIMEOUT_MS,
-    PROVIDER_NONSTREAM_TOTAL_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',
-    },
-    // OpenCode Go — low-cost coding-model subscription gateway. The Go
-    // gateway exposes a unified OpenAI-compatible /chat/completions surface
-    // that transparently fronts every Go model (GLM / Kimi / DeepSeek / MiMo
-    // and the anthropic-native MiniMax / Qwen), including tool-calling and
-    // server-side prefix caching (cached_tokens), so no separate Anthropic
-    // transport is needed. Auth is a single OPENCODE_API_KEY (Bearer).
-    // listModels() pulls the live roster from {baseURL}/models.
-    'opencode-go': {
-        baseURL: 'https://opencode.ai/zen/go/v1',
-        defaultModel: 'glm-5.2',
-    },
-    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, label) {
-    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: parseCompletedToolCallArgumentsJson(tc.function.arguments, label),
-    }));
-}
-function parseJsonObject(value) {
-    try {
-        const parsed = JSON.parse(value || '{}');
-        return parsed && typeof parsed === 'object' ? parsed : {};
-    } catch {
-        return {};
-    }
-}
-function parseResponsesToolCalls(response, label) {
-    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: parseCompletedToolCallArgumentsJson(item.arguments, label),
-        });
-    }
-    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_NONSTREAM_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.
-        params.stream = true;
-        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 }),
-                        {
-                            signal: attemptSignal,
-                            perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
-                            perAttemptLabel: `${this.name} first byte`,
-                        },
-                    );
-                    try { opts.onStageChange?.('streaming'); } catch { /* heartbeat best-effort */ }
-                    return consumeCompatChatCompletionStream(stream, {
-                        signal: attemptSignal,
-                        label: this.name,
-                        onStreamDelta: opts.onStreamDelta,
-                        parseToolCalls,
-                    });
-                },
-                {
-                    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`);
-                    },
-                },
-            );
-        } finally {
-            totalSignal.cleanup();
-        }
-        const response = assembled.response;
-        const choice = response.choices[0];
-        const toolCalls = assembled.toolCalls;
-        // 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 assembled.reasoningContent === 'string')
-            ? assembled.reasoningContent
-            : null;
-        return {
-            content: assembled.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);
-        // SSE transport: report 'requesting' until the stream opens, then
-        // per-chunk onStreamDelta feeds the bridge 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 };
-        params.stream = true;
-        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_NONSTREAM_TOTAL_TIMEOUT_MS, 'xai responses total');
-            try {
-                return await withRetry(
-                    async ({ signal: attemptSignal }) => {
-                        const stream = await withRetry(
-                            ({ signal: openSignal }) => this.client.responses.create(params, { signal: openSignal }),
-                            {
-                                signal: attemptSignal,
-                                perAttemptTimeoutMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS,
-                                perAttemptLabel: 'xai responses first byte',
-                            },
-                        );
-                        try { opts.onStageChange?.('streaming'); } catch { /* heartbeat best-effort */ }
-                        return consumeCompatResponsesStream(stream, {
-                            signal: attemptSignal,
-                            label: 'xai:responses',
-                            onStreamDelta: opts.onStreamDelta,
-                            parseResponsesToolCalls,
-                            responseOutputText,
-                        });
-                    },
-                    {
-                        signal: totalSignal.signal,
-                        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();
-            }
-        });
-        const streamed = scheduled.value;
-        response = streamed.response;
-        cacheLane = cacheLane || scheduled.laneMeta;
-        const toolCalls = streamed.toolCalls;
-        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: streamed.content,
-            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;
-        }
-    }
-}