agents 0.21.0 → 0.23.0

package/dist/{agent-tool-types-CzGGB-20.d.ts → agent-routing-DE5zmCQ8.d.ts}

@@ -1,11 +1,28 @@
-import { n as AgentEmail } from "./internal_context-Dg4Cgjcu.js";
-import { t as RetryOptions } from "./retries-CAvxtG9d.js";
+import {
+  _ as LifecycleJobOutcome,
+  b as Connection,
+  g as LifecycleJobContext,
+  o as MemoryLimitContext,
+  s as LifecycleCapability,
+  t as CapabilityRequestContext,
+  u as LifecycleRouteAddress,
+  w as WSMessage,
+  x as ConnectionContext
+} from "./capability-runner-Be_-PLR1.js";
+import { t as RetryOptions } from "./retries-D9Ds-1lz.js";
+import {
+  c as LifecycleRouteEnvelope,
+  n as CurrentAgentContext,
+  o as Lifecycle
+} from "./current-agent-Da_C9a3b.js";
+import { t as AgentEmail } from "./internal_context-BlxFEWfn.js";
+import { r as EmailResolver, s as SendEmailOptions } from "./email-7TatiTnl.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-BRnybD6X.js";
-import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-VTZj2VtM.js";
+} from "./index-YSKgfgg9.js";
+import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-Tmf1vgKz.js";
 import {
   a as McpAuthContext,
   c as CORSOptions,
@@ -16,27 +33,25 @@ import {
   s as BaseTransportType,
   t as CreateStatelessMcpHandlerOptions,
   u as McpClientOptions
-} from "./handler-stateless-C_bo-Ytq.js";
-import { n as LegacyCallToolResultSchema } from "./client-invoker-BNSZxAkv.js";
+} from "./handler-stateless-DxYpJ_XF.js";
+import { n as LegacyCallToolResultSchema } from "./invoker-CG0_p_Wq.js";
 import { t as MessageType } from "./types-6Zo2zfoO.js";
-import { r as EmailResolver } from "./email-CL27preh.js";
 import {
+  a as ScheduleCriteria,
+  i as Schedule,
+  o as ScheduleOptions,
+  t as Scheduler
+} from "./scheduler-Dwh85ZGl.js";
+import { l as TaskHandlers, r as Tasks } from "./tasks-BRJ5zgya.js";
+import { t as CallableMetadata } from "./callable-decorator-DP__HhBA.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import {
+  DurableObject,
   RpcTarget,
   WorkflowEvent,
   WorkflowSleepDuration,
   WorkflowStep
 } from "cloudflare:workers";
