openai 7.24.0 → 7.26.0

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

@@ -414,6 +414,11 @@ export interface EnvironmentTemplate {
    * The Unix timestamp, in seconds, when the template was last updated.
    */
   updated_at: number;
+
+  /**
+   * Desktop configuration for each OpenAI-hosted environment.
+   */
+  desktop?: EnvironmentTemplate.Desktop;
 }
 
 export namespace EnvironmentTemplate {
@@ -466,7 +471,7 @@ export namespace EnvironmentTemplate {
      *
      * - `enabled` - Allows unrestricted network access.
      * - `disabled` - Disables network access.
-     * - `restricted` - Allows access only to configured domains.
+     * - `restricted` - Applies the configured domain restrictions.
      */
     access: 'enabled' | 'disabled' | 'restricted';
 
@@ -535,6 +540,16 @@ export namespace EnvironmentTemplate {
      */
     type: 'inline';
   }
+
+  /**
+   * Desktop configuration for each OpenAI-hosted environment.
+   */
+  export interface Desktop {
+    /**
+     * Whether the environment provisions a desktop and browser proxy.
+     */
+    enabled: boolean;
+  }
 }
 
 /**
@@ -564,6 +579,12 @@ export interface TemplateCreateParams {
    */
   capability_directories?: Array<string> | null;
 
+  /**
+   * Desktop provisioning. Omission or null inherits the template setting, or
+   * defaults to disabled.
+   */
+  desktop?: TemplateCreateParams.Desktop | null;
+
   /**
    * Environment variables made available to the agent.
    */
@@ -608,6 +629,17 @@ export interface TemplateCreateParams {
 }
 
 export namespace TemplateCreateParams {
+  /**
+   * Desktop provisioning. Omission or null inherits the template setting, or
+   * defaults to disabled.
+   */
+  export interface Desktop {
+    /**
+     * Whether to provision the desktop and its browser proxy.
+     */
+    enabled: boolean;
+  }
+
   /**
    * Network access policy for the environment. Defaults to disabled for GA requests
    * and enabled for beta requests.
@@ -618,7 +650,7 @@ export namespace TemplateCreateParams {
      *
      * - `enabled` - Allows unrestricted network access.
      * - `disabled` - Disables network access.
-     * - `restricted` - Allows access only to configured domains.
+     * - `restricted` - Applies the configured domain restrictions.
      */
     access: 'enabled' | 'disabled' | 'restricted';
 
@@ -626,6 +658,13 @@ export namespace TemplateCreateParams {
      * Domains the environment may access when network access is restricted.
      */
     allowed_domains?: Array<string> | null;
+
+    /**
+     * Domains blocked for both executor and browser when access is restricted. A
+     * nonempty list requires `access: restricted` and cannot be combined with nonempty
+     * `allowed_domains`. Wildcard domains are not supported.
+     */
+    blocked_domains?: Array<string> | null;
   }
 
   /**
@@ -655,6 +694,11 @@ export interface TemplateUpdateParams {
    */
   capability_directories?: Array<string> | null;
 
+  /**
+   * Replacement desktop configuration, or null to disable the desktop.
+   */
+  desktop?: TemplateUpdateParams.Desktop | null;
+
   /**
    * Replacement confidential environment values.
    */
@@ -699,6 +743,16 @@ export interface TemplateUpdateParams {
 }
 
 export namespace TemplateUpdateParams {
+  /**
+   * Replacement desktop configuration, or null to disable the desktop.
+   */
+  export interface Desktop {
+    /**
+     * Whether to provision the desktop and its browser proxy.
+     */
+    enabled: boolean;
+  }
+
   /**
    * Network access available after setup completes. Omit to preserve the current
    * policy, or pass `null` to reset to disabled for GA requests or enabled for beta
@@ -710,7 +764,7 @@ export namespace TemplateUpdateParams {
      *
      * - `enabled` - Allows unrestricted network access.
      * - `disabled` - Disables network access.
-     * - `restricted` - Allows access only to configured domains.
+     * - `restricted` - Applies the configured domain restrictions.
      */
     access: 'enabled' | 'disabled' | 'restricted';
 
@@ -718,6 +772,13 @@ export namespace TemplateUpdateParams {
      * Domains the environment may access when network access is restricted.
      */
     allowed_domains?: Array<string> | null;
+
+    /**
+     * Domains blocked for both executor and browser when access is restricted. A
+     * nonempty list requires `access: restricted` and cannot be combined with nonempty
+     * `allowed_domains`. Wildcard domains are not supported.
+     */
+    blocked_domains?: Array<string> | null;
   }
 
   /**

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

@@ -3,6 +3,9 @@
 export {
   Agents,
   type Agent,
+  type AgentBrowserAuthenticationCancelParam,
+  type AgentBrowserAuthenticationSubmitParam,
+  type AgentBrowserOriginAccessParam,
   type AgentCloseSubagentCallItem,
   type AgentCommandExecutionItem,
   type AgentContent,

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
@@ -31,13 +32,16 @@ export class Events extends APIResource {
    *   {
    *     events: [
    *       {
-   *         input: [
-   *           {
-   *             content: [{ text: 'text', type: 'input_text' }],
-   *             role: 'user',
-   *           },
-   *         ],
-   *         type: 'agent.session.input.message',
+   *         request_id: 'request_id',
+   *         response: {
+   *           action: 'submit',
+   *           fields: [
+   *             { field_id: 'field_id', value: 'value' },
+   *           ],
+   *           type: 'browser_authentication',
+   *         },
+   *         type:
+   *           'agent.session.input.computer_use_approval_request_result',
    *       },
    *     ],
    *   },

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,

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/beta.ts

@@ -76,6 +76,9 @@ import {
 import * as AgentsAPI from './agents/agents';
 import {
   Agent,
+  AgentBrowserAuthenticationCancelParam,
+  AgentBrowserAuthenticationSubmitParam,
+  AgentBrowserOriginAccessParam,
   AgentCloseSubagentCallItem,
   AgentCommandExecutionItem,
   AgentContent,
@@ -451,6 +454,9 @@ export declare namespace Beta {
     type TranscriptionSessionUpdatedEvent as TranscriptionSessionUpdatedEvent,
     Agents as Agents,
     type Agent as Agent,
+    type AgentBrowserAuthenticationCancelParam as AgentBrowserAuthenticationCancelParam,
+    type AgentBrowserAuthenticationSubmitParam as AgentBrowserAuthenticationSubmitParam,
+    type AgentBrowserOriginAccessParam as AgentBrowserOriginAccessParam,
     type AgentCloseSubagentCallItem as AgentCloseSubagentCallItem,
     type AgentCommandExecutionItem as AgentCommandExecutionItem,
     type AgentContent as AgentContent,

package/src/resources/beta/index.ts

@@ -3,6 +3,9 @@
 export {
   Agents,
   type Agent,
+  type AgentBrowserAuthenticationCancelParam,
+  type AgentBrowserAuthenticationSubmitParam,
+  type AgentBrowserOriginAccessParam,
   type AgentCloseSubagentCallItem,
   type AgentCommandExecutionItem,
   type AgentContent,