agents 0.21.0 → 0.23.0

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/durable-execution.md

@@ -466,7 +466,7 @@ Key points:
 
 ### Chat recovery
 
-`AIChatAgent` builds on fibers for LLM streaming recovery. When `chatRecovery` is enabled, each chat turn is wrapped in a fiber automatically. The framework handles the internal recovery path and exposes `onChatRecovery` for provider-specific strategies. See [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams) and the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat).
+`AIChatAgent` and `Think` build on fibers for LLM streaming recovery. Every chat turn is wrapped in a fiber automatically. The framework handles the internal recovery path and exposes `onChatRecovery` for provider-specific strategies. See [Long-Running Agents: Recovering interrupted LLM streams](./long-running-agents.md#recovering-interrupted-llm-streams) and the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat).
 
 ## Concurrent fibers
 

package/docs/http-websockets.md

@@ -408,17 +408,7 @@ export class MyAgent extends Agent {
 
 ## Hibernation
 
-Agents support hibernation - they can sleep when inactive and wake when needed. This saves resources while maintaining WebSocket connections.
-
-### Enabling Hibernation
-
-Hibernation is enabled by default. To disable:
-
-```typescript
-export class AlwaysOnAgent extends Agent {
-  static options = { hibernate: false };
-}
-```
+Agent WebSockets always use Cloudflare's Hibernation API. An idle Agent can leave memory while its WebSocket clients remain connected; there is no non-hibernating mode.
 
 ### How Hibernation Works
 

package/docs/human-in-the-loop.md

@@ -357,7 +357,7 @@ See the complete example: [guides/human-in-the-loop/](https://github.com/cloudfl
 
 ### Surviving restarts while waiting for a human
 
-A Durable Object can be evicted at any time (a deploy, an inactivity timeout, a resource limit), including while a turn is paused on an approval prompt or a client-side tool call. When [`chatRecovery`](./chat-agents.md#stream-recovery) is enabled (the default for `Think`), the SDK recognizes that such a turn is _waiting on the human_, not stuck, and does **not** seal it: the no-progress window, attempt cap, `maxRecoveryWork`, and `shouldKeepRecovering` are all suspended while the interaction is pending. Recovery parks the turn instead of failing it, and the user's eventual approval or `tool_result` resumes the conversation through the normal continuation path. A user who takes minutes to respond to a prompt that was interrupted by a deploy therefore does not see a spurious "session interrupted" error.
+A Durable Object can be evicted at any time (a deploy, an inactivity timeout, a resource limit), including while a turn is paused on an approval prompt or a client-side tool call. Durable [`chatRecovery`](./chat-agents.md#stream-recovery) is always enabled. The SDK recognizes that such a turn is _waiting on the human_, not stuck, and does **not** seal it: the no-progress window, attempt cap, `maxRecoveryWork`, and `shouldKeepRecovering` are all suspended while the interaction is pending. Recovery parks the turn instead of failing it, and the user's eventual approval or `tool_result` resumes the conversation through the normal continuation path. A user who takes minutes to respond to a prompt that was interrupted by a deploy therefore does not see a spurious "session interrupted" error.
 
 This protection applies to interactions only the client can resolve — `approval-requested` parts and `input-available` parts for client-side tools (those without a server `execute`). A server tool whose `execute()` was killed mid-flight is a genuine orphan and recovers through the normal transcript-repair path instead.
 

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,9 +57,9 @@ 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
 
@@ -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
@@ -140,6 +141,9 @@ 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

@@ -0,0 +1,370 @@
+# Durable Object lifecycle
+
+> **Experimental.** Everything exported from `agents/lifecycle` — and the
+> capabilities built on it, including `Scheduler` — may change between
+> releases while the composition surface stabilizes.
+
+`agents/lifecycle` lets reusable durable capabilities work in both `Agent` and a
+plain Cloudflare Durable Object. It uses composition: your class extends the
+platform `DurableObject`, then constructs a lifecycle with `this`.
+
+## Plain Durable Object
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+
+export class MyObject extends DurableObject<Env> {
+  readonly lifecycle = Lifecycle.install(this);
+
+  onStart(): void {
+    // Runs once per in-memory object lifetime, before work is handled.
+  }
+
+  onRequest(request: Request): Response {
+    return new Response(`Hello from ${this.lifecycle.name}: ${request.url}`);
+  }
+
+  onAlarm(): void {
+    // Runs once per alarm invocation, after due jobs are driven.
+  }
+}
+```
+
+The side-effect-named static factory constructs the lifecycle and installs the
+runtime-facing `fetch`, `alarm`, `webSocketMessage`, `webSocketClose`, and
+`webSocketError` handlers. Do not define forwarding versions of those methods.
+Implement the semantic callbacks instead.
+
+The expanded equivalent is available when useful:
+
+```ts
+readonly lifecycle = new Lifecycle(this);
+
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env);
+  this.lifecycle.installHandlers();
+}
+```
+
+Route named objects from the outer Worker when you want URL routing:
+
+```ts
+import { routeAgentRequest } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
+
+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 (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
+      ├─ capability middleware, in registration order
+      │  └─ first Response handles the request
+      └─ host onRequest
+```
+
+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
+
+A capability implements only the phases it needs:
+
+```ts
+import type { DurableObjectCapability } from "agents/lifecycle";
+
+class AuditLog implements DurableObjectCapability {
+  constructor(private readonly storage: DurableObjectStorage) {}
+
+  onStart(): void {
+    this.storage.sql.exec(`
+      CREATE TABLE IF NOT EXISTS audit_log (
+        message TEXT NOT NULL
+      )
+    `);
+  }
+
+  onRequest({ request }: { request: Request }): Response | undefined {
+    if (new URL(request.url).pathname.endsWith("/health")) {
+      return new Response("ok");
+    }
+  }
+}
+```
+
+Install it before startup:
+
+```ts
+export class MyObject extends DurableObject<Env> {
+  private readonly audit = new AuditLog(this.ctx.storage);
+  readonly lifecycle = Lifecycle.install(this).use(this.audit);
+
+  onRequest(): Response {
+    return new Response("application response");
+  }
+}
+```
+
+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, 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
+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.
+
+## The job queue
+
+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 LifecycleJobContext
+} from "agents/lifecycle";
+
+class Cleanup extends LifecycleCapability {
+  constructor() {
+    super("cleanup");
+  }
+
+  async scheduleCleanup(time: number): Promise<void> {
+    await this.lifecycle.jobs.push({ id: "cleanup", fn: "sweep", time });
+  }
+
+  async onJob({ job }: LifecycleJobContext): Promise<void> {
+    // job.fn === "sweep"; returning nothing completes the job.
+    await this.lifecycle.storage.delete("cleanup:marker");
+  }
+}
+```
+
+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
+
+Capabilities publish best-effort telemetry through their standard service
+surface. Lifecycle assigns the capability source from the stable ID passed to
+`super()`:
+
+```ts
+class Cleanup extends LifecycleCapability {
+  constructor() {
+    super("cleanup");
+  }
+
+  reportRemoval(key: string): void {
+    this.lifecycle.events.emit("cleanup:remove", { key });
+  }
+}
+```
+
+Lifecycle publishes events from a plain Lifecycle Object to the existing
+`agents:*` diagnostics channels according to the event type. Delivery is
+best-effort, runs outside ambient host context, and does not fail the emitting
+capability when a telemetry sink throws. Persist an outbox in the capability
+when delivery is part of the durable business operation.
+
+## Capability routing
+
+Every `LifecycleCapability` also receives `lifecycle.routes`. `toRoot()` routes
+a message to the matching capability ID on the root Lifecycle; `to(address, …)`
+routes to another addressed Lifecycle. Lifecycle owns the generic envelope and
+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.
+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.
+
+## Explicit disposal
+
+`lifecycle.dispose()` calls each capability's optional `dispose()` method in
+reverse installation order. This phase releases live resources such as MCP
+transports and listeners. It does not delete capability tables. An explicit
+Lifecycle Object destruction disposes live resources once, then calls
+`storage.deleteAll()` once for all shared durable state. Eviction calls neither.
+
+## Lifecycle Object context
+
+`agents/lifecycle` exports the `LifecycleObject` interface for a
+`DurableObject` with an installed `Lifecycle` and the semantic hooks Lifecycle
+dispatches. This is a host type, not the batteries-included `Agent` class
+exported from `agents`.
+
+Lifecycle establishes the `getCurrentAgent()` context only while it invokes
+host hooks. Capability hooks run outside that ambient context and use their own
+`this`, hook arguments, and explicitly supplied dependencies.
+
+```ts
+import { getCurrentAgent } from "agents/lifecycle";
+
+function currentRequestOrigin(): string | undefined {
+  const { request } = getCurrentAgent();
+  return request ? new URL(request.url).origin : undefined;
+}
+
+export class MyObject extends DurableObject<Env> {
+  readonly lifecycle = Lifecycle.install(this);
+
+  onRequest(): Response {
+    return Response.json({ origin: currentRequestOrigin() });
+  }
+}
+```
+
+Pass the concrete host class when shared host code needs its additional APIs:
+
+```ts
+const { agent: object } = getCurrentAgent<MyObject>();
+```
+
+Host context values follow the invocation:
+
+- `onStart` and `onAlarm`: object;
+- `onRequest`: object and request;
+- `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 are an opt-in capability
+
+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
+import { WebSockets } from "agents/websockets";
+
+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);
+}
+```
+
+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
+
+Native Durable Object RPC does not pass through `fetch`. An RPC method that
+requires initialized capabilities starts the lifecycle explicitly:
+
+```ts
+async runTask(): Promise<void> {
+  await this.lifecycle.start();
+  // initialized work
+}
+```
+
+Agent's internal RPC entry points already enforce this boundary.
+
+## Object names
+
+Use `idFromName()` or `getByName()`. The lifecycle reads the authoritative name
+from `ctx.id.name` and exposes it as `lifecycle.name`.
+
+For migration only, the lifecycle can read an existing `__ps_name` record
+written by an older PartyServer release. It never writes that key. Deprecated
+name headers and bootstrap methods are not supported.
+
+If a name cannot be resolved, the error covers named addressing, updating local
+Wrangler/workerd and the compatibility date, unsupported raw IDs and oversized
+names, and rescheduling alarms created before 2026-03-15.

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> {
@@ -537,7 +537,7 @@ For chat-oriented sub-agents, [Think](https://github.com/cloudflare/agents/blob/
 
 The patterns above handle the project manager's coordination work — scheduling, delegating, polling. But the project manager also uses an LLM directly: generating plans, summarizing progress, drafting status emails. Those LLM calls stream tokens over a connection that cannot be resumed if the agent is evicted mid-response.
 
-For chat-oriented agents built on `AIChatAgent`, this is an even sharper problem — the user is watching the response stream in real time and sees it stop mid-sentence. `chatRecovery` wraps each chat turn in a `runFiber`, providing automatic `keepAlive` during streaming and a recovery hook when the agent restarts:
+For chat-oriented agents built on `AIChatAgent` or `Think`, this is an even sharper problem — the user is watching the response stream in real time and sees it stop mid-sentence. Durable recovery wraps every chat turn in a `runFiber`, providing automatic `keepAlive` during streaming and a recovery hook when the agent restarts:
 
 ```typescript
 import { AIChatAgent } from "@cloudflare/ai-chat";
@@ -547,8 +547,6 @@ import type {
 } from "@cloudflare/ai-chat";
 
 class ProjectChat extends AIChatAgent<Env> {
-  override chatRecovery = true;
-
   override async onChatRecovery(
     ctx: ChatRecoveryContext
   ): Promise<ChatRecoveryOptions> {
@@ -573,7 +571,7 @@ The right recovery strategy depends on the LLM provider:
 
 For a complete multi-provider implementation with full code for each strategy, see the [`forever-chat` example](https://github.com/cloudflare/agents/tree/main/experimental/forever-chat) and the [`forever.md` design doc](https://github.com/cloudflare/agents/tree/main/experimental/forever.md).
 
-[Think](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) enables `chatRecovery` by default. The default path persists partial output and auto-continues or retries the turn when safe, so many apps do not need a custom hook. Override `onChatRecovery` when a provider has a better recovery strategy, or configure `chatRecovery = { maxAttempts, terminalMessage, onExhausted }` to tune the terminal user experience.
+`AIChatAgent` and [Think](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) always enable durable recovery. The default path persists partial output and auto-continues or retries the turn when safe, so many apps do not need a custom hook. Override `onChatRecovery` when a provider has a better recovery strategy, or configure `chatRecovery = { maxAttempts, terminalMessage, onExhausted }` to tune the terminal user experience.
 
 If the agent is interrupted before any assistant stream chunks are written, there is no partial assistant message to continue. When the latest persisted message is still the unanswered user message from that turn, chat recovery retries the turn automatically unless `onChatRecovery` returns `{ continue: false }`.
 
@@ -625,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.