agents 0.13.2 → 0.14.0

package/dist/{agent-tool-types-Dn9n-3SI.d.ts → agent-tool-types-LInzZfLo.d.ts}

@@ -1,11 +1,11 @@
-import { n as AgentEmail } from "./internal_context-BZrMS0B5.js";
-import { t as RetryOptions } from "./retries-BVdRl5ZE.js";
+import { n as AgentEmail } from "./internal_context-CcZy2Em7.js";
+import { t as RetryOptions } from "./retries-ClWwxADl.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-DKey3P4s.js";
-import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-4OKQU9rT.js";
+} from "./index-Brdu5nMI.js";
+import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-CPm9rK5I.js";
 import {
   _ as WorkflowPage,
   g as WorkflowInfo,
@@ -13,9 +13,9 @@ import {
   l as WorkflowCallback,
   s as RunWorkflowOptions,
   y as WorkflowQueryCriteria
-} from "./workflow-types-Dkzg4hAx.js";
-import { t as MessageType } from "./types-_JjKmv-l.js";
-import { r as EmailResolver } from "./email-J0GGS3sa.js";
+} from "./workflow-types-DPkuBi--.js";
+import { t as MessageType } from "./types-B0GymtN_.js";
+import { r as EmailResolver } from "./email-1fTSJwPm.js";
 import { ToolSet, UIMessage } from "ai";
 import { RpcTarget } from "cloudflare:workers";
 import {
@@ -67,7 +67,15 @@ import {
 } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
 import { Client as Client$1 } from "@modelcontextprotocol/sdk/client";
-import { EventStore } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  EventId,
+  EventStore,
+  StreamId
+} from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  EventStore as EventStore$1,
+  StreamId as StreamId$1
+} from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 
 //#region src/sub-routing.d.ts
 /**
@@ -268,8 +276,30 @@ interface WorkerTransportOptions {
    */
   storage?: MCPStorageApi;
   /**
-   * Event store for resumability support.
-   * If provided, enables clients to reconnect and resume messages using Last-Event-ID.
+   * Event store for SSE resumability.
+   *
+   * When set, the transport assigns a globally-unique `id:` to each SSE
+   * event and replays missed events when a client reconnects with the
+   * `Last-Event-ID` header. Both GET (standalone listen stream) and POST
+   * (tool response stream) events are stored and replayable per the
+   * MCP 2025-03-26 spec.
+   *
+   * Configuring an event store **disables the server-side keepalive**
+   * on the standalone GET stream — idle drops are recovered by
+   * reconnect rather than prevented by writing bytes. Without an event
+   * store, the GET stream still gets the 25s comment-frame keepalive
+   * so long-lived idle listeners aren't closed by the Cloudflare edge
+   * ~5min watchdog.
+   *
+   * POST response streams always get the keepalive regardless of this
+   * setting: in-progress tool calls have no way to recover
+   * mid-execution without staying connected, so we don't let the
+   * stream drop in the first place.
+   *
+   * Bring your own {@link EventStore} implementation — e.g.
+   * `new DurableObjectEventStore(this.ctx.storage)` when embedding
+   * `WorkerTransport` inside a Durable Object / Agent. See
+   * cloudflare/agents#1583.
    */
   eventStore?: EventStore;
   /**
@@ -379,6 +409,94 @@ declare function experimental_createMcpHandler(
   options?: CreateMcpHandlerOptions
 ): (request: Request, env: unknown, ctx: ExecutionContext) => Promise<Response>;
 //#endregion
+//#region src/mcp/event-store.d.ts
+/**
+ * Durable Object–backed {@link EventStore} for SSE resumability.
+ *
+ * Default for `McpAgent`. Override `McpAgent.getEventStore()` to swap
+ * or disable.
+ *
+ * ## Storage layout
+ *
+ * Events are stored under `__mcp_event__:<streamId>:<seqHex>`, where
+ * `<seqHex>` is a 16-char zero-padded counter so events in a stream
+ * sort lexicographically and `getStreamIdForEventId` can recover the
+ * stream from `eventId` without a storage hit.
+ *
+ * ## Lifecycle
+ *
+ * Each POST tool-call stream's events live only until the final
+ * response is delivered. The transport calls {@link clearStream}
+ * immediately after writing the close frame, so storage growth is
+ * bounded by the in-flight POST streams plus the standalone GET
+ * stream. There is no background sweep — quiescent agents do no work,
+ * and the DO itself dies with the session.
+ *
+ * Standalone GET stream events (`_GET_stream`) are *not* cleared
+ * automatically; they accumulate for the lifetime of the DO. Bounded
+ * by session length in practice.
+ *
+ * Trade-off: if the client TCP connection dies *after* the close
+ * frame has been enqueued on the WS but before the bytes reach the
+ * client, the final message is unreplayable. Every earlier event in
+ * the stream is still replayable while the in-flight stream is open.
+ *
+ * ## Stream id constraints
+ *
+ * `streamId` MUST NOT contain `:`. `storeEvent` asserts this so
+ * embedders using custom stream ids fail loudly rather than risk
+ * prefix-scan collisions (e.g. clearing `a` accidentally hitting
+ * `a:b`). Default ids (`connection.id` UUIDs and the literal
+ * `_GET_stream`) already satisfy this.
+ */
+declare class DurableObjectEventStore implements EventStore {
+  private static readonly EVENT_KEY_PREFIX;
+  private static readonly SEQ_PAD;
+  /** DO storage caps multi-key delete at 128. */
+  private static readonly DELETE_CHUNK;
+  /** Defensive ceiling on a single replay batch. A live stream's
+   *  event count is small (progress notifications + final result);
+   *  this is here so a pathological history can't OOM the DO. */
+  private static readonly REPLAY_LIMIT;
+  private readonly storage;
+  /** In-memory seq counters per stream, rehydrated lazily from storage. */
+  private readonly seqByStream;
+  private readonly seqInit;
+  constructor(storage: DurableObjectStorage);
+  storeEvent(streamId: StreamId, message: JSONRPCMessage): Promise<EventId>;
+  getStreamIdForEventId(eventId: EventId): Promise<StreamId | undefined>;
+  replayEventsAfter(
+    lastEventId: EventId,
+    {
+      send
+    }: {
+      send: (eventId: EventId, message: JSONRPCMessage) => Promise<void>;
+    }
+  ): Promise<StreamId>;
+  /**
+   * Drop the event log for a single stream. Called by the transport
+   * immediately after a POST's final response has been written to the
+   * wire — no future `Last-Event-ID` for this stream is expected to
+   * resolve.
+   *
+   * Lists and deletes in chunks of {@link DELETE_CHUNK} (128, the DO
+   * storage cap) so we never load the entire event log into memory.
+   * After deleting, the next `list` call won't see the deleted keys,
+   * so passing `start: <prefix>` again is enough — no cursor bookkeeping.
+   */
+  clearStream(streamId: StreamId): Promise<void>;
+  private ensureSeqLoaded;
+}
+//#endregion
+//#region src/mcp/transport.d.ts
+/**
+ * An {@link EventStore} that supports dropping all events for a single
+ * stream id. Implemented by {@link DurableObjectEventStore}.
+ */
+interface ClearableEventStore extends EventStore$1 {
+  clearStream(streamId: StreamId$1): Promise<void>;
+}
+//#endregion
 //#region src/mcp/index.d.ts
 declare abstract class McpAgent<
   Env extends Cloudflare.Env = Cloudflare.Env,
