agents 0.22.0 → 0.24.0

package/docs/chat-agents.md

@@ -520,13 +520,9 @@ their cleanup and skipped continuations return immediately.
 
 #### Overriding the clear handler
 
-The SDK's built-in `CF_AGENT_CHAT_CLEAR` handler calls `resetTurnState()`
-automatically. If your `onMessage` override intercepts `CF_AGENT_CHAT_CLEAR`
-and returns before the SDK sees the message — for example, to scope the delete
-to a specific workflow — the built-in handler never runs. The active stream
-continues and queued continuations persist into the newly-cleared conversation.
+The SDK's built-in `CF_AGENT_CHAT_CLEAR` handler calls `resetTurnState()` and clears the default Sessions handle. If an `onMessage` override intercepts this frame and returns early, the built-in handler cannot stop the active stream or clear history.
 
-Call `this.resetTurnState()` before performing your scoped delete:
+Perform authorization or logging, then pass the frame to the original handler:
 
 ```typescript
 import { MessageType } from "@cloudflare/ai-chat/types";
@@ -536,19 +532,16 @@ this.onMessage = async (connection, message) => {
   if (typeof message === "string") {
     const data = JSON.parse(message);
     if (data.type === MessageType.CF_AGENT_CHAT_CLEAR) {
-      this.resetTurnState();
-      this.sql`
-        DELETE FROM cf_ai_chat_agent_messages
-        WHERE workflow_id = ${this.workflowId}
-      `;
-      await this.saveMessages([]);
-      return;
+      await this.authorizeClear(connection);
+      console.log("clearing conversation");
     }
   }
   return _onMessage(connection, message);
 };
 ```
 
+Do not write directly to Sessions tables. Use `this.sessions.session().clearMessages()` when implementing a separate server-side history operation outside the chat protocol.
+
 ### Lifecycle Hooks
 
 Override `onConnect` and `onClose` to add custom logic. Stream resumption and message sync are handled for you automatically — you do not need to call `super`:

package/docs/client-sdk.md

