agents 0.21.0 → 0.23.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 pushes jobs through `this.lifecycle.jobs` and implements `onJob()`; Lifecycle drives due jobs and re-arms the alarm from queue state. See [Durable Object lifecycle](./lifecycle.md#the-job-queue) 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.
@@ -334,7 +278,7 @@ class MyAgent extends Agent {
 }
 ```
 
-Schedules are stored in the `cf_agents_schedules` SQL table. Cron schedules automatically reschedule themselves after execution, while one-time schedules are deleted.
+Schedules are stored as jobs in the `cf_agents_jobs` SQL table, the Lifecycle-owned job queue. Cron schedules automatically reschedule themselves after execution, while one-time schedules are deleted.
 
 ### `this.mcp` and friends
 
@@ -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/agent-tools.md

@@ -1,7 +1,8 @@
 # Agent Tools
 
 Agent tools let one chat agent dispatch another chat-capable sub-agent as part
-of its work. The child is a real sub-agent with its own Durable Object storage,
+of its work — per-run, parent-supervised delegation is the flagship use case
+for facet-backed dynamic agents. The child is a real sub-agent with its own Durable Object storage,
 messages, tools, resumable stream, and drill-in URL. The parent keeps a small
 run registry so clients can render the child timeline, replay it after refresh,
 and clean it up later.

package/docs/channels.md

@@ -0,0 +1,323 @@
+# `agents/channels`
+
+`agents/channels` gives an agent one interface for sending and receiving
+messages across different platforms. Use a Channel directly, expose it as an AI
+tool, or register it with a durable `ChannelHost` that owns routing and delivery
+recovery.
+
+> [!NOTE]
+> Channels is experimental. Its interface _will_ change before the package
+> reaches a stable release.
+
+## Install
+
+```bash
+npm install agents
+```
+
+## Create channels
+
+Each adapter turns provider configuration into the same `Channel` interface. A
+`ChannelHost` holds them, keyed by names you choose:
+
+```typescript
+import { ChannelHost, routes } from "agents/channels";
+import { email } from "agents/channels/email";
+import { slack } from "agents/channels/slack";
+import { telegram } from "agents/channels/telegram";
+
+const host = new ChannelHost({
+  channels: {
+    slack: slack({
+      botToken: env.SLACK_BOT_TOKEN,
+      webhook: {
+        signingSecret: env.SLACK_SIGNING_SECRET,
+        botUserId: env.SLACK_BOT_USER_ID
+      },
+      route: routes.perThread
+    }),
+    telegram: telegram({
+      botToken: env.TELEGRAM_BOT_TOKEN,
+      webhook: { secretToken: env.TELEGRAM_WEBHOOK_SECRET },
+      route: routes.perThread
+    }),
+    email: email({
+      binding: env.EMAIL,
+      from: "agent@example.com",
+      route: routes.perThread
+    })
+  },
+
+  async onMessage({ route, dispatchId, message }) {
+    await conversationFor(route).receive(dispatchId, message);
+  }
+});
+```
+
+## 1. Send a message
+
+A **surface** is a destination for an outbound message.
+You get one from an inbound message's reply field, or by constructing one from a raw channel identifier through the host.
+
+```typescript
+const surface = host.contactSurface({
+  channelKey: "slack",
+  scope: "T123",
+  subject: "U456"
+});
+
+await host.deliver(surface, {
+  title: "Import needs attention",
+  markdown: "The customer import stopped after **1,240 records**."
+});
+```
+
+An identity's `channelKey` names the configured Channel that observed it. Its
+optional `scope` names a tenant within that Channel and defaults to `"default"`;
+for example, one configured Slack app can observe the same user ID in several
+workspaces. The Host stamps `channelKey` on inbound identities because an adapter
+does not know the key it was configured under.
+
+The same human observed through two configured Channels on one platform is two
+Channel identities, just as the same human on Slack and email is. Applications
+that know they are the same person link those identities explicitly.
+
+Compose destinations with `fallback()` and `fanout()`:
+
+```typescript
+import { fallback, fanout } from "agents/channels";
+
+await host.deliver(fallback([slackSurface, emailSurface]), message);
+await host.deliver(fanout([slackSurface, emailSurface]), message);
+```
+
+`fallback()` tries destinations in order, advancing only after a _confirmed_
+failure, so it can never duplicate a delivery. For a stream, it advances only
+when that failure happens before the destination starts reading; replaying an
+arbitrarily large consumed prefix would require an unbounded buffer. `fanout()`
+sends to all destinations; a partial or uncertain result is reported as
+`uncertain` for the same reason.
+The Host installs both policies as ordinary Channels under reserved keys. You
+can register another composite policy as an ordinary Channel under your own key
+and pair it with a surface constructor that writes that key; inject only the
+outbound resolution capability the policy needs, as the exported built-in
+policy Channels do.
+
+## 2. Give a destination to a model
+
+```typescript
+import { generateText, stepCountIs } from "ai";
+import { createWorkersAI } from "workers-ai-provider";
+import { createSendMessageTool } from "agents/channels/ai-sdk";
+
+const workersai = createWorkersAI({ binding: env.AI });
+
+await generateText({
+  model: workersai("@cf/moonshotai/kimi-k2.7-code"),
+  prompt: "An import stopped after 1,240 records. Notify support.",
+  tools: {
+    contactSupport: createSendMessageTool(
+      host,
+      fallback([slackSurface, emailSurface]),
+      { description: "Contact support when a person needs to intervene" }
+    )
+  },
+  stopWhen: stepCountIs(2)
+});
+```
+
+The model writes the message; you chose the destination. TanStack AI exports the
+same `createSendMessageTool(host, surface, options)` from
+`agents/channels/tanstack-ai`.
+
+## 3. Receive messages
+
+One entry point covers every configured Channel's webhook, and Workers Email
+arrives the same way:
+
+```typescript
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const response = await host.handleRequest(request);
+    if (response) return response;
+    return new Response("Not found", { status: 404 });
+  },
+
+  async email(message: ForwardableEmailMessage): Promise<void> {
+    await host.handleEmail(message);
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+Each Channel authenticates its own input and declines what isn't its business,
+so the Host asks them in configuration order and the first to claim it wins.
+
+### Routing
+
+A Channel's `route` turns one normalized event into an opaque application
+string — a Durable Object name, a queue key, a database id — or `null` to ignore
+the event entirely. The key is used to identify a common destination for
+messages -- i.e. typically a single conversation:
+
+```typescript
+telegram({
+  // …credentials…
+  route(event) {
+    return event.thread.isDirectMessage === true ? event.thread.id : null;
+  }
+});
+```
+
+Channels exposes builtin helpers for the common mappings — `routes.perThread`
+and `routes.perEvent`, which namespace their routes as `thread:…` and
+`event:…`.
+
+Deciding whether an event is relevant at all is a different question, and one
+only your application can answer, because the answer usually depends on state
+you hold. Write that in your own `route` and return `null` to ignore the event:
+
+```typescript
+route(event) {
+  // Slack shows a bot every message in every channel it belongs to. Answer
+  // when addressed, and otherwise only join threads we are already in.
+  const thread = routes.perThread(event);
+  const addressed =
+    event.thread.isDirectMessage === true || event.message.isMention === true;
+  if (addressed) return thread;
+  return (await myConversations.knows(thread)) ? thread : null;
+}
+```
+
+A lookup like that runs for every event reaching it, so put it behind a cheaper
+check, keep it read-only, and do not let it create the state it is testing for —
+otherwise the first stray message conjures the thing the check is looking for.
+
+### Link identities
+
+Personal agents often wwant to resolve users regardless of the channel they messaged on. Your application can explicitly record connections between channel identities and expose them to the Host for messages to be routed on:
+
+```typescript
+const host = new ChannelHost({
+  channels,
+  findUser: (identity) => users.findUser(identity),
+  onMessage,
+  onApprovalResponse
+});
+
+// ...
+// route to a user's central conversaion if one exists, else start a new
+// conversation for each thread:
+route: routes.byUser(routes.perThread);
+
+// or prefer the linked person, then the sender we recognise, then a new
+// conversation per event:
+route: routes.byUser(routes.byIdentity(routes.perEvent));
+```
+
+`byIdentity` groups events carrying the _same_ identity. It never infers that
+two different identities belong to one person — that stays an explicit
+application decision, which `byUser` then exposes to routing. Omit its fallback
+to ignore events that carry no identity at all.
+
+If your application does not already store user identities, `createUserIdentityStore(storage)` creates a Durable Object SQL store of the right shape. Your application can call `store.link` to connect multiple identities together.
+
+### Ask for approval
+
+### Request approval
+
+The Host exposes a utility for durably correlating inbound approvals to outbound requests:
+
+```typescript
+await host.requestApproval({
+  interactionId: "deploy-42",
+  request: {
+    title: "Production deployment",
+    summary: "Deploy version 2026.08.17 to production?",
+    input: {
+      version: "2026.08.17",
+      environment: "production"
+    }
+  }
+});
+await host.requestApproval(surface, {
+  interactionId: crypto.randomUUID(),
+  request: {
+    title: "Production deployment",
+    summary: "Deploy version 2026.08.17 to production?",
+    input: { version: "2026.08.17" }
+  }
+});
+```
+
+Users can respond to approval requests through native surfaces (e.g. Telegram
+buttons) or HTTP inbound URLs, resolved by the Channel Host itself for your application to settle.
+
+## Custom channels
+
+Any transport can become a Channel:
+
+```typescript
+import { matchesPath, routes, type Channel } from "agents/channels";
+
+const supportForm: Channel = {
+  route: routes.perEvent,
+  ingress: {
+    async receive(request) {
+      if (!matchesPath(request, "/support")) return null;
+
+      const raw = await request.json<{ message: string; email: string }>();
+      const eventId = crypto.randomUUID();
+      return {
+        events: [
+          {
+            raw,
+            event: {
+              type: "message",
+              eventId,
+              thread: { id: eventId, isDirectMessage: true },
+              actor: {
+                id: raw.email,
+                // The Host stamps the configured `channelKey`.
+                identity: { subject: raw.email }
+              },
+              message: { id: eventId, text: raw.message }
+            }
+          }
+        ],
+        response: Response.json({ accepted: true }, { status: 202 })
+      };
+    }
+  }
+};
+```
+
+Returning `null` declines the request so another Channel can claim it.
+
+## Durability contract
+
+Channels holds no state: no outbox, no retries, no deduplication, no scheduler.
+Durability is a property of how your application uses it. A caller-supplied
+`deliveryId` is correlation metadata, not an idempotency guarantee; an adapter
+may map it to a provider primitive when one exists.
+
+| Channels guarantees                                                     | Your application must                                                       |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| A `dispatchId` stable across redelivery and unaffected by routing       | Deduplicate on it before starting any side effect                           |
+| The Host awaits your callback before the provider is acknowledged       | Hand off durably before returning — a DO RPC, queue send, or workflow start |
+| One outbound attempt per `deliver()` or `stream()`, reported honestly   | Decide whether to retry; `uncertain` may duplicate a real delivery          |
+| Surfaces are plain JSON you can persist                                 | Keep configured channel keys stable                                         |
+| Decisions arrive as normalized events carrying your own `interactionId` | Own settlement; an interaction id is not an authorization credential        |
+
+## Future work
+
+- [ ] Approval-link ingress: signing, verification, and a confirmation page, so
+      link approvals return through the same normalized path as Slack buttons
+- [ ] Reader-initiated stream cancellation: Slack's `message_stream_stopped`
+      and Telegram's `stopped_message_generation` should reach the running
+      generation as ordinary ingress, so aborting it errors the stream and
+      each Channel finalizes on the path it already has
+- [ ] More built-in channels
+- [ ] Rendering templates (pretty emails)
+- [ ] Automatic webhook registration
+- [ ] Security review of approval flows
+- [ ] Conformance tests of adapters

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`:
@@ -590,17 +583,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.
-
-```typescript
-export class ChatAgent extends AIChatAgent {
-  override chatRecovery = true;
-}
-```
+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.
 
-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 +597,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 +644,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 = {