openai 7.15.0 → 7.17.0

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,4 +1,26 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
+import { OpenAIError } from '../core/error';
+
+/** Options for an independently buffered WebSocket stream iterator. */
+export interface WebSocketStreamOptions {
+  /**
+   * Maximum queued records, including raw data, errors and lifecycle events.
+   * Must be a positive safe integer. Omitted means unlimited. Overflow discards
+   * this iterator's backlog and rejects its next() calls with a WebSocketError,
+   * without closing the shared socket or affecting other iterators.
+   * This bounds event count, not payload bytes or total memory.
+   */
+  maxBufferedEvents?: number | undefined;
+}
+
+/** Snapshots and validates the iterator's limit before listeners are attached. */
+export function getMaxBufferedEvents(options?: WebSocketStreamOptions): number | undefined {
+  const limit = options?.maxBufferedEvents;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+    throw new OpenAIError('maxBufferedEvents must be a positive safe integer');
+  }
+  return limit;
+}
 
 /** Reconnection event passed to the `onReconnecting` handler and event listeners. */
 export interface ReconnectingEvent<Parameters = Record<string, unknown>> {
@@ -64,14 +86,53 @@ 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)) {
+    if (!isWebSocketCredentialHeader(name)) {
+      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;
@@ -230,6 +291,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;
     }

package/src/lib/AssistantStream.ts

@@ -20,7 +20,7 @@ import type {
 } from '../resources/beta/threads/runs/runs';
 import type { ReadableStream } from '../internal/shim-types';
 import { Stream } from '../streaming';
-import { APIError, APIUserAbortError, OpenAIError } from '../error';
+import { APIError, OpenAIError } from '../error';
 import type {
   AssistantStreamEvent,
   MessageStreamEvent,
@@ -99,14 +99,13 @@ export type RunSubmitToolOutputsParamsStream = Omit<RunSubmitToolOutputsParamsBa
   stream?: true;
 };
 
-function stabilizeAssistantStreamEvent(event: AssistantStreamEvent): {
-  event: AssistantStreamEvent;
-  exposedEvent: AssistantStreamEvent;
-} {
+function stabilizeAssistantStreamEvent(event: AssistantStreamEvent) {
   const eventDescriptor = Object.getOwnPropertyDescriptor(event, 'event');
   const dataDescriptor = Object.getOwnPropertyDescriptor(event, 'data');
-  const eventType = Reflect.get(event, 'event', event) as AssistantStreamEvent['event'];
-  const data = Reflect.get(event, 'data', event) as AssistantStreamEvent['data'];
+  // oxlint-disable-next-line anti-slop/no-reflect-get -- Reflective wire reads reject primitive frames and preserve the original event receiver.
+  const eventType: AssistantStreamEvent['event'] = Reflect.get(event, 'event', event);
+  // oxlint-disable-next-line anti-slop/no-reflect-get -- Keep the paired wire-data read on the original receiver after reading the event discriminator.
+  const data: AssistantStreamEvent['data'] = Reflect.get(event, 'data', event);
   let stableData = data;
   if (
     eventType === 'thread.message.created' ||
@@ -123,15 +122,24 @@ function stabilizeAssistantStreamEvent(event: AssistantStreamEvent): {
     eventType === 'thread.run.step.expired'
   ) {
     const messageID = Object.getOwnPropertyDescriptor(data, 'id');
-    if (messageID && 'value' in messageID && Reflect.get(data, 'id', data) !== messageID.value) {
+    if (
+      messageID &&
+      'value' in messageID &&
+      // SAFETY: The own id descriptor was found above; keep its live read unknown while comparing it with the captured descriptor value.
+      (data as { id: unknown }).id !== messageID.value
+    ) {
+      // SAFETY: Descriptor values are untyped; retaining this value as unknown avoids trusting a mutable message identifier.
       const canonicalID = messageID.value as unknown;
+      // SAFETY: The proxy retains the event data and substitutes only its captured own id; all other properties forward to the original receiver.
       stableData = new Proxy(data, {
         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 property === 'id' ? canonicalID : Reflect.get(target, property, target);
         },
       }) as AssistantStreamEvent['data'];
     }
   }
+  // SAFETY: The captured event discriminator and data originate from the same event; TypeScript loses their correlation when constructing the stabilized copy.
   const stableEvent = Object.freeze({ event: eventType, data: stableData }) as AssistantStreamEvent;
   const ordinaryEvent =
     eventDescriptor !== undefined &&
@@ -142,6 +150,7 @@ function stabilizeAssistantStreamEvent(event: AssistantStreamEvent): {
     dataDescriptor.value === data &&
     stableData === data;
 
+  // SAFETY: The captured event discriminator and data originate from the same event; TypeScript loses their correlation when constructing the stabilized copy.
   return {
     event: stableEvent,
     exposedEvent: ordinaryEvent ? event : ({ event: eventType, data: stableData } as AssistantStreamEvent),
@@ -204,7 +213,7 @@ export class AssistantStream
       this.#addEvent(event);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
     return this._addRun(this.#endRequest());
   }
@@ -252,7 +261,7 @@ export class AssistantStream
       this.#addEvent(event);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
 
     return this._addRun(this.#endRequest());
@@ -358,7 +367,7 @@ export class AssistantStream
       this.#addEvent(event);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
 
     return this._addRun(this.#endRequest());
@@ -381,7 +390,7 @@ export class AssistantStream
       this.#addEvent(event);
     }
     if (stream.controller.signal?.aborted) {
-      throw new APIUserAbortError();
+      throw this._userAbortError();
     }
 
     return this._addRun(this.#endRequest());
@@ -777,6 +786,7 @@ export class AssistantStream
         ) {
           for (const toolCall of delta.step_details.tool_calls) {
             if (toolCall.index === this.#currentToolCallIndex) {
+              // SAFETY: The indexed tool call comes from this run-step snapshot after applying the delta for the same tool-call index.
               this.#emitExposed(
                 'toolCallDelta',
                 toolCall,
@@ -807,7 +817,7 @@ export class AssistantStream
         this.#activeRunStepID = undefined;
         const details = event.data.step_details;
         if (details.type === 'tool_calls' && this.#currentToolCall) {
-          this.#emitExposed('toolCallDone', this.#currentToolCall as ToolCall);
+          this.#emitExposed('toolCallDone', this.#currentToolCall);
         }
         this.#emitExposed('runStepDone', event.data, accumulatedRunStep);
         this.#currentToolCallIndex = undefined;
@@ -844,6 +854,7 @@ export class AssistantStream
       }
 
       case 'thread.run.step.delta': {
+        // SAFETY: Run-step snapshots are stored by their canonical run-step id; the delta path checks that the snapshot exists before updating it.
         const snapshot = this.#runStepSnapshots[runStepID] as Runs.RunStep;
         if (!snapshot) {
           throw new Error('Received a RunStepDelta before creation of a snapshot');
@@ -856,10 +867,11 @@ export class AssistantStream
           if (hasOwn(delta, 'id')) {
             throw new OpenAIError('Run-step deltas must not contain an id field');
           }
-          const accumulated = accumulateAssistantStreamDelta(snapshot, delta, true) as Runs.RunStep;
+          const accumulated = accumulateAssistantStreamDelta(snapshot, delta, true);
           this.#runStepSnapshots[runStepID] = accumulated;
         }
 
+        // SAFETY: Run-step snapshots are stored by their canonical run-step id; the delta path checks that the snapshot exists before updating it.
         return this.#runStepSnapshots[runStepID] as Runs.RunStep;
       }
 
@@ -874,7 +886,7 @@ export class AssistantStream
     }
 
     if (this.#runStepSnapshots[runStepID]) {
-      return this.#runStepSnapshots[runStepID] as Runs.RunStep;
+      return this.#runStepSnapshots[runStepID];
     }
     throw new Error('No snapshot available');
   }
@@ -951,11 +963,10 @@ export class AssistantStream
     currentContent: MessageContent | undefined,
     cacheArrays: boolean,
   ): TextContentBlock | ImageFileContentBlock {
-    return accumulateAssistantStreamDelta(
-      currentContent as unknown as Record<any, any>,
-      contentElement,
-      cacheArrays,
-    ) as TextContentBlock | ImageFileContentBlock;
+    // SAFETY: The accumulator merges the matching message-content delta into its existing block; the public return remains the text/image block union.
+    return accumulateAssistantStreamDelta(currentContent as Record<any, any>, contentElement, cacheArrays) as
+      | TextContentBlock
+      | ImageFileContentBlock;
   }
 
   /**

package/src/lib/ChatCompletionRunner.ts

@@ -100,6 +100,7 @@ export class ChatCompletionRunner<ParsedT = null> extends AbstractChatCompletion
   ) {
     super._addMessage(message, emit, normalizeContent);
     if (emit && isAssistantMessage(message) && message.content) {
+      // SAFETY: The runner's content event preserves the existing string-content contract for assistant messages supplied by the API or caller.
       this._emit('content', message.content as string);
     }
   }