agents 0.22.0 → 0.23.0

package/dist/{agent-routing-CnkaHb-v.d.ts → agent-routing-DE5zmCQ8.d.ts}

@@ -1,25 +1,27 @@
 import {
-  l as LifecycleRouteAddress,
-  n as CapabilityRequestContext,
+  _ as LifecycleJobOutcome,
+  b as Connection,
+  g as LifecycleJobContext,
+  o as MemoryLimitContext,
   s as LifecycleCapability,
-  t as AlarmContribution
-} from "./capability-runner-CvHGZqUu.js";
+  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 WSMessage,
-  l as Connection,
+  c as LifecycleRouteEnvelope,
   n as CurrentAgentContext,
-  o as Lifecycle,
-  s as LifecycleRouteEnvelope,
-  u as ConnectionContext
-} from "./current-agent-CuMErtly.js";
+  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 { t as RetryOptions } from "./retries-CAvxtG9d.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-DcSAZKsB.js";
+} from "./index-YSKgfgg9.js";
 import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-Tmf1vgKz.js";
 import {
   a as McpAuthContext,
@@ -37,8 +39,12 @@ import { t as MessageType } from "./types-6Zo2zfoO.js";
 import {
   a as ScheduleCriteria,
   i as Schedule,
+  o as ScheduleOptions,
   t as Scheduler
-} from "./scheduler-DQoTGoAW.js";
+} 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,
@@ -286,9 +292,731 @@ 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/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/dynamic-agents/bridges.d.ts
+/**
+ * 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 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
+/**
+ * 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).
+ */
+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/dynamic-agents/host.d.ts
+/**
+ * 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.
+ *
+ * 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 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>;
+}
+//#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;
+  /**
+   * 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.
+   */
+  cleanupPrefix(ownerPath: ReadonlyArray<AgentPathStep>): Promise<void>;
+  /**
+   * Acquire a root-owned keepAlive ref on behalf of a descendant facet.
+   */
+  acquireKeepAlive(ownerPath: ReadonlyArray<AgentPathStep>): Promise<string>;
+  /**
+   * Release a root-owned keepAlive ref previously acquired for a facet.
+   * Idempotent so disposer calls can safely race or run twice.
+   */
+  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 {
@@ -3162,7 +3890,7 @@ type RunAgentToolResult<Output = unknown> = {
    */
   childStillRunning?: boolean;
 };
-type ChatCapableAgentClass<T extends Agent = Agent> = SubAgentClass<T>;
+type ChatCapableAgentClass<T extends Agent = Agent> = DynamicAgentClass<T>;
 type AgentToolRunInspection<Output = unknown> = {
   runId: string;
   status: Exclude<AgentToolRunStatus, "interrupted">;
@@ -3355,114 +4083,6 @@ type RPCResponse = {
       error: string;
     }
 );
-/**
- * Metadata for a callable method
- */
-type CallableMetadata = {
-  /** Optional description of what the method does */ description?: string /** Whether the method supports streaming responses */;
-  streaming?: boolean;
-};
-type SubAgentConnectionMeta = {
-  id: string;
-  uri: string | null;
-  tags: string[];
-  state: unknown;
-  requestHeaders?: [string, string][];
-};
-type SubAgentConnectionBridgeLike = {
-  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>;
-};
-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 | 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>;
-}
-/**
- * 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.
- */
-type SubAgentClass<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 sub-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 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;
-};
-/**
- * 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;
@@ -3859,6 +4479,17 @@ declare class 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. */
@@ -3903,10 +4534,6 @@ declare class Agent<
   /** True when this agent runs as a facet (sub-agent) inside a parent. */
   private _isFacet;
   private _protocolBroadcastExcludeIds;
-  private _cf_subAgentBridgeContext;
-  private _cf_virtualSubAgentConnections;
-  private _cf_subAgentConnectionOperationTails;
-  private _cf_subAgentBroadcastOperationTail?;
   /**
    * User-facing facet name. For legacy facets this is the same as
    * `ctx.id.name`; path-scoped facets use an internal routing id and
@@ -3924,20 +4551,39 @@ declare class Agent<
   /** Warn-once guard: `chatRecovery` reassigned during onStart() (too late for wake recovery). */
   private _warnedChatRecoveryInOnStart;
   /**
-   * Number of active keepAlive() callers. When > 0, `_rearmAlarm()`
+   * 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. */
@@ -3970,6 +4616,32 @@ declare class Agent<
    * 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
@@ -4345,8 +5017,6 @@ declare class Agent<
    * @returns Array of matching QueueItem objects
    */
   getQueues(key: string, value: string): QueueItem<string>[];
-  private _facetRunRowsForPrefix;
-  private _deleteFacetRunRowsForPrefix;
   private _lifecycleRouteAddress;
   private _routeLifecycleToRoot;
   private _routeLifecycleToTarget;
@@ -4356,7 +5026,6 @@ declare class Agent<
     envelope: LifecycleRouteEnvelope
   ): Promise<unknown>;
   private _rootAlarmOwner;