@@ -120,6 +120,35 @@ useAgent({
 });
 ```
 
+### Transport
+
+`useAgent` speaks the Agent protocol over one of two wires. The default,
+`"cf-websocket"`, is a hibernating WebSocket managed by PartySocket. The
+experimental `"capnweb"` transport carries protocol frames through a single
+[Cap'n Web](https://github.com/cloudflare/capnweb) RPC session whose root
+also serves the host's callables natively:
+
+```typescript
+useAgent({
+  agent: "ChatAgent",
+  name: "room-123",
+  transport: "capnweb" // default: "cf-websocket"
+});
+```
+
+Identity, state sync, reconnection with backoff, and terminal close codes are
+identical on both wires; PartySocket still owns the connection and the
+transport only swaps the socket class it instantiates. `call()` and `stub`
+differ by design. On `cf-websocket` they send JSON `rpc` frames. On `capnweb`
+they invoke the host's `callables` natively on the Cap'n Web session root: a
+method that returns an `RpcTarget` hands you a live stub you can keep
+calling, a `ReadableStream` result streams, and chained calls pipeline.
+`@callable()` decorators on an `Agent` are a JSON-wire feature and are not
+available on `capnweb` unless the Agent also passes a `callables` target.
+The trade-off is that a Cap'n Web connection does not hibernate: the Durable
+Object stays in memory while one is open. `AgentClient` accepts the same
+`transport` option.
+
 ### Async Query Parameters
 
 For authentication tokens or other async data, pass a function that returns a Promise:
@@ -351,6 +380,7 @@ type UseAgentOptions<State> = {
   name?: string; // Instance name (default: "default")
   host?: string; // Custom host
   path?: string; // Custom path prefix
+  transport?: "cf-websocket" | "capnweb"; // Wire (default: "cf-websocket")
 
   // Query parameters
   query?:

package/docs/context.md

@@ -0,0 +1,131 @@
+# Context
+
+> **Experimental.** Everything exported from `agents/context` may change between releases while the API stabilizes.
+
+`agents/context` assembles an agent's system prompt from labelled blocks. A block is a piece of prompt text with a storage provider behind it. What the provider can do decides how the block behaves and which tools the model gets for it.
+
+Context is prompt assembly. It is not conversation storage. It composes with [`agents/sessions`](./sessions.md) rather than living inside it, so an agent can have a prompt without a transcript, or a transcript without a prompt.
+
+## Blocks
+
+```ts
+import { ContextBlocks } from "agents/context";
+
+const context = new ContextBlocks([
+  {
+    label: "soul",
+    provider: { get: async () => "You are a helpful assistant." }
+  },
+  {
+    label: "memory",
+    description: "Facts learned about the user",
+    maxTokens: 1_100,
+    provider: memoryProvider
+  }
+]);
+
+const system = await context.freezeSystemPrompt();
+const tools = await context.tools();
+```
+
+Each block renders as a labelled section of the system prompt. The header carries the label, the description, a token-usage percentage when `maxTokens` is set, and a capability marker (`[readonly]`, `[writable]`, `[loadable]`, or `[searchable]`).
+
+An empty read-only block is skipped. Writable, loadable, and searchable blocks always render so the model knows which tools can address them.
+
+## Providers
+
+The provider decides the block's behavior. The checks are structural, not nominal.
+
+| Provider shape          | Block behavior                               |
+| ----------------------- | -------------------------------------------- |
+| `get()`                 | Read-only text in the prompt                 |
+| `get()` + `set()`       | Writable through the `set_context` tool      |
+| `get()` + `search(key)` | Summary in the prompt, `search_context` tool |
+
+`get()` returns the block's current content, or `null` when it has none. An optional `init(label)` receives the block label before first use, so one provider class can serve several labels.
+
+`ContextBlocks` also accepts a `defaultProvider` factory. A block declared without a `provider` is then wired to whatever that factory returns for its label, which is how a host offers durable writable blocks by label alone.
+
+### Durable SQLite blocks
+
+`AgentContextProvider` stores one block per row in `cf_agents_context_blocks` in the Durable Object's own SQLite database:
+
+```ts
+import { AgentContextProvider } from "agents/context";
+
+const context = new ContextBlocks([
+  { label: "memory", provider: new AgentContextProvider(this, "memory") }
+]);
+```
+
+The constructor takes anything with a tagged-template `sql` method, which an `Agent` already has. The label argument is optional: `init()` fills it in from the block declaration.
+
+### Searchable blocks
+
+`AgentSearchProvider` backs a block with a Durable Object FTS5 table:
+
+```ts
+import { AgentSearchProvider } from "agents/context";
+
+const context = new ContextBlocks([
+  { label: "knowledge", provider: new AgentSearchProvider(this) }
+]);
+```
+
+`get()` renders a count of indexed entries rather than the entries themselves. `search(query)` returns up to 10 ranked matches through the `search_context` tool. `set(key, content)` replaces one keyed entry.
+
+The FTS5 table is the only store for these entries. A mirror row table would double the billed writes of every indexed entry to serve a count and a lookup the index already answers. Entries live in `cf_agents_search_fts`, namespaced by label, separate from the Sessions message index.
+
+## Frozen prompts
+
+`freezeSystemPrompt()` renders once and returns the same string on every later call, so the provider's prefix cache stays warm across turns. `setBlock()` writes to the provider immediately but deliberately does not change the frozen prompt; call `refreshSystemPrompt()` to re-render from current block state.
+
+Pass a `promptStore` (any writable provider) as the second constructor argument and the frozen prompt is persisted:
+
+```ts
+const context = new ContextBlocks(
+  configs,
+  new AgentContextProvider(this, "_system_prompt"),
+  (label) => new AgentContextProvider(this, label)
+);
+
+const system = await context.freezeSystemPrompt();
+```
+
+`freezeSystemPrompt()` returns the stored prompt when one exists, and otherwise loads providers, renders, and persists. So a cold wake reuses the exact prompt string the model already cached instead of re-rendering a subtly different one.
+
+`refreshSystemPrompt()` reloads every provider, re-renders, and overwrites the stored prompt.
+
+## Tools
+
+`tools()` returns an AI SDK `ToolSet` wired from what the blocks can do:
+
+- `set_context` when any block is writable
+- `search_context` when any block is backed by a search provider
+
+An agent with only read-only blocks gets no tools at all.
+
+## Think
+
+`Think` builds its `ContextBlocks` from `configureContext()` during startup:
+
+```ts
+import type { ContextConfig } from "agents/context";
+
+class MyAgent extends Think<Env> {
+  configureContext(): ContextConfig[] {
+    return [
+      { label: "soul", provider: { get: async () => "You are helpful." } },
+      { label: "memory", description: "Learned facts", maxTokens: 2_000 }
+    ];
+  }
+}
+```
+
+A block declared without a provider is auto-wired to durable per-agent SQLite. The frozen system prompt is always persisted, in `_system_prompt`, so there is nothing to opt into.
+
+The assembled blocks are available as `this.context` after `onStart()`.
+
+## Related
+
+- [Sessions](./sessions.md) - durable message trees, streamed history, compaction, and attachment offload

package/docs/index.md

@@ -11,13 +11,13 @@ Build stateful AI agents on Cloudflare Workers. Every agent is a Durable Object
 
 Pick the base class that matches what you are building. They share the same Durable Object foundation, so you can start small and move up without re-platforming.
 
-| You are building...                                            | Use                                                                                | Why                                                                                                                    |
-| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Stateful backend logic, real-time sync, custom protocols       | [`Agent`](./agent-class.md)                                                        | The core class: state, WebSockets, scheduling, SQL, and sub-agents. No opinions about chat or LLMs.                    |
-| A chat UI where you own the loop, the stream, and the response | [`AIChatAgent`](./chat-agents.md)                                                  | A thin chat-protocol adapter for `useAgentChat`. Bring your own agentic loop and custom streaming.                     |
-| A durable, general-purpose reasoning agent                     | [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md)      | Opinionated runtime: agentic loop, sessions, tools, memory, compaction, recovery, and multi-channel delivery built in. |
-| A voice agent (speech in, speech out)                          | [Voice mixins](https://github.com/cloudflare/agents/blob/main/docs/voice/index.md) | `withVoice` adds real-time STT/TTS, interruption and barge-in, and conversation persistence to an agent.               |
-| Durable multi-step processes (not chat)                        | [Workflows](./workflows.md)                                                        | Long-running, retryable step orchestration with Cloudflare Workflows.                                                  |
+| You are building...                                            | Use                                                                           | Why                                                                                                                    |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Stateful backend logic, real-time sync, custom protocols       | [`Agent`](./agent-class.md)                                                   | The core class: state, WebSockets, scheduling, SQL, and sub-agents. No opinions about chat or LLMs.                    |
+| A chat UI where you own the loop, the stream, and the response | [`AIChatAgent`](./chat-agents.md)                                             | A thin chat-protocol adapter for `useAgentChat`. Bring your own agentic loop and custom streaming.                     |
+| A durable, general-purpose reasoning agent                     | [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) | Opinionated runtime: agentic loop, sessions, tools, memory, compaction, recovery, and multi-channel delivery built in. |
+| A voice agent (speech in, speech out)                          | [Voice mixins](./voice.md)                                                    | `withVoice` adds real-time STT/TTS, interruption and barge-in, and conversation persistence to an agent.               |
+| Durable multi-step processes (not chat)                        | [Workflows](./workflows.md)                                                   | Long-running, retryable step orchestration with Cloudflare Workflows.                                                  |
 
 Not sure? Start with [`Agent`](./agent-class.md) for raw building blocks, or [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) if you want a chat or reasoning agent that already handles the hard parts.
 
@@ -40,8 +40,8 @@ The differentiator is not "we have durable state" — it is what happens when a
 ## Core Concepts
 
 - [State Management](./state.md) - Managing agent state with `setState()`, `initialState`, and `onStateChanged()`
-- [Routing](./routing.md) - How `routeAgentRequest()` and agent naming works
-- [Sub-agents](./sub-agents.md) - Parent/child DO composition via facets, nested routing, and direct child connections
+- [Routing](./routing.md) - How `routeAgentRequest()` and agent naming works, plus `RoutedAgents` for a hub that routes to many independent Agents
+- [Dynamic agents](./sub-agents.md) - Facet-backed child agents for code the parent supervises (dynamic/generated code, per-run tool agents, sandboxes) — not the recommended primitive for many independent peers like chats
 - [HTTP & WebSockets](./http-websockets.md) - Request handling and real-time connections
 - [Callable Methods](./callable-methods.md) - The `@callable` decorator and client-server method calls
 - [Readonly Connections](./readonly-connections.md) - Restricting which connections can modify state
@@ -57,13 +57,13 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Webhooks](./webhooks.md) - Receiving and sending webhook events
 - [Push Notifications](./push-notifications.md) - Browser push notifications via Web Push API and scheduled delivery
 - TODO: [SMS](./sms.md) - Text message integration (Twilio, etc.)
-- [Voice Agents](https://github.com/cloudflare/agents/blob/main/docs/voice/index.md) - Build voice agents with real-time speech-to-text, text-to-speech, and conversation persistence
+- [Voice Agents](./voice.md) - Build voice agents with real-time speech-to-text, text-to-speech, and conversation persistence
+- [Channels](./channels.md) - Send and receive messages through Slack, Telegram, email, browser voice, or custom adapters
 - [Chat SDK State](./chat-sdk.md) - Store Chat SDK subscriptions, locks, queues, and history in Agents sub-agents
-- TODO: [Messengers](./messengers.md) - Slack, Discord, Telegram, and other chat platforms
 
 ## Background Processing
 
-- [Queue](./queue.md) - Immediate background task execution
+- [Queue](./queue.md) - Durable background task execution
 - [Scheduling](./scheduling.md) - Delayed, scheduled, and cron-based tasks
 - [Retries](./retries.md) - Automatic retries with exponential backoff and jitter
 - [Durable Execution](./durable-execution.md) - `runFiber()`, `startFiber()`, `stash()`, and crash recovery for long tasks
@@ -80,7 +80,8 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Server-Driven Messages](./server-driven-messages.md) - Autonomous agent workflows: scheduled follow-ups, queue processing, webhooks, chained reasoning
 - TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
 - TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
-- [Sessions (Experimental)](./sessions.md) - Persistent conversation storage with tree-structured messages, context blocks, compaction, and search
+- [Sessions (Experimental)](./sessions.md) - Durable message trees, streamed history, compaction, search, and lossless attachment offload
+- [Context (Experimental)](./context.md) - System-prompt blocks, frozen prompts, writable/searchable/loadable providers, and their tools
 - [Workspace (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/shell/index.md) - Durable virtual filesystem backed by SQLite + R2
 - [Codemode (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/agents/codemode.md) - LLM-generated executable code for tool orchestration
 - [Client Tools Continuation](./client-tools-continuation.md) - Handling tool calls across client/server
@@ -141,6 +142,8 @@ The differentiator is not "we have durable state" — it is what happens when a
 ## Reference
 
 - [Durable Object Lifecycle](./lifecycle.md) - Compose reusable durable components outside the Agent base class
+- [Tasks](./tasks.md) - Durable, replayable background work with journaled steps and durable sleeps (experimental)
+- [Streams](./streams.md) - Durable incremental output: chunk log, cursor, replay-then-tail reads (experimental)
 - TODO: [API Reference](./api-reference.md) - Complete API documentation
 - TODO: [FAQ / How is this different from Durable Objects?](./faq.md)
 - TODO: [Resources & Further Reading](./resources.md)

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,24 @@ 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 declares how it claims traffic with `claims`, which defaults to
+`"selective"`. A `"catch-all"` capability dispatches after every other
+capability, whenever it was installed. Catch-alls are unique per dispatch
+hook: Lifecycle refuses a second catch-all for `onRequest` or for
+`onWebSocketUpgrade`, since it could never be reached, but one of each
+coexists. The `WebSockets` capability is a catch-all for upgrades only, so
+an HTTP catch-all installs beside it, and selective HTTP capabilities that
+target their own routes run before both. 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
@@ -140,49 +158,62 @@ host implicitly.
 
 Capability hooks run outside host context, but user callbacks run through
 `this.lifecycle.runInHostContext(fn)` inside the host invocation context.
-Scheduler dispatches its registered callbacks through this boundary, and a
-future capability that calls user code should do the same.
+Scheduler and Queue dispatch their 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 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.jobs.push({ id: "cleanup", fn: "sweep", time });
   }
 
-  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 +248,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 +298,124 @@ 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
+## WebSockets are an opt-in capability
 
-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`.
-
-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, 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}`);
+      }
+    },
+    callables: new MyCallables(this)
+  });
+  readonly lifecycle = Lifecycle.install(this).use(this.webSockets);
 }
 ```
 
