openai 7.25.0 → 7.27.0

package/src/resources/beta/agents/sessions/traces.ts

@@ -0,0 +1,298 @@
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../../core/resource';
+import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
+import { buildHeaders } from '../../../../internal/headers';
+import { RequestOptions } from '../../../../internal/request-options';
+import { path } from '../../../../internal/utils/path';
+
+function resolveResourceRequestOptions(
+  options: RequestOptions | undefined,
+  buildOptions: (options: RequestOptions | undefined) => RequestOptions | Promise<RequestOptions>,
+): Promise<RequestOptions> {
+  return Promise.resolve(options).then(buildOptions);
+}
+
+// Recognizable options across SDK runtime versions. Keep this independent of
+// private RequestOptions fields so older handwritten runtimes still compile.
+const normalizeRequestOptionsForQueryKeys = new Set([
+  'method',
+  'path',
+  'query',
+  'body',
+  'headers',
+  'maxRetries',
+  'stream',
+  'timeout',
+  'httpAgent',
+  'fetchOptions',
+  'signal',
+  'idempotencyKey',
+  'defaultBaseURL',
+  '__metadata',
+  '__binaryRequest',
+  '__binaryResponse',
+  '__streamClass',
+  '__security',
+  '__synthesizeEventData',
+]);
+
+function normalizeRequestOptionsForQuery(
+  value: unknown,
+  queryKeys: ReadonlyArray<string>,
+  options: RequestOptions | undefined,
+):
+  | ({
+      [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K];
+    } & {
+      [
+        K in
+          | 'method'
+          | 'path'
+          | 'body'
+          | 'stream'
+          | 'httpAgent'
+          | 'fetchOptions'
+          | 'defaultBaseURL'
+          | '__metadata'
+          | '__binaryRequest'
+          | '__binaryResponse'
+          | '__streamClass'
+          | '__security'
+          | '__synthesizeEventData'
+      ]?: never;
+    })
+  | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  // Optional never fields can still be explicitly undefined unless consumers
+  // enable exactOptionalPropertyTypes. Snapshot data without invoking getters.
+  const entries = Object.entries(Object.getOwnPropertyDescriptors(value)).filter(
+    ([, descriptor]) => descriptor.enumerable && (!('value' in descriptor) || descriptor.value !== undefined),
+  );
+  const keys = entries.map(([key]) => key);
+  const requestOnly = keys.some(
+    (key) => normalizeRequestOptionsForQueryKeys.has(key) && !queryKeys.includes(key),
+  );
+  if (!requestOnly) return undefined;
+  // Declared query fields, including stream, must use the query argument.
+  // Mixing them with request-only options is ambiguous and could change the return type.
+  if (
+    options !== undefined ||
+    keys.some((key) => !normalizeRequestOptionsForQueryKeys.has(key) || queryKeys.includes(key))
+  ) {
+    throw new TypeError('Query parameters and request options must be passed as separate arguments.');
+  }
+  // The query position must not gain authority to change the request destination
+  // or transport. Those overrides require the explicit request options argument.
+  if (
+    keys.some(
+      (key) => !['headers', 'maxRetries', 'timeout', 'signal', 'idempotencyKey', 'query'].includes(key),
+    )
+  ) {
+    throw new TypeError('Pass transport overrides in the explicit request options argument.');
+  }
+  // Copy only the validated fields. Spreading value would reintroduce undefined
+  // transport overrides, and deleting them would mutate the caller's object.
+  return Object.fromEntries(
+    entries.map(([key, descriptor]) => {
+      if ('value' in descriptor) return [key, descriptor.value];
+      return [key, descriptor.get ? Reflect.apply(descriptor.get, value, []) : undefined];
+    }),
+  ) as {
+    [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K];
+  } & {
+    [
+      K in
+        | 'method'
+        | 'path'
+        | 'body'
+        | 'stream'
+        | 'httpAgent'
+        | 'fetchOptions'
+        | 'defaultBaseURL'
+        | '__metadata'
+        | '__binaryRequest'
+        | '__binaryResponse'
+        | '__streamClass'
+        | '__security'
+        | '__synthesizeEventData'
+    ]?: never;
+  };
+}
+
+export class Traces extends APIResource {
+  /**
+   * Lists published root-turn traces as OTLP JSON, ordered by turn creation time and
+   * ID. Unpublished traces are skipped. Each page returns data available when read;
+   * it does not wait for late traces. Trace reads and the JSON response are limited
+   * to 16 MiB per request. If the limit is exceeded, request fewer traces.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const sessionTrace of client.beta.agents.sessions.traces.list(
+   *   'session_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    sessionID: string,
+    query?:
+      | (TraceListParams &
+          (
+            | {
+                [
+                  K in
+                    | 'method'
+                    | 'path'
+                    | 'query'
+                    | 'body'
+                    | 'headers'
+                    | 'maxRetries'
+                    | 'stream'
+                    | 'timeout'
+                    | 'httpAgent'
+                    | 'fetchOptions'
+                    | 'signal'
+                    | 'idempotencyKey'
+                    | 'defaultBaseURL'
+                    | '__metadata'
+                    | '__binaryRequest'
+                    | '__binaryResponse'
+                    | '__streamClass'
+                    | '__security'
+                    | '__synthesizeEventData'
+                ]?: never;
+              }
+            | null
+            | undefined
+          ))
+      | null
+      | undefined,
+    options?: RequestOptions,
+  ): PagePromise<SessionTracesPage, SessionTrace>;
+  list(
+    sessionID: string,
+    options?: {
+      [K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query']?: RequestOptions[K];
+    } & {
+      [
+        K in
+          | 'method'
+          | 'path'
+          | 'body'
+          | 'stream'
+          | 'httpAgent'
+          | 'fetchOptions'
+          | 'defaultBaseURL'
+          | '__metadata'
+          | '__binaryRequest'
+          | '__binaryResponse'
+          | '__streamClass'
+          | '__security'
+          | '__synthesizeEventData'
+      ]?: never;
+    },
+  ): PagePromise<SessionTracesPage, SessionTrace>;
+  list(
+    sessionID: string,
+    query:
+      | TraceListParams
+      | ({
+          [
+            K in 'headers' | 'maxRetries' | 'timeout' | 'signal' | 'idempotencyKey' | 'query'
+          ]?: RequestOptions[K];
+        } & {
+          [
+            K in
+              | 'method'
+              | 'path'
+              | 'body'
+              | 'stream'
+              | 'httpAgent'
+              | 'fetchOptions'
+              | 'defaultBaseURL'
+              | '__metadata'
+              | '__binaryRequest'
+              | '__binaryResponse'
+              | '__streamClass'
+              | '__security'
+              | '__synthesizeEventData'
+          ]?: never;
+        })
+      | null
+      | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SessionTracesPage, SessionTrace> {
+    const normalizeRequestOptionsForQueryOptions = normalizeRequestOptionsForQuery(
+      query,
+      ['after', 'limit', 'order'],
+      options,
+    );
+    if (normalizeRequestOptionsForQueryOptions !== undefined) {
+      options = normalizeRequestOptionsForQueryOptions;
+      query = {};
+    }
+    query = query as TraceListParams | null | undefined;
+    return this._client.getAPIList(
+      path`/agents/sessions/${sessionID}/traces`,
+      CursorPage<SessionTrace>,
+      resolveResourceRequestOptions(options, (options) => ({
+        query,
+        ...options,
+        headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
+        __security: { bearerAuth: true },
+      })),
+    );
+  }
+}
+
+export type SessionTracesPage = CursorPage<SessionTrace>;
+
+export interface SessionTrace {
+  /**
+   * The root turn ID. Use this ID as the pagination anchor.
+   */
+  id: string;
+
+  /**
+   * The Unix timestamp in seconds when the root turn was created.
+   */
+  created_at: number;
+
+  /**
+   * The object type, which is always `agent.session.trace`.
+   */
+  object: 'agent.session.trace';
+
+  /**
+   * An OTLP JSON ExportTraceServiceRequest containing resourceSpans. Only currently
+   * published data is returned; later trace updates are not awaited.
+   */
+  otlp: { [key: string]: unknown };
+
+  /**
+   * The session that owns this trace.
+   */
+  session_id: string;
+}
+
+export interface TraceListParams extends CursorPageParams {
+  /**
+   * The order in which resources are returned. Defaults to `desc`.
+   *
+   * - `asc` - Returns resources in ascending order.
+   * - `desc` - Returns resources in descending order.
+   */
+  order?: 'asc' | 'desc';
+}
+
+export declare namespace Traces {
+  export {
+    type SessionTrace as SessionTrace,
+    type SessionTracesPage as SessionTracesPage,
+    type TraceListParams as TraceListParams,
+  };
+}