-  private _cf_rootResolvesToSelf;
   /**
    * Clean root-owned bookkeeping for a sub-tree of facets. This
    * bulk-cancels schedules whose `owner_path` starts with the given
@@ -4372,8 +5041,8 @@ declare class Agent<
   ): Promise<void>;
   /**
    * 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(
@@ -4429,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.
@@ -4636,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.).
@@ -4710,80 +5390,71 @@ declare class Agent<
    * 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 `_rearmAlarm` 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 _rearmAlarm;
-  /**
-   * Contribute Agent-owned alarm work that has not yet been extracted into its
-   * own capability. Scheduler contributes independently.
-   * @internal
-   */
-  getNextAlarm(): Promise<AlarmContribution>;
-  /** @internal Transitional alarm contribution for Agent subclasses. */
-  protected _getExtensionAlarm(): number | null | Promise<number | null>;
-  /** Lifecycle alarm callback; Agent housekeeping runs after user alarm work. */
-  onAlarm(): void;
   /**
-   * Run Lifecycle's alarm phase inside Agent's memory-limit circuit breaker.
+   * Synchronize Agent-owned host jobs with current durable state.
    *
-   * @remarks Use `this.schedule()` for named Agent callbacks. Reusable durable
-   * work belongs in a capability with `getNextAlarm()` and `onAlarm()`.
+   * 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
    */
-  alarm(): Promise<void>;
-  /** Run the Lifecycle alarm phase inside Agent's OOM circuit breaker. */
-  private _cf_runAlarmBody;
+  private _syncHostJobs;
   /**
-   * Durable storage key for the alarm memory-limit strike counter (#1825).
+   * The next wake fiber-recovery or facet-run housekeeping needs, or `null`
+   * when neither has pending durable state.
    */
-  private static readonly _CF_OOM_ALARM_STRIKES_KEY;
+  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
@@ -4792,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.
    */
@@ -4805,25 +5476,6 @@ declare class Agent<
   ): void;
   getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
   getConnections<TState = unknown>(tag?: string): Iterable<Connection<TState>>;
