openai 7.16.0 → 7.17.0

package/src/auth/workload-identity-auth.ts

@@ -53,6 +53,7 @@ function calculateRefreshAt(
 const NATIVE_RESPONSE_PROTOTYPE = Response.prototype;
 const READ_NATIVE_RESPONSE_BODY = NATIVE_RESPONSE_PROTOTYPE.arrayBuffer;
 
+// oxlint-disable-next-line anti-slop/no-object-parameters -- Custom fetch response prototypes are verified through descriptors before trusting their native contract.
 function isResponsePrototype(response: Response, prototype: object): boolean {
   const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
   if (
@@ -73,6 +74,7 @@ function isResponsePrototype(response: Response, prototype: object): boolean {
   );
 }
 
+// oxlint-disable-next-line anti-slop/no-object-parameters -- The prototype walk compares untrusted cross-realm objects by identity and descriptor metadata.
 function isResponseBodyPrototype(prototype: object, responsePrototype: object | null): boolean {
   if (prototype === responsePrototype) {
     return true;
@@ -89,10 +91,12 @@ function isResponseBodyPrototype(prototype: object, responsePrototype: object |
 }
 
 function decodeNativeResponseBody(body: ArrayBuffer): string {
+  // SAFETY: Bun is an optional runtime global; its version is checked before selecting Bun-specific decoding behavior.
   const scope = globalThis as typeof globalThis & { Bun?: { version?: unknown } };
   return new TextDecoder('utf-8', { ignoreBOM: typeof scope.Bun?.version === 'string' }).decode(body);
 }
 
+// oxlint-disable-next-line anti-slop/no-unknown-returns -- Decoded token JSON remains untrusted until the caller validates its fields.
 async function parseOAuthTokenResponse(response: Response): Promise<unknown> {
   let readText: ((this: Response) => Promise<string>) | undefined;
   let responsePrototype: object | null = null;
@@ -140,6 +144,7 @@ async function parseOAuthTokenResponse(response: Response): Promise<unknown> {
 }
 
 function isUnsafeAccessToken(accessToken: string): boolean {
+  // SAFETY: Bun is an optional runtime global; its version is checked before selecting Bun-specific decoding behavior.
   const scope = globalThis as typeof globalThis & { Bun?: { version?: unknown } };
   if (typeof scope.Bun?.version === 'string') {
     return /[^\t\u0020-\u007E]|^[\t ]|[\t ]$/u.test(accessToken);
@@ -173,7 +178,9 @@ export class WorkloadIdentityAuth {
     this.config = {
       identityProviderId,
       serviceAccountId,
+      // Spread creates an own data property without invoking inherited setters or changing the object prototype.
       ...(clientId === undefined ? {} : { clientId }),
+      // Spread creates an own data property without invoking inherited setters or changing the object prototype.
       ...(refreshBufferSeconds === undefined ? {} : { refreshBufferSeconds }),
       provider: {
         tokenType: provider.tokenType,
@@ -226,6 +233,7 @@ export class WorkloadIdentityAuth {
 
   private async refreshToken(generation: number): Promise<string> {
     const subjectToken = await this.config.provider.getToken();
+    // oxlint-disable-next-line anti-slop/no-known-value-widening -- The token-exchange field dictionary gains an optional client_id after its required fields are initialized.
     const body: Record<string, string> = {
       grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
       subject_token: subjectToken,
@@ -260,7 +268,7 @@ export class WorkloadIdentityAuth {
       }
 
       if (response.status === 400 || response.status === 401 || response.status === 403) {
-        throw new OAuthError(response.status as 400 | 401 | 403, body, response.headers);
+        throw new OAuthError(response.status, body, response.headers);
       }
       throw APIError.generate(
         response.status,
@@ -283,6 +291,7 @@ export class WorkloadIdentityAuth {
       throw new OpenAIError("Token exchange response missing 'access_token' field");
     }
 
+    // SAFETY: The token response was checked as an object with a valid access token; expires_in is still validated by calculateExpiresAt.
     const expiresIn = (tokenResponse as Partial<TokenExchangeResponse>).expires_in ?? 3600;
     const expiresAt = calculateExpiresAt(expiresIn, exchangeStartedAt);
 

package/src/auth/x509-transport.ts

@@ -82,6 +82,7 @@ function safeOptionRecord(
   if (prototype !== Object.prototype && prototype !== null) {
     throw new Error(`X.509 ${label} options must have only own plain data properties.`);
   }
+  // SAFETY: The snapshot starts empty with no prototype; only checked own data properties are copied into it below.
   const snapshot = Object.create(null) as Record<string, unknown>;
   for (const name of Reflect.ownKeys(value)) {
     if (typeof name !== 'string' || !allowed.has(name)) {
@@ -179,6 +180,7 @@ function validatedCredentialOptions(options: X509CredentialOptions): ValidatedX5
   const leaf = new X509Certificate(certificateChain);
   const privateKey = createPrivateKey({
     key: privateKeyPEM,
+    // Create an own data property so an inherited setter cannot intercept the private-key passphrase.
     ...(passphrase === undefined ? {} : { passphrase }),
   });
   if (!leaf.checkPrivateKey(privateKey)) {
@@ -239,6 +241,7 @@ function credentialDispatcher(
   requestTls: VerifiedX509TLSOptions,
 ): { dispatcher: Agent | ProxyAgent; proxy: X509ProxyMode } {
   if (proxyOptionsInput === undefined) {
+    // oxlint-disable-next-line anti-slop/no-known-value-widening -- The dispatcher owner returns one contract for direct Agents and both supported CONNECT proxy modes.
     return { dispatcher: new Agent({ connect: requestTls }), proxy: 'direct' };
   }
 
@@ -262,16 +265,20 @@ function credentialDispatcher(
   }
   const auth = proxyAuthentication(url);
 
+  // oxlint-disable-next-line anti-slop/no-known-value-widening -- The declared transport contract preserves the same dispatcher and proxy types across both construction paths.
   return {
     proxy,
     dispatcher: new ProxyAgent({
       uri: url.href,
+      // Define proxy credentials as own data without invoking inherited setters.
       ...(auth === undefined ? {} : { auth }),
       requestTls,
+      // Keep the optional proxy TLS configuration as an own data property.
       ...(proxy === 'https-connect'
         ? {
             proxyTls: {
               rejectUnauthorized: true,
+              // Define explicit proxy trust roots as own data without invoking inherited setters.
               ...(proxyCA === undefined ? {} : { ca: proxyCA }),
             },
           }
@@ -300,6 +307,7 @@ export function createX509Transport(options: X509TransportOptions): X509Transpor
         transport: capability,
         identityProviderId,
         serviceAccountId,
+        // Preserve the cancellation signal as own data without invoking inherited setters.
         ...(signal ? { signal } : {}),
       }),
     run: (operation) =>
@@ -315,11 +323,13 @@ export function createX509Transport(options: X509TransportOptions): X509Transpor
 export function fromX509(options: X509CredentialOptions): X509Credential {
   const configured = validatedCredentialOptions(options);
 
-  const requestTls = {
+  const requestTls: VerifiedX509TLSOptions = {
     cert: configured.certificateChain,
     key: configured.privateKey,
-    rejectUnauthorized: true as const,
+    rejectUnauthorized: true,
+    // Define the TLS passphrase as own data so inherited setters cannot intercept it.
     ...(configured.passphrase === undefined ? {} : { passphrase: configured.passphrase }),
+    // Define explicit workload trust roots as own data without invoking inherited setters.
     ...(configured.ca === undefined ? {} : { ca: configured.ca }),
   };
   const { dispatcher, proxy } = credentialDispatcher(configured.proxy, requestTls);
@@ -335,6 +345,7 @@ export function fromX509(options: X509CredentialOptions): X509Credential {
       type: 'x509',
       identityProviderId: configured.identityProviderId,
       serviceAccountId: configured.serviceAccountId,
+      // Preserve the optional refresh setting as own data without invoking inherited setters.
       ...(configured.refreshBufferSeconds === undefined
         ? {}
         : { refreshBufferSeconds: configured.refreshBufferSeconds }),

package/src/azure.ts

@@ -101,6 +101,7 @@ export class AzureOpenAI extends OpenAI {
       );
     }
 
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Azure accepts JavaScript credential configuration; distinguish static keys from callable token providers.
     if (typeof azureADTokenProvider === 'function') {
       dangerouslyAllowBrowser ??= true;
     }
@@ -143,6 +144,7 @@ export class AzureOpenAI extends OpenAI {
       apiKey: azureADTokenProvider ?? apiKey,
       baseURL,
       ...opts,
+      // Spread creates an own data property without invoking inherited setters or changing the object prototype.
       ...(dangerouslyAllowBrowser === undefined ? {} : { dangerouslyAllowBrowser }),
     });
 
@@ -224,6 +226,7 @@ export class AzureOpenAI extends OpenAI {
     schemes?: { bearerAuth?: boolean; adminAPIKeyAuth?: boolean },
   ): Promise<NullableHeaders | undefined> {
     const security = schemes ?? { bearerAuth: true, adminAPIKeyAuth: true };
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Azure accepts JavaScript credential configuration; distinguish static keys from callable token providers.
     if (security.bearerAuth && typeof this._options.apiKey === 'string') {
       return buildHeaders([{ 'api-key': this.apiKey }]);
     }

package/src/bedrock.ts

@@ -112,6 +112,7 @@ function addBedrockOutputText<ResponseT extends ResponsesAPI.Response>(response:
 function restoreBedrockStreamOutputText(responses: API.Responses): API.Responses {
   const stream = responses.stream.bind(responses);
 
+  // SAFETY: The wrapper forwards the original stream parameters and preserves its generic result, only repairing the final response's output_text property.
   responses.stream = ((body: ResponseStreamParams, options?: RequestOptions) => {
     const responseStream = stream(body, options);
     const finalResponse = responseStream.finalResponse.bind(responseStream);
@@ -162,6 +163,8 @@ export class BedrockOpenAI extends OpenAI {
       apiKey = readEnv('AWS_BEARER_TOKEN_BEDROCK') ?? null;
     }
 
+    // SAFETY: The widening keeps a runtime guard for JavaScript callers that supply an API-key function despite the declared string contract.
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Reject a JavaScript function supplied as a static Bedrock API key before it can become a credential.
     if (typeof (apiKey as unknown) === 'function') {
       throw new Errors.OpenAIError(
         'Pass refreshable Bedrock credentials via `bedrockTokenProvider`, not `apiKey`.',
@@ -281,8 +284,10 @@ export class BedrockOpenAI extends OpenAI {
     const bedrockTokenProvider =
       options.apiKey === undefined ? (options.bedrockTokenProvider ?? this.bedrockTokenProvider) : undefined;
 
+    // SAFETY: Bedrock options extend the base client options; forwarding them preserves the subclass's existing withOptions construction behavior.
     return super.withOptions({
       ...options,
+      // Spread creates an own data property without invoking inherited setters or changing the object prototype.
       ...(bedrockTokenProvider ? { apiKey: undefined, bedrockTokenProvider } : {}),
     } as Partial<ClientOptions>);
   }

package/src/beta/realtime/internal-base.ts

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

package/src/beta/realtime/websocket.ts

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

package/src/beta/realtime/ws.ts

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

package/src/client.ts

@@ -856,6 +856,10 @@ export class OpenAI {
     return Errors.APIError.generate(status, normalizedError, message, headers);
   }
 
+  _hasApiKeyProvider(): boolean {
+    return typeof this._options.apiKey === 'function';
+  }
+
   /**
    * 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
@@ -1108,6 +1112,8 @@ export class OpenAI {
           props.options,
           retriesRemaining,
           props.retryOfRequestLogID ?? props.requestLogID,
+          undefined,
+          props.requestSignal,
         );
         Object.assign(props, next);
       } finally {
@@ -1318,7 +1324,13 @@ export class OpenAI {
             message: x509Authentication ? 'X.509 workload identity API connection failed.' : response.message,
           }),
         );
-        return this.retryRequest(options, retriesRemaining, retryOfRequestLogID ?? requestLogID);
+        return this.retryRequest(
+          options,
+          retriesRemaining,
+          retryOfRequestLogID ?? requestLogID,
+          undefined,
+          req.signal,
+        );
       }
       const terminalMessage = hasStreamingBody
         ? 'error; streaming body cannot be retried'
@@ -1442,6 +1454,7 @@ export class OpenAI {
           retriesRemaining,
           retryOfRequestLogID ?? requestLogID,
           response.headers,
+          req.signal,
         );
       }
 
@@ -1497,7 +1510,15 @@ export class OpenAI {
       helperMethod: options.__metadata?.['helperMethod'],
       ...(continueRequest ? { continueRequest } : {}),
     });
-    return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
+    return {
+      response,
+      options,
+      controller,
+      requestSignal: req.signal,
+      requestLogID,
+      retryOfRequestLogID,
+      startTime,
+    };
   }
 
   getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
@@ -1638,6 +1659,7 @@ export class OpenAI {
     retriesRemaining: number,
     requestLogID: string,
     responseHeaders?: Headers | undefined,
+    requestSignal: AbortSignal | null | undefined = options.signal,
   ): Promise<APIResponseProps> {
     let timeoutMillis: number | undefined;
 
@@ -1685,7 +1707,17 @@ export class OpenAI {
     if (x509Authentication) {
       await x509Authentication.waitForRetry(timeoutMillis, x509Authentication.effectiveSignal());
     } else {
-      await sleep(timeoutMillis);
+      const retrySignals =
+        requestSignal === options.signal ? [requestSignal] : [requestSignal, options.signal];
+      try {
+        await sleep(timeoutMillis, ...retrySignals);
+      } catch (error) {
+        const abortedSignal = retrySignals.find((signal) => signal?.aborted);
+        if (abortedSignal) {
+          throw this._makeUserAbortError(abortedSignal);
+        }
+        throw error;
+      }
     }
 
     return this.makeRequest(options, retriesRemaining - 1, requestLogID);

package/src/core/EventEmitter.ts

@@ -54,12 +54,14 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       return this;
     }
 
+    // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
     const emittedRegistration = this.#emittedListenerRegistrations.get(listener as object);
     if (
       emittedRegistration?.event === event &&
       !emittedRegistration.registration.removed &&
       !emittedRegistration.registration.detached
     ) {
+      // SAFETY: The stored registration event was compared with this event above, preserving the event/listener type correlation.
       this.#removeEmittedListener(
         event,
         emittedRegistration.registration as EventListeners<EventTypes, Event>[number],
@@ -101,6 +103,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       registration?.listener === listener &&
       registration.once
     ) {
+      // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
       this.#emittedListenerRegistrations.set(listener as object, { event, registration });
     }
   }
@@ -114,6 +117,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
     }
 
     registration.removed = true;
+    // SAFETY: Listener functions are object identities used as WeakMap keys; registration and removal use the same function instance.
     this.#emittedListenerRegistrations.delete(registration.listener as object);
     this.#pendingListenerCleanup.add(event);
     if (this.#listenerDispatchDepth === 0) {
@@ -123,9 +127,11 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
 
   #cleanupEmittedListeners(): void {
     for (const event of this.#pendingListenerCleanup) {
+      // SAFETY: Pending cleanup keys are added only from registered EventTypes events; the key retains its event-map membership.
       const eventType = event as keyof EventTypes;
       const listeners = this.#listeners[eventType];
       if (listeners) {
+        // SAFETY: Filtering only removes registrations from the same event bucket and preserves the listener signatures for that event.
         this.#listeners[eventType] = listeners.filter((listener) => !listener.removed) as any;
       }
     }
@@ -150,21 +156,27 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   ): Promise<EmittedEventResult<EventParameters<EventTypes, Event>>> {
     return new Promise((resolve, reject) => {
       const listeners = {
+        // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Failures and rejection reasons can be arbitrary JavaScript values; preserve them until inspection or forwarding.
         onError: (error: unknown) => {
+          // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
           this.off(event, listeners.onEvent as any);
           reject(error);
         },
         onEvent: (...values: unknown[]) => {
           if (event !== 'error') {
+            // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
             this.off('error', listeners.onError as any);
           }
+          // SAFETY: The emitted API returns the sole argument or the full tuple according to its existing EventTypes-dependent result contract.
           resolve((values.length > 1 ? values : values[0]) as any);
         },
       };
 
       if (event !== 'error') {
+        // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
         this.#onceForEmitted('error', listeners.onError as any);
       }
+      // SAFETY: This callback is paired with the same event when registered and removed; its variadic body forwards the event tuple or captured error.
       this.#onceForEmitted(event, listeners.onEvent as any);
     });
   }
@@ -176,6 +188,7 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
   ) {
     const listeners: EventListeners<EventTypes, Event> | undefined = this.#listeners[event];
     if (listeners) {
+      // SAFETY: Filtering only removes registrations from the same event bucket and preserves the listener signatures for that event.
       this.#listeners[event] = listeners.filter((listener) => {
         if (listener.once) {
           listener.detached = true;
@@ -186,10 +199,12 @@ export class EventEmitter<EventTypes extends Record<string, (...args: any) => an
       let firstListenerError: unknown;
       this.#listenerDispatchDepth += 1;
       try {
+        // SAFETY: The listener bucket and argument tuple come from the same EventTypes key; this bridges TypeScript generic indexed-access correlation.
         for (const registration of listeners as any) {
           if (!registration.removed) {
             try {
               const { listener } = registration;
+              // SAFETY: The listener bucket and argument tuple come from the same EventTypes key; this bridges TypeScript generic indexed-access correlation.
               listener(...(args as any));
             } catch (error) {
               if (!listenerThrew) {

package/src/core/streaming.ts

@@ -139,7 +139,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
             let data;
 
             try {
-              data = JSON.parse(sse.data) as any;
+              data = JSON.parse(sse.data);
             } catch {
               logger.error(`Could not parse message into JSON:`);
               logger.error(`From chunk:`);
@@ -164,6 +164,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
               logger.error(`From chunk:`);
               throw new SyntaxError('Error reading response: malformed server-sent event JSON.');
             }
+            // SAFETY: Named SSE events use the public stream's event/data envelope; Item is the caller-selected API event contract.
             yield { event: sse.event, data } as any;
           }
         }
@@ -264,6 +265,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
           if (line) {
             let data: Item;
             try {
+              // SAFETY: Item is the caller's NDJSON response contract; JSON syntax is parsed here without a per-resource runtime schema.
               data = JSON.parse(line) as Item;
             } catch (error) {
               if (error instanceof SyntaxError) {
@@ -352,10 +354,13 @@ export class Stream<Item> implements AsyncIterable<Item> {
    * which can be turned back into a Stream with `Stream.fromReadableStream()`.
    * Canceling a response-backed readable aborts its request. Canceling a tee
    * branch discards its buffered events and leaves sibling consumers running.
+   * Read or serialization failures also release the iterator without replacing the original error.
    */
   toReadableStream(): ReadableStream {
     const { controller } = this;
     let iter: AsyncIterator<Item>;
+    let cancellation: Promise<void> | undefined;
+    const cancel = () => (cancellation ??= this.#cancelIterator(iter, controller));
 
     return makeReadableStream({
       start: async () => {
@@ -373,9 +378,12 @@ export class Stream<Item> implements AsyncIterable<Item> {
           ctrl.enqueue(bytes);
         } catch (err) {
           ctrl.error(err);
+          // An errored readable never invokes its cancel hook. Release the source ourselves,
+          // without letting failed or stalled cleanup replace the read/serialization error.
+          void cancel().catch(() => undefined);
         }
       },
-      cancel: () => this.#cancelIterator(iter, controller),
+      cancel,
     });
   }
 
@@ -385,6 +393,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       if (!this.#isTeeBranch) {
         controller.abort();
       }
+      // oxlint-disable-next-line anti-slop/no-reflect-apply -- Invoke the captured iterator method with its receiver even if a caller-supplied function shadows call.
       await Reflect.apply(returnMethod, iterator, []);
     }
   }
@@ -524,6 +533,7 @@ export async function* _iterSSEMessages(
 ): AsyncGenerator<ServerSentEvent, void, unknown> {
   if (!response.body) {
     controller.abort();
+    // SAFETY: navigator is optional across SDK runtimes; this compatibility branch checks its presence before identifying React Native.
     if (
       (globalThis as any).navigator !== undefined &&
       (globalThis as any).navigator.product === 'ReactNative'
@@ -569,6 +579,15 @@ export async function* _iterSSEMessages(
         yield sse;
       }
     }
+    // Servers sometimes omit the trailing blank line that normally
+    // terminates the last event. Flush any in-progress event exactly once.
+    if (signal.aborted) {
+      return;
+    }
+    const pending = sseDecoder.flush();
+    if (pending) {
+      yield pending;
+    }
   } catch (error) {
     failed = true;
     if (!signal.aborted || (!isAbortError(error) && error !== signal.reason)) {
@@ -699,6 +718,15 @@ class SSEDecoder {
 
     return null;
   }
+
+  /**
+   * Emits a pending event at EOF when the stream omitted the trailing blank
+   * line. Returns `null` when no event is in progress so a record that already
+   * ended with a blank line is not delivered twice.
+   */
+  flush(): ServerSentEvent | null {
+    return this.decode('');
+  }
 }
 
 function partition(str: string, delimiter: string): [string, string, string] {

package/src/helpers/audio.ts

@@ -47,11 +47,13 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
     try {
       let source: NodeJS.ReadableStream;
       if (isResponse(stream)) {
+        // SAFETY: Fetch implementations may expose a web or Node response body; the following pipe check selects the matching stream adapter.
         const body = stream.body as NodeReadableStream | NodeJS.ReadableStream | null;
         if (!body) {
           throw new Error('Cannot play audio from a response without a body');
         }
 
+        // SAFETY: The preceding branch handled Node pipe streams; the remaining response body follows the web ReadableStream contract consumed by fromWeb.
         source =
           'pipe' in body && typeof body.pipe === 'function'
             ? body