agents 0.23.0 → 0.25.0

package/docs/queue.md

@@ -1,218 +1,157 @@
-# Queue System
+# Queue
 
-The Agents SDK provides a built-in queue system that allows you to schedule tasks for asynchronous execution. This is particularly useful for background processing, delayed operations, and managing workloads that don't need immediate execution.
+Durable background work for an Agent or any Lifecycle Object. A queued item
+persists a callback name and a payload, runs from the Durable Object's alarm
+loop one item at a time in push order, retries when the callback throws, and
+survives the object leaving memory.
 
-## Overview
+## Queue Lifecycle capability
 
-The queue system is built into the base `Agent` class. Tasks are stored in a SQLite table and processed automatically in FIFO (First In, First Out) order.
+> **Experimental.** The `Queue` capability and the `agents/lifecycle` surface
+> it builds on may change between releases. Agent's established queue methods
+> (`this.queue()` and friends) are stable.
 
-## QueueItem Type
+`Queue` is a reusable Lifecycle capability. A plain Lifecycle Object can
+install it without extending `Agent`:
 
 ```typescript
-export type QueueItem<T = string> = {
-  id: string; // Unique identifier for the queued task
-  payload: T; // Data to pass to the callback function
-  callback: keyof Agent<unknown>; // Name of the method to call
-  created_at: number; // Timestamp when the task was created
-  retry?: RetryOptions; // Retry options (if configured)
-};
-```
-
-## Core Methods
-
-### queue()
-
-Adds a task to the queue for future execution.
-
-```typescript
-async queue<T = unknown>(
-  callback: keyof this,
-  payload: T,
-  options?: { retry?: RetryOptions }
-): Promise<string>
-```
-
-**Parameters:**
-
-- `callback`: The name of the method to call when processing the task
-- `payload`: Data to pass to the callback method
-- `options.retry`: Optional retry configuration. See [Retries](./retries.md) for details.
-
-**Returns:** The unique ID of the queued task
-
-**Example:**
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { Queue, type QueueItem } from "agents/queue";
 
-```typescript
-class MyAgent extends Agent {
-  async processEmail(data: { email: string; subject: string }) {
-    // Process the email
-    console.log(`Processing email: ${data.subject}`);
-  }
+export class UploadObject extends DurableObject<Env> {
+  readonly queue = new Queue({
+    callbacks: {
+      processUpload: (
+        payload: { fileName: string },
+        item: QueueItem<{ fileName: string }>
+      ) => {
+        console.log(item.id, payload.fileName);
+      }
+    }
+  });
 
-  async onMessage(message: string) {
-    // Queue an email processing task
-    const taskId = await this.queue("processEmail", {
-      email: "user@example.com",
-      subject: "Welcome!"
-    });
+  readonly lifecycle = Lifecycle.install(this).use(this.queue);
 
-    console.log(`Queued task with ID: ${taskId}`);
+  async enqueueUpload(fileName: string): Promise<string> {
+    const item = await this.queue.push("processUpload", { fileName });
+    return item.id;
   }
 }
 ```
 
