@openai/agents-openai 0.4.14 → 0.5.0

package/dist/openaiResponsesModel.mjs

@@ -1,7 +1,10 @@
 import { RequestUsage, Usage, withResponseSpan, createResponseSpan, setCurrentSpan, resetCurrentSpan, UserError, } from '@openai/agents-core';
+import OpenAI from 'openai';
 import logger from "./logger.mjs";
 import { z } from 'zod';
 import { HEADERS } from "./defaults.mjs";
+import { ResponsesWebSocketConnection, ResponsesWebSocketInternalError, isWebSocketNotOpenError, shouldWrapNoEventWebSocketError, throwIfAborted, webSocketFrameToText, withAbortSignal, withTimeout, } from "./responsesWebSocketConnection.mjs";
+import { applyHeadersToAccumulator, createHeaderAccumulator, ensureResponsesWebSocketPath, headerAccumulatorToRecord, headerAccumulatorToSDKHeaders, mergeQueryParamsIntoURL, splitResponsesTransportOverrides, } from "./responsesTransportUtils.mjs";
 import { CodeInterpreterStatus, FileSearchStatus, ImageGenerationStatus, WebSearchStatus, } from "./tools.mjs";
 import { camelOrSnakeToSnakeCase } from "./utils/providerData.mjs";
 import { encodeUint8ArrayToBase64 } from '@openai/agents-core/utils';
@@ -1390,23 +1393,51 @@ function convertToOutputItem(items) {
     });
 }
 export { getToolChoice, converTool, getInputItems, convertToOutputItem };
