openai 7.28.0 → 7.30.0

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

@@ -1,3 +1,10 @@
+import { APIUserAbortError, OpenAIError } from '../../../core/error';
+import { buildHeaders } from '../../../internal/headers';
+import type { RequestOptions } from '../../../internal/request-options';
+import type { Sessions, SessionCreateParams } from '../../../resources/beta/agents/sessions/sessions';
+import type { AgentToolHandler } from '../../agents/agent-session-stream';
+import { TurnState } from '../../agents/turn-state';
+import { AgentToolDispatcher } from './tool-dispatcher';
 import type { AgentOutputFormat, AgentResult } from './output-format-types';
 import type { Stream } from '../../../core/streaming';
 import type { AgentSessionEvent } from '../../../resources/beta/agents/agents';
@@ -12,16 +19,57 @@ export type AgentSessionCreateStream<T = never> = Stream<AgentSessionEvent> & {
   withResultCollection: () => AgentSessionCreateStream<T>;
 };
 
+async function* dispatchCreationTools(
+  source: () => AsyncIterator<AgentSessionEvent>,
+  dispatcher: AgentToolDispatcher,
+  signal: AbortSignal,
+): AsyncGenerator<AgentSessionEvent> {
+  const state = new TurnState();
+  let sessionID: string | undefined;
+  for await (const event of { [Symbol.asyncIterator]: source }) {
+    if (event.type === 'agent.session.created') {
+      sessionID ??= event.session.id;
+    }
+    const dispatch = state.accept(event) ? dispatcher.prepare(state.call(event), sessionID) : undefined;
+    yield event;
+    if (signal.aborted) {
+      return;
+    }
+    try {
+      await dispatch?.();
+    } catch (error) {
+      if (signal.aborted && error instanceof APIUserAbortError) {
+        return;
+      }
+      throw error;
+    }
+  }
+}
+
 /** Add beta result collection without replacing custom stream instances.
  * @internal
  */
 export function withAgentTurnResult<T = never>(
   stream: Stream<AgentSessionEvent>,
   format?: AgentOutputFormat<T>,
+  tools?: {
+    sessions: Sessions;
+    handlers: Record<string, AgentToolHandler>;
+    options?: RequestOptions | undefined;
+  },
 ): AgentSessionCreateStream<T> {
   let collection: ResultCollection;
   stream.__betaTransformIterator((source) => {
-    collection = new ResultCollection(source, undefined, undefined, stream.controller.signal);
+    // A tool result has its own POST endpoint, independent of creation overrides.
+    const { path: _path, method: _method, stream: _stream, ...options } = tools?.options ?? {};
+    const dispatcher =
+      tools && new AgentToolDispatcher(tools.sessions, tools.handlers, stream.controller, options);
+    collection = new ResultCollection(
+      dispatcher ? () => dispatchCreationTools(source, dispatcher, stream.controller.signal) : source,
+      dispatcher ? (name) => dispatcher.canHandle(name) : undefined,
+      undefined,
+      stream.controller.signal,
+    );
     return () => collection.iterate();
   });
   let parsed: Promise<AgentResult<T>> | undefined;
@@ -34,3 +82,41 @@ export function withAgentTurnResult<T = never>(
   });
   return result;
 }
