@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/openai-chat.js

@@ -0,0 +1,782 @@
+/**
+ * OpenAI Chat Completions TransportSSE streaming implementation.
+ *
+ * Covers all OpenAI-compatible providers:
+ *   DeepSeek, Qwen, Minimax, Moonshot, OpenRouter, etc.
+ *
+ * POST {baseUrl}/v1/chat/completions with stream: true
+ * Auth: Authorization: Bearer {apiKey}
+ *
+ * SSE format: lines prefixed with "data: ", JSON parsing per event.
+ *
+ * Adapted from admin-infer-proxy-client.ts SSE logic + Hermes openai_chat.py transport.
+ */
+import { MEDIA_MAX_UPLOAD_SIZE } from "../constants.js";
+import { isLocalUrl, resolveMediaUrl, resolveMediaUrlViaUpload } from "./media-resolve.js";
+import { DEFAULT_MAX_RETRIES, STREAM_IDLE_TIMEOUT_MS, retryDelay, retrySleep, extractHttpStatus, isTransientStatus, } from "../retry.js";
+import { isGPT5xModel, isGPT5NanoModel, isOpenAIReasoningModel } from "../model-detection.js";
+export class OpenAIChatTransport {
+    baseUrl;
+    extraHeaders;
+    timeoutMs;
+    supportsStreamOptions;
+    omitZeroTemperature;
+    quirks;
+    fileUploadAdapter;
+    // MiniMax cumulative streaming state (鎼?.7): reasoning_details and content
+    // are delivered as full accumulated strings, not incremental deltas.
+    // Reset at the start of each stream() call.
+    cumulativeReasoningLen = 0;
+    cumulativeContentLen = 0;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error("OpenAIChatTransport: baseUrl is required (got empty or undefined)");
+        }
+        // Strip trailing slash
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.extraHeaders = config.extraHeaders ?? {};
+        this.timeoutMs = config.timeoutMs ?? 180_000;
+        this.supportsStreamOptions = config.supportsStreamOptions ?? true;
+        this.omitZeroTemperature = config.omitZeroTemperature ?? false;
+        this.quirks = config.quirks ?? {};
+        this.fileUploadAdapter = config.fileUploadAdapter;
+    }
+    async *stream(request, apiKey, signal) {
+        // Reset cumulative state for MiniMax reasoning_split streaming
+        this.cumulativeReasoningLen = 0;
+        this.cumulativeContentLen = 0;
+        // Prefix completion (DeepSeek Beta): switch to /beta endpoint
+        const useBeta = request.prefixMessage && this.quirks.supportsPrefixCompletion;
+        // altcode parity: detect version suffix in baseUrl (e.g. /v4) to avoid doubling
+        const hasVersionInBase = /\/v\d+$/.test(this.baseUrl);
+        let url;
+        if (useBeta) {
+            url = `${this.baseUrl}/beta/v1/chat/completions`;
+        }
+        else if (hasVersionInBase) {
+            url = `${this.baseUrl}/chat/completions`;
+        }
+        else {
+            url = `${this.baseUrl}/v1/chat/completions`;
+        }
+        const body = {
+            model: request.model,
+            messages: convertMessagesForOpenAI(await resolveMessagesMedia(request.messages, this.fileUploadAdapter, apiKey, signal), this.quirks),
+            stream: true,
+        };
+        // stream_options: supported by most providers, but some reject it
+        if (this.supportsStreamOptions) {
+            body.stream_options = { include_usage: true };
+        }
+        if (request.tools && request.tools.length > 0) {
+            body.tools = request.tools;
+            if (request.toolChoice)
+                body.tool_choice = request.toolChoice;
+        }
+        // Inject builtin tools only when user sends function tools.
+        // Provider builtins and system function tools COEXISTthey use different schema types:
+        //   GLM:       { type: "web_search", web_search: { enable: true } }   vs  { type: "function", function: { name: "web_search" } }
+        //   Kimi:      { type: "builtin_function", function: { name: "$web_search" } }
+        //   Volcengine: { type: "web_search" } (Responses API)
+        // The LLM uses provider builtins for fast inline search (during inference, transparent),
+        // and system tools for explicit deep/structured search (agent executes, returns results).
+        // T15: session-level toggle via request.disableBuiltinTools
+        const injectBuiltins = !request.disableBuiltinTools;
+        let kimiWebSearchInjected = false;
+        if (injectBuiltins && this.quirks.builtinWebSearch && body.tools) {
+            const tools = body.tools;
+            if (this.quirks.builtinCodeInterpreter) {
+                // GLM native format
+                tools.push({ type: "web_search", web_search: { enable: true, search_result: true } });
+            }
+            else {
+                // Kimi format (kimi-ProviderMax 鎼?3.2: builtin_function.$web_search)
+                tools.push({ type: "builtin_function", function: { name: "$web_search" } });
+                kimiWebSearchInjected = true;
+            }
+        }
+        if (injectBuiltins && this.quirks.builtinCodeInterpreter && body.tools) {
+            const tools = body.tools;
+            tools.push({ type: "code_interpreter", code_interpreter: { sandbox: "none" } });
+        }
+        // GLM: enable tool_stream for incremental tool call argument streaming
+        if (this.quirks.supportsToolStream && body.tools) {
+            body.tool_stream = true;
+        }
+        // DeepSeek V4 thinking mode: thinking + reasoning_effort as top-level params,
+        // temperature must be suppressed (ignored by API but wasteful to send).
+        const isDeepSeekThinking = this.quirks.useEffortInsteadOfBudget && !!request.reasoning;
+        // Kimi K2.6: immutable sampling paramstemperature always omitted (kimi-ProviderMax 鎼?)
+        const isKimiK26 = request.model.startsWith("kimi-k2.6");
+        // GPT-5.x: temperature allowed even with reasoning (openai-ProviderMax 鎼?)
+        const isGPT5x = isGPT5xModel(request.model);
+        if (request.temperature !== undefined) {
+            // Some providers (e.g. Moonshot/Kimi) reject temperature=0
+            if (!(this.omitZeroTemperature && request.temperature === 0)) {
+                // o-series reasoning models, DeepSeek thinking, Kimi K2.6 suppress temperature.
+                // GPT-5.x explicitly allows temperature with reasoning.
+                if (isGPT5x || (!isOpenAIReasoningModel(request.model) && !isDeepSeekThinking && !isKimiK26)) {
+                    body.temperature = request.temperature;
+                }
+            }
+        }
+        if (request.topP !== undefined) {
+            if (isGPT5x || (!isOpenAIReasoningModel(request.model) && !isDeepSeekThinking && !isKimiK26)) {
+                body.top_p = request.topP;
+            }
+        }
+        if (request.maxTokens !== undefined) {
+            // GPT-5.x, o-series, and Kimi K2 use max_completion_tokens (openai-ProviderMax 鎼?, kimi-ProviderMax 鎼?.12)
+            if (isGPT5x || isOpenAIReasoningModel(request.model) || request.model.startsWith("kimi-k2")) {
+                body.max_completion_tokens = request.maxTokens;
+            }
+            else {
+                body.max_tokens = request.maxTokens;
+            }
+        }
+        if (request.reasoning) {
+            if (isGPT5x) {
+                // GPT-5.x: use reasoning object with effort (supports none/low/medium/high/xhigh)
+                // openai-ProviderMax 鎼?: unified reasoning effort for all 5.x models.
+                let effort = request.reasoning.effort === "minimal" ? "none" : request.reasoning.effort;
+                // gpt-5.4-nano only supports up to medium effort (openai-ProviderMax 鎼?)
+                if (isGPT5NanoModel(request.model) && (effort === "high" || effort === "xhigh")) {
+                    effort = "medium";
+                }
+                body.reasoning = { effort };
+            }
+            else if (isOpenAIReasoningModel(request.model)) {
+                // OpenAI o-series (legacy): reasoning_effort as flat string
+                body.reasoning_effort = request.reasoning.effort;
+            }
+            else if (this.quirks.useEffortInsteadOfBudget) {
+                // DeepSeek V4 OpenAI format: thinking + reasoning_effort as top-level body params.
+                body.thinking = { type: "enabled" };
+                const cap = this.quirks.maxReasoningEffort ?? "high";
+                const effortInput = request.reasoning.effort ?? "high";
+                body.reasoning_effort = effortInput === "low" || effortInput === "medium"
+                    ? "high"
+                    : cap;
+            }
+            else if (this.quirks.supportsThinkingParam) {
+                if (kimiWebSearchInjected) {
+                    // kimi-ProviderMax 鎼?3.4: $web_search requires thinking disabled
+                    body.thinking = { type: "disabled" };
+                }
+                else if (this.quirks.supportsToolStream) {
+                    // GLM (zhipu-openai): thinking.type = "enabled"/"disabled" + clear_thinking
+                    // 鎼?.2/鎼?.5 of zhipu-ProviderMax.md
+                    body.thinking = { type: "enabled", clear_thinking: false };
+                }
+                else {
+                    // Kimi K2: thinking.type = "enabled" (kimi-ProviderMax 鎼?/鎼?.6)
+                    body.thinking = { type: "enabled" };
+                }
+                if (this.quirks.supportsReasoningEffort) {
+                    body.reasoning_effort = request.reasoning.effort;
+                }
+            }
+            else if (this.quirks.supportsReasoningEffort) {
+                body.reasoning_effort = request.reasoning.effort;
+            }
+            else {
+                // Generic pass-through
+                body.reasoning = request.reasoning;
+            }
+        }
+        else if (kimiWebSearchInjected) {
+            // kimi-ProviderMax 鎼?3.4: explicitly disable thinking when web search is active
+            body.thinking = { type: "disabled" };
+        }
+        else if (this.quirks.supportsThinkingParam && this.quirks.disableThinkingByDefault) {
+            body.thinking = { type: "disabled" };
+        }
+        // Structured output / JSON mode (kimi-ProviderMax 鎼?8, volcengine-ProviderMax 鎼?6)
+        if (request.structuredOutput) {
+            if (request.structuredOutput.mode === "json_object") {
+                body.response_format = { type: "json_object" };
+            }
+            else if (request.structuredOutput.mode === "json_schema") {
+                body.response_format = {
+                    type: "json_schema",
+                    json_schema: {
+                        name: request.structuredOutput.name,
+                        strict: request.structuredOutput.strict ?? true,
+                        schema: request.structuredOutput.schema,
+                    },
+                };
+            }
+        }
+        // MiniMax reasoning_split: split thinking into reasoning_details field (minimax-ProviderMax 鎼?.5)
+        if (this.quirks.supportsReasoningSplit && request.reasoning) {
+            body.reasoning_split = true;
+        }
+        // GPT-5.x Predicted Output: speculative decoding for code editing (openai-ProviderMax 鎼?1)
+        if (request.prediction && isGPT5x) {
+            body.prediction = request.prediction;
+        }
+        // Prefix completion (DeepSeek Beta): append assistant message with prefix: true
+        if (useBeta && request.prefixMessage) {
+            const msgs = body.messages;
+            msgs.push({
+                role: "assistant",
+                content: request.prefixMessage,
+                prefix: true,
+            });
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+            ...this.extraHeaders,
+        };
+        // Retry loop with exponential backoff (CC withRetry parity)
+        let lastError = null;
+        for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
+            if (signal?.aborted)
+                throw new Error("Request aborted");
+            if (attempt > 0 && lastError) {
+                await retrySleep(retryDelay(attempt), signal);
+            }
+            try {
+                yield* this.fetchAndStream(url, headers, body, signal);
+                return; // Success
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                const isIdleTimeout = lastError.message.includes("Stream idle timeout");
+                if (!isTransientStatus(extractHttpStatus(lastError)) && !isIdleTimeout)
+                    throw lastError;
+                if (attempt === DEFAULT_MAX_RETRIES)
+                    throw lastError;
+            }
+        }
+    }
+    async *fetchAndStream(url, headers, body, signal) {
+        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+        const combinedSignal = signal
+            ? AbortSignal.any([signal, timeoutSignal])
+            : timeoutSignal;
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: combinedSignal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            const err = new Error(`LLM API error ${response.status}: ${errorBody.slice(0, 500)}`);
+            err.status = response.status;
+            throw err;
+        }
+        if (!response.body) {
+            throw new Error("LLM API returned no response body");
+        }
+        // altcode parity: some providers ignore stream:true and return plain JSON.
+        // Detect via Content-Type header and synthesize stream events.
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json") && !contentType.includes("text/event-stream")) {
+            yield* this.handleNonStreamingResponse(response);
+            return;
+        }
+        yield* this.parseSSEStreamWithWatchdog(response.body);
+    }
+    /**
+     * Handle non-streaming JSON response from providers that ignore stream:true.
+     * Synthesize the same LLMChunk events a streaming response would produce.
+     */
+    async *handleNonStreamingResponse(response) {
+        const data = await response.json();
+        // Synthesize usage (faithfully parse nested detailssame fields as streaming path)
+        if (data.usage) {
+            yield {
+                type: "usage",
+                promptTokens: data.usage.prompt_tokens ?? 0,
+                completionTokens: data.usage.completion_tokens ?? 0,
+                reasoningTokens: data.usage.completion_tokens_details?.reasoning_tokens,
+                cacheReadTokens: data.usage.prompt_tokens_details?.cached_tokens,
+            };
+        }
+        for (const choice of data.choices ?? []) {
+            const msg = choice.message;
+            if (!msg)
+                continue;
+            if (msg.reasoning_content) {
+                yield { type: "reasoning_delta", text: msg.reasoning_content };
+            }
+            if (msg.content) {
+                yield { type: "delta", text: msg.content };
+            }
+            if (msg.tool_calls) {
+                for (let i = 0; i < msg.tool_calls.length; i++) {
+                    const tc = msg.tool_calls[i];
+                    yield {
+                        type: "tool_call_delta",
+                        index: i,
+                        id: tc.id,
+                        name: tc.function.name,
+                        arguments: tc.function.arguments,
+                    };
+                }
+            }
+            if (choice.finish_reason) {
+                yield { type: "done", finishReason: choice.finish_reason };
+            }
+        }
+    }
+    /**
+     * Parse SSE stream with 90s idle watchdog (CC parity).
+     * If no data arrives within STREAM_IDLE_TIMEOUT_MS, throw to trigger retry.
+     */
+    async *parseSSEStreamWithWatchdog(body) {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let idleTimer = null;
+        const abortController = new AbortController();
+        const resetIdleTimer = () => {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                abortController.abort();
+            }, STREAM_IDLE_TIMEOUT_MS);
+        };
+        try {
+            resetIdleTimer();
+            const reader = body.getReader();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (abortController.signal.aborted) {
+                        throw new Error("Stream idle timeout");
+                    }
+                    resetIdleTimer();
+                    buffer += decoder.decode(value, { stream: true });
+                    let newlineIdx;
+                    while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                        const line = buffer.slice(0, newlineIdx).trim();
+                        buffer = buffer.slice(newlineIdx + 1);
+                        if (!line)
+                            continue;
+                        if (line.startsWith(":"))
+                            continue;
+                        if (!line.startsWith("data: "))
+                            continue;
+                        const data = line.slice(6);
+                        if (data === "[DONE]")
+                            return;
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(data);
+                        }
+                        catch {
+                            continue;
+                        }
+                        yield* this.processChunk(parsed);
+                    }
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        finally {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+        }
+    }
+    *processChunk(chunk) {
+        // Usage chunk (often sent at the end with stream_options)
+        if (chunk.usage) {
+            yield {
+                type: "usage",
+                promptTokens: chunk.usage.prompt_tokens ?? 0,
+                completionTokens: chunk.usage.completion_tokens ?? 0,
+                reasoningTokens: chunk.usage.completion_tokens_details?.reasoning_tokens,
+                cacheReadTokens: chunk.usage.prompt_tokens_details?.cached_tokens,
+            };
+        }
+        if (!chunk.choices || chunk.choices.length === 0)
+            return;
+        for (const choice of chunk.choices) {
+            const delta = choice.delta;
+            if (!delta)
+                continue;
+            // Reasoning content (DeepSeek-R1 style)
+            if (delta.reasoning_content) {
+                yield { type: "reasoning_delta", text: delta.reasoning_content };
+            }
+            // MiniMax reasoning_split: reasoning_details is cumulative (鎼?.7)
+            if (delta.reasoning_details) {
+                const newPart = delta.reasoning_details.slice(this.cumulativeReasoningLen);
+                if (newPart) {
+                    this.cumulativeReasoningLen = delta.reasoning_details.length;
+                    yield { type: "reasoning_delta", text: newPart };
+                }
+            }
+            // Text contentMiniMax cumulative mode diff (鎼?.7)
+            if (delta.content) {
+                if (this.quirks.supportsReasoningSplit) {
+                    // MiniMax: content is cumulative string, extract only new portion
+                    const newPart = delta.content.slice(this.cumulativeContentLen);
+                    if (newPart) {
+                        this.cumulativeContentLen = delta.content.length;
+                        yield { type: "delta", text: newPart };
+                    }
+                }
+                else {
+                    yield { type: "delta", text: delta.content };
+                }
+            }
+            // Tool call deltas
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    yield {
+                        type: "tool_call_delta",
+                        index: tc.index,
+                        id: tc.id,
+                        name: tc.function?.name,
+                        arguments: tc.function?.arguments ?? "",
+                    };
+                }
+            }
+            // Finish reason
+            if (choice.finish_reason) {
+                // Map GLM-specific finish_reasons to standard values
+                // GLM returns: sensitive (content filtered), network_error, model_context_window_exceeded
+                const mapped = mapFinishReason(choice.finish_reason);
+                yield { type: "done", finishReason: mapped };
+            }
+        }
+    }
+    // 鈹€鈹€ FIM (Fill-In-Middle) CompletionDeepSeek Beta API 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * FIM completion via /beta/v1/completions.
+     * Only works with DeepSeek (requires supportsPrefixCompletion quirk).
+     * Non-thinking mode only; max completion 4K tokens.
+     */
+    async *complete(request, apiKey, signal) {
+        if (!this.quirks.supportsPrefixCompletion) {
+            throw new Error("FIM completion is not supported by this provider");
+        }
+        const hasVersionInBase = /\/v\d+$/.test(this.baseUrl);
+        const url = hasVersionInBase
+            ? `${this.baseUrl}/beta/completions`
+            : `${this.baseUrl}/beta/v1/completions`;
+        const body = {
+            model: request.model,
+            prompt: request.prompt,
+            stream: true,
+            max_tokens: request.maxTokens ?? 4096,
+        };
+        if (request.suffix)
+            body.suffix = request.suffix;
+        if (request.temperature !== undefined)
+            body.temperature = request.temperature;
+        if (request.stop)
+            body.stop = request.stop;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+            ...this.extraHeaders,
+        };
+        const timeoutSignal = AbortSignal.timeout(this.timeoutMs);
+        const combinedSignal = signal
+            ? AbortSignal.any([signal, timeoutSignal])
+            : timeoutSignal;
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: combinedSignal,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            throw new Error(`FIM API error ${response.status}: ${errorBody.slice(0, 500)}`);
+        }
+        if (!response.body)
+            throw new Error("FIM API returned no response body");
+        const decoder = new TextDecoder();
+        let buffer = "";
+        const reader = response.body.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let newlineIdx;
+                while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, newlineIdx).trim();
+                    buffer = buffer.slice(newlineIdx + 1);
+                    if (!line || line.startsWith(":") || !line.startsWith("data: "))
+                        continue;
+                    const data = line.slice(6);
+                    if (data === "[DONE]")
+                        return;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(data);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const choice of parsed.choices ?? []) {
+                        if (choice.text)
+                            yield { type: "delta", text: choice.text };
+                        if (choice.finish_reason)
+                            yield { type: "done", finishReason: choice.finish_reason };
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    // 鈹€鈹€ #28: Kimi File UploadPOST /v1/files 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * Upload a file for use in conversations (Kimi File API).
+     * Returns a file_id that can be referenced in user messages.
+     * POST /v1/files with multipart/form-data.
+     */
+    async uploadFile(fileBlob, filename, purpose, apiKey, signal) {
+        const hasVersionInBase = /\/v\d+$/.test(this.baseUrl);
+        const url = hasVersionInBase
+            ? `${this.baseUrl}/files`
+            : `${this.baseUrl}/v1/files`;
+        const formData = new FormData();
+        formData.append("file", fileBlob, filename);
+        formData.append("purpose", purpose);
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                ...this.extraHeaders,
+            },
+            body: formData,
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => "");
+            throw new Error(`File upload error ${res.status}: ${errText}`);
+        }
+        const data = await res.json();
+        return {
+            fileId: data.id ?? "",
+            filename: data.filename ?? filename,
+            bytes: data.bytes ?? 0,
+        };
+    }
+    /**
+     * Get file content/statusGET /v1/files/{file_id}
+     */
+    async getFileInfo(fileId, apiKey, signal) {
+        const hasVersionInBase = /\/v\d+$/.test(this.baseUrl);
+        const url = hasVersionInBase
+            ? `${this.baseUrl}/files/${encodeURIComponent(fileId)}`
+            : `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                ...this.extraHeaders,
+            },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => "");
+            throw new Error(`File info error ${res.status}: ${errText}`);
+        }
+        const data = await res.json();
+        return {
+            id: data.id ?? fileId,
+            filename: data.filename ?? "",
+            bytes: data.bytes ?? 0,
+            status: data.status ?? "unknown",
+        };
+    }
+}
+/**
+ * Map provider-specific finish_reason values to standard OpenAI values.
+ * GLM-specific: sensitive 閳?content_filter, model_context_window_exceeded 閳?length
+ */
+function mapFinishReason(reason) {
+    switch (reason) {
+        case "sensitive":
+            return "content_filter";
+        case "model_context_window_exceeded":
+            return "length";
+        case "network_error":
+            return "error";
+        default:
+            return reason;
+    }
+}
+// 鈹€鈹€ Message Conversion 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Pre-resolve local media URLs to base64 data URLs.
+ * Images and videos are left as-is (providers accept URLs and fetch server-side).
+ * Audio must always be base64-encoded (OpenAI input_audio.data requirement).
+ */
+async function resolveMessagesMedia(messages, uploadAdapter, apiKey, signal) {
+    const needsResolution = messages.some((m) => m.audioUrls?.some(isLocalUrl) || m.imageUrls?.some(isLocalUrl));
+    if (!needsResolution)
+        return messages;
+    return Promise.all(messages.map(async (msg) => {
+        // Resolve imageUrls on both user messages and tool result messages
+        if (msg.role !== "user" && msg.role !== "tool")
+            return msg;
+        const patch = {};
+        // Audio MUST be base64 for input_audio (OpenAI API requirementno upload alternative)
+        if (msg.role === "user" && msg.audioUrls?.some(isLocalUrl)) {
+            patch.audioUrls = await Promise.all(msg.audioUrls.map((url) => isLocalUrl(url) ? resolveMediaUrl(url) : Promise.resolve(url)));
+        }
+        // Images: upload via adapter (requiredno base64 fallback)
+        if (msg.imageUrls?.some(isLocalUrl)) {
+            if (!uploadAdapter || !apiKey) {
+                throw new Error("FileUploadAdapter required for local image URLs. Configure OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET or QLOGICAGENT_HUB_URL.");
+            }
+            patch.imageUrls = await Promise.all(msg.imageUrls.map((url) => isLocalUrl(url)
+                ? resolveMediaUrlViaUpload(url, { uploadAdapter, apiKey, signal })
+                : Promise.resolve(url)));
+        }
+        return Object.keys(patch).length > 0 ? { ...msg, ...patch } : msg;
+    }));
+}
+/**
+ * Convert qlogicagent ChatMessage[] into OpenAI wire format.
+ *
+ * Handles three concerns:
+ *  1. Vision: user messages with imageUrls 閳?content:[{type:"text"},{type:"image_url"}]
+ *  2. Thinking passback: assistant thinkingBlocks 閳?reasoning_content field (DeepSeek/GLM)
+ *  3. filterImageBlocks quirk: strip imageUrls for non-vision providers
+ *
+ * NOTE: For audio and local file URLs, the caller must pre-resolve to base64
+ * data URLs using resolveMediaUrl() before calling this function.
+ */
+function convertMessagesForOpenAI(messages, quirks) {
+    return messages.map(msg => {
+        // 鈹€鈹€ User messages: handle vision content blocks 鈹€鈹€
+        if (msg.role === "user") {
+            const hasImages = msg.imageUrls && msg.imageUrls.length > 0 && !quirks.filterImageBlocks;
+            const hasVideos = msg.videoUrls && msg.videoUrls.length > 0;
+            const hasAudios = msg.audioUrls && msg.audioUrls.length > 0;
+            const hasFiles = msg.fileIds && msg.fileIds.length > 0;
+            const hasMultimodal = hasImages || hasVideos || hasAudios || hasFiles;
+            if (hasMultimodal) {
+                const content = [];
+                if (msg.content) {
+                    content.push({ type: "text", text: msg.content });
+                }
+                if (hasImages) {
+                    const multiImage = msg.imageUrls.length > 1;
+                    for (let imgIdx = 0; imgIdx < msg.imageUrls.length; imgIdx++) {
+                        const url = msg.imageUrls[imgIdx];
+                        if (multiImage) {
+                            content.push({ type: "text", text: `[Image ${imgIdx + 1}]` });
+                        }
+                        const imgUrl = { url };
+                        if (msg.imageDetail)
+                            imgUrl.detail = msg.imageDetail;
+                        content.push({ type: "image_url", image_url: imgUrl });
+                    }
+                }
+                if (hasVideos) {
+                    for (const url of msg.videoUrls) {
+                        content.push({ type: "video_url", video_url: { url } });
+                    }
+                }
+                if (hasAudios) {
+                    for (const url of msg.audioUrls) {
+                        // input_audio.data expects base64-encoded content (not a URL).
+                        // The caller must pre-resolve local URLs via resolveMediaUrl().
+                        // data: URLs 閳?extract the base64 portion; http URLs 閳?pass as-is (fallback).
+                        let data = url;
+                        let format = msg.audioFormat ?? "mp3";
+                        if (url.startsWith("data:")) {
+                            const match = /^data:audio\/([^;]+);base64,(.+)$/.exec(url);
+                            if (match) {
+                                format = match[1] === "mpeg" ? "mp3" : match[1];
+                                data = match[2];
+                            }
+                        }
+                        content.push({ type: "input_audio", input_audio: { data, format } });
+                    }
+                }
+                if (hasFiles) {
+                    for (const f of msg.fileIds) {
+                        const mime = f.mimeType || "";
+                        const tooLarge = f.size != null && f.size > MEDIA_MAX_UPLOAD_SIZE;
+                        if (tooLarge) {
+                            const sizeLabel = `${(f.size / (1024 * 1024)).toFixed(1)}MB`;
+                            content.push({ type: "text", text: `[Attached: ${f.id} (${mime || "unknown"}, ${sizeLabel})file too large for direct vision, use tools to process]` });
+                        }
+                        else if (quirks.supportsDocumentVision && (mime === "application/pdf" || f.id.endsWith(".pdf"))) {
+                            // Document vision capable: only use platform file_id for Files API refs (not URLs)
+                            if (f.id.startsWith("http://") || f.id.startsWith("https://")) {
+                                content.push({ type: "text", text: `[Attached PDF: ${f.id}]` });
+                            }
+                            else {
+                                content.push({ type: "file", file: { file_id: f.id } });
+                            }
+                        }
+                        else if (f.id.startsWith("http://") || f.id.startsWith("https://")) {
+                            // URL-first: annotate as text contextagent can use tools to process
+                            const label = mime ? `[Attached: ${f.id} (${mime})]` : `[Attached: ${f.id}]`;
+                            content.push({ type: "text", text: label });
+                        }
+                        else {
+                            // Platform file_id (OpenAI Files API)
+                            content.push({ type: "file", file: { file_id: f.id } });
+                        }
+                    }
+                }
+                return { role: "user", content };
+            }
+            return { role: "user", content: msg.content ?? "" };
+        }
+        // 鈹€鈹€ Assistant messages: thinking blocks + tool calls 鈹€鈹€
+        if (msg.role === "assistant") {
+            const out = { role: "assistant" };
+            // DeepSeek/GLM: pass thinking content back via reasoning_content field
+            if (msg.thinkingBlocks && msg.thinkingBlocks.length > 0) {
+                out.reasoning_content = msg.thinkingBlocks.map(tb => tb.thinking).join("");
+            }
+            out.content = msg.content ?? null;
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                out.tool_calls = msg.tool_calls.map(tc => ({
+                    id: tc.id,
+                    type: tc.type,
+                    function: { name: tc.function.name, arguments: tc.function.arguments },
+                }));
+            }
+            return out;
+        }
+        // 鈹€鈹€ Tool result messages 鈹€鈹€
+        if (msg.role === "tool") {
+            // OpenAI Chat API supports multipart content in tool results (content array).
+            // If the tool result has imageUrls, include them as image_url content blocks.
+            if (msg.imageUrls && msg.imageUrls.length > 0 && !quirks.filterImageBlocks) {
+                const content = [];
+                if (msg.content)
+                    content.push({ type: "text", text: msg.content });
+                for (const url of msg.imageUrls) {
+                    content.push({ type: "image_url", image_url: { url } });
+                }
+                return {
+                    role: "tool",
+                    content,
+                    tool_call_id: msg.tool_call_id ?? "",
+                };
+            }
+            return {
+                role: "tool",
+                content: msg.content ?? "",
+                tool_call_id: msg.tool_call_id ?? "",
+            };
+        }
+        // 鈹€鈹€ System messages: pass through 鈹€鈹€
+        return { role: msg.role, content: msg.content ?? "" };
+    });
+}