openai 7.4.0 → 7.6.0

package/internal/ws.mjs

@@ -1,7 +1,38 @@
 import { concatBytes, encodeUTF8 } from "./utils/bytes.mjs";
+const REDIRECT_SAFE_WEBSOCKET_HEADERS = new Set([
+    'connection',
+    'host',
+    'openai-beta',
+    'origin',
+    'sec-websocket-extensions',
+    'sec-websocket-key',
+    'sec-websocket-version',
+    'upgrade',
+    'user-agent',
+    'x-access-level',
+    'x-auth-metadata',
+    'x-auth-tokenization',
+    'x-authentication-metadata',
+    'x-authentication-tokenization',
+    'x-security-policy',
+    'x-token-budget',
+    'x-trace-id',
+]);
+/** Prevents WebSocket redirects from forwarding caller or SDK credentials to another origin. */
+export function protectWebSocketOptionsFromCredentialRedirects(options) {
+    const hasSensitiveHeader = Object.keys(options.headers ?? {}).some((name) => {
+        const normalized = name.toLowerCase().split('_').join('-');
+        return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(normalized);
+    });
+    if (!options.auth && !hasSensitiveHeader) {
+        return options;
+    }
+    return { ...options, followRedirects: false };
+}
 function toUint8Array(view) {
-    if (view instanceof Uint8Array)
+    if (view instanceof Uint8Array) {
         return view;
+    }
     return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
 }
 /**
@@ -9,46 +40,58 @@ function toUint8Array(view) {
  * `ws.send()` transmits the correct bytes.
  */
 export function flattenRawData(data) {
-    if (Array.isArray(data))
+    if (Array.isArray(data)) {
         return concatBytes(data.map(toUint8Array));
+    }
     return data;
 }
 function snapshotRawData(data) {
-    if (typeof data === 'string')
+    if (typeof data === 'string') {
         return data;
-    if (Array.isArray(data))
+    }
+    if (Array.isArray(data)) {
         return concatBytes(data.map(toUint8Array));
+    }
     if (ArrayBuffer.isView(data)) {
         const copy = new Uint8Array(data.byteLength);
         copy.set(toUint8Array(data));
         return copy;
     }
+    // oxlint-disable-next-line unicorn/prefer-spread -- ArrayBufferLike.slice copies bytes while spread changes the return type.
     return data.slice(0);
 }
 function rawByteLength(data) {
-    if (typeof data === 'string')
+    if (typeof data === 'string') {
         return encodeUTF8(data).byteLength;
-    if (Array.isArray(data))
+    }
+    if (Array.isArray(data)) {
         return data.reduce((sum, buf) => sum + buf.byteLength, 0);
-    if ('byteLength' in data)
+    }
+    if ('byteLength' in data) {
         return data.byteLength;
+    }
     return 0;
 }
 /**
- * A bounded queue for outgoing WebSocket messages. JSON messages are
- * serialized on enqueue; raw messages are stored as-is. The queue enforces
- * a configurable byte-size limit and can return the original messages via
- * {@link drain} when the connection permanently closes.
+ * Buffers outgoing WebSocket messages while a connection is unavailable.
+ *
+ * JSON values are serialized immediately, and raw binary payloads are copied,
+ * so later caller mutations cannot change queued messages. A single oversized
+ * message is accepted when the queue is empty; further messages are rejected
+ * whenever they would exceed the configured byte budget.
  */
 export class SendQueue {
+    /** Creates a queue with a one-mebibyte default byte budget. */
     constructor(maxBytes = 1048576) {
         this._queue = [];
         this._bytes = 0;
         this._maxBytes = maxBytes;
     }
     /**
-     * Serialize and enqueue a JSON message. Returns `true` if the message was
-     * accepted, `false` if it would exceed the byte-size limit.
+     * Serializes and snapshots a JSON message before queueing it.
+     *
+     * @returns `true` when accepted, including an oversized first message; `false`
+     * when adding it to a nonempty queue would exceed the byte budget.
      */
     enqueue(event) {
         const data = JSON.stringify(event);
@@ -61,8 +104,11 @@ export class SendQueue {
         return true;
     }
     /**
-     * Enqueue raw data without serialization. Returns `true` if the data was
-     * accepted, `false` if it would exceed the byte-size limit.
+     * Queues a raw string or a defensive copy of a binary WebSocket payload.
+     * Fragmented typed-array payloads are flattened before storage.
+     *
+     * @returns `true` when accepted, including an oversized first frame; `false`
+     * when adding it to a nonempty queue would exceed the byte budget.
      */
     enqueueRaw(data) {
         const snapshot = snapshotRawData(data);
@@ -88,7 +134,7 @@ export class SendQueue {
             }
             catch (err) {
                 const remaining = pending.slice(i);
-                this._queue = remaining.concat(this._queue);
+                this._queue = [...remaining, ...this._queue];
                 this._bytes = this._queue.reduce((sum, item) => sum + item.byteLength, 0);
                 throw err;
             }
@@ -100,8 +146,9 @@ export class SendQueue {
      */
     drain() {
         const unsent = this._queue.map((entry) => {
-            if (entry.kind === 'raw')
+            if (entry.kind === 'raw') {
                 return { type: 'raw', data: entry.data };
+            }
             return { type: 'message', message: JSON.parse(entry.data) };
         });
         this._queue = [];
@@ -109,39 +156,60 @@ export class SendQueue {
         return unsent;
     }
 }
-// RFC 6455 §7.4.1
+/**
+ * Reports whether an RFC 6455 close code represents a recoverable interruption.
+ *
+ * Network failures, service restarts, temporary server errors, and TLS
+ * handshake failures can be retried; normal closure, protocol violations,
+ * invalid payloads, and unrecognized codes cannot.
+ */
 export function isRecoverableClose(code) {
     switch (code) {
-        case 1000:
-            return false; // Normal closure
-        case 1001:
-            return true; // Going away (server shutting down)
-        case 1002:
-            return false; // Protocol error
-        case 1003:
-            return false; // Unsupported data
-        case 1005:
-            return true; // No status code (abnormal)
-        case 1006:
-            return true; // Abnormal closure (network drop)
-        case 1007:
-            return false; // Invalid payload
-        case 1008:
-            return false; // Policy violation
-        case 1009:
-            return false; // Message too big
-        case 1010:
-            return false; // Missing extension
-        case 1011:
-            return true; // Internal server error
-        case 1012:
-            return true; // Service restart
-        case 1013:
-            return true; // Try again later
-        case 1015:
-            return true; // TLS handshake failure
-        default:
+        case 1000: {
+            return false;
+        } // Normal closure
+        case 1001: {
+            return true;
+        } // Going away (server shutting down)
+        case 1002: {
+            return false;
+        } // Protocol error
+        case 1003: {
+            return false;
+        } // Unsupported data
+        case 1005: {
+            return true;
+        } // No status code (abnormal)
+        case 1006: {
+            return true;
+        } // Abnormal closure (network drop)
+        case 1007: {
             return false;
+        } // Invalid payload
+        case 1008: {
+            return false;
+        } // Policy violation
+        case 1009: {
+            return false;
+        } // Message too big
+        case 1010: {
+            return false;
+        } // Missing extension
+        case 1011: {
+            return true;
+        } // Internal server error
+        case 1012: {
+            return true;
+        } // Service restart
+        case 1013: {
+            return true;
+        } // Try again later
+        case 1015: {
+            return true;
+        } // TLS handshake failure
+        default: {
+            return false;
+        }
     }
 }
 //# sourceMappingURL=ws.mjs.map

package/internal/ws.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ws.mjs","sourceRoot":"","sources":["../src/internal/ws.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws.mjs","sourceRoot":"","sources":["../src/internal/ws.ts"],"names":[],"mappings":"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"}

package/lib/AbstractChatCompletionRunner.d.mts

@@ -4,14 +4,19 @@ import type { ChatCompletion, ChatCompletionCreateParams, ChatCompletionMessage,
 import type { CompletionUsage } from "../resources/completions.mjs";
 import type { ChatCompletionRunner, ChatCompletionToolRunnerParamsWithContext, ChatCompletionToolRunnerParamsWithoutContext } from "./ChatCompletionRunner.mjs";
 import type { ChatCompletionStreamingRunner, ChatCompletionStreamingToolRunnerParamsWithContext, ChatCompletionStreamingToolRunnerParamsWithoutContext } from "./ChatCompletionStreamingRunner.mjs";
-import { BaseEvents, EventStream } from "./EventStream.mjs";
-import { type BaseFunctionsArgs } from "./RunnableFunction.mjs";
+import type { BaseEvents } from "./EventStream.mjs";
+import { EventStream } from "./EventStream.mjs";
+import type { BaseFunctionsArgs } from "./RunnableFunction.mjs";
+/** Mutable conversation state and cancellation controls available to runner callbacks. */
 export interface ChatCompletionRunnerContext {
+    /** The conversation so far; callbacks may append messages before the next request. */
     messages: ChatCompletionMessageParam[];
+    /** Cancels the active request and prevents the runner from continuing. */
     abort(): void;
 }
+/** Request and lifecycle options for chat completion tool-running helpers. */
 export interface RunnerOptions extends RequestOptions {
-    /** How many requests to make before canceling. Default 10. */
+    /** Maximum chat completion requests before the tool runner finishes; defaults to 10. */
     maxChatCompletions?: number;
     /**
      * A callback that runs after each chat completion and after any tool calls from
@@ -21,9 +26,11 @@ export interface RunnerOptions extends RequestOptions {
      */
     afterCompletion?: (completion: ChatCompletion, runner: ChatCompletionRunnerContext) => void | Promise<void>;
 }
+/** Shared conversation, event, cancellation, and final-result behavior for chat completion runners. */
 export declare class AbstractChatCompletionRunner<EventTypes extends AbstractChatCompletionRunnerEvents, ParsedT> extends EventStream<EventTypes> {
     #private;
     protected _chatCompletions: ParsedChatCompletion<ParsedT>[];
+    /** Mutable conversation history, including initial input, assistant replies, and tool results. */
     messages: ChatCompletionMessageParam[];
     protected _addChatCompletion(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>, chatCompletion: ParsedChatCompletion<ParsedT>): ParsedChatCompletion<ParsedT>;
     protected _addMessage(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>, message: ChatCompletionMessageParam, emit?: boolean): void;
@@ -43,28 +50,42 @@ export declare class AbstractChatCompletionRunner<EventTypes extends AbstractCha
      */
     finalMessage(): Promise<ChatCompletionMessage>;
     /**
-     * @returns a promise that resolves with the content of the final FunctionCall, or rejects
-     * if an error occurred or the stream ended prematurely without producing a ChatCompletionMessage.
+     * Waits for completion and returns the last function-tool call, or `undefined`
+     * when no assistant message contains a function-tool call.
      */
     finalFunctionToolCall(): Promise<ChatCompletionMessageFunctionToolCall.Function | undefined>;
+    /** Waits for completion and returns the last matching function-tool result, if any. */
     finalFunctionToolCallResult(): Promise<string | undefined>;
+    /** Waits for completion and sums token usage across every chat completion in the run. */
     totalUsage(): Promise<CompletionUsage>;
+    /** Returns a copy of the chat completions received so far, in request order. */
     allChatCompletions(): ChatCompletion[];
     protected _emitFinal(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>): void;
     protected _createChatCompletion(client: OpenAI, params: ChatCompletionCreateParams, options?: RequestOptions): Promise<ParsedChatCompletion<ParsedT>>;
     protected _runChatCompletion(client: OpenAI, params: ChatCompletionCreateParams, options?: RequestOptions): Promise<ChatCompletion>;
     protected _runTools<FunctionsArgs extends BaseFunctionsArgs, ToolContext>(client: OpenAI, params: ChatCompletionToolRunnerParamsWithContext<FunctionsArgs, ToolContext> | ChatCompletionToolRunnerParamsWithoutContext<FunctionsArgs> | ChatCompletionStreamingToolRunnerParamsWithContext<FunctionsArgs, ToolContext> | ChatCompletionStreamingToolRunnerParamsWithoutContext<FunctionsArgs>, runner: ChatCompletionRunner<any> | ChatCompletionStreamingRunner<any>, options?: RunnerOptions): Promise<void>;
 }
+/** Conversation and final-result events shared by chat completion runners. */
 export interface AbstractChatCompletionRunnerEvents extends BaseEvents {
+    /** Called for each function-tool call produced by an assistant message. */
     functionToolCall: (functionCall: ChatCompletionMessageFunctionToolCall.Function) => void;
+    /** Called when an assistant reply or tool-result message is appended to the conversation. */
     message: (message: ChatCompletionMessageParam) => void;
+    /** Called whenever a complete chat completion is received. */
     chatCompletion: (completion: ChatCompletion) => void;
+    /** Called at successful completion when the final assistant message contains nonempty text. */
     finalContent: (contentSnapshot: string) => void;
+    /** Called at successful completion with the final assistant message. */
     finalMessage: (message: ChatCompletionMessageParam) => void;
+    /** Called at successful completion with the last chat completion received. */
     finalChatCompletion: (completion: ChatCompletion) => void;
+    /** Called at successful completion when the conversation contains a function-tool call. */
     finalFunctionToolCall: (functionCall: ChatCompletionMessageFunctionToolCall.Function) => void;
+    /** Called when a function-tool result message with nonempty content is appended. */
     functionToolCallResult: (content: string) => void;
+    /** Called at successful completion when a matching function-tool result exists. */
     finalFunctionToolCallResult: (content: string) => void;
+    /** Called at successful completion when at least one response includes token usage. */
     totalUsage: (usage: CompletionUsage) => void;
 }
 //# sourceMappingURL=AbstractChatCompletionRunner.d.mts.map

package/lib/AbstractChatCompletionRunner.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractChatCompletionRunner.d.mts","sourceRoot":"","sources":["../src/lib/AbstractChatCompletionRunner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AbstractChatCompletionRunner.d.mts","sourceRoot":"","sources":["../src/lib/AbstractChatCompletionRunner.ts"],"names":[],"mappings":"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"}

package/lib/AbstractChatCompletionRunner.d.ts

@@ -4,14 +4,19 @@ import type { ChatCompletion, ChatCompletionCreateParams, ChatCompletionMessage,
 import type { CompletionUsage } from "../resources/completions.js";
 import type { ChatCompletionRunner, ChatCompletionToolRunnerParamsWithContext, ChatCompletionToolRunnerParamsWithoutContext } from "./ChatCompletionRunner.js";
 import type { ChatCompletionStreamingRunner, ChatCompletionStreamingToolRunnerParamsWithContext, ChatCompletionStreamingToolRunnerParamsWithoutContext } from "./ChatCompletionStreamingRunner.js";
-import { BaseEvents, EventStream } from "./EventStream.js";
-import { type BaseFunctionsArgs } from "./RunnableFunction.js";
+import type { BaseEvents } from "./EventStream.js";
+import { EventStream } from "./EventStream.js";
+import type { BaseFunctionsArgs } from "./RunnableFunction.js";
+/** Mutable conversation state and cancellation controls available to runner callbacks. */
 export interface ChatCompletionRunnerContext {
+    /** The conversation so far; callbacks may append messages before the next request. */
     messages: ChatCompletionMessageParam[];
+    /** Cancels the active request and prevents the runner from continuing. */
     abort(): void;
 }
+/** Request and lifecycle options for chat completion tool-running helpers. */
 export interface RunnerOptions extends RequestOptions {
-    /** How many requests to make before canceling. Default 10. */
+    /** Maximum chat completion requests before the tool runner finishes; defaults to 10. */
     maxChatCompletions?: number;
     /**
      * A callback that runs after each chat completion and after any tool calls from
@@ -21,9 +26,11 @@ export interface RunnerOptions extends RequestOptions {
      */
     afterCompletion?: (completion: ChatCompletion, runner: ChatCompletionRunnerContext) => void | Promise<void>;
 }
+/** Shared conversation, event, cancellation, and final-result behavior for chat completion runners. */
 export declare class AbstractChatCompletionRunner<EventTypes extends AbstractChatCompletionRunnerEvents, ParsedT> extends EventStream<EventTypes> {
     #private;
     protected _chatCompletions: ParsedChatCompletion<ParsedT>[];
+    /** Mutable conversation history, including initial input, assistant replies, and tool results. */
     messages: ChatCompletionMessageParam[];
     protected _addChatCompletion(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>, chatCompletion: ParsedChatCompletion<ParsedT>): ParsedChatCompletion<ParsedT>;
     protected _addMessage(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>, message: ChatCompletionMessageParam, emit?: boolean): void;
@@ -43,28 +50,42 @@ export declare class AbstractChatCompletionRunner<EventTypes extends AbstractCha
      */
     finalMessage(): Promise<ChatCompletionMessage>;
     /**
-     * @returns a promise that resolves with the content of the final FunctionCall, or rejects
-     * if an error occurred or the stream ended prematurely without producing a ChatCompletionMessage.
+     * Waits for completion and returns the last function-tool call, or `undefined`
+     * when no assistant message contains a function-tool call.
      */
     finalFunctionToolCall(): Promise<ChatCompletionMessageFunctionToolCall.Function | undefined>;
+    /** Waits for completion and returns the last matching function-tool result, if any. */
     finalFunctionToolCallResult(): Promise<string | undefined>;
+    /** Waits for completion and sums token usage across every chat completion in the run. */
     totalUsage(): Promise<CompletionUsage>;
+    /** Returns a copy of the chat completions received so far, in request order. */
     allChatCompletions(): ChatCompletion[];
     protected _emitFinal(this: AbstractChatCompletionRunner<AbstractChatCompletionRunnerEvents, ParsedT>): void;
     protected _createChatCompletion(client: OpenAI, params: ChatCompletionCreateParams, options?: RequestOptions): Promise<ParsedChatCompletion<ParsedT>>;
     protected _runChatCompletion(client: OpenAI, params: ChatCompletionCreateParams, options?: RequestOptions): Promise<ChatCompletion>;
     protected _runTools<FunctionsArgs extends BaseFunctionsArgs, ToolContext>(client: OpenAI, params: ChatCompletionToolRunnerParamsWithContext<FunctionsArgs, ToolContext> | ChatCompletionToolRunnerParamsWithoutContext<FunctionsArgs> | ChatCompletionStreamingToolRunnerParamsWithContext<FunctionsArgs, ToolContext> | ChatCompletionStreamingToolRunnerParamsWithoutContext<FunctionsArgs>, runner: ChatCompletionRunner<any> | ChatCompletionStreamingRunner<any>, options?: RunnerOptions): Promise<void>;
 }
+/** Conversation and final-result events shared by chat completion runners. */
 export interface AbstractChatCompletionRunnerEvents extends BaseEvents {
+    /** Called for each function-tool call produced by an assistant message. */
     functionToolCall: (functionCall: ChatCompletionMessageFunctionToolCall.Function) => void;
+    /** Called when an assistant reply or tool-result message is appended to the conversation. */
     message: (message: ChatCompletionMessageParam) => void;
+    /** Called whenever a complete chat completion is received. */
     chatCompletion: (completion: ChatCompletion) => void;
+    /** Called at successful completion when the final assistant message contains nonempty text. */
     finalContent: (contentSnapshot: string) => void;
+    /** Called at successful completion with the final assistant message. */
     finalMessage: (message: ChatCompletionMessageParam) => void;
+    /** Called at successful completion with the last chat completion received. */
     finalChatCompletion: (completion: ChatCompletion) => void;
+    /** Called at successful completion when the conversation contains a function-tool call. */
     finalFunctionToolCall: (functionCall: ChatCompletionMessageFunctionToolCall.Function) => void;
+    /** Called when a function-tool result message with nonempty content is appended. */
     functionToolCallResult: (content: string) => void;
+    /** Called at successful completion when a matching function-tool result exists. */
     finalFunctionToolCallResult: (content: string) => void;
+    /** Called at successful completion when at least one response includes token usage. */
     totalUsage: (usage: CompletionUsage) => void;
 }
 //# sourceMappingURL=AbstractChatCompletionRunner.d.ts.map

package/lib/AbstractChatCompletionRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractChatCompletionRunner.d.ts","sourceRoot":"","sources":["../src/lib/AbstractChatCompletionRunner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AbstractChatCompletionRunner.d.ts","sourceRoot":"","sources":["../src/lib/AbstractChatCompletionRunner.ts"],"names":[],"mappings":"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"}