openai 7.25.0 → 7.27.0

package/src/internal/responses-ws-credentials.ts

@@ -0,0 +1,160 @@
+import { OpenAIError } from '../core/error';
+import type { OpenAI } from '../client';
+import { resolveRealtimeAPIKey } from './realtime-credentials';
+import {
+  buildWebSocketOptions,
+  mergeWebSocketAuthHeaders,
+  snapshotWebSocketCredentials,
+  WEBSOCKET_METADATA_HEADERS,
+} from './ws';
+import type { CredentialedWebSocketOptions } from './ws';
+
+/**
+ * Keep caller credential admission distinct from the hook's final provider-key transform.
+ * The latter reuses captured base headers so no caller getters are reread after the refresh.
+ */
+function buildResponsesWebSocketOptions<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  prepared?: {
+    options: ReturnType<typeof buildWebSocketOptions>;
+    removedHeaders: Set<string>;
+    apiKey?: string | null | undefined;
+  },
+) {
+  if (prepared) {
+    return prepared.apiKey === undefined
+      ? mergeWebSocketAuthHeaders(prepared.options, authHeaders, prepared.removedHeaders)
+      : buildWebSocketOptions(client, authHeaders, prepared.options, prepared.removedHeaders, true);
+  }
+  if (!client._hasApiKeyProvider()) {
+    return buildWebSocketOptions(client, authHeaders, options);
+  }
+  const removedHeaders = new Set<string>();
+  const provided = buildWebSocketOptions(client, {}, options, removedHeaders);
+  return snapshotWebSocketCredentials(provided, WEBSOCKET_METADATA_HEADERS)
+    ? provided
+    : buildWebSocketOptions(client, authHeaders, provided, removedHeaders, true);
+}
+
+/**
+ * Classify reconnect credentials without treating the previous SDK key as a caller override.
+ * Capture routing and caller options before any asynchronous key refresh.
+ */
+function prepareResponsesWebSocketReconnect<Options extends CredentialedWebSocketOptions>(
+  client: OpenAI,
+  socketOptions: Options | null | undefined,
+  initialAuthUsedAPIKey: boolean,
+) {
+  const removedHeaders = new Set<string>();
+  const options = buildWebSocketOptions(client, {}, socketOptions, removedHeaders);
+  let authentication: 'provided' | 'cached' | 'refresh';
+  if (snapshotWebSocketCredentials(options, WEBSOCKET_METADATA_HEADERS)) {
+    authentication = 'provided';
+  } else if (
+    removedHeaders.has('authorization') ||
+    options.headers?.['authorization'] !== undefined ||
+    !initialAuthUsedAPIKey
+  ) {
+    authentication = 'cached';
+  } else {
+    authentication = 'refresh';
+  }
+  return { options, removedHeaders, authentication };
+}
+
+/** Per-connection Responses credential state shared by the stable and beta Node transports. */
+export class ResponsesWebSocketCredentials {
+  private initialAuthUsedAPIKey = false;
+  private initialAPIKey: string | undefined;
+  private prepared:
+    | {
+        options: ReturnType<typeof buildWebSocketOptions>;
+        removedHeaders: Set<string>;
+        apiKey?: string | null | undefined;
+      }
+    | undefined;
+
+  get preparedAPIKey(): string | null | undefined {
+    return this.prepared?.apiKey;
+  }
+
+  trackInitialHeaders(client: OpenAI, headers: Record<string, string>, hasSocket: () => boolean): void {
+    if (!hasSocket() && client._hasApiKeyProvider()) {
+      this.initialAPIKey = headers['Authorization']?.slice('Bearer '.length);
+    }
+  }
+
+  usesAPIKey(client: OpenAI, headers: Record<string, string>): boolean {
+    // Hooks can read the SDK key without delegating. Only use an ordinary cached property here:
+    // invoking custom/Bedrock getters could validate credentials a caller-owned socket never sends.
+    const apiKey =
+      this.initialAPIKey ??
+      (client._hasApiKeyProvider() ? Object.getOwnPropertyDescriptor(client, 'apiKey')?.value : undefined);
+    if (!apiKey) {
+      return false;
+    }
+    // Metadata containing a copy of a credential does not make it the socket's authentication.
+    return snapshotWebSocketCredentials(
+      {
+        headers: Object.fromEntries(
+          Object.entries(headers).map(([name, value]) => [name, value?.includes(apiKey) ? value : '']),
+        ),
+      },
+      WEBSOCKET_METADATA_HEADERS,
+    );
+  }
+
+  build<Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    authHeaders: Record<string, string>,
+    options: Options | null | undefined,
+    initialAuthUsedAPIKey?: boolean,
+  ) {
+    if (initialAuthUsedAPIKey !== undefined) {
+      this.initialAuthUsedAPIKey = initialAuthUsedAPIKey;
+      this.initialAPIKey = undefined;
+    }
+    const socketOptions = buildResponsesWebSocketOptions(client, authHeaders, options, this.prepared);
+    if (
+      client._hasApiKeyProvider() &&
+      !authHeaders['Authorization'] &&
+      !snapshotWebSocketCredentials(socketOptions, WEBSOCKET_METADATA_HEADERS)
+    ) {
+      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.',
+      );
+    }
+    return socketOptions;
+  }
+
+  async prepare<Socket, Options extends CredentialedWebSocketOptions>(
+    client: OpenAI,
+    socketOptions: Options | null | undefined,
+    authHeaders: (apiKey?: string | null) => Record<string, string>,
+    createSocket: (url: URL, headers: Record<string, string>) => Socket,
+  ): Promise<(url: URL) => Socket> {
+    const { options, removedHeaders, authentication } = prepareResponsesWebSocketReconnect(
+      client,
+      socketOptions,
+      this.initialAuthUsedAPIKey,
+    );
+    const createPreparedSocket = (url: URL, headers: Record<string, string>, apiKey?: string | null) => {
+      const previous = this.prepared;
+      this.prepared = { options, removedHeaders, apiKey };
+      try {
+        // Resolve headers inside the scope so legacy zero-argument overrides see this attempt's key.
+        return createSocket(url, apiKey === undefined ? headers : authHeaders(apiKey));
+      } finally {
+        this.prepared = previous;
+      }
+    };
+    if (authentication !== 'refresh') {
+      const headers = authentication === 'provided' ? {} : authHeaders();
+      return (url) => createPreparedSocket(url, headers);
+    }
+    const { commit } = await resolveRealtimeAPIKey(client, true);
+    return (url) => createPreparedSocket(url, {}, commit());
+  }
+}