-### dequeue()
-
-Removes a specific task from the queue by ID.
-
-```typescript
-dequeue(id: string): void
-```
-
-**Parameters:**
-
-- `id`: The ID of the task to remove
-
-**Example:**
-
-```typescript
-// Remove a specific task
-agent.dequeue("abc123def");
-```
-
-### dequeueAll()
-
-Removes all tasks from the queue.
-
-```typescript
-dequeueAll(): void
-```
-
-**Example:**
-
-```typescript
-// Clear the entire queue
-agent.dequeueAll();
-```
-
-### dequeueAllByCallback()
-
-Removes all tasks that match a specific callback method.
-
-```typescript
-dequeueAllByCallback(callback: string): void
-```
-
-**Parameters:**
-
-- `callback`: Name of the callback method
-
-**Example:**
-
-```typescript
-// Remove all email processing tasks
-agent.dequeueAllByCallback("processEmail");
-```
-
-### getQueue()
-
-Retrieves a specific queued task by ID.
-
-```typescript
-getQueue(id: string): QueueItem<string> | undefined
-```
-
-**Parameters:**
+Queue owns no storage of its own. Each item is one job in the Lifecycle job
+queue, due immediately; Lifecycle owns the physical Durable Object alarm, the
+alarm event loop, retry policy, the deadman pre-arm, and the memory-limit
+circuit breaker. See [Durable Object lifecycle](./lifecycle.md#the-job-queue).
 
-- `id`: The ID of the task to retrieve
+Queue's API is small: callbacks are registered by name in the constructor,
+`push()` creates items typed against that registration, and `get()`,
+`list()`, `cancel()`, and `cancelAll()` manage them. All of these are
+asynchronous and work inside routed sub-agents.
 
-**Returns:** The QueueItem with parsed payload or undefined if not found
+Queue Lifecycle hooks run without ambient host context. Registered callbacks
+are user code, so they run inside the host invocation context with the
+Lifecycle Object available through `getCurrentAgent()`.
 
-**Note:** The payload is automatically parsed from JSON before being returned
-
-**Example:**
-
-```typescript
-const task = agent.getQueue("abc123def");
-if (task) {
-  console.log(`Task callback: ${task.callback}`);
-  console.log(`Task payload:`, task.payload);
-}
-```
+### `new Queue(options?)`
 
-### getQueues()
+| Option      | Description                                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `callbacks` | Named callbacks `(payload, item) => unknown`. Register in a field initializer so names re-bind on every wake. |
+| `retry`     | Default retry policy: `{ maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 3000 }`. See [Retries](./retries.md).  |
+| `onError`   | Observes an item's terminal failure after its attempts are exhausted. Runs without host context.              |
 
-Retrieves all queued tasks that match a specific key-value pair in their payload.
+### `push(callback, payload?, options?)`
 
-```typescript
-getQueues(key: string, value: string): QueueItem<string>[]
-```
+Queues one item and returns the `QueueItem`. The item is durable before the
+returned promise resolves, and it runs from the next alarm, so the caller
+never waits for the callback.
 
-**Parameters:**
+- `options.retry` overrides the Queue's retry policy for this item.
+- `options.id` sets a stable id. A push with an existing id replaces that
+  item in place, keeping its position in the queue (and superseding a
+  dispatch of it still in flight); use it for idempotent enqueues keyed by
+  your own identifier.
 
-- `key`: The key to filter by in the payload
-- `value`: The value to match
+Once the Lifecycle has started, the item row is written synchronously before
+`push()` returns its promise, so a push made in the same synchronous block as
+your own SQL writes commits atomically with them.
 
-**Returns:** Array of matching QueueItem objects
+### `get(id)`, `list(criteria?)`, `cancel(id)`, `cancelAll(callback?)`
 
-**Note:** This method fetches all queue items and filters them in memory by parsing each payload and checking if the specified key matches the value
+`list()` returns pending items in push order; `{ callback }` filters by
+callback name. `cancel()` returns whether an item was removed; `cancelAll()`
+returns how many were.
 
-**Example:**
+### QueueItem
 
 ```typescript
-// Find all tasks for a specific user
-const userTasks = await agent.getQueues("userId", "12345");
+type QueueItem<T = unknown> = {
+  id: string; // Unique identifier
+  callback: string; // Callback name
+  payload: T; // Data passed to the callback
+  createdAt: number; // Unix timestamp in seconds
+  retry?: RetryOptions; // Resolved retry policy
+};
 ```
 
-## How Queue Processing Works
-
-1. **Validation**: When calling `queue()`, the method validates that the callback exists as a function on the agent
-2. **Automatic Processing**: After queuing, the system automatically attempts to flush the queue
-3. **FIFO Order**: Tasks are processed in the order they were created (`created_at` timestamp)
-4. **Context Preservation**: Each queued task runs with the same agent context (connection, request, email)
-5. **Automatic Retries**: If a callback fails, it is retried with exponential backoff (configurable per task)
-6. **Automatic Dequeue**: Tasks are removed from the queue after successful execution or after all retry attempts are exhausted
-7. **Error Handling**: If a callback method does not exist at execution time, an error is logged and the task is skipped
-8. **Persistence**: Tasks are stored in the `cf_agents_queues` table and survive agent restarts
+## Using the queue through Agent
 
-## Queue Callback Methods
-
-When defining callback methods for queued tasks, they must follow this signature:
-
-```typescript
-async callbackMethod(payload: unknown, queueItem: QueueItem<string>): Promise<void>
-```
-
-**Example:**
+`Agent` installs a `Queue` and resolves callback names to its own methods, so
+`this.queue("methodName", payload)` keeps working with no registration:
 
 ```typescript
 class MyAgent extends Agent {
-  async sendNotification(
-    payload: { userId: string; message: string },
-    queueItem: QueueItem<string>
+  async processEmail(
+    payload: { email: string; subject: string },
+    item: QueueItem<{ email: string; subject: string }>
   ) {
-    console.log(`Processing task ${queueItem.id}`);
-    console.log(
-      `Sending notification to user ${payload.userId}: ${payload.message}`
-    );
-
-    // Your notification logic here
-    await this.notificationService.send(payload.userId, payload.message);
+    console.log(`Processing ${item.id}: ${payload.subject}`);
   }
 
-  async onUserSignup(userData: any) {
-    // Queue a welcome notification
-    await this.queue("sendNotification", {
-      userId: userData.id,
-      message: "Welcome to our platform!"
+  async onMessage(message: string) {
+    const id = await this.queue("processEmail", {
+      email: "user@example.com",
+      subject: "Welcome!"
     });
+    console.log(`Queued task ${id}`);
   }
 }
 ```
 
-## Use Cases
-
-### Background Processing
+| Method                               | Description                                                         |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| `queue(callback, payload, options?)` | Queue a method by name. Returns the item id. Accepts `retry`, `id`. |
+| `dequeue(id)`                        | Remove a pending item. Resolves to whether one was removed.         |
+| `dequeueAll()`                       | Remove every pending item. Resolves to the count.                   |
+| `dequeueAllByCallback(callback)`     | Remove every pending item for one callback. Resolves to the count.  |
+| `getQueue(id)`                       | Read a pending item.                                                |
+| `getQueues(key, value)`              | Pending items whose payload has `key` equal to `value`.             |
+
+## How queue processing works
+
+1. **Validation**: `queue()` checks the callback exists and validates any
+   retry options. Invalid input throws immediately.
+2. **Durable first**: the item is a row in the `cf_agents_jobs` job queue
+   before `queue()` resolves. Items created before this capability existed
+   are migrated out of the old `cf_agents_queues` table on the next start.
+3. **Alarm-driven**: every push re-arms the Durable Object alarm. The
+   Lifecycle event loop runs due items in push order, awaiting each callback
+   before starting the next, in a fresh invocation rather than the request
+   that queued them.
+4. **Retries**: a throwing callback is retried with exponential backoff per
+   its retry policy, emitting `queue:retry` on each extra attempt.
+5. **Terminal failure**: after the last attempt the item is dropped, a
+   `queue:error` event is emitted, and Agent's `onError` (or the Queue's
+   `onError` option) observes the error.
+6. **Recovery**: an isolate that dies mid-callback wakes again on the
+   Lifecycle deadman alarm and resumes the queue, so callbacks should be
+   idempotent.
+
+## Use cases
+
+Queue work that must not block the current request or WebSocket message:
 
 ```typescript
 class DataProcessor extends Agent {
@@ -221,52 +160,31 @@ class DataProcessor extends Agent {
     await this.notifyUser(data.userId, results);
   }
 
-  async onDataUpload(uploadData: any) {
-    // Queue the processing instead of doing it synchronously
+  async onDataUpload(uploadData: { id: string; userId: string }) {
     await this.queue("processLargeDataset", {
       datasetId: uploadData.id,
       userId: uploadData.userId
     });
-
     return { message: "Data upload received, processing started" };
   }
 }
 ```
 
