openai 7.25.0 → 7.26.0

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

@@ -0,0 +1,133 @@
+import type { RequestOptions } from '../../../internal/request-options';
+import { OpenAIError } from '../../../core/error';
+import type { SessionCreateParams } from '../../../resources/beta/agents/sessions/sessions';
+import type { AgentTurnResult } from './agent-turn-result';
+import type { TextFormatParam } from '../../../resources/beta/agents/agents';
+import type { AgentOutputFormat, AgentResult } from './output-format-types';
+import { ParsedAgentTurnResult } from './parsed-agent-turn-result';
+import { AgentOutputParseError } from './output-parse-error';
+
+/** @internal */
+export function parseAgentResult<T>(result: AgentTurnResult, format?: AgentOutputFormat<T>): AgentResult<T> {
+  try {
+    if (!format) {
+      // SAFETY: Absent formats use the default never/raw overload.
+      return result as AgentResult<T>;
+    }
+    let first: { value: T } | undefined;
+    for (const message of result.messages) {
+      for (const content of message.content) {
+        if (content.type === 'output_text') {
+          const value = format.$parseRaw(content.text);
+          first ??= { value };
+        }
+      }
+    }
+    if (!first) {
+      throw new AgentOutputParseError(result);
+    }
+    // SAFETY: Callers preserve the format's inferred T.
+    return new ParsedAgentTurnResult(result, first.value) as AgentResult<T>;
+  } catch {
+    throw new AgentOutputParseError(result);
+  }
+}
+
+// Inspect only JSON-visible data fields; leave getters and inherited values to normal serialization.
+function ownJSONValue<T extends object, K extends keyof T>(
+  object: T | null | undefined,
+  key: K,
+): T[K] | undefined {
+  const descriptor = object && Object.getOwnPropertyDescriptor(object, key);
+  // SAFETY: The own data descriptor corresponds to the requested property in T.
+  return descriptor?.enumerable && 'value' in descriptor ? (descriptor.value as T[K]) : undefined;
+}
+
+/** @internal */
+export function agentFormatParser<T = unknown>(
+  format: TextFormatParam | null | undefined,
+): AgentOutputFormat<T> | undefined {
+  if (!format) {
+    return undefined;
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(format, '$parseRaw');
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- An own parser data property is the explicit opt-in marker.
+  if (!descriptor || !('value' in descriptor) || typeof descriptor.value !== 'function') {
+    return undefined;
+  }
+  // SAFETY: Inspect the schema data descriptor without evaluating a caller getter; validate its discriminator below.
+  const schema = ownJSONValue(format as TextFormatParam.TextFormatParamJSONSchema, 'schema');
+  if (ownJSONValue(format, 'type') !== 'json_schema' || !schema) {
+    throw new OpenAIError('Typed agent formats require own enumerable type and schema data properties');
+  }
+  // SAFETY: The own descriptor was checked for a callable parser; retain its receiver and never reread the property.
+  const parse = descriptor.value as AgentOutputFormat<T>['$parseRaw'];
+  return { type: 'json_schema', schema, $parseRaw: (text) => parse.call(format, text) };
+}
+
+// Materialize JSON-visible envelope getters once without evaluating unrelated properties.
+function snapshotJSONProperty<T extends object, K extends keyof T>(
+  object: T,
+  key: K,
+  capture: (value: T[K]) => T[K] = (value) => value,
+): T {
+  const descriptor = Object.getOwnPropertyDescriptor(object, key);
+  if (!descriptor?.enumerable) {
+    return object;
+  }
+  const value = capture(object[key]);
+  if ('value' in descriptor && value === descriptor.value) {
+    return object;
+  }
+  // SAFETY: Preserve the original properties/prototype, replacing only this captured property's value.
+  return Object.create(Object.getPrototypeOf(object), {
+    ...Object.getOwnPropertyDescriptors(object),
+    [key]: { value, enumerable: true, configurable: descriptor.configurable, writable: true },
+  }) as T;
+}
+
+/** @internal */
+export function captureAgentOutput(input: SessionCreateParams, options?: RequestOptions) {
+  const body = snapshotJSONProperty(input, 'agent', (agent) =>
+    agent
+      ? snapshotJSONProperty(agent, 'text', (text) => (text ? snapshotJSONProperty(text, 'format') : text))
+      : agent,
+  );
+  const agent = ownJSONValue(body, 'agent');
+  const text = ownJSONValue(agent, 'text');
+  const format = agentFormatParser(ownJSONValue(text, 'format'));
+  if (!format) {
+    return { body, options };
+  }
+  const schema = structuredClone(format.schema);
+  for (const envelope of [body, agent, text]) {
+    if (envelope && 'toJSON' in envelope) {
+      throw new OpenAIError('Typed agent requests cannot customize body, agent, or text serialization');
+    }
+  }
+  // Snapshot options once, matching the own enumerable fields native request spreading uses.
+  const capturedOptions = { ...options };
+  if (ownJSONValue(capturedOptions, 'body') !== undefined) {
+    throw new OpenAIError('Typed agent requests cannot override the body in request options');
+  }
+  delete capturedOptions.body;
+  return {
+    options: capturedOptions,
+    body: {
+      ...body,
+      agent: {
+        ...agent,
+        text: { ...text, format: { type: 'json_schema', schema } },
+      },
+    },
+    format,
+  };
+}
+
+/** @internal */
+export async function parseAgentResultPromise<T>(
+  result: Promise<AgentTurnResult>,
+  format?: AgentOutputFormat<T>,
+): Promise<AgentResult<T>> {
+  return parseAgentResult(await result, format);
+}

package/src/lib/beta/agents/parsed-agent-turn-result.ts

@@ -0,0 +1,12 @@
+import { AgentTurnResult } from './agent-turn-result';
+
+/** Beta: a completed hosted turn whose output passed the local parser. */
+export class ParsedAgentTurnResult<T> extends AgentTurnResult {
+  readonly output_parsed: T;
+  readonly raw_result: AgentTurnResult;
+  constructor(result: AgentTurnResult, parsed: T) {
+    super(result.turn, result.messages);
+    this.raw_result = result;
+    this.output_parsed = parsed;
+  }
+}

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/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,