package/src/resources/beta/responses/ws-base.ts

@@ -125,6 +125,8 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
    */
   protected abstract _createSocket(url: URL, authHeaders: Record<string, string>): TSocket;
 
+  private _cancelRefresh: (() => void) | undefined;
+
   send(event: ResponsesAPI.BetaResponsesClientEvent) {
     if (!this.socket) {
       throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.');
@@ -177,6 +179,7 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     this._intentionallyClosed = true;
     this._closeCode = props?.code ?? 1000;
     this._closeReason = props?.reason ?? 'OK';
+    this._cancelRefresh?.();
     try {
       this.socket.close(this._closeCode, this._closeReason);
     } catch (err) {
@@ -421,10 +424,13 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     };
   }
 
-  private _connect(): TSocket {
-    this.url = buildURL(this._client, this._parameters ?? {});
+  private _connect(
+    createSocket: (url: URL) => TSocket = (url) => this._createSocket(url, this._authHeaders()),
+    url: URL = buildURL(this._client, this._parameters ?? {}),
+  ): TSocket {
+    this.url = url;
 
-    const socket = this._createSocket(this.url, this._authHeaders());
+    const socket = createSocket(this.url);
 
     socket.on('message', (data: string | ArrayBuffer | ArrayBufferView, isBinary: boolean) => {
       if (isBinary) {
@@ -632,7 +638,22 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
       let closeCodePromise: Promise<number> | undefined;
       try {
         const oldSocket = this.socket;
-        this.socket = this._connect();
+        const url = buildURL(this._client, this._parameters ?? {});
+        const canceled = new Promise<undefined>((resolve) => {
+          this._cancelRefresh = () => resolve(undefined);
+        });
+        let createSocket: ((url: URL) => TSocket) | undefined;
+        try {
+          createSocket = await Promise.race([this._prepareReconnectSocket(), canceled]);
+        } finally {
+          this._cancelRefresh = undefined;
+        }
+        if (!this._canReconnect(closeCode)) {
+          this._isReconnecting = false;
+          this._emitPermanentClose(this._closeCode, this._closeReason);
+          return;
+        }
+        this.socket = this._connect(createSocket, url);
         // Registered synchronously after _connect() and before any
         // await so the code is captured even when ws emits 'close'
         // in the same tick as 'error' (e.g. abortHandshake).
@@ -649,6 +670,15 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
         this._internalEvents._emit('reconnected');
         return;
       } catch {
+        if (this._intentionallyClosed) {
+          // A public close observer may have thrown after lifecycle cleanup.
+          // Only emit here if the reconnect itself had not already closed.
+          if (this._isReconnecting) {
+            this._isReconnecting = false;
+            this._emitPermanentClose(this._closeCode, this._closeReason);
+          }
+          return;
+        }
         if (closeCodePromise) {
           // ws may emit 'error' before 'close', so await the code
           // rather than reading it synchronously.
@@ -722,8 +752,12 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     this._emit('close', code, reason, unsent);
   }
 
-  protected _authHeaders(): Record<string, string> {
-    const apiKey = this._client.apiKey;
+  protected _prepareReconnectSocket(): Promise<(url: URL) => TSocket> {
+    const authHeaders = this._authHeaders();
+    return Promise.resolve((url) => this._createSocket(url, authHeaders));
+  }
+
+  protected _authHeaders(apiKey = this._client.apiKey): Record<string, string> {
     return typeof apiKey === 'string' && apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
   }
 }

package/src/resources/beta/responses/ws.ts

@@ -1,11 +1,10 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
 import * as WS from 'ws';
-import { NodeWebSocket } from '../../../internal/ws-adapter-node';
+import { NodeWebSocket, snapshotNodeWebSocketOptions } from '../../../internal/ws-adapter-node';
 import { ResponsesWSBase, type ResponsesWSBaseOptions } from './ws-base';
 import { OpenAI } from '../../../client';
-import { OpenAIError } from '../../../core/error';
-import { snapshotWebSocketCredentials } from '../../../internal/ws';
+import { ResponsesWebSocketCredentials } from '../../../internal/responses-ws-credentials';
 
 export type { WebSocketStreamOptions } from '../../../internal/ws';
 
@@ -18,6 +17,7 @@ export interface ResponsesWSClientOptions extends WS.ClientOptions, ResponsesWSB
 
 export class ResponsesWS extends ResponsesWSBase<NodeWebSocket> {
   private _wsOptions: WS.ClientOptions | null | undefined;
+  private _credentials = new ResponsesWebSocketCredentials();
 
   constructor(client: OpenAI, options?: ResponsesWSClientOptions | null | undefined) {
     if (!WS?.WebSocket) {
@@ -31,32 +31,42 @@ export class ResponsesWS extends ResponsesWSBase<NodeWebSocket> {
     this._connectInitial();
   }
 
+  protected override _authHeaders(apiKey?: string | null): Record<string, string> {
+    const headers = super._authHeaders(apiKey === undefined ? this._credentials.preparedAPIKey : apiKey);
+    this._credentials.trackInitialHeaders(this._client, headers, () => !!this.socket);
+    return headers;
+  }
+
+  /**
+   * Whether credentials passed to the Node transport use the SDK key.
+   * The SDK recognizes its key, including copies and additions in credential headers.
+   * Override and return true if your socket hook signs or otherwise irreversibly transforms it.
+   * Explicit caller options and header removals still take precedence on reconnect.
+   */
+  protected _usesSDKAPIKey(authHeaders: Record<string, string>): boolean {
+    return this._credentials.usesAPIKey(this._client, authHeaders);
+  }
+
   protected _createSocket(url: URL, authHeaders: Record<string, string>): NodeWebSocket {
     const capturedAuthHeaders = { ...authHeaders };
-    const headers = new Map(Object.entries(this._client._buildWebSocketHeaders(capturedAuthHeaders)));
-    for (const [name, value] of Object.entries(this._wsOptions?.headers ?? {})) {
-      if (value === null) {
-        headers.delete(name.toLowerCase());
-      } else if (value !== undefined) {
-        headers.set(name.toLowerCase(), value);
-      }
-    }
-    const socketOptions: ResponsesWSClientOptions = {
-      ...this._wsOptions,
-      headers: Object.fromEntries(headers),
-      followRedirects: false,
-    };
-    if (
-      this._client._hasApiKeyProvider() &&
-      !capturedAuthHeaders['Authorization'] &&
-      !snapshotWebSocketCredentials(socketOptions)
-    ) {
-      throw new OpenAIError(
-        'Cannot open a Responses WebSocket with an unresolved function-based apiKey. Resolve it before constructing the WebSocket or provide explicit WebSocket credentials.',
-      );
-    }
+    const socketOptions = this._credentials.build(
+      this._client,
+      capturedAuthHeaders,
+      this._wsOptions,
+      !this.socket ? this._usesSDKAPIKey(capturedAuthHeaders) : undefined,
+    );
+    return new NodeWebSocket(new WS.WebSocket(url, socketOptions));
+  }
 
-    const ws = new WS.WebSocket(url, socketOptions);
-    return new NodeWebSocket(ws);
+  protected override async _prepareReconnectSocket(): Promise<(url: URL) => NodeWebSocket> {
+    if (!this._client._hasApiKeyProvider()) {
+      return super._prepareReconnectSocket();
+    }
+    return this._credentials.prepare(
+      this._client,
+      snapshotNodeWebSocketOptions(this._wsOptions),
+      (...args) => this._authHeaders(...args),
+      (url, headers) => this._createSocket(url, headers),
+    );
   }
 }

package/src/resources/chat/completions/completions.ts

@@ -1524,7 +1524,7 @@ export namespace ChatCompletionContentPartImage {
      * Specifies the detail level of the image. Learn more in the
      * [Vision guide](https://developers.openai.com/api/docs/guides/images-vision#choose-an-image-detail-level).
      */
-    detail?: 'auto' | 'low' | 'high';
+    detail?: 'auto' | 'low' | 'high' | 'original';
   }
 
   /**

package/src/resources/evals/runs/runs.ts

@@ -300,7 +300,7 @@ export class Runs extends APIResource {
   cancel(runID: string, params: RunCancelParams, options?: RequestOptions): APIPromise<RunCancelResponse> {
     const { eval_id } = params;
     return this._client.post(
-      path`/evals/${eval_id}/runs/${runID}`,
+      path`/evals/${eval_id}/runs/${runID}/cancel`,
       resolveResourceRequestOptions(options, (options) => ({ ...options, __security: { bearerAuth: true } })),
     );
   }

package/src/resources/live/forks/forks.ts

@@ -87,7 +87,7 @@ export namespace ForkServerEvent {
   }
 
   /**
-   * A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to
+   * A SIP DTMF keypress successfully sent to the SIP trunk. Delivered only to
    * sideband observers; this is not a client command.
    */
   export interface TransportDtmfSend {
@@ -96,6 +96,11 @@ export namespace ForkServerEvent {
     event_id: string;
 
     type: 'transport.dtmf.send';
+
+    /**
+     * The event_id of the client command, when supplied.
+     */
+    client_event_id?: string;
   }
 
   /**

package/src/resources/live/live.ts

@@ -1520,7 +1520,7 @@ export namespace ServerEvent {
   }
 
   /**
-   * A SIP DTMF keypress successfully sent by the hosted tool. Delivered only to
+   * A SIP DTMF keypress successfully sent to the SIP trunk. Delivered only to
    * sideband observers; this is not a client command.
    */
   export interface TransportDtmfSend {
@@ -1529,6 +1529,11 @@ export namespace ServerEvent {
     event_id: string;
 
     type: 'transport.dtmf.send';
+
+    /**
+     * The event_id of the client command, when supplied.
+     */
+    client_event_id?: string;
   }
 
   /**

package/src/resources/responses/ws-base.ts

@@ -123,6 +123,8 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
    */
   protected abstract _createSocket(url: URL, authHeaders: Record<string, string>): TSocket;
 
+  private _cancelRefresh: (() => void) | undefined;
+
   send(event: ResponsesAPI.ResponsesClientEvent) {
     if (!this.socket) {
       throw new OpenAIError('Internal error: failed to initialize socket. Please report this issue.');
@@ -175,6 +177,7 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     this._intentionallyClosed = true;
     this._closeCode = props?.code ?? 1000;
     this._closeReason = props?.reason ?? 'OK';
+    this._cancelRefresh?.();
     try {
       this.socket.close(this._closeCode, this._closeReason);
     } catch (err) {
@@ -419,10 +422,13 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     };
   }
 
-  private _connect(): TSocket {
-    this.url = buildURL(this._client, this._parameters ?? {});
+  private _connect(
+    createSocket: (url: URL) => TSocket = (url) => this._createSocket(url, this._authHeaders()),
+    url: URL = buildURL(this._client, this._parameters ?? {}),
+  ): TSocket {
+    this.url = url;
 
-    const socket = this._createSocket(this.url, this._authHeaders());
+    const socket = createSocket(this.url);
 
     socket.on('message', (data: string | ArrayBuffer | ArrayBufferView, isBinary: boolean) => {
       if (isBinary) {
@@ -630,7 +636,22 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
       let closeCodePromise: Promise<number> | undefined;
       try {
         const oldSocket = this.socket;
-        this.socket = this._connect();
+        const url = buildURL(this._client, this._parameters ?? {});
+        const canceled = new Promise<undefined>((resolve) => {
+          this._cancelRefresh = () => resolve(undefined);
+        });
+        let createSocket: ((url: URL) => TSocket) | undefined;
+        try {
+          createSocket = await Promise.race([this._prepareReconnectSocket(), canceled]);
+        } finally {
+          this._cancelRefresh = undefined;
+        }
+        if (!this._canReconnect(closeCode)) {
+          this._isReconnecting = false;
+          this._emitPermanentClose(this._closeCode, this._closeReason);
+          return;
+        }
+        this.socket = this._connect(createSocket, url);
         // Registered synchronously after _connect() and before any
         // await so the code is captured even when ws emits 'close'
         // in the same tick as 'error' (e.g. abortHandshake).
@@ -647,6 +668,15 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
         this._internalEvents._emit('reconnected');
         return;
       } catch {
+        if (this._intentionallyClosed) {
+          // A public close observer may have thrown after lifecycle cleanup.
+          // Only emit here if the reconnect itself had not already closed.
+          if (this._isReconnecting) {
+            this._isReconnecting = false;
+            this._emitPermanentClose(this._closeCode, this._closeReason);
+          }
+          return;
+        }
         if (closeCodePromise) {
           // ws may emit 'error' before 'close', so await the code
           // rather than reading it synchronously.
@@ -720,8 +750,12 @@ export abstract class ResponsesWSBase<TSocket extends WebSocketLike> extends Res
     this._emit('close', code, reason, unsent);
   }
 
-  protected _authHeaders(): Record<string, string> {
-    const apiKey = this._client.apiKey;
+  protected _prepareReconnectSocket(): Promise<(url: URL) => TSocket> {
+    const authHeaders = this._authHeaders();
+    return Promise.resolve((url) => this._createSocket(url, authHeaders));
+  }
+
+  protected _authHeaders(apiKey = this._client.apiKey): Record<string, string> {
     return typeof apiKey === 'string' && apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
   }
 }