-### Delayed Operations
-
-```typescript
-class ReminderAgent extends Agent {
-  async sendReminder(data: { userId: string; message: string }) {
-    await this.emailService.send(data.userId, data.message);
-  }
-
-  async scheduleReminder(userId: string, message: string, delayMs: number) {
-    // Note: For true delayed execution, combine with the scheduling system
-    // This example shows queueing for later processing
-    await this.queue("sendReminder", { userId, message });
-  }
-}
-```
-
-### Batch Operations
+Split large requests into batches that run one after another:
 
 ```typescript
 class BatchProcessor extends Agent {
-  async processBatch(data: { items: any[]; batchId: string }) {
+  async processBatch(data: { items: unknown[]; batchId: string }) {
     for (const item of data.items) {
       await this.processItem(item);
     }
-    console.log(`Completed batch ${data.batchId}`);
   }
 
-  async onLargeRequest(items: any[]) {
-    // Split large requests into smaller batches
+  async onLargeRequest(items: unknown[]) {
     const batchSize = 10;
     for (let i = 0; i < items.length; i += batchSize) {
-      const batch = items.slice(i, i + batchSize);
       await this.queue("processBatch", {
-        items: batch,
+        items: items.slice(i, i + batchSize),
         batchId: `batch-${i / batchSize + 1}`
       });
     }
@@ -274,56 +192,32 @@ class BatchProcessor extends Agent {
 }
 ```
 
