agents 0.22.0 → 0.23.0

package/docs/lifecycle.md

@@ -26,7 +26,7 @@ export class MyObject extends DurableObject<Env> {
   }
 
   onAlarm(): void {
-    // Runs after lifecycle capabilities process the alarm.
+    // Runs once per alarm invocation, after due jobs are driven.
   }
 }
 ```
@@ -65,24 +65,34 @@ export default {
 The default URL shape is `/agents/:binding/:name`. Direct
 `env.MY_OBJECT.getByName(name).fetch(request)` calls work as well.
 
-`Agent` already constructs this lifecycle. Existing Agent classes continue to
-override `onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and
-`onError` normally.
+`Agent` already constructs this lifecycle (and installs the `WebSockets`
+capability for its connections). Existing Agent classes continue to override
+`onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and `onError`
+normally.
 
 ## Request call path
 
+The lifecycle-installed `fetch` is the request handler. It offloads each
+request to the installed capabilities, which act as middleware: the first
+capability registered that matches the request handles it by returning a
+`Response`. A capability that returns `undefined` passes the request on to
+the next capability, and a request no capability claims falls through to the
+host's `onRequest`.
+
 ```text
 routeAgentRequest(request)
 └─ named Durable Object stub.fetch(request)
    └─ lifecycle-installed fetch
       ├─ lifecycle startup capabilities
       ├─ host onStart
-      ├─ lifecycle request capabilities
-      │  └─ first Response wins
+      ├─ capability middleware, in registration order
+      │  └─ first Response handles the request
       └─ host onRequest
 ```
 
-A warm object skips startup but still offers every request to its capabilities.
+A warm object skips startup but still offers every request to its middleware.
+There is no `next()` today: a capability either handles a request or declines
+it, and cannot wrap or observe a downstream response.
 
 ## Reusable capabilities
 
@@ -107,10 +117,6 @@ class AuditLog implements DurableObjectCapability {
       return new Response("ok");
     }
   }
-
-  onAlarm(): void {
-    this.storage.sql.exec("DELETE FROM audit_log");
-  }
 }
 ```
 
@@ -127,12 +133,19 @@ export class MyObject extends DurableObject<Env> {
 }
 ```
 
-Capabilities run in registration order. Startup and alarms run every hook
-sequentially. Request handling stops at the first returned `Response`. A phase
+Capabilities run in registration order. Startup runs every hook
+sequentially. Request handling is middleware dispatch: it stops at the first
+returned `Response`, and returning `undefined` passes the request on. A phase
 failure propagates, and failed startup can be retried.
 
+A capability installed with `{ fallback: true }` dispatches after every
+non-fallback capability, whenever it was installed. This is for a host's
+catch-all: `Agent` installs its WebSockets capability as a fallback, so a
+subclass that installs request or upgrade middleware from its own
+constructor still runs first, even though `Agent`'s constructor ran earlier.
+
 Capabilities extending `LifecycleCapability` receive one standard service
-surface: storage, readiness, startup state, alarm coordination, a host
+surface: storage, readiness, startup state, the job queue, a host
 invocation boundary, best-effort events, and capability routing.
 Host-specific bindings, authentication, and protocol adapters remain explicit
 constructor dependencies. Lifecycle never grants a capability the complete
@@ -143,46 +156,59 @@ Capability hooks run outside host context, but user callbacks run through
 Scheduler dispatches its registered callbacks through this boundary, and a
 future capability that calls user code should do the same.
 
-## Shared alarm ownership
+## The job queue
 
-Lifecycle owns the Durable Object's single physical alarm. A capability that
-needs a future wake-up keeps its work in its own durable storage and implements
-`getNextAlarm()`:
+Lifecycle owns the Durable Object's queue of durable work and its single
+physical alarm. A job is a serialisable callback address — the owning
+capability plus a function name — with a due time and a payload. A capability
+that needs future work pushes a job and implements `onJob()`:
 
 ```ts