+const TERMINAL_RESPONSES_STREAM_EVENT_TYPES = new Set([
+    'response.completed',
+    'response.failed',
+    'response.incomplete',
+    'response.error',
+]);
+function isTerminalResponsesStreamEventType(eventType) {
+    return (typeof eventType === 'string' &&
+        TERMINAL_RESPONSES_STREAM_EVENT_TYPES.has(eventType));
+}
 /**
  * Model implementation that uses OpenAI's Responses API to generate responses.
  */
 export class OpenAIResponsesModel {
-    #client;
-    #model;
+    _client;
+    _model;
     constructor(client, model) {
-        this.#client = client;
-        this.#model = model;
+        this._client = client;
+        this._model = model;
     }
-    async #fetchResponse(request, stream) {
+    async _fetchResponse(request, stream) {
+        const builtRequest = this._buildResponsesCreateRequest(request, stream);
+        const response = await this._client.responses.create(builtRequest.requestData, {
+            headers: builtRequest.sdkRequestHeaders,
+            signal: builtRequest.signal,
+            ...(builtRequest.transportExtraQuery
+                ? { query: builtRequest.transportExtraQuery }
+                : {}),
+        });
+        if (logger.dontLogModelData) {
+            logger.debug('Response received');
+        }
+        else {
+            logger.debug(`Response received: ${JSON.stringify(response, null, 2)}`);
+        }
+        return response;
+    }
+    _buildResponsesCreateRequest(request, stream) {
         const input = getInputItems(request.input);
         const { tools, include } = getTools(request.tools, request.handoffs);
         const toolChoice = getToolChoice(request.modelSettings.toolChoice);
-        const { text, ...restOfProviderData } = request.modelSettings.providerData ?? {};
+        const { providerData: providerDataWithoutTransport, overrides: transportOverrides, } = splitResponsesTransportOverrides(request.modelSettings.providerData);
+        const { text, ...restOfProviderData } = providerDataWithoutTransport;
         if (request.modelSettings.reasoning) {
-            // Merge top-level reasoning settings with provider data
+            // Merge top-level reasoning settings with provider data.
             restOfProviderData.reasoning = {
                 ...request.modelSettings.reasoning,
                 ...restOfProviderData.reasoning,
@@ -1414,7 +1445,7 @@ export class OpenAIResponsesModel {
         }
         let mergedText = text;
         if (request.modelSettings.text) {
-            // Merge top-level text settings with provider data
+            // Merge top-level text settings with provider data.
             mergedText = { ...request.modelSettings.text, ...text };
         }
         const responseFormat = getResponseFormat(request.outputType, mergedText);
@@ -1435,8 +1466,8 @@ export class OpenAIResponsesModel {
         const shouldOmitToolChoice = Boolean(request.prompt) &&
             !shouldSendTools &&
             typeof toolChoice === 'object';
-        const requestData = {
-            ...(shouldSendModel ? { model: this.#model } : {}),
+        let requestData = {
+            ...(shouldSendModel ? { model: this._model } : {}),
             instructions: normalizeInstructions(request.systemInstructions),
             input,
             include,
@@ -1462,23 +1493,34 @@ export class OpenAIResponsesModel {
             prompt_cache_retention: request.modelSettings.promptCacheRetention,
             ...restOfProviderData,
         };
-        if (logger.dontLogModelData) {
-            logger.debug('Calling LLM');
-        }
-        else {
-            logger.debug(`Calling LLM. Request data: ${JSON.stringify(requestData, null, 2)}`);
+        if (transportOverrides.extraBody) {
+            requestData = {
+                ...requestData,
+                ...transportOverrides.extraBody,
+            };
         }
-        const response = await this.#client.responses.create(requestData, {
-            headers: HEADERS,
-            signal: request.signal,
+        // Keep the transport mode aligned with the calling path even if extra_body includes stream.
+        requestData.stream = stream;
+        const requestHeaderAccumulator = createHeaderAccumulator();
+        applyHeadersToAccumulator(requestHeaderAccumulator, HEADERS);
+        applyHeadersToAccumulator(requestHeaderAccumulator, transportOverrides.extraHeaders, {
+            allowBlockedOverride: true,
         });
+        const sdkRequestHeaders = headerAccumulatorToSDKHeaders(requestHeaderAccumulator);
+        const builtRequest = {
+            requestData,
+            sdkRequestHeaders,
+            signal: request.signal,
+            transportExtraHeaders: transportOverrides.extraHeaders,
+            transportExtraQuery: transportOverrides.extraQuery,
+        };
         if (logger.dontLogModelData) {
-            logger.debug('Response received');
+            logger.debug('Calling LLM');
         }
         else {
-            logger.debug(`Response received: ${JSON.stringify(response, null, 2)}`);
+            logger.debug(`Calling LLM. Request data: ${JSON.stringify(builtRequest.requestData, null, 2)}`);
         }
-        return response;
+        return builtRequest;
     }
     /**
      * Get a response from the OpenAI model using the Responses API.
@@ -1487,7 +1529,7 @@ export class OpenAIResponsesModel {
      */
     async getResponse(request) {
         const response = await withResponseSpan(async (span) => {
-            const response = await this.#fetchResponse(request, false);
+            const response = await this._fetchResponse(request, false);
             if (request.tracing) {
                 span.spanData.response_id = response.id;
                 span.spanData._input = request.input;
@@ -1527,10 +1569,11 @@ export class OpenAIResponsesModel {
                     span.spanData._input = request.input;
                 }
             }
-            const response = await this.#fetchResponse(request, true);
+            const response = await this._fetchResponse(request, true);
             let finalResponse;
             for await (const event of response) {
-                if (event.type === 'response.created') {
+                const eventType = event.type;
+                if (eventType === 'response.created') {
                     yield {
                         type: 'response_started',
                         providerData: {
@@ -1538,9 +1581,10 @@ export class OpenAIResponsesModel {
                         },
                     };
                 }
-                else if (event.type === 'response.completed') {
-                    finalResponse = event.response;
-                    const { response, ...remainingEvent } = event;
+                else if (isTerminalResponsesStreamEventType(eventType)) {
+                    const terminalEvent = event;
+                    finalResponse = terminalEvent.response;
+                    const { response, ...remainingEvent } = terminalEvent;
                     const { output, usage, id, ...remainingResponse } = response;
                     yield {
                         type: 'response_done',
@@ -1565,12 +1609,14 @@ export class OpenAIResponsesModel {
                         },
                         providerData: remainingEvent,
                     };
-                    yield {
-                        type: 'model',
-                        event: event,
-                    };
+                    if (eventType === 'response.completed') {
+                        yield {
+                            type: 'model',
+                            event: event,
+                        };
+                    }
                 }
-                else if (event.type === 'response.output_text.delta') {
+                else if (eventType === 'response.output_text.delta') {
                     const { delta, ...remainingEvent } = event;
                     yield {
                         type: 'output_text_delta',
@@ -1611,6 +1657,343 @@ export class OpenAIResponsesModel {
         }
     }
 }
+/**
+ * Model implementation that uses the OpenAI Responses API over a websocket transport.
+ *
+ * @see {@link https://developers.openai.com/api/docs/guides/websocket-mode}
+ */
+export class OpenAIResponsesWSModel extends OpenAIResponsesModel {
+    #websocketBaseURL;
+    #reuseConnection;
+    #wsConnection;
+    #wsConnectionIdentity;
+    #wsRequestLock = Promise.resolve();
+    constructor(client, model, options = {}) {
+        super(client, model);
+        this.#websocketBaseURL = options.websocketBaseURL;
+        this.#reuseConnection = options.reuseConnection ?? true;
+    }
+    async _fetchResponse(request, stream) {
+        // The websocket transport always uses streamed Responses events, then callers either
+        // consume the stream directly or collapse it into the final terminal response.
+        const builtRequest = this._buildResponsesCreateRequest(request, true);
+        if (stream) {
+            return this.#iterWebSocketResponseEvents(builtRequest);
+        }
+        let finalResponse;
+        for await (const event of this.#iterWebSocketResponseEvents(builtRequest)) {
+            const eventType = event.type;
+            if (isTerminalResponsesStreamEventType(eventType)) {
+                finalResponse = event
+                    .response;
+            }
+        }
+        if (!finalResponse) {
+            throw new Error('Responses websocket stream ended without a terminal response event.');
+        }
+        return finalResponse;
+    }
+    async close() {
+        await this.#dropWebSocketConnection();
+    }
+    async *#iterWebSocketResponseEvents(builtRequest) {
+        const requestTimeoutDeadline = this.#createWebSocketRequestTimeoutDeadline();
+        const releaseLock = await this.#acquireWebSocketRequestLock(builtRequest.signal, requestTimeoutDeadline);
+        let receivedAnyEvent = false;
+        let sawTerminalResponseEvent = false;
+        try {
+            throwIfAborted(builtRequest.signal);
+            const { frame, wsURL, headers } = await this.#prepareWebSocketRequest(builtRequest, requestTimeoutDeadline);
+            throwIfAborted(builtRequest.signal);
+            let connection = await this.#ensureWebSocketConnection(wsURL, headers, builtRequest.signal, requestTimeoutDeadline);
+            let reusedConnectionForCurrentAttempt = connection.reused;
+            let activeConnection = connection.connection;
+            const setActiveConnection = (nextConnection) => {
+                connection = nextConnection;
+                activeConnection = nextConnection.connection;
+                reusedConnectionForCurrentAttempt = nextConnection.reused;
+            };
+            throwIfAborted(builtRequest.signal);
+            const serializedFrame = JSON.stringify(frame);
+            const sendSerializedFrame = async () => {
+                try {
+                    await activeConnection.send(serializedFrame);
+                }
+                catch (error) {
+                    if (!isWebSocketNotOpenError(error)) {
+                        throw error;
+                    }
+                    setActiveConnection(await this.#reconnectWebSocketConnection(wsURL, headers, builtRequest.signal, requestTimeoutDeadline));
+                    await activeConnection.send(serializedFrame);
+                }
+            };
+            await sendSerializedFrame();
+            while (true) {
+                const rawFrame = await this.#nextWebSocketFrame(activeConnection, builtRequest.signal, requestTimeoutDeadline);
+                if (rawFrame === null) {
+                    if (!receivedAnyEvent && reusedConnectionForCurrentAttempt) {
+                        // The request frame was already sent on a reused socket. If the
+                        // socket closes before the first response event arrives, the server
+                        // may still be processing the request, so replaying `response.create`
+                        // can duplicate model work and tool side effects.
+                        receivedAnyEvent = true;
+                        throw new Error('Responses websocket connection closed after sending a request on a reused connection before any response events were received. The request may have been accepted, so the SDK will not automatically retry this websocket request.');
+                    }
+                    throw new ResponsesWebSocketInternalError('connection_closed_before_terminal_response_event', 'Responses websocket connection closed before a terminal response event.');
+                }
+                const payloadText = await webSocketFrameToText(rawFrame);
+                const payload = JSON.parse(payloadText);
+                const eventType = isRecord(payload) && typeof payload.type === 'string'
+                    ? payload.type
+                    : undefined;
+                if (eventType === 'error') {
+                    receivedAnyEvent = true;
+                    throw new Error(`Responses websocket error: ${JSON.stringify(payload)}`);
+                }
+                const event = payload;
+                const isTerminalResponseEvent = isTerminalResponsesStreamEventType(eventType);
+                receivedAnyEvent = true;
+                if (isTerminalResponseEvent) {
+                    sawTerminalResponseEvent = true;
+                }
+                yield event;
+                if (isTerminalResponseEvent) {
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            if (!receivedAnyEvent &&
+                !(error instanceof OpenAI.APIUserAbortError) &&
+                shouldWrapNoEventWebSocketError(error)) {
+                const wrappedError = new Error('Responses websocket connection closed before any response events were received. The feature may not be enabled for this account or model yet.');
+                if (error instanceof Error) {
+                    wrappedError.cause = error;
+                }
+                throw wrappedError;
+            }
+            throw error;
+        }
+        finally {
+            const shouldDropConnection = !sawTerminalResponseEvent || !this.#reuseConnection;
+            const dropConnectionPromise = shouldDropConnection
+                ? this.#dropWebSocketConnection()
+                : undefined;
+            releaseLock();
+            await dropConnectionPromise;
+        }
+    }
+    async #prepareWebSocketRequest(builtRequest, requestTimeoutDeadline) {
+        const wsURL = this.#prepareWebSocketURL(builtRequest.transportExtraQuery);
+        const headers = await this.#mergeWebSocketHeaders(wsURL, builtRequest.transportExtraHeaders, builtRequest.signal, requestTimeoutDeadline);
+        const frame = {
+            ...builtRequest.requestData,
+            type: 'response.create',
+            stream: true,
+        };
+        return { frame, wsURL, headers };
+    }
+    async #mergeWebSocketHeaders(wsURL, extraHeaders, signal, requestTimeoutDeadline) {
+        await this.#awaitWebSocketRequestTimedOperation(this.#refreshClientApiKey(), signal, requestTimeoutDeadline, (configuredTimeoutMs) => `Responses websocket auth header preparation timed out after ${configuredTimeoutMs}ms.`);
+        const headerAccumulator = createHeaderAccumulator();
+        const clientWithInternals = this._client;
+        const handshakeURL = new URL(wsURL);
+        const handshakeQuery = searchParamsToAuthHeaderQuery(handshakeURL.searchParams);
+        const authHeaders = typeof clientWithInternals.authHeaders === 'function'
+            ? await this.#awaitWebSocketRequestTimedOperation(clientWithInternals.authHeaders({
+                method: 'get',
+                path: handshakeURL.pathname,
+                ...(handshakeQuery ? { query: handshakeQuery } : {}),
+            }), signal, requestTimeoutDeadline, (configuredTimeoutMs) => `Responses websocket auth header preparation timed out after ${configuredTimeoutMs}ms.`)
+            : undefined;
+        applyHeadersToAccumulator(headerAccumulator, authHeaders);
+        if (typeof clientWithInternals.authHeaders !== 'function' &&
+            typeof this._client.apiKey === 'string' &&
+            this._client.apiKey.length > 0 &&
+            this._client.apiKey !== 'Missing Key') {
+            applyHeadersToAccumulator(headerAccumulator, {
+                Authorization: `Bearer ${this._client.apiKey}`,
+            });
+        }
+        if (this._client.organization) {
+            applyHeadersToAccumulator(headerAccumulator, {
+                'OpenAI-Organization': this._client.organization,
+            });
+        }
+        if (this._client.project) {
+            applyHeadersToAccumulator(headerAccumulator, {
+                'OpenAI-Project': this._client.project,
+            });
+        }
+        applyHeadersToAccumulator(headerAccumulator, clientWithInternals._options?.defaultHeaders);
+        applyHeadersToAccumulator(headerAccumulator, HEADERS);
+        applyHeadersToAccumulator(headerAccumulator, extraHeaders, {
+            allowBlockedOverride: true,
+        });
+        return headerAccumulatorToRecord(headerAccumulator);
+    }
+    #prepareWebSocketURL(extraQuery) {
+        const baseURL = new URL(this.#websocketBaseURL ?? this._client.baseURL);
+        const explicitBaseQuery = typeof this.#websocketBaseURL === 'string'
+            ? new URLSearchParams(baseURL.search)
+            : undefined;
+        const clientWithInternals = this._client;
+        if (baseURL.protocol === 'https:') {
+            baseURL.protocol = 'wss:';
+        }
+        else if (baseURL.protocol === 'http:') {
+            baseURL.protocol = 'ws:';
+        }
+        else if (baseURL.protocol !== 'ws:' && baseURL.protocol !== 'wss:') {
+            throw new UserError(`Unsupported websocket base URL protocol: ${baseURL.protocol}`);
+        }
+        baseURL.pathname = ensureResponsesWebSocketPath(baseURL.pathname);
+        mergeQueryParamsIntoURL(baseURL, clientWithInternals._options?.defaultQuery);
+        if (explicitBaseQuery && Array.from(explicitBaseQuery.keys()).length > 0) {
+            const explicitTopLevelKeys = new Set();
+            for (const key of explicitBaseQuery.keys()) {
+                const bracketIndex = key.indexOf('[');
+                explicitTopLevelKeys.add(bracketIndex >= 0 ? key.slice(0, bracketIndex) : key);
+            }
+            for (const topLevelKey of explicitTopLevelKeys) {
+                for (const existingKey of Array.from(baseURL.searchParams.keys())) {
+                    if (existingKey === topLevelKey ||
+                        existingKey.startsWith(`${topLevelKey}[`)) {
+                        baseURL.searchParams.delete(existingKey);
+                    }
+                }
+            }
+            for (const [key, value] of explicitBaseQuery.entries()) {
+                baseURL.searchParams.append(key, value);
+            }
+        }
+        mergeQueryParamsIntoURL(baseURL, extraQuery);
+        return baseURL.toString();
+    }
+    async #ensureWebSocketConnection(wsURL, headers, signal, requestTimeoutDeadline) {
+        const identity = this.#getConnectionIdentity(wsURL, headers);
+        if (this.#wsConnection &&
+            this.#wsConnectionIdentity &&
+            this.#wsConnectionIdentity === identity &&
+            this.#wsConnection.isReusable()) {
+            return { connection: this.#wsConnection, reused: true };
+        }
+        await this.#dropWebSocketConnection();
+        const connectTimeout = this.#resolveWebSocketRequestTimeout(requestTimeoutDeadline, (configuredTimeoutMs) => `Responses websocket connection timed out before opening after ${configuredTimeoutMs}ms.`);
+        this.#wsConnection = await ResponsesWebSocketConnection.connect(wsURL, headers, signal, connectTimeout.timeoutMs, connectTimeout.errorMessage);
+        this.#wsConnectionIdentity = identity;
+        return { connection: this.#wsConnection, reused: false };
+    }
+    async #reconnectWebSocketConnection(wsURL, headers, signal, requestTimeoutDeadline) {
+        await this.#dropWebSocketConnection();
+        throwIfAborted(signal);
+        const connection = await this.#ensureWebSocketConnection(wsURL, headers, signal, requestTimeoutDeadline);
+        throwIfAborted(signal);
+        return connection;
+    }
+    #getConnectionIdentity(wsURL, headers) {
+        const normalizedHeaders = Object.entries(headers)
+            .map(([key, value]) => [key.toLowerCase(), value])
+            .sort(([leftKey, leftValue], [rightKey, rightValue]) => `${leftKey}:${leftValue}`.localeCompare(`${rightKey}:${rightValue}`));
+        return JSON.stringify([wsURL, normalizedHeaders]);
+    }
+    async #dropWebSocketConnection() {
+        const connectionToClose = this.#wsConnection;
+        if (!connectionToClose) {
+            this.#wsConnectionIdentity = undefined;
+            return;
+        }
+        // Detach cached state before awaiting close so queued requests can proceed
+        // without racing against this teardown path.
+        this.#wsConnection = undefined;
+        this.#wsConnectionIdentity = undefined;
+        try {
+            await connectionToClose.close();
+        }
+        catch {
+            // Ignore close errors and reset the cached connection.
+        }
+    }
+    async #acquireWebSocketRequestLock(signal, requestTimeoutDeadline) {
+        throwIfAborted(signal);
+        const queueWaitTimeout = this.#resolveWebSocketRequestTimeout(requestTimeoutDeadline, (configuredTimeoutMs) => `Responses websocket request queue wait timed out after ${configuredTimeoutMs}ms.`);
+        const previousLock = this.#wsRequestLock;
+        let released = false;
+        let resolveOwnLock;
+        const ownLock = new Promise((resolve) => {
+            resolveOwnLock = resolve;
+        });
+        const releaseLock = () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            resolveOwnLock();
+        };
+        this.#wsRequestLock = previousLock.then(() => ownLock);
+        try {
+            await withAbortSignal(withTimeout(previousLock, queueWaitTimeout.timeoutMs, queueWaitTimeout.errorMessage), signal);
+            throwIfAborted(signal);
+            return releaseLock;
+        }
+        catch (error) {
+            releaseLock();
+            throw error;
+        }
+    }
+    async #refreshClientApiKey() {
+        const clientWithInternals = this._client;
+        if (typeof clientWithInternals._callApiKey === 'function') {
+            await clientWithInternals._callApiKey();
+        }
+    }
+    #getWebSocketFrameReadTimeoutMs() {
+        const clientWithTimeout = this._client;
+        const timeoutCandidate = typeof clientWithTimeout.timeout === 'number'
+            ? clientWithTimeout.timeout
+            : clientWithTimeout._options?.timeout;
+        if (typeof timeoutCandidate === 'number') {
+            return timeoutCandidate;
+        }
+        return OpenAI.DEFAULT_TIMEOUT;
+    }
+    #createWebSocketRequestTimeoutDeadline() {
+        const timeoutMs = this.#getWebSocketFrameReadTimeoutMs();
+        if (typeof timeoutMs !== 'number' ||
+            !Number.isFinite(timeoutMs) ||
+            timeoutMs <= 0) {
+            return undefined;
+        }
+        return {
+            configuredTimeoutMs: timeoutMs,
+            deadlineAtMs: Date.now() + timeoutMs,
+        };
+    }
+    #resolveWebSocketRequestTimeout(requestTimeoutDeadline, errorMessageForConfiguredTimeout) {
+        const configuredTimeoutMs = requestTimeoutDeadline?.configuredTimeoutMs ??
+            this.#getWebSocketFrameReadTimeoutMs();
+        const safeConfiguredTimeoutMs = typeof configuredTimeoutMs === 'number'
+            ? configuredTimeoutMs
+            : OpenAI.DEFAULT_TIMEOUT;
+        const errorMessage = errorMessageForConfiguredTimeout(safeConfiguredTimeoutMs);
+        if (!requestTimeoutDeadline) {
+            return { timeoutMs: configuredTimeoutMs, errorMessage };
+        }
+        const remainingTimeoutMs = Math.ceil(requestTimeoutDeadline.deadlineAtMs - Date.now());
+        if (remainingTimeoutMs <= 0) {
+            throw new Error(errorMessage);
+        }
+        return { timeoutMs: remainingTimeoutMs, errorMessage };
+    }
+    async #awaitWebSocketRequestTimedOperation(promise, signal, requestTimeoutDeadline, errorMessageForConfiguredTimeout) {
+        const timeout = this.#resolveWebSocketRequestTimeout(requestTimeoutDeadline, errorMessageForConfiguredTimeout);
+        return await withAbortSignal(withTimeout(promise, timeout.timeoutMs, timeout.errorMessage), signal);
+    }
+    async #nextWebSocketFrame(connection, signal, requestTimeoutDeadline) {
+        const frameReadTimeout = this.#resolveWebSocketRequestTimeout(requestTimeoutDeadline, (configuredTimeoutMs) => `Responses websocket frame read timed out after ${configuredTimeoutMs}ms.`);
+        return await withTimeout(connection.nextFrame(signal), frameReadTimeout.timeoutMs, frameReadTimeout.errorMessage);
+    }
+}
 /**
  * Sending an empty string for instructions can override the prompt parameter.
  * Thus, this method checks if the instructions is an empty string and returns undefined if it is.
@@ -1626,6 +2009,24 @@ function normalizeInstructions(instructions) {
     }
     return undefined;
 }
+function searchParamsToAuthHeaderQuery(searchParams) {
+    const query = {};
+    let hasEntries = false;
+    for (const [key, value] of searchParams.entries()) {
+        hasEntries = true;
+        const existingValue = query[key];
+        if (typeof existingValue === 'undefined') {
+            query[key] = value;
+            continue;
+        }
+        if (Array.isArray(existingValue)) {
+            existingValue.push(value);
+            continue;
+        }
+        query[key] = [existingValue, value];
+    }
+    return hasEntries ? query : undefined;
+}
 function toRequestUsageEntry(usage, endpoint) {
     return new RequestUsage({
         inputTokens: usage?.input_tokens ?? 0,