-import {
-  Connection,
-  Connection as Connection$1,
-  ConnectionContext,
-  ConnectionContext as ConnectionContext$1,
-  PartyServerOptions,
-  RoutingRetryOptions,
-  Server,
-  WSMessage,
-  WSMessage as WSMessage$1
-} from "partyserver";
 import { z } from "zod";
 import {
   CacheableRequestOptions,
@@ -79,7 +94,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { McpServerFactory } from "@modelcontextprotocol/server";
 import { McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { Server as Server$2 } from "@modelcontextprotocol/sdk/server/index.js";
+import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   EventStore as EventStore$1,
   StreamId as StreamId$1,
@@ -277,78 +292,800 @@ declare function routeSubAgentRequest(
  */
 declare function getSubAgentByName<T extends Agent>(
   parent: unknown,
-  cls: SubAgentClass<T>,
+  cls: DynamicAgentClass<T>,
   name: string
-): Promise<SubAgentStub<T>>;
+): Promise<DynamicAgentStub<T>>;
 //#endregion
-//#region src/core/events.d.ts
-interface Disposable {
-  dispose(): void;
-}
-type Event<T> = (listener: (e: T) => void) => Disposable;
-declare class Emitter<T> implements Disposable {
-  private _listeners;
-  readonly event: Event<T>;
-  fire(data: T): void;
-  dispose(): void;
-}
+//#region src/dynamic-agents/types.d.ts
+type DynamicAgentConnectionMeta = {
+  id: string;
+  uri: string | null;
+  tags: string[];
+  state: unknown;
+  requestHeaders?: [string, string][];
+};
+type DynamicAgentConnectionBridgeLike = {
+  send(message: string | ArrayBuffer | ArrayBufferView): void | Promise<void>;
+  close(code?: number, reason?: string): void | Promise<void>;
+  setState(state: unknown): unknown | Promise<unknown>;
+  broadcast(
+    ownerPath: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): void | Promise<void>;
+};
+type DynamicAgentConnectionOperationName = "send" | "setState" | "close";
+/**
+ * Constructor type for a dynamic agent (facet-backed child) class.
+ * Used by {@link Agent.dynamicAgents} to reference the child class
+ * via `ctx.exports`.
+ *
+ * The class name (`cls.name`) must match the export name in the
+ * worker entry point — re-exports under a different name
+ * (e.g. `export { Foo as Bar }`) are not supported.
+ */
+type DynamicAgentClass<T extends Agent = Agent> = {
+  new (ctx: DurableObjectState, env: never): T;
+};
+/**
+ * Wraps `T` in a `Promise` unless it already is one.
+ */
+type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+/**
+ * A typed RPC stub for a dynamic agent. Exposes all public instance
+ * methods as callable RPC methods with Promise-wrapped return types.
+ *
+ * Methods owned by `Agent`, its lifecycle, or `DurableObject` internals
+ * are excluded — only user-defined methods on the subclass are exposed.
+ */
+type DynamicAgentStub<T extends Agent> = {
+  [K in keyof T as K extends keyof Agent
+    ? never
+    : T[K] extends (...args: never[]) => unknown
+      ? K
+      : never]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promisify<R>
+    : never;
+};
+type FacetRunStorageRow = {
+  owner_path: string;
+  owner_path_key: string;
+  run_id: string;
+  created_at: number;
+};
+/**
+ * Internal RPC surface exposed by the root agent for facets to
+ * delegate alarm-owning operations (schedules + facet teardown).
+ * @internal
+ */
+type RootFacetRpcSurface = {
+  _cf_routeLifecycle(
+    target: LifecycleRouteAddress | undefined,
+    envelope: LifecycleRouteEnvelope
+  ): Promise<unknown>;
+  _cf_cleanupFacetPrefix(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<void>;
+  _cf_destroyDescendantFacet(
+    targetPath: ReadonlyArray<AgentPathStep>
+  ): Promise<void>;
+  _cf_acquireFacetKeepAlive(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<string>;
+  _cf_releaseFacetKeepAlive(token: string): Promise<void>;
+  _cf_registerFacetRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
+  _cf_unregisterFacetRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
+  _cf_broadcastToSubAgent(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  _cf_subAgentConnectionMetas(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<DynamicAgentConnectionMeta[]>;
+  _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>;
+};
 //#endregion
-//#region src/mcp/client-transports.d.ts
+//#region src/dynamic-agents/bridges.d.ts
 /**
- * @deprecated Use SSEClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ * Parent-side bridge handed to a facet over RPC: wraps a live root-owned
+ * `Connection` so the facet can send/close/setState on it, and carries
+ * the root's broadcast entry point for facet-scoped broadcasts.
  */
-declare class SSEEdgeClientTransport extends SSEClientTransport {
-  constructor(url: URL, options: SSEClientTransportOptions);
+declare class DynamicAgentConnectionBridge
+  extends RpcTarget
+  implements DynamicAgentConnectionBridgeLike
+{
+  #private;
+  constructor(
+    connection: Connection,
+    broadcast?: (
+      ownerPath: ReadonlyArray<{
+        className: string;
+        name: string;
+      }>,
+      message: string | ArrayBuffer | ArrayBufferView,
+      without?: string[]
+    ) => void | Promise<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 | Promise<void>;
 }
+//#endregion
+//#region src/dynamic-agents/identity.d.ts
+declare const SUB_AGENT_IDENTITY_VERSION_LEGACY = "legacy";
+declare const SUB_AGENT_IDENTITY_VERSION_PATH_V2 = "path-v2";
+type SubAgentIdentityVersion =
+  | typeof SUB_AGENT_IDENTITY_VERSION_LEGACY
+  | typeof SUB_AGENT_IDENTITY_VERSION_PATH_V2;
+//#endregion
+//#region src/dynamic-agents/registry.d.ts
 /**
- * @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ * SQL access the registry needs from its owning Agent: the tagged
+ * template helper plus raw DDL execution (for additive column
+ * migrations whose errors must be inspected).
  */
-declare class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTransport {
-  constructor(url: URL, options: StreamableHTTPClientTransportOptions);
+type DynamicAgentRegistrySqlHost = {
+  sql<T = Record<string, string | number | boolean | null>>(
+    strings: TemplateStringsArray,
+    ...values: (string | number | boolean | null)[]
+  ): T[];
+  execRawSql(sql: string): void;
+};
+/**
+ * The parent-side registry of spawned dynamic agents (facets), stored
+ * in the parent's own SQLite. Backs `hasSubAgent` / `listSubAgents`
+ * and the identity-versioning decision (legacy bare-name facets vs
+ * path-scoped v2 identities).
+ *
+ * Table and column names are storage-frozen — never rename them.
+ */
+declare class DynamicAgentRegistry {
+  #private;
+  constructor(host: DynamicAgentRegistrySqlHost);
+  ensure(): void;
+  record(
+    className: string,
+    name: string,
+    identity: {
+      version: SubAgentIdentityVersion;
+      name: string;
+    }
+  ): void;
+  row(
+    className: string,
+    name: string
+  ): {
+    identity_version: string | null;
+    identity_name: string | null;
+  } | null;
+  identity(
+    className: string,
+    name: string,
+    childPath: ReadonlyArray<AgentPathStep>
+  ): Promise<{
+    version: SubAgentIdentityVersion;
+    name: string;
+    existing: boolean;
+  }>;
+  forget(className: string, name: string): void;
+  has(className: string, name: string): boolean;
+  list(className?: string): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
 }
 //#endregion
-//#region src/mcp/worker-transport.d.ts
+//#region src/dynamic-agents/host.d.ts
 /**
- * Pluggable storage adapter for persisting `WorkerTransport` state across
- * Durable Object hibernation / restart cycles.
+ * The Agent internals the dynamic-agents (facet) machinery reaches
+ * into. Agent implements this structurally and passes itself at
+ * construction — the interface exists to make the coupling explicit
+ * and reviewable, and is the seam a later capability refactor would
+ * shrink.
  *
- * A typical implementation reads/writes a single key on `this.ctx.storage`
- * inside a Durable Object or Agent.
+ * Members named `_cf_*` are cross-facet RPC entry points that must
+ * stay on the Agent prototype; the module calls back into them when
+ * traversal continues on another agent instance.
+ *
+ * @internal
  */
-interface MCPStorageApi {
-  get(): Promise<TransportState | undefined> | TransportState | undefined;
-  set(state: TransportState): Promise<void> | void;
-}
-/** Shape of the persisted transport state. */
-interface TransportState {
-  sessionId?: string;
-  initialized: boolean;
-  initializeParams?: InitializeRequestParams;
+interface DynamicAgentHostPort {
+  readonly ctx: DurableObjectState;
+  readonly lifecycle: {
+    route(envelope: LifecycleRouteEnvelope): Promise<unknown>;
+    readonly name: string;
+  };
+  sql<T = Record<string, string | number | boolean | null>>(
+    strings: TemplateStringsArray,
+    ...values: (string | number | boolean | null)[]
+  ): T[];
+  /** Facet identity — written by `initAsFacet` and startup restore. */
+  _isFacet: boolean;
+  _facetName?: string;
+  _parentPath: ReadonlyArray<AgentPathStep>;
+  readonly name: string;
+  readonly _ParentClass: {
+    readonly name: string;
+  };
+  readonly selfPath: AgentPathStep[];
+  _keepAliveRefs: number;
+  _isSameAgentPathPrefix(
+    prefix: ReadonlyArray<AgentPathStep>,
+    path: ReadonlyArray<AgentPathStep>
+  ): boolean;
+  hasSubAgent(className: string, name: string): boolean;
+  _cf_resolveSubAgent(className: string, name: string): Promise<unknown>;
+  _cf_cleanupFacetPrefix(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<void>;
+  _cf_routeLifecycle(
+    target: LifecycleRouteAddress | undefined,
+    envelope: LifecycleRouteEnvelope
+  ): Promise<unknown>;
+  _syncHostJobs(): Promise<void>;
+  readonly scheduler: {
+    __DO_NOT_USE_WILL_BREAK__cleanupRoutePrefix(prefix: string): Promise<void>;
+  };
+  readonly tasks: {
+    __DO_NOT_USE_WILL_BREAK__cleanupRoutePrefix(prefix: string): Promise<void>;
+  };
+  /** Local (non-facet-index) durable fiber recovery pass. */
+  _checkRunFibers(): Promise<void>;
+  /** Overridable RPC entry points — call via the host so subclass overrides intercept. */
+  _cf_broadcastToSubAgent(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  _cf_checkRunFibersForFacet(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<number>;
+  /** Ensure constructor-time async initialization has completed. */
+  __unsafe_ensureInitialized(): Promise<void>;
+  /**
+   * Run `body` in a fresh invocation scope with no native request/
+   * connection context attached, so a child-facet RPC never sees
+   * parent-owned I/O handles.
+   */
+  _runFacetInitInvocation<T>(body: () => Promise<T>): Promise<T>;
+  readonly _webSockets: {
+    getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
+    getConnections<TState = unknown>(
+      tag?: string
+    ): Iterable<Connection<TState>>;
+  };
+  _ensureConnectionWrapped(connection: Connection): void;
+  _unsafe_getConnectionFlag(connection: Connection, key: string): unknown;
+  _unsafe_setConnectionFlag(
+    connection: Connection,
+    key: string,
+    value: unknown
+  ): void;
+  readonly _rawStateAccessors: {
+    get(connection: Connection):
+      | {
+          getRaw(): unknown;
+        }
+      | undefined;
+  };
+  shouldConnectionBeReadonly(
+    connection: Connection,
+    context: {
+      request: Request;
+    }
+  ): boolean;
+  setConnectionReadonly(connection: Connection, readonly: boolean): void;
+  shouldSendProtocolMessages(
+    connection: Connection,
+    context: {
+      request: Request;
+    }
+  ): boolean;
+  _setConnectionNoProtocol(connection: Connection): void;
+  getConnectionTags(
+    connection: Connection,
+    context: {
+      request: Request;
+    }
+  ): Promise<string[]> | string[];
+  onConnect(
+    connection: Connection,
+    context: {
+      request: Request;
+    }
+  ): unknown | Promise<unknown>;
+  onMessage(
+    connection: Connection,
+    message: WSMessage
+  ): unknown | Promise<unknown>;
+  onClose(
+    connection: Connection,
+    code: number,
+    reason: string,
+    wasClean: boolean
+  ): unknown | Promise<unknown>;
+  onBeforeSubAgent(
+    request: Request,
+    child: {
+      className: string;
+      name: string;
+    }
+  ): Promise<Request | Response | void>;
 }
-interface WorkerTransportOptions extends WebStandardStreamableHTTPServerTransportOptions {
+//#endregion
+//#region src/dynamic-agents/dynamic-agents.d.ts
+/**
+ * The facet-backed dynamic-agent machinery, extracted from the Agent
+ * class. One instance per Agent, installed as a Lifecycle capability
+ * (`capabilityId: "dynamic-agents"`); the host port documents exactly
+ * which Agent internals it touches.
+ *
+ * The capability claims no runner hooks — four integration points are
+ * deliberately wired directly through the Agent composition root
+ * instead, because the runner's dispatch contract cannot express them:
+ * the `/sub/` upgrade path rewrites the request and *continues* into
+ * `lifecycle.fetch` (onRequest can only claim), forwarded WS frames run
+ * inside the host's onMessage wrapper *after* the WebSockets capability
+ * has claimed the wake, this module *implements* the lifecycle route
+ * transport rather than consuming it, and facet-context restore has
+ * load-bearing startup ordering inside the host's startup span.
+ *
+ * Nothing here renames any wire- or storage-visible identifier: the
+ * `cf_agents_facet_runs` table, `_cf_*` RPC method names, and route
+ * key formats are frozen.
+ *
+ * @internal
+ */
+declare class DynamicAgentsInternal extends LifecycleCapability {
+  #private;
+  /** The parent-side registry of spawned dynamic agents. */
+  readonly registry: DynamicAgentRegistry;
+  constructor(host: DynamicAgentHostPort);
+  runRowsForPrefix(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): FacetRunStorageRow[];
+  deleteRunRowsForPrefix(ownerPath: ReadonlyArray<AgentPathStep>): void;
+  lifecycleRouteAddress(): LifecycleRouteAddress | undefined;
+  routeLifecycleToRoot(envelope: LifecycleRouteEnvelope): Promise<unknown>;
+  routeLifecycleToTarget(
+    target: LifecycleRouteAddress,
+    envelope: LifecycleRouteEnvelope
+  ): Promise<unknown>;
+  /** Body of the single native-RPC aperture for routed Lifecycle capabilities. */
+  routeLifecycle(
+    target: LifecycleRouteAddress | undefined,
+    envelope: LifecycleRouteEnvelope
+  ): Promise<unknown>;
+  rootAlarmOwner(): Promise<RootFacetRpcSurface>;
+  rootResolvesToSelf(): boolean;
   /**
-   * CORS options applied to every response and to OPTIONS preflight.
-   * Defaults: `origin: *`, expose `mcp-session-id`, allow the standard MCP
-   * methods/headers, max-age 86400.
+   * Clean root-owned bookkeeping for a sub-tree of facets: bulk-cancel
+   * schedules and routed Task wake mirrors under the owner-path prefix,
+   * and delete root-side facet fiber recovery leases for the same sub-tree.
    */
-  corsOptions?: CORSOptions;
+  cleanupPrefix(ownerPath: ReadonlyArray<AgentPathStep>): Promise<void>;
   /**
-   * Optional storage adapter for persisting transport state across DO
-   * hibernation / restart. Use this to keep an MCP session alive across
-   * Durable Object wake-ups.
+   * Acquire a root-owned keepAlive ref on behalf of a descendant facet.
    */
-  storage?: MCPStorageApi;
-}
-declare class WorkerTransport extends WebStandardStreamableHTTPServerTransport$1 {
-  private readonly _corsOptions?;
-  private readonly _storage?;
-  private _stateRestored;
-  private _capturedInitializeParams?;
-  private _userOnSessionInitialized?;
-  private _bridgeInstalled;
+  acquireKeepAlive(ownerPath: ReadonlyArray<AgentPathStep>): Promise<string>;
   /**
-   * Request ids whose SSE stream was deliberately torn down via
-   * `closeSSEStream`. The SDK's `send()` throws "No connection established"
+   * Release a root-owned keepAlive ref previously acquired for a facet.
+   * Idempotent so disposer calls can safely race or run twice.
+   */
+  releaseKeepAlive(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.
+   */
+  registerRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
+  /**
+   * 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.
+   */
+  checkRunFibers(): Promise<void>;
+  /**
+   * 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.
+   */
+  checkRunFibersAtPath(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<number>;
+  /**
+   * Invoke an RPC method on the host Agent or a descendant facet
+   * identified by a root-first path. Used by AgentWorkflow to route
+   * callbacks and `this.agent` calls back to the exact sub-agent that
+   * started a workflow.
+   */
+  invokeAgentPath(
+    targetPath: ReadonlyArray<AgentPathStep>,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
+  /**
+   * 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.
+   */
+  destroyDescendant(targetPath: ReadonlyArray<AgentPathStep>): Promise<void>;
+  /**
+   * Shared facet resolution — takes a CamelCase class name string
+   * (matching `ctx.exports`) rather than a class reference. Both
+   * `subAgent(cls, name)` and `_cf_invokeSubAgent(className, ...)`
+   * funnel through here so registry bookkeeping and the
+   * `_cf_initAsFacet` handshake are consistent.
+   */
+  resolve(className: string, name: string): Promise<unknown>;
+  /**
+   * Forcefully abort a running facet. Transitively aborts the child's
+   * own children; storage is preserved.
+   */
+  abort(className: string, name: string, reason?: unknown): void;
+  /**
+   * Delete a facet: abort it if running, then permanently wipe its
+   * storage. Transitively deletes the child's own children.
+   */
+  delete(className: string, name: string): Promise<void>;
+  /** Drop all facet-side virtual connections (test/rehydration hook). */
+  clearVirtualConnections(): void;
+  /** Facet-side lookup of a virtual connection by id. */
+  getVirtualConnection(id: string): Connection | undefined;
+  /** Facet-side iteration over virtual connections, optionally by tag. */
+  getVirtualConnections(tag?: string): Iterable<Connection>;
+  activeBridge(
+    connectionId?: string
+  ): DynamicAgentConnectionBridgeLike | undefined;
+  /**
+   * Route a virtual sub-agent connection operation through its live frame
+   * bridge, or through the durable root Agent after that frame completes.
+   * All operations share one per-connection queue. Facet broadcasts wait for
+   * older queued operations; failures do not block later work.
+   */
+  routeConnectionOperation(
+    connectionId: string,
+    operationName: DynamicAgentConnectionOperationName,
+    operation: (bridge: DynamicAgentConnectionBridgeLike) => unknown
+  ): void;
+  /**
+   * Route a facet broadcast after every older connection operation.
+   *
+   * This barrier is intentionally one-way: facet startup can broadcast before
+   * a child connection has finished initializing its tags and protocol flags.
+   * Making those later connection operations wait would let the next frame
+   * observe stale root-owned metadata.
+   */
+  routeBroadcast(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[],
+    upstreamBridge?: DynamicAgentConnectionBridgeLike
+  ): Promise<void>;
+  broadcastToParent(
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  broadcastToPath(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    message: string | ArrayBuffer | ArrayBufferView,
+    without?: string[]
+  ): Promise<void>;
+  connectionMetas(
+    ownerPath: ReadonlyArray<AgentPathStep>
+  ): Promise<DynamicAgentConnectionMeta[]>;
+  sendToConnection(
+    connectionId: string,
+    message: string | ArrayBuffer | ArrayBufferView
+  ): Promise<void>;
+  closeConnection(
+    connectionId: string,
+    code?: number,
+    reason?: string
+  ): Promise<void>;
+  setConnectionState(connectionId: string, state: unknown): Promise<unknown>;
+  connectionTargetPath(
+    connection: Connection
+  ): ReadonlyArray<AgentPathStep> | null;
+  isSameAgentPath(
+    a: ReadonlyArray<AgentPathStep>,
+    b: ReadonlyArray<AgentPathStep>
+  ): boolean;
+  connectionHasChildTarget(connection: Connection): boolean;
+  connectionTargetsChild(connection: Connection): boolean;
+  requestTargetsChild(request: Request): boolean;
+  forwardWebSocketConnect(
+    connection: Connection,
+    request: Request,
+    options: {
+      gate: boolean;
+    }
+  ): Promise<boolean>;
+  forwardWebSocketMessage(
+    connection: Connection,
+    message: WSMessage,
+    replyBridge?: DynamicAgentConnectionBridge
+  ): Promise<boolean>;
+  forwardWebSocketClose(
+    connection: Connection,
+    code: number,
+    reason: string,
+    wasClean: boolean
+  ): Promise<boolean>;
+  handleWebSocketConnect(
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta
+  ): Promise<void>;
+  handleWebSocketMessage(
+    message: WSMessage,
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta,
+    replyBridge?: DynamicAgentConnectionBridge
+  ): Promise<void>;
+  handleWebSocketClose(
+    code: number,
+    reason: string,
+    wasClean: boolean,
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta
+  ): Promise<void>;
+  runWithBridge<T>(
+    bridge: DynamicAgentConnectionBridgeLike,
+    connectionId: string,
+    fn: () => Promise<T> | T
+  ): Promise<T>;
+  createBridgeConnection(meta: DynamicAgentConnectionMeta): Connection;
+  storeVirtualConnection(connection: Connection): void;
+  /**
+   * Restore the facet identity persisted by `init` (wake after
+   * hibernation), then best-effort hydrate the virtual connections
+   * from the root's WebSocket state.
+   */
+  restoreFacetContext(): Promise<void>;
+  hydrateConnectionsFromRoot(): Promise<void>;
+  getRawConnectionState(connection: Connection): unknown;
+  getForwardedState(connection: Connection): unknown;
+  /**
+   * Resolve the facet Fetcher for the match and forward the request to
+   * it with `/sub/{class}/{name}` stripped.
+   */
+  forward(
+    req: Request,
+    match: {
+      childClass: string;
+      childName: string;
+      remainingPath: string;
+    }
+  ): Promise<Response>;
+  /**
+   * Bridge used by `getSubAgentByName`: resolve the facet and dispatch
+   * one RPC method. Stateless — no cached references.
+   */
+  invoke(
+    className: string,
+    name: string,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
+  /**
+   * Bridge used by `parentAgent()` when the requested parent is itself
+   * a facet (and therefore has no top-level env namespace). The root
+   * receives the full root-first target path, then each hop delegates
+   * to the next facet using that facet's own `ctx.facets`.
+   */
+  invokePath(
+    path: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
+  invokeStubMethod(
+    stub: unknown,
+    className: string,
+    method: string,
+    args: unknown[]
+  ): Promise<unknown>;
+  /**
+   * Initialize the host agent as a facet in a single RPC. Runs entirely
+   * inside the child's isolate, so every storage write and `onStart()`
+   * I/O is owned by the child DO.
+   */
+  init(
+    name: string,
+    parentPath?: ReadonlyArray<{
+      className: string;
+      name: string;
+    }>,
+    identityName?: string
+  ): Promise<void>;
+  /** Remove a completed facet fiber from the root-side index. */
+  unregisterRun(
+    ownerPath: ReadonlyArray<AgentPathStep>,
+    runId: string
+  ): Promise<void>;
+}
+//#endregion
+//#region src/dynamic-agents/api.d.ts
+/**
+ * The public dynamic-agents capability surface, reached via
+ * `this.dynamicAgents` on an Agent.
+ *
+ * A dynamic agent is a facet-backed child: it runs in its own isolate
+ * with its own SQLite database, colocated with — and supervised by —
+ * its parent Agent. Use dynamic agents for code whose class or
+ * lifecycle the parent owns (dynamically-loaded/generated code,
+ * per-run tool agents, sandboxed components). For independent peers
+ * such as one-DO-per-chat, use `getAgentByName` instead.
+ *
+ * @experimental The API surface may change before stabilizing.
+ */
+declare class DynamicAgents {
+  #private;
+  /** @internal Constructed by Agent; do not instantiate directly. */
+  constructor(internal: DynamicAgentsInternal);
+  /**
+   * Get (creating or waking if needed) the dynamic agent of the given
+   * class and name, as a typed RPC stub. Idempotent — repeated calls
+   * with the same class and name return the same child.
+   *
+   * @experimental
+   */
+  get<T extends Agent>(
+    cls: DynamicAgentClass<T>,
+    name: string
+  ): Promise<DynamicAgentStub<T>>;
+  /**
+   * Forcefully abort a running dynamic agent. The child stops
+   * executing immediately and restarts on the next {@link get} call;
+   * its storage is preserved. Transitively aborts the child's own
+   * children. Pending RPC calls receive the reason as an error.
+   *
+   * @experimental
+   */
+  abort(cls: DynamicAgentClass, name: string, reason?: unknown): void;
+  /**
+   * Delete a dynamic agent: abort it if running, then permanently wipe
+   * its storage. Transitively deletes the child's own children.
+   *
+   * @experimental
+   */
+  delete(cls: DynamicAgentClass, name: string): Promise<void>;
+  /**
+   * Whether this agent has previously spawned (and not deleted) a
+   * dynamic agent of the given class and name. Backed by an
+   * auto-maintained SQLite registry in the parent's storage.
+   *
+   * @experimental
+   */
+  has<T extends Agent>(cls: DynamicAgentClass<T>, name: string): boolean;
+  has(className: string, name: string): boolean;
+  /**
+   * List known dynamic agents, optionally filtered by class. Reflects
+   * the registry rows written by {@link get} and removed by
+   * {@link delete}.
+   *
+   * @experimental
+   */
+  list<T extends Agent>(
+    cls: DynamicAgentClass<T>
+  ): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
+  list(className?: string): Array<{
+    className: string;
+    name: string;
+    createdAt: number;
+  }>;
+}
+//#endregion
+//#region src/core/events.d.ts
+interface Disposable {
+  dispose(): void;
+}
+type Event<T> = (listener: (e: T) => void) => Disposable;
+declare class Emitter<T> implements Disposable {
+  private _listeners;
+  readonly event: Event<T>;
+  fire(data: T): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/mcp/client/transports.d.ts
+/**
+ * @deprecated Use SSEClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ */
+declare class SSEEdgeClientTransport extends SSEClientTransport {
+  constructor(url: URL, options: SSEClientTransportOptions);
+}
+/**
+ * @deprecated Use StreamableHTTPClientTransport from @modelcontextprotocol/client instead. This alias will be removed in the next major version.
+ */
+declare class StreamableHTTPEdgeClientTransport extends StreamableHTTPClientTransport {
+  constructor(url: URL, options: StreamableHTTPClientTransportOptions);
+}
+//#endregion
+//#region src/mcp/server/worker-transport.d.ts
+/**
+ * Pluggable storage adapter for persisting `WorkerTransport` state across
+ * Durable Object hibernation / restart cycles.
+ *
+ * A typical implementation reads/writes a single key on `this.ctx.storage`
+ * inside a Durable Object or Agent.
+ */
+interface MCPStorageApi {
+  get(): Promise<TransportState | undefined> | TransportState | undefined;
+  set(state: TransportState): Promise<void> | void;
+}
+/** Shape of the persisted transport state. */
+interface TransportState {
+  sessionId?: string;
+  initialized: boolean;
+  initializeParams?: InitializeRequestParams;
+}
+interface WorkerTransportOptions extends WebStandardStreamableHTTPServerTransportOptions {
+  /**
+   * CORS options applied to every response and to OPTIONS preflight.
+   * Defaults: `origin: *`, expose `mcp-session-id`, allow the standard MCP
+   * methods/headers, max-age 86400.
+   */
+  corsOptions?: CORSOptions;
+  /**
+   * Optional storage adapter for persisting transport state across DO
+   * hibernation / restart. Use this to keep an MCP session alive across
+   * Durable Object wake-ups.
+   */
+  storage?: MCPStorageApi;
+}
+declare class WorkerTransport extends WebStandardStreamableHTTPServerTransport$1 {
+  private readonly _corsOptions?;
+  private readonly _storage?;
+  private _stateRestored;
+  private _capturedInitializeParams?;
+  private _userOnSessionInitialized?;
+  private _bridgeInstalled;
+  /**
+   * Request ids whose SSE stream was deliberately torn down via
+   * `closeSSEStream`. The SDK's `send()` throws "No connection established"
    * when a request id has no stream — a race that surfaces whenever the
    * server's tool handler resolves *after* the caller closed the stream
    * (e.g. polling-style early-close, or test fixtures closing mid-flight).
@@ -414,7 +1151,7 @@ declare class WorkerTransport extends WebStandardStreamableHTTPServerTransport$1
   private saveState;
 }
 //#endregion
-//#region src/mcp/handler-legacy.d.ts
+//#region src/mcp/server/handler-legacy.d.ts
 /** Options for the retained SDK v1, sessionful handler. */
 interface CreateLegacyMcpHandlerOptions extends WorkerTransportOptions {
   /** Exact route handled by this handler. @default "/mcp" */
@@ -437,11 +1174,11 @@ type LegacyMcpHandler = (
  * `agents/mcp/server` instead.
  */
 declare function createLegacyMcpHandler(
-  server: McpServer$1 | Server$2,
+  server: McpServer$1 | Server$1,
   options?: CreateLegacyMcpHandlerOptions
 ): LegacyMcpHandler;
 //#endregion
-//#region src/mcp/handler-compat.d.ts
+//#region src/mcp/server/handler-compat.d.ts
 /**
  * @deprecated Passing an SDK v1 server to createMcpHandler is deprecated and
  * will be removed in the next major version. Pass an SDK v2 factory to
@@ -449,7 +1186,7 @@ declare function createLegacyMcpHandler(
  * sessionful SDK v1 behavior while migrating.
  */
 declare function createMcpHandler$1(
-  server: McpServer$1 | Server$2,
+  server: McpServer$1 | Server$1,
   options?: CreateMcpHandlerOptions$1
 ): LegacyMcpHandler;
 declare function createMcpHandler$1(
@@ -463,11 +1200,11 @@ declare function createMcpHandler$1(
  * behavior while migrating.
  */
 declare function experimental_createMcpHandler(
-  server: McpServer$1 | Server$2,
+  server: McpServer$1 | Server$1,
   options?: CreateMcpHandlerOptions$1
 ): LegacyMcpHandler;
 //#endregion
-//#region src/mcp/event-store.d.ts
+//#region src/mcp/server/event-store.d.ts
 /**
  * Durable Object–backed {@link EventStore} for SSE resumability.
  *
@@ -546,7 +1283,7 @@ declare class DurableObjectEventStore implements EventStore {
   private ensureSeqLoaded;
 }
 //#endregion
-//#region src/mcp/transport.d.ts
+//#region src/mcp/server/transport.d.ts
 /**
  * An {@link EventStore} that supports dropping all events for a single
  * stream id. Implemented by {@link DurableObjectEventStore}.
@@ -555,7 +1292,7 @@ interface ClearableEventStore extends EventStore$1 {
   clearStream(streamId: StreamId$1): Promise<void>;
 }
 //#endregion
-//#region src/mcp/legacy-agent.d.ts
+//#region src/mcp/server/legacy-agent.d.ts
 /**
  * @deprecated McpAgent is feature-frozen. Migrate to an SDK v2 factory with
  * createMcpHandler from agents/mcp/server. When sessionful features prevent an
@@ -571,10 +1308,10 @@ declare abstract class McpAgent<
   private _pendingElicitations;
   props?: Props;
   shouldSendProtocolMessages(
-    _connection: Connection$1,
-    ctx: ConnectionContext$1
+    _connection: Connection,
+    ctx: ConnectionContext
   ): boolean;
-  abstract server: MaybePromise<McpServer$1 | Server$2>;
+  abstract server: MaybePromise<McpServer$1 | Server$1>;
   abstract init(): Promise<void>;
   setInitializeRequest(initializeRequest: JSONRPCMessage$1): Promise<void>;
   getInitializeRequest(): Promise<JSONRPCMessage$1 | undefined>;
@@ -628,7 +1365,7 @@ declare abstract class McpAgent<
    */
   getSessionId(): string;
   /** Get the unique WebSocket. SSE transport only. */
-  getWebSocket(): Connection$1<unknown> | null;
+  getWebSocket(): Connection<unknown> | null;
   /**
    * Returns options for configuring the RPC server transport.
    * Override this method to customize RPC transport behavior (e.g., timeout).
@@ -667,8 +1404,8 @@ declare abstract class McpAgent<
   onStart(props?: Props): Promise<void>;
   /** Validates new WebSocket connections. */
   onConnect(
-    conn: Connection$1,
-    { request: req }: ConnectionContext$1
+    conn: Connection,
+    { request: req }: ConnectionContext
   ): Promise<void>;
   /** Handles MCP Messages for the legacy SSE transport. */
   onSSEMcpMessage(
@@ -817,7 +1554,7 @@ declare class RPCServerTransport implements Transport$1 {
   ): Promise<JSONRPCMessage$2 | JSONRPCMessage$2[] | undefined>;
 }
 //#endregion
-//#region src/mcp/client-connection.d.ts
+//#region src/mcp/client/connection.d.ts
 /**
  * Connection state machine for MCP client connections.
  *
@@ -1823,7 +2560,7 @@ declare class MCPClientConnection {
   private _capabilityErrorHandler;
 }
 //#endregion
-//#region src/mcp/client-storage.d.ts
+//#region src/mcp/client/storage.d.ts
 /**
  * Represents a row in the cf_agents_mcp_servers table.
  */
@@ -1873,7 +2610,7 @@ type PersistedMcpServerOptions = {
   capabilities?: ClientCapabilities;
 };
 //#endregion
-//#region src/mcp/client.d.ts
+//#region src/mcp/client/index.d.ts
 type MCPAITool = {
   description?: string;
   title?: string;
@@ -1997,9 +2734,14 @@ type MCPClientElicitationHandlers = {
   form?: MCPClientElicitationHandler;
   url?: MCPClientElicitationHandler;
 };
+/** Dependencies used by {@link MCPClientManager} across Durable Object wakes. */
 type MCPClientManagerOptions = {
-  storage: DurableObjectStorage;
-  createAuthProvider?: (callbackUrl: string) => AgentMcpOAuthProvider;
+  /**
+   * Runtime bindings used to restore persisted RPC MCP connections.
+   * Required when the durable catalog contains `rpc://` servers.
+   */
+  readonly env?: Cloudflare.Env /** Construct the OAuth provider used for a persisted HTTP server. */;
+  readonly createAuthProvider?: (callbackUrl: string) => AgentMcpOAuthProvider;
 };
 /**
  * Filter options for scoping tools, prompts, resources, and resource templates
@@ -2015,19 +2757,21 @@ type MCPServerFilter = {
   state?: MCPConnectionState | MCPConnectionState[];
 };
 /**
- * Utility class that aggregates multiple MCP clients into one
+ * A Durable Object capability that persists and aggregates MCP client
+ * connections. Installing it directly on a Lifecycle (outside `agent.mcp`)
+ * is experimental: that capability surface may change before stabilizing.
  */
-declare class MCPClientManager {
-  private _name;
-  private _version;
+declare class MCPClientManager extends LifecycleCapability {
+  private readonly _name;
+  private readonly _version;
   mcpConnections: Record<string, MCPClientConnection>;
   /** Cache only the current catalog so old schema graphs are not retained. */
   private readonly _aiToolSchemas;
   private _didWarnAboutUnstableGetAITools;
   private _oauthCallbackConfig?;
   private _connectionDisposables;
-  private _storage;
-  private _createAuthProviderFn?;
+  private readonly _env;
+  private readonly _createAuthProviderFn;
   private _isRestored;
   private _pendingConnections;
   private _elicitationHandlers?;
@@ -2041,15 +2785,22 @@ declare class MCPClientManager {
    */
   readonly onServerStateChanged: Event<void>;
   /**
-   * @param _name Name of the MCP client
-   * @param _version Version of the MCP Client
-   * @param options Storage adapter for persisting MCP server state
+   * Construct a reusable Durable Object MCP client capability.
+   *
+   * @param _name - MCP client implementation name sent during negotiation.
+   * @param _version - MCP client implementation version sent during negotiation.
+   * @param options - Optional runtime bindings and OAuth configuration.
    */
   constructor(
     _name: string,
     _version: string,
-    options: MCPClientManagerOptions
+    options?: MCPClientManagerOptions
   );
+  /** Restore persisted HTTP and RPC connections before the host handles work. */
+  onStart(): Promise<void>;
+  /** Intercept a registered MCP OAuth callback request. */
+  onRequest(context: CapabilityRequestContext): Promise<Response | undefined>;
+  private oauthCallbackResponse;
   /**
    * Scope the manager-level elicitation handler to a single connection.
    * Returns undefined when no handler is configured so the connection keeps
@@ -2118,15 +2869,12 @@ declare class MCPClientManager {
    * @internal
    */
   private createAuthProvider;
-  /**
-   * Get saved RPC servers from storage (servers with rpc:// URLs).
-   * These are restored separately by the Agent class since they need env bindings.
-   */
+  /** Get saved RPC servers from storage (servers with `rpc://` URLs). */
   getRpcServersFromStorage(): MCPServerRow[];
   /**
    * Save an RPC server to storage for hibernation recovery.
-   * The bindingName is stored in server_options so the Agent can look up
-   * the namespace from env during restore.
+   * The binding name is stored so this manager can resolve the namespace from
+   * its runtime environment during restore.
    */
   saveRpcServerToStorage(
     id: string,
@@ -2136,12 +2884,9 @@ declare class MCPClientManager {
     props?: Record<string, unknown>
   ): void;
   /**
-   * Restore MCP server connections from storage
-   * This method is called on Agent initialization to restore previously connected servers.
-   * RPC servers (rpc:// URLs) are skipped here -- they are restored by the Agent class
-   * which has access to env bindings.
+   * Restore persisted HTTP MCP connections.
    *
-   * @param clientName Name to use for OAuth client (typically the agent instance name)
+   * @param clientName - Durable Object identity used to scope OAuth state.
    */
   restoreConnectionsFromStorage(clientName: string): Promise<void>;
   /**
@@ -2855,351 +3600,567 @@ declare class WorkflowRejectedError extends Error {
   constructor(reason?: string | undefined, workflowId?: string | undefined);
 }
 //#endregion
-//#region src/index.d.ts
-/**
- * Structural type for Cloudflare's `send_email` binding.
- * Accepts both raw MIME messages and structured builder objects.
- */
-type EmailSendBinding = {
-  send(
-    message:
-      | EmailMessage
-      | {
-          from:
-            | string
-            | {
-                email: string;
-                name?: string;
-              };
-          to: string | string[];
-          subject: string;
-          replyTo?:
-            | string
-            | {
-                email: string;
-                name?: string;
-              };
-          cc?: string | string[];
-          bcc?: string | string[];
-          headers?: Record<string, string>;
-          text?: string;
-          html?: string;
-        }
-  ): Promise<EmailSendResult>;
-};
+//#region src/agent-tool-types.d.ts
+type AgentToolRunStatus =
+  | "starting"
+  | "running"
+  | "completed"
+  | "error"
+  | "aborted"
+  | "interrupted";
+type AgentToolTerminalStatus = Extract<
+  AgentToolRunStatus,
+  "completed" | "error" | "aborted" | "interrupted"
+>;
 /**
- * Options for Agent.sendEmail()
- */
-type SendEmailOptions = {
-  binding: EmailSendBinding;
-  to: string | string[];
-  from:
-    | string
-    | {
-        email: string;
-        name?: string;
-      };
-  subject: string;
-  text?: string;
-  html?: string;
-  replyTo?:
-    | string
-    | {
-        email: string;
-        name?: string;
-      };
-  cc?: string | string[];
-  bcc?: string | string[];
-  inReplyTo?: string;
-  headers?: Record<string, string>;
-  secret?: string;
-};
-/**
- * RPC request message from client
+ * Machine-readable cause of an `interrupted` seal (#1630 follow-up). Lets a
+ * caller branch on WHY a run was abandoned without parsing the human-readable
+ * `error` prose, which is not a stable contract.
+ *
+ * - `no-progress` — the child went silent for a full no-progress window while
+ *   the parent was tailing it (genuinely stalled / hung).
+ * - `window-exceeded` — a finite `agentToolReattachMaxWindowMs` ceiling elapsed
+ *   while the child was still non-terminal. Only fires when an integrator opts
+ *   into a hard wall-clock cap (the default ceiling is `Infinity`).
+ * - `not-tailable` — the child runtime cannot live-tail, so the parent could
+ *   not re-attach to its stream to follow it to terminal.
+ * - `inspect-timeout` — inspecting the child timed out during parent recovery.
+ * - `inspect-failed` — inspecting the child failed during parent recovery.
+ * - `recovery-deadline` — the overall parent-recovery deadline elapsed before
+ *   this run could be reconciled.
+ * - `budget-exceeded` — a detached run's absolute `maxBudgetMs` ceiling elapsed
+ *   before it reached a terminal. The parent gave up watching and tore the
+ *   child down. Like `window-exceeded` this is a soft seal: a child that
+ *   completes anyway can still repair the run and re-fire the completion hook.
  */
-type RPCRequest = {
-  type: "rpc";
-  id: string;
-  method: string;
-  args: unknown[];
-};
+type AgentToolInterruptedReason =
+  | "no-progress"
+  | "window-exceeded"
+  | "not-tailable"
+  | "inspect-timeout"
+  | "inspect-failed"
+  | "recovery-deadline"
+  | "budget-exceeded";
 /**
- * State update message from client
+ * 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 StateUpdateMessage = {
-  type: MessageType.CF_AGENT_STATE;
-  state: unknown;
+type AgentToolFailure = {
+  ok: false;
+  status: Exclude<AgentToolTerminalStatus, "completed">;
+  error: string;
+  retryable: boolean /** Present only when `status` is `interrupted` — machine-readable cause. */;
+  reason?: AgentToolInterruptedReason;
+  /**
+   * Present only when `status` is `interrupted`. `true` when the child facet was
+   * still non-terminal (running / advancing) at the moment the parent stopped
+   * waiting; `false` once the parent has torn the child down so it is no longer
+   * doing work. Lets a caller decide between re-dispatching vs. reconnecting.
+   */
+  childStillRunning?: boolean;
 };
+type AgentToolDisplayMetadata = {
+  name?: string;
+  icon?: string;
+} & Record<string, unknown>;
 /**
- * RPC response message to client
+ * Reserved chunk type a sub-agent emits via `reportProgress` while it runs.
+ * Rides the child's own UI-message stream as a **transient** data part, so it
+ * re-broadcasts to the parent's clients (via the parent's tail) and surfaces in
+ * `useAgentToolEvents` without persisting into the child's stored message parts.
+ * See `design/rfc-detached-agent-tools.md` §"Progress and milestone signaling".
  */
-type RPCResponse = {
-  type: MessageType.RPC;
-  id: string;
-} & (
-  | {
-      success: true;
-      result: unknown;
-      done?: false;
-    }
-  | {
-      success: true;
-      result: unknown;
-      done: true;
-    }
-  | {
-      success: false;
-      error: string;
-    }
-);
+declare const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
 /**
- * Metadata for a callable method
+ * Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.
+ * Unlike the ephemeral progress part this rides the child's stream as a
+ * **persisted** data part, so it survives eviction, replays on drill-in, and
+ * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
  */
-type CallableMetadata = {
-  /** Optional description of what the method does */ description?: string /** Whether the method supports streaming responses */;
-  streaming?: boolean;
-};
+declare const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
 /**
- * Error class for SQL execution failures, containing the query that failed
+ * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The
+ * well-known fields drive generic UI (a bar + status line) with no per-app
+ * convention; `data` is an app-specific escape hatch that is **live-only** by
+ * default (not persisted) unless `reportProgress(p, { persist: true })`. Naming a
+ * `milestone` promotes the signal to the **durable** tier: it persists as one row
+ * per milestone, replays, and (with `data`) is retained.
  */
-declare class SqlError extends Error {
-  /** The SQL query that failed */
-  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;
+type AgentToolProgress<T = unknown> = {
+  /** 0..1 — drives a progress bar. */ fraction?: number /** Human-readable status line, e.g. "Ingested 40k/80k rows". */;
+  message?: string /** Coarse stage label, e.g. "scaffolding" | "deploying". */;
+  phase?: string;
+  /**
+   * Present ⇒ a **durable** milestone: persisted, replayable, and surfaced as a
+   * distinct row in `AgentToolRunState.milestones` / `inspectAgentToolRun`. Use
+   * for named phase boundaries ("schema-ready", "preview-ready", "deployed").
+   */
+  milestone?: string /** App-specific payload; live-only for progress, persisted for milestones. */;
+  data?: T;
 };
-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
- * via `ctx.exports`.
- *
- * The class name (`cls.name`) must match the export name in the
- * worker entry point — re-exports under a different name
- * (e.g. `export { Foo as Bar }`) are not supported.
+ * A durable milestone a sub-agent reached, projected onto `AgentToolRunState`
+ * and `inspectAgentToolRun`. `sequence` is monotonic per run so replay/live
+ * races dedupe on `(runId, sequence)`.
  */
-type SubAgentClass<T extends Agent = Agent> = {
-  new (ctx: DurableObjectState, env: never): T;
+type AgentToolMilestone = {
+  name: string /** Monotonic per-run ordinal; dedupe key for replay vs live races. */;
+  sequence: number /** Epoch ms the milestone was reached. */;
+  at: number /** App-specific payload carried with the milestone (persisted). */;
+  data?: unknown;
 };
 /**
- * Wraps `T` in a `Promise` unless it already is one.
- */
-type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
-/**
- * A typed RPC stub for a sub-agent. Exposes all public instance methods
- * as callable RPC methods with Promise-wrapped return types.
- *
- * Methods inherited from `Agent` / `Server` / `DurableObject` internals
- * are excluded — only user-defined methods on the subclass are exposed.
+ * Latest progress snapshot persisted on the child run row and surfaced through
+ * `inspectAgentToolRun` + `AgentToolRunState`. Only the safe-to-inspect fields
+ * are retained by default; `at` is the emit timestamp (drives the resetting
+ * no-progress budget).
  */
-type SubAgentStub<T extends Agent> = {
-  [K in keyof T as K extends keyof Agent
-    ? never
-    : T[K] extends (...args: never[]) => unknown
-      ? K
-      : never]: T[K] extends (...args: infer A) => infer R
-    ? (...args: A) => Promisify<R>
-    : never;
+type AgentToolProgressSnapshot = {
+  fraction?: number;
+  message?: string;
+  phase?: string;
+  /**
+   * Set when this signal was a durable milestone (`reportProgress({ milestone })`).
+   * Lets an `onProgress` consumer branch on milestone vs. ephemeral progress.
+   */
+  milestone?: string /** Epoch ms of the latest signal. */;
+  at: number /** Present only when the emitter opted into persisting `data`. */;
+  data?: unknown;
 };
-/**
- * Decorator that marks a method as callable by clients
- * @param metadata Optional metadata about the callable method
- */
-declare function callable(
-  metadata?: CallableMetadata
-): <This, Args extends unknown[], Return>(
-  target: (this: This, ...args: Args) => Return,
-  _context: ClassMethodDecoratorContext
-) => (this: This, ...args: Args) => Return;
-/**
- * Decorator that marks a method as callable by clients
- * @deprecated this has been renamed to callable, and unstable_callable will be removed in the next major version
- * @param metadata Optional metadata about the callable method
- */
-declare const unstable_callable: (
-  metadata?: CallableMetadata
-) => <This, Args extends unknown[], Return>(
-  target: (this: This, ...args: Args) => Return,
-  _context: ClassMethodDecoratorContext
-) => (this: This, ...args: Args) => Return;
-type QueueItem<T = string> = {
-  id: string;
-  payload: T;
-  callback: keyof Agent<Cloudflare.Env>;
-  created_at: number;
-  retry?: RetryOptions;
+type AgentToolRunInfo = {
+  runId: string;
+  parentToolCallId?: string;
+  agentType: string;
+  inputPreview?: unknown;
+  status: AgentToolRunStatus;
+  display?: AgentToolDisplayMetadata;
+  /**
+   * Caller-controlled `metadata.source` for chat-agent `detached.notify`
+   * completions. Present only for detached notify runs that supplied one.
+   */
+  notifySource?: string;
+  displayOrder: number;
+  startedAt: number;
+  completedAt?: number;
+};
+type AgentToolLifecycleResult = {
+  status: AgentToolTerminalStatus;
+  summary?: string;
+  error?: string /** Present only when `status` is `interrupted` — machine-readable cause. */;
+  reason?: AgentToolInterruptedReason;
+  /**
+   * Present only when `status` is `interrupted`. Whether the child facet was
+   * still non-terminal when the parent stopped waiting (before any teardown).
+   */
+  childStillRunning?: boolean;
 };
 /**
- * Represents a scheduled task within an Agent
- * @template T Type of the payload data
+ * Configuration for a detached ("background") agent-tool run. See
+ * `design/rfc-detached-agent-tools.md`.
+ *
+ * Callbacks are referenced by **method name** on the dispatching agent (the same
+ * durable, eviction-surviving pattern as `Agent.schedule`) — never closures,
+ * which cannot be rehydrated after the Durable Object is evicted.
+ *
+ * `Self` is threaded from `runAgentTool(cls, options)` so the method names are
+ * type-checked against the calling agent's own methods.
  */
-type Schedule<T = string> = {
-  /** Unique identifier for the schedule */ id: string /** Name of the method to be called */;
-  callback: string /** Data to be passed to the callback */;
-  payload: T /** Retry options for callback execution */;
-  retry?: RetryOptions;
-} & (
-  | {
-      /** Type of schedule for one-time execution at a specific time */ type: "scheduled" /** Timestamp when the task should execute */;
-      time: number;
-    }
-  | {
-      /** Type of schedule for delayed execution */ type: "delayed" /** Timestamp when the task should execute */;
-      time: number /** Number of seconds to delay execution */;
-      delayInSeconds: number;
-    }
-  | {
-      /** Type of schedule for recurring execution based on cron expression */ type: "cron" /** Timestamp for the next execution */;
-      time: number /** Cron expression defining the schedule */;
-      cron: string;
-    }
-  | {
-      /** Type of schedule for recurring execution at fixed intervals */ type: "interval" /** Timestamp for the next execution */;
-      time: number /** Number of seconds between executions */;
-      intervalSeconds: number;
-    }
-);
-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 DetachedReconcilePayload = {
-  cadenceIndex?: number;
+type DetachedAgentToolConfig<Self = Record<string, unknown>> = {
+  /**
+   * Method invoked once per terminal delivery. Branch on `result.status`:
+   * `"completed" | "error" | "aborted" | "interrupted"`. A budget give-up
+   * arrives as `status: "interrupted"` with `reason: "budget-exceeded"`; because
+   * `interrupted` is soft, a child that later completes can fire the hook again
+   * with `"completed"`, so a give-up never hides a late real result. Make the
+   * handler idempotent.
+   */
+  onFinish?: Extract<keyof Self, string>;
+  /**
+   * Absolute safety ceiling — a backstop against a child that runs forever. On
+   * expiry the parent gives up watching (delivers `onFinish` with
+   * `interrupted` / `budget-exceeded`) and tears the child down. Defaults to the
+   * parent-level `detachedMaxBudgetMs`.
+   */
+  maxBudgetMs?: number;
+  /**
+   * Per-run override of the resetting no-progress window (ms). Once the child
+   * emits its first `reportProgress`, the parent gives up if it then goes silent
+   * for this long (resets on each signal). Defaults to the parent-level
+   * `detachedNoProgressBudgetMs` (1h). `0`/`Infinity` disables it.
+   */
+  noProgressBudgetMs?: number;
+  /**
+   * Chat-agent convenience (`@cloudflare/think` / `AIChatAgent`): when the run
+   * finishes, inject a message into the chat so the model can react to the
+   * result, instead of you wiring `onFinish` by hand. Sugar that auto-targets
+   * the agent's `_cfDetachedNotifyFinish` hook; ignored on a base `Agent` that
+   * does not implement it, and ignored when `onFinish` is also set (an explicit
+   * `onFinish` wins). Pass `{ source }` to fit the injected message into your
+   * app's existing metadata taxonomy. Override `formatDetachedCompletion()` to
+   * customize the injected text.
+   */
+  notify?:
+    | boolean
+    | {
+        source?: string;
+      };
+  /**
+   * Chat-agent convenience: milestone names that, when the detached run reaches
+   * them, surface an idempotent synthetic message in the chat BEFORE the run
+   * finishes. Each `(runId, name)` fires at most once (idempotency-keyed),
+   * whether observed live or reconciled after eviction. Override the wording via
+   * `formatDetachedMilestone()`. Requires a chat host (`@cloudflare/think`); a
+   * no-op on a base `Agent`.
+   *
+   * Two delivery modes (the string-array shorthand defaults to `"narrate"`):
+   * - `"narrate"` (default) — inject a synthetic **assistant** message directly
+   *   (no inference): a cheap, honest status line ("Found 2 sources…") that does
+   *   not trigger a model turn. Best for pure progress narration.
+   * - `"react"` — inject a **user-role** turn so the model responds to the
+   *   milestone (steer, start dependent work, narrate with context). Costs a
+   *   model turn. Opt in for milestones the agent should *act on*.
+   */
+  onMilestones?:
+    | string[]
+    | {
+        names: string[];
+        mode?: "react" | "narrate";
+      };
 };
-type ScheduleCriteria = {
-  id?: string;
-  type?: "scheduled" | "delayed" | "cron" | "interval";
-  timeRange?: {
-    start?: Date;
-    end?: Date;
-  };
+type RunAgentToolOptions<Input = unknown, Self = Record<string, unknown>> = {
+  input: Input;
+  runId?: string;
+  parentToolCallId?: string;
+  displayOrder?: number;
+  signal?: AbortSignal;
+  inputPreview?: unknown;
+  display?: AgentToolDisplayMetadata;
+  /**
+   * Run the sub-agent **detached**: dispatch it, let the current turn continue,
+   * and (optionally) get a durable callback when it finishes. `true` is
+   * fire-and-forget (observe via `agent-tool-event` frames + the global
+   * `onAgentToolFinish` hook); an object adds the targeted, eviction-surviving
+   * `onFinish` callback. A detached run does NOT inherit `options.signal` — it
+   * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.
+   */
+  detached?: boolean | DetachedAgentToolConfig<Self>;
 };
 /**
- * Context passed to the `runFiber` callback. Provides checkpoint
- * and identity for durable execution.
+ * Result of dispatching a detached run. Returns immediately after dispatch
+ * rather than after completion.
  */
-type FiberContext = {
-  /** Unique identifier for this fiber execution. */ id: string /** Cooperative cancellation signal for managed fiber callers. */;
-  signal: AbortSignal /** Checkpoint data during execution. Synchronous SQLite write. */;
-  stash(
-    data: unknown
-  ): void /** Currently null during execution; recovered snapshots are passed to onFiberRecovered(). */;
-  snapshot: unknown | null;
+type DetachedRunAgentToolResult = {
+  runId: string;
+  agentType: string;
+  /**
+   * `"running"` on a successful dispatch; `"error"` if dispatch itself failed
+   * (e.g. the `maxConcurrentAgentTools` cap was exceeded — rejected
+   * synchronously, no child started, no callback wired).
+   */
+  status: "running" | "error";
+  error?: string;
 };
-type FiberStatus =
-  | "pending"
-  | "running"
-  | "completed"
-  | "aborted"
-  | "interrupted"
-  | "error";
-type StartFiberOptions = {
-  fiberId?: string;
-  idempotencyKey?: string;
-  metadata?: Record<string, unknown>;
-  waitForCompletion?: boolean;
+type RunAgentToolResult<Output = unknown> = {
+  runId: string;
+  agentType: string;
+  status: AgentToolTerminalStatus;
+  output?: Output;
+  summary?: string;
+  error?: string;
+  /**
+   * Present only when `status` is `interrupted` — a machine-readable cause so
+   * callers don't pattern-match the `error` prose (#1630 follow-up).
+   */
+  reason?: AgentToolInterruptedReason;
+  /**
+   * Present only when `status` is `interrupted`. `true` when the child facet was
+   * still non-terminal (running / advancing) at the moment the parent stopped
+   * waiting and before any teardown; `false` once the parent has torn the child
+   * down so it is no longer doing work.
+   */
+  childStillRunning?: boolean;
 };
-type FiberInspection = {
-  fiberId: string;
-  name: string;
-  idempotencyKey?: string;
-  status: FiberStatus;
-  snapshot?: unknown;
+type ChatCapableAgentClass<T extends Agent = Agent> = DynamicAgentClass<T>;
+type AgentToolRunInspection<Output = unknown> = {
+  runId: string;
+  status: Exclude<AgentToolRunStatus, "interrupted">;
+  requestId?: string;
+  streamId?: string;
+  output?: Output;
+  summary?: string;
   error?: string;
-  metadata?: Record<string, unknown>;
-  createdAt: number;
-  startedAt?: number;
-  settledAt?: number;
+  startedAt: number;
+  completedAt?: number;
+  /**
+   * Latest progress snapshot the child has persisted, so a rehydrated parent
+   * (recovery / backbone reconcile) can reconstruct "where is this run" and
+   * reset the resetting no-progress budget without having tailed the live
+   * stream. Absent until the child emits its first `reportProgress`.
+   */
+  progress?: AgentToolProgressSnapshot;
+  /**
+   * Durable milestones the child has persisted, ordered by `sequence`. Lets a
+   * rehydrated parent (recovery / backbone reconcile) replay milestone-gated
+   * work and milestone notifications without having observed the live stream.
+   */
+  milestones?: AgentToolMilestone[];
 };
-type StartFiberResult = FiberInspection & {
-  accepted: boolean;
+type AgentToolStoredChunk = {
+  sequence: number;
+  body: string;
 };
-type FiberRecoveryResult =
+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 =
   | {
-      status: "completed";
-      snapshot?: unknown;
-      metadata?: Record<string, unknown>;
+      kind: "started";
+      runId: string;
+      agentType: string;
+      inputPreview?: unknown;
+      order: number;
+      display?: AgentToolDisplayMetadata;
     }
   | {
-      status: "error";
-      error?: unknown;
-      snapshot?: unknown;
+      kind: "chunk";
+      runId: string;
+      body: string;
     }
   | {
-      status: "aborted";
-      reason?: string;
-      snapshot?: unknown;
+      kind: "finished";
+      runId: string;
+      summary: string;
     }
   | {
-      status: "interrupted";
+      kind: "error";
+      runId: string;
+      error: string;
+    }
+  | {
+      kind: "aborted";
+      runId: string;
       reason?: string;
-      snapshot?: unknown;
+    }
+  | {
+      kind: "interrupted";
+      runId: string;
+      error: string /** Machine-readable cause of the interrupt (#1630 follow-up). */;
+      reason?: AgentToolInterruptedReason;
+      /**
+       * Whether the child facet was still non-terminal when the parent stopped
+       * waiting (before any teardown). Lets a UI distinguish a still-running
+       * child from one the parent has torn down.
+       */
+      childStillRunning?: boolean;
     };
-type ListFibersOptions = {
-  status?: FiberStatus | FiberStatus[];
-  name?: string;
-  limit?: number;
-};
-type DeleteFibersOptions = {
-  status?: FiberStatus | FiberStatus[];
+type AgentToolEventMessage = {
+  type: "agent-tool-event";
+  parentToolCallId?: string;
+  sequence: number;
+  replay?: true;
+  event: AgentToolEvent;
+};
+type AgentToolRunPart = {
+  type: string;
+};
+type AgentToolRunState<Part extends AgentToolRunPart = AgentToolRunPart> = {
+  runId: string;
+  agentType: string;
+  parentToolCallId?: string;
+  inputPreview?: unknown;
+  order: number;
+  display?: AgentToolDisplayMetadata;
+  status: "running" | "completed" | "error" | "aborted" | "interrupted";
+  /**
+   * Message parts reconstructed from the child agent's streamed chunks.
+   *
+   * The default stays framework-neutral so importing `agents` does not require
+   * an AI SDK peer. AI SDK consumers can use
+   * `AgentToolRunState<UIMessage["parts"][number]>` when they need its exact
+   * discriminated union.
+   */
+  parts: Part[];
+  summary?: string;
+  error?: string;
+  /**
+   * Present only when `status` is `interrupted` — machine-readable cause and
+   * whether the child is still running, mirrored from the wire event so a UI
+   * can render the reason without parsing `error` (#1630 follow-up).
+   */
+  reason?: AgentToolInterruptedReason;
+  childStillRunning?: boolean;
+  /**
+   * Latest progress snapshot, projected from the child's transient
+   * `data-agent-progress` signals so a UI can render a bar / ETA / phase label
+   * for a running (especially detached / background) run without drilling in.
+   */
+  progress?: AgentToolProgressSnapshot;
+  /**
+   * Durable milestones the run has reached, ordered by `sequence` (deduped
+   * across replay/live races). Drives milestone chips / a phase timeline.
+   */
+  milestones?: AgentToolMilestone[];
+  subAgent: {
+    agent: string;
+    name: string;
+  };
+};
+type AgentToolEventState<Part extends AgentToolRunPart = AgentToolRunPart> = {
+  runsById: Record<string, AgentToolRunState<Part>>;
+  runsByToolCallId: Record<string, AgentToolRunState<Part>[]>;
+  unboundRuns: AgentToolRunState<Part>[];
+};
+//#endregion
+//#region src/index.d.ts
+/**
+ * RPC request message from client
+ */
+type RPCRequest = {
+  type: "rpc";
+  id: string;
+  method: string;
+  args: unknown[];
+};
+/**
+ * State update message from client
+ */
+type StateUpdateMessage = {
+  type: MessageType.CF_AGENT_STATE;
+  state: unknown;
+};
+/**
+ * RPC response message to client
+ */
+type RPCResponse = {
+  type: MessageType.RPC;
+  id: string;
+} & (
+  | {
+      success: true;
+      result: unknown;
+      done?: false;
+    }
+  | {
+      success: true;
+      result: unknown;
+      done: true;
+    }
+  | {
+      success: false;
+      error: string;
+    }
+);
+type QueueItem<T = string> = {
+  id: string;
+  payload: T;
+  callback: keyof Agent<Cloudflare.Env>;
+  created_at: number;
+  retry?: RetryOptions;
+};
+type DetachedReconcilePayload = {
+  cadenceIndex?: number;
+};
+/**
+ * Context passed to the `runFiber` callback. Provides checkpoint
+ * and identity for durable execution.
+ */
+type FiberContext = {
+  /** Unique identifier for this fiber execution. */ id: string /** Cooperative cancellation signal for managed fiber callers. */;
+  signal: AbortSignal /** Checkpoint data during execution. Synchronous SQLite write. */;
+  stash(
+    data: unknown
+  ): void /** Currently null during execution; recovered snapshots are passed to onFiberRecovered(). */;
+  snapshot: unknown | null;
+};
+type FiberStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "aborted"
+  | "interrupted"
+  | "error";
+type StartFiberOptions = {
+  fiberId?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+  waitForCompletion?: boolean;
+};
+type FiberInspection = {
+  fiberId: string;
+  name: string;
+  idempotencyKey?: string;
+  status: FiberStatus;
+  snapshot?: unknown;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+  startedAt?: number;
+  settledAt?: number;
+};
+type StartFiberResult = FiberInspection & {
+  accepted: boolean;
+};
+type FiberRecoveryResult =
+  | {
+      status: "completed";
+      snapshot?: unknown;
+      metadata?: Record<string, unknown>;
+    }
+  | {
+      status: "error";
+      error?: unknown;
+      snapshot?: unknown;
+    }
+  | {
+      status: "aborted";
+      reason?: string;
+      snapshot?: unknown;
+    }
+  | {
+      status: "interrupted";
+      reason?: string;
+      snapshot?: unknown;
+    };
+type ListFibersOptions = {
+  status?: FiberStatus | FiberStatus[];
+  name?: string;
+  limit?: number;
+};
+type DeleteFibersOptions = {
+  status?: FiberStatus | FiberStatus[];
   settledBefore?: Date;
   limit?: number;
 };
@@ -3329,8 +4290,7 @@ type AddRpcMcpServerOptions = {
  * Child classes can override specific options without spreading.
  */
 declare const DEFAULT_AGENT_STATIC_OPTIONS: {
-  /** Whether the Agent should hibernate when inactive */ hibernate: boolean /** Whether to send identity (name, agent) to clients on connect */;
-  sendIdentityOnConnect: boolean;
+  /** Whether to send identity (name, agent) to clients on connect */ sendIdentityOnConnect: boolean;
   /**
    * Timeout in seconds before a running interval schedule is considered "hung"
    * and force-reset. Increase this if you have callbacks that legitimately
@@ -3391,10 +4351,8 @@ declare const DEFAULT_AGENT_STATIC_OPTIONS: {
  * Configuration options for the Agent.
  * Override in subclasses via `static options`.
  * All fields are optional - defaults are applied at runtime.
- * Note: `hibernate` defaults to `true` if not specified.
  */
 interface AgentStaticOptions {
-  hibernate?: boolean;
   sendIdentityOnConnect?: boolean;
   hungScheduleTimeoutSeconds?: number;
   /**
@@ -3488,14 +4446,10 @@ interface AgentStaticOptions {
    */
   maxAlarmMemoryLimitStrikes?: number;
 }
-declare function getCurrentAgent<
-  T extends Agent<Cloudflare.Env> = Agent<Cloudflare.Env>
->(): {
-  agent: T | undefined;
-  connection: Connection | undefined;
-  request: Request | undefined;
-  email: AgentEmail | undefined;
-};
+/** Compatibility alias for the lifecycle-owned current Agent accessor. */
+declare const getCurrentAgent: <
+  T extends DurableObject = Agent<Cloudflare.Env>
+>() => CurrentAgentContext<T, AgentEmail>;
 /**
  * Extract string keys from Env where the value is a Workflow binding.
  */
@@ -3518,7 +4472,49 @@ declare class Agent<
   Env extends Cloudflare.Env = Cloudflare.Env,
   State = unknown,
   Props extends Record<string, unknown> = Record<string, unknown>
-> extends Server<Env, Props> {
+> extends DurableObject<Env> {
+  /**
+   * Runtime lifecycle and reusable durable capabilities for this Agent.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  readonly lifecycle: Lifecycle<Env, Props>;
+  /**
+   * WebSocket connection subsystem. Constructed as a field initializer
+   * so it exists before the constructor installs it; the handler arrows
+   * defer to `this.*`, so they always hit the framework-wrapped hooks.
+   * Those wrappers still open their own invocation scope even though
+   * the capability's dispatch already entered one via the host invoker
+   * — the inner wrap is kept because the wrapped hooks are also invoked
+   * from paths that do not pass through the capability (facet bridging,
+   * direct calls).
+   */
+  private readonly _webSockets;
+  /** Run user initialization after lifecycle components have started. */
+  onStart(_props?: Props): void | Promise<void>;
+  /** Handle an HTTP request not claimed by a lifecycle component. */
+  onRequest(_request: Request): Response | Promise<Response>;
+  /** Handle a newly accepted hibernating WebSocket connection. */
+  onConnect(
+    _connection: Connection,
+    _context: ConnectionContext
+  ): void | Promise<void>;
+  /** Handle a message from a hibernating WebSocket connection. */
+  onMessage(_connection: Connection, _message: WSMessage): void | Promise<void>;
+  /** Handle a hibernating WebSocket connection closing. */
+  onClose(
+    _connection: Connection,
+    _code: number,
+    _reason: string,
+    _wasClean: boolean
+  ): void | Promise<void>;
+  /** Return tags persisted with a hibernating WebSocket connection. */
+  getConnectionTags(
+    _connection: Connection,
+    _context: ConnectionContext
+  ): string[] | Promise<string[]>;
+  /** @internal Ensure lifecycle startup before a native RPC implementation. */
+  __unsafe_ensureInitialized(props?: Props): Promise<void>;
   private _state;
   private _disposables;
   private _destroyed;
@@ -3538,8 +4534,6 @@ declare class Agent<
   /** True when this agent runs as a facet (sub-agent) inside a parent. */
   private _isFacet;
   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
@@ -3554,27 +4548,42 @@ declare class Agent<
    * @internal
    */
   private _parentPath;
-  /** True while user's onStart() is executing. Used to warn about non-idempotent schedule() calls. */
-  private _insideOnStart;
-  /** Tracks callbacks already warned about during this onStart() to avoid log spam. */
-  private _warnedScheduleInOnStart;
   /** Warn-once guard: `chatRecovery` reassigned during onStart() (too late for wake recovery). */
   private _warnedChatRecoveryInOnStart;
   /**
-   * Number of active keepAlive() callers. When > 0, `_scheduleNextAlarm()`
+   * Number of active keepAlive() callers. When > 0, `_syncHostJobs()`
    * caps the next alarm at `keepAliveIntervalMs` so the DO stays alive.
    * Purely in-memory — lost on eviction, which is correct because the
    * in-memory work keepAlive was protecting is also lost.
    * @internal
    */
   _keepAliveRefs: number;
+  /** @internal The extracted dynamic-agent (facet) machinery. */
+  private _dynamicAgentsInstance;
+  /** @internal */
+  private get _dynamicAgents();
+  /** @internal */
+  private _dynamicAgentsApi;
   /**
-   * 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
+   * The dynamic-agents capability: facet-backed child agents that run
+   * in their own isolate with their own SQLite database, colocated
+   * with — and supervised by — this agent.
+   *
+   * Use dynamic agents for code whose class or lifecycle this agent
+   * owns: dynamically-loaded or AI-generated code, per-run tool
+   * agents, sandboxed components. For independent peers (for example
+   * one Durable Object per chat), use `getAgentByName` instead.
+   *
+   * ```ts
+   * const child = await this.dynamicAgents.get(Researcher, id);
+   * await child.doWork();
+   * this.dynamicAgents.abort(Researcher, id, reason);
+   * await this.dynamicAgents.delete(Researcher, id);
+   * ```
+   *
+   * @experimental The API surface may change before stabilizing.
    */
-  private _facetKeepAliveTokens;
+  get dynamicAgents(): DynamicAgents;
   /** @internal In-memory set of fiber IDs running in this process. */
   private _runFiberActiveFibers;
   /** @internal In-memory abort controllers for managed running fibers. */
@@ -3599,6 +4608,40 @@ declare class Agent<
   /** @internal Edge-trigger latch for the live-detached-count warning. */
   private _detachedLiveCountWarned;
   private _ParentClass;
+  /**
+   * Durable scheduling capability installed into this Agent's Lifecycle.
+   *
+   * @experimental The API surface may change before stabilizing. Agent's
+   * schedule()/scheduleEvery()/getScheduleById()/listSchedules()/
+   * cancelSchedule() methods are the stable surface.
+   */
+  readonly scheduler: Scheduler;
+  /**
+   * Durable replayable execution capability installed into this Agent's
+   * Lifecycle. Declare definitions on the overridable
+   * {@link taskDefinitions} property and start runs with
+   * `this.tasks.run(name, input, options)`.
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  readonly tasks: Tasks;
+  /**
+   * Named Task definitions for this Agent, resolved lazily on every
+   * dispatch. Declare as a field so the map is rebuilt on every Durable
+   * Object wake — that is what lets in-flight runs resolve their persisted
+   * definition names after a restart:
+   *
+   * ```ts
+   * readonly taskDefinitions = {
+   *   "build-report@v1": async (input: ReportInput, step: TaskStep) => {
+   *     // ...
+   *   }
+   * } satisfies TaskHandlers;
+   * ```
+   *
+   * @experimental The API surface may change before stabilizing.
+   */
+  readonly taskDefinitions?: TaskHandlers;
   readonly mcp: MCPClientManager;
   /**
    * Initial state for the Agent
@@ -3680,6 +4723,7 @@ declare class Agent<
    */
   protected _ensureSchema(): void;
   constructor(ctx: AgentContext, env: Env);
+  private _restoreAgentFacetContext;
   /**
    * Check for workflows referencing unknown bindings and warn with migration suggestion.
    */
@@ -3897,8 +4941,8 @@ declare class Agent<
   sendEmail(options: SendEmailOptions): Promise<EmailSendResult>;
   private _tryCatch;
   /**
-   * Automatically wrap custom methods with agent context
-   * This ensures getCurrentAgent() works in all custom methods without decorators
+   * Wrap public subclass methods that may be entered outside Lifecycle, such as
+   * native Durable Object RPC. Lifecycle hooks already have Agent context.
    */
   private _autoWrapCustomMethods;
   onError(connection: Connection, error: unknown): void | Promise<void>;
@@ -3973,87 +5017,15 @@ declare class Agent<
    * @returns Array of matching QueueItem objects
    */
   getQueues(key: string, value: string): QueueItem<string>[];
-  private _scheduleOwnerPathKey;
-  private _facetRunRowsForPrefix;
-  private _deleteFacetRunRowsForPrefix;
+  private _lifecycleRouteAddress;
+  private _routeLifecycleToRoot;
+  private _routeLifecycleToTarget;
+  /** Single native-RPC aperture for routed Lifecycle capabilities. */
+  _cf_routeLifecycle(
+    target: LifecycleRouteAddress | undefined,
+    envelope: LifecycleRouteEnvelope
+  ): Promise<unknown>;
   private _rootAlarmOwner;
-  private _cf_rootResolvesToSelf;
-  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
@@ -4067,30 +5039,10 @@ declare class Agent<
   _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.
+   * Facets run in separate colocated isolates but cannot set their own
+   * physical alarm, so this lets facet work use the root alarm heartbeat.
    * @internal
    */
   _cf_acquireFacetKeepAlive(
@@ -4146,10 +5098,7 @@ declare class Agent<
     when: Date | string | number,
     callback: keyof this,
     payload?: T,
-    options?: {
-      retry?: RetryOptions;
-      idempotent?: boolean;
-    }
+    options?: ScheduleOptions
   ): Promise<Schedule<T>>;
   /**
    * Schedule a task to run repeatedly at a fixed interval.
@@ -4201,7 +5150,6 @@ declare class Agent<
    * 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
    */
@@ -4221,7 +5169,6 @@ declare class Agent<
    * 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
    */
@@ -4355,6 +5302,20 @@ declare class Agent<
    * Throws if called outside a `runFiber` callback.
    */
   stash(data: unknown): void;
+  /**
+   * Run `fn` inside the fiber stash context so `this.stash()` keeps working
+   * for turns executing on the `tasks` capability exactly as it does inside
+   * legacy `runFiber()` closures.
+   * @internal
+   */
+  protected _withFiberStash<T>(
+    context: {
+      id: string;
+      signal: AbortSignal;
+      stash: (data: unknown) => void;
+    },
+    fn: () => Promise<T>
+  ): Promise<T>;
   /**
    * Called when an interrupted fiber is detected after restart.
    * Override to implement recovery (re-invoke work, notify clients, etc.).
@@ -4396,21 +5357,6 @@ declare class Agent<
   _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<boolean>;
   /**
    * Invoke an RPC method on this Agent or a descendant facet identified
    * by a root-first path. Used by AgentWorkflow to route callbacks and
@@ -4438,103 +5384,77 @@ declare class Agent<
   _cf_destroyDescendantFacet(
     targetPath: ReadonlyArray<AgentPathStep>
   ): Promise<void>;
-  private _executeScheduleCallback;
   /**
    * Whether any runFiber recovery work is still outstanding: orphaned
    * `cf_agents_runs` rows left by a dead process (excluding fibers currently
    * executing in memory, which already hold a keepAlive ref) or managed
    * ledger fibers stuck in a non-terminal state with no live run row.
    *
-   * Used by `_scheduleNextAlarm` to arm a follow-up alarm so multi-pass
+   * Used by `_syncHostJobs` to arm a follow-up alarm so multi-pass
    * recovery (e.g. after a scan-deadline yield, or while retrying a throwing
    * recovery hook) resumes instead of starving.
    * @internal
    */
   private _hasPendingFiberRecovery;
-  private _scheduleNextAlarm;
-  private _scheduleNextAlarmBody;
   /**
-   * Override PartyServer's onAlarm hook as a no-op.
-   * Agent handles alarm logic directly in the alarm() method override,
-   * but super.alarm() calls onAlarm() after #ensureInitialized(),
-   * so we suppress the default "Implement onAlarm" warning.
-   */
-  onAlarm(): void;
-  /**
-   * Method called when an alarm fires.
-   * Executes any scheduled tasks that are due.
-   *
-   * Calls super.alarm() first to ensure PartyServer's #ensureInitialized()
-   * runs, which resolves this.name from ctx.id.name (including for
-   * facets, which are spawned with an explicit id so they have their
-   * own ctx.id.name; pre-2026-03-15 alarms fall back to the legacy
-   * __ps_name storage record) and calls onStart() if needed.
+   * Synchronize Agent-owned host jobs with current durable state.
    *
-   * @remarks
-   * To schedule a task, please use the `this.schedule` method instead.
-   * See {@link https://developers.cloudflare.com/agents/api-reference/schedule-tasks/}
-   */
-  alarm(): Promise<void>;
-  /**
-   * The alarm body: PartyServer init + due-schedule processing + housekeeping +
-   * next-alarm arm. Extracted from {@link alarm} so the memory-limit circuit
-   * breaker can wrap it at the outermost frame (see {@link alarm}).
-   */
-  private _cf_runAlarmBody;
-  /**
-   * Durable storage key for the alarm memory-limit strike counter (#1825).
+   * Replaces the old pull-based `getNextAlarm()` contribution: keep-alive
+   * refs hold a `cf:keep-alive` job, and fiber-recovery / facet-run state
+   * holds a `cf:housekeeping` job. Every state change that used to trigger
+   * an alarm recalculation now re-pushes or cancels these jobs; queue
+   * mutations re-arm the physical alarm automatically.
+   * @internal
    */
-  private static readonly _CF_OOM_ALARM_STRIKES_KEY;
+  private _syncHostJobs;
   /**
-   * The schedule row id currently executing in the alarm loop, so the
-   * memory-limit circuit breaker can purge the exact looping row (#1825).
-   * `undefined` outside a callback (e.g. an OOM from `super.alarm()`/onStart).
+   * The next wake fiber-recovery or facet-run housekeeping needs, or `null`
+   * when neither has pending durable state.
    */
-  private _cf_executingScheduleRowId?;
+  private _nextHousekeepingWakeMs;
+  /** Lifecycle alarm callback; Agent housekeeping runs after user alarm work. */
+  onAlarm(): void;
   /**
-   * The schedule-callback names whose alarm rows drive a recovery loop that can
-   * deterministically OOM. The base agent has none; chat hosts (`Think`,
-   * `AIChatAgent`) override this to return their recovery continuation callbacks
-   * so the circuit breaker can surgically back them off / purge them WITHOUT
-   * disturbing unrelated scheduled tasks. See {@link _cf_handleAlarmMemoryLimitReset}.
+   * Drive one Agent-owned host job from the Lifecycle queue.
+   * @internal Dispatched by Lifecycle's alarm event loop; extensions add
+   * job fns through {@link _onHostJob}.
    */
-  protected _cf_recoveryAlarmCallbacks(): string[];
+  onJob(
+    context: LifecycleJobContext
+  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;
   /**
-   * Hook for a host to terminalize ("seal") any in-flight recovery work as an
-   * out-of-memory exhaustion when the alarm circuit breaker trips at its strike
-   * budget (#1825). Runs at the outermost alarm frame (post-unwind, so writes
-   * can land). Default: no-op. Chat hosts override to fire `onExhausted` + the
-   * terminal banner and persist the sealed incident.
+   * @internal Dispatch one host job fn. Agent extensions (Think) override
+   * this to add fns and delegate unknown ones to `super`.
    */
-  protected _cf_sealMemoryLimitedRecovery(): Promise<void>;
+  protected _onHostJob(
+    fn: string,
+    _context: LifecycleJobContext
+  ): LifecycleJobOutcome | void | Promise<LifecycleJobOutcome | void>;
   /**
-   * Clear the durable memory-limit strike counter after a clean alarm so the
-   * circuit breaker counts CONSECUTIVE resets rather than lifetime ones
-   * (#1825). Reads first (cheap, usually cached) and only writes when a strike
-   * is actually recorded, so the common no-strike path costs no write.
-   * Best-effort: a stale strike only costs one extra tolerated spike later.
+   * Apply host policy after the alarm memory-limit breaker records a strike.
+   *
+   * New chat hosts override this hook directly. The sealed-only fallback keeps
+   * `agents` 0.23 compatible with already-published chat packages whose peer
+   * ranges accept it but which implement only the former
+   * `_cf_sealMemoryLimitedRecovery` template method. Queue membership remains
+   * job-row policy; this invokes terminalization only and can be removed once
+   * old chat releases no longer accept the current `agents` range.
+   *
+   * @internal
    */
-  private _cf_clearAlarmMemoryLimitStrikes;
+  protected onAlarmMemoryLimit(context: MemoryLimitContext): Promise<void>;
   /**
-   * Alarm-boundary circuit breaker for Durable Object memory-limit resets
-   * (#1825). The in-DO recovery budgets (`chatRecovery.maxOomRetries` /
-   * `maxRecoveryWork`) only engage if their code runs AND its writes land; a
-   * severe OOM can defeat both — thrown before the budget runs (boot hydration),
-   * or its own small writes also OOM under memory pressure. In that case the
-   * error reaches {@link alarm} and, unhandled, the platform auto-retries the
-   * alarm indefinitely (re-running the doomed, billable turn each cycle).
+   * Run Lifecycle's alarm event loop after the pending-destroy preamble.
    *
-   * This runs at the OUTERMOST frame: the heavy turn has unwound and GC has
-   * reclaimed its footprint, so the small writes here can land where mid-turn
-   * ones (e.g. give-up's incident read) OOMed. A durable strike counter tolerates
-   * a few resets (a transient spike may clear), backing off the recovery rows so
-   * the retry is not a hot loop. At the `maxAlarmMemoryLimitStrikes` budget it
-   * seals the recovery work and purges the looping rows so the loop — and the
-   * bill — stops. Each step is best-effort: even these tiny writes can OOM, but
-   * swallowing (not re-throwing) still halts the platform's auto-retry, and a
-   * later wake re-arms legitimate schedules.
+   * The alarm memory-limit circuit breaker (#1825) lives inside
+   * `Lifecycle.alarm()`; capabilities and hosts opt into extra domain
+   * policy via their `onMemoryLimit` / `onAlarmMemoryLimit` hooks and the
+   * `recoveryLoop` schedule option.
+   *
+   * @remarks Use `this.schedule()` for named Agent callbacks. Reusable durable
+   * work belongs in a capability that pushes jobs and implements `onJob()`.
    */
-  private _cf_handleAlarmMemoryLimitReset;
+  alarm(): Promise<void>;
   /**
    * Intercept incoming HTTP/WS requests whose URL contains a
    * `/sub/{child-class}/{child-name}` marker and forward them to
@@ -4543,9 +5463,9 @@ declare class Agent<
    * Response, the framework resolves the facet and hands the
    * request off.
    *
-   * After a WebSocket upgrade completes, subsequent frames route
-   * directly to the child — the parent is only on the path for the
-   * initial request.
+   * The parent owns an upgraded WebSocket for its lifetime. Subsequent
+   * frames wake the root parent, which forwards them to the child over
+   * RPC and routes replies back to the native socket.
    *
    * @experimental The API surface may change before stabilizing.
    */
@@ -4556,7 +5476,6 @@ declare class Agent<
   ): 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,
@@ -4564,7 +5483,7 @@ declare class Agent<
   ): Promise<void>;
   _cf_subAgentConnectionMetas(
     ownerPath: ReadonlyArray<AgentPathStep>
-  ): Promise<SubAgentConnectionMeta[]>;
+  ): Promise<DynamicAgentConnectionMeta[]>;
   _cf_sendToSubAgentConnection(
     connectionId: string,
     message: string | ArrayBuffer | ArrayBufferView
@@ -4578,11 +5497,6 @@ declare class Agent<
     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
@@ -4594,32 +5508,26 @@ declare class Agent<
    */
   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
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta
   ): Promise<void>;
   _cf_handleSubAgentWebSocketMessage(
     message: WSMessage,
-    bridge: SubAgentConnectionBridge,
-    meta: SubAgentConnectionMeta
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta,
+    replyBridge?: DynamicAgentConnectionBridge
   ): Promise<void>;
   _cf_handleSubAgentWebSocketClose(
     code: number,
     reason: string,
     wasClean: boolean,
-    bridge: SubAgentConnectionBridge,
-    meta: SubAgentConnectionMeta
+    bridge: DynamicAgentConnectionBridge,
+    meta: DynamicAgentConnectionMeta
   ): 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` /
@@ -4655,7 +5563,7 @@ declare class Agent<
    * class Inbox extends Agent {
    *   override async onBeforeSubAgent(req, { className, name }) {
    *     // Strict registry gate
-   *     if (!this.hasSubAgent(className, name)) {
+   *     if (!this.dynamicAgents.has(className, name)) {
    *       return new Response("Not found", { status: 404 });
    *     }
    *   }
@@ -4705,7 +5613,6 @@ declare class Agent<
     method: string,
     args: unknown[]
   ): Promise<unknown>;
-  private _cf_invokeStubMethod;
   /**
    * Initialize this agent as a facet in a single RPC.
    *
@@ -4812,7 +5719,7 @@ declare class Agent<
    * ```
    */
   parentAgent<T extends Agent>(
-    cls: SubAgentClass<T>
+    cls: DynamicAgentClass<T>
   ): Promise<DurableObjectStub<T>>;
   private _cf_getTopLevelNamespaceByClassName;
   private _cf_asDurableObjectNamespace;
@@ -4837,11 +5744,13 @@ declare class Agent<
    * const searcher = await this.subAgent(SearchAgent, "main-search");
    * const results = await searcher.search("cloudflare agents");
    * ```
+   *
+   * @deprecated Use {@link Agent.dynamicAgents | this.dynamicAgents.get()} instead.
    */
   subAgent<T extends Agent>(
-    cls: SubAgentClass<T>,
+    cls: DynamicAgentClass<T>,
     name: string
-  ): Promise<SubAgentStub<T>>;
+  ): Promise<DynamicAgentStub<T>>;
   /** Maximum number of non-terminal agent-tool runs this parent may own at once. */
   maxConcurrentAgentTools: number;
   onAgentToolStart(_run: AgentToolRunInfo): Promise<void>;
@@ -4976,7 +5885,7 @@ declare class Agent<
    */
   _cfDetachedReconcileTick(payload?: DetachedReconcilePayload): Promise<void>;
   hasAgentToolRun<T extends Agent>(
-    cls: SubAgentClass<T>,
+    cls: DynamicAgentClass<T>,
     runId: string
   ): boolean;
   hasAgentToolRun(agentType: string, runId: string): boolean;
@@ -5130,6 +6039,13 @@ declare class Agent<
    * @internal
    */
   private _cf_resolveSubAgent;
+  /**
+   * Run `body` in a fresh invocation scope with no native request/
+   * connection context attached, so a child-facet RPC never sees
+   * parent-owned I/O handles.
+   * @internal
+   */
+  private _runFacetInitInvocation;
   /**
    * Forcefully abort a running sub-agent. The child stops executing
    * immediately and will be restarted on next {@link subAgent} call.
@@ -5141,8 +6057,10 @@ declare class Agent<
    * @param cls The Agent subclass used when creating the child
    * @param name Name of the child to abort
    * @param reason Error thrown to pending/future RPC callers
+   *
+   * @deprecated Use {@link Agent.dynamicAgents | this.dynamicAgents.abort()} instead.
    */
-  abortSubAgent(cls: SubAgentClass, name: string, reason?: unknown): void;
+  abortSubAgent(cls: DynamicAgentClass, name: string, reason?: unknown): void;
   /**
    * Delete a sub-agent: abort it if running, then permanently wipe its
    * storage. Transitively deletes the child's own children.
@@ -5151,20 +6069,10 @@ declare class Agent<
    *
    * @param cls The Agent subclass used when creating the child
    * @param name Name of the child to delete
+   *
+   * @deprecated Use {@link Agent.dynamicAgents | this.dynamicAgents.delete()} instead.
    */
-  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;
+  deleteSubAgent(cls: DynamicAgentClass, name: string): Promise<void>;
   /**
    * Whether this agent has previously spawned (and not deleted) a
    * sub-agent of the given class and name. Backed by an
@@ -5183,8 +6091,13 @@ declare class Agent<
    *   }
    * }
    * ```
+   *
+   * @deprecated Use {@link Agent.dynamicAgents | this.dynamicAgents.has()} instead.
    */
-  hasSubAgent<T extends Agent>(cls: SubAgentClass<T>, name: string): boolean;
+  hasSubAgent<T extends Agent>(
+    cls: DynamicAgentClass<T>,
+    name: string
+  ): boolean;
   hasSubAgent(className: string, name: string): boolean;
   /**
    * List known sub-agents, optionally filtered by class. Reflects
@@ -5192,9 +6105,11 @@ declare class Agent<
    * {@link deleteSubAgent}.
    *
    * @experimental The API surface may change before stabilizing.
+   *
+   * @deprecated Use {@link Agent.dynamicAgents | this.dynamicAgents.list()} instead.
    */
   listSubAgents<T extends Agent>(
-    cls: SubAgentClass<T>
+    cls: DynamicAgentClass<T>
   ): Array<{
     className: string;
     name: string;
@@ -5246,9 +6161,8 @@ declare class Agent<
    * durable marker directly — the in-memory `_isFacet` flag may not be
    * hydrated yet at the call sites, but facets never write the marker.
    */
+  private _pendingDestroyAlarm;
   private _hasPendingDestroy;
-  /** @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
@@ -5559,7 +6473,6 @@ declare class Agent<
   private _workflowOrigin;
   private _findAgentBindingNameForClass;
   private _findBindingNameForNamespace;
-  private _restoreRpcMcpServers;
   /**
    * Handle a callback from a workflow.
    * Invoked via the internal `_workflow_handleCallback` RPC whenever an
@@ -5711,27 +6624,6 @@ declare class Agent<
    */
   createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider;
   private broadcastMcpServers;
-  /**
-   * Handle MCP OAuth callback request if it's an OAuth callback.
-   *
-   * This method encapsulates the entire OAuth callback flow:
-   * 1. Checks if the request is an MCP OAuth callback
-   * 2. Processes the OAuth code exchange
-   * 3. Establishes the connection if successful
-   * 4. Broadcasts MCP server state updates
-   * 5. Returns the appropriate HTTP response
-   *
-   * @param request The incoming HTTP request
-   * @returns Response if this was an OAuth callback, null otherwise
-   */
-  private handleMcpOAuthCallback;
-  /**
-   * Handle OAuth callback response using MCPClientManager configuration
-   * @param result OAuth callback result
-   * @param request The original request (needed for base URL)
-   * @returns Response for the OAuth callback
-   */
-  private handleOAuthCallbackResponse;
 }
 /**
  * Namespace for creating Agent instances
@@ -5744,29 +6636,6 @@ type AgentNamespace<Agentic extends Agent<Cloudflare.Env>> =
  * Agent's durable context
  */
 type AgentContext = DurableObjectState;
-/**
- * Configuration options for Agent routing
- */
-type AgentOptions<Env> = PartyServerOptions<Env>;
-type AgentGetOptions<
-  Env,
-  Props extends Record<string, unknown> = Record<string, unknown>
-> = Pick<
-  PartyServerOptions<Env, Props>,
-  "jurisdiction" | "locationHint" | "props" | "routingRetry"
->;
-/**
- * Route a request to the appropriate Agent
- * @param request Request to route
- * @param env Environment containing Agent bindings
- * @param options Routing options
- * @returns Response from the Agent or undefined if no route matched
- */
-declare function routeAgentRequest<Env>(
-  request: Request,
-  env: Env,
-  options?: AgentOptions<Env>
-): Promise<Response | null>;
 type EmailRoutingOptions<Env> = AgentOptions<Env> & {
   resolver: EmailResolver<Env>;
   /**
@@ -5801,24 +6670,6 @@ declare function routeAgentEmail<Env extends Cloudflare.Env = Cloudflare.Env>(
   env: Env,
   options: EmailRoutingOptions<Env>
 ): Promise<void>;
-/**
- * Get or create an Agent by name
- * @template Env Environment type containing bindings
- * @template T Type of the Agent class
- * @param namespace Agent namespace
- * @param name Name of the Agent instance
- * @param options Options for Agent creation
- * @returns Promise resolving to an Agent instance stub
- */
-declare function getAgentByName<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  T extends Agent<Env> = Agent<Env>,
-  Props extends Record<string, unknown> = Record<string, unknown>
->(
-  namespace: DurableObjectNamespace<T>,
-  name: string,
-  options?: AgentGetOptions<Env, Props>
-): Promise<DurableObjectStub<T>>;
 /**
  * A wrapper for streaming responses in callable methods
  */
@@ -5827,6 +6678,7 @@ declare class StreamingResponse {
   private _id;
   private _closed;
   constructor(connection: Connection, id: string);
+  private _send;
   /**
    * Whether the stream has been closed (via end() or error())
    */
@@ -5851,600 +6703,256 @@ 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"
->;
-/**
- * Machine-readable cause of an `interrupted` seal (#1630 follow-up). Lets a
- * caller branch on WHY a run was abandoned without parsing the human-readable
- * `error` prose, which is not a stable contract.
- *
- * - `no-progress` — the child went silent for a full no-progress window while
- *   the parent was tailing it (genuinely stalled / hung).
- * - `window-exceeded` — a finite `agentToolReattachMaxWindowMs` ceiling elapsed
- *   while the child was still non-terminal. Only fires when an integrator opts
- *   into a hard wall-clock cap (the default ceiling is `Infinity`).
- * - `not-tailable` — the child runtime cannot live-tail, so the parent could
- *   not re-attach to its stream to follow it to terminal.
- * - `inspect-timeout` — inspecting the child timed out during parent recovery.
- * - `inspect-failed` — inspecting the child failed during parent recovery.
- * - `recovery-deadline` — the overall parent-recovery deadline elapsed before
- *   this run could be reconciled.
- * - `budget-exceeded` — a detached run's absolute `maxBudgetMs` ceiling elapsed
- *   before it reached a terminal. The parent gave up watching and tore the
- *   child down. Like `window-exceeded` this is a soft seal: a child that
- *   completes anyway can still repair the run and re-fire the completion hook.
- */
-type AgentToolInterruptedReason =
-  | "no-progress"
-  | "window-exceeded"
-  | "not-tailable"
-  | "inspect-timeout"
-  | "inspect-failed"
-  | "recovery-deadline"
-  | "budget-exceeded";
-/**
- * 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 /** Present only when `status` is `interrupted` — machine-readable cause. */;
-  reason?: AgentToolInterruptedReason;
+//#region src/agent-routing.d.ts
+interface RoutingRetryEvent {
+  error: unknown;
+  attempt: number;
+  maxAttempts: number;
+  delayMs: number;
+  name: string;
+  className?: string;
+}
+/** Retry policy for Agent routing infrastructure failures. */
+interface RoutingRetryOptions {
+  /** Max number of attempts, including the first. Default: 3. */
+  maxAttempts?: number;
+  /** Base delay in milliseconds for exponential backoff. Default: 100. */
+  baseDelayMs?: number;
+  /** Maximum delay in milliseconds. Default: 800. */
+  maxDelayMs?: number;
+  /** Optional callback invoked before each retry delay. */
+  onRetry?: (event: RoutingRetryEvent) => void | Promise<void>;
+}
+interface AgentRouteMatch<Env = Cloudflare.Env> {
+  /** The Durable Object environment binding name. */
+  className: Extract<keyof Env, string>;
+  /** The named Durable Object instance extracted from the URL. */
+  name: string;
+}
+interface AgentRouteOptions<
+  Env = Cloudflare.Env,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> {
+  /** URL prefix before the binding and instance name. Default: `agents`. */
+  prefix?: string;
+  jurisdiction?: DurableObjectJurisdiction;
+  locationHint?: DurableObjectLocationHint;
+  /** Properties supplied before lifecycle startup. */
+  props?: Props;
   /**
-   * Present only when `status` is `interrupted`. `true` when the child facet was
-   * still non-terminal (running / advancing) at the moment the parent stopped
-   * waiting; `false` once the parent has torn the child down so it is no longer
-   * doing work. Lets a caller decide between re-dispatching vs. reconnecting.
+   * Whether to enable CORS for matched routes.
+   *
+   * When `true`, uses default permissive CORS headers:
+   * - Access-Control-Allow-Origin: *
+   * - Access-Control-Allow-Methods: GET, POST, HEAD, OPTIONS
+   * - Access-Control-Allow-Headers: *
+   * - Access-Control-Max-Age: 86400
+   *
+   * For credentialed requests, pass explicit headers with a specific origin.
+   * When set to a `HeadersInit` value, uses those as the CORS headers instead.
+   * CORS preflight requests are handled automatically for matched routes.
    */
-  childStillRunning?: boolean;
-};
-type AgentToolDisplayMetadata = {
-  name?: string;
-  icon?: string;
-} & Record<string, unknown>;
-/**
- * Reserved chunk type a sub-agent emits via `reportProgress` while it runs.
- * Rides the child's own UI-message stream as a **transient** data part, so it
- * re-broadcasts to the parent's clients (via the parent's tail) and surfaces in
- * `useAgentToolEvents` without persisting into the child's stored message parts.
- * See `design/rfc-detached-agent-tools.md` §"Progress and milestone signaling".
- */
-declare const AGENT_TOOL_PROGRESS_PART = "data-agent-progress";
-/**
- * Reserved chunk type a sub-agent emits via `reportProgress({ milestone })`.
- * Unlike the ephemeral progress part this rides the child's stream as a
- * **persisted** data part, so it survives eviction, replays on drill-in, and
- * re-resolves milestone waiters. See `design/rfc-detached-agent-tools.md`.
- */
-declare const AGENT_TOOL_MILESTONE_PART = "data-agent-milestone";
-/**
- * Ephemeral progress signal a running sub-agent emits with `reportProgress`. The
- * well-known fields drive generic UI (a bar + status line) with no per-app
- * convention; `data` is an app-specific escape hatch that is **live-only** by
- * default (not persisted) unless `reportProgress(p, { persist: true })`. Naming a
- * `milestone` promotes the signal to the **durable** tier: it persists as one row
- * per milestone, replays, and (with `data`) is retained.
- */
-type AgentToolProgress<T = unknown> = {
-  /** 0..1 — drives a progress bar. */ fraction?: number /** Human-readable status line, e.g. "Ingested 40k/80k rows". */;
-  message?: string /** Coarse stage label, e.g. "scaffolding" | "deploying". */;
-  phase?: string;
+  cors?: boolean | HeadersInit;
   /**
-   * Present ⇒ a **durable** milestone: persisted, replayable, and surfaced as a
-   * distinct row in `AgentToolRunState.milestones` / `inspectAgentToolRun`. Use
-   * for named phase boundaries ("schema-ready", "preview-ready", "deployed").
+   * Retry transient Durable Object infrastructure errors thrown while routing.
+   * Enabled by default; pass `false` to disable.
    */
-  milestone?: string /** App-specific payload; live-only for progress, persisted for milestones. */;
-  data?: T;
-};
+  routingRetry?: false | RoutingRetryOptions;
+  onBeforeConnect?: (
+    request: Request,
+    route: AgentRouteMatch<Env>
+  ) => Response | Request | void | Promise<Response | Request | void>;
+  onBeforeRequest?: (
+    request: Request,
+    route: AgentRouteMatch<Env>
+  ) =>
+    | Response
+    | Request
+    | void
+    | Promise<Response | Request | undefined | void>;
+}
+/** Configuration options for {@link routeAgentRequest}. */
+type AgentOptions<Env> = AgentRouteOptions<Env>;
+/** Options for resolving and starting a named Agent. */
+type AgentGetOptions<
+  Env,
+  Props extends Record<string, unknown> = Record<string, unknown>
+> = Pick<
+  AgentRouteOptions<Env, Props>,
+  "jurisdiction" | "locationHint" | "props" | "routingRetry"
+>;
 /**
- * A durable milestone a sub-agent reached, projected onto `AgentToolRunState`
- * and `inspectAgentToolRun`. `sequence` is monotonic per run so replay/live
- * races dedupe on `(runId, sequence)`.
+ * Route `/agents/:binding/:name` HTTP and WebSocket requests to a named
+ * Durable Object. The target may extend `Agent` or compose `Lifecycle`
+ * directly into a plain `DurableObject`.
+ *
+ * @param request - Incoming Worker request.
+ * @param env - Worker environment containing Durable Object bindings.
+ * @param options - Routing options.
+ * @returns The matched response, or `null` when the path does not match.
  */
-type AgentToolMilestone = {
-  name: string /** Monotonic per-run ordinal; dedupe key for replay vs live races. */;
-  sequence: number /** Epoch ms the milestone was reached. */;
-  at: number /** App-specific payload carried with the milestone (persisted). */;
-  data?: unknown;
-};
+declare function routeAgentRequest<Env>(
+  request: Request,
+  env: Env,
+  options?: AgentOptions<Env>
+): Promise<Response | null>;
 /**
- * Latest progress snapshot persisted on the child run row and surfaced through
- * `inspectAgentToolRun` + `AgentToolRunState`. Only the safe-to-inspect fields
- * are retained by default; `at` is the emit timestamp (drives the resetting
- * no-progress budget).
+ * Get a named Agent stub after its lifecycle startup has completed.
+ *
+ * @param namespace - Agent Durable Object namespace.
+ * @param name - Agent instance name.
+ * @param options - Placement, startup properties, and retry options.
+ * @returns The initialized Agent stub.
  */
-type AgentToolProgressSnapshot = {
-  fraction?: number;
-  message?: string;
-  phase?: string;
-  /**
-   * Set when this signal was a durable milestone (`reportProgress({ milestone })`).
-   * Lets an `onProgress` consumer branch on milestone vs. ephemeral progress.
-   */
-  milestone?: string /** Epoch ms of the latest signal. */;
-  at: number /** Present only when the emitter opted into persisting `data`. */;
-  data?: unknown;
-};
-type AgentToolRunInfo = {
-  runId: string;
-  parentToolCallId?: string;
-  agentType: string;
-  inputPreview?: unknown;
-  status: AgentToolRunStatus;
-  display?: AgentToolDisplayMetadata;
-  /**
-   * Caller-controlled `metadata.source` for chat-agent `detached.notify`
-   * completions. Present only for detached notify runs that supplied one.
-   */
-  notifySource?: string;
-  displayOrder: number;
-  startedAt: number;
-  completedAt?: number;
-};
-type AgentToolLifecycleResult = {
-  status: AgentToolTerminalStatus;
-  summary?: string;
-  error?: string /** Present only when `status` is `interrupted` — machine-readable cause. */;
-  reason?: AgentToolInterruptedReason;
-  /**
-   * Present only when `status` is `interrupted`. Whether the child facet was
-   * still non-terminal when the parent stopped waiting (before any teardown).
-   */
-  childStillRunning?: boolean;
-};
-/**
- * Configuration for a detached ("background") agent-tool run. See
- * `design/rfc-detached-agent-tools.md`.
- *
- * Callbacks are referenced by **method name** on the dispatching agent (the same
- * durable, eviction-surviving pattern as `Agent.schedule`) — never closures,
- * which cannot be rehydrated after the Durable Object is evicted.
- *
- * `Self` is threaded from `runAgentTool(cls, options)` so the method names are
- * type-checked against the calling agent's own methods.
- */
-type DetachedAgentToolConfig<Self = Record<string, unknown>> = {
-  /**
-   * Method invoked once per terminal delivery. Branch on `result.status`:
-   * `"completed" | "error" | "aborted" | "interrupted"`. A budget give-up
-   * arrives as `status: "interrupted"` with `reason: "budget-exceeded"`; because
-   * `interrupted` is soft, a child that later completes can fire the hook again
-   * with `"completed"`, so a give-up never hides a late real result. Make the
-   * handler idempotent.
-   */
-  onFinish?: Extract<keyof Self, string>;
-  /**
-   * Absolute safety ceiling — a backstop against a child that runs forever. On
-   * expiry the parent gives up watching (delivers `onFinish` with
-   * `interrupted` / `budget-exceeded`) and tears the child down. Defaults to the
-   * parent-level `detachedMaxBudgetMs`.
-   */
-  maxBudgetMs?: number;
-  /**
-   * Per-run override of the resetting no-progress window (ms). Once the child
-   * emits its first `reportProgress`, the parent gives up if it then goes silent
-   * for this long (resets on each signal). Defaults to the parent-level
-   * `detachedNoProgressBudgetMs` (1h). `0`/`Infinity` disables it.
-   */
-  noProgressBudgetMs?: number;
-  /**
-   * Chat-agent convenience (`@cloudflare/think` / `AIChatAgent`): when the run
-   * finishes, inject a message into the chat so the model can react to the
-   * result, instead of you wiring `onFinish` by hand. Sugar that auto-targets
-   * the agent's `_cfDetachedNotifyFinish` hook; ignored on a base `Agent` that
-   * does not implement it, and ignored when `onFinish` is also set (an explicit
-   * `onFinish` wins). Pass `{ source }` to fit the injected message into your
-   * app's existing metadata taxonomy. Override `formatDetachedCompletion()` to
-   * customize the injected text.
-   */
-  notify?:
-    | boolean
-    | {
-        source?: string;
-      };
-  /**
-   * Chat-agent convenience: milestone names that, when the detached run reaches
-   * them, surface an idempotent synthetic message in the chat BEFORE the run
-   * finishes. Each `(runId, name)` fires at most once (idempotency-keyed),
-   * whether observed live or reconciled after eviction. Override the wording via
-   * `formatDetachedMilestone()`. Requires a chat host (`@cloudflare/think`); a
-   * no-op on a base `Agent`.
-   *
-   * Two delivery modes (the string-array shorthand defaults to `"narrate"`):
-   * - `"narrate"` (default) — inject a synthetic **assistant** message directly
-   *   (no inference): a cheap, honest status line ("Found 2 sources…") that does
-   *   not trigger a model turn. Best for pure progress narration.
-   * - `"react"` — inject a **user-role** turn so the model responds to the
-   *   milestone (steer, start dependent work, narrate with context). Costs a
-   *   model turn. Opt in for milestones the agent should *act on*.
-   */
-  onMilestones?:
-    | string[]
-    | {
-        names: string[];
-        mode?: "react" | "narrate";
-      };
-};
-type RunAgentToolOptions<Input = unknown, Self = Record<string, unknown>> = {
-  input: Input;
-  runId?: string;
-  parentToolCallId?: string;
-  displayOrder?: number;
-  signal?: AbortSignal;
-  inputPreview?: unknown;
-  display?: AgentToolDisplayMetadata;
-  /**
-   * Run the sub-agent **detached**: dispatch it, let the current turn continue,
-   * and (optionally) get a durable callback when it finishes. `true` is
-   * fire-and-forget (observe via `agent-tool-event` frames + the global
-   * `onAgentToolFinish` hook); an object adds the targeted, eviction-surviving
-   * `onFinish` callback. A detached run does NOT inherit `options.signal` — it
-   * must outlive the spawning turn; cancel it explicitly via `cancelAgentTool`.
-   */
-  detached?: boolean | DetachedAgentToolConfig<Self>;
-};
-/**
- * Result of dispatching a detached run. Returns immediately after dispatch
- * rather than after completion.
- */
-type DetachedRunAgentToolResult = {
-  runId: string;
-  agentType: string;
-  /**
-   * `"running"` on a successful dispatch; `"error"` if dispatch itself failed
-   * (e.g. the `maxConcurrentAgentTools` cap was exceeded — rejected
-   * synchronously, no child started, no callback wired).
-   */
-  status: "running" | "error";
-  error?: string;
-};
-type RunAgentToolResult<Output = unknown> = {
-  runId: string;
-  agentType: string;
-  status: AgentToolTerminalStatus;
-  output?: Output;
-  summary?: string;
-  error?: string;
-  /**
-   * Present only when `status` is `interrupted` — a machine-readable cause so
-   * callers don't pattern-match the `error` prose (#1630 follow-up).
-   */
-  reason?: AgentToolInterruptedReason;
-  /**
-   * Present only when `status` is `interrupted`. `true` when the child facet was
-   * still non-terminal (running / advancing) at the moment the parent stopped
-   * waiting and before any teardown; `false` once the parent has torn the child
-   * down so it is no longer doing work.
-   */
-  childStillRunning?: boolean;
-};
-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;
-  /**
-   * Latest progress snapshot the child has persisted, so a rehydrated parent
-   * (recovery / backbone reconcile) can reconstruct "where is this run" and
-   * reset the resetting no-progress budget without having tailed the live
-   * stream. Absent until the child emits its first `reportProgress`.
-   */
-  progress?: AgentToolProgressSnapshot;
-  /**
-   * Durable milestones the child has persisted, ordered by `sequence`. Lets a
-   * rehydrated parent (recovery / backbone reconcile) replay milestone-gated
-   * work and milestone notifications without having observed the live stream.
-   */
-  milestones?: AgentToolMilestone[];
-};
-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 /** Machine-readable cause of the interrupt (#1630 follow-up). */;
-      reason?: AgentToolInterruptedReason;
-      /**
-       * Whether the child facet was still non-terminal when the parent stopped
-       * waiting (before any teardown). Lets a UI distinguish a still-running
-       * child from one the parent has torn down.
-       */
-      childStillRunning?: boolean;
-    };
-type AgentToolEventMessage = {
-  type: "agent-tool-event";
-  parentToolCallId?: string;
-  sequence: number;
-  replay?: true;
-  event: AgentToolEvent;
-};
-type AgentToolRunPart = {
-  type: string;
-};
-type AgentToolRunState<Part extends AgentToolRunPart = AgentToolRunPart> = {
-  runId: string;
-  agentType: string;
-  parentToolCallId?: string;
-  inputPreview?: unknown;
-  order: number;
-  display?: AgentToolDisplayMetadata;
-  status: "running" | "completed" | "error" | "aborted" | "interrupted";
-  /**
-   * Message parts reconstructed from the child agent's streamed chunks.
-   *
-   * The default stays framework-neutral so importing `agents` does not require
-   * an AI SDK peer. AI SDK consumers can use
-   * `AgentToolRunState<UIMessage["parts"][number]>` when they need its exact
-   * discriminated union.
-   */
-  parts: Part[];
-  summary?: string;
-  error?: string;
-  /**
-   * Present only when `status` is `interrupted` — machine-readable cause and
-   * whether the child is still running, mirrored from the wire event so a UI
-   * can render the reason without parsing `error` (#1630 follow-up).
-   */
-  reason?: AgentToolInterruptedReason;
-  childStillRunning?: boolean;
-  /**
-   * Latest progress snapshot, projected from the child's transient
-   * `data-agent-progress` signals so a UI can render a bar / ETA / phase label
-   * for a running (especially detached / background) run without drilling in.
-   */
-  progress?: AgentToolProgressSnapshot;
-  /**
-   * Durable milestones the run has reached, ordered by `sequence` (deduped
-   * across replay/live races). Drives milestone chips / a phase timeline.
-   */
-  milestones?: AgentToolMilestone[];
-  subAgent: {
-    agent: string;
-    name: string;
-  };
-};
-type AgentToolEventState<Part extends AgentToolRunPart = AgentToolRunPart> = {
-  runsById: Record<string, AgentToolRunState<Part>>;
-  runsByToolCallId: Record<string, AgentToolRunState<Part>[]>;
-  unboundRuns: AgentToolRunState<Part>[];
-};
+declare function getAgentByName<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  T extends Agent<Env> = Agent<Env>,
+  Props extends Record<string, unknown> = Record<string, unknown>
+>(
+  namespace: DurableObjectNamespace<T>,
+  name: string,
+  options?: AgentGetOptions<Env, Props>
+): Promise<DurableObjectStub<T>>;
 //#endregion
 export {
-  RoutingRetryOptions as $,
-  MCPOAuthCallbackResult as $t,
-  AgentGetOptions as A,
-  StreamableHTTPEdgeClientTransport as An,
-  WorkflowCompleteCallback as At,
-  EmailSendBinding as B,
-  parseSubAgentPath as Bn,
-  WorkflowTrackingRow as Bt,
-  DetachedRunAgentToolResult as C,
-  LegacyMcpHandler as Cn,
-  ApprovalEventPayload as Ct,
-  AddRpcMcpServerOptions as D,
-  WorkerTransport as Dn,
-  WorkflowCallback as Dt,
-  AddMcpServerOptions as E,
-  TransportState as En,
-  WaitForApprovalOptions as Et,
-  Connection$1 as F,
-  buildAgentPath as Fn,
-  WorkflowPage as Ft,
-  FiberStatus as G,
-  MCPClientElicitationHandler as Gt,
-  FiberInspection as H,
-  withInvocationScope as Hn,
-  ElicitResult$2 as Ht,
-  ConnectionContext$1 as I,
-  buildAgentUrl as In,
-  WorkflowProgressCallback as It,
-  MCPServerMessage as J,
-  MCPClientManagerOptions as Jt,
-  ListFibersOptions as K,
-  MCPClientElicitationHandlers as Kt,
-  DEFAULT_AGENT_STATIC_OPTIONS as L,
-  buildSubAgentPath as Ln,
-  WorkflowQueryCriteria as Lt,
-  AgentOptions as M,
-  BuildAgentPathOptions as Mn,
-  WorkflowEventCallback as Mt,
-  AgentStaticOptions as N,
-  SUB_PREFIX as Nn,
-  WorkflowEventPayload as Nt,
-  Agent as O,
-  WorkerTransportOptions as On,
-  WorkflowCallbackBase as Ot,
-  CallableMetadata as P,
-  SubAgentPathMatch as Pn,
-  WorkflowInfo as Pt,
-  RPCResponse as Q,
-  MCPDiscoverResult as Qt,
-  DeleteFibersOptions as R,
-  buildSubAgentPathUnchecked as Rn,
-  WorkflowRejectedError as Rt,
-  DetachedAgentToolConfig as S,
-  CreateMcpHandlerOptions$1 as Sn,
-  AgentWorkflowStep as St,
-  RunAgentToolResult as T,
-  MCPStorageApi as Tn,
-  RunWorkflowOptions as Tt,
-  FiberRecoveryContext as U,
-  MCPAITool as Ut,
-  FiberContext as V,
-  routeSubAgentRequest as Vn,
-  ElicitRequest$1 as Vt,
-  FiberRecoveryResult as W,
-  MCPAIToolSet as Wt,
-  QueueItem as X,
-  MCPClientOAuthResult as Xt,
-  MCPServersState as Y,
-  MCPClientOAuthCallbackConfig as Yt,
-  RPCRequest as Z,
-  MCPConnectionResult as Zt,
-  AgentToolRunState as _,
-  ClearableEventStore as _n,
-  AgentWorkflowEvent as _t,
-  AgentToolEvent as a,
-  normalizeServerId as an,
-  StartFiberResult as at,
-  AgentToolTerminalStatus as b,
-  experimental_createMcpHandler as bn,
-  AgentWorkflowParams as bt,
-  AgentToolFailure as c,
-  RPCClientTransport as cn,
-  SubAgentClass as ct,
-  AgentToolMilestone as d,
-  RPCServerTransportOptions as dn,
-  callable as dt,
-  MCPServerFilter as en,
-  Schedule as et,
-  AgentToolProgress as f,
-  RPC_DO_PREFIX as fn,
-  getAgentByName as ft,
-  AgentToolRunPart as g,
-  McpAgent as gn,
-  unstable_callable as gt,
-  AgentToolRunInspection as h,
-  ElicitResult$3 as hn,
-  routeAgentRequest as ht,
-  AgentToolDisplayMetadata as i,
-  getNamespacedData as in,
-  StartFiberOptions as it,
-  AgentNamespace as j,
-  AgentPathStep as jn,
-  WorkflowErrorCallback as jt,
-  AgentContext as k,
-  SSEEdgeClientTransport as kn,
-  WorkflowCallbackType as kt,
-  AgentToolInterruptedReason as l,
-  RPCClientTransportOptions as ln,
-  SubAgentStub as lt,
-  AgentToolRunInfo as m,
-  ElicitRequestSchema as mn,
-  routeAgentEmail as mt,
-  AGENT_TOOL_PROGRESS_PART as n,
-  MCP_SERVER_ID_MAX_LENGTH as nn,
-  SendEmailOptions as nt,
-  AgentToolEventMessage as o,
-  MCPElicitationHandler as on,
-  StateUpdateMessage as ot,
-  AgentToolProgressSnapshot as p,
-  ElicitRequest$2 as pn,
-  getCurrentAgent as pt,
-  MCPServer as q,
-  MCPClientManager as qt,
-  AgentToolChildAdapter as r,
-  RegisterServerOptions as rn,
-  SqlError as rt,
-  AgentToolEventState as s,
-  MCPElicitationHandlers as sn,
-  StreamingResponse as st,
-  AGENT_TOOL_MILESTONE_PART as t,
-  MCPServerOptions as tn,
-  ScheduleCriteria as tt,
-  AgentToolLifecycleResult as u,
-  RPCServerTransport as un,
-  WSMessage$1 as ut,
-  AgentToolRunStatus as v,
-  DurableObjectEventStore as vn,
-  AgentWorkflowInternalParams as vt,
-  RunAgentToolOptions as w,
-  createLegacyMcpHandler as wn,
-  DefaultProgress as wt,
-  ChatCapableAgentClass as x,
-  CreateLegacyMcpHandlerOptions as xn,
-  AgentWorkflowPathStep as xt,
-  AgentToolStoredChunk as y,
-  createMcpHandler$1 as yn,
-  AgentWorkflowOrigin as yt,
-  EmailRoutingOptions as z,
-  getSubAgentByName as zn,
-  WorkflowStatus as zt
+  ChatCapableAgentClass as $,
+  RPC_DO_PREFIX as $t,
+  StreamingResponse as A,
+  routeSubAgentRequest as An,
+  MCPAITool as At,
+  AgentToolFailure as B,
+  MCPOAuthCallbackResult as Bt,
+  MCPServersState as C,
+  SubAgentPathMatch as Cn,
+  WorkflowProgressCallback as Ct,
+  StartFiberOptions as D,
+  buildSubAgentPathUnchecked as Dn,
+  WorkflowTrackingRow as Dt,
+  RPCResponse as E,
+  buildSubAgentPath as En,
+  WorkflowStatus as Et,
+  AgentToolChildAdapter as F,
+  MCPClientManagerOptions as Ft,
+  AgentToolProgressSnapshot as G,
+  getNamespacedData as Gt,
+  AgentToolLifecycleResult as H,
+  MCPServerOptions as Ht,
+  AgentToolDisplayMetadata as I,
+  MCPClientOAuthCallbackConfig as It,
+  AgentToolRunPart as J,
+  MCPElicitationHandlers as Jt,
+  AgentToolRunInfo as K,
+  normalizeServerId as Kt,
+  AgentToolEvent as L,
+  MCPClientOAuthResult as Lt,
+  routeAgentEmail as M,
+  MCPClientElicitationHandler as Mt,
+  AGENT_TOOL_MILESTONE_PART as N,
+  MCPClientElicitationHandlers as Nt,
+  StartFiberResult as O,
+  getSubAgentByName as On,
+  ElicitRequest$1 as Ot,
+  AGENT_TOOL_PROGRESS_PART as P,
+  MCPClientManager as Pt,
+  AgentToolTerminalStatus as Q,
+  RPCServerTransportOptions as Qt,
+  AgentToolEventMessage as R,
+  MCPConnectionResult as Rt,
+  MCPServerMessage as S,
+  SUB_PREFIX as Sn,
+  WorkflowPage as St,
+  RPCRequest as T,
+  buildAgentUrl as Tn,
+  WorkflowRejectedError as Tt,
+  AgentToolMilestone as U,
+  MCP_SERVER_ID_MAX_LENGTH as Ut,
+  AgentToolInterruptedReason as V,
+  MCPServerFilter as Vt,
+  AgentToolProgress as W,
+  RegisterServerOptions as Wt,
+  AgentToolRunStatus as X,
+  RPCClientTransportOptions as Xt,
+  AgentToolRunState as Y,
+  RPCClientTransport as Yt,
+  AgentToolStoredChunk as Z,
+  RPCServerTransport as Zt,
+  FiberRecoveryContext as _,
+  StreamableHTTPEdgeClientTransport as _n,
+  WorkflowCompleteCallback as _t,
+  routeAgentRequest as a,
+  DurableObjectEventStore as an,
+  AgentWorkflowInternalParams as at,
+  ListFibersOptions as b,
+  AgentPathStep as bn,
+  WorkflowEventPayload as bt,
+  Agent as c,
+  CreateLegacyMcpHandlerOptions as cn,
+  AgentWorkflowPathStep as ct,
+  AgentStaticOptions as d,
+  createLegacyMcpHandler as dn,
+  DefaultProgress as dt,
+  ElicitRequest$2 as en,
+  DetachedAgentToolConfig as et,
+  DEFAULT_AGENT_STATIC_OPTIONS as f,
+  MCPStorageApi as fn,
+  RunWorkflowOptions as ft,
+  FiberInspection as g,
+  SSEEdgeClientTransport as gn,
+  WorkflowCallbackType as gt,
+  FiberContext as h,
+  WorkerTransportOptions as hn,
+  WorkflowCallbackBase as ht,
+  getAgentByName as i,
+  ClearableEventStore as in,
+  AgentWorkflowEvent as it,
+  getCurrentAgent as j,
+  withInvocationScope as jn,
+  MCPAIToolSet as jt,
+  StateUpdateMessage as k,
+  parseSubAgentPath as kn,
+  ElicitResult$2 as kt,
+  AgentContext as l,
+  CreateMcpHandlerOptions$1 as ln,
+  AgentWorkflowStep as lt,
+  EmailRoutingOptions as m,
+  WorkerTransport as mn,
+  WorkflowCallback as mt,
+  AgentOptions as n,
+  ElicitResult$3 as nn,
+  RunAgentToolOptions as nt,
+  AddMcpServerOptions as o,
+  createMcpHandler$1 as on,
+  AgentWorkflowOrigin as ot,
+  DeleteFibersOptions as p,
+  TransportState as pn,
+  WaitForApprovalOptions as pt,
+  AgentToolRunInspection as q,
+  MCPElicitationHandler as qt,
+  RoutingRetryOptions as r,
+  McpAgent as rn,
+  RunAgentToolResult as rt,
+  AddRpcMcpServerOptions as s,
+  experimental_createMcpHandler as sn,
+  AgentWorkflowParams as st,
+  AgentGetOptions as t,
+  ElicitRequestSchema as tn,
+  DetachedRunAgentToolResult as tt,
+  AgentNamespace as u,
+  LegacyMcpHandler as un,
+  ApprovalEventPayload as ut,
+  FiberRecoveryResult as v,
+  DynamicAgentClass as vn,
+  WorkflowErrorCallback as vt,
+  QueueItem as w,
+  buildAgentPath as wn,
+  WorkflowQueryCriteria as wt,
+  MCPServer as x,
+  BuildAgentPathOptions as xn,
+  WorkflowInfo as xt,
+  FiberStatus as y,
+  DynamicAgentStub as yn,
+  WorkflowEventCallback as yt,
+  AgentToolEventState as z,
+  MCPDiscoverResult as zt
 };
-//# sourceMappingURL=agent-tool-types-CzGGB-20.d.ts.map
+//# sourceMappingURL=agent-routing-DE5zmCQ8.d.ts.map