openai 7.25.0 → 7.27.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/filesystem.ts

@@ -0,0 +1,187 @@
+import { constants } from 'node:fs';
+import type { Stats } from 'node:fs';
+import type { WritableStream as AgentWritableStream } from '../../../internal/shim-types';
+import { lstat, open, realpath } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import nodePath from 'node:path';
+import { OpenAIError } from '../../../core/error';
+import { toStreamingFile } from '../../../internal/uploads';
+import type { StreamingFile } from '../../../internal/uploads';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Files } from '../../../resources/beta/agents/environments/files';
+import type { PreparedAgentFiles } from '../../../lib/beta/agents/files';
+
+async function checkedPath(path: string, boundary?: string): Promise<{ path: string; info: Stats }> {
+  const absolute = nodePath.resolve(path);
+  const root = boundary ?? nodePath.dirname(absolute);
+  let current = root;
+  let selected: Stats | undefined;
+  for (const component of nodePath.relative(root, absolute).split(nodePath.sep)) {
+    current = nodePath.join(current, component);
+    // oxlint-disable-next-line no-await-in-loop -- Check each ancestor before following the next path component.
+    const info = await lstat(current);
+    selected = info;
+    if (info.isSymbolicLink()) {
+      throw new OpenAIError('Agent file sources cannot contain symbolic links');
+    }
+  }
+  const resolved = await realpath(absolute);
+  const info = await lstat(resolved);
+  const relative = boundary ? nodePath.relative(boundary, resolved) : '';
+  if (
+    !selected ||
+    selected.dev !== info.dev ||
+    selected.ino !== info.ino ||
+    selected.size !== info.size ||
+    (boundary &&
+      (relative === '..' || relative.startsWith(`..${nodePath.sep}`) || nodePath.isAbsolute(relative)))
+  ) {
+    throw new OpenAIError('Selected agent file changed while resolving its path');
+  }
+  return { path: resolved, info: selected };
+}
+
+function selectedAgentFile({
+  path: absolute,
+  info,
+}: {
+  path: string;
+  info: Stats;
+}): StreamingFile & { size: number } {
+  if (!info.isFile()) {
+    throw new OpenAIError('Agent file sources must be regular files');
+  }
+  async function* bytes() {
+    // oxlint-disable-next-line no-bitwise -- Combine native filesystem open flags.
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const current = await handle.stat();
+      if (
+        !current.isFile() ||
+        current.dev !== info.dev ||
+        current.ino !== info.ino ||
+        current.size !== info.size
+      ) {
+        throw new OpenAIError('Selected agent file changed before upload');
+      }
+      let received = 0;
+      if (info.size > 0) {
+        for await (const chunk of handle.createReadStream({ autoClose: false, end: info.size - 1 })) {
+          received += chunk.length;
+          yield chunk;
+        }
+      }
+      const finalInfo = await handle.stat();
+      if (received !== info.size || finalInfo.size !== info.size) {
+        throw new OpenAIError('Selected agent file changed while uploading');
+      }
+    } finally {
+      await handle.close();
+    }
+  }
+  return Object.assign(toStreamingFile({ [Symbol.asyncIterator]: bytes }, nodePath.basename(absolute)), {
+    size: info.size,
+  });
+}
+
+/** Beta, Node.js: select an application-owned file in a stable directory for a lazy upload. */
+export async function agentFile(path: string): Promise<StreamingFile & { size: number }> {
+  return selectedAgentFile(await checkedPath(path));
+}
+
+/** Beta, Node.js: prepare explicit files from a stable application-owned directory once. */
+export async function prepareAgentDirectory(
+  resource: Files,
+  directory: string,
+  params: { include: readonly string[]; to?: string },
+  options?: RequestOptions,
+): Promise<PreparedAgentFiles> {
+  const include = [...params.include];
+  const destination = params.to ?? '/workspace';
+  const { path: root, info: rootInfo } = await checkedPath(directory);
+  if (!rootInfo.isDirectory()) {
+    throw new OpenAIError('Expected a directory');
+  }
+  const selected: Record<string, StreamingFile & { size: number }> = {};
+  const seen = new Set<string>();
+  for (const relative of include) {
+    if (
+      relative.includes('\\') ||
+      relative.includes('\0') ||
+      relative.split('/').some((part) => part === '' || part === '.' || part === '..') ||
+      seen.has(relative)
+    ) {
+      throw new OpenAIError('Directory selections must be unique relative file paths');
+    }
+    seen.add(relative);
+    // oxlint-disable-next-line no-await-in-loop -- Prepare each explicitly selected source before any upload begins.
+    const source = await checkedPath(nodePath.join(root, relative), root);
+    selected[`${destination}/${relative}`] = selectedAgentFile(source);
+  }
+  return resource.prepare(selected, options);
+}
+
+/** Beta, Node.js: an application-owned safe path in a stable directory, opened lazily for a download. */
+export function agentFileDestination(path: string): AgentWritableStream<Uint8Array> {
+  const absolute = nodePath.resolve(path);
+  let handle: FileHandle | undefined;
+  const close = async () => {
+    await handle?.close();
+    handle = undefined;
+  };
+  const file = async () => {
+    if (handle) {
+      return handle;
+    }
+    let expected: Stats | undefined;
+    try {
+      expected = await lstat(absolute);
+    } catch (error) {
+      if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+        throw error;
+      }
+    }
+    if (expected && !expected.isFile()) {
+      throw new OpenAIError('Agent artifact destinations must be regular files');
+    }
+    // Never truncate before verifying the opened entry. Exclusive creation also rejects dangling links.
+    /* oxlint-disable no-bitwise -- Combine native flags; identity validation also covers Windows. */
+    const flags =
+      constants.O_WRONLY |
+      (constants.O_NOFOLLOW ?? 0) |
+      (constants.O_NONBLOCK ?? 0) |
+      (expected ? 0 : constants.O_CREAT | constants.O_EXCL);
+    /* oxlint-enable no-bitwise */
+    const opened = await open(absolute, flags);
+    try {
+      const current = await opened.stat();
+      if (!current.isFile() || (expected && (current.dev !== expected.dev || current.ino !== expected.ino))) {
+        throw new OpenAIError('Agent artifact destination changed before opening');
+      }
+      await opened.truncate(0);
+      handle = opened;
+      return handle;
+    } catch (error) {
+      await opened.close();
+      throw error;
+    }
+  };
+  return new WritableStream<Uint8Array>({
+    async write(chunk) {
+      try {
+        const target = await file();
+        await target.writeFile(chunk);
+      } catch (error) {
+        await close();
+        throw error;
+      }
+    },
+    async close() {
+      await file();
+      await close();
+    },
+    async abort() {
+      await close();
+    },
+  });
+}

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;
+    },
+  };
 }