@@ -396,6 +514,45 @@ declare abstract class McpAgent<
   abstract init(): Promise<void>;
   setInitializeRequest(initializeRequest: JSONRPCMessage): Promise<void>;
   getInitializeRequest(): Promise<JSONRPCMessage | undefined>;
+  /**
+   * Storage key prefix for the `streamId -> requestIds` mapping used
+   * to support POST stream resumption across WebSocket reconnects.
+   *
+   * @internal
+   */
+  private static readonly STREAM_REQS_KEY_PREFIX;
+  /** Persist the `requestIds` for a POST stream. @internal */
+  setStreamRequestIds(streamId: string, requestIds: RequestId[]): Promise<void>;
+  /** Read the persisted `requestIds` for a POST stream. @internal */
+  getStreamRequestIds(streamId: string): Promise<RequestId[] | undefined>;
+  /** Drop the persisted `requestIds` for a POST stream. @internal */
+  deleteStreamRequestIds(streamId: string): Promise<void>;
+  /**
+   * Reverse lookup: find which POST stream a given `requestId` belongs
+   * to, and return the stream's full `requestIds` list in the same
+   * pass. Used by the transport when the originating WS has dropped,
+   * so `send()` can still record events for replay and decide whether
+   * the stream is fully responded — mirrors the SDK's
+   * `_requestToStreamMapping` which outlives connection loss.
+   *
+   * Returning `requestIds` alongside `streamId` lets `send()` skip a
+   * second `getStreamRequestIds` read on the same key.
+   *
+   * O(n) in the number of in-flight POST streams — single-digit in
+   * practice since each stream is cleaned up on its final response.
+   * The `limit` is a defensive ceiling so an abandoned-POST leak can't
+   * unbounded-load this scan; if you hit it, something else has gone
+   * wrong and `send()` will throw `No active stream found`.
+   *
+   * @internal
+   */
+  getStreamForRequestId(requestId: RequestId): Promise<
+    | {
+        streamId: string;
+        requestIds: RequestId[];
+      }
+    | undefined
+  >;
   /** Read the transport type for this agent.
    * This relies on the naming scheme being `sse:${sessionId}`,
    * `streamable-http:${sessionId}`, or `rpc:${sessionId}`.
@@ -422,6 +579,21 @@ declare abstract class McpAgent<
    * ```
    */
   protected getRpcTransportOptions(): RPCServerTransportOptions;