-There is no non-hibernating mode.
+Without the capability installed, WebSocket upgrades are declined.
+
+### A plain host works with `useAgent`
+
+The capability speaks the Agent protocol on every connection, so a plain
+Durable Object is reachable from `useAgent` and `AgentClient` exactly like an
+`Agent`:
+
+- On connect it sends the identity frame, which resolves the client's
+  `ready` and `identified`, then the current state when `state` is set.
+  `protocol` controls this: `true` (default) for every connection, a
+  function to decide per connection — `false` marks it no-protocol, so it
+  gets no protocol text frames on connect or by broadcast but still sends
+  and receives ordinary messages and callables — or `false` to have the
+  host drive the sequence itself with `sendIdentity()` and `sendState()`.
+  `Agent` passes `false`, because it must decide whether a connection
+  belongs to a facet before any frame is sent.
+- `readonly` decides per connection whether state writes over the wire are
+  refused; `setReadonly()` flips it later. Both flags are stored in the
+  connection's own state under `_cf_` keys, hidden from `connection.state`
+  and preserved across `setState`, so they survive hibernation. `Agent`'s
+  `isConnectionReadonly`, `setConnectionReadonly`, and
+  `isConnectionProtocolEnabled` delegate to the same storage.
+- `callables` is an `RpcTarget` whose prototype methods are the host's
+  complete remote interface, reached through `call()` and `stub`. On the
+  `cf-websocket` wire the capability answers them as JSON `rpc` frames. On
+  the `capnweb` wire they are native Cap'n Web methods on the session root:
+  a returned `RpcTarget` arrives as a live stub the client can keep
+  calling, a `ReadableStream` streams, and chained calls pipeline. Methods
+  run through the host invocation boundary with the calling connection in
+  scope.
+- `state` takes a `State` capability (from `agents/state`) and syncs it over
+  connections, so `useAgent().state` and `setState()` work against a plain
+  host:
+
+  ```ts
+  readonly state = new State({
+    initialState: { count: 0 },
+    // The state owner decides who hears about a change.
+    onChanged: (_state, source) => this.webSockets.broadcastState(source)
+  });
+  readonly webSockets = new WebSockets({ state: this.state });
+  readonly lifecycle = Lifecycle.install(this)
+    .use(this.state)
+    .use(this.webSockets);
+  ```
+
+  The current value is pushed to each new connection after identity. A
+  client's `cf_agent_state` frame goes through the `State` capability, so
+  the host's own `validateStateChange` decides; a readonly connection is
+  refused, and a rejected change is logged server-side and answered with a
+  generic `cf_agent_state_error`. `broadcastState(source)` pushes the
+  current value to every protocol-enabled connection except `source`. This
+  is distinct from `connection.setState()`, which is per-connection and
+  never leaves the host. Without the option, state is never sent or
+  accepted over connections.
+
+- Any other frame goes to `handlers.onMessage`.
+
+An `Agent` adds no new surface for this: its `@callable()`-decorated methods
+are its JSON-wire interface, answered by its own message handler. They are
+not mirrored onto the Cap'n Web root; an Agent that wants native calls on
+`capnweb` passes a `callables` target like any other host.
+
+### Two wires
+
+The client chooses how frames travel:
+
+- **`cf-websocket`** (default) — accepted with Cloudflare's WebSocket Hibernation
+  API. Idle clients remain connected while the Durable Object leaves memory;
+  when a message wakes it, the constructor and lifecycle startup run again
+  before `onMessage`. State needed after a wake belongs in storage or
+  `connection.setState()`.
+- **Cap'n Web** (`?__agents_transport=capnweb`, or
+  `useAgent({ transport: "capnweb" })`) — protocol frames travel through one
+  pipe method on a Cap'n Web session whose root also carries the host's
+  `callables` natively. The connection is an in-memory socket and does not
+  hibernate: the object stays pinned while it is open, and clients reconnect
+  after an eviction.
+
+Handlers are wire-agnostic. Both kinds of connection dispatch the same
+`onConnect`/`onMessage`/`onClose`/`onError`, appear in `getConnections()`,
+and honour `connection.close(code, reason)`.
 
 ## 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.