package/src/internal/shim-types.ts

@@ -23,3 +23,20 @@ type _ReadableStream<R = any> = NeverToAny<
 >;
 
 export type { _ReadableStream as ReadableStream };
+
+/** @ts-ignore */
+type _DOMWritableStream<R = any> = globalThis.WritableStream<R>;
+
+/** @ts-ignore */
+type _NodeWritableStream<R = any> = import('stream/web').WritableStream<R>;
+
+type _ConditionalNodeWritableStream<R = any> = typeof globalThis extends { WritableStream: any }
+  ? never
+  : _NodeWritableStream<R>;
+
+type _WritableStream<R = any> = NeverToAny<
+  | ([0] extends [1 & _DOMWritableStream<R>] ? never : _DOMWritableStream<R>)
+  | ([0] extends [1 & _ConditionalNodeWritableStream<R>] ? never : _ConditionalNodeWritableStream<R>)
+>;
+
+export type { _WritableStream as WritableStream };

package/src/internal/ws-adapter-node.ts

@@ -1,10 +1,76 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type * as WS from 'ws';
 import type { WebSocketLike } from './ws-adapter';
 import { protectWebSocketOptionsFromCredentialRedirects } from './ws';
+import { setRealtimeAPIKeyCacheContext } from './realtime-credentials';
+import type { DeferredAPIKeyCache } from './realtime-credentials';
+
+setRealtimeAPIKeyCacheContext(new AsyncLocalStorage<DeferredAPIKeyCache | undefined>());
 
 /** A generic event listener callback. */
 type Listener = (...args: any[]) => void;
 