+  /**
+   * Returns the {@link EventStore} for SSE resumability. Defaults to a
+   * {@link DurableObjectEventStore} backed by this agent's storage,
+   * letting clients reconnect with `Last-Event-ID` after the Cloudflare
+   * edge closes an idle SSE stream (~5 minute watchdog) instead of
+   * relying on a server-side keepalive that would block hibernation.
+   *
+   * Per-stream events are cleared by the transport immediately after
+   * the final response is written to the wire, so there's no
+   * background cleanup — storage cost is bounded by the in-flight
+   * streams alone.
+   *
+   * Override to disable (`return undefined`) or swap implementations.
+   */
+  protected getEventStore(): EventStore | undefined;
   /** Returns a new transport matching the type of the Agent. */
   private initTransport;
   /** Update and store the props */
@@ -535,10 +707,10 @@ interface RPCServerTransportOptions {
 }
 declare class RPCServerTransport implements Transport {
   private _started;
-  private _pendingResponse;
-  private _responseResolver;
   private _protocolVersion?;
   private _timeout;
+  private _pendingRequests;
+  private _pendingContinuations;
   sessionId?: string;
   onclose?: () => void;
   onerror?: (error: Error) => void;
@@ -548,17 +720,25 @@ declare class RPCServerTransport implements Transport {
   getProtocolVersion(): string | undefined;
   start(): Promise<void>;
   close(): Promise<void>;
-  send(message: JSONRPCMessage, _options?: TransportSendOptions): Promise<void>;
+  private _makeTimeout;
+  private _appendPending;
+  private _completePending;
+  private _completeRequest;
+  private _appendRequest;
+  private _completeContinuation;
+  private _appendContinuation;
+  send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
   /**
    * @internal Called by McpAgent.handleMcpMessage() — not for external use.
    *
-   * Wait for the next send() call and return whatever it produces.
+   * Wait for the next unmatched send() call that expects a client response or
+   * completes a resumed tool call.
    *
-   * Used after resolving an elicitation response: the tool handler is still
-   * running and will eventually call send() with either another elicitation
-   * request or the final tool result. This method captures that send() using
-   * the same _responseResolver / _pendingResponse / timeout mechanism as
-   * handle().
+   * Used after resolving an elicitation response: the original tool call has
+   * already returned the elicitation request to the RPC client, and the resumed
+   * tool handler will eventually send the final tool result. That final response
+   * has the original tool request id, so there is no active handle() waiter left
+   * for id-based routing; this continuation waiter receives it instead.
    */
   _awaitPendingResponse(): Promise<
     JSONRPCMessage | JSONRPCMessage[] | undefined
@@ -872,6 +1052,31 @@ type MCPServerRow = {
 };
 //#endregion
 //#region src/mcp/client.d.ts
+/** Maximum length of a normalized MCP server id. */
+declare const MCP_SERVER_ID_MAX_LENGTH = 64;
+/**
+ * Normalize a caller-supplied MCP server id into a stable, storage- and
+ * tool-name-safe form.
+ *
+ * The id is surfaced in several places where the character set matters:
+ *  - as the primary key in the `cf_agents_mcp_servers` SQLite table
+ *  - embedded in AI SDK tool names as `` `tool_${id.replace(/-/g, "")}_${tool}` ``
+ *    (tool names must match `/^[A-Za-z0-9_]+$/`)
+ *  - as a key on the `mcpConnections` map and OAuth provider storage
+ *
+ * Rules:
+ *  1. Lowercase.
+ *  2. Replace any run of disallowed characters with a single `-`.
+ *  3. Collapse repeated `-` and trim leading/trailing `-`/`_`.
+ *  4. Prefix with `id-` if the result is empty or doesn't start with a letter.
+ *  5. Truncate to {@link MCP_SERVER_ID_MAX_LENGTH} characters.
+ *
+ * @example
+ * normalizeServerId("my-supplied-id");  // "my-supplied-id"
+ * normalizeServerId("GitHub MCP!");     // "github-mcp"
+ * normalizeServerId("42-things");       // "id-42-things"
+ */
+declare function normalizeServerId(input: string): string;
 /**
  * Options that can be stored in the server_options column
  * This is what gets JSON.stringify'd and stored in the database
@@ -1009,6 +1214,31 @@ declare class MCPClientManager {
   private sql;
   private saveServerToStorage;
   private removeServerFromStorage;
+  /**
+   * Rename a server's id, in-place, across every place the id is used as a
+   * key. Used to JIT-migrate servers that were originally registered under an
+   * auto-generated nanoid to a caller-supplied stable id (see
+   * `Agent.addMcpServer`'s `{ id }` option).
+   *
+   * Migrates:
+   *  - the `cf_agents_mcp_servers` row (primary key)
+   *  - the in-memory `mcpConnections` map key
+   *  - the connection disposables map key
+   *  - the attached `authProvider.serverId`, if any
+   *  - OAuth-related storage keys under `/{clientName}/{oldId}/...`
+   *
+   * Safe to call when no OAuth keys exist (RPC / bearer-token HTTP servers).
+   * If `oldId === newId` this is a no-op. If a row already exists under
+   * `newId`, throws — the caller is expected to have verified uniqueness.
+   *
+   * @internal Exposed for `Agent.addMcpServer` JIT-migration.
+   */
+  migrateServerId(
+    oldId: string,
+    newId: string,
+    clientName: string
+  ): Promise<void>;
+  private _renameInMemoryConnection;
   private getServersFromStorage;
   private filterConnections;
   /**
@@ -1909,9 +2139,26 @@ type FiberRecoveryContext = {
    * Epoch milliseconds when the fiber row was inserted (when `runFiber`
    * started). Use `Date.now() - createdAt` to gate stale recoveries.
    */
-  createdAt: number;
+  createdAt: number /** Why this recovery hook is running. */;
+  recoveryReason: "interrupted";
   [key: string]: unknown;
 };
+type InternalFiberOptions = {
+  signal?: AbortSignal;
+  managed?: boolean;
+  initialSnapshot?: unknown;
+  wrapStash?: (data: unknown) => unknown;
+  beforeRunCleanup?: (
+    outcome:
+      | {
+          ok: true;
+        }
+      | {
+          ok: false;
+          error: unknown;
+        }
+  ) => void;
+};
 /**
  * MCP Server state update message from server -> Client
  */
@@ -1946,7 +2193,18 @@ type MCPServer = {
  * Options for adding an MCP server
  */
 type AddMcpServerOptions = {
-  /** OAuth callback host (auto-derived from request if omitted) */ callbackHost?: string;
+  /**
+   * Optional caller-supplied stable server id. When provided, this id is used
+   * for storage, restore, and tool-name namespacing instead of a generated
+   * `nanoid`. The value is normalized via {@link normalizeServerId} — for
+   * connector-style integrations this lets `addMcpServer` keep producing
+   * keys like `tool_github_create_pull_request`.
+   *
+   * Throws if an existing server already uses the same (normalized) id but a
+   * different name or url.
+   */
+  id?: string /** OAuth callback host (auto-derived from request if omitted) */;
+  callbackHost?: string;
   /**
    * Custom callback URL path — bypasses the default `/agents/{class}/{name}/callback` construction.
    * Required when `sendIdentityOnConnect` is `false` to prevent leaking the instance name.
@@ -1967,7 +2225,16 @@ type AddMcpServerOptions = {
  * Options for adding an MCP server via RPC (Durable Object binding)
  */
 type AddRpcMcpServerOptions = {
-  /** Props to pass to the McpAgent instance */ props?: Record<string, unknown>;
+  /**
+   * Optional caller-supplied stable server id. When provided, this id is used
+   * for storage, restore, and tool-name namespacing instead of a generated
+   * `nanoid`. The value is normalized via {@link normalizeServerId}.
+   *
+   * Throws if an existing server already uses the same (normalized) id but a
+   * different name or url.
+   */
+  id?: string /** Props to pass to the McpAgent instance */;
+  props?: Record<string, unknown>;
 };
 /**
  * Default options for Agent configuration.
@@ -1991,7 +2258,15 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
     maxAttempts: number;
     baseDelayMs: number;
     maxDelayMs: number;
-  };
+  } /** Timeout for internal framework fiber recovery hooks. */;
+  fiberRecoveryHookTimeoutMs: number /** Soft deadline for one interrupted-fiber recovery scan. */;
+  fiberRecoveryScanDeadlineMs: number;
+  /**
+   * Maximum age of an unmanaged interrupted-fiber row before recovery gives
+   * up. Bounds repeated retries of a `onFiberRecovered()` hook that keeps
+   * throwing so a poison row cannot re-trigger forever across boots.
+   */
+  fiberRecoveryMaxAgeMs: number;
 };
 /**
  * Configuration options for the Agent.
@@ -2011,6 +2286,19 @@ interface AgentStaticOptions {
   keepAliveIntervalMs?: number;
   /** Default retry options for schedule(), queue(), and this.retry(). */
   retry?: RetryOptions;
+  /**
+   * Timeout in milliseconds for internal framework fiber recovery hooks.
+   * User-defined `onFiberRecovered()` hooks are not timed out by default.
+   */
+  fiberRecoveryHookTimeoutMs?: number;
+  /** Soft deadline in milliseconds for one interrupted-fiber recovery scan. */
+  fiberRecoveryScanDeadlineMs?: number;
+  /**
+   * Maximum age in milliseconds of an unmanaged interrupted-fiber row before
+   * recovery stops retrying a repeatedly-throwing `onFiberRecovered()` hook
+   * and discards the row. Set to `0` to retain rows indefinitely.
+   */
+  fiberRecoveryMaxAgeMs?: number;
 }
 declare function getCurrentAgent<
   T extends Agent<Cloudflare.Env> = Agent<Cloudflare.Env>
@@ -2071,6 +2359,13 @@ declare class Agent<
   private _protocolBroadcastExcludeIds;
   private _cf_currentSubAgentBridge?;
   private _cf_virtualSubAgentConnections;
+  /**
+   * User-facing facet name. For legacy facets this is the same as
+   * `ctx.id.name`; path-scoped facets use an internal routing id and
+   * keep the logical name here instead.
+   * @internal
+   */
+  private _facetName?;
   /**
    * Ancestor chain, root-first. Empty for top-level DOs; populated at
    * facet init time from the parent's own `selfPath`. Exposed publicly
@@ -2107,6 +2402,8 @@ declare class Agent<
   private _managedFiberTerminalWaiters;
   /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
   private _runFiberRecoveryInProgress;
+  /** @internal Single-flight background recovery for parent agent-tool rows. */
+  private _agentToolRunRecoveryPromise;
   private _ParentClass;
   readonly mcp: MCPClientManager;
   /**
@@ -2483,6 +2780,7 @@ declare class Agent<
   private _facetRunRowsForPrefix;
   private _deleteFacetRunRowsForPrefix;
   private _rootAlarmOwner;
+  private _cf_rootResolvesToSelf;
   private _validateScheduleCallback;
   /**
    * Insert (or, for idempotent calls, return the existing row for) a
@@ -2799,6 +3097,9 @@ declare class Agent<
   private _applyManagedFiberRecoveryResult;
   private _settleManagedFiberExecution;
   private _parseFiberRecoverySnapshot;
+  private _fiberRecoveryPayload;
+  private _withFiberRecoveryTimeout;
+  private _recordFiberRecoveryFailure;
   private _runFiberRecoveryHook;
   private _fiberInspectionFromRow;
   private _waitForManagedFiber;
@@ -2828,6 +3129,20 @@ declare class Agent<
    * @returns The return value of fn
    */
   runFiber<T>(name: string, fn: (ctx: FiberContext) => Promise<T>): Promise<T>;
+  /**
+   * Internal framework entry point for fibers that need to compose their own
+   * recovery metadata with user checkpoint data while preserving the public
+   * `this.stash()` behavior.
+   *
+   * This deliberately stays protected/internal rather than becoming a public
+   * `runFiber()` option until the durable execution API needs this generality.
+   * @internal
+   */
+  protected _runFiberWithStashWrapper<T>(
+    name: string,
+    fn: (ctx: FiberContext) => Promise<T>,
+    options: Pick<InternalFiberOptions, "initialSnapshot" | "wrapStash">
+  ): Promise<T>;
   startFiber(
     name: string,
     fn: (ctx: FiberContext) => Promise<void>,
@@ -3128,13 +3443,9 @@ declare class Agent<
    * 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
-   * parent passed an explicit named Durable Object id to
-   * `ctx.facets.get()` — see {@link _cf_resolveSubAgent}. No
-   * `setName()` call or `__ps_name` storage write is needed; the
-   * facet's name survives cold wake automatically because the factory
-   * re-runs and `idFromName` is deterministic.
+   * The facet's logical name is persisted separately from its routing id.
+   * Legacy facets used the logical name directly as `ctx.id.name`; newer
+   * facets can use path-scoped routing ids while preserving `this.name`.
    *
    * @internal Called by {@link subAgent}.
    */
@@ -3143,8 +3454,10 @@ declare class Agent<
     parentPath?: ReadonlyArray<{
       className: string;
       name: string;
-    }>
+    }>,
+    identityName?: string
   ): Promise<void>;
