openai 7.25.0 → 7.27.0

package/src/lib/beta/agents/result-collection.ts

@@ -0,0 +1,115 @@
+import { OpenAIError } from '../../../core/error';
+import type { AgentSessionEvent } from '../../../resources/beta/agents/agents';
+import type { AgentTurnResult } from './agent-turn-result';
+import { AgentTurnResultCollector } from './agent-turn-result-collector';
+import { AgentTurnResultError } from './agent-turn-result-error';
+
+/** Shares collection between a raw creation stream and the follow-up helper.
+ * @internal
+ */
+export class ResultCollection {
+  #iterator: AsyncGenerator<AgentSessionEvent, void> | undefined;
+  #ended = false;
+  #enabled = false;
+  #uncollectedEvents = false;
+  #error: unknown;
+  #result: Promise<AgentTurnResult> | undefined;
+  readonly collector: AgentTurnResultCollector;
+
+  readonly #source: () => AsyncIterator<AgentSessionEvent>;
+  readonly #signal: AbortSignal | undefined;
+  readonly #canHandle: (name: string) => boolean;
+
+  constructor(
+    source: () => AsyncIterator<AgentSessionEvent>,
+    canHandle: (name: string) => boolean = () => false,
+    sessionID?: string,
+    signal?: AbortSignal,
+  ) {
+    this.#source = source;
+    this.#signal = signal;
+    this.#canHandle = canHandle;
+    this.collector = new AgentTurnResultCollector(sessionID);
+  }
+
+  enable(): void {
+    if (!this.#enabled && this.#uncollectedEvents) {
+      throw new OpenAIError(
+        'Call withResultCollection() before consuming events, or call finalResult() on a fresh stream.',
+      );
+    }
+    this.#enabled = true;
+  }
+
+  iterate(): AsyncIterator<AgentSessionEvent> {
+    if (this.#iterator) {
+      throw new OpenAIError('An agent result stream can only be consumed once');
+    }
+    return (this.#iterator = this.#observe());
+  }
+
+  async *#observe(): AsyncGenerator<AgentSessionEvent, void> {
+    const iterator = this.#source();
+    let done = false;
+    try {
+      while (true) {
+        // oxlint-disable-next-line no-await-in-loop -- Pull the single-use stream sequentially.
+        const next = await iterator.next();
+        if (next.done) {
+          done = true;
+          return;
+        }
+        if (this.#enabled) {
+          this.collector.accept(next.value);
+        } else {
+          this.#uncollectedEvents = true;
+        }
+        yield next.value;
+      }
+    } catch (error) {
+      if (this.#enabled) {
+        this.#error = error;
+      }
+      throw error;
+    } finally {
+      this.#ended = true;
+      if (!done) {
+        await iterator.return?.();
+      }
+    }
+  }
+
+  finalResult(): Promise<AgentTurnResult> {
+    return (this.#result ??= this.#collect());
+  }
+
+  async #collect(): Promise<AgentTurnResult> {
+    this.enable();
+    try {
+      const iterator = this.#iterator ?? this.iterate();
+      while (!this.#ended && !this.collector.ready) {
+        this.collector.checkAction(this.#canHandle);
+        // oxlint-disable-next-line no-await-in-loop -- Each event can dispatch tools before the next pull.
+        const next = await iterator.next();
+        if (next.done) {
+          break;
+        }
+      }
+      if (this.#error !== undefined && !this.collector.ready) {
+        throw this.#error;
+      }
+      if (!this.collector.ready && this.#signal?.aborted) {
+        throw this.collector.error('observation', this.#signal.reason);
+      }
+      return this.collector.finish();
+    } catch (error) {
+      throw error instanceof AgentTurnResultError ? error : this.collector.error('observation', error);
+    } finally {
+      try {
+        await this.#iterator?.return();
+      } finally {
+        this.collector.release();
+      }
+    }
+  }
+}

package/src/lib/beta/agents/tool-output.ts

@@ -0,0 +1,22 @@
+import { hasOwn, isObj } from '../../../internal/utils/values';
+import type { InputContentParam } from '../../../resources/beta/agents/agents';
+
+/**
+ * Recognizes supported content blocks without confusing JSON business data with content.
+ * @internal
+ */
+export function isInputContent(value: unknown): value is InputContentParam {
+  if (!isObj(value)) {
+    return false;
+  }
+  const content = value;
+  let field: string;
+  if (content['type'] === 'input_text') {
+    field = 'text';
+  } else if (content['type'] === 'input_image') {
+    field = 'image_url';
+  } else {
+    return false;
+  }
+  return hasOwn(content, 'type') && hasOwn(content, field) && typeof content[field] === 'string';
+}

package/src/lib/responses/responses-websocket-session.ts

@@ -22,9 +22,13 @@ interface LaneState {
   bytes: number;
 }
 
+// A disposed helper cannot distinguish a delayed terminal from a later request
+// on the same socket. Retain only IDs (never lane buffers) until that socket is gone.
+const reservedLanes = new WeakMap<WebSocketLike, Set<string | undefined>>();
+
 /** Limits for this optional helper. They do not change the underlying socket's limits. */
 export interface ResponsesWebSocketSessionOptions {
-  /** Maximum lane IDs registered until the next reconnect, including detached lanes. */
+  /** Maximum lane IDs registered on the socket until the next reconnect, including detached lanes. */
   maxLanes: number;
   /** Maximum queued events across all lanes. */
   maxBufferedEvents: number;
@@ -129,10 +133,16 @@ export class ResponsesWebSocketSession {
     ) {
       throw new OpenAIError('Invalid Responses WebSocket stream ID');
     }
-    if (this.#lanes.has(streamID)) {
+    const { socket: physicalSocket } = this.#connection;
+    let reservations = reservedLanes.get(physicalSocket);
+    if (!reservations) {
+      reservations = new Set();
+      reservedLanes.set(physicalSocket, reservations);
+    }
+    if (reservations.has(streamID)) {
       throw new OpenAIError('Responses WebSocket lane is already registered');
     }
-    if (this.#lanes.size >= this.#maxLanes) {
+    if (reservations.size >= this.#maxLanes) {
       throw new OpenAIError('Responses WebSocket lane limit exceeded');
     }
     const entry: LaneState = {
@@ -160,6 +170,7 @@ export class ResponsesWebSocketSession {
         positiveInteger(limits.maxBufferedBytes ?? this.#maxBytes),
       ),
     };
+    reservations.add(streamID);
     this.#lanes.set(streamID, entry);
     return entry.lane;
   }

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

@@ -3667,6 +3667,12 @@ export namespace Environment {
      */
     type: 'openai_hosted';
 
+    /**
+     * The effective CPU and memory tier, or null when unknown or outside the public
+     * tiers.
+     */
+    container_size?: 'small' | 'medium' | 'large' | null;
+
     /**
      * The effective desktop configuration.
      */
@@ -3791,6 +3797,11 @@ export namespace EnvironmentParam {
      */
     capability_directories?: Array<string> | null;
 
+    /**
+     * The hosted container size. Omission selects the medium tier.
+     */
+    container_size?: 'small' | 'medium' | 'large';
+
     /**
      * Desktop provisioning. Omission or null inherits the template setting, or
      * defaults to disabled.

package/src/resources/beta/agents/environments/files.ts

@@ -1,5 +1,11 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
+import {
+  prepareAgentFiles,
+  uploadAgentFile,
+  type PreparedAgentFiles,
+} from '../../../../lib/beta/agents/files';
+import type { Uploadable } from '../../../../internal/uploads';
 import { APIResource } from '../../../../core/resource';
 import { APIPromise } from '../../../../core/api-promise';
 import { PagePromise, TokenPage, type TokenPageParams } from '../../../../core/pagination';
@@ -15,6 +21,16 @@ function resolveResourceRequestOptions(
 }
 
 export class Files extends APIResource {
+  /** Beta: prepare initial hosted file references; uploaded Files API objects remain caller-owned. */
+  prepare(files: Record<string, Uploadable>, options?: RequestOptions): Promise<PreparedAgentFiles> {
+    return prepareAgentFiles(this._client, files, options);
+  }
+
+  /** Beta: upload one local file and stage its reference in a live environment. */
+  upload(environmentID: string, params: { file: Uploadable; path: string }, options?: RequestOptions) {
+    return uploadAgentFile(this._client, this, environmentID, params, options);
+  }
+
   /**
    * Copies inline bytes or a Files API file into a connected execution environment.
    * See

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

@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
+import { AgentResultArtifacts } from '../../../../lib/beta/agents/result-artifacts';
+import type { AgentTurnResult } from '../../../../lib/beta/agents/agent-turn-result';
 import { APIResource } from '../../../../core/resource';
 import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
@@ -122,6 +124,11 @@ function normalizeRequestOptionsForQuery(
 }
 
 export class Artifacts extends APIResource {
+  /** Beta: bind artifact lookup and downloads to a completed result's exact session and turn. */
+  forResult(result: AgentTurnResult): AgentResultArtifacts {
+    return new AgentResultArtifacts(this, result);
+  }
+
   /**
    * Retrieves immutable metadata for one durable session artifact. See
    * [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).

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

@@ -17,11 +17,12 @@ function resolveResourceRequestOptions(
 
 export class Events extends APIResource {
   /**
-   * Submits message, cancellation, or tool-result events to a managed agent session.
-   * Cancellation can recover a still-open turn whose backend execution has ended by
-   * marking it cancelled and abandoning unpublished outputs. Saved results,
-   * published files, and existing terminal outcomes are preserved. HTTP 202 confirms
-   * acceptance, not durable completion. See
+   * Submits message, cancellation, tool-result, or computer-use approval-response
+   * events to a managed agent session. Cancellation can recover a still-open turn
+   * whose backend execution has ended by marking it cancelled and abandoning
+   * unpublished outputs. Saved results, published files, and existing terminal
+   * outcomes are preserved. HTTP 202 confirms acceptance, not durable completion.
+   * See
    * [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events).
    *
    * @example

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

@@ -21,4 +21,5 @@ export {
   type SessionListParams,
 } from './sessions';
 export { Subagents, type SubagentRetrieveParams, type SubagentListParams } from './subagents/index';
+export { Traces, type SessionTrace, type TraceListParams, type SessionTracesPage } from './traces';
 export { Turns, type Turn, type TurnRetrieveParams, type TurnListParams, type TurnsPage } from './turns';

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

@@ -4,6 +4,12 @@ import {
   AgentSessionStream,
   type AgentSessionStreamParams,
 } from '../../../../lib/agents/agent-session-stream';
+import {
+  type AgentSessionCreateStream,
+  withAgentTurnResult,
+} from '../../../../lib/beta/agents/agent-session-create-stream';
+import type { AgentOutputFormat } from '../../../../lib/beta/agents/output-format-types';
+import { captureAgentOutput } from '../../../../lib/beta/agents/parse-result';
 import { APIResource } from '../../../../core/resource';
 import * as SessionsAPI from './sessions';
 import * as AgentsAPI from '../agents';
@@ -23,13 +29,15 @@ import * as EventsAPI from './events';
 import { EventCreateParams, Events } from './events';
 import * as ItemsAPI from './items';
 import { ItemListParams, Items } from './items';
+import * as TracesAPI from './traces';
+import { SessionTrace, SessionTracesPage, TraceListParams, Traces } from './traces';
 import * as TurnsAPI from './turns';
 import { Turn, TurnListParams, TurnRetrieveParams, Turns, TurnsPage } from './turns';
 import * as SubagentsAPI from './subagents/subagents';
 import { SubagentListParams, SubagentRetrieveParams, Subagents } from './subagents/subagents';
 import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
-import { Stream } from '../../../../core/streaming';
+import type { Stream } from '../../../../core/streaming';
 import { buildHeaders } from '../../../../internal/headers';
 import { RequestOptions } from '../../../../internal/request-options';
 import { path } from '../../../../internal/utils/path';
@@ -150,7 +158,11 @@ function normalizeRequestOptionsForQuery(
 
 export class Sessions extends APIResource {
   /** Stream one turn on an idle session with a single input writer. See AgentSessionStream for lifecycle and tool handling. */
-  stream(sessionID: string, params: AgentSessionStreamParams, options?: RequestOptions): AgentSessionStream {
+  stream<T = never>(
+    sessionID: string,
+    params: AgentSessionStreamParams<T>,
+    options?: RequestOptions,
+  ): AgentSessionStream<T> {
     return new AgentSessionStream(this, sessionID, params, options);
   }
 
@@ -158,6 +170,7 @@ export class Sessions extends APIResource {
   artifacts: ArtifactsAPI.Artifacts = new ArtifactsAPI.Artifacts(this._client);
   items: ItemsAPI.Items = new ItemsAPI.Items(this._client);
   events: EventsAPI.Events = new EventsAPI.Events(this._client);
+  traces: TracesAPI.Traces = new TracesAPI.Traces(this._client);
   turns: TurnsAPI.Turns = new TurnsAPI.Turns(this._client);
 
   /**
@@ -173,29 +186,38 @@ export class Sessions extends APIResource {
    *   });
    * ```
    */
-  create(body: SessionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<AgentsAPI.AgentSession>;
-  create(
-    body: SessionCreateParamsStreaming,
+  create<T>(
+    body: SessionCreateParamsStreaming & { agent: { text: { format: AgentOutputFormat<T> } } },
     options?: RequestOptions,
-  ): APIPromise<Stream<AgentsAPI.AgentSessionEvent>>;
+  ): APIPromise<AgentSessionCreateStream<T>>;
+  create(body: SessionCreateParamsNonStreaming, options?: RequestOptions): APIPromise<AgentsAPI.AgentSession>;
+  create(body: SessionCreateParamsStreaming, options?: RequestOptions): APIPromise<AgentSessionCreateStream>;
   create(
     body: SessionCreateParamsBase,
     options?: RequestOptions,
-  ): APIPromise<Stream<AgentsAPI.AgentSessionEvent> | AgentsAPI.AgentSession>;
+  ): APIPromise<AgentSessionCreateStream | AgentsAPI.AgentSession>;
   create(
     body: SessionCreateParams,
     options?: RequestOptions,
-  ): APIPromise<AgentsAPI.AgentSession> | APIPromise<Stream<AgentsAPI.AgentSessionEvent>> {
-    return this._client.post(
-      '/agents/sessions',
-      resolveResourceRequestOptions(options, (options) => ({
-        body,
-        ...options,
-        headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
-        stream: body.stream ?? false,
-        __security: { bearerAuth: true },
-      })),
-    ) as APIPromise<AgentsAPI.AgentSession> | APIPromise<Stream<AgentsAPI.AgentSessionEvent>>;
+  ): APIPromise<AgentsAPI.AgentSession> | APIPromise<AgentSessionCreateStream> {
+    const output = captureAgentOutput(body, options);
+    return this._client
+      .post<AgentsAPI.AgentSession | Stream<AgentsAPI.AgentSessionEvent>>(
+        '/agents/sessions',
+        resolveResourceRequestOptions(output.options, (options) => ({
+          body: output.body,
+          ...options,
+          headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
+          stream: output.body.stream ?? false,
+          __security: { bearerAuth: true },
+        })),
+      )
+      ._thenUnwrap((data, { options }) =>
+        // SAFETY: defaultParseResponse uses this same resolved flag to return the configured stream instance.
+        options.stream
+          ? withAgentTurnResult(data as Stream<AgentsAPI.AgentSessionEvent>, output.format)
+          : data,
+      ) as APIPromise<AgentsAPI.AgentSession> | APIPromise<AgentSessionCreateStream>;
   }
 
   /**
@@ -587,6 +609,7 @@ Sessions.Subagents = Subagents;
 Sessions.Artifacts = Artifacts;
 Sessions.Items = Items;
 Sessions.Events = Events;
+Sessions.Traces = Traces;
 Sessions.Turns = Turns;
 
 export declare namespace Sessions {
@@ -619,6 +642,13 @@ export declare namespace Sessions {
 
   export { Events as Events, type EventCreateParams as EventCreateParams };
 
+  export {
+    Traces as Traces,
+    type SessionTrace as SessionTrace,
+    type SessionTracesPage as SessionTracesPage,
+    type TraceListParams as TraceListParams,
+  };
+
   export {
     Turns as Turns,
     type Turn as Turn,