agents 0.11.9 → 0.12.1

package/dist/{index-DSwOzhhd.d.ts → agent-tool-types-CB7nISDE.d.ts}

@@ -16,6 +16,7 @@ import {
 } from "./workflow-types-DHs0L0KP.js";
 import { t as MessageType } from "./types-DAHCZC_W.js";
 import { r as EmailResolver } from "./email-X72-zjuq.js";
+import { ToolSet, UIMessage } from "ai";
 import { RpcTarget } from "cloudflare:workers";
 import {
   Connection,
@@ -24,7 +25,8 @@ import {
   ConnectionContext as ConnectionContext$1,
   PartyServerOptions,
   Server,
-  WSMessage
+  WSMessage,
+  WSMessage as WSMessage$1
 } from "partyserver";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
@@ -54,9 +56,8 @@ import {
   Resource,
   ResourceTemplate,
   ServerCapabilities,
-  Tool
+  Tool as Tool$1
 } from "@modelcontextprotocol/sdk/types.js";
-import { ToolSet } from "ai";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
@@ -615,7 +616,7 @@ declare class MCPClientConnection {
   connectionError: string | null;
   lastConnectedTransport: BaseTransportType | undefined;
   instructions?: string;
-  tools: Tool[];
+  tools: Tool$1[];
   private _transport?;
   prompts: Prompt[];
   resources: Resource[];
@@ -675,7 +676,7 @@ declare class MCPClientConnection {
    * Notification handler registration for tools
    * Should only be called if serverCapabilities.tools exists
    */
-  registerTools(): Promise<Tool[]>;
+  registerTools(): Promise<Tool$1[]>;
   /**
    * Notification handler registration for resources
    * Should only be called if serverCapabilities.resources exists
@@ -1517,7 +1518,7 @@ declare class MCPClientManager {
   }>;
 }
 type NamespacedData = {
-  tools: (Tool & {
+  tools: (Tool$1 & {
     serverId: string;
   })[];
   prompts: (Prompt & {
@@ -1647,6 +1648,54 @@ declare class SqlError extends Error {
   readonly query: string;
   constructor(query: string, cause: unknown);
 }
+type SubAgentConnectionMeta = {
+  id: string;
+  uri: string | null;
+  tags: string[];
+  state: unknown;
+  requestHeaders?: [string, string][];
+};
+type SubAgentConnectionBridgeLike = {
+  send(message: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  setState(state: unknown): unknown;
+  broadcast(
+    ownerPath: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+};
+declare class SubAgentConnectionBridge
+  extends RpcTarget
+  implements SubAgentConnectionBridgeLike
+{
+  #private;
+  constructor(
+    connection: Connection,
+    broadcast?: (
+      ownerPath: ReadonlyArray<{
+        className: string;
+        name: string;
+      }>,
+      message: string | ArrayBuffer | ArrayBufferView,
+      without?: string[]
+    ) => void
+  );
+  send(message: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  setState(state: unknown): unknown;
+  broadcast(
+    ownerPath: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+}
 /**
  * Constructor type for a sub-agent class.
  * Used by {@link Agent.subAgent} to reference the child class
@@ -1737,6 +1786,34 @@ type Schedule<T = string> = {
       intervalSeconds: number;
     }
 );
+type AgentPathStep = {
+  className: string;
+  name: string;
+};
+type ScheduleStorageRow = {
+  id: string;
+  callback: string;
+  payload: string;
+  type: "scheduled" | "delayed" | "cron" | "interval";
+  time: number;
+  delayInSeconds?: number;
+  cron?: string;
+  intervalSeconds?: number;
+  retry?: RetryOptions;
+  running?: number;
+  execution_started_at?: number | null;
+  retry_options?: string | null;
+  owner_path?: string | null;
+  owner_path_key?: string | null;
+};
+type ScheduleCriteria = {
+  id?: string;
+  type?: "scheduled" | "delayed" | "cron" | "interval";
+  timeRange?: {
+    start?: Date;
+    end?: Date;
+  };
+};
 /**
  * Context passed to the `runFiber` callback. Provides checkpoint
  * and identity for durable execution.
@@ -1774,7 +1851,7 @@ type MCPServersState = {
   servers: {
     [id: string]: MCPServer;
   };
-  tools: (Tool & {
+  tools: (Tool$1 & {
     serverId: string;
   })[];
   prompts: (Prompt & {
@@ -1912,6 +1989,15 @@ declare class Agent<
   private _persistenceHookMode;
   /** True when this agent runs as a facet (sub-agent) inside a parent. */
   private _isFacet;
+  /**
+   * True only while the internal facet bootstrap RPC runs startup.
+   * Startup may happen while the parent is handling a WebSocket
+   * message, so protocol broadcasts must not touch any ambient
+   * parent-owned WebSocket handles during this window.
+   */
+  private _suppressProtocolBroadcasts;
+  private _cf_currentSubAgentBridge?;
+  private _cf_virtualSubAgentConnections;
   /**
    * Ancestor chain, root-first. Empty for top-level DOs; populated at
    * facet init time from the parent's own `selfPath`. Exposed publicly
@@ -1931,6 +2017,13 @@ declare class Agent<
    * @internal
    */
   _keepAliveRefs: number;
+  /**
+   * In-memory tokens for keepAlive leases acquired by facets and held
+   * on the root alarm owner. Lost on eviction, like `_keepAliveRefs`,
+   * because the in-memory work those leases were protecting is also gone.
+   * @internal
+   */
+  private _facetKeepAliveTokens;
   /** @internal In-memory set of fiber IDs running in this process. */
   private _runFiberActiveFibers;
   /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
@@ -2301,6 +2394,152 @@ declare class Agent<
    * @returns Array of matching QueueItem objects
    */
   getQueues(key: string, value: string): QueueItem<string>[];
+  private _scheduleOwnerPathKey;
+  private _facetRunRowsForPrefix;
+  private _deleteFacetRunRowsForPrefix;
+  private _rootAlarmOwner;
+  private _validateScheduleCallback;
+  /**
+   * Insert (or, for idempotent calls, return the existing row for) a
+   * schedule owned by either this top-level agent (`ownerPath === null`)
+   * or a descendant facet. Returns `{ schedule, created }` — `created`
+   * is `false` when an idempotent insert deduplicates onto an existing
+   * row, so callers can suppress the `schedule:create` event in that
+   * case to match historic semantics.
+   * @internal
+   */
+  private _insertScheduleForOwner;
+  /**
+   * Insert a schedule row owned by a descendant facet. Called via RPC
+   * from the facet's `schedule()`. Returns `{ schedule, created }`
+   * so the originating facet can suppress `schedule:create` on
+   * idempotent dedup. This method does not emit observability
+   * events itself.
+   * @internal
+   */
+  _cf_scheduleForFacet<T = string>(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    when: Date | string | number,
+    callback: string,
+    payload?: T,
+    options?: {
+      retry?: RetryOptions;
+      idempotent?: boolean;
+    }
+  ): Promise<{
+    schedule: Schedule<T>;
+    created: boolean;
+  }>;
+  /**
+   * Insert (or, for idempotent calls, return the existing row for) an
+   * interval schedule. Mirrors {@link _insertScheduleForOwner} —
+   * returns `{ schedule, created }` so callers can suppress
+   * `schedule:create` on dedup.
+   * @internal
+   */
+  private _insertIntervalScheduleForOwner;
+  /**
+   * Insert an interval schedule row owned by a descendant facet.
+   * Called via RPC from the facet's `scheduleEvery()`. Returns
+   * `{ schedule, created }` so the originating facet can suppress
+   * `schedule:create` on idempotent dedup. This method does not
+   * emit observability events itself.
+   * @internal
+   */
+  _cf_scheduleEveryForFacet<T = string>(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    intervalSeconds: number,
+    callback: string,
+    payload?: T,
+    options?: {
+      retry?: RetryOptions;
+      _idempotent?: boolean;
+    }
+  ): Promise<{
+    schedule: Schedule<T>;
+    created: boolean;
+  }>;
+  /**
+   * Cancel a schedule row owned by a descendant facet, scoped by
+   * `owner_path_key` so siblings can't reach each other's rows.
+   * Returns the canceled row's callback name so the originating
+   * facet can emit `schedule:cancel`. This method does not emit
+   * observability events itself.
+   * @internal
+   */
+  _cf_cancelScheduleForFacet(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    id: string
+  ): Promise<{
+    ok: boolean;
+    callback?: string;
+  }>;
+  /**
+   * Clean root-owned bookkeeping for a sub-tree of facets. This
+   * bulk-cancels schedules whose `owner_path` starts with the given
+   * prefix and deletes root-side facet fiber recovery leases for the
+   * same sub-tree. Used by `deleteSubAgent` and recursive facet
+   * destroy. Emits `schedule:cancel` on this agent (the alarm-owning
+   * root) for each schedule row removed — the facets being torn down
+   * may not be alive to receive the events themselves.
+   * @internal
+   */
+  _cf_cleanupFacetPrefix(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<void>;
+  private _scheduleRowToSchedule;
+  private _getScheduleForOwner;
+  private _listSchedulesForOwner;
+  /**
+   * Read a single schedule row owned by a descendant facet.
+   * @internal
+   */
+  _cf_getScheduleForFacet(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    id: string
+  ): Promise<Schedule<unknown> | undefined>;
+  /**
+   * List schedule rows owned by a descendant facet, scoped by
+   * `owner_path_key` so siblings remain isolated from each other.
+   * @internal
+   */
+  _cf_listSchedulesForFacet(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    criteria?: ScheduleCriteria
+  ): Promise<Schedule<unknown>[]>;
+  /**
+   * Acquire a root-owned keepAlive ref on behalf of a descendant facet.
+   * Facets share the root isolate but cannot set their own physical
+   * alarm, so this lets facet work use the root alarm heartbeat.
+   * @internal
+   */
+  _cf_acquireFacetKeepAlive(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<string>;
+  /**
+   * Release a root-owned keepAlive ref previously acquired for a facet.
+   * Idempotent so disposer calls can safely race or run twice.
+   * @internal
+   */
+  _cf_releaseFacetKeepAlive(token: string): Promise<void>;
+  /**
+   * Register a facet's durable run row in the root-side index so root
+   * alarm housekeeping can dispatch recovery checks into idle facets.
+   * The facet remains authoritative for snapshots and recovery hooks.
+   * @internal
+   */
+  _cf_registerFacetRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
+  /**
+   * Remove a completed facet fiber from the root-side index.
+   * @internal
+   */
+  _cf_unregisterFacetRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
   /**
    * Schedule a task to be executed in the future
    *
@@ -2372,24 +2611,52 @@ declare class Agent<
    * @template T Type of the payload data
    * @param id ID of the scheduled task
    * @returns The Schedule object or undefined if not found
+   * @deprecated Use {@link getScheduleById}. This synchronous API cannot cross
+   * Durable Object boundaries and throws inside sub-agents.
    */
   getSchedule<T = string>(id: string): Schedule<T> | undefined;
+  /**
+   * Get a scheduled task by ID.
+   *
+   * Unlike the deprecated synchronous {@link getSchedule}, this works inside
+   * sub-agents by delegating to the top-level parent that owns the alarm.
+   *
+   * @template T Type of the payload data
+   * @param id ID of the scheduled task
+   * @returns The Schedule object or undefined if not found
+   */
+  getScheduleById(id: string): Promise<Schedule<unknown> | undefined>;
   /**
    * Get scheduled tasks matching the given criteria
    * @template T Type of the payload data
    * @param criteria Criteria to filter schedules
    * @returns Array of matching Schedule objects
+   * @deprecated Use {@link listSchedules}. This synchronous API cannot cross
+   * Durable Object boundaries and throws inside sub-agents.
    */
-  getSchedules<T = string>(criteria?: {
-    id?: string;
-    type?: "scheduled" | "delayed" | "cron" | "interval";
-    timeRange?: {
-      start?: Date;
-      end?: Date;
-    };
-  }): Schedule<T>[];
+  getSchedules<T = string>(criteria?: ScheduleCriteria): Schedule<T>[];
+  /**
+   * List scheduled tasks matching the given criteria.
+   *
+   * Unlike the deprecated synchronous {@link getSchedules}, this works inside
+   * sub-agents by delegating to the top-level parent that owns the alarm.
+   *
+   * @template T Type of the payload data
+   * @param criteria Criteria to filter schedules
+   * @returns Array of matching Schedule objects
+   */
+  listSchedules(criteria?: ScheduleCriteria): Promise<Schedule<unknown>[]>;
   /**
-   * Cancel a scheduled task
+   * Cancel a scheduled task.
+   *
+   * Schedules are isolated by owner: a top-level agent's
+   * `cancelSchedule(id)` only matches its own schedules, and a
+   * sub-agent's `cancelSchedule(id)` only matches schedules it
+   * created. To clear every schedule under a sub-agent (and its
+   * descendants), call `parent.deleteSubAgent(Cls, name)` from the
+   * parent — that bulk-cleans root-owned bookkeeping via
+   * {@link _cf_cleanupFacetPrefix}.
+   *
    * @param id ID of the task to cancel
    * @returns true if the task was cancelled, false if the task was not found
    */
@@ -2404,11 +2671,8 @@ declare class Agent<
    * alarm system, without creating schedule rows or emitting observability
    * events. Configure via `static options = { keepAliveIntervalMs: 5000 }`.
    *
-   * No-op on facets. Facets share the parent's isolate and don't
-   * need a separate alarm heartbeat — the parent's own activity,
-   * any open WebSocket to the facet, and any in-flight Promise
-   * already keep the shared machine alive for the duration of
-   * real work.
+   * In facets, delegates the physical heartbeat to the root parent
+   * because facets do not have independent alarm slots.
    *
    * @example
    * ```ts
@@ -2482,6 +2746,55 @@ declare class Agent<
   private _checkRunFibers;
   /** @internal */
   _onAlarmHousekeeping(): Promise<void>;
+  private _isSameAgentPathPrefix;
+  /**
+   * Root-side scan for durable fibers owned by descendant facets.
+   * `cf_agents_facet_runs` is only an index; actual snapshots and
+   * recovery hooks live in each facet's own `cf_agents_runs` table.
+   * @internal
+   */
+  private _checkFacetRunFibers;
+  /**
+   * Dispatch a runFiber recovery check into the facet identified by
+   * `ownerPath`. Returns the number of remaining local `cf_agents_runs`
+   * rows on the target facet after recovery.
+   * @internal
+   */
+  _cf_checkRunFibersForFacet(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<number>;
+  /**
+   * Dispatch a scheduled callback into the facet identified by
+   * `ownerPath`. Walks one step at a time: if `ownerPath` matches
+   * `selfPath`, executes the callback locally; otherwise resolves
+   * the next descendant facet and recurses through its own RPC.
+   *
+   * Called by the root's `alarm()` (which owns the physical alarm
+   * for facet-owned schedules) and by intermediate facets while
+   * walking down the chain.
+   * @internal
+   */
+  _cf_dispatchScheduledCallback(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    row: ScheduleStorageRow
+  ): Promise<void>;
+  /**
+   * Recursively destroy a descendant facet identified by
+   * `targetPath`. Walks down from `selfPath` until reaching the
+   * target's immediate parent, where it cancels the target's
+   * parent-owned schedules (and any descendants), removes the
+   * target from the registry, and calls `ctx.facets.delete` to
+   * wipe the target's storage.
+   *
+   * Called by a facet's own `destroy()` (via the root) so that
+   * `this.destroy()` inside a sub-agent results in the same
+   * cleanup as `parent.deleteSubAgent(Cls, name)` from the parent.
+   * @internal
+   */
+  _cf_destroyDescendantFacet(
+    targetPath: ReadonlyArray<AgentPathStep>
+  ): Promise<void>;
+  private _executeScheduleCallback;
   private _scheduleNextAlarm;
   /**
    * Override PartyServer's onAlarm hook as a no-op.
@@ -2520,6 +2833,76 @@ declare class Agent<
    * @experimental The API surface may change before stabilizing.
    */
   fetch(request: Request): Promise<Response>;
+  broadcast(
+    msg: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void;
+  getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
+  getConnections<TState = unknown>(tag?: string): Iterable<Connection<TState>>;
+  private _cf_broadcastToParentSubAgent;
+  _cf_broadcastToSubAgent(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  _cf_subAgentConnectionMetas(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<SubAgentConnectionMeta[]>;
+  _cf_sendToSubAgentConnection(
+    connectionId: string,
+    message: string | ArrayBuffer | ArrayBufferView
+  ): Promise<void>;
+  _cf_closeSubAgentConnection(
+    connectionId: string,
+    code?: number,
+    reason?: string
+  ): Promise<void>;
+  _cf_setSubAgentConnectionState(
+    connectionId: string,
+    state: unknown
+  ): Promise<unknown>;
+  private _cf_subAgentConnectionMetaForPath;
+  private _cf_subAgentTargetPath;
+  private _cf_subAgentPathFromOuterUri;
+  private _isSameAgentPath;
+  private _cf_connectionHasSubAgentTarget;
+  protected _cf_connectionTargetsSubAgent(connection: Connection): boolean;
+  /**
+   * Returns true when the current request is addressed to a child facet of
+   * this agent rather than to this agent itself.
+   *
+   * Chat-style subclasses wrap `onConnect` before the base Agent forwarding
+   * wrapper runs, so they need a request-level check to avoid sending their
+   * own protocol frames on sockets that are about to be forwarded to a child.
+   */
+  protected _cf_requestTargetsSubAgent(request: Request): boolean;
+  private _cf_forwardSubAgentWebSocketConnect;
+  private _cf_createSubAgentConnectionBridge;
+  private _cf_forwardSubAgentWebSocketMessage;
+  private _cf_forwardSubAgentWebSocketClose;
+  private _cf_resolveSubAgentConnection;
+  _cf_handleSubAgentWebSocketConnect(
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  _cf_handleSubAgentWebSocketMessage(
+    message: WSMessage,
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  _cf_handleSubAgentWebSocketClose(
+    code: number,
+    reason: string,
+    wasClean: boolean,
+    bridge: SubAgentConnectionBridge,
+    meta: SubAgentConnectionMeta
+  ): Promise<void>;
+  private _cf_runWithSubAgentBridge;
+  private _cf_createSubAgentBridgeConnection;
+  private _cf_storeVirtualSubAgentConnection;
+  protected _cf_hydrateSubAgentConnectionsFromRoot(): Promise<void>;
+  private _cf_getRawConnectionState;
+  private _cf_getForwardedSubAgentState;
   /**
    * Parent-side middleware hook. Fires before a request is
    * forwarded into a facet sub-agent. Mirrors `onBeforeConnect` /
@@ -2602,10 +2985,10 @@ declare class Agent<
    * We set `_isFacet` eagerly (before `__unsafe_ensureInitialized`
    * runs `onStart()`) so any code that legitimately branches on it
    * — e.g. skipping parent-owned alarms in schedule guards — sees
-   * the flag during the first `onStart()` run. Broadcast paths no
-   * longer special-case facets, since facets can be directly
-   * addressed via sub-agent routing and have their own WebSocket
-   * connections.
+   * the flag during the first `onStart()` run. Protocol broadcasts are
+   * suppressed only during this bootstrap window; afterward, facets can
+   * broadcast to their own WebSocket clients reached via sub-agent
+   * routing.
    *
    * The facet's name (and `this.name` getter) is handled entirely by
    * partyserver via `ctx.id.name`, which is populated because the
@@ -2721,6 +3104,45 @@ declare class Agent<
     cls: SubAgentClass<T>,
     name: string
   ): Promise<SubAgentStub<T>>;
+  /** Maximum number of non-terminal agent-tool runs this parent may own at once. */
+  maxConcurrentAgentTools: number;
+  onAgentToolStart(_run: AgentToolRunInfo): Promise<void>;
+  onAgentToolFinish(
+    _run: AgentToolRunInfo,
+    _result: AgentToolLifecycleResult
+  ): Promise<void>;
+  runAgentTool<Input = unknown, Output = unknown>(
+    cls: ChatCapableAgentClass,
+    options: RunAgentToolOptions<Input>
+  ): Promise<RunAgentToolResult<Output>>;
+  hasAgentToolRun<T extends Agent>(
+    cls: SubAgentClass<T>,
+    runId: string
+  ): boolean;
+  hasAgentToolRun(agentType: string, runId: string): boolean;
+  clearAgentToolRuns(options?: {
+    olderThan?: number;
+    status?: AgentToolRunStatus[];
+  }): Promise<void>;
+  private _isAgentToolTerminal;
+  private _activeAgentToolRunCount;
+  private _defaultAgentToolPreview;
+  private _readAgentToolRun;
+  private _resultFromAgentToolRow;
+  private _terminalResultFromInspection;
+  private _updateAgentToolTerminal;
+  private _markAgentToolRunning;
+  private _parseAgentToolJson;
+  private _stringifyAgentToolOutput;
+  private _broadcastAgentToolEvent;
+  private _broadcastAgentToolChunks;
+  private _forwardAgentToolStream;
+  private _broadcastAgentToolTerminal;
+  private _asAgentToolChildAdapter;
+  private _agentToolClassByName;
+  private _replayAndInterruptAgentToolRun;
+  private _replayAgentToolRuns;
+  private _reconcileAgentToolRuns;
   /**
    * Shared facet resolution — takes a CamelCase class name string
    * (matching `ctx.exports`) rather than a class reference. Both
@@ -2753,7 +3175,7 @@ declare class Agent<
    * @param cls The Agent subclass used when creating the child
    * @param name Name of the child to delete
    */
-  deleteSubAgent(cls: SubAgentClass, name: string): void;
+  deleteSubAgent(cls: SubAgentClass, name: string): Promise<void>;
   /** @internal */
   private _subAgentRegistryReady;
   /** @internal */
@@ -2803,9 +3225,23 @@ declare class Agent<
     createdAt: number;
   }>;
   /**
-   * Destroy the Agent, removing all state and scheduled tasks
+   * Destroy the Agent, removing all state and scheduled tasks.
+   *
+   * On a top-level agent: drops every table, clears the alarm, and
+   * aborts the isolate.
+   *
+   * On a sub-agent (facet): delegates teardown to the immediate
+   * parent so the parent-owned schedule rows for this sub-agent
+   * (and any of its descendants) are cancelled, the parent's
+   * `cf_agents_sub_agents` registry entry is cleared, and
+   * `ctx.facets.delete` wipes the facet's own storage. The
+   * `ctx.facets.delete` call aborts this isolate, so this method
+   * may not return cleanly when invoked from inside the facet —
+   * callers should treat it as fire-and-forget.
    */
   destroy(): Promise<void>;
+  /** @internal Drop every internal Agents SDK table during top-level destroy. */
+  protected _dropInternalTablesForDestroy(): void;
   /**
    * Check if a method is callable
    * @param method The method name to check
@@ -3391,78 +3827,248 @@ declare class StreamingResponse {
   error(message: string): boolean;
 }
 //#endregion
+//#region src/agent-tool-types.d.ts
+type AgentToolRunStatus =
+  | "starting"
+  | "running"
+  | "completed"
+  | "error"
+  | "aborted"
+  | "interrupted";
+type AgentToolTerminalStatus = Extract<
+  AgentToolRunStatus,
+  "completed" | "error" | "aborted" | "interrupted"
+>;
+type AgentToolDisplayMetadata = {
+  name?: string;
+  icon?: string;
+} & Record<string, unknown>;
+type AgentToolRunInfo = {
+  runId: string;
+  parentToolCallId?: string;
+  agentType: string;
+  inputPreview?: unknown;
+  status: AgentToolRunStatus;
+  display?: AgentToolDisplayMetadata;
+  displayOrder: number;
+  startedAt: number;
+  completedAt?: number;
+};
+type AgentToolLifecycleResult = {
+  status: AgentToolTerminalStatus;
+  summary?: string;
+  error?: string;
+};
+type RunAgentToolOptions<Input = unknown> = {
+  input: Input;
+  runId?: string;
+  parentToolCallId?: string;
+  displayOrder?: number;
+  signal?: AbortSignal;
+  inputPreview?: unknown;
+  display?: AgentToolDisplayMetadata;
+};
+type RunAgentToolResult<Output = unknown> = {
+  runId: string;
+  agentType: string;
+  status: AgentToolTerminalStatus;
+  output?: Output;
+  summary?: string;
+  error?: string;
+};
+type ChatCapableAgentClass<T extends Agent = Agent> = SubAgentClass<T>;
+type AgentToolRunInspection<Output = unknown> = {
+  runId: string;
+  status: Exclude<AgentToolRunStatus, "interrupted">;
+  requestId?: string;
+  streamId?: string;
+  output?: Output;
+  summary?: string;
+  error?: string;
+  startedAt: number;
+  completedAt?: number;
+};
+type AgentToolStoredChunk = {
+  sequence: number;
+  body: string;
+};
+type AgentToolChildAdapter<Input = unknown, Output = unknown> = {
+  startAgentToolRun(
+    input: Input,
+    options: {
+      runId: string;
+      signal?: AbortSignal;
+    }
+  ): Promise<AgentToolRunInspection<Output>>;
+  cancelAgentToolRun(runId: string, reason?: unknown): Promise<void>;
+  inspectAgentToolRun(
+    runId: string
+  ): Promise<AgentToolRunInspection<Output> | null>;
+  getAgentToolChunks(
+    runId: string,
+    options?: {
+      afterSequence?: number;
+    }
+  ): Promise<AgentToolStoredChunk[]>;
+  tailAgentToolRun?(
+    runId: string,
+    options?: {
+      afterSequence?: number;
+      signal?: AbortSignal;
+    }
+  ): Promise<ReadableStream<AgentToolStoredChunk>>;
+};
+type AgentToolEvent =
+  | {
+      kind: "started";
+      runId: string;
+      agentType: string;
+      inputPreview?: unknown;
+      order: number;
+      display?: AgentToolDisplayMetadata;
+    }
+  | {
+      kind: "chunk";
+      runId: string;
+      body: string;
+    }
+  | {
+      kind: "finished";
+      runId: string;
+      summary: string;
+    }
+  | {
+      kind: "error";
+      runId: string;
+      error: string;
+    }
+  | {
+      kind: "aborted";
+      runId: string;
+      reason?: string;
+    }
+  | {
+      kind: "interrupted";
+      runId: string;
+      error: string;
+    };
+type AgentToolEventMessage = {
+  type: "agent-tool-event";
+  parentToolCallId?: string;
+  sequence: number;
+  replay?: true;
+  event: AgentToolEvent;
+};
+type AgentToolRunState = {
+  runId: string;
+  agentType: string;
+  parentToolCallId?: string;
+  inputPreview?: unknown;
+  order: number;
+  display?: AgentToolDisplayMetadata;
+  status: "running" | "completed" | "error" | "aborted" | "interrupted";
+  parts: UIMessage["parts"];
+  summary?: string;
+  error?: string;
+  subAgent: {
+    agent: string;
+    name: string;
+  };
+};
+type AgentToolEventState = {
+  runsById: Record<string, AgentToolRunState>;
+  runsByToolCallId: Record<string, AgentToolRunState[]>;
+  unboundRuns: AgentToolRunState[];
+};
+//#endregion
 export {
-  ElicitRequestSchema$1 as $,
-  callable as A,
-  MCPConnectionResult as B,
-  SendEmailOptions as C,
-  SubAgentClass as D,
-  StreamingResponse as E,
-  unstable_callable as F,
-  RegisterServerOptions as G,
-  MCPOAuthCallbackResult as H,
-  MCPClientManager as I,
-  RPCClientTransportOptions as J,
-  getNamespacedData as K,
-  MCPClientManagerOptions as L,
-  getCurrentAgent as M,
-  routeAgentEmail as N,
-  SubAgentStub as O,
-  routeAgentRequest as P,
-  ElicitRequest$1 as Q,
-  MCPClientOAuthCallbackConfig as R,
-  Schedule as S,
-  StateUpdateMessage as T,
-  MCPServerFilter as U,
-  MCPDiscoverResult as V,
-  MCPServerOptions as W,
-  RPCServerTransportOptions as X,
-  RPCServerTransport as Y,
-  RPC_DO_PREFIX as Z,
-  MCPServerMessage as _,
-  parseSubAgentPath as _t,
-  AgentNamespace as a,
-  McpAuthContext as at,
-  RPCRequest as b,
-  CallableMetadata as c,
-  WorkerTransport as ct,
-  DEFAULT_AGENT_STATIC_OPTIONS as d,
-  StreamableHTTPEdgeClientTransport as dt,
-  ElicitResult$1 as et,
-  EmailRoutingOptions as f,
-  McpClientOptions as ft,
-  MCPServer as g,
-  getSubAgentByName as gt,
-  FiberRecoveryContext as h,
-  SubAgentPathMatch as ht,
-  AgentContext as i,
-  experimental_createMcpHandler as it,
-  getAgentByName as j,
-  WSMessage as k,
-  Connection$1 as l,
-  WorkerTransportOptions as lt,
-  FiberContext as m,
-  SUB_PREFIX as mt,
-  AddRpcMcpServerOptions as n,
-  CreateMcpHandlerOptions as nt,
-  AgentOptions as o,
-  getMcpAuthContext as ot,
-  EmailSendBinding as p,
-  TransportType as pt,
-  RPCClientTransport as q,
-  Agent as r,
-  createMcpHandler as rt,
-  AgentStaticOptions as s,
-  TransportState as st,
-  AddMcpServerOptions as t,
-  McpAgent as tt,
-  ConnectionContext$1 as u,
-  SSEEdgeClientTransport as ut,
-  MCPServersState as v,
-  routeSubAgentRequest as vt,
-  SqlError as w,
-  RPCResponse as x,
-  QueueItem as y,
-  MCPClientOAuthResult as z
+  MCPClientManagerOptions as $,
+  FiberRecoveryContext as A,
+  SUB_PREFIX as At,
+  SqlError as B,
+  CallableMetadata as C,
+  TransportState as Ct,
+  EmailRoutingOptions as D,
+  StreamableHTTPEdgeClientTransport as Dt,
+  DEFAULT_AGENT_STATIC_OPTIONS as E,
+  SSEEdgeClientTransport as Et,
+  RPCRequest as F,
+  WSMessage$1 as G,
+  StreamingResponse as H,
+  RPCResponse as I,
+  getCurrentAgent as J,
+  callable as K,
+  Schedule as L,
+  MCPServerMessage as M,
+  getSubAgentByName as Mt,
+  MCPServersState as N,
+  parseSubAgentPath as Nt,
+  EmailSendBinding as O,
+  McpClientOptions as Ot,
+  QueueItem as P,
+  routeSubAgentRequest as Pt,
+  MCPClientManager as Q,
+  ScheduleCriteria as R,
+  AgentStaticOptions as S,
+  getMcpAuthContext as St,
+  ConnectionContext$1 as T,
+  WorkerTransportOptions as Tt,
+  SubAgentClass as U,
+  StateUpdateMessage as V,
+  SubAgentStub as W,
+  routeAgentRequest as X,
+  routeAgentEmail as Y,
+  unstable_callable as Z,
+  AddRpcMcpServerOptions as _,
+  McpAgent as _t,
+  AgentToolEventState as a,
+  MCPServerFilter as at,
+  AgentNamespace as b,
+  experimental_createMcpHandler as bt,
+  AgentToolRunInspection as c,
+  getNamespacedData as ct,
+  AgentToolStoredChunk as d,
+  RPCServerTransport as dt,
+  MCPClientOAuthCallbackConfig as et,
+  AgentToolTerminalStatus as f,
+  RPCServerTransportOptions as ft,
+  AddMcpServerOptions as g,
+  ElicitResult$1 as gt,
+  RunAgentToolResult as h,
+  ElicitRequestSchema$1 as ht,
+  AgentToolEventMessage as i,
+  MCPOAuthCallbackResult as it,
+  MCPServer as j,
+  SubAgentPathMatch as jt,
+  FiberContext as k,
+  TransportType as kt,
+  AgentToolRunState as l,
+  RPCClientTransport as lt,
+  RunAgentToolOptions as m,
+  ElicitRequest$1 as mt,
+  AgentToolDisplayMetadata as n,
+  MCPConnectionResult as nt,
+  AgentToolLifecycleResult as o,
+  MCPServerOptions as ot,
+  ChatCapableAgentClass as p,
+  RPC_DO_PREFIX as pt,
+  getAgentByName as q,
+  AgentToolEvent as r,
+  MCPDiscoverResult as rt,
+  AgentToolRunInfo as s,
+  RegisterServerOptions as st,
+  AgentToolChildAdapter as t,
+  MCPClientOAuthResult as tt,
+  AgentToolRunStatus as u,
+  RPCClientTransportOptions as ut,
+  Agent as v,
+  CreateMcpHandlerOptions as vt,
+  Connection$1 as w,
+  WorkerTransport as wt,
+  AgentOptions as x,
+  McpAuthContext as xt,
+  AgentContext as y,
+  createMcpHandler as yt,
+  SendEmailOptions as z
 };
-//# sourceMappingURL=index-DSwOzhhd.d.ts.map
+//# sourceMappingURL=agent-tool-types-CB7nISDE.d.ts.map