+  get name(): string;
   /**
    * Ancestor chain for this agent, root-first. Empty for top-level
    * DOs. Populated at facet init time; survives hibernation.
@@ -3290,13 +3603,58 @@ declare class Agent<
   private _broadcastAgentToolEvent;
   private _broadcastAgentToolChunks;
   private _broadcastAgentToolStoredChunks;
+  private _broadcastAgentToolStoredChunksFromAdapter;
   private _forwardAgentToolStream;
+  /**
+   * Hook invoked by `_forwardAgentToolStream` after a child produces output that
+   * was forwarded to the parent's connections. Forwarding a sub-agent's stream
+   * is genuine forward progress for the *parent* turn (the parent is
+   * orchestrating the child), so chat-recovery subclasses (Think / AIChatAgent)
+   * override this to advance their recovery progress marker.
+   *
+   * Without it, a parent whose turn merely `await`s a sub-agent banks zero
+   * progress of its own, so under deploy churn the parent's no-progress recovery
+   * window exhausts and abandons the turn as `interrupted` — even though the
+   * child is healthily streaming and ultimately completes (observed in the
+   * `deploy-churn --mode subagent` harness: `attempt 6/6, stable_timeout,
+   * progress: 1`).
+   *
+   * Called ONLY after at least one chunk was actually forwarded — never merely
+   * because a child is attached — so a silent / hung child still lets the parent
+   * exhaust on its own timer. The base Agent has no recovery budget, so this is
+   * a no-op; subclasses should throttle the (durable) bump since this can be
+   * called repeatedly while a child streams.
+   */
+  protected _onAgentToolStreamProgress(): Promise<void>;
   private _broadcastAgentToolTerminal;
   private _asAgentToolChildAdapter;
   private _agentToolClassByName;
   private _replayAndInterruptAgentToolRun;
+  /**
+   * Re-attach to a still-running child agent-tool run and tail it to its real
+   * terminal result, instead of abandoning it as `interrupted` (#1630). The
+   * child is a separate facet with its own `chatRecovery`, so resolving it via
+   * the adapter wakes it and lets it self-complete the interrupted turn; we tail
+   * its live stream (forwarding chunks to the parent's connections) until it
+   * reaches terminal, then inspect for the collected result.
+   *
+   * Bounded by {@link DEFAULT_AGENT_TOOL_REATTACH_TIMEOUT_MS}: a child that keeps
+   * advancing toward terminal within the window is collected; a genuinely hung
+   * child returns `{ result: undefined }` once the budget elapses so the caller
+   * falls back to `interrupted` and recovery can never block forever.
+   *
+   * Returns the terminal `result` (and `completedAt`) when the child reaches a
+   * terminal status within the budget, plus the advanced broadcast `sequence`.
+   * Returns `{ result: undefined }` when there is no `tailAgentToolRun` adapter,
+   * the budget is exhausted, or the child is still non-terminal.
+   */
+  private _reattachAgentToolRunToTerminal;
   private _replayAgentToolRuns;
   private _reconcileAgentToolRuns;
+  private _inspectAgentToolRunForRecovery;
+  private _scheduleAgentToolRunRecovery;
+  private _agentToolRunRecoveryRunIds;
+  private _getAgentToolChunksForRecovery;
   /**
    * Shared facet resolution — takes a CamelCase class name string
    * (matching `ctx.exports`) rather than a class reference. Both
@@ -3332,11 +3690,15 @@ declare class Agent<
   deleteSubAgent(cls: SubAgentClass, name: string): Promise<void>;
   /** @internal */
   private _subAgentRegistryReady;