-import { LifecycleCapability, type AlarmContribution } from "agents/lifecycle";
+import {
+  LifecycleCapability,
+  type LifecycleJobContext
+} from "agents/lifecycle";
 
 class Cleanup extends LifecycleCapability {
   constructor() {
     super("cleanup");
   }
 
-  async getNextAlarm(): Promise<AlarmContribution> {
-    return (await this.lifecycle.storage.get<number>("cleanup:next")) ?? null;
+  async scheduleCleanup(time: number): Promise<void> {
+    await this.lifecycle.jobs.push({ id: "cleanup", fn: "sweep", time });
   }
 
-  async onAlarm(): Promise<void> {
-    const next = await this.lifecycle.storage.get<number>("cleanup:next");
-    if (next === undefined || next > Date.now()) return;
-    await this.lifecycle.storage.delete("cleanup:next");
-  }
-
-  async scheduleCleanup(time: number): Promise<void> {
-    await this.lifecycle.storage.put("cleanup:next", time);
-    await this.lifecycle.alarms.rearm();
+  async onJob({ job }: LifecycleJobContext): Promise<void> {
+    // job.fn === "sweep"; returning nothing completes the job.
+    await this.lifecycle.storage.delete("cleanup:marker");
   }
 }
 ```
 
-Lifecycle selects the earliest contribution from every capability and the
-host. It runs all capability `onAlarm()` hooks, then host `onAlarm()`, then
-recalculates the physical alarm. Capabilities do not depend on Scheduler or on
-each other merely to receive alarm wakes.
-A contribution can be `{ time, exclusive: true }` when its wake time must
-replace ordinary wake candidates, such as a pending teardown. This changes only
-which physical alarm is armed; when that alarm fires, normal capability and host
-hook order still applies. Hosts can implement `getNextAlarm()` for alarm work
-that has not yet been extracted into a capability.
+The queue is ordered by timestamp, and every queue mutation re-arms the
+physical alarm automatically — there is no explicit rearm call. When the
+alarm fires, Lifecycle drives due jobs in due order as an event loop, then
+runs host `onAlarm()`, then re-arms from queue state. Before driving any job
+it arms a deadman pre-alarm so an isolate death mid-drive still wakes the
+object to resume.
+
+A job's drive result decides what happens next: returning nothing completes
+and deletes it, `{ rescheduleAt }` suspends it until a future time, and
+`"yield"` leaves it due so the object wakes again immediately. Lifecycle also
+owns dispatch retries: a job's `retry` options bound in-process attempts,
+platform-class failures (a superseded isolate after a deploy, a memory-limit
+reset) preserve the job for a fresh invocation, and a terminal application
+failure reaches the owner's `onJobError()`, whose result decides advancement.
+
+A job pushed with `exclusive: true` suppresses ordinary alarm candidates
+while it is pending — Agent's deferred destroy uses this so a condemned
+object cannot be kept alive by other work. A `singleflight` job is skipped
+while a previous run is still in flight, until it crosses its hung timeout.
+The host pushes jobs through `lifecycle.jobs` and implements the same
+`onJob()` hook (a host job's terminal failure completes it; the host
+re-derives its jobs from durable state). Capabilities do not depend on
+Scheduler or
+on each other merely to receive wakes.
 
 ## Capability events
 
@@ -217,7 +243,7 @@ dispatch. A host with child objects supplies the transport internally.
 
 Agent uses this for facet schedules: Scheduler sends owner-scoped CRUD to the
 root Scheduler and routes due callbacks back to the matching facet Scheduler.
-Existing rows remain in the root `cf_agents_schedules` table. Scheduler does not
+Facet schedules live as jobs in the root's queue. Scheduler does not
 implement facet traversal, and Agent exposes only one internal generic Lifecycle
 route aperture.
 
@@ -267,33 +293,54 @@ Host context values follow the invocation:
 
 - `onStart` and `onAlarm`: object;
 - `onRequest`: object and request;
-- `onConnect`: object, connection, and upgrade request;
-- `onMessage`, `onClose`, and `onError`: object and connection.
+- `WebSockets` capability handlers `onConnect`: object, connection, and
+  upgrade request;
+- `WebSockets` capability handlers `onMessage`, `onClose`, and `onError`:
+  object and connection.
 
 `getConnectionTags(connection, { request })` remains argument-driven because it
 already receives both values explicitly. The root `agents` package continues
 to export `getCurrentAgent()` for the `Agent` class as a compatibility alias.
 
-## WebSockets always hibernate
-
-The lifecycle always uses Cloudflare's WebSocket Hibernation API. Idle clients
-remain connected while the Durable Object can leave memory. When a message
-wakes the object, its constructor and lifecycle startup run again before
-`onMessage`.
+## WebSockets are an opt-in capability
 
-State needed after a wake must be stored durably or through connection state:
+Lifecycle itself does not model WebSockets. Hosts that want connections
+install the `WebSockets` capability, which owns the subsystem end to end —
+it claims upgrades, accepts hibernating sockets, dispatches handlers inside
+the host invocation boundary, and answers `getConnections()`:
 
 ```ts
-onConnect(connection: Connection): void {
-  connection.setState({ authenticated: true });
-}
+import { WebSockets } from "agents/websockets";
 
-onMessage(connection: Connection<{ authenticated: boolean }>): void {
-  console.log(connection.state?.authenticated);
+export class MyObject extends DurableObject<Env> {
+  readonly webSockets = new WebSockets({
+    handlers: {
+      onConnect: (connection) => {
+        connection.setState({ authenticated: true });
+      },
+      onMessage: (connection, message) => {
+        connection.send(`echo:${message}`);
+      }
+    }
+  });
+  readonly lifecycle = Lifecycle.install(this).use(this.webSockets);
 }
 ```
 
-There is no non-hibernating mode.
+Without the capability installed, WebSocket upgrades are declined.
+
+The capability can also serve remote methods: pass an `RpcTarget` as
+`callables` and its prototype methods become the complete remote interface,
+served over a Cap'n Web session (`?__agents_rpc=capnweb`). An `Agent` adds
+no new surface for this — its `@callable()`-decorated methods are its
+interface, served on every wire: natively over the legacy JSON RPC protocol
+and, through the decorator-derived target, over the Cap'n Web endpoint.
+
+Connections use Cloudflare's WebSocket Hibernation API. Idle clients remain
+connected while the Durable Object can leave memory; when a message wakes the
+object, its constructor and lifecycle startup run again before `onMessage`.
+State needed after a wake must be stored durably or through
+`connection.setState()`. There is no non-hibernating mode.
 
 ## Native RPC
 

package/docs/long-running-agents.md

@@ -505,7 +505,7 @@ This pattern has several advantages for long-running agents:
 
 ## Delegating to sub-agents
 
-A project manager does not do everything itself. It delegates specialized work to sub-agents — child Durable Objects (facets) spawned under the parent. Each facet has its own isolated SQLite state and runs in parallel, but stays colocated on the same machine as the parent.
+A project manager does not do everything itself. It delegates specialized work to sub-agents — child Durable Objects (facets) spawned under the parent. Each facet has its own isolated SQLite state and runs in parallel, but stays colocated on the same machine as the parent. This per-run, parent-supervised delegation is the use case facets are for; see [When to use dynamic agents](./sub-agents.md#when-to-use-dynamic-agents) before reaching for one to model long-lived independent peers.
 
 ```typescript
 export class ProjectManager extends Agent<Env, ProjectState> {
@@ -623,7 +623,7 @@ The [Session API](./sessions.md) addresses this directly:
 
 - **Compaction** — automatically summarizes older messages when the estimated token count exceeds a threshold. The summary replaces the middle of the conversation as a non-destructive overlay. Original messages remain in SQLite for audit.
 - **Context blocks** — persistent structured sections injected into the system prompt (identity, memory, learned facts). The agent or the LLM can write to these blocks, and they survive hibernation and eviction.
-- **Multi-session management** — `SessionManager` provides a registry of named sessions within a single agent, with forking, cross-session search, and `compactAndSplit` for splitting long conversations into linked continuations.
+- **Conversation isolation** — use one Durable Object per user-facing conversation and keep the conversation directory in a parent Durable Object. Sessions can still fork paths or use named handles for local drafts and namespaces.
 
 For simpler cases: keep only the last N messages in the active context (sliding window), or selectively retain messages that contain decisions and approvals while pruning routine exchanges.
 

package/docs/mcp-servers.md

@@ -78,7 +78,11 @@ createMcpHandler(() => createServer(), {
 });
 ```
 
-All upstream SDK v2 handler options pass through. Use `createLegacyMcpHandler` for WorkerTransport, storage, session, and event-store options.
+`createMcpHandler` supports upstream SDK v2 handler options except `bus`, which is not exposed by the Agents SDK. Supplying `bus` throws a `TypeError`.
+
+To publish change events, use the returned handler's `notify` methods, such as `handler.notify.toolsChanged()`. Create the handler once at module scope and reuse it for requests and notifications. Notifications are isolate-local: they do not reach subscriptions in other Worker isolates. See the [handler notification API](https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/#publish-list-and-resource-changes) for the available methods.
+
+Use `createLegacyMcpHandler` for SDK v1 WorkerTransport, storage, session, and event-store options. The SDK v2 `bus` option is not available on that handler either.
 
 The handler validates every present `Origin` header before serving the request. It rejects malformed, opaque, and non-HTTP origins. Requests without `Origin` remain valid for non-browser MCP clients.
 

package/docs/resumable-streaming.md

@@ -70,7 +70,7 @@ function Chat() {
 - Chunks are batched (every 10 chunks) and flushed to SQLite for performance
 - When a client sends `CF_AGENT_STREAM_RESUME_REQUEST`, the server checks for active streams and responds with `CF_AGENT_STREAM_RESUMING`
 - Stale streams (older than 5 minutes) are cleaned up on restore
-- Stream buffers are garbage collected from a scheduled alarm: completed or errored streams are retained for 10 minutes (a brief reconnect-and-replay grace; the assistant message itself is persisted separately), and abandoned in-flight streams are retained for 1 hour after their last chunk before being reclaimed
+- Stream buffers are deleted in the same transaction that persists the assistant message (the cutover), so a finished turn leaves nothing behind and no cleanup alarm is armed. A buffer a crash left behind is reclaimed when the next stream starts: finished streams immediately, abandoned in-flight streams after 1 hour without a chunk (recovery has until then to rebuild the message from it)
 
 ### Client-side (`useAgentChat`)
 

package/docs/routing.md

@@ -601,6 +601,94 @@ Each agent is accessed via its own path:
 
 ---
 
+## Routing to independent Agents
+
+A hub Agent often owns an open-ended set of independent peers: one Durable Object per chat, document, or session for a user. `RoutedAgents` from `agents/routing` codifies that topology as a Lifecycle capability. The hub keeps a durable catalog of public IDs mapped to opaque physical names, and forwards requests under one route segment to the selected Agent:
+
+```typescript
+import { Agent, callable, routeAgentRequest } from "agents";
+import { RoutedAgents } from "agents/routing";
+
+export class ChatAgent extends Agent<Env> {
+  // An ordinary top-level Agent: its own storage, alarms, and placement.
+}
+
+export class UserAgent extends Agent<Env> {
+  readonly chats = new RoutedAgents<ChatAgent, { title: string }>({
+    namespace: this.env.ChatAgent,
+    route: "chats"
+  });
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.lifecycle.use(this.chats);
+  }
+
+  @callable()
+  createChat(title: string) {
+    return this.chats.create({ metadata: { title } });
+  }
+
+  @callable()
+  listChats() {
+    return this.chats.list();
+  }
+
+  @callable()
+  deleteChat(id: string) {
+    return this.chats.delete(id);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Routes both /agents/user-agent/{id} and the forwarded
+    // /agents/user-agent/{id}/chats/{id}/... paths — RoutedAgents claims
+    // the latter from inside UserAgent once the request reaches it.
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+The client keeps one connection to the hub and one to the active chat, both addressed through the hub:
+
+```
+/agents/user-agent/alice                    -> UserAgent "alice"
+/agents/user-agent/alice/chats/{id}         -> the ChatAgent behind that entry
+/agents/user-agent/alice/chats/{id}/...     -> same ChatAgent, suffix preserved
+```
+
+```tsx
+const user = useAgent({ agent: "UserAgent", name: "alice" });
+const chat = useAgent({
+  agent: "ChatAgent",
+  basePath: `agents/user-agent/alice/chats/${encodeURIComponent(chatId)}`
+});
+```
+
+What the capability guarantees:
+
+- `create()`, `list()`, and `setMetadata()` touch only the hub's SQLite. No target wakes.
+- `list()` orders most-recently-updated first, ties broken by write order rather than by the random entry ID. Each write scans the route's own entries to derive that order — an intentional trade for a route sized like one owner's own catalog, not a route meant to hold thousands of entries.
+- `get(id)` returns an initialized, typed stub for RPC, or `null` for an unknown or deleted ID.
+- A WebSocket upgrade is answered by the target, which then owns the socket. Chat frames never wake the hub. This is the same two-socket shape as connecting to the chat directly, but the hub stays the authority that resolves an ID, so it can gate, migrate, or redirect entries later.
+- `delete(id)` hides the entry first, condemns the target, then removes the row. The target wipes its own storage on its next wake, moments later, and the condemned marker survives interruption. A failed call leaves a hidden row, and calling `delete` again retries.
+- Physical names are random UUIDs that never leave the hub. Clients only ever see entry IDs.
+- `namespace` is any `DurableObjectNamespace`, including a binding to a class exported by another Worker via `script_name`, so the hub and its targets can be deployed and scaled independently.
+- Destroying the hub retries condemning every remaining entry before its own storage is wiped, but this is best-effort: the platform wipes the hub's storage right after disposal regardless of outcome, so a target that is still unreachable after retries is orphaned, with no catalog row left to retry from later.
+
+The catalog stores existence, ownership, and application metadata. Conversation data stays in the target, and a target that needs its hub calls back with `getAgentByName(this.env.UserAgent, ownerName)`. When to prefer this over facets is covered in [Dynamic agents](./sub-agents.md#when-to-use-dynamic-agents).
+
+Two sharp edges to design around:
+
+- **Pick a route that can't collide.** Forwarding matches every occurrence of the route segment anywhere in the path, so if the hub's own name, class, or another one of its own routes is also literally `"chats"`, a coincidental match with no active entry behind it returns `404` instead of reaching the hub's own handler for that path.
+- **A routed suffix can't address a target's own dynamic agents.** `Agent.fetch()` resolves a `/sub/{class}/{name}` marker against the _hub's_ exported classes before this capability's request handling ever runs, so `/chats/{id}/sub/{class}/{name}` is served as a facet of the hub, not forwarded to the chat. Reach a target's dynamic agents through a direct connection to that target instead of through the hub's route.
+
+---
+
 ## Routing with Authentication
 
 Check authentication before routing to agents:
@@ -737,6 +825,23 @@ Get an agent instance by name for server-side RPC or request forwarding.
 
 **Returns:** `Promise<DurableObjectStub<T>>` - Typed stub for calling agent methods or forwarding requests
 
+### `new RoutedAgents(options)` (from `agents/routing`)
+
+A Lifecycle capability installed on a hub Agent with `this.lifecycle.use(...)`. See [Routing to independent Agents](#routing-to-independent-agents).
+
+| Parameter           | Type                        | Description                                      |
+| ------------------- | --------------------------- | ------------------------------------------------ |
+| `options.namespace` | `DurableObjectNamespace<T>` | Target binding the entries are created in        |
+| `options.route`     | `string`                    | One URL-safe path segment this capability claims |
+
+| Method                      | Returns                                              | Description                                           |
+| --------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| `create(options?)`          | `Promise<RoutedAgentEntry<Metadata>>`                | Create an entry without waking the target             |
+| `get(id)`                   | `Promise<DurableObjectStub<T> \| null>`              | Resolve an active entry to an initialized stub        |
+| `list()`                    | `Promise<ReadonlyArray<RoutedAgentEntry<Metadata>>>` | Active entries, most recently updated first           |
+| `setMetadata(id, metadata)` | `Promise<boolean>`                                   | Replace an active entry's metadata                    |
+| `delete(id)`                | `Promise<boolean>`                                   | Hide the entry, condemn the target, then drop the row |
+
 ### `useAgent(options)` / `AgentClient` Options
 
 Client connection options: