mixdog 0.8.0 → 0.9.0

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

@@ -9,11 +9,11 @@ import {
     parseCompletedToolCallArgumentsJson,
 } from './openai-compat-stream.mjs';
 import { enrichModels, getModelMetadataSync } from './model-catalog.mjs';
-import { appendBridgeTrace, traceBridgeUsage } from '../bridge-trace.mjs';
+import { appendAgentTrace, traceAgentUsage } from '../agent-trace.mjs';
 import {
     resolveProviderCacheKey,
     resolveProviderPromptCacheLane,
-} from '../smart-bridge/cache-strategy.mjs';
+} from '../agent-runtime/cache-strategy.mjs';
 import {
     PROVIDER_FIRST_BYTE_TIMEOUT_MS,
     PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
@@ -23,42 +23,16 @@ import {
 } from '../stall-policy.mjs';
 import { traceHash, stableTraceStringify, summarizeTraceTools, traceTextShape } from './trace-utils.mjs';
 import {
-    contentHasImage,
     normalizeContentForOpenAIChat,
     normalizeContentForOpenAIResponses,
     splitToolContentForOpenAIChat,
     splitToolContentForOpenAIResponses,
 } from './media-normalization.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. GLM / Kimi /
-    // DeepSeek / MiMo use the OpenAI-compatible chat surface; MiniMax / Qwen
-    // use the Anthropic-compatible messages surface. opencode-go.mjs provides
-    // the dual transport while this preset remains the shared base URL/key
-    // source. Auth is a single OPENCODE_API_KEY (Bearer).
-    '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',
-    },
-};
+import {
+    customToolCallFromResponseItem,
+} from './custom-tool-wire.mjs';
+import { OPENAI_COMPAT_PRESETS } from './openai-compat-presets.mjs';
+export { OPENAI_COMPAT_PRESETS } from './openai-compat-presets.mjs';
 const PRESETS = OPENAI_COMPAT_PRESETS;
 const MODEL_LIST_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_COMPAT_MODEL_LIST_TIMEOUT_MS',
@@ -266,6 +240,41 @@ function useXaiResponsesWebSocket(opts, config) {
     return !['0', 'false', 'off', 'http', 'https', 'responses-http', 'sdk'].includes(transport);
 }
 
