openai 7.27.0 → 7.30.0

package/src/lib/ResponsesParser.ts

@@ -276,6 +276,14 @@ function getInputToolByName(
       );
     }
   }
+  // Hosted discovery exposes a deferred top-level function under its own name.
+  // A declared namespace above owns that identity, even if it has no matching function.
+  if (namespace === name) {
+    return input_tools.find(
+      (tool): tool is FunctionTool =>
+        tool.type === 'function' && tool.name === name && tool.defer_loading === true,
+    );
+  }
   return undefined;
 }
 

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

@@ -1,16 +1,15 @@
 import type { AgentOutputFormat, AgentResult } from '../beta/agents/output-format-types';
 import { TurnState } from './turn-state';
+import { AgentToolDispatcher } from '../beta/agents/tool-dispatcher';
 import { agentFormatParser, parseAgentResultPromise } from '../beta/agents/parse-result';
 import { ResultCollection } from '../beta/agents/result-collection';
-import { APIUserAbortError, BadRequestError, OpenAIError } from '../../core/error';
+import { APIUserAbortError, 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 { isObj } from '../../internal/utils/values';
-import { isInputContent } from '../beta/agents/tool-output';
+import type { AgentToolError } from '../beta/agents/tool-error';
 import type {
-  AgentFunctionCallItem,
   AgentFunctionCallOutputParam,
   AgentSessionEvent,
   AgentSessionInputMessageParam,
@@ -33,39 +32,16 @@ export type AgentSessionStreamParams<T = never> = {
   input: string | AgentSessionInputMessageParam[];
   /** Registered functions run after their call event is yielded; unknown functions remain manual. */
   toolHandlers?: Record<string, AgentToolHandler>;
+  /**
+   * Beta: use alongside `toolHandlers` to log or monitor local argument validation,
+   * handler execution, and output serialization failures. Does not observe API or
+   * transport errors. Observer errors are ignored; model-visible errors remain sanitized.
+   */
+  onToolError?: (failure: AgentToolError) => void | PromiseLike<void>;
   /** 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 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)),
-  };
-}
-
 async function cancelBody(response: Response | undefined): Promise<void> {
   try {
     await response?.body?.cancel();
@@ -100,7 +76,7 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
   #sessions: Sessions;
   #sessionID: string;
   #input: AgentSessionInputParam.SessionInputParamAgentSessionInputMessage;
-  #handlers: Map<string, AgentToolHandler>;
+  #dispatcher: AgentToolDispatcher;
   #inputKey: string | undefined;
   #options: RequestOptions;
 
@@ -125,7 +101,6 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
     this.#sessions = sessions;
     this.#sessionID = sessionID;
     this.#input = { type: 'agent.session.input.message', input };
-    this.#handlers = new Map(Object.entries(params.toolHandlers ?? {}));
     const headers = buildHeaders([options?.headers]);
     this.#inputKey = headers.nulls.has('idempotency-key')
       ? undefined
@@ -137,9 +112,16 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
     headers.nulls.delete('idempotency-key');
     const { idempotencyKey: _key, ...rest } = options ?? {};
     this.#options = { ...rest, headers };
+    this.#dispatcher = new AgentToolDispatcher(
+      sessions,
+      params.toolHandlers ?? {},
+      this.controller,
+      this.#options,
+      params.onToolError,
+    );
     this.#collection = new ResultCollection(
       () => this.#iterate(),
-      (name) => this.#handlers.has(name),
+      (name) => this.#dispatcher.canHandle(name),
       sessionID,
     );
   }
@@ -216,10 +198,7 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
           continue;
         }
         const terminal = state.terminal(event);
-        const pendingCall = state.call(event);
-        const handler = pendingCall && this.#handlers.get(pendingCall.name);
-        // Freeze dispatch identity and arguments before exposing the original event.
-        const call = pendingCall && handler ? structuredClone(pendingCall) : undefined;
+        const dispatch = this.#dispatcher.prepare(state.call(event), this.#sessionID);
         if (terminal) {
           this.#stream.controller.abort();
         }
@@ -228,12 +207,7 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
           return;
         }
         this.#checkAbort();
-        if (!call || !handler) {
-          continue;
-        }
-        const result = await this.#result(call, handler);
-        this.#checkAbort();
-        await this.#submit(result, options);
+        await dispatch?.();
       }
       this.#checkAbort();
       throw new OpenAIError('Session event stream ended before the turn reached idle or failed');
@@ -244,26 +218,6 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
     }
   }
 
-  async #result(call: AgentFunctionCallItem, handler: AgentToolHandler): Promise<ToolResult> {
-    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');
-      }
-      // SAFETY: Arguments were parsed as JSON and checked to be a non-null non-array object before invoking the handler.
-      return toolResult(call, await this.#wait(() => handler(args as Record<string, unknown>)));
-    } catch {
-      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();
@@ -279,62 +233,4 @@ export class AgentSessionStream<T = never> implements AsyncIterable<AgentSession
     });
     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(result: ToolResult, options: RequestOptions, key = uuid4(), attempt = 0): Promise<void> {
-    this.#checkAbort();
-    try {
-      await this.#sessions.events.create(
-        this.#sessionID,
-        { events: [result], 'Idempotency-Key': key },
-        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(result, options, key, attempt + 1);
-    }
-  }
 }

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 };