openai 7.24.0 → 7.26.0

package/src/client.ts

@@ -48,7 +48,11 @@ import {
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
-import { resolveRealtimeAPIKey } from './internal/realtime-credentials';
+import {
+  getDeferredRealtimeAPIKeyCache,
+  resolveRealtimeAPIKey,
+  validateCapturedAPIKey,
+} from './internal/realtime-credentials';
 import {
   Batch,
   BatchCreateParams,
@@ -258,6 +262,7 @@ import {
 import { type Fetch } from './internal/builtin-types';
 import { isRunningInBrowser } from './internal/detect-platform';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
+import { mergeWebSocketAuthHeaders, webSocketHeaderRemovals } from './internal/ws';
 import { configureProvider, type Provider, type ProviderRuntime } from './internal/provider';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import { readEnv } from './internal/utils/env';
@@ -490,6 +495,8 @@ export class OpenAI {
   protected idempotencyHeader?: string;
   protected _options: ClientOptions;
   private _provider: ProviderRuntime | undefined;
+  private _apiKeyInvocation = 0;
+  private _lastCachedAPIKeyInvocation = 0;
   private _workloadIdentityAuth?: WorkloadIdentityAuth | X509WorkloadIdentityAuth;
 
   /**
@@ -741,18 +748,33 @@ export class OpenAI {
   }
 
   /** @internal Client request headers for each new WebSocket handshake. */
-  _buildWebSocketHeaders(authHeaders: Record<string, string>): Record<string, string> {
-    return Object.fromEntries(
-      buildHeaders([
-        {
-          'User-Agent': this.getUserAgent(),
-          'OpenAI-Organization': this.organization,
-          'OpenAI-Project': this.project,
-        },
+  _buildWebSocketHeaders(
+    authHeaders: Record<string, string>,
+    removedHeaders?: Set<string>,
+  ): Record<string, string> {
+    const context = webSocketHeaderRemovals.get(this);
+    if (context?.baseHeaders) {
+      return mergeWebSocketAuthHeaders(
+        { headers: context.baseHeaders },
         authHeaders,
-        this._options.defaultHeaders,
-      ]).values,
-    );
+        context.removedHeaders ?? new Set(),
+      ).headers;
+    }
+    const headers = buildHeaders([
+      {
+        'User-Agent': this.getUserAgent(),
+        'OpenAI-Organization': this.organization,
+        'OpenAI-Project': this.project,
+      },
+      authHeaders,
+      this._options.defaultHeaders,
+    ]);
+    headers.nulls.forEach((name) => (removedHeaders ?? context?.removedHeaders)?.add(name));
+    const result = Object.fromEntries(headers.values);
+    if (context) {
+      context.baseHeaders = { ...result };
+    }
+    return result;
   }
 
   protected validateHeaders(
@@ -877,11 +899,8 @@ export class OpenAI {
   }
 
   /**
-   * Resolves a function-based API key and retains the resolved value on this client.
-   * Returns whether a provider was invoked. Internal callers can capture this
-   * invocation's key before another request updates the shared `apiKey` property.
-   * Overrides should forward `capture` or invoke it with their own resolved key
-   * to preserve invocation-local credentials in concurrent requests and Realtime factories.
+   * Resolves and retains a provider key, returning whether a provider was invoked.
+   * Overrides should forward `capture` (or call it with their resolved key) for local credentials.
    * @internal
    */
   async _callApiKey(capture?: (apiKey: string | null) => void): Promise<boolean> {
@@ -896,6 +915,8 @@ export class OpenAI {
       return false;
     }
 
+    const deferredCache = getDeferredRealtimeAPIKeyCache(this);
+    const invocation = ++this._apiKeyInvocation;
     let token: unknown;
     try {
       token = await apiKey();
@@ -913,8 +934,23 @@ export class OpenAI {
         `Expected 'apiKey' function argument to return a string but it returned ${token}`,
       );
     }
-    this.apiKey = token;
-    capture?.(this.apiKey);
+    const resolvedToken = token;
+    const commit = () => {
+      if (capture) validateCapturedAPIKey(this, resolvedToken);
+      if (invocation < this._lastCachedAPIKeyInvocation) {
+        return resolvedToken;
+      }
+      this.apiKey = resolvedToken;
+      const cached = capture ? this.apiKey : resolvedToken;
+      this._lastCachedAPIKeyInvocation = invocation;
+      return cached;
+    };
+    if (deferredCache) {
+      deferredCache.providerKey = resolvedToken;
+      deferredCache.commit = commit;
+    }
+    const cached = deferredCache ? validateCapturedAPIKey(this, resolvedToken) : commit();
+    capture?.(cached);
     return true;
   }
 

package/src/core/streaming.ts

@@ -301,6 +301,15 @@ export class Stream<Item> implements AsyncIterable<Item> {
     return this.iterator();
   }
 
+  /** Beta-only iterator decoration for Agents helpers, preserving custom stream identity.
+   * @internal
+   */
+  __betaTransformIterator(
+    transform: (iterator: () => AsyncIterator<Item>) => () => AsyncIterator<Item>,
+  ): void {
+    this.iterator = transform(this.iterator.bind(this));
+  }
+
   /**
    * Splits the stream into two streams which can be
    * independently read from at different speeds.

package/src/helpers/beta/agents/standard-schema.ts

@@ -0,0 +1,13 @@
+import { standardTextFormat } from '../../standard-schema';
+import type { JSONSchema } from '../../../lib/jsonschema';
+import { agentOutputFormat } from '../../../lib/beta/agents/output-format';
+
+/** Beta: bind a synchronous Standard Schema validator to Agents output. */
+export function standardAgentTextFormat<S extends Parameters<typeof standardTextFormat>[0]>(
+  schema: S,
+  jsonSchema?: JSONSchema,
+) {
+  const format = standardTextFormat(schema, 'agent_output', { schema: jsonSchema });
+  // SAFETY: The native Responses helper owns Standard Schema conversion and validation.
+  return agentOutputFormat(format.schema as JSONSchema, format.$parseRaw);
+}

package/src/helpers/beta/agents/zod.ts

@@ -0,0 +1,10 @@
+import { zodTextFormat } from '../../zod';
+import type { JSONSchema } from '../../../lib/jsonschema';
+import { agentOutputFormat } from '../../../lib/beta/agents/output-format';
+
+/** Beta: bind a Zod v3/v4/Mini schema to an Agents text format and completed result. */
+export function zodAgentTextFormat<S extends Parameters<typeof zodTextFormat>[0]>(schema: S) {
+  const format = zodTextFormat(schema, 'agent_output');
+  // SAFETY: The native Responses helper owns Zod schema conversion and validation.
+  return agentOutputFormat(format.schema as JSONSchema, format.$parseRaw);
+}

package/src/internal/realtime-credentials.ts

@@ -1,4 +1,44 @@
 import type { OpenAI } from '../client';
+import { assertValidBedrockBearerCredential, brand_privateBedrockClient } from './bedrock';
+
+type CaptureAPIKey = (apiKey: string | null) => void;
+export interface DeferredAPIKeyCache {
+  client: Pick<OpenAI, 'apiKey'>;
+  providerKey?: string;
+  commit: () => string | null;
+}
+interface RealtimeAPIKeyCacheContext {
+  run: <T>(cache: DeferredAPIKeyCache | undefined, operation: () => T) => T;
+  getStore: () => DeferredAPIKeyCache | undefined;
+}
+// Only the key crosses module formats: the context belongs to each participating client.
+const realtimeCacheContext = Symbol.for('openai.realtimeAPIKeyCacheContext');
+type CredentialClient = Pick<OpenAI, 'apiKey'> & {
+  [realtimeCacheContext]?: RealtimeAPIKeyCacheContext;
+};
+let cacheContext: RealtimeAPIKeyCacheContext | undefined;
+
+/** Installs the Node transport's invocation context without loading Node in the base client. @internal */
+export function setRealtimeAPIKeyCacheContext(context: RealtimeAPIKeyCacheContext): void {
+  cacheContext = context;
+}
+
+/** Reserves a deferred commit when the base hook is entered for this invocation. @internal */
+export function getDeferredRealtimeAPIKeyCache(client: CredentialClient): DeferredAPIKeyCache | undefined {
+  const deferred = client[realtimeCacheContext]?.getStore();
+  return deferred?.client === client ? deferred : undefined;
+}
+
+/** Applies the Bedrock getter's validation when a captured credential does not enter the cache. @internal */
+export function validateCapturedAPIKey(
+  client: Pick<OpenAI, 'apiKey'>,
+  credential: string | null,
+): string | null {
+  if (credential !== null && brand_privateBedrockClient in client) {
+    assertValidBedrockBearerCredential(credential);
+  }
+  return credential;
+}
 
 /** Selects a captured credential without treating an explicit null as absent. @internal */
 export function getRealtimeAPIKey(
@@ -15,13 +55,39 @@ export function getRealtimeAPIKey(
  * synchronizing concurrent credential updates.
  * @internal
  */
-export async function resolveRealtimeAPIKey(client: Pick<OpenAI, 'apiKey' | '_callApiKey'>): Promise<{
+export async function resolveRealtimeAPIKey(
+  client: CredentialClient & Pick<OpenAI, '_callApiKey'>,
+  deferCache = false,
+): Promise<{
   apiKey: string | null;
   isProvider: boolean;
+  commit: () => string | null;
 }> {
   let apiKey: string | null | undefined;
-  const isProvider = await client._callApiKey((resolved) => {
+  const current: DeferredAPIKeyCache = {
+    client,
+    commit: () => (apiKey === undefined ? client.apiKey : apiKey),
+  };
+  const capture: CaptureAPIKey = (resolved) => {
     apiKey = resolved;
-  });
-  return { apiKey: apiKey === undefined ? client.apiKey : apiKey, isProvider };
+  };
+  const invoke = () => client._callApiKey(capture);
+  const context = client[realtimeCacheContext] ?? cacheContext;
+  if (deferCache && context && !client[realtimeCacheContext]) {
+    Object.defineProperty(client, realtimeCacheContext, { value: context });
+  }
+  // An HTTP or ordinary Realtime request nested inside a WebSocket hook owns its own cache writes.
+  const isProvider = await (context ? context.run(deferCache ? current : undefined, invoke) : invoke());
+  return {
+    apiKey: apiKey === undefined ? client.apiKey : apiKey,
+    isProvider,
+    commit: () => {
+      const hookKey =
+        current.providerKey !== undefined && apiKey !== undefined && apiKey !== current.providerKey
+          ? validateCapturedAPIKey(client, apiKey)
+          : undefined;
+      const cached = current.commit();
+      return hookKey === undefined ? validateCapturedAPIKey(client, cached) : hookKey;
+    },
+  };
 }

package/src/internal/responses-ws-credentials.ts

@@ -0,0 +1,160 @@
+import { OpenAIError } from '../core/error';
+import type { OpenAI } from '../client';
+import { resolveRealtimeAPIKey } from './realtime-credentials';
+import {
+  buildWebSocketOptions,
+  mergeWebSocketAuthHeaders,
+  snapshotWebSocketCredentials,
+  WEBSOCKET_METADATA_HEADERS,
+} from './ws';
+import type { CredentialedWebSocketOptions } from './ws';
+
+/**
+ * Keep caller credential admission distinct from the hook's final provider-key transform.
+ * The latter reuses captured base headers so no caller getters are reread after the refresh.
+ */
+function buildResponsesWebSocketOptions<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  prepared?: {
+    options: ReturnType<typeof buildWebSocketOptions>;
+    removedHeaders: Set<string>;
+    apiKey?: string | null | undefined;
+  },
+) {
+  if (prepared) {
+    return prepared.apiKey === undefined
+      ? mergeWebSocketAuthHeaders(prepared.options, authHeaders, prepared.removedHeaders)
+      : buildWebSocketOptions(client, authHeaders, prepared.options, prepared.removedHeaders, true);
+  }
+  if (!client._hasApiKeyProvider()) {
+    return buildWebSocketOptions(client, authHeaders, options);
+  }
+  const removedHeaders = new Set<string>();
+  const provided = buildWebSocketOptions(client, {}, options, removedHeaders);
+  return snapshotWebSocketCredentials(provided, WEBSOCKET_METADATA_HEADERS)
+    ? provided
+    : buildWebSocketOptions(client, authHeaders, provided, removedHeaders, true);
+}
+
+/**
+ * Classify reconnect credentials without treating the previous SDK key as a caller override.
+ * Capture routing and caller options before any asynchronous key refresh.
+ */
+function prepareResponsesWebSocketReconnect<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  socketOptions: Options | null | undefined,
+  initialAuthUsedAPIKey: boolean,
+) {
+  const removedHeaders = new Set<string>();
+  const options = buildWebSocketOptions(client, {}, socketOptions, removedHeaders);
+  let authentication: 'provided' | 'cached' | 'refresh';
+  if (snapshotWebSocketCredentials(options, WEBSOCKET_METADATA_HEADERS)) {
+    authentication = 'provided';
+  } else if (
+    removedHeaders.has('authorization') ||
+    options.headers?.['authorization'] !== undefined ||
+    !initialAuthUsedAPIKey
+  ) {
+    authentication = 'cached';
+  } else {
+    authentication = 'refresh';
+  }
+  return { options, removedHeaders, authentication };
+}
+
+/** Per-connection Responses credential state shared by the stable and beta Node transports. */
+export class ResponsesWebSocketCredentials {
+  private initialAuthUsedAPIKey = false;
+  private initialAPIKey: string | undefined;
+  private prepared:
+    | {
+        options: ReturnType<typeof buildWebSocketOptions>;
+        removedHeaders: Set<string>;
+        apiKey?: string | null | undefined;
+      }
+    | undefined;
+
+  get preparedAPIKey(): string | null | undefined {
+    return this.prepared?.apiKey;
+  }
+
+  trackInitialHeaders(client: OpenAI, headers: Record<string, string>, hasSocket: () => boolean): void {
+    if (!hasSocket() && client._hasApiKeyProvider()) {
+      this.initialAPIKey = headers['Authorization']?.slice('Bearer '.length);
+    }
+  }
+
+  usesAPIKey(client: OpenAI, headers: Record<string, string>): boolean {
+    // Hooks can read the SDK key without delegating. Only use an ordinary cached property here:
+    // invoking custom/Bedrock getters could validate credentials a caller-owned socket never sends.
+    const apiKey =
+      this.initialAPIKey ??
+      (client._hasApiKeyProvider() ? Object.getOwnPropertyDescriptor(client, 'apiKey')?.value : undefined);
+    if (!apiKey) {
+      return false;
+    }
+    // Metadata containing a copy of a credential does not make it the socket's authentication.
+    return snapshotWebSocketCredentials(
+      {
+        headers: Object.fromEntries(
+          Object.entries(headers).map(([name, value]) => [name, value?.includes(apiKey) ? value : '']),
+        ),
+      },
+      WEBSOCKET_METADATA_HEADERS,
+    );
+  }
+
+  build<Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    authHeaders: Record<string, string>,
+    options: Options | null | undefined,
+    initialAuthUsedAPIKey?: boolean,
+  ) {
+    if (initialAuthUsedAPIKey !== undefined) {
+      this.initialAuthUsedAPIKey = initialAuthUsedAPIKey;
+      this.initialAPIKey = undefined;
+    }
+    const socketOptions = buildResponsesWebSocketOptions(client, authHeaders, options, this.prepared);
+    if (
+      client._hasApiKeyProvider() &&
+      !authHeaders['Authorization'] &&
+      !snapshotWebSocketCredentials(socketOptions, WEBSOCKET_METADATA_HEADERS)
+    ) {
+      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.',
+      );
+    }
+    return socketOptions;
+  }
+
+  async prepare<Socket, Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    socketOptions: Options | null | undefined,
+    authHeaders: (apiKey?: string | null) => Record<string, string>,
+    createSocket: (url: URL, headers: Record<string, string>) => Socket,
+  ): Promise<(url: URL) => Socket> {
+    const { options, removedHeaders, authentication } = prepareResponsesWebSocketReconnect(
+      client,
+      socketOptions,
+      this.initialAuthUsedAPIKey,
+    );
+    const createPreparedSocket = (url: URL, headers: Record<string, string>, apiKey?: string | null) => {
+      const previous = this.prepared;
+      this.prepared = { options, removedHeaders, apiKey };
+      try {
+        // Resolve headers inside the scope so legacy zero-argument overrides see this attempt's key.
+        return createSocket(url, apiKey === undefined ? headers : authHeaders(apiKey));
+      } finally {
+        this.prepared = previous;
+      }
+    };
+    if (authentication !== 'refresh') {
+      const headers = authentication === 'provided' ? {} : authHeaders();
+      return (url) => createPreparedSocket(url, headers);
+    }
+    const { commit } = await resolveRealtimeAPIKey(client, true);
+    return (url) => createPreparedSocket(url, {}, commit());
+  }
+}

package/src/internal/ws-adapter-node.ts

@@ -1,10 +1,76 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type * as WS from 'ws';
 import type { WebSocketLike } from './ws-adapter';
 import { protectWebSocketOptionsFromCredentialRedirects } from './ws';
+import { setRealtimeAPIKeyCacheContext } from './realtime-credentials';
+import type { DeferredAPIKeyCache } from './realtime-credentials';
+
+setRealtimeAPIKeyCacheContext(new AsyncLocalStorage<DeferredAPIKeyCache | undefined>());
 
 /** A generic event listener callback. */
 type Listener = (...args: any[]) => void;
 
+function copyTLSMaterial(value: string | Buffer): string | Buffer {
+  return ArrayBuffer.isView(value)
+    ? Buffer.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength))
+    : value;
+}
+
+/** Snapshot caller headers and TLS identity before an async reconnect credential refresh. */
+export function snapshotNodeWebSocketOptions(
+  options: WS.ClientOptions | null | undefined,
+): Omit<WS.ClientOptions, 'headers'> & { headers: Record<string, string | string[]> } {
+  const captured = {
+    ...options,
+    headers: Object.fromEntries(
+      Object.entries(options?.headers ?? {}).map(([name, value]) => [
+        name,
+        Array.isArray(value) ? [...value] : value,
+      ]),
+    ),
+  };
+  const { ca, cert, crl, key, pfx } = captured;
+  if (ca !== undefined) {
+    captured.ca = Array.isArray(ca) ? ca.map(copyTLSMaterial) : copyTLSMaterial(ca);
+  }
+  if (cert !== undefined) {
+    captured.cert = Array.isArray(cert) ? cert.map(copyTLSMaterial) : copyTLSMaterial(cert);
+  }
+  if (crl !== undefined) {
+    captured.crl = Array.isArray(crl) ? crl.map(copyTLSMaterial) : copyTLSMaterial(crl);
+  }
+  if (key !== undefined) {
+    captured.key = Array.isArray(key)
+      ? key.map((value) =>
+          typeof value === 'string' || ArrayBuffer.isView(value)
+            ? copyTLSMaterial(value)
+            : { ...value, pem: copyTLSMaterial(value.pem) },
+        )
+      : copyTLSMaterial(key);
+  }
+  if (pfx !== undefined) {
+    captured.pfx = Array.isArray(pfx)
+      ? pfx.map((value) =>
+          typeof value === 'string' || ArrayBuffer.isView(value)
+            ? copyTLSMaterial(value)
+            : { ...value, buf: copyTLSMaterial(value.buf) },
+        )
+      : copyTLSMaterial(pfx);
+  }
+  if ('session' in captured && Buffer.isBuffer(captured.session)) {
+    captured.session = Buffer.from(captured.session);
+  }
+  if ('ALPNProtocols' in captured) {
+    if (Array.isArray(captured.ALPNProtocols)) {
+      captured.ALPNProtocols = [...captured.ALPNProtocols];
+    } else if (ArrayBuffer.isView(captured.ALPNProtocols)) {
+      const { buffer, byteOffset, byteLength } = captured.ALPNProtocols;
+      captured.ALPNProtocols = Buffer.from(new Uint8Array(buffer, byteOffset, byteLength));
+    }
+  }
+  return captured;
+}
+
 /**
  * Adapts a Node.js `ws` socket to the SDK's platform-neutral WebSocket API.
  *

package/src/internal/ws.ts

@@ -1,6 +1,7 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
 import { OpenAIError } from '../core/error';
 import type { WebSocketLike } from './ws-adapter';
+import type { OpenAI } from '../client';
 
 const webSocketErrors = new WeakMap<WebSocketLike, Error>();
 
@@ -73,7 +74,7 @@ export type ReconnectingOverrides<Parameters = Record<string, unknown>> =
  */
 export type RawWebSocketData = string | ArrayBufferLike | ArrayBufferView | ArrayBufferView[];
 
-interface CredentialedWebSocketOptions {
+export interface CredentialedWebSocketOptions {
   auth?: string | null | undefined;
   followRedirects?: boolean | undefined;
   headers?: object | null | undefined;
@@ -99,19 +100,57 @@ const REDIRECT_SAFE_WEBSOCKET_HEADERS = new Set([
   'x-trace-id',
 ]);
 
+const WEBSOCKET_METADATA_HEADER_NAMES = new Set([
+  'accept',
+  'accept-encoding',
+  'accept-language',
+  'content-type',
+  'x-request-id',
+  'x-client-request-id',
+  'x-correlation-id',
+  'traceparent',
+  'tracestate',
+  'sentry-trace',
+  'x-amzn-trace-id',
+  'x-cloud-trace-context',
+  'x-datadog-trace-id',
+  'x-datadog-parent-id',
+  'x-datadog-sampling-priority',
+  'x-datadog-origin',
+  'x-datadog-tags',
+  'baggage',
+  'b3',
+]);
+
+// Request and tracing metadata do not authenticate a Responses socket, but remain protected on redirects.
+export const WEBSOCKET_METADATA_HEADERS = {
+  has: (name: string, values: readonly unknown[]): boolean =>
+    WEBSOCKET_METADATA_HEADER_NAMES.has(name) ||
+    name.startsWith('x-b3-') ||
+    (name === 'sec-websocket-protocol' &&
+      !values.some(
+        (value) =>
+          typeof value === 'string' &&
+          value.split(',').some((protocol) => protocol.trim().startsWith('openai-insecure-api-key.')),
+      )),
+};
+
 function isWebSocketCredentialHeader(name: string): boolean {
   return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(name.toLowerCase().split('_').join('-'));
 }
 
 /**
  * Snapshots credential values in final socket options before validation and dispatch.
- * Reports potential caller authentication, including custom headers; the server
- * remains responsible for validating credentials. Noncredential headers are left intact.
+ * Reports potential caller authentication, excluding additional metadata when requested.
+ * The server remains responsible for validating credentials. Noncredential headers are left intact.
  */
-export function snapshotWebSocketCredentials(options: {
-  auth?: unknown;
-  headers?: Record<string, unknown> | undefined;
-}): boolean {
+export function snapshotWebSocketCredentials(
+  options: {
+    auth?: unknown;
+    headers?: Record<string, unknown> | undefined;
+  },
+  metadataHeaders?: { has: (name: string, values: readonly unknown[]) => boolean },
+): boolean {
   if (options.auth !== null && options.auth !== undefined) {
     options.auth = String(options.auth);
   }
@@ -135,10 +174,12 @@ export function snapshotWebSocketCredentials(options: {
     }
     headers[name] = snapshot;
     const values = Array.isArray(snapshot) ? snapshot : [snapshot];
-    credentials.set(
-      name.toLowerCase(),
-      values.some((item) => typeof item === 'string' && item.trim().length > 0),
-    );
+    if (!metadataHeaders?.has(normalizedName, values)) {
+      credentials.set(
+        name.toLowerCase(),
+        values.some((item) => typeof item === 'string' && item.trim().length > 0),
+      );
+    }
   }
   // Node applies header names case-insensitively, and Authorization overrides Basic auth.
   return (
@@ -147,6 +188,93 @@ export function snapshotWebSocketCredentials(options: {
   );
 }
 
+/** Merge transport authentication before explicit caller overrides and header removals. */
+export function mergeWebSocketAuthHeaders<Options extends CredentialedWebSocketOptions>(
+  options: Options,
+  authHeaders: Record<string, string>,
+  removedHeaders: ReadonlySet<string>,
+) {
+  const headers = new Map(Object.entries(authHeaders).map(([name, value]) => [name.toLowerCase(), value]));
+  for (const name of removedHeaders) {
+    headers.delete(name);
+  }
+  for (const [name, value] of Object.entries(options.headers ?? {})) {
+    headers.set(name, value);
+  }
+  return { ...options, headers: Object.fromEntries(headers) };
+}
+
+/** Removal sink for one synchronous header-hook call, including legacy one-argument overrides. */
+export const webSocketHeaderRemovals = new WeakMap<
+  OpenAI,
+  { removedHeaders: Set<string> | undefined; baseHeaders: Record<string, string> | undefined }
+>();
+const preparedWebSocketHeaders = new WeakMap<
+  object,
+  { baseHeaders: Record<string, string> | undefined; transportHeaders: Map<string, boolean> }
+>();
+
+/** Build a WebSocket handshake with explicit caller headers applied after the client defaults. */
+export function buildWebSocketOptions<Options extends Pick<CredentialedWebSocketOptions, 'headers'>>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  removedHeaders?: Set<string>,
+  usePreparedHeaders = false,
+) {
+  // Capture the base result even through older overrides that forward only one argument.
+  const previous = webSocketHeaderRemovals.get(client);
+  const prepared = usePreparedHeaders && options ? preparedWebSocketHeaders.get(options) : undefined;
+  const context: NonNullable<ReturnType<typeof webSocketHeaderRemovals.get>> = {
+    removedHeaders,
+    baseHeaders: prepared?.baseHeaders,
+  };
+  webSocketHeaderRemovals.set(client, context);
+  let headers: Map<string, string>;
+  try {
+    headers = new Map(
+      Object.entries(client._buildWebSocketHeaders(authHeaders, removedHeaders)).map(([name, value]) => [
+        name.toLowerCase(),
+        value,
+      ]),
+    );
+  } finally {
+    if (previous) {
+      webSocketHeaderRemovals.set(client, previous);
+    } else {
+      webSocketHeaderRemovals.delete(client);
+    }
+  }
+  // The first hook output is not a caller override of the final, credentialed hook.
+  // Save transport names and explicit nulls separately, then reuse their validated values.
+  const transportHeaders = new Map<string, boolean>();
+  const currentHeaders = new Map(Object.entries(options?.headers ?? {}));
+  const overrides = prepared
+    ? [...prepared.transportHeaders].map(
+        ([name, removed]) => [name, removed ? null : currentHeaders.get(name)] as const,
+      )
+    : currentHeaders;
+  for (const [name, value] of overrides) {
+    const normalizedName = name.toLowerCase();
+    if (value === null) {
+      headers.delete(normalizedName);
+      removedHeaders?.add(normalizedName);
+      transportHeaders.set(normalizedName, true);
+    } else if (value !== undefined) {
+      headers.set(normalizedName, value);
+      removedHeaders?.delete(normalizedName);
+      transportHeaders.set(normalizedName, false);
+    }
+  }
+  const result = {
+    ...options,
+    headers: Object.fromEntries(headers),
+    followRedirects: false,
+  };
+  preparedWebSocketHeaders.set(result, { baseHeaders: context.baseHeaders, transportHeaders });
+  return result;
+}
+
 /** Prevents WebSocket redirects from forwarding caller or SDK credentials to another origin. */
 export function protectWebSocketOptionsFromCredentialRedirects<Options extends CredentialedWebSocketOptions>(
   options: Options,