-  private _cf_activeSubAgentBridge;
-  /**
-   * 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.
-   */
-  private _cf_routeSubAgentConnectionOperation;
-  /**
-   * 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.
-   */
-  private _cf_routeSubAgentBroadcast;
-  private _cf_reportSubAgentConnectionOperationFailure;
-  private _cf_broadcastToParentSubAgent;
   _cf_broadcastToSubAgent(
     ownerPath: ReadonlyArray<AgentPathStep>,
     message: string | ArrayBuffer | ArrayBufferView,
@@ -4831,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
@@ -4845,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
@@ -4861,33 +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,
-    replyBridge?: SubAgentConnectionBridge
+    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` /
@@ -4923,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 });
    *     }
    *   }
@@ -4973,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.
    *
@@ -5080,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;
@@ -5105,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>;
@@ -5244,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;
@@ -5398,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.
@@ -5409,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.
@@ -5419,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
@@ -5451,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
@@ -5460,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;
@@ -6168,147 +6815,144 @@ declare function getAgentByName<
 ): Promise<DurableObjectStub<T>>;
 //#endregion
 export {
-  AgentToolRunPart as $,
-  MCPElicitationHandlers as $t,
-  StateUpdateMessage as A,
-  buildSubAgentPathUnchecked as An,
-  WorkflowRejectedError as At,
-  AgentToolChildAdapter as B,
-  MCPClientManagerOptions as Bt,
-  MCPServerMessage as C,
-  AgentPathStep as Cn,
-  WorkflowErrorCallback as Ct,
-  RPCResponse as D,
-  buildAgentPath as Dn,
-  WorkflowPage as Dt,
-  RPCRequest as E,
-  SubAgentPathMatch as En,
-  WorkflowInfo as Et,
-  getCurrentAgent as F,
-  MCPAITool as Ft,
-  AgentToolFailure as G,
-  MCPOAuthCallbackResult as Gt,
-  AgentToolEvent as H,
-  MCPClientOAuthResult as Ht,
-  routeAgentEmail as I,
-  MCPAIToolSet as It,
-  AgentToolMilestone as J,
-  MCP_SERVER_ID_MAX_LENGTH as Jt,
-  AgentToolInterruptedReason as K,
-  MCPServerFilter as Kt,
-  unstable_callable as L,
-  MCPClientElicitationHandler as Lt,
-  SubAgentClass as M,
-  parseSubAgentPath as Mn,
-  WorkflowTrackingRow as Mt,
-  SubAgentStub as N,
-  routeSubAgentRequest as Nn,
-  ElicitRequest$1 as Nt,
-  StartFiberOptions as O,
-  buildAgentUrl as On,
-  WorkflowProgressCallback as Ot,
-  callable as P,
-  withInvocationScope as Pn,
-  ElicitResult$2 as Pt,
-  AgentToolRunInspection as Q,
-  MCPElicitationHandler as Qt,
-  AGENT_TOOL_MILESTONE_PART as R,
-  MCPClientElicitationHandlers as Rt,
-  MCPServer as S,
-  StreamableHTTPEdgeClientTransport as Sn,
-  WorkflowCompleteCallback as St,
-  QueueItem as T,
-  SUB_PREFIX as Tn,
-  WorkflowEventPayload as Tt,
-  AgentToolEventMessage as U,
-  MCPConnectionResult as Ut,
-  AgentToolDisplayMetadata as V,
-  MCPClientOAuthCallbackConfig as Vt,
-  AgentToolEventState as W,
-  MCPDiscoverResult as Wt,
-  AgentToolProgressSnapshot as X,
-  getNamespacedData as Xt,
-  AgentToolProgress as Y,
-  RegisterServerOptions as Yt,
-  AgentToolRunInfo as Z,
-  normalizeServerId as Zt,
-  FiberInspection as _,
-  MCPStorageApi as _n,
-  RunWorkflowOptions as _t,
+  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,
-  ElicitRequest$2 as an,
-  DetachedAgentToolConfig as at,
-  FiberStatus as b,
-  WorkerTransportOptions as bn,
-  WorkflowCallbackBase as bt,
+  DurableObjectEventStore as an,
+  AgentWorkflowInternalParams as at,
+  ListFibersOptions as b,
+  AgentPathStep as bn,
+  WorkflowEventPayload as bt,
   Agent as c,
-  McpAgent as cn,
-  RunAgentToolResult as ct,
+  CreateLegacyMcpHandlerOptions as cn,
+  AgentWorkflowPathStep as ct,
   AgentStaticOptions as d,
-  createMcpHandler$1 as dn,
-  AgentWorkflowOrigin as dt,
-  RPCClientTransport as en,
-  AgentToolRunState as et,
-  CallableMetadata as f,
-  experimental_createMcpHandler as fn,
-  AgentWorkflowParams as ft,
-  FiberContext as g,
-  createLegacyMcpHandler as gn,
-  DefaultProgress as gt,
-  EmailRoutingOptions as h,
-  LegacyMcpHandler as hn,
-  ApprovalEventPayload as ht,
+  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,
-  RPC_DO_PREFIX as in,
-  ChatCapableAgentClass as it,
-  StreamingResponse as j,
-  getSubAgentByName as jn,
-  WorkflowStatus as jt,
-  StartFiberResult as k,
-  buildSubAgentPath as kn,
-  WorkflowQueryCriteria as kt,
+  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,
-  ClearableEventStore as ln,
-  AgentWorkflowEvent as lt,
-  DeleteFibersOptions as m,
-  CreateMcpHandlerOptions$1 as mn,
-  AgentWorkflowStep as mt,
+  CreateMcpHandlerOptions$1 as ln,
+  AgentWorkflowStep as lt,
+  EmailRoutingOptions as m,
+  WorkerTransport as mn,
+  WorkflowCallback as mt,
   AgentOptions as n,
-  RPCServerTransport as nn,
-  AgentToolStoredChunk as nt,
+  ElicitResult$3 as nn,
+  RunAgentToolOptions as nt,
   AddMcpServerOptions as o,
-  ElicitRequestSchema as on,
-  DetachedRunAgentToolResult as ot,
-  DEFAULT_AGENT_STATIC_OPTIONS as p,
-  CreateLegacyMcpHandlerOptions as pn,
-  AgentWorkflowPathStep as pt,
-  AgentToolLifecycleResult as q,
-  MCPServerOptions as qt,
+  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,
-  RPCServerTransportOptions as rn,
-  AgentToolTerminalStatus as rt,
+  McpAgent as rn,
+  RunAgentToolResult as rt,
   AddRpcMcpServerOptions as s,
-  ElicitResult$3 as sn,
-  RunAgentToolOptions as st,
+  experimental_createMcpHandler as sn,
+  AgentWorkflowParams as st,
   AgentGetOptions as t,
-  RPCClientTransportOptions as tn,
-  AgentToolRunStatus as tt,
+  ElicitRequestSchema as tn,
+  DetachedRunAgentToolResult as tt,
   AgentNamespace as u,
-  DurableObjectEventStore as un,
-  AgentWorkflowInternalParams as ut,
-  FiberRecoveryContext as v,
-  TransportState as vn,
-  WaitForApprovalOptions as vt,
-  MCPServersState as w,
-  BuildAgentPathOptions as wn,
-  WorkflowEventCallback as wt,
-  ListFibersOptions as x,
-  SSEEdgeClientTransport as xn,
-  WorkflowCallbackType as xt,
-  FiberRecoveryResult as y,
-  WorkerTransport as yn,
-  WorkflowCallback as yt,
-  AGENT_TOOL_PROGRESS_PART as z,
-  MCPClientManager as zt
+  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-routing-CnkaHb-v.d.ts.map
+//# sourceMappingURL=agent-routing-DE5zmCQ8.d.ts.map