openai 7.16.0 → 7.18.0

package/src/internal/responses/response-accumulator.ts

@@ -128,6 +128,7 @@ type ResponseIgnoredEvent = Extract<
       | 'response.audio.done'
       | 'response.audio.transcript.delta'
       | 'response.audio.transcript.done'
+      | 'response.compaction.compacting'
       | 'response.image_generation_call.partial_image'
       | 'response.mcp_list_tools.in_progress'
       | 'response.mcp_list_tools.completed'
@@ -198,6 +199,7 @@ function hasRoutedOutputCallIdentity(
 }
 
 function getOutputItemIdentityKeys(output: Response['output'][number], eventType: string): string[] {
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate untrusted streamed item identifiers and discriminators before mutating the response snapshot.
   if (!hasOwn(output, 'type') || typeof output.type !== 'string') {
     throw new OpenAIError(`expected an own output item type for ${eventType}`);
   }
@@ -206,6 +208,7 @@ function getOutputItemIdentityKeys(output: Response['output'][number], eventType
   const identities: string[] = [];
 
   if (hasOwn(output, 'id')) {
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate untrusted streamed item identifiers and discriminators before mutating the response snapshot.
     if (typeof output.id !== 'string' || output.id.length === 0) {
       throw new OpenAIError(`expected a non-empty output item id for ${eventType}`);
     }
@@ -215,6 +218,7 @@ function getOutputItemIdentityKeys(output: Response['output'][number], eventType
   }
 
   if (hasRoutedOutputCallIdentity(output)) {
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate untrusted streamed item identifiers and discriminators before mutating the response snapshot.
     if (!hasOwn(output, 'call_id') || typeof output.call_id !== 'string' || output.call_id.length === 0) {
       throw new OpenAIError(`expected a non-empty output item call_id for ${eventType}`);
     }
@@ -328,6 +332,7 @@ const expectedOutputItemTypes = {
   'response.mcp_list_tools.in_progress': 'mcp_list_tools',
   'response.mcp_list_tools.completed': 'mcp_list_tools',
   'response.mcp_list_tools.failed': 'mcp_list_tools',
+  'response.compaction.compacting': 'compaction',
 } satisfies Record<
   Exclude<ResponseItemScopedEvent['type'], 'response.content_part.added' | 'response.content_part.done'>,
   Response['output'][number]['type']
@@ -400,7 +405,9 @@ function validateOutputItemIdentity(
     return;
   }
 
+  // SAFETY: The event type was classified as item-scoped; the following checks validate its own item_id before use.
   const itemEvent = event as ResponseItemScopedEvent;
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate untrusted streamed item identifiers and discriminators before mutating the response snapshot.
   if (!hasOwn(event, 'item_id') || typeof itemEvent.item_id !== 'string' || itemEvent.item_id.length === 0) {
     throw new OpenAIError(`expected a non-empty item_id for ${event.type}`);
   }
@@ -514,6 +521,7 @@ const supportedResponseEventTypes = createSupportedResponseEventTypes([
   'response.audio.done',
   'response.audio.transcript.delta',
   'response.audio.transcript.done',
+  'response.compaction.compacting',
   'response.image_generation_call.partial_image',
   'response.mcp_list_tools.in_progress',
   'response.mcp_list_tools.completed',
@@ -535,19 +543,37 @@ const responseEventRoutingFields = [
   'summary_index',
 ] as const;
 
-function sanitizeResponseEvent(event: ResponseAccumulatorEvent): ResponseAccumulatorEvent {
+// These fields are snapshotted before the event-specific validators inspect them.
+interface ResponseEventPayload {
+  item_id?: unknown;
+  output_index?: unknown;
+  content_index?: unknown;
+  annotation_index?: unknown;
+  command_index?: unknown;
+  summary_index?: unknown;
+  item?: unknown;
+  part?: unknown;
+}
+
+function sanitizeResponseEvent(
+  event: ResponseAccumulatorEvent & ResponseEventPayload,
+): ResponseAccumulatorEvent {
   let descriptor: PropertyDescriptor | undefined;
   try {
     descriptor = Object.getOwnPropertyDescriptor(event, 'type');
   } catch {
+    // SAFETY: assertNever always throws; the cast routes invalid runtime events through the existing unsupported-event error path.
     return assertNever(event as never);
   }
 
   const type: unknown = descriptor?.value;
+  // SAFETY: The string is used only as a Set lookup key; membership performs the supported-event check.
   if (
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate untrusted streamed item identifiers and discriminators before mutating the response snapshot.
     typeof type !== 'string' ||
     !supportedResponseEventTypes.has(type as ResponseAccumulatorEvent['type'])
   ) {
+    // SAFETY: assertNever always throws; the cast routes invalid runtime events through the existing unsupported-event error path.
     return assertNever(event as never);
   }
 
@@ -566,21 +592,23 @@ function sanitizeResponseEvent(event: ResponseAccumulatorEvent): ResponseAccumul
     try {
       for (const field of responseEventRoutingFields) {
         const routingDescriptor = Object.getOwnPropertyDescriptor(event, field);
-        stableValues.set(field, routingDescriptor ? Reflect.get(event, field, event) : undefined);
+        stableValues.set(field, routingDescriptor ? event[field] : undefined);
       }
 
       if (type === 'response.output_item.done') {
-        stableValues.set('item', structuredClone(Reflect.get(event, 'item', event)));
+        stableValues.set('item', structuredClone(event.item));
       } else if (type === 'response.content_part.added' || type === 'response.content_part.done') {
-        stableValues.set('part', structuredClone(Reflect.get(event, 'part', event)));
+        stableValues.set('part', structuredClone(event.part));
       }
     } catch {
+      // SAFETY: assertNever always throws; the cast routes invalid runtime events through the existing unsupported-event error path.
       return assertNever(event as never);
     }
   }
 
   return new Proxy(event, {
     get(target, property) {
+      // oxlint-disable-next-line anti-slop/no-reflect-get -- Proxy forwarding must preserve arbitrary keys with the original target as accessor receiver.
       return stableValues.has(property) ? stableValues.get(property) : Reflect.get(target, property, target);
     },
   });
@@ -772,6 +800,7 @@ function accumulateOutputTextEvent(
           throw new OpenAIError(`expected content to be 'output_text', got ${content.type}`);
         }
         validateArrayIndex(content.annotations, event.annotation_index, 'annotation', true);
+        // SAFETY: The output_text discriminator and annotation index were checked; the annotation is cloned from the corresponding API event contract.
         content.annotations[event.annotation_index] = structuredClone(
           event.annotation,
         ) as ResponseOutputText['annotations'][number];
@@ -1151,6 +1180,7 @@ function isIgnoredResponseEvent(event: ResponseAccumulatorEvent): event is Respo
     case 'response.audio.done':
     case 'response.audio.transcript.delta':
     case 'response.audio.transcript.done':
+    case 'response.compaction.compacting':
     case 'response.image_generation_call.partial_image':
     case 'response.mcp_list_tools.in_progress':
     case 'response.mcp_list_tools.completed':

package/src/internal/to-file.ts

@@ -186,7 +186,7 @@ async function getBytes(value: BlobLikePart | AsyncIterable<BlobLikePart>): Prom
     isAsyncIterable(value) // includes Readable, ReadableStream, etc.
   ) {
     for await (const chunk of value) {
-      parts.push(...(await getBytes(chunk as BlobLikePart)));
+      parts.push(...(await getBytes(chunk)));
     }
   } else {
     const constructor = value?.constructor?.name;

package/src/internal/uploads.ts

@@ -105,6 +105,7 @@ type NamedBlob = Blob & {
  */
 export const checkFileSupport = () => {
   if (typeof File === 'undefined') {
+    // SAFETY: This optional Node global is inspected only to improve the missing-File diagnostic in runtimes without process.
     const { process } = globalThis as any;
     const isOldNode =
       typeof process?.versions?.node === 'string' &&
@@ -148,6 +149,7 @@ export function makeFile(
   options?: FilePropertyBag,
 ): File {
   checkFileSupport();
+  // SAFETY: The SDK BlobPart union supports Node and web binary inputs; the native File constructor handles those parts across their differing ambient types.
   return new File(fileBits as any, fileName ?? 'unknown_file', options);
 }
 
@@ -268,6 +270,7 @@ const supportsFormDataMap = /* @__PURE__ */ new WeakMap<Fetch, Promise<boolean>>
  * confusing error messages later on.
  */
 function supportsFormData(fetchObject: OpenAI | Fetch): Promise<boolean> {
+  // SAFETY: The union has already excluded callable fetch values; the remaining OpenAI client owns the fetch implementation used by this probe.
   const fetch: Fetch = typeof fetchObject === 'function' ? fetchObject : (fetchObject as any).fetch;
   const cached = supportsFormDataMap.get(fetch);
   if (cached) {
@@ -277,10 +280,12 @@ function supportsFormData(fetchObject: OpenAI | Fetch): Promise<boolean> {
     try {
       let FetchResponse: typeof Response;
       if ('Response' in fetch) {
+        // SAFETY: Custom fetch implementations may expose their matching Response constructor; the enclosing probe catches incompatible constructors.
         FetchResponse = fetch.Response as typeof Response;
       } else {
         const response = await fetch('data:,');
         await response.arrayBuffer();
+        // SAFETY: The successful fetch response supplies the constructor used to test its own FormData support; failures remain inside the probe's catch.
         FetchResponse = response.constructor as typeof Response;
       }
       const data = new FormData();
@@ -351,6 +356,7 @@ const isUploadable = (value: unknown): value is Uploadable =>
     isStreamingFile(value) ||
     isBlob(value));
 
+// SAFETY: The enclosing object guard and own-key enumeration allow reading these property values without assigning them a trusted value type.
 const hasStreamingUploadableValue = (value: unknown): boolean => {
   if (isStreamingFile(value) || isAsyncIterable(value) || isReadableStream(value)) {
     return true;
@@ -369,6 +375,7 @@ const hasStreamingUploadableValue = (value: unknown): boolean => {
   return false;
 };
 
+// SAFETY: The enclosing object guard and own-key enumeration allow reading these property values without assigning them a trusted value type.
 const hasUploadableValue = (value: unknown): boolean => {
   if (isUploadable(value)) {
     return true;
@@ -496,6 +503,7 @@ function* iterateFormValue(key: string, value: unknown): Generator<FormEntry> {
 }
 
 function getStreamingFileName(value: Uploadable, options: CreateFormOptions): string {
+  // oxlint-disable-next-line anti-slop/no-known-value-widening -- The runtime guard validates JavaScript and custom upload values before trusting the StreamingFile brand.
   if (isStreamingFile(value)) {
     const { name } = value;
     if (typeof name !== 'string' || !name) {
@@ -513,6 +521,7 @@ function getStreamingFileName(value: Uploadable, options: CreateFormOptions): st
 function getStreamingFileType(value: Uploadable): string {
   let type: string | undefined;
 
+  // oxlint-disable-next-line anti-slop/no-known-value-widening -- Runtime upload-brand checks intentionally accept unknown inputs despite the static Uploadable annotation.
   if (isStreamingFile(value) || isBlob(value)) {
     ({ type } = value);
   } else if (value instanceof Response) {
@@ -537,7 +546,8 @@ function validateStreamingFileType(type: string): string {
   return type;
 }
 
-function getStreamingFileData(value: Uploadable): unknown {
+function getStreamingFileData(value: Uploadable): Exclude<Uploadable, StreamingFile> {
+  // oxlint-disable-next-line anti-slop/no-known-value-widening -- The runtime guard validates the streaming wrapper before accessing its potentially custom data.
   if (isStreamingFile(value)) {
     return value.data;
   }

package/src/internal/utils/abort.ts

@@ -4,16 +4,18 @@ interface WeakReference<T> {
 }
 type WeakAbortCallback = WeakReference<AbortCallback>;
 interface AbortFinalizer {
-  register: (target: AbortCallback, cleanup: AbortCallback, token: object) => void;
-  unregister: (token: object) => boolean;
+  register: (target: AbortCallback, cleanup: AbortCallback, token: WeakAbortCallback) => void;
+  unregister: (token: WeakAbortCallback) => boolean;
 }
 
 // Keep these optional runtime features out of the SDK's ES2020 type requirements.
+// SAFETY: These host features are optional and checked before use; the structural view avoids requiring newer ambient library declarations.
 const weakGlobals = globalThis as typeof globalThis & {
   WeakRef?: new <T extends object>(target: T) => WeakReference<T>;
   FinalizationRegistry?: new (cleanup: (value: AbortCallback) => void) => AbortFinalizer;
 };
 const finalizer =
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Weak references and finalizers are optional host capabilities, so probe them before constructing either.
   typeof weakGlobals.FinalizationRegistry === 'function'
     ? new weakGlobals.FinalizationRegistry((cleanup) => {
         try {
@@ -68,10 +70,12 @@ function releaseOnAbort(
 
 /** Keep cancellation alive until abort or collection of the response body or bodyless custom response. */
 export function retainRequestAbortCallback(
+  // oxlint-disable-next-line anti-slop/no-object-parameters -- Abort callbacks are retained by any response-body or custom-response owner identity.
   owner: object,
   abort: AbortCallback,
   requestSignal: AbortSignal,
 ): void {
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Weak references and finalizers are optional host capabilities, so probe them before constructing either.
   if (typeof weakGlobals.WeakRef === 'function' && finalizer && !requestSignal.aborted) {
     let callbacks = callbackOwners.get(owner);
     if (!callbacks) {
@@ -99,6 +103,7 @@ export function addRequestAbortListener(
       // No listener was installed for an already aborted signal.
     };
   }
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Weak references and finalizers are optional host capabilities, so probe them before constructing either.
   if (typeof weakGlobals.WeakRef !== 'function' || !finalizer) {
     signal.addEventListener('abort', abort, { once: true });
     return () => signal.removeEventListener('abort', abort);

package/src/internal/utils/bytes.ts

@@ -19,6 +19,7 @@ let encodeUTF8_: (str: string) => Uint8Array;
 /** Encodes text as UTF-8 bytes, reusing the platform encoder after its first call. */
 export function encodeUTF8(str: string) {
   let encoder;
+  // SAFETY: Supported runtimes provide the standard TextEncoder/TextDecoder globals; the cast keeps their ambient DOM declarations optional.
   return (
     encodeUTF8_ ??
     ((encoder = new (globalThis as any).TextEncoder()), (encodeUTF8_ = encoder.encode.bind(encoder)))
@@ -30,6 +31,7 @@ let decodeUTF8_: (bytes: Uint8Array) => string;
 /** Decodes UTF-8 bytes as text, reusing the platform decoder after its first call. */
 export function decodeUTF8(bytes: Uint8Array) {
   let decoder;
+  // SAFETY: Supported runtimes provide the standard TextEncoder/TextDecoder globals; the cast keeps their ambient DOM declarations optional.
   return (
     decodeUTF8_ ??
     ((decoder = new (globalThis as any).TextDecoder()), (decodeUTF8_ = decoder.decode.bind(decoder)))

package/src/internal/utils/path.ts

@@ -24,6 +24,7 @@ const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null))
  * `encodeURIComponent`. Nullish values, ordinary objects, and literal or
  * percent-encoded `.`/`..` path segments are rejected with an SDK error.
  */
+// SAFETY: This branch compares prototype methods to recognize cross-realm plain values; it does not call the optional hasOwnProperty member.
 export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
   function path(statics: readonly string[], ...params: readonly unknown[]): string {
     // If there are no params, no processing is needed.
@@ -45,6 +46,7 @@ export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
         if (
           index !== params.length &&
           (value == null ||
+            // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Path parameters may arrive from JavaScript callers and require runtime validation before URL encoding.
             (typeof value === 'object' &&
               // handle values from other realms
               value.toString ===

package/src/internal/utils/sleep.ts

@@ -1 +1,52 @@
-export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+export const sleep = (ms: number, ...signals: (AbortSignal | null | undefined)[]): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const activeSignals = [...new Set(signals.filter((signal): signal is AbortSignal => signal != null))];
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let settled = false;
+    const cleanup = () => {
+      for (const signal of activeSignals) {
+        try {
+          signal.removeEventListener('abort', abort);
+        } catch {
+          // Structural signal cleanup must not prevent the promise from settling.
+        }
+      }
+    };
+    const settle = (callback: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timeout !== undefined) {
+        clearTimeout(timeout);
+        timeout = undefined;
+      }
+      cleanup();
+      callback();
+    };
+    const abort = () => {
+      settle(() => reject());
+    };
+
+    if (activeSignals.some((signal) => signal.aborted)) {
+      abort();
+      return;
+    }
+
+    timeout = setTimeout(() => {
+      settle(resolve);
+    }, ms);
+    for (const signal of activeSignals) {
+      if (settled) {
+        break;
+      }
+      try {
+        signal.addEventListener('abort', abort, { once: true });
+      } catch (error) {
+        settle(() => reject(error));
+      }
+    }
+    if (activeSignals.some((signal) => signal.aborted)) {
+      abort();
+    }
+  });

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

@@ -166,6 +166,7 @@ export class BrowserWebSocket implements WebSocketLike {
           const message = ev?.message || ev?.error?.message || 'WebSocket error';
           const err = new Error(message);
           if (ev?.error) {
+            // SAFETY: The locally created Error receives the browser error event's cause; the cast avoids requiring newer Error ambient declarations.
             (err as any).cause = ev.error;
           }
           listener(err);
@@ -173,6 +174,7 @@ export class BrowserWebSocket implements WebSocketLike {
       }
 
       default: {
+        // SAFETY: Non-special events use the native DOM handler contract directly; the adapter only wraps message, close, and error variants above.
         return listener as DOMEventHandler;
       }
     }

package/src/internal/ws.ts

@@ -1,5 +1,18 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
 import { OpenAIError } from '../core/error';
+import type { WebSocketLike } from './ws-adapter';
+
+const webSocketErrors = new WeakMap<WebSocketLike, Error>();
+
+/** Records physical failure before transport callbacks notify public observers. @internal */
+export function recordWebSocketError(socket: WebSocketLike, error: Error): void {
+  webSocketErrors.set(socket, error);
+}
+
+/** Returns physical failure for this socket instance, never for a replacement. @internal */
+export function getWebSocketError(socket: WebSocketLike): Error | undefined {
+  return webSocketErrors.get(socket);
+}
 
 /** Options for an independently buffered WebSocket stream iterator. */
 export interface WebSocketStreamOptions {
@@ -86,14 +99,59 @@ const REDIRECT_SAFE_WEBSOCKET_HEADERS = new Set([
   'x-trace-id',
 ]);
 
+function isWebSocketCredentialHeader(name: string): boolean {
+  return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(name.toLowerCase().split('_').join('-'));
+}
+
+/**
+ * Snapshots credential values in final socket options before validation and dispatch.
+ * Reports potential caller authentication, including custom headers; the server
+ * remains responsible for validating credentials. Noncredential headers are left intact.
+ */
+export function snapshotWebSocketCredentials(options: {
+  auth?: unknown;
+  headers?: Record<string, unknown> | undefined;
+}): boolean {
+  if (options.auth !== null && options.auth !== undefined) {
+    options.auth = String(options.auth);
+  }
+  const credentials = new Map<string, boolean>();
+  const headers = options.headers ?? {};
+  for (const [name, value] of Object.entries(headers)) {
+    const normalizedName = name.toLowerCase().split('_').join('-');
+    // Routing metadata is still protected on redirects, but cannot authenticate a socket.
+    if (
+      !isWebSocketCredentialHeader(name) ||
+      normalizedName === 'openai-organization' ||
+      normalizedName === 'openai-project'
+    ) {
+      continue;
+    }
+    let snapshot = value;
+    if (Array.isArray(value)) {
+      snapshot = value.map(String);
+    } else if (value !== null && value !== undefined) {
+      snapshot = String(value);
+    }
+    headers[name] = snapshot;
+    const values = Array.isArray(snapshot) ? snapshot : [snapshot];
+    credentials.set(
+      name.toLowerCase(),
+      values.some((item) => typeof item === 'string' && item.trim().length > 0),
+    );
+  }
+  // Node applies header names case-insensitively, and Authorization overrides Basic auth.
+  return (
+    [...credentials.values()].some(Boolean) ||
+    (!credentials.has('authorization') && typeof options.auth === 'string' && options.auth.trim().length > 0)
+  );
+}
+
 /** Prevents WebSocket redirects from forwarding caller or SDK credentials to another origin. */
 export function protectWebSocketOptionsFromCredentialRedirects<Options extends CredentialedWebSocketOptions>(
   options: Options,
 ): Options {
-  const hasSensitiveHeader = Object.keys(options.headers ?? {}).some((name) => {
-    const normalized = name.toLowerCase().split('_').join('-');
-    return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(normalized);
-  });
+  const hasSensitiveHeader = Object.keys(options.headers ?? {}).some(isWebSocketCredentialHeader);
 
   if (!options.auth && !hasSensitiveHeader) {
     return options;
@@ -157,9 +215,24 @@ function snapshotRawData(data: RawWebSocketData): Exclude<RawWebSocketData, Arra
   return data.slice(0);
 }
 
-function rawByteLength(data: RawWebSocketData): number {
+/** Counts wire bytes without allocating another payload-sized buffer. */
+export function rawByteLength(data: RawWebSocketData): number {
   if (typeof data === 'string') {
-    return encodeUTF8(data).byteLength;
+    let bytes = 0;
+    for (let index = 0; index < data.length; index += 1) {
+      const code = data.codePointAt(index)!;
+      if (code < 128) {
+        bytes += 1;
+      } else if (code < 2048) {
+        bytes += 2;
+      } else if (code <= 65_535) {
+        bytes += 3;
+      } else {
+        bytes += 4;
+        index += 1;
+      }
+    }
+    return bytes;
   }
   if (Array.isArray(data)) {
     return data.reduce((sum, buf) => sum + buf.byteLength, 0);
@@ -252,6 +325,7 @@ export class SendQueue<T = unknown> {
       if (entry.kind === 'raw') {
         return { type: 'raw', data: entry.data };
       }
+      // SAFETY: T is the transport caller's event contract; JSON syntax is parsed here without imposing a runtime schema on forward-compatible events.
       return { type: 'message', message: JSON.parse(entry.data) as T };
     });
     this._queue = [];

package/src/lib/AbstractChatCompletionRunner.ts

@@ -1,4 +1,4 @@
-import { APIUserAbortError, OpenAIError } from '../error';
+import { OpenAIError } from '../error';
 import type OpenAI from '../index';
 import type { RequestOptions } from '../internal/request-options';
 import { uuid4 } from '../internal/utils/uuid';
@@ -142,6 +142,7 @@ export class AbstractChatCompletionRunner<
     this._emit('chatCompletion', chatCompletion);
     const message = chatCompletion.choices[0]?.message;
     if (message) {
+      // SAFETY: An API assistant message is also accepted as a subsequent conversation message; this preserves that existing input/output bridge.
       this._addMessage(message as ChatCompletionMessageParam);
     }
     return chatCompletion;
@@ -163,6 +164,7 @@ export class AbstractChatCompletionRunner<
       this._emit('message', message);
       if (isToolMessage(message) && message.content) {
         // Note, this assumes that {role: 'tool', content: …} is always the result of a call of tool of type=function.
+        // SAFETY: The legacy function-tool result event assumes textual tool output, as documented by the adjacent compatibility comment.
         this._emit('functionToolCallResult', message.content as string);
       } else if (isAssistantMessage(message) && message.tool_calls) {
         for (const tool_call of message.tool_calls) {
@@ -206,6 +208,7 @@ export class AbstractChatCompletionRunner<
       const message = this.messages[i];
       if (isAssistantMessage(message)) {
         // Audio is intentionally omitted from the final message snapshot.
+        // SAFETY: The assistant-message branch normalizes missing content and refusal to null when constructing the completed message.
         const ret: Omit<ChatCompletionMessage, 'audio'> = {
           ...message,
           content: (message as ChatCompletionMessage).content ?? null,
@@ -257,6 +260,7 @@ export class AbstractChatCompletionRunner<
       if (
         isToolMessage(message) &&
         message.content != null &&
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Chat history and tool-choice inputs can contain runtime variants that select different runner behavior.
         typeof message.content === 'string' &&
         this.messages.some(
           (x) =>
@@ -340,13 +344,7 @@ export class AbstractChatCompletionRunner<
 
   #throwIfAborted() {
     if (this.controller.signal.aborted) {
-      const error = new APIUserAbortError();
-      Object.defineProperty(error, 'cause', {
-        value: this.controller.signal.reason,
-        writable: true,
-        configurable: true,
-      });
-      throw error;
+      throw this._userAbortError();
     }
   }
 
@@ -397,8 +395,10 @@ export class AbstractChatCompletionRunner<
   ) {
     const role = 'tool' as const;
     const { tool_choice = 'auto', stream, toolContext: inputToolContext, ...restParams } = params;
+    // SAFETY: The generic runner parameters tie toolContext to ToolContext; undefined remains valid when the caller omits it under that contract.
     const toolContext = inputToolContext as ToolContext;
     const singleFunctionToCall =
+      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Chat history and tool-choice inputs can contain runtime variants that select different runner behavior.
       typeof tool_choice !== 'string' && tool_choice.type === 'function' && tool_choice?.function?.name;
     const { maxChatCompletions = DEFAULT_MAX_CHAT_COMPLETIONS, afterCompletion } = options || {};
     const runAfterCompletion = async (completion: ChatCompletion) => {
@@ -417,6 +417,7 @@ export class AbstractChatCompletionRunner<
           throw new OpenAIError('Tool given to `.runTools()` that does not have an associated function');
         }
 
+        // SAFETY: The auto-parseable tool supplies its own validated parameter schema and parser; this bridges the legacy runnable-tool parameter type.
         return {
           type: 'function',
           function: {
@@ -430,7 +431,8 @@ export class AbstractChatCompletionRunner<
         };
       }
 
-      return tool as any as RunnableToolFunction<any>;
+      // SAFETY: Unbranded tools follow the existing runnable-tool contract; the function-tool branch below performs its normal dispatch.
+      return tool as RunnableToolFunction<any>;
     });
 
     const functionsByName: Record<string, RunnableFunction<any, ToolContext>> = Object.create(null);
@@ -440,6 +442,9 @@ export class AbstractChatCompletionRunner<
       }
     }
 
+    // SAFETY: The runnable function's parameter schema is forwarded as JSON keyword properties without changing or inspecting its values.
+    // SAFETY: This is the intentional non-function tool pass-through; the runnable and wire types differ in index signatures, not the forwarded value.
+    // SAFETY: Omitting the tools list preserves the optional wire field; the existing conditional result type is broader than the runnable helper's declaration.
     const tools: ChatCompletionTool[] =
       'tools' in params
         ? inputTools.map((t) =>
@@ -448,12 +453,14 @@ export class AbstractChatCompletionRunner<
                   type: 'function',
                   function: {
                     name: t.function.name || t.function.function.name,
+                    // oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- Tool parameter schemas use the published open JSON Schema dictionary contract, including arbitrary extensions.
                     parameters: t.function.parameters as Record<string, unknown>,
                     description: t.function.description,
                     strict: t.function.strict,
                   },
                 }
-              : (t as unknown as ChatCompletionTool),
+              : // oxlint-disable-next-line anti-slop/no-chained-type-assertions -- Preserve the existing non-function tool pass-through; runnable and wire schema interfaces have incompatible index signatures.
+                (t as unknown as ChatCompletionTool),
           )
         : (undefined as any);
 
@@ -504,20 +511,34 @@ export class AbstractChatCompletionRunner<
           parsed = await fn.parse(args);
         } catch (error) {
           if (this.controller.signal.aborted) {
-            throw new APIUserAbortError();
+            throw this._userAbortError();
           }
           const content = error instanceof Error ? error.message : String(error);
           return { message: { role, tool_call_id, content }, functionCalled: false };
         }
         if (this.controller.signal.aborted) {
-          throw new APIUserAbortError();
+          throw this._userAbortError();
+        }
+        try {
+          rawContent = await fn.function(parsed, runner, toolContext);
+        } catch (error) {
+          if (this.controller.signal.aborted && Object.is(error, this.controller.signal.reason)) {
+            throw this._userAbortError();
+          }
+          throw error;
         }
-        rawContent = await fn.function(parsed, runner, toolContext);
       } else {
         if (this.controller.signal.aborted && !bufferedToolCall) {
-          throw new APIUserAbortError();
+          throw this._userAbortError();
+        }
+        try {
+          rawContent = await fn.function(args, runner, toolContext);
+        } catch (error) {
+          if (this.controller.signal.aborted && Object.is(error, this.controller.signal.reason)) {
+            throw this._userAbortError();
+          }
+          throw error;
         }
-        rawContent = await fn.function(args, runner, toolContext);
       }
 
       const content = AbstractChatCompletionRunner.#stringifyFunctionCallResult(rawContent);
@@ -555,7 +576,7 @@ export class AbstractChatCompletionRunner<
             this._addMessage(result.message);
           }
           if (this.controller.signal.aborted) {
-            throw new APIUserAbortError();
+            throw this._userAbortError();
           }
 
           if (singleFunctionToCall && result.functionCalled) {
@@ -584,7 +605,7 @@ export class AbstractChatCompletionRunner<
           }
         }
         if (this.controller.signal.aborted) {
-          throw new APIUserAbortError();
+          throw this._userAbortError();
         }
       }
 
@@ -592,7 +613,9 @@ export class AbstractChatCompletionRunner<
     }
   }
 
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Public tool callbacks can return any JavaScript value; this boundary normalizes their results for the API.
   static #stringifyFunctionCallResult(rawContent: unknown): string {
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Chat history and tool-choice inputs can contain runtime variants that select different runner behavior.
     if (typeof rawContent === 'string') {
       return rawContent;
     }