openai 7.28.0 → 7.30.0

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

@@ -2,7 +2,7 @@
 
 import { APIResource } from '../../../core/resource';
 import * as AgentsAPI from './agents';
-import * as TurnsAPI from './sessions/turns';
+import * as TurnsAPI from './sessions/turns/turns';
 import * as EnvironmentsAPI from './environments/environments';
 import { EnvironmentInfo, Environments } from './environments/environments';
 import * as SessionsAPI from './sessions/sessions';
@@ -3825,8 +3825,8 @@ export namespace EnvironmentParam {
     files?: Array<AgentsAPI.HostedEnvironmentFileParam> | null;
 
     /**
-     * Network access policy for the environment. Defaults to disabled for GA requests
-     * and enabled for beta requests.
+     * Network access policy for the environment. If omitted, the API version
+     * determines whether network access is enabled or disabled.
      */
     network?: EnvironmentParamOpenAIHosted.Network | null;
 
@@ -3865,8 +3865,8 @@ export namespace EnvironmentParam {
     }
 
     /**
-     * Network access policy for the environment. Defaults to disabled for GA requests
-     * and enabled for beta requests.
+     * Network access policy for the environment. If omitted, the API version
+     * determines whether network access is enabled or disabled.
      */
     export interface Network {
       /**
@@ -5003,6 +5003,12 @@ export interface SessionTurnError {
    * - `session_budget_exceeded` - The session has reached its usage budget.
    * - `usage_limit_exceeded` - The organization has reached a usage, plan, or
    *   billing limit.
+   * - `project_spend_limit_exceeded` - The project has reached its enforced spend
+   *   limit.
+   * - `organization_spend_limit_exceeded` - The organization has reached its
+   *   enforced spend limit.
+   * - `organization_usage_limit_exceeded` - The organization has reached its
+   *   OpenAI-assigned usage limit.
    * - `credit_balance_exhausted` - The organization has no API credits remaining.
    * - `rate_limit_exceeded` - The request exceeds the available rate limit.
    * - `flex_unavailable` - Flex processing is temporarily unavailable.
@@ -5029,6 +5035,9 @@ export interface SessionTurnError {
     | 'context_length_exceeded'
     | 'session_budget_exceeded'
     | 'usage_limit_exceeded'
+    | 'project_spend_limit_exceeded'
+    | 'organization_spend_limit_exceeded'
+    | 'organization_usage_limit_exceeded'
     | 'credit_balance_exhausted'
     | 'rate_limit_exceeded'
     | 'flex_unavailable'

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

@@ -601,8 +601,8 @@ export interface TemplateCreateParams {
   name?: string | null;
 
   /**
-   * Network access policy for the environment. Defaults to disabled for GA requests
-   * and enabled for beta requests.
+   * Network access policy for the environment. If omitted, the API version
+   * determines whether network access is enabled or disabled.
    */
   network?: TemplateCreateParams.Network | null;
 
@@ -641,8 +641,8 @@ export namespace TemplateCreateParams {
   }
 
   /**
-   * Network access policy for the environment. Defaults to disabled for GA requests
-   * and enabled for beta requests.
+   * Network access policy for the environment. If omitted, the API version
+   * determines whether network access is enabled or disabled.
    */
   export interface Network {
     /**
@@ -716,8 +716,7 @@ export interface TemplateUpdateParams {
 
   /**
    * 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
-   * requests.
+   * policy, or pass `null` to reset to the default policy.
    */
   network?: TemplateUpdateParams.Network | null;
 
@@ -755,8 +754,7 @@ export namespace TemplateUpdateParams {
 
   /**
    * 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
-   * requests.
+   * policy, or pass `null` to reset to the default policy.
    */
   export interface Network {
     /**

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

@@ -22,4 +22,10 @@ export {
 } 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';
+export {
+  Turns,
+  type Turn,
+  type TurnRetrieveParams,
+  type TurnListParams,
+  type TurnsPage,
+} from './turns/index';

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

@@ -3,10 +3,12 @@
 import {
   AgentSessionStream,
   type AgentSessionStreamParams,
+  type AgentToolHandler,
 } from '../../../../lib/agents/agent-session-stream';
 import {
   type AgentSessionCreateStream,
   withAgentTurnResult,
+  captureCreationTools,
 } 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';
@@ -31,10 +33,10 @@ 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 * as TurnsAPI from './turns/turns';
+import { Turn, TurnListParams, TurnRetrieveParams, Turns, TurnsPage } from './turns/turns';
 import { APIPromise } from '../../../../core/api-promise';
 import { CursorPage, type CursorPageParams, PagePromise } from '../../../../core/pagination';
 import type { Stream } from '../../../../core/streaming';
@@ -200,7 +202,8 @@ export class Sessions extends APIResource {
     body: SessionCreateParams,
     options?: RequestOptions,
   ): APIPromise<AgentsAPI.AgentSession> | APIPromise<AgentSessionCreateStream> {
-    const output = captureAgentOutput(body, options);
+    const creation = captureCreationTools(body, options);
+    const output = captureAgentOutput(creation.body, creation.options);
     return this._client
       .post<AgentsAPI.AgentSession | Stream<AgentsAPI.AgentSessionEvent>>(
         '/agents/sessions',
@@ -215,7 +218,13 @@ export class Sessions extends APIResource {
       ._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)
+          ? withAgentTurnResult(
+              data as Stream<AgentsAPI.AgentSessionEvent>,
+              output.format,
+              creation.handlers
+                ? { sessions: this, handlers: creation.handlers, options: output.options }
+                : undefined,
+            )
           : data,
       ) as APIPromise<AgentsAPI.AgentSession> | APIPromise<AgentSessionCreateStream>;
   }
@@ -514,6 +523,7 @@ export namespace SessionCreateParams {
 }
 
 export interface SessionCreateParamsNonStreaming extends SessionCreateParamsBase {
+  toolHandlers?: never;
   /**
    * Whether to stream session events as server-sent events. Defaults to `false`.
    */
@@ -521,6 +531,8 @@ export interface SessionCreateParamsNonStreaming extends SessionCreateParamsBase
 }
 
 export interface SessionCreateParamsStreaming extends SessionCreateParamsBase {
+  /** Beta: local function handlers run during iteration and are never sent to the API. */
+  toolHandlers?: Record<string, AgentToolHandler>;
   /**
    * Whether to stream session events as server-sent events. Defaults to `false`.
    */

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

@@ -1,8 +1,8 @@
 // File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../../../../../core/resource';
-import * as TurnsAPI from '../../turns';
-import { TurnsPage } from '../../turns';
+import * as TurnsAPI from '../../turns/turns';
+import { TurnsPage } from '../../turns/turns';
 import * as ItemsAPI from './items';
 import { ItemListParams, Items } from './items';
 import { APIPromise } from '../../../../../../core/api-promise';

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

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+export { Items, type ItemListParams } from './items';
+export { Turns, type Turn, type TurnRetrieveParams, type TurnListParams, type TurnsPage } from './turns';

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

@@ -0,0 +1,79 @@
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../../../core/resource';
+import * as AgentsAPI from '../../agents';
+import { AgentSessionItemsPage } from '../../agents';
+import {
+  ConversationCursorPage,
+  type ConversationCursorPageParams,
+  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);
+}
+
+export class Items extends APIResource {
+  /**
+   * Lists items belonging to one root-agent turn, including its interactions with
+   * subagents. See
+   * [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability).
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const agentSessionItem of client.beta.agents.sessions.turns.items.list(
+   *   'turn_id',
+   *   { session_id: 'session_id' },
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    turnID: string,
+    params: ItemListParams,
+    options?: RequestOptions,
+  ): PagePromise<AgentSessionItemsConversationCursorPage, AgentsAPI.AgentSessionItem> {
+    const { session_id, ...query } = params;
+    return this._client.getAPIList(
+      path`/agents/sessions/${session_id}/turns/${turnID}/items`,
+      ConversationCursorPage<AgentsAPI.AgentSessionItem>,
+      resolveResourceRequestOptions(options, (options) => ({
+        query,
+        ...options,
+        headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
+        __security: { bearerAuth: true },
+      })),
+    );
+  }
+}
+
+export type AgentSessionItemsConversationCursorPage = ConversationCursorPage<AgentsAPI.AgentSessionItem>;
+
+export interface ItemListParams extends ConversationCursorPageParams {
+  /**
+   * Path param: The ID of the session that owns the turn.
+   */
+  session_id: string;
+
+  /**
+   * Query param: 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 Items {
+  export { type ItemListParams as ItemListParams };
+}
+
+export { type AgentSessionItemsPage };

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

@@ -0,0 +1,383 @@
+// File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../../../core/resource';
+import * as AgentsAPI from '../../agents';
+import * as ItemsAPI from './items';
+import { ItemListParams, Items } from './items';
+import { APIPromise } from '../../../../../core/api-promise';
+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 Turns extends APIResource {
+  items: ItemsAPI.Items = new ItemsAPI.Items(this._client);
+
+  /**
+   * Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if
+   * the turn does not belong to the session. See
+   * [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).
+   *
+   * @example
+   * ```ts
+   * const turn =
+   *   await client.beta.agents.sessions.turns.retrieve(
+   *     'turn_id',
+   *     { session_id: 'session_id' },
+   *   );
+   * ```
+   */
+  retrieve(turnID: string, params: TurnRetrieveParams, options?: RequestOptions): APIPromise<Turn> {
+    const { session_id } = params;
+    return this._client.get(
+      path`/agents/sessions/${session_id}/turns/${turnID}`,
+      resolveResourceRequestOptions(options, (options) => ({
+        ...options,
+        headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
+        __security: { bearerAuth: true },
+      })),
+    );
+  }
+
+  /**
+   * Lists turns by creation time and turn ID. The after cursor is exclusive in the
+   * selected order. See
+   * [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const turn of client.beta.agents.sessions.turns.list(
+   *   'session_id',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    sessionID: string,
+    query?:
+      | (TurnListParams &
+          (
+            | {
+                [
+                  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<TurnsPage, Turn>;
+  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<TurnsPage, Turn>;
+  list(
+    sessionID: string,
+    query:
+      | TurnListParams
+      | ({
+          [
+            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<TurnsPage, Turn> {
+    const normalizeRequestOptionsForQueryOptions = normalizeRequestOptionsForQuery(
+      query,
+      ['after', 'limit', 'order'],
+      options,
+    );
+    if (normalizeRequestOptionsForQueryOptions !== undefined) {
+      options = normalizeRequestOptionsForQueryOptions;
+      query = {};
+    }
+    query = query as TurnListParams | null | undefined;
+    return this._client.getAPIList(
+      path`/agents/sessions/${sessionID}/turns`,
+      CursorPage<Turn>,
+      resolveResourceRequestOptions(options, (options) => ({
+        query,
+        ...options,
+        headers: buildHeaders([{ 'OpenAI-Beta': 'agents=v1' }, options?.headers]),
+        __security: { bearerAuth: true },
+      })),
+    );
+  }
+}
+
+export type TurnsPage = CursorPage<Turn>;
+
+/**
+ * The canonical public representation of a session turn.
+ */
+export interface Turn {
+  /**
+   * The ID of the turn.
+   */
+  id: string;
+
+  /**
+   * The ID of the agent that ran the turn.
+   */
+  agent_id: string;
+
+  /**
+   * The Unix timestamp, in seconds, when the turn reached a terminal state.
+   */
+  completed_at: number | null;
+
+  /**
+   * The Unix timestamp, in seconds, used to order the turn by creation time.
+   * Subagent turns use their start time, falling back to completion time or the
+   * subagent opening time when the preceding timestamps are unavailable.
+   */
+  created_at: number;
+
+  /**
+   * A customer-safe error. Non-null only for a failed turn.
+   */
+  error: AgentsAPI.SessionTurnError | null;
+
+  /**
+   * The object type. Always `agent.session.turn`.
+   */
+  object: 'agent.session.turn';
+
+  /**
+   * The ID of the session that owns the turn.
+   */
+  session_id: string;
+
+  /**
+   * The Unix timestamp, in seconds, when the turn started.
+   */
+  started_at: number | null;
+
+  /**
+   * The current status of the turn.
+   *
+   * - `queued` - The turn is waiting to start.
+   * - `in_progress` - The turn is in progress.
+   * - `waiting` - The turn is waiting for external input.
+   * - `completed` - The turn completed successfully.
+   * - `failed` - The turn failed.
+   * - `cancelled` - The turn was cancelled.
+   */
+  status: 'queued' | 'in_progress' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+
+  /**
+   * The ID of the subagent that ran the turn, if applicable.
+   */
+  subagent_id: string | null;
+
+  /**
+   * Best-effort token usage for the turn, or null if unknown. Recorded usage may
+   * change.
+   */
+  usage: AgentsAPI.TokenUsage | null;
+}
+
+export interface TurnRetrieveParams {
+  /**
+   * The ID of the session that owns the turn.
+   */
+  session_id: string;
+}
+
+export interface TurnListParams 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';
+}
+
+Turns.Items = Items;
+
+export declare namespace Turns {
+  export {
+    type Turn as Turn,
+    type TurnsPage as TurnsPage,
+    type TurnRetrieveParams as TurnRetrieveParams,
+    type TurnListParams as TurnListParams,
+  };
+
+  export { Items as Items, type ItemListParams as ItemListParams };
+}