@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/openai-responses.js

@@ -0,0 +1,778 @@
+/**
+ * OpenAI Responses API TransportSSE streaming implementation.
+ *
+ * Implements the OpenAI Responses API (`POST /v1/responses`),
+ * the officially recommended path for GPT-5.x text generation.
+ *
+ * Key differences from OpenAI Chat Completions:
+ *   - Endpoint: POST {baseUrl}/v1/responses
+ *   - Request body uses `input` (not `messages`), `instructions`, `reasoning`
+ *   - SSE events: response.output_text.delta, response.function_call_arguments.delta,
+ *     response.completed, etc.
+ *   - Tool defs: { type: "function", name, parameters } (not nested under `function:`)
+ *   - Tool results: { type: "function_call_output", call_id, output }
+ *   - Context persistence: previous_response_id for server-side session continuation
+ *   - Structured output: `text: { format: { type: "json_schema", ... } }`
+ *   - Reasoning: `reasoning: { effort, summary }` for GPT-5.x models
+ *
+ * Wire format reference:
+ *   https://developers.openai.com/api/docs/api-reference/responses/create
+ *   https://developers.openai.com/api/docs/api-reference/responses/streaming-events
+ *
+ * Design: Closely mirrors volcengine-responses.ts patterns while adapting to
+ * OpenAI-specific wire format. Shared LLMChunk output makes upper layers
+ * transport-agnostic.
+ */
+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 } from "../model-detection.js";
+export class OpenAIResponsesTransport {
+    baseUrl;
+    extraHeaders;
+    timeoutMs;
+    quirks;
+    fileUploadAdapter;
+    constructor(config) {
+        if (!config.baseUrl) {
+            throw new Error("OpenAIResponsesTransport: 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 /v1/responses
+        const hasVersionInBase = /\/v\d+$/.test(this.baseUrl);
+        const url = hasVersionInBase
+            ? `${this.baseUrl}/responses`
+            : `${this.baseUrl}/v1/responses`;
+        const body = await this.buildRequestBody(request, apiKey, signal);
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+            ...this.extraHeaders,
+        };
+        // 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;
+            }
+        }
+    }
+    // 鈹€鈹€ Request Body Builder 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async buildRequestBody(request, apiKey, signal) {
+        const body = {
+            model: request.model,
+            input: convertMessagesForOpenAIResponses(await resolveMessagesMediaForResponses(request.messages, this.fileUploadAdapter, apiKey, signal), this.quirks),
+            stream: true,
+        };
+        // Server-side context continuation (mutually exclusive)
+        if (request.conversationId) {
+            body.conversation = request.conversationId;
+        }
+        else if (request.previousResponseId) {
+            body.previous_response_id = request.previousResponseId;
+        }
+        // Storage control
+        if (request.store !== undefined) {
+            body.store = request.store;
+        }
+        // Per-turn instructions (system/developer message)
+        if (request.instructions) {
+            body.instructions = request.instructions;
+        }
+        // Structured output: text.format
+        if (request.structuredOutput) {
+            if (request.structuredOutput.mode === "json_object") {
+                body.text = { format: { type: "json_object" } };
+            }
+            else {
+                body.text = {
+                    format: {
+                        type: "json_schema",
+                        name: request.structuredOutput.name,
+                        strict: request.structuredOutput.strict ?? true,
+                        schema: request.structuredOutput.schema,
+                    },
+                };
+            }
+        }
+        // Tools 閳?OpenAI Responses API format
+        // Responses API uses flat tool defs: { type: "function", name, description, parameters, strict }
+        // (not the Chat Completions nested { type: "function", function: { name, ... } } format)
+        if (request.tools && request.tools.length > 0) {
+            body.tools = request.tools.map(tool => ({
+                type: "function",
+                name: tool.function.name,
+                description: tool.function.description,
+                parameters: tool.function.parameters,
+                strict: true,
+            }));
+        }
+        // tool_choice
+        if (request.toolChoice !== undefined) {
+            if (typeof request.toolChoice === "string") {
+                body.tool_choice = request.toolChoice;
+            }
+            else {
+                body.tool_choice = { type: request.toolChoice.type, name: request.toolChoice.name };
+            }
+        }
+        const suppressSampling = isGPT5xModel(request.model);
+        // GPT-5 Responses models reject explicit sampling params.
+        if (!suppressSampling && request.temperature !== undefined) {
+            body.temperature = request.temperature;
+        }
+        // top_p
+        if (!suppressSampling && request.topP !== undefined) {
+            body.top_p = request.topP;
+        }
+        // Max tokens 閳?max_output_tokens in Responses API
+        if (request.maxTokens !== undefined) {
+            body.max_output_tokens = request.maxTokens;
+        }
+        // Reasoning effort for GPT-5.x
+        if (request.reasoning) {
+            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";
+            }
+            const reasoning = { effort };
+            // Reasoning summary: let model produce a reasoning summary (Responses API only)
+            // Official API has both generate_summary and summary fields (openai-ProviderMax 鎼?)
+            reasoning.summary = "auto";
+            reasoning.generate_summary = "auto";
+            body.reasoning = reasoning;
+        }
+        // Predicted output for speculative decoding (code editing optimization)
+        if (request.prediction && isGPT5xModel(request.model)) {
+            body.prediction = request.prediction;
+        }
+        // Truncation: auto for safety (server-side context trimming)
+        body.truncation = "auto";
+        // Prompt cache optimization (openai-ProviderMax 鎼?1)
+        if (request.promptCacheKey) {
+            body.prompt_cache_key = request.promptCacheKey;
+        }
+        if (request.promptCacheRetention) {
+            body.prompt_cache_retention = request.promptCacheRetention;
+        }
+        // Service tier scheduling (openai-ProviderMax 鎼?4)
+        if (request.serviceTier) {
+            body.service_tier = request.serviceTier;
+        }
+        // Encrypted reasoning for ZDR (openai-ProviderMax 鎼?)
+        if (request.reasoning?.includeEncryptedReasoning) {
+            if (request.store === undefined) {
+                body.store = false;
+            }
+            body.include = ["reasoning.encrypted_content"];
+        }
+        // Context managementserver-side compression (openai-ProviderMax 鎼?1)
+        if (request.contextManagement) {
+            body.context_management = request.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;
+            });
+        }
+        // 鈹€鈹€ Builtin tools injection (quirks-driven, same pattern as Gemini/GLM/Kimi) 鈹€鈹€
+        // Priority: explicit openaiBuiltinTools > quirks-driven auto-injection
+        // Both respect disableBuiltinTools flag (session-level toggle, T15 parity)
+        if (!request.disableBuiltinTools) {
+            const existingTools = body.tools ?? [];
+            const includes = body.include ?? [];
+            if (request.openaiBuiltinTools && request.openaiBuiltinTools.length > 0) {
+                // Explicit caller-specified builtin tools (highest priority)
+                for (const bt of request.openaiBuiltinTools) {
+                    existingTools.push({ ...bt });
+                }
+                // Auto-expand `include` for builtin tool result details
+                const builtinTypes = new Set(request.openaiBuiltinTools.map((t) => t.type));
+                if (builtinTypes.has("web_search_preview"))
+                    includes.push("web_search_call.action.sources");
+                if (builtinTypes.has("file_search"))
+                    includes.push("file_search_call.results");
+                if (builtinTypes.has("code_interpreter"))
+                    includes.push("code_interpreter_call.outputs");
+                if (builtinTypes.has("computer_use_preview"))
+                    includes.push("computer_call_output.output.image_url");
+            }
+            else {
+                // Quirks-driven auto-injection (same pattern as Gemini/GLM transports)
+                if (this.quirks.builtinWebSearch) {
+                    existingTools.push({ type: "web_search_preview" });
+                    includes.push("web_search_call.action.sources");
+                }
+                if (this.quirks.builtinCodeInterpreter) {
+                    existingTools.push({ type: "code_interpreter" });
+                    includes.push("code_interpreter_call.outputs");
+                }
+                if (this.quirks.builtinFileSearch) {
+                    existingTools.push({ type: "file_search" });
+                    includes.push("file_search_call.results");
+                }
+            }
+            if (existingTools.length > 0)
+                body.tools = existingTools;
+            if (includes.length > 0)
+                body.include = includes;
+        }
+        // Max builtin tool calls limit (openai-ProviderMax 鎼?)
+        if (request.maxToolCalls !== undefined) {
+            body.max_tool_calls = request.maxToolCalls;
+        }
+        // Parallel tool calls control
+        if (request.parallelToolCalls !== undefined) {
+            body.parallel_tool_calls = request.parallelToolCalls;
+        }
+        // Text output verbosity (openai-ProviderMax 鎼?)
+        if (request.textVerbosity) {
+            const text = body.text ?? {};
+            text.verbosity = request.textVerbosity;
+            body.text = text;
+        }
+        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(`OpenAI Responses API error ${response.status}: ${errorBody.slice(0, 500)}`);
+            err.status = response.status;
+            throw err;
+        }
+        if (!response.body) {
+            throw new Error("OpenAI Responses API returned no response body");
+        }
+        // Check if the response is non-streaming JSON (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();
+        // 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 ?? "" };
+                            // Extract annotations from content blocks
+                            if (block.annotations && block.annotations.length > 0) {
+                                yield {
+                                    type: "annotations",
+                                    annotations: block.annotations.map(a => ({
+                                        ...a,
+                                        type: a.type ?? "url_citation",
+                                        url: a.url,
+                                        title: a.title,
+                                    })),
+                                };
+                            }
+                        }
+                    }
+                }
+                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 OpenAI 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 閳?reasoning summary 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.content_part.done           閳?content part completed (annotations)
+     *   - 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) {
+                            currentEvent = "";
+                            continue;
+                        }
+                        if (line.startsWith(":"))
+                            continue; // SSE comment
+                        if (line.startsWith("event:")) {
+                            currentEvent = line.slice(6).trim();
+                            continue;
+                        }
+                        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 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":
+                break;
+            // 鈹€鈹€ Content part doneextract annotations 鈹€鈹€
+            case "response.content_part.done": {
+                const part = data.part;
+                if (part?.type === "output_text") {
+                    const anns = part.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,
+                            })),
+                        };
+                    }
+                }
+                break;
+            }
+            // 鈹€鈹€ Output item doneextract annotations from completed messages 鈹€鈹€
+            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,
+                                    })),
+                                };
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+            // 鈹€鈹€ Response completedextract usage 鈹€鈹€
+            case "response.completed": {
+                const resp = data.response;
+                if (resp) {
+                    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,
+                        };
+                    }
+                    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;
+            }
+            // 鈹€鈹€ Web search tool events (builtin) 鈹€鈹€
+            default: {
+                if (eventType.startsWith("response.web_search_call")) {
+                    yield {
+                        type: "builtin_tool_status",
+                        toolType: "web_search",
+                        event: eventType,
+                        data: data,
+                    };
+                }
+                // Other events (response.created, output_text.done, etc.) are informational.
+                break;
+            }
+        }
+    }
+}
+// 鈹€鈹€ Message Conversion for Responses API 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Pre-resolve local media URLs for Responses API.
+ * Images: prefer upload via adapter (no size limit), fallback to base64 (legacy, 閳?0MB).
+ * Audio: must always be base64 (OpenAI input_audio.data requirement).
+ */
+async function resolveMessagesMediaForResponses(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 (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 Responses API `input` format.
+ *
+ * Responses API input is an array of items:
+ *   - { role: "developer", content: "..." }       閳?system messages use "developer" role
+ *   - { role: "user", content: "..." | [...] }    閳?text or multimodal content array
+ *   - { role: "assistant", content: "..." }
+ *   - { type: "function_call_output", call_id: "...", output: "..." }
+ *
+ * Key differences from Chat Completions:
+ *   - System 閳?developer role (OpenAI Responses API convention)
+ *   - Vision: { type: "input_image", image_url: "..." } (not image_url object)
+ *   - Tool results: { type: "function_call_output" } (not role: "tool")
+ *   - Tool calls from assistant: { type: "function_call", call_id, name, arguments }
+ */
+function convertMessagesForOpenAIResponses(messages, quirks = {}) {
+    const result = [];
+    for (const msg of messages) {
+        // System messages 閳?developer role (OpenAI Responses API uses "developer" for system instructions)
+        if (msg.role === "system") {
+            result.push({ role: "developer", content: msg.content ?? "" });
+            continue;
+        }
+        // User messages: handle vision/multimodal 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 = [];
+                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;
+                        content.push(img);
+                    }
+                }
+                if (hasVideos) {
+                    for (const url of msg.videoUrls) {
+                        content.push({ type: "input_video", video_url: url });
+                    }
+                }
+                if (hasAudios) {
+                    for (const url of msg.audioUrls) {
+                        // input_audio.data expects base64 content, not a URL.
+                        // Caller must pre-resolve local URLs via resolveMediaUrl().
+                        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", 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: "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
+            if (msg.content) {
+                result.push({ role: "assistant", content: msg.content });
+            }
+            // Emit tool calls as function_call output items (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") {
+            if (!msg.tool_call_id)
+                continue;
+            // If tool result has imageUrls, include as content array (GPT-5.x support)
+            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;
+}