-## Best Practices
+For work that should run at a specific time or on a schedule, use
+[Scheduling](./scheduling.md) instead. Both ride the same Lifecycle job queue.
 
-1. **Keep Payloads Small**: Payloads are JSON-serialized and stored in the database
-2. **Idempotent Operations**: Design callback methods to be safe to retry
-3. **Error Handling**: Include proper error handling in callback methods
-4. **Monitoring**: Use logging to track queue processing
-5. **Cleanup**: Regularly clean up completed or failed tasks if needed
+## Best practices
 
-## Error Handling and Retries
+1. **Keep payloads small**: payloads are JSON-serialized into the job row.
+2. **Idempotent callbacks**: an item can run again after an isolate reset.
+3. **Bounded callbacks**: the event loop awaits each callback, so a long one
+   delays every other job on the object. Detach unbounded work and return.
+4. **Stable ids for dedupe**: pass `id` when the same logical task may be
+   queued more than once.
 
-Queued tasks are automatically retried on failure with exponential backoff. The default is 3 attempts. You can customize this per task:
+## Error handling and retries
 
 ```typescript
-// Retry up to 5 times with custom backoff
 await this.queue("reliableTask", payload, {
   retry: { maxAttempts: 5, baseDelayMs: 500 }
 });
 ```
 
-If you need custom error handling in the callback:
-
-```typescript
-class RobustAgent extends Agent {
-  async reliableTask(payload: { data: string }, queueItem: QueueItem<string>) {
-    try {
-      await this.doSomethingRisky(payload);
-    } catch (error) {
-      console.error(`Task ${queueItem.id} failed:`, error);
-      // The retry system will catch this error and retry automatically
-      throw error;
-    }
-  }
-}
-```
-
-See [Retries](./retries.md) for full documentation on retry options and patterns.
-
-## Integration with Other Features
-
-The queue system works seamlessly with other Agent SDK features:
-
-- **State Management**: Access agent state within queued callbacks
-- **Scheduling**: Combine with `schedule()` for time-based queue processing
-- **Retries**: Built-in retry with exponential backoff. See [Retries](./retries.md).
-- **Context**: Queued tasks maintain the original request context
-- **Database**: Uses the same database as other agent data
+See [Retries](./retries.md) for full documentation on retry options, and
+[Observability](./observability.md) for the `queue:create`, `queue:retry`,
+and `queue:error` events.
 
 ## Limitations
 
-- Tasks are processed sequentially, not in parallel
-- No priority system (FIFO only)
-- Queue processing happens during agent execution, not as separate background jobs
-- Failed tasks are dequeued after all retry attempts are exhausted (no dead-letter queue)
+- Items run sequentially, not in parallel.
+- No priority system (FIFO only).
+- Failed items are dropped after all retry attempts (no dead-letter queue).

package/docs/resumable-streaming.md