+
+/** Remove local callbacks without changing ordinary creation requests. @internal */
+export function captureCreationTools(body: SessionCreateParams, options?: RequestOptions) {
+  const descriptor = Object.getOwnPropertyDescriptor(body, 'toolHandlers');
+  if (!descriptor) {
+    return { body, options };
+  }
+  const handlers = body.toolHandlers;
+  if (handlers === undefined && 'value' in descriptor) {
+    return { body, options };
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(body);
+  delete descriptors.toolHandlers;
+  const capturedOptions = { ...options };
+  if ('toJSON' in body || capturedOptions.body !== undefined) {
+    throw new OpenAIError('Creation tool handlers cannot customize request body serialization');
+  }
+  if (handlers === undefined) {
+    // SAFETY: Preserve request fields while removing the accessor so serialization cannot evaluate it again.
+    return {
+      body: Object.create(Object.getPrototypeOf(body), descriptors) as SessionCreateParams,
+      options: capturedOptions,
+    };
+  }
+  const { stream } = body;
+  if (stream !== true) {
+    throw new OpenAIError('toolHandlers requires stream: true');
+  }
+  capturedOptions.headers = buildHeaders([capturedOptions.headers]);
+  descriptors.stream = { value: stream, enumerable: true, configurable: true, writable: true };
+  // SAFETY: Preserve request fields, omitting callbacks and fixing the validated streaming mode.
+  const request = Object.create(Object.getPrototypeOf(body), descriptors) as SessionCreateParams;
+  return {
+    body: request,
+    options: capturedOptions,
+    handlers: handlers && Object.fromEntries(Object.entries(handlers)),
+  };
+}

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

@@ -3,6 +3,8 @@ import type { AgentToolHandler } from '../../agents/agent-session-stream';
 import type { AutoParseableResponseTool } from '../../ResponsesParser';
 import type { AgentToolParam } from '../../../resources/beta/agents/agents';
 import { isInputContent } from './tool-output';
+import { toolStages } from './tool-stages';
+import type { StagedToolHandler } from './tool-stages';
 
 /** A beta Agents function definition paired with its local, validating handler. */
 export interface AgentFunctionTool {
@@ -32,6 +34,26 @@ export function functionTool<Arguments>(
   if (!execute || !tool.parameters) {
     throw new OpenAIError('Agents function tools require a callback and argument schema');
   }
+  const handler: StagedToolHandler = async (arguments_, setStage) => {
+    setStage?.('arguments');
+    const parsed = parse(JSON.stringify(arguments_));
+    setStage?.('execution');
+    const result: unknown = await execute(parsed);
+    setStage?.('output');
+    if (Array.isArray(result)) {
+      return result.length > 0 && result.every(isInputContent) ? result : JSON.stringify(result);
+    }
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Existing schema-tool callbacks return arbitrary application values; adapt them to the Agents dispatcher's output contract.
+    if (typeof result === 'object' || typeof result === 'string') {
+      return result;
+    }
+    const text = result === undefined ? 'undefined' : JSON.stringify(result);
+    if (text === undefined) {
+      throw new OpenAIError('Tool output must be JSON serializable');
+    }
+    return text;
+  };
+  Object.defineProperty(handler, toolStages, { value: true });
   return {
     name: tool.name,
     definition: {
@@ -41,20 +63,6 @@ export function functionTool<Arguments>(
       parameters: tool.parameters,
       ...(tool.defer_loading === undefined ? {} : { defer_loading: tool.defer_loading }),
     },
-    handler: async (arguments_) => {
-      const result: unknown = await execute(parse(JSON.stringify(arguments_)));
-      if (Array.isArray(result)) {
-        return result.length > 0 && result.every(isInputContent) ? result : JSON.stringify(result);
-      }
-      // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Existing schema-tool callbacks return arbitrary application values; adapt them to the Agents dispatcher's output contract.
-      if (typeof result === 'object' || typeof result === 'string') {
-        return result;
-      }
-      const text = result === undefined ? 'undefined' : JSON.stringify(result);
-      if (text === undefined) {
-        throw new OpenAIError('Tool output must be JSON serializable');
-      }
-      return text;
-    },
+    handler,
   };
 }

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

@@ -0,0 +1,226 @@
+import { APIUserAbortError, BadRequestError, OpenAIError } from '../../../core/error';
+import { buildHeaders } from '../../../internal/headers';
+import type { RequestOptions } from '../../../internal/request-options';
+import { uuid4 } from '../../../internal/utils/uuid';
+import { isObj } from '../../../internal/utils/values';
+import { isInputContent } from './tool-output';
+import type { AgentToolError } from './tool-error';
+import { toolStages } from './tool-stages';
+import type { StagedToolHandler } from './tool-stages';
+import type {
+  AgentToolHandler,
+  AgentToolOutput,
+  AgentSessionStreamParams,
+} from '../../agents/agent-session-stream';
+import type {
+  AgentFunctionCallItem,
+  AgentFunctionCallOutputParam,
+  AgentSessionInputParam,
+} from '../../../resources/beta/agents/agents';
+import type { Sessions } from '../../../resources/beta/agents/sessions/sessions';
+
+type ToolResult = AgentSessionInputParam.SessionInputParamAgentSessionInputToolResult;
+
+function normalizedOutput(value: unknown): AgentFunctionCallOutputParam | null {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === 'string' || (Array.isArray(value) && value.every(isInputContent))) {
+    return value;
+  }
+  throw new OpenAIError('Tool output must be text, content, a JSON object, or null');
+}
+
+// oxlint-disable-next-line anti-slop/no-object-parameters -- The public AgentToolOutput contract accepts arbitrary JSON-serializable object results.
+function toolResult(call: AgentFunctionCallItem, value: AgentToolOutput): ToolResult {
+  const output = isObj(value) ? JSON.stringify(value) : value;
+  // Detect unserializable callback results inside the redacted failure boundary.
+  const serialized = JSON.stringify(output);
+  if (serialized === undefined) {
+    throw new OpenAIError('Tool output must be JSON serializable');
+  }
+  return {
+    type: 'agent.session.input.tool_result',
+    turn_id: call.turn_id,
+    call_id: call.call_id,
+    success: true,
+    output: normalizedOutput(typeof output === 'string' ? output : JSON.parse(serialized)),
+  };
+}
+
+/** Shared local function dispatch for creation and follow-up streams. @internal */
+export class AgentToolDispatcher {
+  readonly #handlers: Map<string, AgentToolHandler>;
+  readonly #options: RequestOptions;
+  readonly #sessions: Sessions;
+  readonly #controller: AbortController;
+  readonly #onToolError: AgentSessionStreamParams['onToolError'];
+
+  constructor(
+    sessions: Sessions,
+    handlers: Record<string, AgentToolHandler>,
+    controller: AbortController,
+    options?: RequestOptions,
+    onToolError?: AgentSessionStreamParams['onToolError'],
+  ) {
+    this.#sessions = sessions;
+    this.#controller = controller;
+    this.#onToolError = onToolError;
+    this.#handlers = new Map(Object.entries(handlers));
+    const headers = buildHeaders([options?.headers]);
+    headers.values.delete('idempotency-key');
+    headers.nulls.delete('idempotency-key');
+    const { idempotencyKey: _key, ...rest } = options ?? {};
+    this.#options = { ...rest, headers, signal: controller.signal };
+  }
+
+  canHandle(name: string): boolean {
+    return typeof this.#handlers.get(name) === 'function';
+  }
+
+  /** Capture routing and arguments before the caller can mutate the yielded event. */
+  prepare(
+    call: AgentFunctionCallItem | undefined,
+    sessionID: string | undefined,
+  ): (() => Promise<void>) | undefined {
+    const handler = call && this.#handlers.get(call.name);
+    if (!call || typeof handler !== 'function') {
+      return;
+    }
+    if (!sessionID) {
+      throw new OpenAIError('Tool call received before the session creation event');
+    }
+    const snapshot = structuredClone(call);
+    return async () => {
+      this.#checkAbort();
+      const result = await this.#result(snapshot, handler, sessionID);
+      this.#checkAbort();
+      await this.#submit(sessionID, result);
+    };
+  }
+
+  async #result(
+    call: AgentFunctionCallItem,
+    handler: StagedToolHandler,
+    sessionID: string,
+  ): Promise<ToolResult> {
+    let stage: AgentToolError['stage'] = 'arguments';
+    try {
+      const args: unknown = typeof call.arguments === 'string' ? JSON.parse(call.arguments) : call.arguments;
+      if (!isObj(args)) {
+        throw new OpenAIError('Function arguments must be a JSON object');
+      }
+      stage = 'execution';
+      // SAFETY: Arguments were parsed as JSON and checked to be a non-null non-array object before invoking the handler.
+      const arguments_ = args as Record<string, unknown>;
+      const output = await this.#wait(() =>
+        this.#onToolError && handler[toolStages]
+          ? handler(arguments_, (value) => {
+              stage = value;
+            })
+          : handler(arguments_),
+      );
+      stage = 'output';
+      return toolResult(call, output);
+    } catch (error) {
+      this.#checkAbort();
+      if (this.#onToolError) {
+        const failure: AgentToolError = Object.freeze({
+          error,
+          stage,
+          tool_name: call.name,
+          session_id: sessionID,
+          turn_id: call.turn_id,
+          call_id: call.call_id,
+        });
+        try {
+          await this.#wait(() => this.#onToolError?.(failure));
+        } catch {
+          // Observers must not prevent the original sanitized tool failure from being submitted.
+          this.#checkAbort();
+        }
+      }
+      return {
+        type: 'agent.session.input.tool_result',
+        turn_id: call.turn_id,
+        call_id: call.call_id,
+        success: false,
+        error: 'Tool handler failed.',
+      };
+    }
+  }
+
+  #checkAbort(): void {
+    if (this.#controller.signal.aborted) {
+      throw this.#abortError();
+    }
+  }
+
+  #abortError(): APIUserAbortError {
+    const error = new APIUserAbortError();
+    Object.defineProperty(error, 'cause', {
+      value: this.#controller.signal.reason,
+      writable: true,
+      configurable: true,
+    });
+    return error;
+  }
+
+  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) => {
+      onAbort = () => reject(this.#abortError());
+      this.#controller.signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+      this.#checkAbort();
+      // Capture synchronous throws before racing cancellation, so both promises
+      // always have rejection handlers even if the callback aborts and throws.
+      const invoke = async () => await action();
+      return await Promise.race([invoke(), aborted]);
+    } finally {
+      if (onAbort) {
+        this.#controller.signal.removeEventListener('abort', onAbort);
+      }
+    }
+  }
+
+  async #submit(sessionID: string, result: ToolResult, key = uuid4(), attempt = 0): Promise<void> {
+    this.#checkAbort();
+    try {
+      await this.#sessions.events.create(
+        sessionID,
+        { events: [result], 'Idempotency-Key': key },
+        this.#options,
+      );
+    } catch (error) {
+      const delay = [100, 300, 600][attempt];
+      if (
+        delay === undefined ||
+        !(error instanceof BadRequestError) ||
+        error.code !== 'invalid_request_error' ||
+        !error.error ||
+        !('message' in error.error) ||
+        error.error.message !== `Unknown pending tool call: ${result.call_id}`
+      ) {
+        throw error;
+      }
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await this.#wait(
+          () =>
+            // oxlint-disable-next-line promise/avoid-new -- Own the registration timer so cancellation clears it promptly.
+            new Promise<void>((resolve) => {
+              timer = setTimeout(resolve, delay);
+            }),
+        );
+      } finally {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+        }
+      }
+      await this.#submit(sessionID, result, key, attempt + 1);
+    }
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Beta diagnostic for logging or monitoring failures from local `toolHandlers`.
+ * The original error is local only; API and transport failures propagate separately.
+ */
+export interface AgentToolError {
+  readonly error: unknown;
+  readonly tool_name: string;
+  readonly session_id: string;
+  readonly turn_id: string;
+  readonly call_id: string;
+  readonly stage: 'arguments' | 'execution' | 'output';
+}

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

