@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/volcengine-responses.js

@@ -0,0 +1,797 @@
+/**
+ * Volcengine Responses API TransportSSE streaming implementation.
+ *
+ * Implements the fire mountain ark Responses API (`/api/v3/responses`),
+ * which is the officially recommended primary path for Doubao LLM text generation
+ * (250615+ models: doubao-seed-2.0 series).
+ *
+ * Key differences from OpenAI Chat Completions:
+ *   - Endpoint: POST {baseUrl}/v3/responses
+ *   - Request body uses `input` (not `messages`), `instructions`, `thinking`, `reasoning`
+ *   - SSE events: response.output_text.delta, response.reasoning_summary_text.delta,
+ *     response.function_call_arguments.delta, response.completed, etc.
+ *   - Tool calling: function_call / function_call_output with call_id
+ *   - Context persistence: previous_response_id for server-side session continuation
+ *   - Deep thinking: thinking.type (enabled/disabled/auto) + reasoning.effort
+ *
+ * Docs: https://www.volcengine.com/docs/82379/1399008
+ */
+import { MEDIA_MAX_UPLOAD_SIZE } from "../constants.js";
+import { isLocalUrl, resolveMediaUrlViaUpload } from "./media-resolve.js";
+import { DEFAULT_MAX_RETRIES, STREAM_IDLE_TIMEOUT_MS, retryDelay, retrySleep, extractHttpStatus, isTransientStatus, } from "../retry.js";
+export class VolcengineResponsesTransport {
+    baseUrl;
+    extraHeaders;
+    timeoutMs;
+    quirks;
+    fileUploadAdapter;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error("VolcengineResponsesTransport: baseUrl is required");
+        }
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.extraHeaders = config.extraHeaders ?? {};
+        this.timeoutMs = config.timeoutMs ?? 180_000;
+        this.quirks = config.quirks ?? {};
+        this.fileUploadAdapter = config.fileUploadAdapter;
+    }
+    async *stream(request, apiKey, signal) {
+        // Responses API endpoint: POST /api/v3/responses
+        // Normalize baseUrl: strip trailing /v3 or /vN, then always append /v3/responses
+        const base = this.baseUrl.replace(/\/v\d+$/, "");
+        const url = `${base}/v3/responses`;
+        const body = await this.buildRequestBody(request, apiKey, signal);
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+            ...this.extraHeaders,
+        };
+        // Builtin tools require beta feature-gate headers (鎼?9.8)
+        if (request.builtinTools && !request.disableBuiltinTools && request.builtinTools.length > 0) {
+            for (const bt of request.builtinTools) {
+                if (bt.type === "builtin_web_search")
+                    headers["ark-beta-web-search"] = "true";
+                else if (bt.type === "builtin_image_process")
+                    headers["ark-beta-image-process"] = "true";
+                else if (bt.type === "builtin_knowledge_search")
+                    headers["ark-beta-knowledge-search"] = "true";
+                else if (bt.type === "builtin_doubao_app")
+                    headers["ark-beta-doubao-app"] = "true";
+            }
+        }
+        // Retry loop with exponential backoff (CC 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;
+            }
+            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;
+            }
+        }
+    }
+    // 鈹€鈹€ Capability Constraint Resolution (鎼?0.7, 鎼?0.9, 鎼?0.10) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * Resolve known Volcengine Responses API incompatibilities:
+     *   - instructions + caching 閳?drop caching (鎼?0.7)
+     *   - caching + json_schema 閳?downgrade to json_object (鎼?0.10)
+     *   - caching + builtin_web_search/image_process 閳?drop those builtin tools
+     * Returns a shallow copy with fields adjusted; never mutates the original.
+     */
+    resolveConstraints(request) {
+        let req = request;
+        const hasCaching = req.caching && req.caching.type === "enabled";
+        if (hasCaching) {
+            // 鎼?0.7: instructions and caching are mutually exclusiveinstructions wins
+            if (req.instructions) {
+                req = { ...req, caching: undefined };
+                // After dropping caching, remaining constraints no longer apply
+                return req;
+            }
+            // 鎼?0.10: caching + json_schema 閳?downgrade to json_object
+            if (req.structuredOutput && req.structuredOutput.mode === "json_schema") {
+                req = { ...req, structuredOutput: { mode: "json_object" } };
+            }
+            // 鎼?0.9 / 鎼?131-3146: caching incompatible with web_search and image_process
+            if (req.builtinTools && req.builtinTools.length > 0) {
+                const filtered = req.builtinTools.filter((bt) => bt.type !== "builtin_web_search" && bt.type !== "builtin_image_process");
+                if (filtered.length !== req.builtinTools.length) {
+                    req = { ...req, builtinTools: filtered.length > 0 ? filtered : undefined };
+                }
+            }
+        }
+        return req;
+    }
+    // 鈹€鈹€ Request Body Builder 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async buildRequestBody(request, apiKey, signal) {
+        // W11-W13: Resolve Volcengine-specific capability conflicts before building body
+        const req = this.resolveConstraints(request);
+        // Pre-resolve local media URLs (Volcengine API can't reach localhost)
+        const resolvedMessages = await resolveMessagesMediaForVolcengine(req.messages, this.fileUploadAdapter, apiKey, signal);
+        const body = {
+            model: req.model,
+            input: convertMessagesForResponses(resolvedMessages, this.quirks),
+            stream: true,
+        };
+        // W3: Server-side context continuation (鎼?)
+        if (req.previousResponseId) {
+            body.previous_response_id = req.previousResponseId;
+        }
+        // W4: Storage control (鎼?.1)
+        if (req.store !== undefined) {
+            body.store = req.store;
+        }
+        if (req.storeExpireAt !== undefined) {
+            body.expire_at = req.storeExpireAt;
+        }
+        // W5: Per-turn instructions (鎼?)note: incompatible with caching
+        if (req.instructions) {
+            body.instructions = req.instructions;
+        }
+        // W6: Structured output (鎼?6)
+        if (req.structuredOutput) {
+            if (req.structuredOutput.mode === "json_object") {
+                body.text = { format: { type: "json_object" } };
+            }
+            else {
+                const fmt = {
+                    type: "json_schema",
+                    name: req.structuredOutput.name,
+                    schema: req.structuredOutput.schema,
+                };
+                if (req.structuredOutput.strict !== undefined) {
+                    fmt.strict = req.structuredOutput.strict;
+                }
+                body.text = { format: fmt };
+            }
+        }
+        // W7: Caching (鎼?0)
+        if (req.caching) {
+            const cachingObj = { type: req.caching.type };
+            if (req.caching.prefix !== undefined)
+                cachingObj.prefix = req.caching.prefix;
+            body.caching = cachingObj;
+            // 鎼?0.3: Prefix cache creation requires stream=false
+            if (req.caching.prefix) {
+                body.stream = false;
+            }
+        }
+        // W8: Context management edits (鎼?1, beta)
+        if (req.contextManagement) {
+            const edits = req.contextManagement.edits.map((edit) => {
+                const e = { type: edit.type };
+                if (edit.type === "clear_thinking" && edit.keep !== undefined) {
+                    e.keep = edit.keep;
+                }
+                else if (edit.type === "clear_tool_uses") {
+                    if (edit.trigger)
+                        e.trigger = edit.trigger;
+                    if (edit.keep)
+                        e.keep = edit.keep;
+                    if (edit.excludeTools)
+                        e.exclude_tools = edit.excludeTools;
+                    if (edit.clearToolInput !== undefined)
+                        e.clear_tool_input = edit.clearToolInput;
+                }
+                return e;
+            });
+            body.context_management = { edits };
+        }
+        // Tools 閳?Volcengine Responses API format
+        const tools = [];
+        if (req.tools && req.tools.length > 0) {
+            for (const tool of req.tools) {
+                tools.push({
+                    type: "function",
+                    name: tool.function.name,
+                    description: tool.function.description,
+                    parameters: tool.function.parameters,
+                });
+            }
+        }
+        // Builtin tools (鎼?9.8): web_search, image_process, knowledge_search, doubao_app
+        // Provider builtins and system function tools COEXISTthey use different type values:
+        //   system:  { type: "function", name: "web_search", ... }
+        //   builtin: { type: "web_search" }
+        // The LLM uses builtins for fast inline search (platform-side, transparent)
+        // and system tools for explicit deep/structured search (agent executes).
+        // Per B4: respect disableBuiltinTools flag
+        if (req.builtinTools && !req.disableBuiltinTools && req.builtinTools.length > 0) {
+            for (const bt of req.builtinTools) {
+                // Strip "builtin_" prefixVolcengine API uses bare names
+                const volcType = bt.type.replace(/^builtin_/, "");
+                const entry = { type: volcType };
+                // Spread tool-specific config fields at top level (web_search.sources, .limit, etc.)
+                if (bt.config)
+                    Object.assign(entry, bt.config);
+                tools.push(entry);
+            }
+        }
+        if (tools.length > 0) {
+            body.tools = tools;
+        }
+        // max_tool_callsVolcengine tool dispatch scheduling (鎼?9.15)
+        if (req.maxToolCalls !== undefined) {
+            body.max_tool_calls = req.maxToolCalls;
+        }
+        // tool_choiceVolcengine supports string or named function object
+        if (req.toolChoice !== undefined) {
+            if (typeof req.toolChoice === "string") {
+                body.tool_choice = req.toolChoice;
+            }
+            else {
+                // Named function call: { type: "function", name: "..." }
+                body.tool_choice = { type: req.toolChoice.type, name: req.toolChoice.name };
+            }
+        }
+        // Temperature
+        if (req.temperature !== undefined) {
+            body.temperature = req.temperature;
+        }
+        // top_p (鎼?7.11: nucleus sampling)
+        if (req.topP !== undefined) {
+            body.top_p = req.topP;
+        }
+        // Max tokens 閳?max_output_tokens in Responses API
+        if (req.maxTokens !== undefined) {
+            body.max_output_tokens = req.maxTokens;
+        }
+        // Deep thinking: thinking.type + reasoning.effort (鎼?7)
+        //   thinking: { type: "enabled" | "disabled" | "auto" }
+        //   reasoning: { effort: "minimal" | "low" | "medium" | "high" }
+        // "minimal" maps to thinking.type="disabled" (skip thinking entirely)
+        if (req.reasoning) {
+            const effort = req.reasoning.effort ?? "high";
+            if (effort === "minimal") {
+                body.thinking = { type: "disabled" };
+            }
+            else {
+                body.thinking = { type: "enabled" };
+                body.reasoning = { effort };
+            }
+            // 鎼?7.7: Request encrypted original reasoning content
+            if (req.reasoning.includeEncryptedReasoning) {
+                body.include = ["reasoning.encrypted_content"];
+            }
+        }
+        // Prefix completion 閳?assistant with partial=true (鎼? prefill mode)
+        if (req.prefixMessage) {
+            const input = body.input;
+            input.push({
+                role: "assistant",
+                content: req.prefixMessage,
+                partial: true,
+            });
+        }
+        return body;
+    }
+    // 鈹€鈹€ Fetch + Stream 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    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(`Volcengine Responses API error ${response.status}: ${errorBody.slice(0, 500)}`);
+            err.status = response.status;
+            throw err;
+        }
+        if (!response.body) {
+            throw new Error("Volcengine Responses API returned no response body");
+        }
+        // Check if the response is actually SSE (some non-streaming fallback)
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json") && !contentType.includes("text/event-stream")) {
+            yield* this.handleNonStreamingResponse(response);
+            return;
+        }
+        yield* this.parseSSEStream(response.body);
+    }
+    // 鈹€鈹€ Non-streaming fallback 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async *handleNonStreamingResponse(response) {
+        const data = await response.json();
+        // W10: Emit response ID for context chain
+        if (data.id) {
+            yield { type: "response_id", id: data.id };
+        }
+        if (data.usage) {
+            yield {
+                type: "usage",
+                promptTokens: data.usage.input_tokens ?? 0,
+                completionTokens: data.usage.output_tokens ?? 0,
+                reasoningTokens: data.usage.output_tokens_details?.reasoning_tokens,
+                cacheReadTokens: data.usage.input_tokens_details?.cached_tokens,
+            };
+        }
+        // Process output items
+        if (data.output) {
+            for (const item of data.output) {
+                if (item.type === "message" && item.content) {
+                    for (const block of item.content) {
+                        if (block.type === "output_text") {
+                            yield { type: "delta", text: block.text ?? "" };
+                        }
+                    }
+                }
+                if (item.type === "reasoning" && item.summary) {
+                    for (const block of item.summary) {
+                        if (block.type === "summary_text") {
+                            yield { type: "reasoning_delta", text: block.text ?? "" };
+                        }
+                    }
+                }
+                if (item.type === "function_call") {
+                    yield {
+                        type: "tool_call_delta",
+                        index: 0,
+                        id: item.call_id,
+                        name: item.name,
+                        arguments: item.arguments ?? "",
+                    };
+                }
+            }
+        }
+        yield { type: "done", finishReason: data.status === "completed" ? "stop" : (data.status ?? "stop") };
+    }
+    // 鈹€鈹€ SSE Stream Parser 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * Parse Volcengine Responses API SSE stream.
+     *
+     * Event format: "event: <type>\ndata: <json>\n\n"
+     * Key events:
+     *   - response.output_text.delta           閳?text content delta
+     *   - response.reasoning_summary_text.delta 閳?thinking/reasoning text
+     *   - response.function_call_arguments.delta 閳?tool call arguments streaming
+     *   - response.output_item.added           閳?new output item started
+     *   - response.output_item.done            閳?output item completed
+     *   - response.completed                   閳?full response complete with usage
+     *   - response.failed                      閳?error
+     */
+    async *parseSSEStream(body) {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let currentEvent = "";
+        let idleTimer = null;
+        const abortController = new AbortController();
+        // Track tool call indices for multiple parallel function calls
+        let toolCallIndex = 0;
+        const toolCallIdToIndex = new Map();
+        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) {
+                            // Empty line = event boundary, process accumulated event+data
+                            currentEvent = "";
+                            continue;
+                        }
+                        if (line.startsWith(":"))
+                            continue; // SSE comment
+                        // event: <type> (with or without space after colon)
+                        if (line.startsWith("event:")) {
+                            currentEvent = line.slice(6).trim();
+                            continue;
+                        }
+                        // data: <json>
+                        if (line.startsWith("data:")) {
+                            const dataStr = line.slice(5).trim();
+                            if (dataStr === "[DONE]")
+                                return;
+                            let parsed;
+                            try {
+                                parsed = JSON.parse(dataStr);
+                            }
+                            catch {
+                                continue;
+                            }
+                            yield* this.processEvent(currentEvent, parsed, toolCallIdToIndex, () => toolCallIndex++);
+                        }
+                    }
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        finally {
+            if (idleTimer)
+                clearTimeout(idleTimer);
+        }
+    }
+    // 鈹€鈹€ Event Processing 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    *processEvent(eventType, data, toolCallIdToIndex, nextIndex) {
+        switch (eventType) {
+            // 鈹€鈹€ Text content delta 鈹€鈹€
+            case "response.output_text.delta": {
+                const delta = data.delta;
+                if (delta) {
+                    yield { type: "delta", text: delta };
+                }
+                break;
+            }
+            // 鈹€鈹€ Reasoning/thinking summary delta 鈹€鈹€
+            case "response.reasoning_summary_text.delta": {
+                const delta = data.delta;
+                if (delta) {
+                    yield { type: "reasoning_delta", text: delta };
+                }
+                break;
+            }
+            // 鈹€鈹€ Function call arguments streaming 鈹€鈹€
+            case "response.function_call_arguments.delta": {
+                const delta = data.delta;
+                const callId = data.call_id;
+                const name = data.name;
+                if (delta !== undefined && callId) {
+                    let idx = toolCallIdToIndex.get(callId);
+                    if (idx === undefined) {
+                        idx = nextIndex();
+                        toolCallIdToIndex.set(callId, idx);
+                    }
+                    yield {
+                        type: "tool_call_delta",
+                        index: idx,
+                        id: callId,
+                        name: name,
+                        arguments: delta,
+                    };
+                }
+                break;
+            }
+            // 鈹€鈹€ Output item added (function_call start) 鈹€鈹€
+            case "response.output_item.added": {
+                const item = data.item;
+                if (item && item.type === "function_call") {
+                    const callId = item.call_id;
+                    const name = item.name;
+                    if (callId && !toolCallIdToIndex.has(callId)) {
+                        const idx = nextIndex();
+                        toolCallIdToIndex.set(callId, idx);
+                        yield {
+                            type: "tool_call_delta",
+                            index: idx,
+                            id: callId,
+                            name: name,
+                            arguments: "",
+                        };
+                    }
+                }
+                break;
+            }
+            // 鈹€鈹€ Function call arguments done 鈹€鈹€
+            case "response.function_call_arguments.done":
+                // Arguments fully received; no action needed (accumulation in tool loop handles it)
+                break;
+            // 鈹€鈹€ Output item doneextract annotations + finalize function_call args 鈹€鈹€
+            case "response.output_item.done": {
+                const item = data.item;
+                if (item?.type === "message") {
+                    const content = item.content;
+                    if (content) {
+                        for (const block of content) {
+                            const anns = block.annotations;
+                            if (anns && anns.length > 0) {
+                                yield {
+                                    type: "annotations",
+                                    annotations: anns.map(a => ({
+                                        type: a.type ?? "url_citation",
+                                        url: a.url,
+                                        title: a.title,
+                                        ...a,
+                                    })),
+                                };
+                            }
+                        }
+                    }
+                }
+                // Volcengine reasoning models may deliver function_call with complete arguments
+                // in output_item.done without streaming function_call_arguments.delta events.
+                if (item?.type === "function_call") {
+                    const callId = item.call_id;
+                    const name = item.name;
+                    const args = item.arguments ?? "";
+                    if (callId && args) {
+                        let idx = toolCallIdToIndex.get(callId);
+                        const alreadySeen = idx !== undefined;
+                        if (!alreadySeen) {
+                            idx = nextIndex();
+                            toolCallIdToIndex.set(callId, idx);
+                        }
+                        yield {
+                            type: "tool_call_delta",
+                            index: idx,
+                            id: callId,
+                            // Only emit name if not already emitted via output_item.added
+                            name: alreadySeen ? undefined : name,
+                            arguments: args,
+                        };
+                    }
+                }
+                break;
+            }
+            // 鈹€鈹€ Response completedextract usage 鈹€鈹€
+            case "response.completed": {
+                const resp = data.response;
+                if (resp) {
+                    // W10: Emit response ID for server-side context chain (鎼?)
+                    const respId = resp.id;
+                    if (respId) {
+                        yield { type: "response_id", id: respId };
+                    }
+                    const usage = resp.usage;
+                    if (usage) {
+                        const inputDetails = usage.input_tokens_details;
+                        const outputDetails = usage.output_tokens_details;
+                        yield {
+                            type: "usage",
+                            promptTokens: usage.input_tokens ?? 0,
+                            completionTokens: usage.output_tokens ?? 0,
+                            reasoningTokens: outputDetails?.reasoning_tokens,
+                            cacheReadTokens: inputDetails?.cached_tokens,
+                        };
+                    }
+                    // Check if response ended with function calls (incomplete = need tool results)
+                    const status = resp.status;
+                    yield { type: "done", finishReason: status === "incomplete" ? "tool_calls" : "stop" };
+                }
+                else {
+                    yield { type: "done", finishReason: "stop" };
+                }
+                break;
+            }
+            // 鈹€鈹€ Response failed 鈹€鈹€
+            case "response.failed": {
+                const resp = data.response;
+                const error = resp?.error;
+                const message = error?.message ?? "Unknown error";
+                yield { type: "error", message };
+                yield { type: "done", finishReason: "error" };
+                break;
+            }
+            // 鈹€鈹€ Builtin tool lifecycle events (鎼?9.12): web_search, image_process 鈹€鈹€
+            // These are informational SSE events emitted during platform-executed tool runs.
+            // Forward them so upper layers can show search progress, cost, and citations.
+            default: {
+                if (eventType.startsWith("response.web_search_call")) {
+                    yield {
+                        type: "builtin_tool_status",
+                        toolType: "web_search",
+                        event: eventType,
+                        data: data,
+                    };
+                }
+                else if (eventType.startsWith("response.image_process")) {
+                    yield {
+                        type: "builtin_tool_status",
+                        toolType: "image_process",
+                        event: eventType,
+                        data: data,
+                    };
+                }
+                // Other events (output_text.done, etc.) are purely informational.
+                break;
+            }
+        }
+    }
+}
+// 鈹€鈹€ Local media resolution for Volcengine 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Pre-resolve local media URLs. Volcengine's API accepts URLs for images/video/audio,
+ * but cannot reach localhost. Upload to File API when adapter available, otherwise base64 fallback.
+ */
+async function resolveMessagesMediaForVolcengine(messages, uploadAdapter, apiKey, signal) {
+    const needsResolution = messages.some((m) => m.imageUrls?.some(isLocalUrl) || m.videoUrls?.some(isLocalUrl) || m.audioUrls?.some(isLocalUrl));
+    if (!needsResolution)
+        return messages;
+    const resolve = (url) => {
+        if (!isLocalUrl(url))
+            return Promise.resolve(url);
+        if (!uploadAdapter || !apiKey) {
+            throw new Error("FileUploadAdapter required for local media URLs. Configure OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET or QLOGICAGENT_HUB_URL.");
+        }
+        return resolveMediaUrlViaUpload(url, { uploadAdapter, apiKey, signal });
+    };
+    return Promise.all(messages.map(async (msg) => {
+        if (msg.role !== "user" && msg.role !== "tool")
+            return msg;
+        const patch = {};
+        if (msg.imageUrls?.some(isLocalUrl)) {
+            patch.imageUrls = await Promise.all(msg.imageUrls.map(resolve));
+        }
+        if (msg.role === "user" && msg.videoUrls?.some(isLocalUrl)) {
+            patch.videoUrls = await Promise.all(msg.videoUrls.map(resolve));
+        }
+        if (msg.role === "user" && msg.audioUrls?.some(isLocalUrl)) {
+            patch.audioUrls = await Promise.all(msg.audioUrls.map(resolve));
+        }
+        return Object.keys(patch).length > 0 ? { ...msg, ...patch } : msg;
+    }));
+}
+// 鈹€鈹€ Message Conversion for Responses API 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Convert qlogicagent ChatMessage[] into Volcengine Responses API `input` format.
+ *
+ * Responses API input is an array of message objects with roles:
+ *   - { role: "user", content: "..." } or { role: "user", content: [{type:"input_text",...},{type:"input_image",...}] }
+ *   - { role: "assistant", content: "..." }
+ *   - { role: "system", content: "..." } (extracted to top-level `instructions`)
+ *   - { type: "function_call_output", call_id: "...", output: "..." }
+ *
+ * Key differences from OpenAI Chat:
+ *   - Vision uses input_image (not image_url) with url field
+ *   - Tool results use function_call_output type (not role: "tool")
+ *   - System messages map to instructions (handled separately)
+ */
+function convertMessagesForResponses(messages, quirks = {}) {
+    const result = [];
+    for (const msg of messages) {
+        // 鈹€鈹€ System messages 閳?pass as-is (Responses API supports role: "system" in input) 鈹€鈹€
+        if (msg.role === "system") {
+            result.push({ role: "system", content: msg.content ?? "" });
+            continue;
+        }
+        // 鈹€鈹€ User messages: handle vision content blocks 鈹€鈹€
+        if (msg.role === "user") {
+            const hasImages = msg.imageUrls && msg.imageUrls.length > 0;
+            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 = [];
+                // Volcengine Responses API: media content before text (official wire order)
+                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: "input_text", text: `[Image ${imgIdx + 1}]` });
+                        }
+                        const img = { type: "input_image", image_url: url };
+                        if (msg.imageDetail)
+                            img.detail = msg.imageDetail;
+                        if (msg.imagePixelLimit)
+                            img.image_pixel_limit = msg.imagePixelLimit;
+                        content.push(img);
+                    }
+                }
+                if (hasVideos) {
+                    for (const url of msg.videoUrls) {
+                        const vid = { type: "input_video", video_url: url };
+                        if (msg.videoFps !== undefined)
+                            vid.fps = msg.videoFps;
+                        content.push(vid);
+                    }
+                }
+                if (hasAudios) {
+                    for (const url of msg.audioUrls) {
+                        const aud = { type: "input_audio", audio_url: url };
+                        if (msg.audioFormat)
+                            aud.format = msg.audioFormat;
+                        content.push(aud);
+                    }
+                }
+                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: "input_text", text: `[Attached: ${f.id} (${mime || "unknown"}, ${sizeLabel}) \u2014 file too large for direct vision, use tools to process]` });
+                        }
+                        else if (quirks.supportsDocumentVision && (mime === "application/pdf" || f.id.endsWith(".pdf"))) {
+                            // Only use input_file for platform file IDs, not HTTP URLs
+                            if (f.id.startsWith("http://") || f.id.startsWith("https://")) {
+                                content.push({ type: "input_text", text: `[Attached PDF: ${f.id}]` });
+                            }
+                            else {
+                                content.push({ type: "input_file", file_id: f.id });
+                            }
+                        }
+                        else if (f.id.startsWith("http://") || f.id.startsWith("https://")) {
+                            const label = mime ? `[Attached: ${f.id} (${mime})]` : `[Attached: ${f.id}]`;
+                            content.push({ type: "input_text", text: label });
+                        }
+                        else {
+                            content.push({ type: "input_file", file_id: f.id });
+                        }
+                    }
+                }
+                if (msg.content) {
+                    content.push({ type: "input_text", text: msg.content });
+                }
+                result.push({ role: "user", content });
+            }
+            else {
+                result.push({ role: "user", content: msg.content ?? "" });
+            }
+            continue;
+        }
+        // 鈹€鈹€ Assistant messages: include tool calls as separate function_call items 鈹€鈹€
+        if (msg.role === "assistant") {
+            // Emit text content only if non-empty (empty assistant content with tool_calls causes 400)
+            if (msg.content) {
+                result.push({ role: "assistant", content: msg.content });
+            }
+            // Emit tool calls as function_call items (required for multi-turn replay)
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                for (const tc of msg.tool_calls) {
+                    result.push({
+                        type: "function_call",
+                        call_id: tc.id,
+                        name: tc.function.name,
+                        arguments: tc.function.arguments || "{}",
+                    });
+                }
+            }
+            continue;
+        }
+        // 鈹€鈹€ Tool result messages 閳?function_call_output 鈹€鈹€
+        if (msg.role === "tool") {
+            // G2: call_id is required by Volcengineskip malformed tool results
+            if (!msg.tool_call_id)
+                continue;
+            // If tool result has imageUrls, include as content array
+            if (msg.imageUrls && msg.imageUrls.length > 0) {
+                const content = [];
+                if (msg.content)
+                    content.push({ type: "input_text", text: msg.content });
+                for (const url of msg.imageUrls) {
+                    content.push({ type: "input_image", image_url: url });
+                }
+                result.push({
+                    type: "function_call_output",
+                    call_id: msg.tool_call_id,
+                    output: content,
+                });
+            }
+            else {
+                result.push({
+                    type: "function_call_output",
+                    call_id: msg.tool_call_id,
+                    output: msg.content ?? "",
+                });
+            }
+            continue;
+        }
+    }
+    return result;
+}