@@ -84,6 +84,8 @@ function Chat() {
 
 Replayed chunks include `replay: true` to distinguish them from live chunks. The client uses this to batch-apply all replayed chunks before rendering, which prevents intermediate states (like reasoning "Thinking..." indicators) from flashing briefly during replay. During a live stream, chunks arrive gradually and React renders each intermediate state naturally.
 
+Live and replayed chunks also carry a `seq` field: the chunk's position in the stream, starting at `0`. A continuation stream (for example, a tool continuation) appends to an assistant message that the client already holds, so replaying it from the start would apply the same text twice. The client remembers the highest `seq` it has applied for each request and skips replayed continuation chunks at or below it. Replays of non-continuation streams rebuild the message from the first chunk and are not filtered.
+
 ## Durable client cleanup
 
 `resume: true` controls whether the client tries to reconnect to an active stream. `cancelOnClientAbort: false` is the default cancellation behavior: generic client stream abort/cleanup is local-only, while explicit `stop()` still cancels the server turn.

package/docs/retries.md

@@ -188,7 +188,7 @@ await this.queue("processWebhook", webhookData, {
 });
 ```
 
-If the callback throws, it is retried before the task is dequeued. After all attempts are exhausted, the task is dequeued and the error is logged.
+If the callback throws, it is retried before the item is removed. After all attempts are exhausted, the item is dropped, a `queue:error` event is emitted, and the error is logged.
 
 ## Validation
 

package/docs/routing.md

@@ -777,9 +777,9 @@ The error message lists available agents. Check:
 2. Check that `routeAgentRequest()` is called before your 404 handler
 3. Ensure the response from `routeAgentRequest()` is returned (not just called)
 
-### WebSocket won't connect
+### WebSocket will not connect
 
-1. Don't modify the response from `routeAgentRequest()` for WebSocket upgrades
+1. Do not modify the response from `routeAgentRequest()` for WebSocket upgrades
 2. Ensure CORS is enabled if connecting from a different origin
 3. Check browser dev tools for the actual error
 
@@ -798,16 +798,16 @@ The error message lists available agents. Check:
 
 Routes a request to the appropriate agent.
 
-| Parameter                 | Type                      | Description                                         |
-| ------------------------- | ------------------------- | --------------------------------------------------- |
-| `request`                 | `Request`                 | The incoming request                                |
-| `env`                     | `Env`                     | Environment with agent bindings                     |
-| `options.cors`            | `boolean \| HeadersInit`  | Enable CORS headers                                 |
-| `options.props`           | `Record<string, unknown>` | Props passed to whichever agent handles the request |
-| `options.locationHint`    | `string`                  | Preferred location for agent instances              |
-| `options.jurisdiction`    | `string`                  | Data jurisdiction for agent instances               |
-| `options.onBeforeConnect` | `Function`                | Callback before WebSocket connections               |
-| `options.onBeforeRequest` | `Function`                | Callback before HTTP requests                       |
+| Parameter                 | Type                     | Description                                                                          |
+| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
+| `request`                 | `Request`                | The incoming request                                                                 |
+| `env`                     | `Env`                    | Environment with agent bindings                                                      |
+| `options.cors`            | `boolean \| HeadersInit` | Enable CORS headers                                                                  |
+| `options.props`           | `object`                 | Props passed to whichever agent handles the request. Sent as JSON, so use plain data |
+| `options.locationHint`    | `string`                 | Preferred location for agent instances                                               |
+| `options.jurisdiction`    | `string`                 | Data jurisdiction for agent instances                                                |
+| `options.onBeforeConnect` | `Function`               | Callback before WebSocket connections                                                |
+| `options.onBeforeRequest` | `Function`               | Callback before HTTP requests                                                        |
 
 **Returns:** `Promise<Response \| undefined>` - Response if matched, undefined if no agent route
 
@@ -821,7 +821,7 @@ Get an agent instance by name for server-side RPC or request forwarding.
 | `name`                 | `string`                    | Instance name                           |
 | `options.locationHint` | `string`                    | Preferred location                      |
 | `options.jurisdiction` | `string`                    | Data jurisdiction                       |
-| `options.props`        | `Record<string, unknown>`   | Initialization properties for `onStart` |
+| `options.props`        | `object`                    | Initialization properties for `onStart` |
 
 **Returns:** `Promise<DurableObjectStub<T>>` - Typed stub for calling agent methods or forwarding requests
 

package/docs/sessions.md

@@ -242,7 +242,23 @@ await session.addCompaction(summary, fromMessageId, toMessageId);
 
 Sessions stamps each message with a token estimate when the row is written. `compactAfter()` gates on that O(1) aggregate and never reads the transcript to decide whether to compact. Auto-compaction failures are non-fatal: they log, emit `session:error`, and leave the transcript alone.
 
-To trim a transcript before handing it to a model, `truncateOlderMessages` is exported from [`agents/chat`](./chat-agents.md), not from `agents/sessions`.
+To trim a transcript before handing it to a model, `truncateOlderMessages` is exported from [`agents/chat`](./chat-agents.md), not from `agents/sessions`. If your tools define `toModelOutput`, a truncated tool output may no longer match the tool's output schema. In that case, pass `toolOutputs: false` to `truncateOlderMessages` and call `truncateOlderToolResults` on the result of `convertToModelMessages`, which truncates what the model reads after `toModelOutput` has run. Provider-executed tool outputs are never truncated.
+
+With the default `keepRecent`, the truncation cutoff moves forward by one message whenever a message is added, so every turn rewrites a message near the end of the prompt and invalidates the provider's prompt cache from that point. To keep the prefix stable, move the cutoff in steps and pass the same `keepRecent` to both functions:
+
+```ts
+const step = 8;
+const keepRecent = history.length <= 4 ? 4 : 4 + ((history.length - 4) % step);
+const truncated = truncateOlderMessages(history, {
+  keepRecent,
+  toolOutputs: false
+});
+const modelMessages = truncateOlderToolResults(
+  await convertToModelMessages(truncated, { tools }),
+  truncated,
+  { keepRecent }
+);
+```
 
 ## Large messages
 
@@ -345,6 +361,25 @@ const unsubscribe = sessions.subscribe(async (event) => {
 
 `import` fires once per `importMessage()` and carries the row; it is deliberately not an `append`, so a projection does not patch itself per imported row during a migration — it marks itself stale and re-derives once. `compaction` fires when an overlay is stored directly through `addCompaction()`; `compact()` reports its own overlay as `compact`.
 
+A host that keeps an in-memory transcript does not need to write that reduction itself. `session.mirror()` subscribes for one session and patches an array in place: an append or update replaces the entry with the same id (or pushes a new row), a delete filters, and a clear empties it:
+
+```ts
+const stop = sessions.session("").mirror<UIMessage>({
+  get: () => this.messages,
+  set: (messages) => {
+    this.messages = messages;
+  },
+  transform: (message) => toCachedMessage(message),
+  intercept: async (event) => {
+    if (event.type !== "compact") return false;
+    this.messages = await reloadFromStorage();
+    return true;
+  }
+});
+```
+
+`get()` is read on every event, so reassigning the array is safe. `intercept` handles an event instead of the default reduction. Use it for changes an in-place patch cannot express, such as a branch append or a compaction. `onApplied` runs after an append or update was written, with the entry it replaced.
+
 This is a local cache-coherence feed, not a cross-object event log. Capability diagnostics are also emitted through Lifecycle observability.
 
 ## Errors

package/docs/state.md

@@ -301,6 +301,7 @@ const client = new AgentClient({
   host: "your-worker.workers.dev"
 });
 
+// Resolves once the agent's stored state has arrived, if it has any
 await client.ready;
 
 // Read state directly

package/docs/sub-agents.md

@@ -4,7 +4,7 @@ Dynamic agents are child Durable Objects **colocated under and supervised by** a
 
 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).
+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/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing).
 
 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).
@@ -246,6 +246,15 @@ The hook receives the **original** request with its URL intact — including the
 
 WebSocket upgrade requests flow through this hook the same way as plain HTTP. If you return a mutated `Request`, keep the original `Upgrade: websocket` and `Sec-WebSocket-*` headers — cloning via `new Headers(req.headers)` and only adding or replacing entries is the safest recipe.
 
+When the hook returns a `Response` for a WebSocket upgrade, the framework accepts the socket and immediately closes it, because browsers hide the status of a failed handshake and reconnecting clients would retry it forever. The close code carries the status:
+
+| Returned status | Close code      | Client behavior                                                       |
+| --------------- | --------------- | --------------------------------------------------------------------- |
+| `4xx`           | `4000 + status` | Terminal: `useAgent` and `AgentClient` stop and set `connectionError` |
+| anything else   | `1011`          | Retried with backoff                                                  |
+
+The close reason is `Sub-agent connection rejected (<status>)`, so a `404` arrives as code `4404`. At the first `/sub/` hop, a returned `Response` that already carries a `webSocket` is passed through unchanged; deeper hops always close with the mapped code.
+
 ### `this.parentPath` and `this.selfPath`
 
 Root-first ancestor chains. `parentPath` covers strict ancestors; `selfPath` includes the current agent.
@@ -471,13 +480,13 @@ await user.recordChatActivity(chatId, { title, lastMessage, seq });
 
 `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).
 
-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).
+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/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing) 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).
 
 ## Examples
 
 - [`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).
+- [`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/routing`](https://github.com/cloudflare/agents/tree/main/examples/next/routing) — see [When to use dynamic agents](#when-to-use-dynamic-agents).
 
 ## Related