agents 0.22.0 → 0.23.0

package/docs/sub-agents.md

@@ -1,40 +1,57 @@
-# Sub-agents
+# Dynamic agents (facets)
 
-Sub-agents are child Durable Objects colocated under a parent agent. Each sub-agent has its own isolated SQLite storage and its own WebSocket connections, but shares the parent's machine and is spawned, listed, and torn down through the parent. Clients reach a sub-agent directly via a nested URL; inside an agent, sub-agents are typed RPC stubs.
+Dynamic agents are child Durable Objects **colocated under and supervised by** a parent agent, built on the runtime's facet primitive. Each child runs in its **own isolate** with its **own SQLite database**, but lives inside the parent's Durable Object: the parent spawns it, can abort or delete it, and is the only way to reach it. Inside an agent they are typed RPC stubs reached via `this.dynamicAgents`; clients reach one directly via a nested URL.
 
-Use sub-agents when a single user or entity owns an open-ended set of long-lived agents — chats, documents, sessions, shards, projects — and you want each one to run in parallel with its own state while keeping one parent agent as the coordinator.
+Use dynamic agents for code whose **class or lifecycle the parent owns**: dynamically-loaded or AI-generated code that has no wrangler binding, per-run tool agents, sandboxed components that need isolated storage plus supervised abort/restart. That is what the runtime built facets for.
+
+Do **not** use dynamic agents to model an open-ended set of independent peers — many chats, documents, or sessions per user. Those want one top-level Durable Object each plus a per-user index; see [When to use dynamic agents](#when-to-use-dynamic-agents) and [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats).
 
 If you want a parent chat agent to dispatch another chat-capable agent during a
 single turn and render that child's progress inline, use [Agent Tools](./agent-tools.md).
-Agent tools are built on sub-agents, but add a parent-side run registry,
+Agent tools are built on dynamic agents, but add a parent-side run registry,
 streaming `agent-tool-event` frames, replay, cancellation, and cleanup.
 
+> **Naming**: dynamic agents were previously called **sub-agents**. The
+> `subAgent()` / `hasSubAgent()` / `listSubAgents()` / `abortSubAgent()` /
+> `deleteSubAgent()` methods still work and now delegate to the same
+> `this.dynamicAgents` capability; they are deprecated in place. The `/sub/`
+> URL segment, `useAgent({ sub })`, and the `onBeforeSubAgent` hook are
+> unchanged.
+
 ## Overview
 
 ```typescript
 import { Agent, callable } from "agents";
 
-export class Inbox extends Agent {
+export class Supervisor extends Agent {
+  @callable()
+  async runJob(runId: string, input: string) {
+    // Spawn (or reattach to) an isolated child for this run. The child
+    // gets its own isolate and its own SQLite database, colocated with
+    // and supervised by this agent.
+    const worker = await this.dynamicAgents.get(JobRunner, runId);
+    return worker.execute(input);
+  }
+
   @callable()
-  async createChat() {
-    const id = crypto.randomUUID();
-    // Spawn a child Chat Durable Object under this Inbox.
-    await this.subAgent(Chat, id);
-    return id;
+  cancelJob(runId: string) {
+    // Stops the child immediately; its storage survives for inspection.
+    this.dynamicAgents.abort(JobRunner, runId, new Error("cancelled"));
   }
 
   @callable()
-  listChats() {
-    return this.listSubAgents(Chat);
+  async cleanupJob(runId: string) {
+    // Wipes the child's storage and registry entry.
+    await this.dynamicAgents.delete(JobRunner, runId);
   }
 }
 
-export class Chat extends Agent {
-  async say(text: string) {
-    // Reach back up to the inbox by class — the framework fills in
-    // the parent's instance name from `this.parentPath`.
-    const inbox = await this.parentAgent(Inbox);
-    await inbox.recordTurn(this.name, text);
+export class JobRunner extends Agent {
+  async execute(input: string) {
+    // Runs in the child's own isolate; this.sql is the child's own DB.
+    // Reach back up by class when needed:
+    const supervisor = await this.parentAgent(Supervisor);
+    // ...
   }
 }
 ```
@@ -43,90 +60,107 @@ export class Chat extends Agent {
 // Client
 import { useAgent } from "agents/react";
 
-// Connect to the inbox for the sidebar:
-const inbox = useAgent({ agent: "Inbox", name: userId });
+// Connect to the supervisor:
+const supervisor = useAgent({ agent: "Supervisor", name: userId });
 
-// Connect to a specific chat child:
-const chat = useAgent({
-  agent: "Inbox",
+// Connect to a specific child:
+const runner = useAgent({
+  agent: "Supervisor",
   name: userId,
-  sub: [{ agent: "Chat", name: chatId }]
+  sub: [{ agent: "JobRunner", name: runId }]
 });
 ```
 
-The resulting URL for the chat connection is `/agents/inbox/{userId}/sub/chat/{chatId}`.
+The resulting URL for the child connection is `/agents/supervisor/{userId}/sub/job-runner/{runId}`.
 
 ## Concepts
 
 ```
 ┌──────────────────────────────────────────────────────────┐
-│  Inbox (Durable Object, "user-123")                      │
-│  - parent of all chats for this user                     │
-│  - owns chat list + shared memory                        │
+│  Supervisor (Durable Object, "user-123")                 │
+│  - owns the registry and lifecycle of its children       │
 │  - runs `onBeforeSubAgent` on every incoming /sub/ hop   │
+│  - owns the one physical alarm and the WebSockets        │
 └────┬─────────────────────┬───────────────────┬───────────┘
      │                     │                   │
      ▼                     ▼                   ▼
-  Chat ("chat-a")      Chat ("chat-b")     Chat ("chat-c")
-  - own SQLite         - own SQLite        - own SQLite
-  - own WS clients     - own WS clients    - own WS clients
-  - runs in parallel with siblings
+  JobRunner ("run-a")  JobRunner ("run-b")  CodemodeRuntime
+  - own isolate        - own isolate        - own isolate
+  - own SQLite         - own SQLite         - own SQLite
+  - runs in parallel with siblings, on the same machine
 ```
 
-### Colocation
+### Facet semantics
+
+Dynamic agents are backed by workerd **facets**. The properties below are what the runtime actually provides — several of them are the reason this is an isolation primitive rather than a scale-out primitive:
 
-Sub-agents (also called **facets**) live on the **same machine** as their parent. They are not independent Durable Objects scattered across the edge — they are colocated with the parent for RPC latency and shared-memory patterns. Two chats belonging to the same inbox can run in parallel because each is its own single-threaded isolate, but they all share the parent's physical location.
+- **Separate isolate, same machine.** Each facet runs in its own isolate (its own JS heap), colocated with the parent for cheap RPC. The whole tree shares the parent's physical placement and moves or dies with it — facets never scatter across the edge.
+- **Own SQLite database.** Each facet's storage is invisible to its siblings and to the parent's SQL. The runtime stores the databases together as one logical root object; do not treat a facet as an independently placed top-level storage object.
+- **No independent alarms.** Facets cannot set a physical alarm; the top-level parent owns the one alarm slot and the SDK routes scheduled callbacks back into children (see [Scheduling](#scheduling)).
+- **Supervised lifecycle.** The parent can abort a child transitively (storage survives), delete it (storage wiped), and restart the same storage under a _different class_ — a code upgrade on stable state. A broken facet breaks the whole actor, except when the parent itself aborted it.
+- **Independent hibernation.** A facet hibernates and restarts independently of its parent, but cannot outlive the root Durable Object's placement.
+- **Private addressability.** A facet is reachable only through its parent; siblings cannot see each other unless the parent passes references.
+- **Bounded nesting.** Facet trees are limited in depth (currently four levels including the root).
 
 ### Independent state
 
-Each sub-agent has its own SQLite database and its own in-memory state. Writes from one sibling never leak into another. When a sub-agent is deleted with `deleteSubAgent()`, its storage is wiped.
+Each dynamic agent has its own SQLite database and its own in-memory state. Writes from one sibling never leak into another. When a child is deleted with `this.dynamicAgents.delete()`, its storage is wiped.
 
 ### Scheduling
 
-Sub-agents can schedule their own callbacks with `this.schedule()` and `this.scheduleEvery()`:
+Dynamic agents can schedule their own callbacks with `this.schedule()` and `this.scheduleEvery()`:
 
 ```typescript
-export class Chat extends Agent {
+export class JobRunner extends Agent {
   async onStart() {
-    await this.scheduleEvery(60, "compactHistory");
+    await this.scheduleEvery(60, "checkpoint");
   }
 
-  async compactHistory() {
-    // Runs inside the Chat sub-agent.
-    // this.sql points at the Chat SQLite database.
+  async checkpoint() {
+    // Runs inside the child; this.sql points at the child's database.
   }
 }
 ```
 
-The top-level parent still owns the underlying Durable Object alarm because facets do not have independent alarm slots. The Agents SDK stores a logical owner path for the sub-agent schedule, wakes the parent when the alarm fires, then dispatches the callback back into the sub-agent. The callback runs with the sub-agent as `this`, so it uses the sub-agent's SQLite storage, state, `parentPath`, and `getCurrentAgent()` context.
+The top-level parent still owns the underlying Durable Object alarm because facets do not have independent alarm slots. The Agents SDK stores a logical owner path for the child's schedule, wakes the parent when the alarm fires, then dispatches the callback back into the child. The callback runs with the child as `this`, so it uses the child's SQLite storage, state, `parentPath`, and `getCurrentAgent()` context.
 
-`cancelSchedule()`, `getScheduleById()`, and `listSchedules()` also work inside sub-agents. They are scoped to the calling sub-agent — a sub-agent cannot cancel or list a sibling's schedules by id. To clear every schedule under a sub-agent (and any of its descendants), call `parent.deleteSubAgent(Cls, name)` from the parent. The older synchronous `getSchedule()` and `getSchedules()` APIs throw inside sub-agents because scheduled rows are stored on the top-level parent.
+`cancelSchedule()`, `getScheduleById()`, and `listSchedules()` also work inside dynamic agents. They are scoped to the calling child — a child cannot cancel or list a sibling's schedules by id. To clear every schedule under a child (and any of its descendants), call `this.dynamicAgents.delete(Cls, name)` from the parent. The older synchronous `getSchedule()` and `getSchedules()` APIs throw inside dynamic agents because scheduled rows are stored on the top-level parent.
 
-Calling `this.destroy()` inside a sub-agent delegates the same teardown back to the parent: it cancels the sub-agent's parent-owned schedules (and descendants), removes the sub-agent from the parent's registry, and asks the runtime to wipe the sub-agent's storage. Because the underlying `ctx.facets.delete` call aborts the sub-agent's isolate, treat `this.destroy()` as fire-and-forget — it may not return cleanly to the caller.
+Calling `this.destroy()` inside a dynamic agent delegates the same teardown back to the parent: it cancels the child's parent-owned schedules (and descendants), removes the child from the parent's registry, and asks the runtime to wipe the child's storage. Because the underlying `ctx.facets.delete` call aborts the child's isolate, treat `this.destroy()` as fire-and-forget — it may not return cleanly to the caller.
 
 ### Durable execution and chat recovery
 
-Sub-agents can use `runFiber()` and Think's `chatRecovery` just like top-level agents. Fiber rows live in the sub-agent's own SQLite database, so recovery hooks run with the sub-agent as `this` and see the sub-agent's state, storage, `parentPath`, and `getCurrentAgent()` context.
+Dynamic agents can use `runFiber()` and Think's `chatRecovery` just like top-level agents. Fiber rows live in the child's own SQLite database, so recovery hooks run with the child as `this` and see the child's state, storage, `parentPath`, and `getCurrentAgent()` context.
 
-Because facets do not have independent alarm slots, the top-level parent owns the physical alarm heartbeat for sub-agent fibers. The sub-agent still stores fiber rows and snapshots in its own SQLite database, while the parent stores a small root-side index of active facet fibers. When the parent alarm fires, it checks that index and routes recovery checks back into the owning sub-agent. Think's chat recovery can schedule its recovered continuation from inside the sub-agent; the parent owns the physical alarm and routes the continuation back to the child.
+Because facets do not have independent alarm slots, the top-level parent owns the physical alarm heartbeat for child fibers. The child still stores fiber rows and snapshots in its own SQLite database, while the parent stores a small root-side index of active facet fibers. When the parent alarm fires, it checks that index and routes recovery checks back into the owning child. Think's chat recovery can schedule its recovered continuation from inside the child; the parent owns the physical alarm and routes the continuation back to the child.
 
-Sub-agents can also start [Workflows](./workflows.md) with `this.runWorkflow()`. Workflow tracking is local to the sub-agent's SQLite database, and `AgentWorkflow.agent` routes RPC, callbacks, state updates, and broadcasts back to the originating sub-agent. Parent agents do not automatically list or control child-started workflows. Because `SubAgentStub<T>` only exposes user-defined child methods, add child wrapper methods for controls such as `getWorkflow()`, `approveWorkflow()`, or `terminateWorkflow()`, then call those wrappers through `await this.subAgent(Child, name)`. If you pass `runWorkflow(..., { agentBinding })` from a sub-agent, use the root Agent binding name, not a child binding name.
+Dynamic agents can also start [Workflows](./workflows.md) with `this.runWorkflow()`. Workflow tracking is local to the child's SQLite database, and `AgentWorkflow.agent` routes RPC, callbacks, state updates, and broadcasts back to the originating child. Parent agents do not automatically list or control child-started workflows. Because the child stub only exposes user-defined child methods, add child wrapper methods for controls such as `getWorkflow()`, `approveWorkflow()`, or `terminateWorkflow()`, then call those wrappers through `await this.dynamicAgents.get(Child, name)`. If you pass `runWorkflow(..., { agentBinding })` from a child, use the root Agent binding name, not a child binding name.
 
-For sub-agent workflow origins, `AgentWorkflow.agent` is RPC-only. Use it to call Agent methods, but use `routeSubAgentRequest()` or the nested `/agents/{parent}/{name}/sub/{child}/{name}` URL shape for external HTTP or WebSocket routing instead of `this.agent.fetch()`.
+For child workflow origins, `AgentWorkflow.agent` is RPC-only. Use it to call Agent methods, but use `routeSubAgentRequest()` or the nested `/agents/{parent}/{name}/sub/{child}/{name}` URL shape for external HTTP or WebSocket routing instead of `this.agent.fetch()`.
 
 ### Shared identity
 
-Sub-agents know who their parent is via `this.parentPath` (root-first ancestor chain) and `this.parentAgent(ParentClass)` (typed stub). A sub-agent with no parent (top-level agent) has `parentPath === []`.
+Dynamic agents know who their parent is via `this.parentPath` (root-first ancestor chain) and `this.parentAgent(ParentClass)` (typed stub). A child with no parent (top-level agent) has `parentPath === []`.
 
 ## Server API
 
-### `this.subAgent(Cls, name)`
+The capability lives at `this.dynamicAgents`. The legacy method names delegate to it and remain supported:
+
+| Legacy (deprecated)              | Capability                             |
+| -------------------------------- | -------------------------------------- |
+| `this.subAgent(Cls, name)`       | `this.dynamicAgents.get(Cls, name)`    |
+| `this.abortSubAgent(Cls, name)`  | `this.dynamicAgents.abort(Cls, name)`  |
+| `this.deleteSubAgent(Cls, name)` | `this.dynamicAgents.delete(Cls, name)` |
+| `this.hasSubAgent(Cls, name)`    | `this.dynamicAgents.has(Cls, name)`    |
+| `this.listSubAgents(Cls?)`       | `this.dynamicAgents.list(Cls?)`        |
+
+### `this.dynamicAgents.get(Cls, name)`
 
-Get or create a sub-agent. Lazy: the first call for `(Cls, name)` spawns the child; subsequent calls return the existing instance. Returns a typed RPC stub.
+Get or create a dynamic agent. Lazy: the first call for `(Cls, name)` spawns the child; subsequent calls return the existing instance. Returns a typed RPC stub.
 
 ```typescript
-const chat = await this.subAgent(Chat, "chat-abc");
-await chat.ping();
+const runner = await this.dynamicAgents.get(JobRunner, "run-abc");
+await runner.ping();
 ```
 
 The child class must:
@@ -138,46 +172,48 @@ The child class must:
 
 The parent class also has requirements that are implicit for normal usage but worth knowing if you hit the related error:
 
-- Be bound as a Durable Object namespace in `wrangler.jsonc durable_objects.bindings`. (Top-level agents always are — this matters only if you try to call `subAgent()` from a class that's exported but unbound.)
+- Be bound as a Durable Object namespace in `wrangler.jsonc durable_objects.bindings`. (Top-level agents always are — this matters only if you try to call `dynamicAgents.get()` from a class that's exported but unbound.)
 - Have its class name preserved by your bundler. The framework looks the parent up via `ctx.exports[this.constructor.name].idFromName(name)` to give the child its own `ctx.id.name`. If your bundler minifies class identifiers (e.g. esbuild without `keepNames: true`), `this.constructor.name` becomes a short id like `_a` and the lookup fails. The framework throws a descriptive error in that case pointing at the bundler config.
 
+For code with **no static class at all** — dynamically-loaded or generated Durable Object classes from Worker Loader — mount the class as a facet directly with `ctx.facets.get`; see [`examples/next/dynamic-agents`](https://github.com/cloudflare/agents/tree/main/examples/next/dynamic-agents) for the supervised-gadget pattern.
+
 ### Notes for testing
 
 Tests that use `@cloudflare/vitest-pool-workers` may need to list facet classes as test-only Durable Object bindings so `ctx.exports` provides a facet-compatible class value. Keep those facet classes out of `new_sqlite_classes`; the extra binding belongs only in test `wrangler.jsonc` files and is not a production Worker requirement.
 
-### `this.deleteSubAgent(Cls, name)`
+### `this.dynamicAgents.delete(Cls, name)`
 
-Abort a running sub-agent, cancel its pending schedules, and permanently wipe its storage. Idempotent — safe to call for a never-spawned or already-deleted child.
+Abort a running child, cancel its pending schedules, and permanently wipe its storage. Idempotent — safe to call for a never-spawned or already-deleted child.
 
 ```typescript
-await this.deleteSubAgent(Chat, "chat-abc");
+await this.dynamicAgents.delete(JobRunner, "run-abc");
 ```
 
-### `this.abortSubAgent(Cls, name, reason?)`
+### `this.dynamicAgents.abort(Cls, name, reason?)`
 
-Forcefully abort a running sub-agent without wiping its storage. The child stops executing immediately and will be restarted on next `subAgent()` access.
+Forcefully abort a running child without wiping its storage. The child stops executing immediately and will be restarted on next `dynamicAgents.get()` access.
 
 ```typescript
-this.abortSubAgent(Chat, "chat-abc", new Error("quota exceeded"));
+this.dynamicAgents.abort(JobRunner, "run-abc", new Error("quota exceeded"));
 ```
 
-### `this.hasSubAgent(Cls | className, name)`
+### `this.dynamicAgents.has(Cls | className, name)`
 
 Check whether a child has been spawned and not deleted. Backed by a framework-maintained SQLite registry.
 
 ```typescript
-if (!this.hasSubAgent(Chat, id)) {
+if (!this.dynamicAgents.has(JobRunner, id)) {
   return new Response("not found", { status: 404 });
 }
 ```
 
-### `this.listSubAgents(Cls?)`
+### `this.dynamicAgents.list(Cls?)`
 
-List spawned sub-agents, optionally filtered by class. Returns `{ className, name, createdAt }` rows in creation order.
+List spawned children, optionally filtered by class. Returns `{ className, name, createdAt }` rows in creation order.
 
 ```typescript
-const chats = this.listSubAgents(Chat);
-// → [{ className: "Chat", name: "...", createdAt: 1700... }, ...]
+const runs = this.dynamicAgents.list(JobRunner);
+// → [{ className: "JobRunner", name: "...", createdAt: 1700... }, ...]
 ```
 
 ### `this.onBeforeSubAgent(req, { className, name })`
@@ -193,11 +229,11 @@ Return one of:
 | `Response`   | Short-circuit: send this response to the client, do not wake the child |
 
 ```typescript
-export class Inbox extends Agent {
+export class Supervisor extends Agent {
   override async onBeforeSubAgent(_req, { className, name }) {
-    // Strict-registry gate: only allow clients to reach chats that
-    // have actually been created via `createChat`.
-    if (!this.hasSubAgent(className, name)) {
+    // Strict-registry gate: only allow clients to reach children that
+    // have actually been created by this agent.
+    if (!this.dynamicAgents.has(className, name)) {
       return new Response(`${className} "${name}" not found`, {
         status: 404
       });
@@ -215,23 +251,23 @@ WebSocket upgrade requests flow through this hook the same way as plain HTTP. If
 Root-first ancestor chains. `parentPath` covers strict ancestors; `selfPath` includes the current agent.
 
 ```typescript
-// Inside a Chat that was spawned by an Inbox:
+// Inside a JobRunner that was spawned by a Supervisor:
 this.parentPath;
-// → [{ className: "Inbox", name: "user-123" }]
+// → [{ className: "Supervisor", name: "user-123" }]
 
 this.selfPath;
-// → [{ className: "Inbox", name: "user-123" }, { className: "Chat", name: "chat-abc" }]
+// → [{ className: "Supervisor", name: "user-123" }, { className: "JobRunner", name: "run-abc" }]
 ```
 
 `parentPath` is **root-first**, so the direct parent is always `parentPath.at(-1)`. Top-level agents have `parentPath === []`.
 
 ### `this.parentAgent(Cls)`
 
-Typed parent stub to the **immediate** parent, resolved from `parentPath`. Symmetric with `subAgent(Cls, name)`: one opens a stub parent→child, the other opens a stub child→parent.
+Typed parent stub to the **immediate** parent, resolved from `parentPath`. Symmetric with `dynamicAgents.get(Cls, name)`: one opens a stub parent→child, the other opens a stub child→parent.
 
 ```typescript
-const inbox = await this.parentAgent(Inbox);
-await inbox.recordTurn(this.name, "...");
+const supervisor = await this.parentAgent(Supervisor);
+await supervisor.recordProgress(this.name, "...");
 ```
 
 The framework:
@@ -259,16 +295,16 @@ When `parentAgent()` returns a facet-parent proxy, RPC methods and normal HTTP `
 Extend any `useAgent` call with a `sub` chain to connect to a descendant facet:
 
 ```tsx
-const chat = useAgent({
-  agent: "Inbox",
+const runner = useAgent({
+  agent: "Supervisor",
   name: userId,
-  sub: [{ agent: "Chat", name: chatId }]
+  sub: [{ agent: "JobRunner", name: runId }]
 });
 ```
 
 - `agent` / `name` identify the **top-level** agent (the one bound in `env`).
 - `sub` is a root-first array of `{ agent, name }` hops into descendants.
-- The hook builds the URL `/agents/inbox/{userId}/sub/chat/{chatId}` and opens a direct WebSocket to the `Chat` child.
+- The hook builds the URL `/agents/supervisor/{userId}/sub/job-runner/{runId}` and opens a WebSocket routed to the child.
 - `.path` on the returned hook object gives you the full chain including the leaf.
 
 Every other `useAgent` feature works as usual: `state` sync, `stub.method()` calls, `@callable` RPCs, `useAgentChat` on top of the returned socket.
@@ -282,13 +318,13 @@ import { buildAgentPath } from "agents";
 
 const path = buildAgentPath(
   [
-    { className: "Inbox", name: userId },
-    { className: "Chat", name: chatId }
+    { className: "Supervisor", name: userId },
+    { className: "JobRunner", name: runId }
   ],
   { leafPath: "/callbacks/job" }
 );
 
-// /agents/inbox/{userId}/sub/chat/{chatId}/callbacks/job
+// /agents/supervisor/{userId}/sub/job-runner/{runId}/callbacks/job
 ```
 
 Inside an Agent, pass `this.selfPath` directly. If the root Durable Object binding name differs from its class name, also pass `rootBinding` in the options. `buildAgentUrl()` adds a public origin, which is useful when registering callbacks, webhooks, approval URLs, or asynchronous job-completion URLs with an external system:
@@ -296,7 +332,7 @@ Inside an Agent, pass `this.selfPath` directly. If the root Durable Object bindi
 ```typescript
 import { buildAgentUrl } from "agents";
 
-export class Chat extends Agent<Env> {
+export class JobRunner extends Agent<Env> {
   callbackUrl() {
     return buildAgentUrl(this.env.PUBLIC_ORIGIN, this.selfPath, {
       leafPath: "/callbacks/job"
@@ -312,7 +348,7 @@ export class Chat extends Agent<Env> {
 }
 ```
 
-The Worker must pass the incoming request to `routeAgentRequest()`. Each ancestor's `onBeforeSubAgent` hook runs before the destination receives the request. For a sub-agent destination, the nested `/sub/...` routing segments are removed during forwarding, so its pathname is the `leafPath` suffix.
+The Worker must pass the incoming request to `routeAgentRequest()`. Each ancestor's `onBeforeSubAgent` hook runs before the destination receives the request. For a dynamic-agent destination, the nested `/sub/...` routing segments are removed during forwarding, so its pathname is the `leafPath` suffix.
 
 `buildAgentUrl()` accepts an HTTP(S) or WS(S) origin without a pathname, query, fragment, or credentials. Set callback query parameters through the returned URL's `searchParams`. If you use a custom routing prefix, pass the same value to both `buildAgentPath()` and `routeAgentRequest()`.
 
@@ -320,7 +356,7 @@ Root Agent names follow `routeAgentRequest`'s raw pathname-segment behavior and
 
 ### Custom routing
 
-For fetch handlers that do their own top-level URL parsing, use `routeSubAgentRequest` to dispatch a request into a sub-agent from an already-resolved parent stub:
+For fetch handlers that do their own top-level URL parsing, use `routeSubAgentRequest` to dispatch a request into a dynamic agent from an already-resolved parent stub:
 
 ```typescript
 import { getAgentByName, routeSubAgentRequest } from "agents";
@@ -332,25 +368,25 @@ export default {
     if (!match) return new Response("Not found", { status: 404 });
 
     const [, userId, rest] = match;
-    const parent = await getAgentByName(env.Inbox, userId);
+    const parent = await getAgentByName(env.Supervisor, userId);
     return routeSubAgentRequest(req, parent, { fromPath: rest });
   }
 };
 ```
 
-`fromPath` takes any pathname containing the sub-agent tail (something like `/sub/chat/chat-abc/...`). When the destination is already represented as a root-first Agent path, pass the result of `buildAgentPath()` directly. The helper parses the first child hop, runs the parent's `onBeforeSubAgent` hook, and forwards into the facet.
+`fromPath` takes any pathname containing the sub-agent tail (something like `/sub/job-runner/run-abc/...`). When the destination is already represented as a root-first Agent path, pass the result of `buildAgentPath()` directly. The helper parses the first child hop, runs the parent's `onBeforeSubAgent` hook, and forwards into the facet.
 
 ### External typed RPC
 
-From inside the parent DO, `this.subAgent(Cls, name)` returns a typed stub. From **outside** the parent, use `getSubAgentByName`:
+From inside the parent DO, `this.dynamicAgents.get(Cls, name)` returns a typed stub. From **outside** the parent, use `getSubAgentByName`:
 
 ```typescript
 import { getAgentByName, getSubAgentByName } from "agents";
 
-const inbox = await getAgentByName(env.Inbox, userId);
-const chat = await getSubAgentByName(inbox, Chat, chatId);
+const supervisor = await getAgentByName(env.Supervisor, userId);
+const runner = await getSubAgentByName(supervisor, JobRunner, runId);
 
-await chat.addMessage({ role: "user", content: "hi" });
+await runner.execute("hi");
 ```
 
 `getSubAgentByName` returns an RPC-only Proxy — method calls work; `.fetch()` throws (use `routeSubAgentRequest` for HTTP/WS). Arguments and return values must be structured-cloneable.
@@ -359,7 +395,7 @@ await chat.addMessage({ role: "user", content: "hi" });
 
 ### Creation
 
-`subAgent(Cls, name)` is lazy and idempotent:
+`dynamicAgents.get(Cls, name)` is lazy and idempotent:
 
 - The first call for a name triggers the child's `onStart()`.
 - Subsequent calls are no-ops and return the existing instance.
@@ -373,59 +409,83 @@ When a client connects to `/agents/{parent}/{name}/sub/{child}/{childName}`:
 2. The parent's `onBeforeSubAgent` fires.
 3. If the hook does not short-circuit, the framework resolves the facet (creating it on first access, unless the hook rejected with a `Response`).
 4. The request is forwarded to the child, which handles the WebSocket upgrade or HTTP response.
-5. After the upgrade, subsequent WebSocket frames flow **directly** to the child — the parent is no longer on the hot path.
+5. The **parent owns the native WebSocket for the connection's lifetime.** Every subsequent frame wakes the root parent, which forwards it to the child over serializable RPC (the parent's own gating logic does not re-run per frame); replies come back the same way. The parent stays on the hot path — a design consequence of hibernation-safe sockets, and one more reason not to fan an unbounded number of busy WebSocket sessions through one parent.
 
 ### Deletion
 
-`deleteSubAgent(Cls, name)` aborts any running instance, removes pending schedules for that sub-agent tree, deletes its storage, and removes its registry entry. Idempotent.
+`dynamicAgents.delete(Cls, name)` aborts any running instance, removes pending schedules for that child's tree, deletes its storage, and removes its registry entry. Idempotent.
 
 ### Hibernation
 
-Sub-agents hibernate when idle, same as any Durable Object. `this.name` is restored automatically from the facet's `ctx.id` (the runtime carries it across eviction). `this.parentPath` is persisted during `_cf_initAsFacet` and restored on wake.
+Dynamic agents hibernate when idle, same as any Durable Object. `this.name` is restored automatically from the facet's `ctx.id` (the runtime carries it across eviction). `this.parentPath` is persisted at facet init and restored on wake.
 
-## Scheduling and durable work in sub-agents
+## Scheduling and durable work in dynamic agents
 
-Sub-agents can schedule their own callbacks and run durable fibers:
+Dynamic agents can schedule their own callbacks and run durable fibers:
 
-- `this.schedule()` / `this.scheduleEvery()` / `this.cancelSchedule()` work on a sub-agent.
-- `this.getScheduleById()` / `this.listSchedules()` work on a sub-agent.
-- `this.runFiber()` and Think `chatRecovery` work on a sub-agent.
+- `this.schedule()` / `this.scheduleEvery()` / `this.cancelSchedule()` work on a child.
+- `this.getScheduleById()` / `this.listSchedules()` work on a child.
+- `this.runFiber()` and Think `chatRecovery` work on a child.
 
-The top-level parent still owns the physical alarm because facets do not have independent alarm slots. The Agents SDK stores the child owner path with each schedule row, wakes the parent, and routes the callback back into the child. `keepAlive()` and `keepAliveWhile()` work in sub-agents by delegating their heartbeat ref to the top-level parent. `runFiber()` also works in sub-agents: fiber rows and snapshots live in the child's own SQLite database, and the parent keeps a small root-side index so alarm housekeeping can route recovery checks back into idle children.
+The top-level parent still owns the physical alarm because facets do not have independent alarm slots. The Agents SDK stores the child owner path with each schedule row, wakes the parent, and routes the callback back into the child. `keepAlive()` and `keepAliveWhile()` work in dynamic agents by delegating their heartbeat ref to the top-level parent. `runFiber()` also works in dynamic agents: fiber rows and snapshots live in the child's own SQLite database, and the parent keeps a small root-side index so alarm housekeeping can route recovery checks back into idle children.
 
 ## Broadcasts
 
-`this.broadcast(msg)` and `setState()`-driven broadcasts work the same way inside a sub-agent as in a top-level agent — they go to the sub-agent's own WebSocket clients. Siblings do not see each other's broadcasts; reach them explicitly via RPC if needed.
+`this.broadcast(msg)` and `setState()`-driven broadcasts work the same way inside a dynamic agent as in a top-level agent — they go to the child's own WebSocket clients. Siblings do not see each other's broadcasts; reach them explicitly via RPC if needed. (The frames are physically sent by the root parent, which owns the native sockets.)
+
+## When to use dynamic agents
+
+The decision rule: **a facet is a child whose code or lifecycle the parent supervises and which must live inside the parent; an independent peer you address by name should be its own top-level Durable Object.**
+
+| Situation                                                                        | Dynamic agents?                                        |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Dynamically-loaded or AI-generated code needs durable, isolated storage          | Yes — the only way; there is no binding to give it     |
+| Per-run tool agents with isolated scratch state, supervised abort, and cleanup   | Yes (see [Agent Tools](./agent-tools.md))              |
+| A component needs isolated storage + independent abort, colocated with the agent | Yes (codemode runtimes, sandboxes, connector wrappers) |
+| The parent should control what class runs over the child's storage (upgrades)    | Yes — restart the same storage under new code          |
+| Many chats / documents / sessions per user                                       | **No** — one top-level DO each + a per-user index      |
+| The children need independent geographic placement or scaling                    | No — top-level DOs                                     |
+| The children need independent physical alarm slots                               | No — top-level DOs; revisit when facet alarms ship     |
+| High-fan-out busy WebSocket sessions                                             | No — every frame wakes the one root parent             |
 
-## When to use sub-agents
+### The recommended many-chats pattern
+
+One top-level Durable Object per chat, plus a per-user index DO the chats push their metadata into:
+
+```typescript
+// ChatAgent (one DO per chat) pushes on every write, through whatever
+// RPC surface the hub exposes over its RoutedAgents catalog. `seq` is a
+// strictly monotonic per-chat ordinal, not a wall-clock timestamp — two
+// messages sent back to back can round-trip inside one millisecond and
+// a wall-clock fence would tie, silently discarding the newer push.
+const user = await getAgentByName(this.env.UserAgent, ownerUserId);
+await user.recordChatActivity(chatId, { title, lastMessage, seq });
+
+// UserAgent (the hub) answers listing and cross-chat search from its
+// own SQLite — no chat DO wakes up — and applies the push with
+// `this.chats.setMetadata(chatId, meta)` after fencing `seq` against
+// the entry's current value inside `blockConcurrencyWhile`, so a push
+// delayed by a slow round-trip can't overwrite one that arrived first,
+// and two concurrent pushes can't both read the same stale value.
+```
 
-| Situation                                                                          | Sub-agents?                                        |
-| ---------------------------------------------------------------------------------- | -------------------------------------------------- |
-| One user owns an open-ended set of long-lived contexts (chats, docs, sessions)     | Yes                                                |
-| You want each context to run in parallel with isolated state                       | Yes                                                |
-| You want a single parent DO to own the index, the shared memory, and the lifecycle | Yes                                                |
-| You need a worker pool, scatter/gather, or ephemeral task isolation                | Often yes                                          |
-| You have a single conversation per user and no need for per-context isolation      | No — just use one agent                            |
-| The children need independent geographic placement                                 | No — top-level DOs instead                         |
-| The children need their own logical scheduled callbacks or chat recovery           | Yes                                                |
-| The children need independent physical alarm slots                                 | No — top-level DOs; revisit when facet alarms ship |
+`RoutedAgents` packages the hub side of this pattern: a durable ID-to-Agent catalog plus request and WebSocket forwarding under one route segment. See [Routing to independent Agents](./routing.md#routing-to-independent-agents).
 
-## Example
+Each chat gets its own alarms, placement, and storage budget; deletion is one `chats.delete(id)` call; and "search across all my chats" reads only the index. The example treats that index as a best-effort derived projection: a failed push leaves it stale until the next message, and a push for a deleted chat is refused. See [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats) for the pattern built on `RoutedAgents`, with tests. Idempotency and repair belong to the production design in [`design/rfc-user-chat-durable-objects.md`](https://github.com/cloudflare/agents/blob/main/design/rfc-user-chat-durable-objects.md).
 
-See [`examples/multi-ai-chat`](https://github.com/cloudflare/agents/tree/main/examples/multi-ai-chat) for a complete multi-session chat app:
+## Examples
 
-- `Inbox` is a top-level agent per user — owns the chat list, shared memory, and the strict-registry gate.
-- `Chat` is an `AIChatAgent` facet. Each chat runs in parallel; storage is isolated.
-- Server spawns via `this.subAgent(Chat, id)`; client connects via `useAgent({ sub: [...] })`.
-- Shared-memory tools inside the chat use `this.parentAgent(Inbox)` to write into the parent.
+- [`examples/next/dynamic-agents`](https://github.com/cloudflare/agents/tree/main/examples/next/dynamic-agents) — the headline use case: a supervisor stores user-submitted Durable Object code, loads it via Worker Loader, and runs it as facets with isolated storage, supervised abort, and code upgrades over stable state.
+- [`examples/agents-as-tools`](https://github.com/cloudflare/agents/tree/main/examples/agents-as-tools) — per-run child agents as tools with inline streaming.
+- [`examples/multi-ai-chat`](https://github.com/cloudflare/agents/tree/main/examples/multi-ai-chat) — a multi-session chat app built on facet children under one `Inbox`. It works and demonstrates the routing surface, but for many long-lived chats per user prefer the top-level-DO-per-chat pattern in [`examples/next/chats`](https://github.com/cloudflare/agents/tree/main/examples/next/chats) — see [When to use dynamic agents](#when-to-use-dynamic-agents).
 
 ## Related
 
 - [Think sub-agents and programmatic turns](https://github.com/cloudflare/agents/blob/main/docs/think/sub-agents.md) — Think's `chat()` RPC method for streaming from a parent to a Think-based child
-- [Agent Tools](./agent-tools.md) — run Think or `AIChatAgent` sub-agents as tools with inline streaming child timelines
-- [Long-running agents](./long-running-agents.md) — how sub-agents fit alongside `schedule`, `runFiber`, and workflows
-- [Callable methods](./callable-methods.md) — `@callable` methods work unchanged on sub-agents
-- [Scheduling](./scheduling.md) — scheduling primitives for top-level agents and sub-agents
+- [Agent Tools](./agent-tools.md) — run Think or `AIChatAgent` children as tools with inline streaming child timelines
+- [Long-running agents](./long-running-agents.md) — how dynamic agents fit alongside `schedule`, `runFiber`, and workflows
+- [Callable methods](./callable-methods.md) — `@callable` methods work unchanged on dynamic agents
+- [Scheduling](./scheduling.md) — scheduling primitives for top-level and dynamic agents
 
 ## See also