openai 7.25.0 → 7.26.0

package/resources/responses/ws.js

@@ -6,8 +6,7 @@ const tslib_1 = require("../../internal/tslib.js");
 const WS = tslib_1.__importStar(require("ws"));
 const ws_adapter_node_1 = require("../../internal/ws-adapter-node.js");
 const ws_base_1 = require("./ws-base.js");
-const error_1 = require("../../core/error.js");
-const ws_1 = require("../../internal/ws.js");
+const responses_ws_credentials_1 = require("../../internal/responses-ws-credentials.js");
 class ResponsesWS extends ws_base_1.ResponsesWSBase {
     constructor(client, options) {
         if (!WS?.WebSocket) {
@@ -15,32 +14,34 @@ class ResponsesWS extends ws_base_1.ResponsesWSBase {
         }
         const { reconnect, maxQueueSize, ...wsOptions } = options ?? {};
         super(client, { reconnect, maxQueueSize });
+        this._credentials = new responses_ws_credentials_1.ResponsesWebSocketCredentials();
         this._wsOptions = wsOptions;
         this._connectInitial();
     }
+    _authHeaders(apiKey) {
+        const headers = super._authHeaders(apiKey === undefined ? this._credentials.preparedAPIKey : apiKey);
+        this._credentials.trackInitialHeaders(this._client, headers, () => !!this.socket);
+        return headers;
+    }
+    /**
+     * Whether credentials passed to the Node transport use the SDK key.
+     * The SDK recognizes its key, including copies and additions in credential headers.
+     * Override and return true if your socket hook signs or otherwise irreversibly transforms it.
+     * Explicit caller options and header removals still take precedence on reconnect.
+     */
+    _usesSDKAPIKey(authHeaders) {
+        return this._credentials.usesAPIKey(this._client, authHeaders);
+    }
     _createSocket(url, authHeaders) {
         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 = {
-            ...this._wsOptions,
-            headers: Object.fromEntries(headers),
-            followRedirects: false,
-        };
-        if (this._client._hasApiKeyProvider() &&
-            !capturedAuthHeaders['Authorization'] &&
-            !(0, ws_1.snapshotWebSocketCredentials)(socketOptions)) {
-            throw new error_1.OpenAIError('Cannot open a Responses WebSocket with an unresolved function-based apiKey. Resolve it before constructing the WebSocket or provide explicit WebSocket credentials.');
+        const socketOptions = this._credentials.build(this._client, capturedAuthHeaders, this._wsOptions, !this.socket ? this._usesSDKAPIKey(capturedAuthHeaders) : undefined);
+        return new ws_adapter_node_1.NodeWebSocket(new WS.WebSocket(url, socketOptions));
+    }
+    async _prepareReconnectSocket() {
+        if (!this._client._hasApiKeyProvider()) {
+            return super._prepareReconnectSocket();
         }
-        const ws = new WS.WebSocket(url, socketOptions);
-        return new ws_adapter_node_1.NodeWebSocket(ws);
+        return this._credentials.prepare(this._client, (0, ws_adapter_node_1.snapshotNodeWebSocketOptions)(this._wsOptions), (...args) => this._authHeaders(...args), (url, headers) => this._createSocket(url, headers));
     }
 }
 exports.ResponsesWS = ResponsesWS;

package/resources/responses/ws.js.map

@@ -1 +1 @@
-{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/resources/responses/ws.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;AAErF,+CAAyB;AACzB,uEAA+D;AAC/D,0CAAyE;AAEzE,+CAA+C;AAC/C,6CAAiE;AAWjE,MAAa,WAAY,SAAQ,yBAA8B;IAG7D,YAAY,MAAc,EAAE,OAAqD;QAC/E,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAChE,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAES,aAAa,CAAC,GAAQ,EAAE,WAAmC;QACnE,MAAM,mBAAmB,GAAG,EAAE,GAAG,WAAW,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;QAClG,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3E,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YACrC,CAAC;iBAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,MAAM,aAAa,GAA6B;YAC9C,GAAG,IAAI,CAAC,UAAU;YAClB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC;YACpC,eAAe,EAAE,KAAK;SACvB,CAAC;QACF,IACE,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE;YACjC,CAAC,mBAAmB,CAAC,eAAe,CAAC;YACrC,CAAC,IAAA,iCAA4B,EAAC,aAAa,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,mBAAW,CACnB,qKAAqK,CACtK,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QAChD,OAAO,IAAI,+BAAa,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF;AA3CD,kCA2CC"}
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/resources/responses/ws.ts"],"names":[],"mappings":";AAAA,qFAAqF;;;;AAErF,+CAAyB;AACzB,uEAA6F;AAC7F,0CAAyE;AAEzE,yFAAwF;AAWxF,MAAa,WAAY,SAAQ,yBAA8B;IAI7D,YAAY,MAAc,EAAE,OAAqD;QAC/E,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAChE,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;QATrC,iBAAY,GAAG,IAAI,wDAA6B,EAAE,CAAC;QAUzD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEkB,YAAY,CAAC,MAAsB;QACpD,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACrG,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClF,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACO,cAAc,CAAC,WAAmC;QAC1D,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjE,CAAC;IAES,aAAa,CAAC,GAAQ,EAAE,WAAmC;QACnE,MAAM,mBAAmB,GAAG,EAAE,GAAG,WAAW,EAAE,CAAC;QAC/C,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAC3C,IAAI,CAAC,OAAO,EACZ,mBAAmB,EACnB,IAAI,CAAC,UAAU,EACf,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,SAAS,CACpE,CAAC;QACF,OAAO,IAAI,+BAAa,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC;IACjE,CAAC;IAEkB,KAAK,CAAC,uBAAuB;QAC9C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC,uBAAuB,EAAE,CAAC;QACzC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAC9B,IAAI,CAAC,OAAO,EACZ,IAAA,8CAA4B,EAAC,IAAI,CAAC,UAAU,CAAC,EAC7C,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,EACvC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CACnD,CAAC;IACJ,CAAC;CACF;AAtDD,kCAsDC"}

package/resources/responses/ws.mjs

@@ -1,9 +1,8 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 import * as WS from 'ws';
-import { NodeWebSocket } from "../../internal/ws-adapter-node.mjs";
+import { NodeWebSocket, snapshotNodeWebSocketOptions } from "../../internal/ws-adapter-node.mjs";
 import { ResponsesWSBase } from "./ws-base.mjs";
-import { OpenAIError } from "../../core/error.mjs";
-import { snapshotWebSocketCredentials } from "../../internal/ws.mjs";
+import { ResponsesWebSocketCredentials } from "../../internal/responses-ws-credentials.mjs";
 export class ResponsesWS extends ResponsesWSBase {
     constructor(client, options) {
         if (!WS?.WebSocket) {
@@ -11,32 +10,34 @@ export class ResponsesWS extends ResponsesWSBase {
         }
         const { reconnect, maxQueueSize, ...wsOptions } = options ?? {};
         super(client, { reconnect, maxQueueSize });
+        this._credentials = new ResponsesWebSocketCredentials();
         this._wsOptions = wsOptions;
         this._connectInitial();
     }
+    _authHeaders(apiKey) {
+        const headers = super._authHeaders(apiKey === undefined ? this._credentials.preparedAPIKey : apiKey);
+        this._credentials.trackInitialHeaders(this._client, headers, () => !!this.socket);
+        return headers;
+    }
+    /**
+     * Whether credentials passed to the Node transport use the SDK key.
+     * The SDK recognizes its key, including copies and additions in credential headers.
+     * Override and return true if your socket hook signs or otherwise irreversibly transforms it.
+     * Explicit caller options and header removals still take precedence on reconnect.
+     */
+    _usesSDKAPIKey(authHeaders) {
+        return this._credentials.usesAPIKey(this._client, authHeaders);
+    }
     _createSocket(url, authHeaders) {
         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 = {
-            ...this._wsOptions,
-            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 socketOptions = this._credentials.build(this._client, capturedAuthHeaders, this._wsOptions, !this.socket ? this._usesSDKAPIKey(capturedAuthHeaders) : undefined);
+        return new NodeWebSocket(new WS.WebSocket(url, socketOptions));
+    }
+    async _prepareReconnectSocket() {
+        if (!this._client._hasApiKeyProvider()) {
+            return super._prepareReconnectSocket();
         }
-        const ws = new WS.WebSocket(url, socketOptions);
-        return new NodeWebSocket(ws);
+        return this._credentials.prepare(this._client, snapshotNodeWebSocketOptions(this._wsOptions), (...args) => this._authHeaders(...args), (url, headers) => this._createSocket(url, headers));
     }
 }
 //# sourceMappingURL=ws.mjs.map

package/resources/responses/ws.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ws.mjs","sourceRoot":"","sources":["../../src/resources/responses/ws.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,2CAAuC;AAC/D,OAAO,EAAE,eAAe,EAA+B,sBAAkB;AAEzE,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAC/C,OAAO,EAAE,4BAA4B,EAAE,8BAA0B;AAWjE,MAAM,OAAO,WAAY,SAAQ,eAA8B;IAG7D,YAAY,MAAc,EAAE,OAAqD;QAC/E,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAChE,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAES,aAAa,CAAC,GAAQ,EAAE,WAAmC;QACnE,MAAM,mBAAmB,GAAG,EAAE,GAAG,WAAW,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;QAClG,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3E,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;YACrC,CAAC;iBAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,MAAM,aAAa,GAA6B;YAC9C,GAAG,IAAI,CAAC,UAAU;YAClB,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC;YACpC,eAAe,EAAE,KAAK;SACvB,CAAC;QACF,IACE,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE;YACjC,CAAC,mBAAmB,CAAC,eAAe,CAAC;YACrC,CAAC,4BAA4B,CAAC,aAAa,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,WAAW,CACnB,qKAAqK,CACtK,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QAChD,OAAO,IAAI,aAAa,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"ws.mjs","sourceRoot":"","sources":["../../src/resources/responses/ws.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,2CAAuC;AAC7F,OAAO,EAAE,eAAe,EAA+B,sBAAkB;AAEzE,OAAO,EAAE,6BAA6B,EAAE,oDAAgD;AAWxF,MAAM,OAAO,WAAY,SAAQ,eAA8B;IAI7D,YAAY,MAAc,EAAE,OAAqD;QAC/E,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,wGAAwG,CACzG,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAChE,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;QATrC,iBAAY,GAAG,IAAI,6BAA6B,EAAE,CAAC;QAUzD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEkB,YAAY,CAAC,MAAsB;QACpD,MAAM,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACrG,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClF,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACO,cAAc,CAAC,WAAmC;QAC1D,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjE,CAAC;IAES,aAAa,CAAC,GAAQ,EAAE,WAAmC;QACnE,MAAM,mBAAmB,GAAG,EAAE,GAAG,WAAW,EAAE,CAAC;QAC/C,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAC3C,IAAI,CAAC,OAAO,EACZ,mBAAmB,EACnB,IAAI,CAAC,UAAU,EACf,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,SAAS,CACpE,CAAC;QACF,OAAO,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC;IACjE,CAAC;IAEkB,KAAK,CAAC,uBAAuB;QAC9C,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC,uBAAuB,EAAE,CAAC;QACzC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,CAC9B,IAAI,CAAC,OAAO,EACZ,4BAA4B,CAAC,IAAI,CAAC,UAAU,CAAC,EAC7C,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,EACvC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CACnD,CAAC;IACJ,CAAC;CACF"}

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.
  *