agents 0.21.0 → 0.22.0

package/docs/agent-class.md

@@ -6,10 +6,15 @@ This document tries to bridge that gap, empowering any developer aiming to get s
 
 # What is the Agent?
 
-The `Agent` class is an extension of `DurableObject`. That is to say, they _are_ **Durable Objects**. If you're not familiar with Durable Objects, it is highly recommended that you read ["What are Durable Objects"](https://developers.cloudflare.com/durable-objects/) but at their core, Durable Objects are globally addressable (each instance has a unique ID) single-threaded compute instances with long term storage (KV/SQLite).  
-That being said, `Agent` does **not** extend `DurableObject` directly but instead `Server`. `Server` is a class provided by [PartyKit](https://github.com/cloudflare/partykit/tree/main/packages/partyserver).
+`Agent` directly extends Cloudflare's `DurableObject`, so every Agent is a globally addressable, single-threaded compute instance with durable KV/SQLite storage. If you are unfamiliar with the platform primitive, start with [What are Durable Objects](https://developers.cloudflare.com/durable-objects/).
 
-You can visualize the logic as a Matryoshka doll: **DurableObject** -> **Server** -> **Agent**.
+Each Agent composes a `Lifecycle` instance. The lifecycle installs request, alarm, and hibernating WebSocket entry points while the Agent supplies semantic callbacks and higher-level features:
+
+```text
+DurableObject
+└── Agent
+    └── owns Lifecycle
+```
 
 ## Layer 0: Durable Object
 
@@ -73,11 +78,11 @@ export class MyDurableObject extends DurableObject {
 }
 ```
 
-### `alarm()`
+### Alarms
 
-HTTP and RPC requests are not the only entrypoints for a DO. Alarms allow developers to schedule an event to trigger at a later time. Whenever the next alarm is due, the runtime will call the `alarm()` method, which is left to the developer to implement.
+`Lifecycle` owns the Agent's physical Durable Object alarm because schedules, keep-alive, fibers, sub-agents, and other capabilities share the same alarm slot. Do not override `alarm()` or call `this.ctx.storage.setAlarm()` from an Agent feature; one caller could overwrite another feature's wake-up.
 
-To schedule an alarm, you can use the `this.ctx.storage.setAlarm()` method. For more information, check [the documentation](https://developers.cloudflare.com/durable-objects/api/alarms/).
+Use `this.schedule()` for named Agent callbacks. A reusable capability with its own durable work implements `getNextAlarm()` and `onAlarm()`, then calls `this.lifecycle.alarms.rearm()` after its durable state changes. See [Durable Object lifecycle](./lifecycle.md#shared-alarm-ownership) and [Scheduling](./scheduling.md).
 
 ### `this.ctx`
 
@@ -102,104 +107,43 @@ const token = kv.get("someToken");
 
 Lastly, it's worth mentioning that the DO also has the Worker `Env` in `this.env`. Read more [here](https://developers.cloudflare.com/workers/runtime-apis/bindings).
 
-## Layer 1: Partykit `Server`
-
-Now that you've seen what Durable Objects come with out-of-the-box, what [PartyKit](https://github.com/cloudflare/partykit)'s `Server` (package `partyserver`) implements will be clearer. It's an **opinionated `DurableObject` wrapper that improves DX by hiding away DO primitives in favor of more developer friendly callbacks**.
-
-An important note is that `Server` **does NOT persist to the DO storage** so you will not see extra storage operations by using it.
-
-### Addressing
+## Layer 1: lifecycle composition
 
-`partyserver` exposes helper to address your DOs instead of manually through your bindings. This allows `partyserver` to implement several improvements, including a unique URL routing scheme for your DOs (e.g. `<your-worker>/servers/:durableClass/:durableName`).
-
-Compare this to the DO addressing [example above](#rpc).
+`Agent` uses `Lifecycle.install(this)`, an explicit side-effect-named factory that constructs the lifecycle and installs the platform-facing `fetch`, `alarm`, `webSocketMessage`, `webSocketClose`, and `webSocketError` handlers. Agent subclasses implement semantic callbacks instead of a second base class:
 
 ```ts
-// Note the await here!
-const stub = await getServerByName(env.MY_DO, "foo");
-
-// We can still call RPC methods.
-await stub.bar();
-```
-
-Since we have a URL addressing scheme, we also get access to `routePartykitRequest()`.
-
-```ts
-  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    // Behind the scenes, PartyKit normalizes your DO binding names
-    // and tries to do some pattern matching.
-    const res = await routePartykitRequest(request, env);
-
-    if (res) return res;
-
-    return Response("Not found", { status: 404 });
-  }
-```
-
-You can have a look at [the implementation](https://github.com/cloudflare/partykit/blob/main/packages/partyserver/src/index.ts#L122) if you're interested.
-
-### `onStart`
-
-The extra plumbing that `Server` includes on addressing allows it to expose an `onStart` callback that is **executed every time the DO starts up** (the DO was evicted, hibernated or never created at all) and **before any `fetch` or RPC**.
-
-```ts
-class MyServer extends Server {
+class MyAgent extends Agent {
   onStart() {
-    // Some initialization logic that you wish
-    // to run every time the DO is started up.
-    const sql = this.ctx.storage.sql;
-    sql.exec(`...`);
+    // Runs once per in-memory lifetime before work is handled.
   }
-}
-```
-
-### `onRequest` and `onConnect`
 
-`Server` already implements `fetch` for the underlying Durable Object and exposes 2 different callbacks that developers can make use of, `onRequest` and `onConnect` for HTTP requests and incoming WS connections, respectively (**WebSocket connections are accepted by default**).
-
-```ts
-class MyServer extends Server {
-  async onRequest(request: Request) {
-    const url = new URL(request.url);
-
-    return new Response(`Hello from ${url.origin}!`);
+  onRequest(request: Request) {
+    return new Response(`Hello from ${request.url}`);
   }
 
-  async onConnect(conn, ctx) {
-    const { request } = ctx;
-    const url = new URL(request.url);
-
-    // Connections are a WebSocket wrapper
-    conn.send(`Hello from ${url.origin}!`);
+  onConnect(connection: Connection) {
+    connection.send("connected");
   }
 }
 ```
 
-### WebSockets
-
-Just as `onConnect` is the callback for every new connection, `Server` also provides wrappers on top of the default callbacks from the `DurableObject` class: `onMessage`, `onClose` and `onError`.
-
-There's also `this.broadcast` that sends a WS message to all connected clients (no magic, just a loop over `this.getConnections()`!).
-
-### `this.name`
+Lifecycle WebSockets always use Cloudflare's Hibernation API. Idle clients stay connected while the Durable Object can leave memory; constructor fields and `onStart` run again when a message wakes it. Persist anything needed across wakes in storage or `connection.state`.
 
-Since [2026-03-15](https://developers.cloudflare.com/changelog/post/2026-03-15-durable-object-id-name/), the Workers runtime populates `ctx.id.name` inside a Durable Object addressed via `idFromName()` or `getByName()`, including in alarm handlers. Constructor-time availability isn't spelled out in the docs, but workerd's own tests pin it ([workerd#6421](https://github.com/cloudflare/workerd/pull/6421)), as do `partyserver`'s runtime-contract tests. `partyserver` reads `ctx.id.name` first, so for named access `this.name` resolves natively with no extra machinery.
+Reusable capabilities can be installed through `this.lifecycle.use(capability)`. Capabilities start before Agent startup, can intercept requests before `onRequest`, and process alarms before `onAlarm`. See [Durable Object lifecycle](./lifecycle.md).
 
-`ctx.id.name` is still `undefined` in these cases (see [the DO id docs](https://developers.cloudflare.com/durable-objects/api/id/#name)):
+### Identity
 
-- the object is addressed via `idFromString()` (even if the id was originally created with `idFromName()`) or `newUniqueId()` — deliberate design, not a gap;
-- the name is longer than 1,024 bytes;
-- the alarm firing was scheduled before 2026-03-15, or was scheduled from a context that itself had no name (reschedule it from a `fetch()` or RPC handler where the name is available).
+Since [2026-03-15](https://developers.cloudflare.com/changelog/post/2026-03-15-durable-object-id-name/), Workers exposes the name used by `idFromName()` or `getByName()` as `ctx.id.name`, including in alarm handlers. Agents and Agent facets use named IDs, and `this.name` projects that native identity.
 
-For those cases `partyserver` falls back to a legacy name record in storage (written automatically during named-access initialization, or by the `setName()` bootstrap for raw-id DOs), and `this.name` throws if no name can be resolved at all.
+For migration, lifecycle can read an existing `__ps_name` value written by an older release. It never writes a duplicate name. Raw IDs, `idFromString()`, and names over 1,024 bytes do not provide native identity. Alarms created before 2026-03-15 must be rescheduled from a named fetch or RPC handler.
 
 ## Layer 2: Agent
 
-Now finally, the `Agent` class. `Agent` extends `Server` and provides opinionated primitives for stateful, schedulable, and observable agents that can communicate via RPC, WebSockets, and (even!) email.
+The `Agent` class directly extends `DurableObject`, composes the lifecycle above, and provides opinionated primitives for stateful, schedulable, and observable agents that can communicate via RPC, WebSockets, and (even!) email.
 
 ### `this.state` and `this.setState()`
 
-One of the core features of `Agent` is **automatic state persistence**. Developers define the shape of their state via the generic parameter and `initialState` (which is only used if no state exists in storage), and the Agent handles loading, saving, and broadcasting state changes (check `Server`'s `this.broadcast()` above).
+One of the core features of `Agent` is **automatic state persistence**. Developers define the shape of their state via the generic parameter and `initialState` (which is only used if no state exists in storage), and the Agent handles loading, saving, and broadcasting state changes (using its lifecycle-managed WebSocket connections).
 
 `this.state` is a getter that lazily loads state from storage (SQL). **State is persisted across DO evictions** when it's updated with `this.setState()`, which automatically serializes the state and writes it back to storage.  
 There's also `this.onStateChanged` that you can override to react to state changes.
@@ -419,7 +363,7 @@ function someUtilityFunction() {
 
 ### `this.onError`
 
-`Agent` extends `Server`'s `onError` so it can be used to handle errors that are not necessarily WebSocket errors. It is called with a `Connection` or `unknown` error.
+`Agent.onError` handles both WebSocket errors and other Agent errors. It is called with a `Connection` or `unknown` error.
 
 ```ts
 class MyAgent extends Agent {
@@ -495,14 +439,12 @@ application; return a recovery result to update the retained status record.
 
 ### Routing
 
-The `Agent` class re-exports PartyKit's [addressing helpers](#addressing) as `getAgentByName` and `routeAgentRequest`.
+Use `getAgentByName` for named RPC stubs and `routeAgentRequest` for `/agents/:class/:name` HTTP and WebSocket routing.
 
 ```ts
-// Same API as getServerByName
 const stub = await getAgentByName(env.MY_DO, "foo");
 // ...
 
-// Same API as routeServerRequest
 const res = await routeAgentRequest(request, env);
 
 if (res) return res;

package/docs/chat-agents.md

@@ -590,17 +590,11 @@ If you do not pass `abortSignal` to `streamText`, the LLM call will continue run
 
 ### Stream Recovery
 
-When a Durable Object is evicted mid-stream (code update, inactivity timeout, resource limit), the LLM connection is severed permanently and the in-memory streaming state is lost. `chatRecovery` wraps each chat turn in a [`runFiber()`](./durable-execution.md), providing automatic `keepAlive` during streaming and a recovery hook on restart.
+When a Durable Object is evicted mid-stream (code update, inactivity timeout, resource limit), the LLM connection is severed permanently and the in-memory streaming state is lost. Durable recovery wraps every `AIChatAgent` and `Think` chat turn in a [`runFiber()`](./durable-execution.md), providing automatic `keepAlive` during streaming and a recovery hook on restart.
 
-```typescript
-export class ChatAgent extends AIChatAgent {
-  override chatRecovery = true;
-}
-```
-
-When enabled, every `onChatMessage` call runs inside a fiber. If the agent is evicted mid-stream, the fiber row survives in SQLite. On the next activation, the framework detects the interrupted fiber, reconstructs the partial response from buffered stream chunks, and calls `onChatRecovery`.
+If the agent is evicted mid-stream, the fiber row survives in SQLite. On the next activation, the framework detects the interrupted fiber, reconstructs the partial response from buffered stream chunks, and calls `onChatRecovery`.
 
-`AIChatAgent` defaults `chatRecovery` to `false` so existing chat agents only get client reconnect/resumable-stream behavior. `Think` defaults it to `true`.
+Durable recovery is always enabled. Use `chatRecovery` only to tune its budgets and terminal behavior.
 
 > **Assign `chatRecovery` as a class field or in the constructor — never in `onStart()`.** On every wake the SDK evaluates recovery budgets (and may seal an interrupted turn, firing `onExhausted`) _before_ your `onStart()` body runs. A config produced inside `onStart()` is therefore read as the built-in defaults at the moment recovery decides, so your `maxRecoveryWork` / `shouldKeepRecovering` / `onExhausted` silently never apply to the recovery that matters. The SDK logs a one-time warning if it detects `chatRecovery` being assigned during `onStart()`.
 
@@ -610,8 +604,6 @@ Override to implement provider-specific recovery. The default behavior persists
 
 ```typescript
 export class ChatAgent extends AIChatAgent {
-  override chatRecovery = true;
-
   override async onChatRecovery(
     ctx: ChatRecoveryContext
   ): Promise<ChatRecoveryOptions> {
@@ -659,7 +651,16 @@ Settled work is never dropped: `persist: false` only suppresses persistence of a
 
 When recovery happens before any stream chunks were written, there is no partial assistant message to continue. If the latest persisted message is still the unanswered user message from the interrupted turn, the framework retries that turn automatically unless `continue` is `false`.
 
-`chatRecovery` can also be configured with budgets and terminal behavior:
+#### Controlling automatic continuation
+
+Durable bookkeeping stays enabled even when automatic continuation is not appropriate:
+
+- **Retries or side effects are unsafe:** override `onChatRecovery()` and return `{ continue: false }`. Persist idempotency keys or completion records before external side effects so a recovered turn can tell whether work already happened.
+- **Cancellation must survive eviction:** an `AbortSignal` only cancels the current in-memory turn. Also persist cancellation intent in agent state or SQL, read it in `onChatRecovery()`, and return `{ continue: false }` when cancellation was requested.
+- **Cost must be bounded:** set `maxAttempts`, `noProgressTimeoutMs`, `maxRecoveryWork`, and `maxOomRetries`. Use `shouldKeepRecovering` with durable spend data to stop later attempts. The predicate is not bound to the agent instance, so read spend from a store keyed by `ctx.recoveryRootRequestId`.
+- **A provider can resume without a new model call:** use `this.stash()` to save its response ID, retrieve that response in `onChatRecovery()`, and return `{ persist: false, continue: false }`.
+
+`chatRecovery` can be configured with budgets and terminal behavior:
 
 ```typescript
 override chatRecovery = {

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

@@ -140,6 +140,7 @@ 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
 - 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,323 @@
+# 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 after lifecycle capabilities process the alarm.
+  }
+}
+```
+
+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. Existing Agent classes continue to
+override `onStart`, `onRequest`, `onConnect`, `onMessage`, `onClose`, and
+`onError` normally.
+
+## Request call path
+
+```text
+routeAgentRequest(request)
+└─ named Durable Object stub.fetch(request)
+   └─ lifecycle-installed fetch
+      ├─ lifecycle startup capabilities
+      ├─ host onStart
+      ├─ lifecycle request capabilities
+      │  └─ first Response wins
+      └─ host onRequest
+```
+
+A warm object skips startup but still offers every request to its capabilities.
+
+## 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");
+    }
+  }
+
+  onAlarm(): void {
+    this.storage.sql.exec("DELETE FROM audit_log");
+  }
+}
+```
+
+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 and alarms run every hook
+sequentially. Request handling stops at the first returned `Response`. A phase
+failure propagates, and failed startup can be retried.
+
+Capabilities extending `LifecycleCapability` receive one standard service
+surface: storage, readiness, startup state, alarm coordination, 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.
+
+## Shared alarm ownership
+
+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()`:
+
+```ts
+import { LifecycleCapability, type AlarmContribution } 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.storage.put("cleanup:next", time);
+    await this.lifecycle.alarms.rearm();
+  }
+}
+```
+
+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.
+
+## 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.
+Existing rows remain in the root `cf_agents_schedules` table. 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;
+- `onConnect`: object, connection, and upgrade request;
+- `onMessage`, `onClose`, and `onError`: object and connection.
+
+`getConnectionTags(connection, { request })` remains argument-driven because it
+already receives both values explicitly. The root `agents` package continues
+to export `getCurrentAgent()` for the `Agent` class as a compatibility alias.
+
+## WebSockets always hibernate
+
+The lifecycle always uses Cloudflare's WebSocket Hibernation API. Idle clients
+remain connected while the Durable Object can leave memory. When a message
+wakes the object, its constructor and lifecycle startup run again before
+`onMessage`.
+
+State needed after a wake must be stored durably or through connection state:
+
+```ts
+onConnect(connection: Connection): void {
+  connection.setState({ authenticated: true });
+}
+
+onMessage(connection: Connection<{ authenticated: boolean }>): void {
+  console.log(connection.state?.authenticated);
+}
+```
+
+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

@@ -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 }`.