openai 7.16.0 → 7.18.0

package/src/providers/bedrock/aws.ts

@@ -96,11 +96,12 @@ function validateStaticCredentials(options: BedrockProviderOptions): AwsCredenti
   return {
     accessKeyId: options.accessKeyId,
     secretAccessKey: options.secretAccessKey,
+    // Spread creates an own data property without invoking inherited setters or changing the object prototype.
     ...(options.sessionToken ? { sessionToken: options.sessionToken } : {}),
   };
 }
 
-function requestTarget(parsedURL: URL): { path: string; query: Record<string, string | string[]> } {
+function requestTarget(parsedURL: URL) {
   const query: Record<string, string | string[]> = Object.create(null);
   for (const [name, value] of parsedURL.searchParams) {
     if (name === '__proto__') {
@@ -195,6 +196,7 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
   }
 
   async prepareRequest(request: FinalizedRequestInit, context: ProviderRequestContext): Promise<void> {
+    // SAFETY: process is optional outside Node; the native process tag is checked before using Node-specific signing and credential behavior.
     if (Object.prototype.toString.call((globalThis as any).process) !== '[object process]') {
       throw new Errors.OpenAIError(
         'Bedrock AWS credential authentication is only supported in Node.js and compatible server runtimes. Use bearer authentication in this runtime.',
@@ -230,10 +232,12 @@ class BedrockSigV4Auth implements BedrockRequestAuth {
         this.signatureV4().sign({
           protocol: parsedURL.protocol,
           hostname: parsedURL.hostname,
+          // Spread creates an own data property without invoking inherited setters or changing the object prototype.
           ...(parsedURL.port ? { port: Number(parsedURL.port) } : {}),
           method,
           ...target,
           headers: Object.fromEntries(headers.entries()),
+          // Spread creates an own data property without invoking inherited setters or changing the object prototype.
           ...(body === undefined ? {} : { body }),
         }),
       failureMessage: this.options.usesDefaultChain

package/src/realtime/internal-base.ts

@@ -13,6 +13,7 @@ import { assertX509WebSocketSupported } from '../internal/auth/x509-workload-ide
 /** Parses frame data without exposing malformed payloads through JSON syntax errors. */
 export function parseRealtimeEvent(data: string): RealtimeServerEvent {
   try {
+    // SAFETY: RealtimeServerEvent is the API wire contract; JSON syntax is checked here while future event types remain accepted at runtime.
     return JSON.parse(data) as RealtimeServerEvent;
   } catch (error) {
     if (error instanceof SyntaxError) {
@@ -87,6 +88,7 @@ type RealtimeEvents = Simplify<
           type: EventType;
         }
       >,
+      // oxlint-disable-next-line anti-slop/no-unknown-returns -- Preserve the published event-callback contract, which accepts and ignores arbitrary return values.
     ) => unknown;
   }
 >;

package/src/realtime/websocket.ts

@@ -43,6 +43,7 @@ function isRunningInBrowserOrBrowserWorker(): boolean {
     return true;
   }
 
+  // SAFETY: RuntimeScope describes optional host capabilities; the following predicates verify their presence and value before use.
   const scope = globalThis as RuntimeScope;
   return (
     typeof scope.WorkerGlobalScope === 'function' &&
@@ -61,6 +62,7 @@ function isRunningInBrowserOrBrowserWorker(): boolean {
 
 /** Reports whether the runtime supports request headers in native WebSocket options. */
 function supportsWebSocketRequestHeaders(): boolean {
+  // SAFETY: RuntimeScope describes optional host capabilities; the following predicates verify their presence and value before use.
   const scope = globalThis as RuntimeScope;
   if (
     isRunningInBrowserOrBrowserWorker() ||
@@ -183,7 +185,9 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
   ) {
     super();
     let apiKey = getRealtimeAPIKey(client, props.__apiKey);
+    // SAFETY: The supplied OpenAI client owns _options; these compatibility reads preserve its provider and browser-consent settings.
     const hasProvider = typeof (client as any)?._options?.apiKey === 'function';
+    // SAFETY: The supplied OpenAI client owns _options; these compatibility reads preserve its provider and browser-consent settings.
     const dangerouslyAllowBrowser =
       props.dangerouslyAllowBrowser ??
       (client as any)?._options?.dangerouslyAllowBrowser ??
@@ -257,7 +261,12 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     });
 
     this.socket.addEventListener('error', (event: any) => {
-      this._onError(null, event.message, null);
+      // Native ErrorEvents can carry an empty message while `error` still holds the failure.
+      const cause = event.error ?? null;
+      const message = [event.message, cause?.message].find(
+        (value) => typeof value === 'string' && value !== '',
+      );
+      this._onError(null, message ?? 'unknown error', cause);
     });
   }
 
@@ -317,6 +326,7 @@ export class OpenAIRealtimeWebSocket extends OpenAIRealtimeEmitter {
     return new OpenAIRealtimeWebSocket(
       {
         ...connection,
+        // Preserve explicit browser consent as an own data property without invoking an inherited setter.
         ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
         __resolvedApiKey: isApiKeyProvider,
         __apiKey: apiKey,

package/src/realtime/ws.ts

@@ -55,6 +55,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     super();
     client ??= new OpenAI();
     const apiKey = props.__apiKey === undefined ? client.apiKey : props.__apiKey;
+    // SAFETY: The supplied OpenAI client owns _options; this read detects its existing API-key provider without changing its public surface.
     const hasProvider = typeof (client as any)?._options?.apiKey === 'function';
     if (hasProvider && !props.__resolvedApiKey) {
       throw new Error(
@@ -69,6 +70,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
     const headers = {
       'User-Agent': `${client.constructor.name}/JS ${VERSION}`,
       ...props.options?.headers,
+      // A credential must be an own data property without invoking an inherited setter.
       ...(isAzure(client) && !props.__resolvedApiKey ? {} : { Authorization: `Bearer ${apiKey}` }),
     };
 
@@ -178,6 +180,7 @@ export class OpenAIRealtimeWS extends OpenAIRealtimeEmitter {
           ...props.options,
           headers: {
             ...props.options?.headers,
+            // A credential must be an own data property without invoking an inherited setter.
             ...(isApiKeyProvider ? {} : { 'api-key': apiKey }),
           },
         },

package/src/resources/beta/agents/agents.ts

@@ -4048,6 +4048,7 @@ export interface SessionTurnError {
    * - `session_budget_exceeded` - The session has reached its usage budget.
    * - `usage_limit_exceeded` - The organization has reached a usage, plan, or
    *   billing limit.
+   * - `credit_balance_exhausted` - The organization has no API credits remaining.
    * - `rate_limit_exceeded` - The request exceeds the available rate limit.
    * - `server_overloaded` - The model service is temporarily overloaded.
    * - `cyber_policy` - The request was rejected by a safety policy.
@@ -4070,6 +4071,7 @@ export interface SessionTurnError {
     | 'context_length_exceeded'
     | 'session_budget_exceeded'
     | 'usage_limit_exceeded'
+    | 'credit_balance_exhausted'
     | 'rate_limit_exceeded'
     | 'server_overloaded'
     | 'cyber_policy'

package/src/resources/beta/agents/sessions/sessions.ts

@@ -100,7 +100,8 @@ export class Sessions extends APIResource {
   }
 
   /**
-   * Updates session metadata. Omitted fields are unchanged. See
+   * Updates session metadata, model, reasoning effort, or service tier. Model
+   * settings apply to subsequent turns. Omitted fields are unchanged. See
    * [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).
    *
    * @example
@@ -277,6 +278,11 @@ export interface SessionCreateParamsStreaming extends SessionCreateParamsBase {
 }
 
 export interface SessionUpdateParams {
+  /**
+   * Model settings for subsequent turns. Omitted fields stay unchanged.
+   */
+  agent?: SessionUpdateParams.Agent;
+
   /**
    * Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it.
    * Up to 16 string key-value pairs, with keys up to 64 and values up to 512
@@ -285,6 +291,46 @@ export interface SessionUpdateParams {
   metadata?: { [key: string]: string } | null;
 }
 
+export namespace SessionUpdateParams {
+  /**
+   * Model settings for subsequent turns. Omitted fields stay unchanged.
+   */
+  export interface Agent {
+    /**
+     * The model for subsequent turns. Omit to keep the current model.
+     */
+    model?: string;
+
+    /**
+     * Reasoning settings to update. Omit to keep the current effort.
+     */
+    reasoning?: Agent.Reasoning;
+
+    /**
+     * The service tier used for model requests.
+     *
+     * - `auto` - Selects the service tier automatically.
+     * - `default` - Uses the default service tier.
+     * - `flex` - Uses the flex service tier.
+     * - `priority` - Uses the priority service tier.
+     * - `fast` - Uses the fast service tier.
+     */
+    service_tier?: 'auto' | 'default' | 'flex' | 'priority' | 'fast' | null;
+  }
+
+  export namespace Agent {
+    /**
+     * Reasoning settings to update. Omit to keep the current effort.
+     */
+    export interface Reasoning {
+      /**
+       * The amount of reasoning effort the model should use.
+       */
+      effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null;
+    }
+  }
+}
+
 export interface SessionListParams extends CursorPageParams {
   /**
    * Only return sessions whose root agent has this ID. Omit to return sessions for

package/src/resources/beta/beta.ts

@@ -217,6 +217,7 @@ import {
   BetaResponseCodeInterpreterCallInProgressEvent,
   BetaResponseCodeInterpreterCallInterpretingEvent,
   BetaResponseCodeInterpreterToolCall,
+  BetaResponseCompactionCompactingEvent,
   BetaResponseCompactionItem,
   BetaResponseCompactionItemParam,
   BetaResponseCompletedEvent,
@@ -588,6 +589,7 @@ export declare namespace Beta {
     type BetaResponseCodeInterpreterCallInProgressEvent as BetaResponseCodeInterpreterCallInProgressEvent,
     type BetaResponseCodeInterpreterCallInterpretingEvent as BetaResponseCodeInterpreterCallInterpretingEvent,
     type BetaResponseCodeInterpreterToolCall as BetaResponseCodeInterpreterToolCall,
+    type BetaResponseCompactionCompactingEvent as BetaResponseCompactionCompactingEvent,
     type BetaResponseCompactionItem as BetaResponseCompactionItem,
     type BetaResponseCompactionItemParam as BetaResponseCompactionItemParam,
     type BetaResponseCompletedEvent as BetaResponseCompletedEvent,

package/src/resources/beta/index.ts

@@ -165,6 +165,7 @@ export {
   type BetaResponseCodeInterpreterCallInProgressEvent,
   type BetaResponseCodeInterpreterCallInterpretingEvent,
   type BetaResponseCodeInterpreterToolCall,
+  type BetaResponseCompactionCompactingEvent,
   type BetaResponseCompactionItem,
   type BetaResponseCompactionItemParam,
   type BetaResponseCompletedEvent,

package/src/resources/beta/responses/index.ts

@@ -40,6 +40,7 @@ export {
   type BetaResponseCodeInterpreterCallInProgressEvent,
   type BetaResponseCodeInterpreterCallInterpretingEvent,
   type BetaResponseCodeInterpreterToolCall,
+  type BetaResponseCompactionCompactingEvent,
   type BetaResponseCompactionItem,
   type BetaResponseCompactionItemParam,
   type BetaResponseCompletedEvent,

package/src/resources/beta/responses/internal-base.ts

@@ -27,13 +27,21 @@ type WebSocketErrorEvent = Extract<ResponsesAPI.BetaResponsesServerEvent, { type
 export class WebSocketError extends OpenAIError {
   /**
    * The error data that the API sent back in an error event.
+   *
+   * This property is non-enumerable to avoid exposing the event through
+   * JSON serialization, object spread, or Object.assign.
    */
   error?: WebSocketErrorEvent | undefined;
 
   constructor(message: string, event: WebSocketErrorEvent | null) {
     super(message);
 
-    this.error = event ?? undefined;
+    Object.defineProperty(this, 'error', {
+      value: event ?? undefined,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
   }
 }
 
@@ -77,13 +85,8 @@ export abstract class ResponsesEmitter extends EventEmitter<WebSocketEvents> {
   protected _onError(event: null, message: string, cause: any): void;
   protected _onError(event: WebSocketErrorEvent, message?: string | undefined): void;
   protected _onError(event: WebSocketErrorEvent | null, message?: string | undefined, cause?: any): void {
-    const eventMessage = event && ('error' in event ? event.error?.message : event.message);
-    message = message ?? eventMessage ?? safeJSONStringify(event) ?? 'unknown error';
-    try {
-      message = String(message);
-    } catch {
-      message = '[unserializable error value]';
-    }
+    const safeMessage = safeWebSocketErrorMessage(event, message);
+    message = safeMessage ?? 'unknown error';
 
     if (!this._hasListener('error')) {
       const error = new WebSocketError(
@@ -114,10 +117,20 @@ export function buildURL(client: OpenAI, parameters: Record<string, unknown>): U
   return url;
 }
 
-function safeJSONStringify(value: unknown): string | null {
+function safeWebSocketErrorMessage(event: unknown, message: unknown): string | undefined {
+  if (typeof message === 'string') return message;
+  if (typeof event !== 'object' || event === null) return undefined;
+
   try {
-    return JSON.stringify(value);
+    const error = Object.getOwnPropertyDescriptor(event, 'error')?.value;
+    const nestedMessage =
+      typeof error === 'object' && error !== null
+        ? Object.getOwnPropertyDescriptor(error, 'message')?.value
+        : undefined;
+    const eventMessage = Object.getOwnPropertyDescriptor(event, 'message')?.value;
+    const candidate = typeof nestedMessage === 'string' ? nestedMessage : eventMessage;
+    return typeof candidate === 'string' ? candidate : undefined;
   } catch {
-    return null;
+    return undefined;
   }
 }

package/src/resources/beta/responses/responses.ts

@@ -1163,7 +1163,6 @@ export interface BetaResponse {
     | 'gpt-5.1'
     | 'gpt-5.1-2025-11-13'
     | 'gpt-5.1-codex'
-    | 'gpt-5.1-mini'
     | 'gpt-5.1-chat-latest'
     | 'gpt-5'
     | 'gpt-5-mini'
@@ -1194,6 +1193,8 @@ export interface BetaResponse {
     | 'gpt-4o-2024-11-20'
     | 'gpt-4o-2024-08-06'
     | 'gpt-4o-2024-05-13'
+    | 'gpt-audio-mini'
+    | 'gpt-audio-mini-2025-12-15'
     | 'gpt-4o-audio-preview'
     | 'gpt-4o-audio-preview-2024-10-01'
     | 'gpt-4o-audio-preview-2024-12-17'
@@ -1227,6 +1228,7 @@ export interface BetaResponse {
     | 'gpt-3.5-turbo-1106'
     | 'gpt-3.5-turbo-0125'
     | 'gpt-3.5-turbo-16k-0613'
+    | 'gpt-5.1-mini'
     | 'o1-pro'
     | 'o1-pro-2025-03-19'
     | 'o3-pro'
@@ -2443,6 +2445,49 @@ export namespace BetaResponseCodeInterpreterToolCall {
   }
 }
 
+/**
+ * Emitted when new summary content is sampled for a compaction trigger. Contains
+ * no summary content.
+ */
+export interface BetaResponseCompactionCompactingEvent {
+  /**
+   * The ID of the compaction output item.
+   */
+  item_id: string;
+
+  /**
+   * The index of the compaction output item.
+   */
+  output_index: number;
+
+  /**
+   * The sequence number of the event that was emitted.
+   */
+  sequence_number: number;
+
+  /**
+   * The type of the event, always `response.compaction.compacting`.
+   */
+  type: 'response.compaction.compacting';
+
+  /**
+   * The agent that owns this multi-agent streaming event.
+   */
+  agent?: BetaResponseCompactionCompactingEvent.Agent;
+}
+
+export namespace BetaResponseCompactionCompactingEvent {
+  /**
+   * The agent that owns this multi-agent streaming event.
+   */
+  export interface Agent {
+    /**
+     * The canonical name of the agent that produced this item.
+     */
+    agent_name: string;
+  }
+}
+
 /**
  * A compaction item generated by the
  * [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact).
@@ -10942,6 +10987,7 @@ export type BetaResponseStreamEvent =
   | BetaResponseCodeInterpreterCallCompletedEvent
   | BetaResponseCodeInterpreterCallInProgressEvent
   | BetaResponseCodeInterpreterCallInterpretingEvent
+  | BetaResponseCompactionCompactingEvent
   | BetaResponseCompletedEvent
   | BetaResponseContentPartAddedEvent
   | BetaResponseContentPartDoneEvent
@@ -11696,7 +11742,6 @@ export namespace BetaResponsesClientEvent {
       | 'gpt-5.1'
       | 'gpt-5.1-2025-11-13'
       | 'gpt-5.1-codex'
-      | 'gpt-5.1-mini'
       | 'gpt-5.1-chat-latest'
       | 'gpt-5'
       | 'gpt-5-mini'
@@ -11727,6 +11772,8 @@ export namespace BetaResponsesClientEvent {
       | 'gpt-4o-2024-11-20'
       | 'gpt-4o-2024-08-06'
       | 'gpt-4o-2024-05-13'
+      | 'gpt-audio-mini'
+      | 'gpt-audio-mini-2025-12-15'
       | 'gpt-4o-audio-preview'
       | 'gpt-4o-audio-preview-2024-10-01'
       | 'gpt-4o-audio-preview-2024-12-17'
@@ -11760,6 +11807,7 @@ export namespace BetaResponsesClientEvent {
       | 'gpt-3.5-turbo-1106'
       | 'gpt-3.5-turbo-0125'
       | 'gpt-3.5-turbo-16k-0613'
+      | 'gpt-5.1-mini'
       | 'o1-pro'
       | 'o1-pro-2025-03-19'
       | 'o3-pro'
@@ -12134,6 +12182,12 @@ export namespace BetaResponsesClientEvent {
        */
       mode?: 'implicit' | 'explicit';
 
+      /**
+       * Prepares the prompt cache without generating output. Defaults to `false`. When
+       * set to `true`, overrides the `generate` field to `false`.
+       */
+      prewarm?: boolean;
+
       /**
        * The minimum lifetime applied to every implicit and explicit cache breakpoint
        * written by the request. Defaults to `30m`, which is currently the only supported
@@ -12231,6 +12285,7 @@ export type BetaResponsesServerEvent =
   | BetaResponsesServerEvent.BetaResponseCodeInterpreterCallWsCompleted
   | BetaResponsesServerEvent.BetaResponseCodeInterpreterCallInWsProgress
   | BetaResponsesServerEvent.BetaResponseCodeInterpreterCallWsInterpreting
+  | BetaResponsesServerEvent.BetaResponseCompactionWsCompacting
   | BetaResponsesServerEvent.BetaResponseWsCompleted
   | BetaResponsesServerEvent.BetaResponseContentPartWsAdded
   | BetaResponsesServerEvent.BetaResponseContentPartWsDone
@@ -12387,6 +12442,18 @@ export namespace BetaResponsesServerEvent {
     stream_id?: string;
   }
 
+  /**
+   * Emitted when new summary content is sampled for a compaction trigger. Contains
+   * no summary content.
+   */
+  export interface BetaResponseCompactionWsCompacting extends BetaResponseCompactionCompactingEvent {
+    /**
+     * The WebSocket lane that emitted this event. This field is present when the
+     * originating `response.create` event supplied a `stream_id`.
+     */
+    stream_id?: string;
+  }
+
   /**
    * Emitted when the model response is complete.
    */
@@ -13926,7 +13993,6 @@ export interface ResponseCreateParamsBase {
     | 'gpt-5.1'
     | 'gpt-5.1-2025-11-13'
     | 'gpt-5.1-codex'
-    | 'gpt-5.1-mini'
     | 'gpt-5.1-chat-latest'
     | 'gpt-5'
     | 'gpt-5-mini'
@@ -13957,6 +14023,8 @@ export interface ResponseCreateParamsBase {
     | 'gpt-4o-2024-11-20'
     | 'gpt-4o-2024-08-06'
     | 'gpt-4o-2024-05-13'
+    | 'gpt-audio-mini'
+    | 'gpt-audio-mini-2025-12-15'
     | 'gpt-4o-audio-preview'
     | 'gpt-4o-audio-preview-2024-10-01'
     | 'gpt-4o-audio-preview-2024-12-17'
@@ -13990,6 +14058,7 @@ export interface ResponseCreateParamsBase {
     | 'gpt-3.5-turbo-1106'
     | 'gpt-3.5-turbo-0125'
     | 'gpt-3.5-turbo-16k-0613'
+    | 'gpt-5.1-mini'
     | 'o1-pro'
     | 'o1-pro-2025-03-19'
     | 'o3-pro'
@@ -14365,6 +14434,12 @@ export namespace ResponseCreateParams {
      */
     mode?: 'implicit' | 'explicit';
 
+    /**
+     * Prepares the prompt cache without generating output. Defaults to `false`. When
+     * set to `true`, overrides the `generate` field to `false`.
+     */
+    prewarm?: boolean;
+
     /**
      * The minimum lifetime applied to every implicit and explicit cache breakpoint
      * written by the request. Defaults to `30m`, which is currently the only supported
@@ -14588,7 +14663,6 @@ export interface ResponseCompactParams {
     | 'gpt-5.1'
     | 'gpt-5.1-2025-11-13'
     | 'gpt-5.1-codex'
-    | 'gpt-5.1-mini'
     | 'gpt-5.1-chat-latest'
     | 'gpt-5'
     | 'gpt-5-mini'
@@ -14619,6 +14693,8 @@ export interface ResponseCompactParams {
     | 'gpt-4o-2024-11-20'
     | 'gpt-4o-2024-08-06'
     | 'gpt-4o-2024-05-13'
+    | 'gpt-audio-mini'
+    | 'gpt-audio-mini-2025-12-15'
     | 'gpt-4o-audio-preview'
     | 'gpt-4o-audio-preview-2024-10-01'
     | 'gpt-4o-audio-preview-2024-12-17'
@@ -14652,6 +14728,7 @@ export interface ResponseCompactParams {
     | 'gpt-3.5-turbo-1106'
     | 'gpt-3.5-turbo-0125'
     | 'gpt-3.5-turbo-16k-0613'
+    | 'gpt-5.1-mini'
     | 'o1-pro'
     | 'o1-pro-2025-03-19'
     | 'o3-pro'
@@ -14820,6 +14897,7 @@ export declare namespace Responses {
     type BetaResponseCodeInterpreterCallInProgressEvent as BetaResponseCodeInterpreterCallInProgressEvent,
     type BetaResponseCodeInterpreterCallInterpretingEvent as BetaResponseCodeInterpreterCallInterpretingEvent,
     type BetaResponseCodeInterpreterToolCall as BetaResponseCodeInterpreterToolCall,
+    type BetaResponseCompactionCompactingEvent as BetaResponseCompactionCompactingEvent,
     type BetaResponseCompactionItem as BetaResponseCompactionItem,
     type BetaResponseCompactionItemParam as BetaResponseCompactionItemParam,
     type BetaResponseCompletedEvent as BetaResponseCompletedEvent,

package/src/resources/beta/responses/ws-base.ts

@@ -7,6 +7,8 @@ import { type WebSocketLike, ReadyState } from '../../../internal/ws-adapter';
 import {
   SendQueue,
   getMaxBufferedEvents,
+  recordWebSocketError,
+  rawByteLength,
   type WebSocketStreamOptions,
   flattenRawData,
   isRecoverableClose,
@@ -19,6 +21,19 @@ import * as ResponsesAPI from './responses';
 import { OpenAI } from '../../../client';
 import { OpenAIError } from '../../../core/error';
 
+const webSocketEventPayloads = new WeakMap<object, string>();
+const webSocketEventBytes = new WeakMap<object, number>();
+
+/** Original wire size, available only during synchronous event notification. @internal */
+export function getWebSocketEventBytes(event: object): number | undefined {
+  return webSocketEventBytes.get(event);
+}
+
+/** Original JSON, available only during synchronous event notification. @internal */
+export function getWebSocketEventPayload(event: object): string | undefined {
+  return webSocketEventPayloads.get(event);
+}
+
 export interface ResponsesWSReconnectOptions {
   /**
    * Called before each reconnect attempt. Return an object with
@@ -103,7 +118,11 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     this.socket = this._connect();
   }
 
-  /** Creates a platform-specific WebSocket for the given URL and auth headers. */
+  /**
+   * Creates a platform-specific WebSocket for the given URL and captured client auth headers.
+   * The transport must supply or validate its final credentials before connecting;
+   * these headers may be empty when authentication is managed by the transport.
+   */
   protected abstract _createSocket(url: URL, authHeaders: Record<string, string>): TSocket;
 
   send(event: ResponsesAPI.BetaResponsesClientEvent) {
@@ -453,7 +472,14 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
         return;
       }
 
-      this._emit('event', event);
+      webSocketEventBytes.set(event, rawByteLength(data));
+      webSocketEventPayloads.set(event, text);
+      try {
+        this._emit('event', event);
+      } finally {
+        webSocketEventBytes.delete(event);
+        webSocketEventPayloads.delete(event);
+      }
 
       if (event.type === 'error') {
         this._onError(event);
@@ -464,6 +490,7 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     });
 
     socket.on('error', (err: Error) => {
+      recordWebSocketError(socket, err);
       // Suppress transient errors during reconnection — the retry loop
       // already handles them and will surface a close if retries exhaust.
       if (this._isReconnecting) return;
@@ -696,9 +723,7 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
   }
 
   protected _authHeaders(): Record<string, string> {
-    if (this._client.apiKey) {
-      return { Authorization: `Bearer ${this._client.apiKey}` };
-    }
-    return {};
+    const apiKey = this._client.apiKey;
+    return typeof apiKey === 'string' && apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
   }
 }

package/src/resources/beta/responses/ws.ts

@@ -4,13 +4,17 @@ import * as WS from 'ws';
 import { NodeWebSocket } from '../../../internal/ws-adapter-node';
 import { ResponsesWSBase, type ResponsesWSBaseOptions } from './ws-base';
 import { OpenAI } from '../../../client';
-import { VERSION } from '../../../version';
+import { OpenAIError } from '../../../core/error';
+import { snapshotWebSocketCredentials } from '../../../internal/ws';
 
 export type { WebSocketStreamOptions } from '../../../internal/ws';
 
 export type { ResponsesWSReconnectOptions } from './ws-base';
 
-export interface ResponsesWSClientOptions extends WS.ClientOptions, ResponsesWSBaseOptions {}
+export interface ResponsesWSClientOptions extends WS.ClientOptions, ResponsesWSBaseOptions {
+  /** Basic authentication forwarded by the Node `ws` transport. */
+  auth?: string;
+}
 
 export class ResponsesWS extends ResponsesWSBase<NodeWebSocket> {
   private _wsOptions: WS.ClientOptions | null | undefined;
@@ -21,7 +25,6 @@ export class ResponsesWS extends ResponsesWSBase<NodeWebSocket> {
         'ResponsesWS from "openai/resources/beta/responses/ws" requires the "ws" package but it could not be loaded.',
       );
     }
-
     const { reconnect, maxQueueSize, ...wsOptions } = options ?? {};
     super(client, { reconnect, maxQueueSize });
     this._wsOptions = wsOptions;
@@ -29,16 +32,31 @@ export class ResponsesWS extends ResponsesWSBase<NodeWebSocket> {
   }
 
   protected _createSocket(url: URL, authHeaders: Record<string, string>): NodeWebSocket {
-    const ws = new WS.WebSocket(url, {
+    const capturedAuthHeaders = { ...authHeaders };
+    const headers = new Map(Object.entries(this._client._buildWebSocketHeaders(capturedAuthHeaders)));
+    for (const [name, value] of Object.entries(this._wsOptions?.headers ?? {})) {
+      if (value === null) {
+        headers.delete(name.toLowerCase());
+      } else if (value !== undefined) {
+        headers.set(name.toLowerCase(), value);
+      }
+    }
+    const socketOptions: ResponsesWSClientOptions = {
       ...this._wsOptions,
-      headers: {
-        'User-Agent': `${this._client.constructor.name}/JS ${VERSION}`,
-
-        ...authHeaders,
-        ...this._wsOptions?.headers,
-      },
+      headers: Object.fromEntries(headers),
       followRedirects: false,
-    });
+    };
+    if (
+      this._client._hasApiKeyProvider() &&
+      !capturedAuthHeaders['Authorization'] &&
+      !snapshotWebSocketCredentials(socketOptions)
+    ) {
+      throw new OpenAIError(
+        'Cannot open a Responses WebSocket with an unresolved function-based apiKey. Resolve it before constructing the WebSocket or provide explicit WebSocket credentials.',
+      );
+    }
+
+    const ws = new WS.WebSocket(url, socketOptions);
     return new NodeWebSocket(ws);
   }
 }