+function _envFlag(name, fallback = true) {
+    const raw = process.env[name];
+    if (raw == null || raw === '') return fallback;
+    return !['0', 'false', 'off', 'no'].includes(String(raw).toLowerCase());
+}
+
+function _shouldFallbackXaiWsToHttp(err, signal) {
+    if (!_envFlag('MIXDOG_XAI_WS_HTTP_FALLBACK', true)) return false;
+    if (signal?.aborted) return false;
+    if (err?.liveTextEmitted === true) return false;
+    if (err?.emittedToolCall === true || err?.unsafeToRetry === true) return false;
+    const status = Number(err?.httpStatus || err?.status || 0);
+    if (status === 401 || status === 403 || status === 404 || status === 429) return false;
+    if (status >= 500 && status < 600) return true;
+    const code = String(err?.code || '');
+    if (['EWSACQUIRETIMEOUT', 'ETIMEDOUT', 'ESOCKETTIMEDOUT', 'ECONNRESET', 'EAI_AGAIN', 'ENOTFOUND', 'EAI_NODATA', 'ECONNREFUSED', 'ENETUNREACH', 'EHOSTUNREACH', 'EPIPE'].includes(code)) {
+        return true;
+    }
+    const classifier = String(err?.retryClassifier || err?.midstreamClassifier || '');
+    if ([
+        'timeout', 'reset', 'dns', 'refused', 'network', 'acquire_timeout', 'http_5xx',
+        'first_byte_timeout', 'first_meaningful_timeout',
+        'ws_1006', 'ws_1011', 'ws_1012', 'ws_1000', 'ws_4000', 'agent_stall', 'stream_stalled',
+        'response_failed_disconnected', 'response_failed_network', 'response_failed_auth_expired',
+        'ws_send_failed',
+    ].includes(classifier)) {
+        return true;
+    }
+    if (/^http_5\d\d$/.test(classifier)) return true;
+    if (err?.firstByteTimeout) return true;
+    if (err?.firstMeaningfulTimeout) return true;
+    const msg = String(err?.message || '');
+    return /opening handshake has timed out|socket hang up|acquire timed out|no first server event|no meaningful output/i.test(msg);
+}
+
 function useXaiResponsesWebSocketWarmup(opts, config, { previousResponseId, instructions, rawTools }) {
     if (previousResponseId) return false;
     const raw = opts?.xaiResponsesWarmup
@@ -282,7 +291,7 @@ function useXaiResponsesWebSocketWarmup(opts, config, { previousResponseId, inst
     return String(instructions || '').length >= 2048 || (Array.isArray(rawTools) && rawTools.length >= 10);
 }
 
-// Match OpenAI/Codex cache-lane semantics: default to 12 stable shards (via
+// Match OpenAI OAuth/API cache-lane semantics: default to 12 stable shards (via
 // resolveProviderPromptCacheLane) and serialize each final shard. This gives
 // Grok/xAI 10+ worker fanout without concurrent same-key cache contention.
 const XAI_RESPONSES_CACHE_LANE_DEFAULT_MAX_IN_FLIGHT = 1;
@@ -511,7 +520,7 @@ function acquireXaiResponsesCacheLane({ key, maxInFlight, signal, timeoutMs }) {
 function traceXaiCacheLane(opts, payload) {
     if (!compatCacheTraceEnabled('xai')) return;
     try {
-        appendBridgeTrace({
+        appendAgentTrace({
             sessionId: opts?.sessionId || opts?.session?.id || null,
             iteration: Number.isFinite(Number(opts?.iteration)) ? Number(opts.iteration) : null,
             kind: 'cache_lane',
@@ -784,7 +793,7 @@ function traceXaiResponsesCacheContext(args) {
         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({
+        appendAgentTrace({
             sessionId,
             iteration,
             kind: 'cache_context',
@@ -797,7 +806,7 @@ function traceXaiResponsesCacheContext(args) {
                 anomaly: 'xai_mid_turn_cold_cache',
                 reason: 'previous_response_id_present_but_cached_tokens_low',
             };
-            appendBridgeTrace({
+            appendAgentTrace({
                 sessionId,
                 iteration,
                 kind: 'cache_anomaly',
@@ -942,10 +951,6 @@ function toOpenAIMessages(messages, providerName, options = {}) {
     return out;
 }
 
-function messagesHaveImageContent(messages) {
-    return (messages || []).some((m) => contentHasImage(m?.content));
-}
-
 function toOpenAITools(tools) {
     return tools.map((t) => ({
         type: 'function',
@@ -957,14 +962,34 @@ function toOpenAITools(tools) {
     }));
 }
 function toResponsesTools(tools) {
-    return tools.map((t) => ({
-        type: 'function',
-        name: t.name,
-        description: t.description,
-        parameters: t.inputSchema,
-    }));
+    return tools.map((t) => {
+        if (t?.name === 'tool_search') {
+            return {
+                type: 'tool_search',
+                execution: 'client',
+                description: t.description,
+                parameters: t.inputSchema,
+            };
+        }
+        // xAI/Grok Responses rejects the OpenAI-only `type:'custom'` freeform
+        // variant ("unknown variant 'custom'"). Serialize freeform/grammar
+        // tools (e.g. apply_patch) as ordinary function tools instead. Grammar
+        // tools may carry no usable inputSchema, so fall back to a permissive
+        // object schema so grok still registers a valid function tool.
+        return {
+            type: 'function',
+            name: t.name,
+            description: t.description,
+            parameters: t.inputSchema || { type: 'object', additionalProperties: true },
+        };
+    });
 }
-function parseToolCalls(choice, label) {
+function nativeResponsesTools(opts) {
+    return Array.isArray(opts?.nativeTools)
+        ? opts.nativeTools.filter(t => t && typeof t === 'object')
+        : [];
+}
+export function parseToolCalls(choice, label) {
     const calls = choice.message?.tool_calls;
     if (!calls?.length)
         return undefined;
@@ -979,18 +1004,31 @@ function parseToolCalls(choice, label) {
         arguments: parseCompletedToolCallArgumentsJson(tc.function.arguments, label, { id: tc.id, name: tc.function.name, finishReason }),
     }));
 }
-function parseResponsesToolCalls(response, label) {
+export function parseResponsesToolCalls(response, label) {
     const out = [];
     // A Responses tool call is only parsed off a completed/done item, so any
     // malformed-JSON failure here is deterministic, not mid-stream truncation.
     const finishReason = response?.status || 'completed';
     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, { id: item.call_id || item.id, name: item.name, finishReason }),
-        });
+        if (item?.type === 'function_call') {
+            out.push({
+                id: item.call_id || item.id,
+                name: item.name,
+                arguments: parseCompletedToolCallArgumentsJson(item.arguments, label, { id: item.call_id || item.id, name: item.name, finishReason }),
+            });
+        } else if (item?.type === 'custom_tool_call') {
+            const call = customToolCallFromResponseItem(item);
+            if (call) out.push(call);
+        } else if (item?.type === 'tool_search_call') {
+            out.push({
+                id: item.call_id || item.id,
+                name: 'tool_search',
+                arguments: item.arguments && typeof item.arguments === 'object'
+                    ? item.arguments
+                    : parseCompletedToolCallArgumentsJson(item.arguments || '{}', label, { id: item.call_id || item.id, name: 'tool_search', finishReason }),
+                nativeType: 'tool_search_call',
+            });
+        }
     }
     return out.length ? out : undefined;
 }
@@ -1005,9 +1043,71 @@ function responseOutputText(response) {
     }
     return chunks.join('');
 }
-function toResponsesInputMessage(m, pendingToolMedia = null) {
+function collectCompatResponseSearchSources(response) {
+    const citations = [];
+    const webSearchCalls = [];
+    const seen = new Set();
+    const addCitation = (source, fallback = {}) => {
+        if (!source) return;
+        if (typeof source === 'string') {
+            const url = source.trim();
+            if (!url || seen.has(url)) return;
+            seen.add(url);
+            citations.push({ title: url, url, snippet: '', source: fallback.source || 'citation', provider: 'xai' });
+            return;
+        }
+        if (typeof source !== 'object') return;
+        const url = String(
+            source.url
+            || source.uri
+            || source.href
+            || source.source_url
+            || source.url_citation?.url
+            || '',
+        ).trim();
+        if (!url || seen.has(url)) return;
+        seen.add(url);
+        citations.push({
+            title: String(source.title || source.name || source.query || source.url_citation?.title || fallback.title || url).trim(),
+            url,
+            snippet: String(source.snippet || source.text || source.description || '').trim(),
+            source: source.source || fallback.source || 'citation',
+            provider: source.provider || 'xai',
+        });
+    };
+    for (const citation of Array.isArray(response?.citations) ? response.citations : []) addCitation(citation);
+    for (const item of Array.isArray(response?.output) ? response.output : []) {
+        if (item?.type === 'web_search_call') {
+            webSearchCalls.push({ id: item.id || '', status: item.status || '', action: item.action || null });
+            const action = item.action || {};
+            for (const source of Array.isArray(action.sources) ? action.sources : []) addCitation(source, { title: action.query || '', source: 'web_search_call' });
+            if (action.url) addCitation({ url: action.url, title: action.query || '' }, { source: 'web_search_call' });
+            for (const url of Array.isArray(action.urls) ? action.urls : []) addCitation({ url, title: action.query || '' }, { source: 'web_search_call' });
+        }
+        for (const citation of Array.isArray(item?.citations) ? item.citations : []) addCitation(citation);
+        for (const part of Array.isArray(item?.content) ? item.content : []) {
+            for (const annotation of Array.isArray(part?.annotations) ? part.annotations : []) {
+                addCitation(annotation, { source: 'annotation' });
+            }
+        }
+    }
+    return { citations, webSearchCalls };
+}
+function toResponsesInputMessage(m, pendingToolMedia = null, customToolCallNameById = null) {
     if (m.role === 'tool') {
+        if (Array.isArray(m.nativeToolSearch?.openaiTools)) {
+            return {
+                type: 'tool_search_output',
+                call_id: m.toolCallId || '',
+                status: 'completed',
+                execution: 'client',
+                tools: m.nativeToolSearch.openaiTools,
+            };
+        }
         const { output, mediaContent } = splitToolContentForOpenAIResponses(m.content);
+        // xai path: never emit `custom_tool_call_output` (the `custom` variant
+        // is rejected by grok). Replay prior tool outputs as the standard
+        // `function_call_output` item regardless of original native type.
         const item = {
             type: 'function_call_output',
             call_id: m.toolCallId || '',
@@ -1020,12 +1120,25 @@ function toResponsesInputMessage(m, pendingToolMedia = null) {
         const items = [];
         if (m.content) items.push({ role: 'assistant', content: normalizeContentForOpenAIResponses(m.content, { role: 'assistant' }) });
         for (const tc of m.toolCalls) {
-            items.push({
-                type: 'function_call',
-                call_id: tc.id,
-                name: tc.name,
-                arguments: JSON.stringify(tc.arguments || {}),
-            });
+            if (tc.nativeType === 'tool_search_call' || tc.name === 'tool_search') {
+                items.push({
+                    type: 'tool_search_call',
+                    call_id: tc.id,
+                    execution: 'client',
+                    arguments: tc.arguments || {},
+                });
+            } else {
+                // xai path: prior native `custom_tool_call` history is replayed
+                // as a standard `function_call` (grok rejects the `custom`
+                // variant). tc.arguments already holds the recovered object
+                // form, so the same stringify path as regular calls applies.
+                items.push({
+                    type: 'function_call',
+                    call_id: tc.id,
+                    name: tc.name,
+                    arguments: JSON.stringify(tc.arguments || {}),
+                });
+            }
         }
         return items;
     }
@@ -1062,6 +1175,7 @@ function toXaiResponsesInput(messages, providerState, options = {}) {
     }
     const input = [];
     const pendingToolMedia = [];
+    const customToolCallNameById = new Map();
     const flushToolMedia = () => {
         if (!pendingToolMedia.length) return;
         input.push({ role: 'user', content: pendingToolMedia.splice(0) });
@@ -1069,7 +1183,7 @@ function toXaiResponsesInput(messages, providerState, options = {}) {
     for (const m of messages.slice(startIndex)) {
         if (!includeSystem && m.role === 'system') continue;
         if (m.role !== 'tool') flushToolMedia();
-        const converted = toResponsesInputMessage(m, pendingToolMedia);
+        const converted = toResponsesInputMessage(m, pendingToolMedia, customToolCallNameById);
         if (Array.isArray(converted)) input.push(...converted);
         else input.push(converted);
     }
@@ -1145,8 +1259,35 @@ export class OpenAICompatProvider {
         const useModel = model || this.defaultModel;
         const opts = sendOpts || {};
         if (this.name === 'xai' && useXaiResponsesApi(opts, this.config)) {
-            if (useXaiResponsesWebSocket(opts, this.config) && !messagesHaveImageContent(messages)) {
-                return await this._doSendXaiResponsesWebSocket(messages, useModel, tools, opts);
+            if (useXaiResponsesWebSocket(opts, this.config)) {
+                try {
+                    return await this._doSendXaiResponsesWebSocket(messages, useModel, tools, opts);
+                } catch (err) {
+                    if (_shouldFallbackXaiWsToHttp(err, opts.signal)) {
+                        const reason = err?.midstreamClassifier || err?.retryClassifier || err?.code || err?.message || 'ws_failed';
+                        process.stderr.write(`[xai:responses] WebSocket unhealthy (${reason}); falling back to HTTP/SSE\n`);
+                        try {
+                            appendAgentTrace({
+                                sessionId: opts?.sessionId || opts?.session?.id || null,
+                                iteration: Number.isFinite(Number(opts?.iteration)) ? Number(opts.iteration) : null,
+                                kind: 'transport_fallback',
+                                provider: 'xai',
+                                model: useModel,
+                                transport: 'http',
+                                payload: {
+                                    from: 'websocket',
+                                    to: 'http',
+                                    reason,
+                                    error_code: err?.code || null,
+                                    error_http_status: Number(err?.httpStatus || 0) || null,
+                                    error_classifier: err?.retryClassifier || err?.midstreamClassifier || null,
+                                },
+                            });
+                        } catch {}
+                        return await this._doSendXaiResponses(messages, useModel, tools, opts);
+                    }
+                    throw err;
+                }
             }
             return await this._doSendXaiResponses(messages, useModel, tools, opts);
         }
@@ -1283,7 +1424,7 @@ export class OpenAICompatProvider {
         if (response.usage) {
             const inputTokens = Number(response.usage.prompt_tokens ?? response.usage.input_tokens ?? 0);
             const cachedTokens = extractCompatCachedTokens(response.usage);
-            traceBridgeUsage({
+            traceAgentUsage({
                 sessionId: opts.sessionId || opts.session?.id || null,
                 iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
                 inputTokens,
@@ -1357,9 +1498,10 @@ export class OpenAICompatProvider {
             prompt_cache_key: cacheRouting.key,
         };
         if (previousResponseId) params.previous_response_id = previousResponseId;
-        if (tools?.length) params.tools = toResponsesTools(tools);
+        const nativeTools = nativeResponsesTools(opts);
+        if (tools?.length || nativeTools.length) params.tools = [...nativeTools, ...toResponsesTools(tools || [])];
         // SSE transport: report 'requesting' until the stream opens, then
-        // per-chunk onStreamDelta feeds the bridge stall watchdog.
+        // per-chunk onStreamDelta feeds the agent stall watchdog.
         try { opts.onStageChange?.('requesting'); } catch { /* heartbeat best-effort */ }
         const reasoningEffort = normalizeXaiReasoningEffort(opts.xaiReasoningEffort
             ?? opts.effort
@@ -1453,7 +1595,7 @@ export class OpenAICompatProvider {
         if (response.usage) {
             const inputTokens = Number(response.usage.input_tokens ?? response.usage.prompt_tokens ?? 0);
             const cachedTokens = extractCompatCachedTokens(response.usage);
-            traceBridgeUsage({
+            traceAgentUsage({
                 sessionId: opts.sessionId || opts.session?.id || null,
                 iteration: Number.isFinite(Number(opts.iteration)) ? Number(opts.iteration) : null,
                 inputTokens,
@@ -1469,11 +1611,14 @@ export class OpenAICompatProvider {
             });
         }
         const nextPreviousResponseId = streamed.stopReason === 'length' ? null : response.id;
+        const searchSources = collectCompatResponseSearchSources(response);
         return {
             content: streamed.content,
             model: response.model || useModel,
             toolCalls,
             stopReason: streamed.stopReason || null,
+            citations: searchSources.citations.length ? searchSources.citations : undefined,
+            webSearchCalls: searchSources.webSearchCalls.length ? searchSources.webSearchCalls : undefined,
             providerState: {
                 ...(opts.providerState || {}),
                 xaiResponses: {
@@ -1529,7 +1674,8 @@ export class OpenAICompatProvider {
         // 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 nativeTools = nativeResponsesTools(opts);
+        if (tools?.length || nativeTools.length) params.tools = [...nativeTools, ...toResponsesTools(tools || [])];
         const reasoningEffort = normalizeXaiReasoningEffort(opts.xaiReasoningEffort
             ?? opts.effort
             ?? this.config?.reasoningEffort
@@ -1640,6 +1786,8 @@ export class OpenAICompatProvider {
                 ...result.usage,
                 ...(costUsd != null ? { costUsd } : {}),
             } : undefined,
+            citations: Array.isArray(result.citations) && result.citations.length ? result.citations : undefined,
+            webSearchCalls: Array.isArray(result.webSearchCalls) && result.webSearchCalls.length ? result.webSearchCalls : undefined,
         };
     }
     async _fetchModelItems() {
@@ -1717,3 +1865,6 @@ export class OpenAICompatProvider {
         return null;
     }
 }
+
+export const _toResponsesToolsForTest = toResponsesTools;
+export const _toXaiResponsesInputForTest = toXaiResponsesInput;