openai 7.4.0 → 7.6.0

package/src/client.ts

@@ -1,25 +1,36 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
 import type { RequestInit, RequestInfo, BodyInit } from './internal/builtin-types';
 import type { HTTPMethod, PromiseOrValue, MergedRequestInit, FinalizedRequestInit } from './internal/types';
 import { uuid4 } from './internal/utils/uuid';
-import { validatePositiveInteger, isAbsoluteURL, safeJSON } from './internal/utils/values';
+import { validatePositiveInteger, isAbsoluteURL, safeJSON, hasOwn } from './internal/utils/values';
 import { sleep } from './internal/utils/sleep';
 export type { Logger, LogLevel } from './internal/utils/log';
 import { castToError, isAbortError } from './internal/errors';
-import type { APIResponseProps } from './internal/parse';
+import { addRequestID, defaultParseResponse, type APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
 import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
+import { resolveDataResidency, type DataResidency } from './internal/data-residency';
+export type { DataResidency } from './internal/data-residency';
 import * as Errors from './core/error';
 import * as Pagination from './core/pagination';
-import type { WorkloadIdentity } from './auth/types';
+import type { WorkloadIdentity, X509WorkloadIdentity } from './auth/types';
 import { WorkloadIdentityAuth } from './auth/workload-identity-auth';
+import {
+  X509_API_BASE_URL,
+  X509WorkloadIdentityAuth,
+  assertX509APIOrigin,
+  assertX509RequestOptions,
+  isX509WorkloadIdentity,
+  snapshotX509RequestOptions,
+} from './internal/auth/x509-workload-identity-auth';
+import type { X509Transport } from './internal/auth/x509-transport-registry';
+import { isTransientX509ConnectionError, markApprovedX509Client } from '#x509-transport-state';
 import { OAuthError, SubjectTokenProviderError } from './core/error';
 import {
-  AbstractPage,
   type ConversationCursorPageParams,
   ConversationCursorPageResponse,
   type CursorPageParams,
@@ -250,7 +261,28 @@ import {
 } from './internal/utils/log';
 import { isEmptyObj } from './internal/utils/values';
 
+function isRunningInBrowserOrBrowserWorker(): boolean {
+  if (isRunningInBrowser()) return true;
+
+  const scope = globalThis as any;
+  return (
+    typeof scope.WorkerGlobalScope === 'function' &&
+    scope instanceof scope.WorkerGlobalScope &&
+    typeof scope.WorkerNavigator === 'function' &&
+    scope.navigator instanceof scope.WorkerNavigator &&
+    typeof scope.navigator?.userAgent === 'string' &&
+    scope.navigator.userAgent !== 'Cloudflare-Workers' &&
+    scope.process?.versions?.node === undefined &&
+    scope.Deno === undefined &&
+    scope.Bun === undefined &&
+    scope.EdgeRuntime === undefined &&
+    scope.WebSocketPair === undefined
+  );
+}
+
 const WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER = 'workload-identity-auth';
+const inheritedDataResidencySelection = Symbol('inheritedDataResidencySelection');
+type InternalClientOptions = ClientOptions & { [inheritedDataResidencySelection]?: boolean };
 
 export type ApiKeySetter = () => Promise<string>;
 
@@ -296,6 +328,14 @@ export interface ClientOptions {
    */
   baseURL?: string | null | undefined;
 
+  /**
+   * Select an OpenAI regional endpoint. This overrides an inherited or environment
+   * base URL and is mutually exclusive with an explicit `baseURL` or `provider`.
+   * Availability depends on your project and model; no fallback is performed.
+   * `null` and `undefined` leave ordinary base URL resolution unchanged.
+   */
+  dataResidency?: DataResidency | null | undefined;
+
   /**
    * The maximum amount of time (in milliseconds) that the client should wait for a response
    * from the server before timing out a single request.
@@ -303,6 +343,23 @@ export interface ClientOptions {
    * Note that request timeouts are retried by default, so in a worst-case scenario you may wait
    * much longer than this timeout before the promise succeeds or fails.
    *
+   * Node.js fetch enforces independent response-header and body-inactivity timeouts, typically
+   * defaulting to five minutes, even when this timeout is longer. To increase them, install
+   * `undici` and configure an Agent with the matching fetch implementation:
+   *
+   * ```ts
+   * import { Agent, fetch } from 'undici';
+   *
+   * const timeout = 20 * 60 * 1000;
+   * const client = new OpenAI({
+   *   timeout,
+   *   fetch,
+   *   fetchOptions: {
+   *     dispatcher: new Agent({ headersTimeout: timeout, bodyTimeout: timeout }),
+   *   },
+   * });
+   * ```
+   *
    * @unit milliseconds
    */
   timeout?: number | undefined;
@@ -368,7 +425,10 @@ export interface ClientOptions {
    * Workload identity configuration for OAuth2 token exchange authentication.
    * Mutually exclusive with `apiKey`.
    */
-  workloadIdentity?: WorkloadIdentity | undefined;
+  workloadIdentity?: WorkloadIdentity | X509WorkloadIdentity | undefined;
+
+  /** Approved, frozen Node.js certificate transport required only for X.509 workload identity. */
+  x509Transport?: X509Transport | undefined;
 
   /**
    * Configure this client to use a third-party API provider.
@@ -396,10 +456,25 @@ export class OpenAI {
 
   private fetch: Fetch;
   #encoder: Opts.RequestEncoder;
+  #x509Authentication: X509WorkloadIdentityAuth | undefined;
+  #x509Fetch: Fetch | undefined;
+  // Preserve an explicit global selection without storing a second routing URL.
+  #explicitDataResidency = false;
+  #responseAttempts = new WeakMap<
+    AbortController,
+    {
+      timeout: number;
+      retriesRemaining: number;
+      hasStreamingBody: boolean;
+      authentication?: X509WorkloadIdentityAuth;
+      helperMethod?: unknown;
+      continueRequest?: <T>(operation: () => Promise<T>) => Promise<T>;
+    }
+  >();
   protected idempotencyHeader?: string;
   protected _options: ClientOptions;
   private _provider: ProviderRuntime | undefined;
-  private _workloadIdentityAuth?: WorkloadIdentityAuth;
+  private _workloadIdentityAuth?: WorkloadIdentityAuth | X509WorkloadIdentityAuth;
 
   /**
    * API Client for interfacing with the OpenAI API.
@@ -420,11 +495,25 @@ export class OpenAI {
    * @param {boolean} [opts.dangerouslyAllowBrowser=false] - By default, client-side use of this library is not allowed, as it risks exposing your secret API credentials to attackers.
    */
   constructor(clientOptions: ClientOptions = {}) {
+    const residencyBaseURL = resolveDataResidency(clientOptions);
     const provider = clientOptions.provider;
+    const {
+      baseURL = provider ? null : readEnv('OPENAI_BASE_URL'),
+      dataResidency: _dataResidency,
+      [inheritedDataResidencySelection]: inheritedResidencySelection = false,
+      apiKey = provider ? null : (readEnv('OPENAI_API_KEY') ?? null),
+      adminAPIKey = provider ? null : (readEnv('OPENAI_ADMIN_KEY') ?? null),
+      organization = provider ? null : (readEnv('OPENAI_ORG_ID') ?? null),
+      project = provider ? null : (readEnv('OPENAI_PROJECT_ID') ?? null),
+      webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
+      workloadIdentity,
+      x509Transport,
+      ...opts
+    } = clientOptions as InternalClientOptions;
     if (provider) {
-      const conflictingOptions = (['apiKey', 'adminAPIKey', 'workloadIdentity', 'baseURL'] as const).filter(
-        (key) => clientOptions[key] != null,
-      );
+      const conflictingOptions = (
+        ['apiKey', 'adminAPIKey', 'workloadIdentity', 'x509Transport', 'baseURL', 'dataResidency'] as const
+      ).filter((key) => (key === 'workloadIdentity' ? workloadIdentity : clientOptions[key]) != null);
       if (conflictingOptions.length) {
         throw new Errors.OpenAIError(
           `The \`provider\` option cannot be used with ${conflictingOptions
@@ -433,17 +522,11 @@ export class OpenAI {
         );
       }
     }
-
-    const {
-      baseURL = provider ? null : readEnv('OPENAI_BASE_URL'),
-      apiKey = provider ? null : readEnv('OPENAI_API_KEY') ?? null,
-      adminAPIKey = provider ? null : readEnv('OPENAI_ADMIN_KEY') ?? null,
-      organization = provider ? null : readEnv('OPENAI_ORG_ID') ?? null,
-      project = provider ? null : readEnv('OPENAI_PROJECT_ID') ?? null,
-      webhookSecret = readEnv('OPENAI_WEBHOOK_SECRET') ?? null,
-      workloadIdentity,
-      ...opts
-    } = clientOptions;
+    const identity = isX509WorkloadIdentity(workloadIdentity)
+      ? { x509: workloadIdentity, legacy: undefined }
+      : { x509: undefined, legacy: workloadIdentity };
+    const x509Identity = identity.x509;
+    const usesX509Identity = x509Identity !== undefined;
     const providerRuntime = provider ? configureProvider(provider) : undefined;
     const options: ClientOptions = {
       apiKey,
@@ -452,11 +535,40 @@ export class OpenAI {
       project,
       webhookSecret,
       workloadIdentity,
+      x509Transport,
       provider,
       ...opts,
-      baseURL: providerRuntime?.baseURL ?? (baseURL || `https://api.openai.com/v1`),
+      baseURL:
+        providerRuntime?.baseURL ??
+        residencyBaseURL ??
+        (baseURL || (usesX509Identity ? X509_API_BASE_URL : `https://api.openai.com/v1`)),
     };
 
+    if (x509Transport && !usesX509Identity) {
+      throw new Errors.OpenAIError('An X.509 transport requires an X.509 workload identity.');
+    }
+
+    if (usesX509Identity) {
+      if (residencyBaseURL !== undefined || inheritedResidencySelection) {
+        throw new Errors.OpenAIError('X.509 workload identity does not support data residency selection.');
+      }
+      if (clientOptions.fetch !== undefined) {
+        throw new Errors.OpenAIError(
+          'X.509 workload identity does not support a custom fetch implementation.',
+        );
+      }
+      assertX509APIOrigin(options.baseURL!);
+      assertX509RequestOptions(options.fetchOptions);
+      if (
+        this.fetchWithAuth !== OpenAI.prototype.fetchWithAuth ||
+        this.fetchWithTimeout !== OpenAI.prototype.fetchWithTimeout
+      ) {
+        throw new Errors.OpenAIError(
+          'X.509 workload identity does not support overridden fetch dispatch hooks.',
+        );
+      }
+    }
+
     if (apiKey && workloadIdentity) {
       throw new Errors.OpenAIError('The `apiKey` and `workloadIdentity` options are mutually exclusive');
     }
@@ -467,14 +579,15 @@ export class OpenAI {
       );
     }
 
-    if (!options.dangerouslyAllowBrowser && isRunningInBrowser()) {
+    if (!options.dangerouslyAllowBrowser && isRunningInBrowserOrBrowserWorker()) {
       throw new Errors.OpenAIError(
         "It looks like you're running in a browser-like environment.\n\nThis is disabled by default, as it risks exposing your secret API credentials to attackers.\nIf you understand the risks and have appropriate mitigations in place,\nyou can set the `dangerouslyAllowBrowser` option to `true`, e.g.,\n\nnew OpenAI({ apiKey, dangerouslyAllowBrowser: true });\n\nhttps://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety\n",
       );
     }
 
     this.baseURL = options.baseURL!;
-    this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT /* 10 minutes */;
+    this.#explicitDataResidency = residencyBaseURL !== undefined || inheritedResidencySelection;
+    this.timeout = options.timeout ?? OpenAI.DEFAULT_TIMEOUT; /* 10 minutes */
     this.logger = options.logger ?? console;
     const defaultLogLevel = 'warn';
     // Set default logLevel early so that we can log a warning in parseLogLevel.
@@ -503,8 +616,15 @@ export class OpenAI {
     this._options = options;
     this._provider = providerRuntime;
 
-    if (workloadIdentity) {
-      this._workloadIdentityAuth = new WorkloadIdentityAuth(workloadIdentity, this.fetch);
+    if (x509Identity) {
+      const authentication = new X509WorkloadIdentityAuth(x509Identity, x509Transport, organization, project);
+      this._workloadIdentityAuth = authentication;
+      this.#x509Authentication = authentication;
+      this.#x509Fetch = authentication.fetch();
+      this.fetch = this.#x509Fetch;
+      markApprovedX509Client(this);
+    } else if (identity.legacy) {
+      this._workloadIdentityAuth = new WorkloadIdentityAuth(identity.legacy, this.fetch);
     }
 
     this.apiKey = typeof apiKey === 'string' ? apiKey : null;
@@ -518,8 +638,10 @@ export class OpenAI {
    * Create a new client instance re-using the same options given to the current client with optional overriding.
    */
   withOptions(options: Partial<ClientOptions>): this {
+    const residencyBaseURL = resolveDataResidency(options);
     const inheritedProvider = this._options.provider;
     const provider = options.provider ?? inheritedProvider;
+    const x509Authentication = this.#x509Authentication;
     const inheritedOptions: ClientOptions = {
       ...this._options,
       baseURL: this.baseURL,
@@ -527,19 +649,38 @@ export class OpenAI {
       timeout: this.timeout,
       logger: this.logger,
       logLevel: this.logLevel,
-      fetch: this.fetch,
+      fetch: this.#x509Authentication ? undefined : this.fetch,
       fetchOptions: this.fetchOptions,
       apiKey: this._options.apiKey,
       adminAPIKey: this.adminAPIKey,
-      workloadIdentity: this._options.workloadIdentity,
+      workloadIdentity: x509Authentication?.identitySnapshot() ?? this._options.workloadIdentity,
+      x509Transport: this._options.x509Transport,
       organization: this.organization,
       project: this.project,
       webhookSecret: this.webhookSecret,
     };
+    const currentlyX509 = x509Authentication !== undefined;
+    const nextIdentity = hasOwn(options, 'workloadIdentity')
+      ? options.workloadIdentity
+      : inheritedOptions.workloadIdentity;
+    const nextX509 = isX509WorkloadIdentity(nextIdentity);
+    if (currentlyX509 !== nextX509) {
+      delete inheritedOptions.fetch;
+      delete inheritedOptions.baseURL;
+      if (nextX509) {
+        inheritedOptions.apiKey = null;
+      } else {
+        delete inheritedOptions.x509Transport;
+      }
+    }
+    if (residencyBaseURL !== undefined) {
+      delete inheritedOptions.baseURL;
+    }
     if (provider) {
       delete inheritedOptions.apiKey;
       delete inheritedOptions.adminAPIKey;
       delete inheritedOptions.workloadIdentity;
+      delete inheritedOptions.x509Transport;
       delete inheritedOptions.baseURL;
       if (provider !== inheritedProvider) {
         delete inheritedOptions.organization;
@@ -548,11 +689,27 @@ export class OpenAI {
       }
     }
 
-    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+    const clientOptions: InternalClientOptions = {
       ...inheritedOptions,
       ...options,
       provider,
-    });
+      [inheritedDataResidencySelection]:
+        this.#explicitDataResidency &&
+        residencyBaseURL === undefined &&
+        !hasOwn(options, 'baseURL') &&
+        !provider,
+    };
+    const client = new (this.constructor as any as new (props: ClientOptions) => typeof this)(clientOptions);
+    if (
+      this.#x509Authentication &&
+      client.#x509Authentication &&
+      this.baseURL === client.baseURL &&
+      this.#x509Authentication.matches(client.#x509Authentication)
+    ) {
+      client._workloadIdentityAuth = this.#x509Authentication;
+      client.#x509Authentication = this.#x509Authentication;
+      client.#x509Fetch = this.#x509Fetch;
+    }
     return client;
   }
 
@@ -560,7 +717,11 @@ export class OpenAI {
    * Check whether the base URL is set to its default.
    */
   #baseURLOverridden(): boolean {
-    return this._provider !== undefined || this.baseURL !== 'https://api.openai.com/v1';
+    return (
+      this.#explicitDataResidency ||
+      this._provider !== undefined ||
+      this.baseURL !== 'https://api.openai.com/v1'
+    );
   }
 
   protected defaultQuery(): Record<string, string | undefined> | undefined {
@@ -597,6 +758,14 @@ export class OpenAI {
       adminAPIKeyAuth: true,
     },
   ): Promise<NullableHeaders | undefined> {
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    if (
+      authentication instanceof X509WorkloadIdentityAuth &&
+      schemes.adminAPIKeyAuth &&
+      this.adminAPIKey !== null
+    ) {
+      return await this.adminAPIKeyAuth(opts);
+    }
     return buildHeaders([
       schemes.bearerAuth ? await this.bearerAuth(opts) : null,
       schemes.adminAPIKeyAuth ? await this.adminAPIKeyAuth(opts) : null,
@@ -604,8 +773,40 @@ export class OpenAI {
   }
 
   protected async bearerAuth(opts: FinalRequestOptions): Promise<NullableHeaders | undefined> {
-    if (this._workloadIdentityAuth) {
-      return buildHeaders([{ Authorization: `Bearer ${await this._workloadIdentityAuth.getToken()}` }]);
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    if (authentication) {
+      if (authentication instanceof X509WorkloadIdentityAuth) {
+        if (
+          authentication === this._workloadIdentityAuth &&
+          (this.fetchWithAuth !== OpenAI.prototype.fetchWithAuth ||
+            this.fetchWithTimeout !== OpenAI.prototype.fetchWithTimeout)
+        ) {
+          throw new Errors.OpenAIError(
+            'X.509 workload identity does not support overridden fetch dispatch hooks.',
+          );
+        }
+        const snapshots = authentication.headerSnapshots();
+        if (
+          !X509WorkloadIdentityAuth.shouldAuthenticate(
+            opts,
+            snapshots.defaultHeaders,
+            snapshots.requestHeaders,
+          )
+        ) {
+          return undefined;
+        }
+      }
+      const token =
+        authentication instanceof X509WorkloadIdentityAuth
+          ? await authentication.getToken(opts, {
+              apiURL: authentication.requestAPIURL(),
+              ...authentication.headerSnapshots(),
+              ...authentication.requestSnapshot(),
+              signal: authentication.effectiveSignal(),
+              ...authentication.tenantSnapshot(),
+            })
+          : await authentication.getToken();
+      return buildHeaders([{ Authorization: `Bearer ${token}` }]);
     }
     if (this.apiKey == null) {
       return undefined;
@@ -638,7 +839,9 @@ export class OpenAI {
     message: string | undefined,
     headers: Headers,
   ): Errors.APIError {
-    return Errors.APIError.generate(status, error, message, headers);
+    const normalizedError =
+      error && typeof error === 'object' && (error as { error?: unknown }).error == null ? { error } : error;
+    return Errors.APIError.generate(status, normalizedError, message, headers);
   }
 
   async _callApiKey(): Promise<boolean> {
@@ -674,9 +877,8 @@ export class OpenAI {
     defaultBaseURL?: string | undefined,
   ): string {
     const baseURL = (!this.#baseURLOverridden() && defaultBaseURL) || this.baseURL;
-    const url =
-      isAbsoluteURL(path) ?
-        new URL(path)
+    const url = isAbsoluteURL(path)
+      ? new URL(path)
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
@@ -751,7 +953,191 @@ export class OpenAI {
     options: PromiseOrValue<FinalRequestOptions>,
     remainingRetries: number | null = null,
   ): APIPromise<Rsp> {
-    return new APIPromise(this, this.makeRequest(options, remainingRetries, undefined));
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    const request =
+      authentication instanceof X509WorkloadIdentityAuth
+        ? Promise.resolve(options).then((resolved) =>
+            authentication.runRequest(() => this.makeRequest(resolved, remainingRetries, undefined), this),
+          )
+        : this.makeRequest(options, remainingRetries, undefined);
+    return this.responsePromise<Rsp>(request);
+  }
+
+  private responsePromise<Rsp>(
+    request: Promise<APIResponseProps>,
+    parse: (client: OpenAI, props: APIResponseProps) => Promise<any> = (client, props) =>
+      this.parseResponseWithTimeout<Rsp>(client, props),
+  ): APIPromise<Rsp> {
+    const promise = new APIPromise<Rsp>(this, request, (client, props) => {
+      const resume = this.#responseAttempts.get(props.controller)?.continueRequest;
+      return resume ? resume(() => parse(client, props)) : parse(client, props);
+    });
+
+    // A body timeout can retry after the original raw response has arrived. Wait for
+    // parsing before selecting the response so withResponse() reports the retry.
+    promise.withResponse = async () => {
+      const data = await promise;
+      const { response } = await request;
+      return { data, response, request_id: response.headers.get('x-request-id') };
+    };
+    promise._thenUnwrap = <Next>(transform: (data: Rsp, props: APIResponseProps) => Next) =>
+      this.responsePromise<Next>(request, async (client, props) =>
+        addRequestID(transform(await parse(client, props), props), props.response),
+      );
+
+    return promise;
+  }
+
+  private async parseResponseWithTimeout<Rsp>(client: OpenAI, props: APIResponseProps): Promise<any> {
+    if (
+      props.options.stream ||
+      props.options.__binaryResponse ||
+      props.response.status === 204 ||
+      props.response.headers.get('content-length') === '0'
+    ) {
+      return defaultParseResponse<Rsp>(client, props);
+    }
+
+    while (true) {
+      const attempt = this.#responseAttempts.get(props.controller);
+      const timeout = attempt?.timeout ?? props.options.timeout ?? this.timeout;
+      const x509Authentication = attempt?.authentication;
+      const callerSignal = x509Authentication ? props.controller.signal : props.options.signal;
+      const abortError = () =>
+        x509Authentication && callerSignal
+          ? this._makeUserAbortError(callerSignal)
+          : new Errors.APIUserAbortError();
+      let remaining: number;
+      try {
+        remaining =
+          x509Authentication?.remainingTimeout(props.options, timeout) ??
+          Math.max(0, props.startTime + timeout - Date.now());
+      } catch (error) {
+        const cancellation = callerSignal?.aborted ? abortError() : undefined;
+        props.controller.abort();
+        void Shims.CancelReadableStream(props.response.body).catch(() => undefined);
+        throw cancellation ?? error;
+      }
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let abortListener: (() => void) | undefined;
+      let timedOut = false;
+
+      try {
+        // Tool runners preserve a completed buffered turn before cancellation stops the next request.
+        if (callerSignal?.aborted && attempt?.helperMethod !== 'runTools') {
+          throw abortError();
+        }
+
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            timedOut = true;
+            props.controller.abort();
+            reject(new Errors.APIConnectionTimeoutError());
+          }, remaining);
+
+          if (callerSignal) {
+            abortListener = () => {
+              if (!timedOut) reject(abortError());
+            };
+            callerSignal.addEventListener('abort', abortListener, { once: true });
+          }
+        });
+
+        return await Promise.race([defaultParseResponse<Rsp>(client, props), timeoutPromise]);
+      } catch (error) {
+        if (callerSignal?.aborted && !timedOut) {
+          throw abortError();
+        }
+        if (!timedOut) {
+          if (x509Authentication && error instanceof SyntaxError) {
+            throw new SyntaxError('X.509 workload identity API response contains invalid JSON.');
+          }
+          if (x509Authentication && !(error instanceof Errors.OpenAIError)) {
+            throw new Errors.APIConnectionError({
+              message: 'X.509 workload identity API response body could not be read.',
+            });
+          }
+          throw error;
+        }
+
+        const retriesRemaining = attempt?.retriesRemaining ?? 0;
+        if (
+          !retriesRemaining ||
+          attempt?.hasStreamingBody ||
+          props.options.__metadata?.['hasStreamingBody'] ||
+          ((globalThis as any).ReadableStream &&
+            props.options.body instanceof (globalThis as any).ReadableStream) ||
+          (typeof props.options.body === 'object' &&
+            props.options.body !== null &&
+            (Symbol.asyncIterator in props.options.body ||
+              (Symbol.iterator in props.options.body &&
+                'next' in props.options.body &&
+                typeof props.options.body.next === 'function')))
+        ) {
+          throw new Errors.APIConnectionTimeoutError();
+        }
+
+        if (timer !== undefined) clearTimeout(timer);
+        if (abortListener) callerSignal?.removeEventListener('abort', abortListener);
+        abortListener = undefined;
+
+        const next = await this.retryRequest(
+          props.options,
+          retriesRemaining,
+          props.retryOfRequestLogID ?? props.requestLogID,
+        );
+        Object.assign(props, next);
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        if (abortListener) callerSignal?.removeEventListener('abort', abortListener);
+      }
+    }
+  }
+
+  /** Keeps terminal X.509 error-body consumption inside the original logical request deadline. */
+  private async readX509ResponseError(
+    response: Response,
+    options: FinalRequestOptions,
+    timeout: number,
+    controller: AbortController,
+    authentication: X509WorkloadIdentityAuth,
+  ): Promise<string> {
+    const deadline = new AbortController();
+    const callerSignal = controller.signal;
+    let timedOut = false;
+    const cancel = () => deadline.abort(callerSignal.reason);
+    callerSignal.addEventListener('abort', cancel, { once: true });
+    if (callerSignal.aborted) {
+      cancel();
+    }
+
+    try {
+      const remaining = authentication.remainingTimeout(options, timeout);
+      const expiration = authentication.waitForRetry(remaining, deadline.signal).then(() => {
+        throw new Errors.APIConnectionTimeoutError();
+      });
+      const body = await Promise.race([
+        response.text().catch(() => 'X.509 workload identity API response body could not be read.'),
+        expiration,
+      ]);
+      if (callerSignal.aborted) {
+        throw this._makeUserAbortError(callerSignal);
+      }
+      return body;
+    } catch (error) {
+      if (error instanceof Errors.APIConnectionTimeoutError) {
+        timedOut = !callerSignal.aborted;
+        controller.abort();
+        void Shims.CancelReadableStream(response.body).catch(() => undefined);
+      }
+      if (callerSignal.aborted && !timedOut) {
+        throw this._makeUserAbortError(callerSignal);
+      }
+      throw error;
+    } finally {
+      callerSignal.removeEventListener('abort', cancel);
+      deadline.abort();
+    }
   }
 
   private async makeRequest(
@@ -767,18 +1153,85 @@ export class OpenAI {
 
     await this.prepareOptions(options);
 
-    const { req, url, timeout } = await this.buildRequest(options, {
-      retryCount: maxRetries - retriesRemaining,
-    });
-    const hasStreamingBody = options.__metadata?.['hasStreamingBody'] === true;
-
-    await this.prepareRequest(req, { url, options });
-    await this._provider?.prepareRequest?.(req, { url, options });
+    const x509Authentication = this.#x509Authentication;
+    x509Authentication?.beginRequestPlanning();
+    let built: { req: FinalizedRequestInit; url: string; timeout: number };
+    try {
+      const candidate = await this.buildRequest(options, {
+        retryCount: maxRetries - retriesRemaining,
+      });
+      built = { req: candidate.req, url: candidate.url, timeout: candidate.timeout };
+      if (x509Authentication) {
+        validatePositiveInteger('timeout', built.timeout);
+        x509Authentication.authorizePlannedRequest(built.url, built.req, built.timeout);
+        if (X509WorkloadIdentityAuth.isStreamingRequestBody(built.req.body)) {
+          options.__metadata = { ...options.__metadata, hasStreamingBody: true };
+        }
+        await this.prepareRequest(built.req, { url: built.url, options });
+        await this._provider?.prepareRequest?.(built.req, { url: built.url, options });
+        x509Authentication.beginRequestPlanning();
+        x509Authentication.authorizePlannedRequest(built.url, built.req, built.timeout, true);
+        if (X509WorkloadIdentityAuth.isStreamingRequestBody(built.req.body)) {
+          options.__metadata = { ...options.__metadata, hasStreamingBody: true };
+        }
+        const callerSignal = x509Authentication.requestSnapshot().signal;
+        if (callerSignal?.aborted || built.req.signal?.aborted) {
+          throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : built.req.signal!);
+        }
+        x509Authentication.setEffectiveSignal(
+          built.req.signal || callerSignal
+            ? createRequestController(built.req.signal ?? callerSignal, callerSignal).signal
+            : undefined,
+        );
+        x509Authentication.beginRequestNetwork();
+        const security = options.__security ?? { bearerAuth: true };
+        const authenticationHeaders = await this.authHeaders(options, security);
+        const suppliedHeaders = x509Authentication.headerSnapshots();
+        const supplied = buildHeaders([suppliedHeaders.defaultHeaders, suppliedHeaders.requestHeaders]);
+        for (const [name, value] of authenticationHeaders?.values ?? []) {
+          if (!supplied.nulls.has(name) && !built.req.headers.has(name)) {
+            built.req.headers.set(name, value);
+          }
+        }
+        this.validateHeaders(buildHeaders([supplied, built.req.headers]), security);
+      }
+    } catch (error) {
+      x509Authentication?.retireRequestBody();
+      if (
+        x509Authentication &&
+        retriesRemaining &&
+        !options.__metadata?.['hasStreamingBody'] &&
+        X509WorkloadIdentityAuth.isRetryableFailure(error)
+      ) {
+        return await this.retryRequest(
+          options,
+          retriesRemaining,
+          retryOfRequestLogID ?? 'x509-token-exchange',
+          X509WorkloadIdentityAuth.retryHeaders(error),
+        );
+      }
+      throw error;
+    }
+    const { req, url } = built;
+    const timeout = x509Authentication
+      ? Math.min(built.timeout, x509Authentication.requestSnapshot().timeout)
+      : built.timeout;
+    x509Authentication?.bindRequest(options, req, this.adminAPIKey);
+    let hasStreamingBody = options.__metadata?.['hasStreamingBody'] === true;
+
+    if (!x509Authentication) {
+      await this.prepareRequest(req, { url, options });
+      await this._provider?.prepareRequest?.(req, { url, options });
+    }
+    x509Authentication?.adoptRequestHeaders(req);
+    if (x509Authentication && X509WorkloadIdentityAuth.isStreamingRequestBody(req.body)) {
+      hasStreamingBody = true;
+    }
 
     /** Not an API request ID, just for correlating local log entries. */
     const requestLogID = 'log_' + ((Math.random() * (1 << 24)) | 0).toString(16).padStart(6, '0');
     const retryLogStr = retryOfRequestLogID === undefined ? '' : `, retryOf: ${retryOfRequestLogID}`;
-    const startTime = Date.now();
+    const startTime = x509Authentication?.requestStartedAt(options) ?? Date.now();
 
     loggerFor(this).debug(
       `[${requestLogID}] sending request`,
@@ -786,24 +1239,36 @@ export class OpenAI {
         retryOfRequestLogID,
         method: options.method,
         url,
-        options,
+        options: x509Authentication ? { body: req.body, ...x509Authentication.requestSnapshot() } : options,
         headers: req.headers,
       }),
     );
 
-    if (options.signal?.aborted) {
-      throw new Errors.APIUserAbortError();
+    const callerSignal = x509Authentication ? x509Authentication.requestSnapshot().signal : options.signal;
+    if (callerSignal?.aborted || req.signal?.aborted) {
+      throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : req.signal!);
     }
-
     const security = options.__security ?? { bearerAuth: true };
-    const controller = new AbortController();
-    const response = await this.fetchWithAuth(url, req, timeout, controller, security).catch(castToError);
+    // Request hooks may replace the caller signal before it reaches fetch.
+    const controller =
+      x509Authentication || this.fetchWithTimeout === OpenAI.prototype.fetchWithTimeout
+        ? createRequestController(
+            req.signal ?? (x509Authentication ? callerSignal : undefined),
+            x509Authentication ? callerSignal : undefined,
+          )
+        : new AbortController();
+    const remainingTimeout = x509Authentication?.remainingTimeout(options, timeout) ?? timeout;
+    const fetchWithAuth = x509Authentication ? OpenAI.prototype.fetchWithAuth : this.fetchWithAuth;
+    x509Authentication?.releaseRequestBody(req.body);
+    const response = await fetchWithAuth
+      .call(this, url, req, remainingTimeout, controller, security)
+      .catch(castToError);
     const headersTime = Date.now();
 
     if (response instanceof globalThis.Error) {
       const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
-      if (options.signal?.aborted) {
-        throw new Errors.APIUserAbortError();
+      if (callerSignal?.aborted || req.signal?.aborted) {
+        throw this._makeUserAbortError(callerSignal?.aborted ? callerSignal : req.signal!);
       }
       // detect native connection timeout errors
       // deno throws "TypeError: error sending request for url (https://example/): client error (Connect): tcp connect error: Operation timed out (os error 60): Operation timed out (os error 60)"
@@ -812,7 +1277,11 @@ export class OpenAI {
       const isTimeout =
         isAbortError(response) ||
         /timed? ?out/i.test(String(response) + ('cause' in response ? String(response.cause) : ''));
-      if (retriesRemaining && !hasStreamingBody) {
+      if (
+        retriesRemaining &&
+        !hasStreamingBody &&
+        (!x509Authentication || isTransientX509ConnectionError(response))
+      ) {
         loggerFor(this).info(
           `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - ${retryMessage}`,
         );
@@ -822,13 +1291,14 @@ export class OpenAI {
             retryOfRequestLogID,
             url,
             durationMs: headersTime - startTime,
-            message: response.message,
+            message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
           }),
         );
         return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
       }
-      const terminalMessage =
-        hasStreamingBody ? 'error; streaming body cannot be retried' : 'error; no more retries left';
+      const terminalMessage = hasStreamingBody
+        ? 'error; streaming body cannot be retried'
+        : 'error; no more retries left';
       loggerFor(this).info(
         `[${requestLogID}] connection ${isTimeout ? 'timed out' : 'failed'} - ${terminalMessage}`,
       );
@@ -838,14 +1308,33 @@ export class OpenAI {
           retryOfRequestLogID,
           url,
           durationMs: headersTime - startTime,
-          message: response.message,
+          message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
         }),
       );
       if (response instanceof OAuthError || response instanceof SubjectTokenProviderError) {
         throw response;
       }
       if (isTimeout) {
-        throw new Errors.APIConnectionTimeoutError();
+        const transportCause = 'cause' in response ? response.cause : undefined;
+        const isHeadersTimeout =
+          typeof transportCause === 'object' &&
+          transportCause !== null &&
+          'code' in transportCause &&
+          transportCause.code === 'UND_ERR_HEADERS_TIMEOUT';
+        const timeoutError = isHeadersTimeout
+          ? new Errors.APIConnectionTimeoutError({
+              message:
+                'Request timed out. Node.js fetch timed out waiting for response headers; ' +
+                'configure a matching undici fetch and fetchOptions.dispatcher with an Agent whose headersTimeout is at least the SDK timeout.',
+            })
+          : new Errors.APIConnectionTimeoutError();
+        if (x509Authentication) {
+          throw new Errors.APIConnectionTimeoutError();
+        }
+        throw Object.assign(timeoutError, { cause: response });
+      }
+      if (x509Authentication) {
+        throw new Errors.APIConnectionError({ message: 'X.509 workload identity API connection failed.' });
       }
       throw new Errors.APIConnectionError({
         message: getConnectionErrorMessage(response),
@@ -862,35 +1351,57 @@ export class OpenAI {
     } with status ${response.status} in ${headersTime - startTime}ms`;
 
     if (!response.ok) {
+      const rejectedX509Credential =
+        response.status === 401 &&
+        x509Authentication &&
+        security.bearerAuth &&
+        x509Authentication.usedWorkloadToken(options);
+      if (rejectedX509Credential) {
+        x509Authentication.invalidateToken();
+      }
       if (
         response.status === 401 &&
-        this._workloadIdentityAuth &&
+        (x509Authentication || this._workloadIdentityAuth) &&
         security.bearerAuth &&
-        !options.__metadata?.['hasStreamingBody'] &&
+        (!x509Authentication || x509Authentication.usedWorkloadToken(options)) &&
+        (!x509Authentication || retriesRemaining > 0) &&
+        !hasStreamingBody &&
         !options.__metadata?.['workloadIdentityTokenRefreshed']
       ) {
-        await Shims.CancelReadableStream(response.body);
-        this._workloadIdentityAuth.invalidateToken();
+        if (x509Authentication) {
+          void Shims.CancelReadableStream(response.body).catch(() => undefined);
+        } else {
+          await Shims.CancelReadableStream(response.body);
+          this._workloadIdentityAuth?.invalidateToken();
+        }
 
-        return this.makeRequest(
-          {
-            ...options,
-            __metadata: {
-              ...options.__metadata,
-              workloadIdentityTokenRefreshed: true,
-            },
+        const replayOptions = {
+          ...options,
+          __metadata: {
+            ...options.__metadata,
+            workloadIdentityTokenRefreshed: true,
           },
-          retriesRemaining,
+        };
+        return this.makeRequest(
+          replayOptions,
+          x509Authentication ? retriesRemaining - 1 : retriesRemaining,
           retryOfRequestLogID ?? requestLogID,
         );
       }
 
-      const shouldRetry = await this.shouldRetry(response);
+      const shouldRetry =
+        rejectedX509Credential && options.__metadata?.['workloadIdentityTokenRefreshed']
+          ? false
+          : await this.shouldRetry(response);
       if (retriesRemaining && shouldRetry && !hasStreamingBody) {
         const retryMessage = `retrying, ${retriesRemaining} attempts remaining`;
 
         // We don't need the body of this response.
-        await Shims.CancelReadableStream(response.body);
+        if (x509Authentication) {
+          void Shims.CancelReadableStream(response.body).catch(() => undefined);
+        } else {
+          await Shims.CancelReadableStream(response.body);
+        }
         loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
         loggerFor(this).debug(
           `[${requestLogID}] response error (${retryMessage})`,
@@ -910,15 +1421,17 @@ export class OpenAI {
         );
       }
 
-      const retryMessage =
-        shouldRetry ?
-          hasStreamingBody ? `error; streaming body cannot be retried`
+      const retryMessage = shouldRetry
+        ? hasStreamingBody
+          ? `error; streaming body cannot be retried`
           : `error; no more retries left`
         : `error; not retryable`;
 
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
-      const errText = await response.text().catch((err: any) => castToError(err).message);
+      const errText = x509Authentication
+        ? await this.readX509ResponseError(response, options, timeout, controller, x509Authentication)
+        : await response.text().catch((err: any) => castToError(err).message);
       const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
@@ -950,6 +1463,16 @@ export class OpenAI {
       }),
     );
 
+    const continueRequest = x509Authentication?.continuation();
+    x509Authentication?.releaseRequestCredentials();
+    this.#responseAttempts.set(controller, {
+      timeout,
+      retriesRemaining,
+      hasStreamingBody,
+      ...(x509Authentication ? { authentication: x509Authentication } : {}),
+      helperMethod: options.__metadata?.['helperMethod'],
+      ...(continueRequest ? { continueRequest } : {}),
+    });
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
@@ -960,9 +1483,9 @@ export class OpenAI {
   ): Pagination.PagePromise<PageClass, Item> {
     return this.requestAPIList(
       Page,
-      opts && 'then' in opts ?
-        opts.then((opts) => ({ method: 'get', path, ...opts }))
-      : { method: 'get', path, ...opts },
+      opts && 'then' in opts
+        ? opts.then((opts) => ({ method: 'get', path, ...opts }))
+        : { method: 'get', path, ...opts },
     );
   }
 
@@ -973,8 +1496,24 @@ export class OpenAI {
     Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
     options: PromiseOrValue<FinalRequestOptions>,
   ): Pagination.PagePromise<PageClass, Item> {
-    const request = this.makeRequest(options, null, undefined);
-    return new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
+    const authentication = this.#x509Authentication ?? this._workloadIdentityAuth;
+    const request =
+      authentication instanceof X509WorkloadIdentityAuth
+        ? Promise.resolve(options).then((resolved) =>
+            authentication.runRequest(() => this.makeRequest(resolved, null, undefined), this),
+          )
+        : this.makeRequest(options, null, undefined);
+    const page = new Pagination.PagePromise<PageClass, Item>(this as any as OpenAI, request, Page);
+    const guarded = this.responsePromise<PageClass>(request, async (client, props) => {
+      const body = await this.parseResponseWithTimeout(client, props);
+      return new Page(client, props.response, body, props.options);
+    });
+    page.then = guarded.then.bind(guarded);
+    page.catch = guarded.catch.bind(guarded);
+    page.finally = guarded.finally.bind(guarded);
+    page.withResponse = guarded.withResponse.bind(guarded);
+    page._thenUnwrap = guarded._thenUnwrap.bind(guarded);
+    return page;
   }
 
   protected async fetchWithAuth(
@@ -987,7 +1526,7 @@ export class OpenAI {
       adminAPIKeyAuth: true,
     },
   ): Promise<Response> {
-    if (this._workloadIdentityAuth && schemes.bearerAuth) {
+    if (this._workloadIdentityAuth && !this.#x509Fetch && schemes.bearerAuth) {
       const headers = init.headers as Headers;
       const authHeader = headers.get('Authorization');
       if (!authHeader || authHeader === `Bearer ${WORKLOAD_IDENTITY_API_KEY_PLACEHOLDER}`) {
@@ -996,7 +1535,8 @@ export class OpenAI {
       }
     }
 
-    const response = await this.fetchWithTimeout(url, init, timeout, controller);
+    const fetchWithTimeout = this.#x509Fetch ? OpenAI.prototype.fetchWithTimeout : this.fetchWithTimeout;
+    const response = await fetchWithTimeout.call(this, url, init, timeout, controller);
 
     return response;
   }
@@ -1009,7 +1549,8 @@ export class OpenAI {
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
     const abort = this._makeAbort(controller);
-    if (signal) signal.addEventListener('abort', abort, { once: true });
+    const composed = !!signal && composedCallerSignals.get(controller) === signal;
+    if (signal && !composed) signal.addEventListener('abort', abort, { once: true });
 
     const timeout = setTimeout(abort, ms);
 
@@ -1031,7 +1572,10 @@ export class OpenAI {
 
     try {
       // use undefined this binding; fetch errors if bound to something else in browser/cloudflare
-      return await this.fetch.call(undefined, url, fetchOptions);
+      return await (this.#x509Fetch ?? this.fetch).call(undefined, url, fetchOptions);
+    } catch (err) {
+      if (signal && !composed) signal.removeEventListener('abort', abort);
+      throw err;
     } finally {
       clearTimeout(timeout);
     }
@@ -1079,7 +1623,7 @@ export class OpenAI {
 
     // About the Retry-After header: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After
     const retryAfterHeader = responseHeaders?.get('retry-after');
-    if (retryAfterHeader && !timeoutMillis) {
+    if (retryAfterHeader && timeoutMillis === undefined) {
       const timeoutSeconds = parseFloat(retryAfterHeader);
       if (!Number.isNaN(timeoutSeconds)) {
         timeoutMillis = timeoutSeconds * 1000;
@@ -1090,11 +1634,30 @@ export class OpenAI {
 
     // If the API asks us to wait a certain amount of time, just do what it
     // says, but otherwise calculate a default
-    if (timeoutMillis === undefined) {
+    if (
+      timeoutMillis === undefined ||
+      !Number.isFinite(timeoutMillis) ||
+      timeoutMillis < 0 ||
+      timeoutMillis > 60 * 1000
+    ) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
-    await sleep(timeoutMillis);
+    const x509Authentication = this.#x509Authentication;
+    if (x509Authentication) {
+      const remaining = x509Authentication.remainingTimeout(
+        options,
+        x509Authentication.requestSnapshot().timeout,
+      );
+      if (timeoutMillis >= remaining) {
+        throw new Errors.APIConnectionTimeoutError();
+      }
+    }
+    if (x509Authentication) {
+      await x509Authentication.waitForRetry(timeoutMillis, x509Authentication.effectiveSignal());
+    } else {
+      await sleep(timeoutMillis);
+    }
 
     return this.makeRequest(options, retriesRemaining - 1, requestLogID);
   }
@@ -1118,12 +1681,46 @@ export class OpenAI {
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},
   ): Promise<{ req: FinalizedRequestInit; url: string; timeout: number }> {
+    if (this.#x509Authentication && !this.#x509Authentication.inRequest(this)) {
+      const authentication = this.#x509Authentication;
+      return await authentication.runRequest(async () => {
+        const built = await OpenAI.prototype.buildRequest.call(this, inputOptions, { retryCount });
+        authentication.releaseRequestBody(built.req.body);
+        return built;
+      }, this);
+    }
     const options = { ...inputOptions };
+    const x509Authentication = this.#x509Authentication;
+    const x509Tenant = x509Authentication?.snapshotTenant(this.organization, this.project);
+    const x509Headers = x509Authentication?.snapshotHeaders(this._options.defaultHeaders, options.headers);
+    if (x509Headers) {
+      options.headers = x509Headers.requestHeaders;
+    }
+    const x509ClientFetchOptions = x509Authentication
+      ? snapshotX509RequestOptions(this.fetchOptions)
+      : undefined;
+    const x509RequestFetchOptions = x509Authentication
+      ? snapshotX509RequestOptions(options.fetchOptions)
+      : undefined;
     const { method, path, query, defaultBaseURL } = options;
 
     const url = this.buildURL(path!, query as Record<string, unknown>, defaultBaseURL);
-    if ('timeout' in options) validatePositiveInteger('timeout', options.timeout);
+    x509Authentication?.snapshotAPIURL(url);
+    const explicitTimeout = 'timeout' in options;
+    if (explicitTimeout) validatePositiveInteger('timeout', options.timeout);
     options.timeout = options.timeout ?? this.timeout;
+    if (x509Authentication && x509RequestFetchOptions) {
+      x509Authentication.snapshotRequest(options.signal, options.timeout, x509RequestFetchOptions);
+    }
+    if (x509Authentication) {
+      const snapshot = x509Authentication.requestSnapshot();
+      options.timeout = snapshot.timeout;
+      if (snapshot.signal === undefined) {
+        delete options.signal;
+      } else {
+        options.signal = snapshot.signal;
+      }
+    }
     const { bodyHeaders, body, isStreamingBody } = this.buildBody({ options });
 
     if (isStreamingBody) {
@@ -1131,9 +1728,18 @@ export class OpenAI {
         ...inputOptions.__metadata,
         hasStreamingBody: true,
       };
+      x509Authentication?.ownRequestBody(body, options.body);
     }
 
-    const reqHeaders = await this.buildHeaders({ options: inputOptions, method, bodyHeaders, retryCount });
+    const reqHeaders = await this.buildHeaders({
+      options: inputOptions,
+      method,
+      bodyHeaders,
+      retryCount,
+      x509Headers,
+      x509Timeout: explicitTimeout ? options.timeout : undefined,
+      x509Tenant,
+    });
 
     const req: FinalizedRequestInit = {
       method,
@@ -1142,8 +1748,8 @@ export class OpenAI {
       ...((globalThis as any).ReadableStream &&
         body instanceof (globalThis as any).ReadableStream && { duplex: 'half' }),
       ...(body && { body }),
-      ...((this.fetchOptions as any) ?? {}),
-      ...((options.fetchOptions as any) ?? {}),
+      ...(((x509Authentication ? x509ClientFetchOptions : this.fetchOptions) as any) ?? {}),
+      ...(((x509Authentication ? x509RequestFetchOptions : options.fetchOptions) as any) ?? {}),
     };
 
     return { req, url, timeout: options.timeout };
@@ -1154,11 +1760,17 @@ export class OpenAI {
     method,
     bodyHeaders,
     retryCount,
+    x509Headers,
+    x509Timeout,
+    x509Tenant,
   }: {
     options: FinalRequestOptions;
     method: HTTPMethod;
     bodyHeaders: HeadersLike;
     retryCount: number;
+    x509Headers?: { defaultHeaders: NullableHeaders; requestHeaders: NullableHeaders } | undefined;
+    x509Timeout: number | undefined;
+    x509Tenant?: { organization: string | null; project: string | null } | undefined;
   }): Promise<Headers> {
     let idempotencyHeaders: HeadersLike = {};
     if (this.idempotencyHeader && method !== 'get') {
@@ -1166,26 +1778,29 @@ export class OpenAI {
       idempotencyHeaders[this.idempotencyHeader] = options.idempotencyKey;
     }
 
+    const helperMethod = options.__metadata?.['helperMethod'];
+    const timeout = x509Headers ? x509Timeout : options.timeout;
     const headers = buildHeaders([
       idempotencyHeaders,
       {
         Accept: 'application/json',
-        'User-Agent': this.getUserAgent(),
+        ...(!isRunningInBrowserOrBrowserWorker() ? { 'User-Agent': this.getUserAgent() } : undefined),
         'X-Stainless-Retry-Count': String(retryCount),
-        ...(options.timeout ? { 'X-Stainless-Timeout': String(Math.trunc(options.timeout / 1000)) } : {}),
+        ...(timeout ? { 'X-Stainless-Timeout': String(Math.trunc(timeout / 1000)) } : {}),
         ...getPlatformHeaders(),
-        'OpenAI-Organization': this.organization,
-        'OpenAI-Project': this.project,
+        ...(typeof helperMethod === 'string' ? { 'X-Stainless-Helper-Method': helperMethod } : {}),
+        'OpenAI-Organization': x509Tenant ? x509Tenant.organization : this.organization,
+        'OpenAI-Project': x509Tenant ? x509Tenant.project : this.project,
       },
-      this._provider ? undefined : (
-        await this.authHeaders(options, options.__security ?? { bearerAuth: true })
-      ),
-      this._options.defaultHeaders,
+      this._provider || this.#x509Authentication?.isPlanningRequest()
+        ? undefined
+        : await this.authHeaders(options, options.__security ?? { bearerAuth: true }),
+      x509Headers?.defaultHeaders ?? this._options.defaultHeaders,
       bodyHeaders,
-      options.headers,
+      x509Headers?.requestHeaders ?? options.headers,
     ]);
 
-    if (!this._provider) {
+    if (!this._provider && !this.#x509Authentication?.isPlanningRequest()) {
       this.validateHeaders(headers, options.__security ?? { bearerAuth: true });
     }
 
@@ -1198,6 +1813,12 @@ export class OpenAI {
     return () => controller.abort();
   }
 
+  private _makeUserAbortError(signal: NonNullable<RequestInit['signal']>): Errors.APIUserAbortError {
+    const error = new Errors.APIUserAbortError();
+    Object.defineProperty(error, 'cause', { value: signal.reason, writable: true, configurable: true });
+    return error;
+  }
+
   private buildBody({ options }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -1345,6 +1966,9 @@ export class OpenAI {
   evals: API.Evals = new API.Evals(this);
   containers: API.Containers = new API.Containers(this);
   skills: API.Skills = new API.Skills(this);
+  /**
+   * @deprecated The Sora API is scheduled to permanently shut down on September 24, 2026.
+   */
   videos: API.Videos = new API.Videos(this);
 }
 
@@ -1373,6 +1997,37 @@ OpenAI.Containers = Containers;
 OpenAI.Skills = Skills;
 OpenAI.Videos = Videos;
 
+const composedCallerSignals = new WeakMap<AbortController, AbortSignal>();
+
+function createRequestController(
+  callerSignal: AbortSignal | null | undefined,
+  originalSignal?: AbortSignal | null,
+): AbortController {
+  const controller = new AbortController();
+  if (!callerSignal) return controller;
+
+  const nativeAbortSignal = (globalThis as any).AbortSignal;
+  if (typeof nativeAbortSignal?.any !== 'function' || !(callerSignal instanceof nativeAbortSignal)) {
+    return controller;
+  }
+
+  try {
+    // Native composition keeps cancellation active after response headers without
+    // retaining an abort listener on the caller's signal or changing its reason.
+    const signals = [controller.signal, callerSignal];
+    if (originalSignal && originalSignal !== callerSignal) {
+      signals.push(originalSignal);
+    }
+    const composed = nativeAbortSignal.any(signals) as AbortSignal;
+    Object.defineProperty(controller, 'signal', { value: composed, configurable: true });
+    composedCallerSignals.set(controller, callerSignal);
+  } catch {
+    // Older or incompatible runtimes retain the existing listener-based fallback.
+  }
+
+  return controller;
+}
+
 function getConnectionErrorMessage(error: Error): string | undefined {
   if (isUndiciDispatcherVersionMismatchError(error)) {
     return `Connection error. This may be caused by passing an undici dispatcher, such as ProxyAgent, that is incompatible with the fetch implementation. If you are using undici's ProxyAgent, pass the fetch implementation from the same undici package: import { fetch, ProxyAgent } from 'undici'; new OpenAI({ fetch, fetchOptions: { dispatcher: new ProxyAgent(...) } });`;
@@ -1407,6 +2062,7 @@ function isUndiciDispatcherVersionMismatchError(error: unknown): boolean {
 }
 
 export declare namespace OpenAI {
+  export { type DataResidency as DataResidency };
   export type RequestOptions = Opts.RequestOptions;
 
   export import Page = Pagination.Page;