+function copyTLSMaterial(value: string | Buffer): string | Buffer {
+  return ArrayBuffer.isView(value)
+    ? Buffer.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength))
+    : value;
+}
+
+/** Snapshot caller headers and TLS identity before an async reconnect credential refresh. */
+export function snapshotNodeWebSocketOptions(
+  options: WS.ClientOptions | null | undefined,
+): Omit<WS.ClientOptions, 'headers'> & { headers: Record<string, string | string[]> } {
+  const captured = {
+    ...options,
+    headers: Object.fromEntries(
+      Object.entries(options?.headers ?? {}).map(([name, value]) => [
+        name,
+        Array.isArray(value) ? [...value] : value,
+      ]),
+    ),
+  };
+  const { ca, cert, crl, key, pfx } = captured;
+  if (ca !== undefined) {
+    captured.ca = Array.isArray(ca) ? ca.map(copyTLSMaterial) : copyTLSMaterial(ca);
+  }
+  if (cert !== undefined) {
+    captured.cert = Array.isArray(cert) ? cert.map(copyTLSMaterial) : copyTLSMaterial(cert);
+  }
+  if (crl !== undefined) {
+    captured.crl = Array.isArray(crl) ? crl.map(copyTLSMaterial) : copyTLSMaterial(crl);
+  }
+  if (key !== undefined) {
+    captured.key = Array.isArray(key)
+      ? key.map((value) =>
+          typeof value === 'string' || ArrayBuffer.isView(value)
+            ? copyTLSMaterial(value)
+            : { ...value, pem: copyTLSMaterial(value.pem) },
+        )
+      : copyTLSMaterial(key);
+  }
+  if (pfx !== undefined) {
+    captured.pfx = Array.isArray(pfx)
+      ? pfx.map((value) =>
+          typeof value === 'string' || ArrayBuffer.isView(value)
+            ? copyTLSMaterial(value)
+            : { ...value, buf: copyTLSMaterial(value.buf) },
+        )
+      : copyTLSMaterial(pfx);
+  }
+  if ('session' in captured && Buffer.isBuffer(captured.session)) {
+    captured.session = Buffer.from(captured.session);
+  }
+  if ('ALPNProtocols' in captured) {
+    if (Array.isArray(captured.ALPNProtocols)) {
+      captured.ALPNProtocols = [...captured.ALPNProtocols];
+    } else if (ArrayBuffer.isView(captured.ALPNProtocols)) {
+      const { buffer, byteOffset, byteLength } = captured.ALPNProtocols;
+      captured.ALPNProtocols = Buffer.from(new Uint8Array(buffer, byteOffset, byteLength));
+    }
+  }
+  return captured;
+}
+
 /**
  * Adapts a Node.js `ws` socket to the SDK's platform-neutral WebSocket API.
  *

package/src/internal/ws.ts

@@ -1,6 +1,7 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
 import { OpenAIError } from '../core/error';
 import type { WebSocketLike } from './ws-adapter';
+import type { OpenAI } from '../client';
 
 const webSocketErrors = new WeakMap<WebSocketLike, Error>();
 
@@ -73,7 +74,7 @@ export type ReconnectingOverrides<Parameters = Record<string, unknown>> =
  */
 export type RawWebSocketData = string | ArrayBufferLike | ArrayBufferView | ArrayBufferView[];
 