@@ -0,0 +1,14 @@
+import type { AgentToolHandler } from '../../agents/agent-session-stream';
+import type { AgentToolError } from './tool-error';
+
+/** @internal */
+export const toolStages = Symbol.for('openai.beta.agents.toolStages');
+
+/**
+ * Marks handlers that accept stage updates, including across ESM/CJS imports.
+ * @internal
+ */
+export type StagedToolHandler = ((
+  arguments_: Parameters<AgentToolHandler>[0],
+  setStage?: (stage: AgentToolError['stage']) => void,
+) => ReturnType<AgentToolHandler>) & { [toolStages]?: true };

package/src/lib/chat-completions/streaming.ts

@@ -0,0 +1,35 @@
+import type { Stream } from '../../core/streaming';
+import type { ChatCompletionChunk } from '../../resources/chat/completions/completions';
+
+/** Wire chunks can omit the finish reason, including the final audio expiry update. */
+export type ChatCompletionWireChunk = Omit<ChatCompletionChunk, 'choices'> & {
+  choices: (Omit<ChatCompletionChunk.Choice, 'finish_reason'> & {
+    finish_reason?: ChatCompletionChunk.Choice['finish_reason'];
+  })[];
+};
+
+export function normalizeChatCompletionChunk(chunk: ChatCompletionWireChunk): ChatCompletionChunk {
+  if (!Array.isArray(chunk?.choices)) {
+    // SAFETY: This is an opaque provider record, with no choices to normalize.
+    // Preserve the existing SSE pass-through; the SDK does not validate these records.
+    return chunk as ChatCompletionChunk;
+  }
+  return {
+    ...chunk,
+    choices: chunk.choices.map((choice) => ({ ...choice, finish_reason: choice.finish_reason ?? null })),
+  };
+}
+
+export function normalizeChatCompletionStream(
+  stream: Stream<ChatCompletionWireChunk>,
+): Stream<ChatCompletionChunk> {
+  const iterator = stream[Symbol.asyncIterator].bind(stream);
+  stream[Symbol.asyncIterator] = async function* normalizedChunks() {
+    const source = { [Symbol.asyncIterator]: iterator };
+    for await (const chunk of source) {
+      yield normalizeChatCompletionChunk(chunk);
+    }
+  };
+  // SAFETY: The installed iterator normalizes every wire chunk before exposing it.
+  return stream as Stream<ChatCompletionChunk>;
+}