+  private _addColumnIfNotExists;
   /** @internal */
   private _ensureSubAgentRegistry;
   /** @internal */
   private _recordSubAgent;
   /** @internal */
+  private _subAgentRegistryRow;
+  private _cf_subAgentIdentity;
+  /** @internal */
   private _forgetSubAgent;
   /**
    * Whether this agent has previously spawned (and not deleted) a
@@ -3996,6 +4358,26 @@ type AgentToolTerminalStatus = Extract<
   AgentToolRunStatus,
   "completed" | "error" | "aborted" | "interrupted"
 >;
+/**
+ * Structured failure envelope an `agentTool()` returns when a sub-agent run
+ * does not complete. Instead of an opaque error string the parent model would
+ * parrot back to the user, the caller (or an orchestration harness) gets a
+ * machine-readable signal:
+ *
+ * - `status` mirrors the underlying terminal status (`error` | `aborted` |
+ *   `interrupted`).
+ * - `retryable` is `true` only for a transient interruption — the child was
+ *   reset or superseded by a deploy / parent recovery and never reached a
+ *   logical outcome, so re-dispatching the same run is the right move. A
+ *   genuine `error` or an intentional `aborted` is `false`.
+ * - `error` stays human-readable for logs and UI.
+ */
+type AgentToolFailure = {
+  ok: false;
+  status: Exclude<AgentToolTerminalStatus, "completed">;
+  error: string;
+  retryable: boolean;
+};
 type AgentToolDisplayMetadata = {
   name?: string;
   icon?: string;
@@ -4139,102 +4521,107 @@ type AgentToolEventState = {
 };
 //#endregion
 export {
-  SubAgentStub as $,
-  EmailSendBinding as A,
-  McpAuthContext as At,
-  QueueItem as B,
-  SubAgentPathMatch as Bt,
-  AgentStaticOptions as C,
-  ElicitRequest$1 as Ct,
-  DEFAULT_AGENT_STATIC_OPTIONS as D,
-  CreateMcpHandlerOptions as Dt,
-  ConnectionContext$1 as E,
-  McpAgent as Et,
-  FiberStatus as F,
-  SSEEdgeClientTransport as Ft,
-  ScheduleCriteria as G,
-  RPCResponse as H,
-  parseSubAgentPath as Ht,
-  ListFibersOptions as I,
-  StreamableHTTPEdgeClientTransport as It,
-  StartFiberOptions as J,
-  SendEmailOptions as K,
-  MCPServer as L,
-  McpClientOptions as Lt,
-  FiberInspection as M,
-  TransportState as Mt,
-  FiberRecoveryContext as N,
-  WorkerTransport as Nt,
-  DeleteFibersOptions as O,
-  createMcpHandler as Ot,
-  FiberRecoveryResult as P,
-  WorkerTransportOptions as Pt,
-  SubAgentClass as Q,
-  MCPServerMessage as R,
-  TransportType as Rt,
-  AgentOptions as S,
-  RPC_DO_PREFIX as St,
-  Connection$1 as T,
-  ElicitResult$1 as Tt,
-  RoutingRetryOptions as U,
-  routeSubAgentRequest as Ut,
-  RPCRequest as V,
-  getSubAgentByName as Vt,
-  Schedule as W,
-  StateUpdateMessage as X,
-  StartFiberResult as Y,
-  StreamingResponse as Z,
-  AddRpcMcpServerOptions as _,
-  getNamespacedData as _t,
+  SubAgentClass as $,
+  EmailRoutingOptions as A,
+  ClearableEventStore as At,
+  MCPServersState as B,
+  SSEEdgeClientTransport as Bt,
+  AgentOptions as C,
+  RPCServerTransport as Ct,
+  ConnectionContext$1 as D,
+  ElicitRequestSchema$1 as Dt,
+  Connection$1 as E,
+  ElicitRequest$1 as Et,
+  FiberRecoveryResult as F,
+  McpAuthContext as Ft,
+  Schedule as G,
+  SubAgentPathMatch as Gt,
+  RPCRequest as H,
+  McpClientOptions as Ht,
+  FiberStatus as I,
+  getMcpAuthContext as It,
+  SqlError as J,
+  routeSubAgentRequest as Jt,
+  ScheduleCriteria as K,
+  getSubAgentByName as Kt,
+  ListFibersOptions as L,
+  TransportState as Lt,
+  FiberContext as M,
+  CreateMcpHandlerOptions as Mt,
+  FiberInspection as N,
+  createMcpHandler as Nt,
+  DEFAULT_AGENT_STATIC_OPTIONS as O,
+  ElicitResult$1 as Ot,
+  FiberRecoveryContext as P,
+  experimental_createMcpHandler as Pt,
+  StreamingResponse as Q,
+  MCPServer as R,
+  WorkerTransport as Rt,
+  AgentNamespace as S,
+  RPCClientTransportOptions as St,
+  CallableMetadata as T,
+  RPC_DO_PREFIX as Tt,
+  RPCResponse as U,
+  TransportType as Ut,
+  QueueItem as V,
+  StreamableHTTPEdgeClientTransport as Vt,
+  RoutingRetryOptions as W,
+  SUB_PREFIX as Wt,
+  StartFiberResult as X,
+  StartFiberOptions as Y,
+  StateUpdateMessage as Z,
+  AddMcpServerOptions as _,
+  MCP_SERVER_ID_MAX_LENGTH as _t,
   AgentToolEventState as a,
-  routeAgentRequest as at,
-  AgentGetOptions as b,
-  RPCServerTransport as bt,
-  AgentToolRunInspection as c,
-  MCPClientManagerOptions as ct,
-  AgentToolStoredChunk as d,
-  MCPConnectionResult as dt,
-  WSMessage$1 as et,
-  AgentToolTerminalStatus as f,
-  MCPDiscoverResult as ft,
-  AddMcpServerOptions as g,
-  RegisterServerOptions as gt,
-  RunAgentToolResult as h,
-  MCPServerOptions as ht,
+  routeAgentEmail as at,
+  AgentContext as b,
+  normalizeServerId as bt,
+  AgentToolRunInfo as c,
+  MCPClientManager as ct,
+  AgentToolRunStatus as d,
+  MCPClientOAuthResult as dt,
+  SubAgentStub as et,
+  AgentToolStoredChunk as f,
+  MCPConnectionResult as ft,
+  RunAgentToolResult as g,
+  MCPServerOptions as gt,
+  RunAgentToolOptions as h,
+  MCPServerFilter as ht,
   AgentToolEventMessage as i,
-  routeAgentEmail as it,
-  FiberContext as j,
-  getMcpAuthContext as jt,
-  EmailRoutingOptions as k,
-  experimental_createMcpHandler as kt,
-  AgentToolRunState as l,
-  MCPClientOAuthCallbackConfig as lt,
-  RunAgentToolOptions as m,
-  MCPServerFilter as mt,
+  getCurrentAgent as it,
+  EmailSendBinding as j,
+  DurableObjectEventStore as jt,
+  DeleteFibersOptions as k,
+  McpAgent as kt,
+  AgentToolRunInspection as l,
+  MCPClientManagerOptions as lt,
+  ChatCapableAgentClass as m,
+  MCPOAuthCallbackResult as mt,
   AgentToolDisplayMetadata as n,
-  getAgentByName as nt,
-  AgentToolLifecycleResult as o,
-  unstable_callable as ot,
-  ChatCapableAgentClass as p,
-  MCPOAuthCallbackResult as pt,
-  SqlError as q,
+  callable as nt,
+  AgentToolFailure as o,
+  routeAgentRequest as ot,
+  AgentToolTerminalStatus as p,
+  MCPDiscoverResult as pt,
+  SendEmailOptions as q,
+  parseSubAgentPath as qt,
   AgentToolEvent as r,
-  getCurrentAgent as rt,
-  AgentToolRunInfo as s,
-  MCPClientManager as st,
+  getAgentByName as rt,
+  AgentToolLifecycleResult as s,
+  unstable_callable as st,
   AgentToolChildAdapter as t,
-  callable as tt,
-  AgentToolRunStatus as u,
-  MCPClientOAuthResult as ut,
-  Agent as v,
-  RPCClientTransport as vt,
-  CallableMetadata as w,
-  ElicitRequestSchema$1 as wt,
-  AgentNamespace as x,
-  RPCServerTransportOptions as xt,
-  AgentContext as y,
-  RPCClientTransportOptions as yt,
-  MCPServersState as z,
-  SUB_PREFIX as zt
+  WSMessage$1 as tt,
+  AgentToolRunState as u,
+  MCPClientOAuthCallbackConfig as ut,
+  AddRpcMcpServerOptions as v,
+  RegisterServerOptions as vt,
+  AgentStaticOptions as w,
+  RPCServerTransportOptions as wt,
+  AgentGetOptions as x,
+  RPCClientTransport as xt,
+  Agent as y,
+  getNamespacedData as yt,
+  MCPServerMessage as z,
+  WorkerTransportOptions as zt
 };
-//# sourceMappingURL=agent-tool-types-Dn9n-3SI.d.ts.map
+//# sourceMappingURL=agent-tool-types-LInzZfLo.d.ts.map