-interface CredentialedWebSocketOptions {
+export interface CredentialedWebSocketOptions {
   auth?: string | null | undefined;
   followRedirects?: boolean | undefined;
   headers?: object | null | undefined;
@@ -99,19 +100,57 @@ const REDIRECT_SAFE_WEBSOCKET_HEADERS = new Set([
   'x-trace-id',
 ]);
 
+const WEBSOCKET_METADATA_HEADER_NAMES = new Set([
+  'accept',
+  'accept-encoding',
+  'accept-language',
+  'content-type',
+  'x-request-id',
+  'x-client-request-id',
+  'x-correlation-id',
+  'traceparent',
+  'tracestate',
+  'sentry-trace',
+  'x-amzn-trace-id',
+  'x-cloud-trace-context',
+  'x-datadog-trace-id',
+  'x-datadog-parent-id',
+  'x-datadog-sampling-priority',
+  'x-datadog-origin',
+  'x-datadog-tags',
+  'baggage',
+  'b3',
+]);
+
+// Request and tracing metadata do not authenticate a Responses socket, but remain protected on redirects.
+export const WEBSOCKET_METADATA_HEADERS = {
+  has: (name: string, values: readonly unknown[]): boolean =>
+    WEBSOCKET_METADATA_HEADER_NAMES.has(name) ||
+    name.startsWith('x-b3-') ||
+    (name === 'sec-websocket-protocol' &&
+      !values.some(
+        (value) =>
+          typeof value === 'string' &&
+          value.split(',').some((protocol) => protocol.trim().startsWith('openai-insecure-api-key.')),
+      )),
+};
+
 function isWebSocketCredentialHeader(name: string): boolean {
   return !REDIRECT_SAFE_WEBSOCKET_HEADERS.has(name.toLowerCase().split('_').join('-'));
 }
 
 /**
  * Snapshots credential values in final socket options before validation and dispatch.
- * Reports potential caller authentication, including custom headers; the server
- * remains responsible for validating credentials. Noncredential headers are left intact.
+ * Reports potential caller authentication, excluding additional metadata when requested.
+ * The server remains responsible for validating credentials. Noncredential headers are left intact.
  */
-export function snapshotWebSocketCredentials(options: {
-  auth?: unknown;
-  headers?: Record<string, unknown> | undefined;
-}): boolean {
+export function snapshotWebSocketCredentials(
+  options: {
+    auth?: unknown;
+    headers?: Record<string, unknown> | undefined;
+  },
+  metadataHeaders?: { has: (name: string, values: readonly unknown[]) => boolean },
+): boolean {
   if (options.auth !== null && options.auth !== undefined) {
     options.auth = String(options.auth);
   }
@@ -135,10 +174,12 @@ export function snapshotWebSocketCredentials(options: {
     }
     headers[name] = snapshot;
     const values = Array.isArray(snapshot) ? snapshot : [snapshot];
-    credentials.set(
-      name.toLowerCase(),
-      values.some((item) => typeof item === 'string' && item.trim().length > 0),
-    );
+    if (!metadataHeaders?.has(normalizedName, values)) {
+      credentials.set(
+        name.toLowerCase(),
+        values.some((item) => typeof item === 'string' && item.trim().length > 0),
+      );
+    }
   }
   // Node applies header names case-insensitively, and Authorization overrides Basic auth.
   return (
@@ -147,6 +188,93 @@ export function snapshotWebSocketCredentials(options: {
   );
 }
 
+/** Merge transport authentication before explicit caller overrides and header removals. */
+export function mergeWebSocketAuthHeaders<Options extends CredentialedWebSocketOptions>(
+  options: Options,
+  authHeaders: Record<string, string>,
+  removedHeaders: ReadonlySet<string>,
+) {
+  const headers = new Map(Object.entries(authHeaders).map(([name, value]) => [name.toLowerCase(), value]));
+  for (const name of removedHeaders) {
+    headers.delete(name);
+  }
+  for (const [name, value] of Object.entries(options.headers ?? {})) {
+    headers.set(name, value);
+  }
+  return { ...options, headers: Object.fromEntries(headers) };
+}
+
+/** Removal sink for one synchronous header-hook call, including legacy one-argument overrides. */
+export const webSocketHeaderRemovals = new WeakMap<
+  OpenAI,
+  { removedHeaders: Set<string> | undefined; baseHeaders: Record<string, string> | undefined }
+>();
+const preparedWebSocketHeaders = new WeakMap<
+  object,
+  { baseHeaders: Record<string, string> | undefined; transportHeaders: Map<string, boolean> }
+>();
+
+/** Build a WebSocket handshake with explicit caller headers applied after the client defaults. */
+export function buildWebSocketOptions<Options extends Pick<CredentialedWebSocketOptions, 'headers'>>(
+  client: OpenAI,
+  authHeaders: Record<string, string>,
+  options: Options | null | undefined,
+  removedHeaders?: Set<string>,
+  usePreparedHeaders = false,
+) {
+  // Capture the base result even through older overrides that forward only one argument.
+  const previous = webSocketHeaderRemovals.get(client);
+  const prepared = usePreparedHeaders && options ? preparedWebSocketHeaders.get(options) : undefined;
+  const context: NonNullable<ReturnType<typeof webSocketHeaderRemovals.get>> = {
+    removedHeaders,
+    baseHeaders: prepared?.baseHeaders,
+  };
+  webSocketHeaderRemovals.set(client, context);
+  let headers: Map<string, string>;
+  try {
+    headers = new Map(
+      Object.entries(client._buildWebSocketHeaders(authHeaders, removedHeaders)).map(([name, value]) => [
+        name.toLowerCase(),
+        value,
+      ]),
+    );
+  } finally {
+    if (previous) {
+      webSocketHeaderRemovals.set(client, previous);
+    } else {
+      webSocketHeaderRemovals.delete(client);
+    }
+  }
+  // The first hook output is not a caller override of the final, credentialed hook.
+  // Save transport names and explicit nulls separately, then reuse their validated values.
+  const transportHeaders = new Map<string, boolean>();
+  const currentHeaders = new Map(Object.entries(options?.headers ?? {}));
+  const overrides = prepared
+    ? [...prepared.transportHeaders].map(
+        ([name, removed]) => [name, removed ? null : currentHeaders.get(name)] as const,
+      )
+    : currentHeaders;
+  for (const [name, value] of overrides) {
+    const normalizedName = name.toLowerCase();
+    if (value === null) {
+      headers.delete(normalizedName);
+      removedHeaders?.add(normalizedName);
+      transportHeaders.set(normalizedName, true);
+    } else if (value !== undefined) {
+      headers.set(normalizedName, value);
+      removedHeaders?.delete(normalizedName);
+      transportHeaders.set(normalizedName, false);
+    }
+  }
+  const result = {
+    ...options,
+    headers: Object.fromEntries(headers),
+    followRedirects: false,
+  };
+  preparedWebSocketHeaders.set(result, { baseHeaders: context.baseHeaders, transportHeaders });
+  return result;
+}
+
 /** Prevents WebSocket redirects from forwarding caller or SDK credentials to another origin. */
 export function protectWebSocketOptionsFromCredentialRedirects<Options extends CredentialedWebSocketOptions>(
   options: Options,

package/src/lib/agents/agent-session-stream.ts

@@ -1,17 +1,20 @@
+import type { AgentOutputFormat, AgentResult } from '../beta/agents/output-format-types';
 import { TurnState } from './turn-state';
+import { agentFormatParser, parseAgentResultPromise } from '../beta/agents/parse-result';
+import { ResultCollection } from '../beta/agents/result-collection';
 import { APIUserAbortError, BadRequestError, OpenAIError } from '../../core/error';
 import type { Stream } from '../../core/streaming';
 import { buildHeaders } from '../../internal/headers';
 import type { RequestOptions } from '../../internal/request-options';
 import { uuid4 } from '../../internal/utils/uuid';
-import { hasOwn, isObj } from '../../internal/utils/values';
+import { isObj } from '../../internal/utils/values';
+import { isInputContent } from '../beta/agents/tool-output';
 import type {
   AgentFunctionCallItem,
   AgentFunctionCallOutputParam,
   AgentSessionEvent,
   AgentSessionInputMessageParam,
   AgentSessionInputParam,
-  InputContentParam,
 } from '../../resources/beta/agents/agents';
 import type { Sessions } from '../../resources/beta/agents/sessions/sessions';
 
@@ -23,33 +26,19 @@ export type AgentToolHandler = (
 ) => AgentToolOutput | PromiseLike<AgentToolOutput>;
 
 /** Input and optional sequential tool handlers for one turn on an idle session. */
-export interface AgentSessionStreamParams {
+export type AgentSessionStreamParams<T = never> = {
+  /** Beta: parse this turn locally; does not change the existing session schema. */
+  outputFormat?: AgentOutputFormat<T>;
   /** User messages, or text normalized to a single user message. Must not be empty. */
   input: string | AgentSessionInputMessageParam[];
   /** Registered functions run after their call event is yielded; unknown functions remain manual. */
   toolHandlers?: Record<string, AgentToolHandler>;
   /** Key for the input submission only; request headers take precedence, case-insensitively. */
   idempotencyKey?: string;
-}
+} & ([T] extends [never] ? unknown : { outputFormat: AgentOutputFormat<T> });
 
 type ToolResult = AgentSessionInputParam.SessionInputParamAgentSessionInputToolResult;
 
-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';
-}
-
 function normalizedOutput(value: unknown): AgentFunctionCallOutputParam | null {
   if (value === null) {
     return null;
@@ -98,10 +87,13 @@ async function cancelBody(response: Response | undefined): Promise<void> {
  * idempotency key. Breaking iteration or calling abort closes local requests;
  * neither cancels the backend turn. No work starts until iteration begins.
  */
-export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
+export class AgentSessionStream<T = never> implements AsyncIterable<AgentSessionEvent> {
   /** Aborts local requests and iteration without cancelling the backend turn. */
   readonly controller = new AbortController();
   #consumed = false;
+  #format: AgentOutputFormat<T> | undefined;
+  #parsedResult: Promise<AgentResult<T>> | undefined;
+  #collection: ResultCollection;
   #stream: Stream<AgentSessionEvent> | undefined;
   #response: Response | undefined;
   #reading = false;
@@ -116,7 +108,7 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
   constructor(
     sessions: Sessions,
     sessionID: string,
-    params: AgentSessionStreamParams,
+    params: AgentSessionStreamParams<T>,
     options?: RequestOptions,
   ) {
     const input: AgentSessionInputMessageParam[] =
@@ -126,6 +118,10 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     if (params.input.length === 0) {
       throw new OpenAIError('input must not be empty');
     }
+    this.#format = agentFormatParser<T>(params.outputFormat);
+    if (params.outputFormat && !this.#format) {
+      throw new OpenAIError('outputFormat must have its own parser function');
+    }
     this.#sessions = sessions;
     this.#sessionID = sessionID;
     this.#input = { type: 'agent.session.input.message', input };
@@ -141,6 +137,11 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     headers.nulls.delete('idempotency-key');
     const { idempotencyKey: _key, ...rest } = options ?? {};
     this.#options = { ...rest, headers };
+    this.#collection = new ResultCollection(
+      () => this.#iterate(),
+      (name) => this.#handlers.has(name),
+      sessionID,
+    );
   }
 
   /** Closes local requests without cancelling the turn; an optional reason becomes the abort error's cause. */
@@ -158,7 +159,18 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
       throw new OpenAIError('An AgentSessionStream can only be consumed once');
     }
     this.#consumed = true;
-    return this.#iterate();
+    return this.#collection.iterate();
+  }
+
+  /** Beta: opt into retaining completed final messages before iterating progress events. */
+  withResultCollection(): this {
+    this.#collection.enable();
+    return this;
+  }
+
+  /** Beta: drain this turn, dispatch registered tools, and collect its final assistant messages. */
+  finalResult(): Promise<AgentResult<T>> {
+    return (this.#parsedResult ??= parseAgentResultPromise(this.#collection.finalResult(), this.#format));
   }
 
   async *#iterate(): AsyncGenerator<AgentSessionEvent> {
@@ -268,7 +280,7 @@ export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
     return error;
   }
 
-  async #wait<T>(action: () => T | PromiseLike<T>): Promise<T> {
+  async #wait<Value>(action: () => Value | PromiseLike<Value>): Promise<Value> {
     let onAbort: (() => void) | undefined;
     // oxlint-disable-next-line promise/avoid-new -- Bridge the caller's AbortSignal while a handler or registration delay is pending.
     const aborted = new Promise<never>((_resolve, reject) => {

package/src/lib/beta/agents/agent-session-create-stream.ts

@@ -0,0 +1,36 @@
+import type { AgentOutputFormat, AgentResult } from './output-format-types';
+import type { Stream } from '../../../core/streaming';
+import type { AgentSessionEvent } from '../../../resources/beta/agents/agents';
+import { parseAgentResultPromise } from './parse-result';
+import { ResultCollection } from './result-collection';
+
+/** Beta: the original creation stream with optional collection of its initial root turn. */
+export type AgentSessionCreateStream<T = never> = Stream<AgentSessionEvent> & {
+  /** Drain through the selected turn's completion and idle event, then return its final messages. */
+  finalResult: () => Promise<AgentResult<T>>;
+  /** Opt into retaining completed final messages before iterating progress events. */
+  withResultCollection: () => AgentSessionCreateStream<T>;
+};
+
+/** Add beta result collection without replacing custom stream instances.
+ * @internal
+ */
+export function withAgentTurnResult<T = never>(
+  stream: Stream<AgentSessionEvent>,
+  format?: AgentOutputFormat<T>,
+): AgentSessionCreateStream<T> {
+  let collection: ResultCollection;
+  stream.__betaTransformIterator((source) => {
+    collection = new ResultCollection(source, undefined, undefined, stream.controller.signal);
+    return () => collection.iterate();
+  });
+  let parsed: Promise<AgentResult<T>> | undefined;
+  const result: AgentSessionCreateStream<T> = Object.assign(stream, {
+    finalResult: () => (parsed ??= parseAgentResultPromise(collection.finalResult(), format)),
+    withResultCollection: (): AgentSessionCreateStream<T> => {
+      collection.enable();
+      return result;
+    },
+  });
+  return result;
+}