agents 0.21.0 → 0.23.0

package/docs/mcp-client.md

@@ -13,6 +13,61 @@ The MCP client capability lets your agent:
 
 > **Note:** This page covers connecting to MCP servers as a client. To create your own MCP server, see [Creating MCP Servers](./mcp-servers.md).
 
+## Compose the MCP client with a Durable Object
+
+`MCPClientManager` is a lifecycle capability. A class can extend the platform
+`DurableObject` directly and install the manager without extending `Agent`:
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { MCPClientManager } from "agents/mcp/client";
+
+export class MyObject extends DurableObject<Env> {
+  readonly mcp = new MCPClientManager("my-object", "1.0.0");
+
+  readonly lifecycle = Lifecycle.install(this).use(this.mcp);
+
+  onRequest() {
+    return Response.json({ tools: this.mcp.listTools() });
+  }
+}
+```
+
+The lifecycle calls the manager automatically:
+
+- `onStart()` initializes its schema and restores persisted connections before
+  the host handles work.
+- `onRequest()` intercepts registered OAuth callback URLs before the host's
+  request handler.
+
+Do not call these hooks manually. For a native Durable Object RPC method,
+which bypasses `fetch`, call `await this.lifecycle.start()` before using the
+manager. Explicit cleanup remains available through `mcp.dispose()`; Durable
+Objects do not provide an eviction callback.
+
+The manager does not require a particular OAuth callback route. Pass the exact
+callback URL to `registerServer()` and route that request to the same named
+Durable Object. The manager persists the URL and only intercepts a callback
+whose origin and pathname match it.
+
+An HTTP-only manager does not need `env`. Pass the Durable Object environment
+when the catalog can contain RPC servers so persisted binding names can be
+resolved after a wake:
+
+```ts
+readonly mcp = new MCPClientManager("my-object", "1.0.0", {
+  env: this.env
+});
+```
+
+If an RPC row exists without `env`, startup logs a warning identifying the
+server and does not recreate that connection.
+
+`Agent` installs this same capability object directly. Existing `this.mcp`,
+`addMcpServer()`, `removeMcpServer()`, and `getMcpServers()` APIs remain
+available.
+
 ## Quick Start
 
 Install the exact MCP client peer used by this Agents release:

package/docs/mcp-servers.md

@@ -78,7 +78,11 @@ createMcpHandler(() => createServer(), {
 });
 ```
 
-All upstream SDK v2 handler options pass through. Use `createLegacyMcpHandler` for WorkerTransport, storage, session, and event-store options.
+`createMcpHandler` supports upstream SDK v2 handler options except `bus`, which is not exposed by the Agents SDK. Supplying `bus` throws a `TypeError`.
+
+To publish change events, use the returned handler's `notify` methods, such as `handler.notify.toolsChanged()`. Create the handler once at module scope and reuse it for requests and notifications. Notifications are isolate-local: they do not reach subscriptions in other Worker isolates. See the [handler notification API](https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/#publish-list-and-resource-changes) for the available methods.
+
+Use `createLegacyMcpHandler` for SDK v1 WorkerTransport, storage, session, and event-store options. The SDK v2 `bus` option is not available on that handler either.
 
 The handler validates every present `Origin` header before serving the request. It rejects malformed, opaque, and non-HTTP origins. Requests without `Origin` remain valid for non-browser MCP clients.
 

package/docs/observability.md

@@ -158,17 +158,17 @@ These events are emitted by `AIChatAgent` from `@cloudflare/ai-chat`. They track
 
 ### Chat recovery events
 
-| Type                      | Payload                                                                  | When                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `chat:request:failed`     | `{ requestId?, stage, messagesPersisted?, error }`                       | A Think chat request fails while parsing, persisting, running, or streaming                                                                                                                                                                                                                                                               |
-| `chat:recovery:detected`  | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | An interrupted chat fiber is first observed                                                                                                                                                                                                                                                                                               |
-| `chat:recovery:attempt`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | The framework begins a recovery attempt                                                                                                                                                                                                                                                                                                   |
-| `chat:recovery:scheduled` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | A retry or continuation callback is scheduled                                                                                                                                                                                                                                                                                             |
-| `chat:recovery:completed` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | Recovery completed successfully                                                                                                                                                                                                                                                                                                           |
-| `chat:recovery:skipped`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery was skipped because the conversation changed or was no longer recoverable                                                                                                                                                                                                                                                        |
-| `chat:recovery:failed`    | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery ran but failed                                                                                                                                                                                                                                                                                                                   |
-| `chat:recovery:exhausted` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason }`  | Recovery exceeded its configured attempt budget                                                                                                                                                                                                                                                                                           |
-| `chat:stream:stalled`     | `{ requestId, timeoutMs }`                                               | The inactivity watchdog fired — no stream chunk arrived within `chatStreamStallTimeoutMs`. With `chatRecovery` on (the default) the turn then routes into bounded recovery (look for `chat:recovery:*`); with recovery off it terminalizes. See [Think configuration](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) |
+| Type                      | Payload                                                                  | When                                                                                                                                                                                                                                                             |
+| ------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chat:request:failed`     | `{ requestId?, stage, messagesPersisted?, error }`                       | A Think chat request fails while parsing, persisting, running, or streaming                                                                                                                                                                                      |
+| `chat:recovery:detected`  | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | An interrupted chat fiber is first observed                                                                                                                                                                                                                      |
+| `chat:recovery:attempt`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | The framework begins a recovery attempt                                                                                                                                                                                                                          |
+| `chat:recovery:scheduled` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | A retry or continuation callback is scheduled                                                                                                                                                                                                                    |
+| `chat:recovery:completed` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind }`          | Recovery completed successfully                                                                                                                                                                                                                                  |
+| `chat:recovery:skipped`   | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery was skipped because the conversation changed or was no longer recoverable                                                                                                                                                                               |
+| `chat:recovery:failed`    | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason? }` | Recovery ran but failed                                                                                                                                                                                                                                          |
+| `chat:recovery:exhausted` | `{ incidentId, requestId, attempt, maxAttempts, recoveryKind, reason }`  | Recovery exceeded its configured attempt budget                                                                                                                                                                                                                  |
+| `chat:stream:stalled`     | `{ requestId, timeoutMs }`                                               | The inactivity watchdog fired — no stream chunk arrived within `chatStreamStallTimeoutMs`. The turn then routes into bounded recovery; look for `chat:recovery:*`. See [Think configuration](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) |
 
 `recoveryKind` is `"retry"` when recovery replays an unanswered user turn and `"continue"` when it continues a partial assistant turn.
 

package/docs/resumable-streaming.md

@@ -2,7 +2,7 @@
 
 The `AIChatAgent` class provides **automatic resumable streaming** out of the box. When a client disconnects and reconnects during an active stream, the response automatically resumes from where it left off.
 
-This is client reconnect recovery, not Durable Object eviction recovery. If the Worker process or Durable Object is evicted while the model call is in flight, enable `chatRecovery` so the turn runs inside a recoverable fiber. `Think` enables `chatRecovery` by default; plain `AIChatAgent` subclasses opt in with `override chatRecovery = true`.
+This is client reconnect recovery, not Durable Object eviction recovery. Durable Object eviction recovery is also always enabled for `AIChatAgent` and `Think`: every turn runs inside a recoverable fiber. Use `chatRecovery` only to tune its budgets and terminal behavior.
 
 ## How It Works
 
@@ -70,7 +70,7 @@ function Chat() {
 - Chunks are batched (every 10 chunks) and flushed to SQLite for performance
 - When a client sends `CF_AGENT_STREAM_RESUME_REQUEST`, the server checks for active streams and responds with `CF_AGENT_STREAM_RESUMING`
 - Stale streams (older than 5 minutes) are cleaned up on restore
-- Stream buffers are garbage collected from a scheduled alarm: completed or errored streams are retained for 10 minutes (a brief reconnect-and-replay grace; the assistant message itself is persisted separately), and abandoned in-flight streams are retained for 1 hour after their last chunk before being reclaimed
+- Stream buffers are deleted in the same transaction that persists the assistant message (the cutover), so a finished turn leaves nothing behind and no cleanup alarm is armed. A buffer a crash left behind is reclaimed when the next stream starts: finished streams immediately, abandoned in-flight streams after 1 hour without a chunk (recovery has until then to rebuild the message from it)
 
 ### Client-side (`useAgentChat`)
 

package/docs/routing.md

@@ -601,6 +601,94 @@ Each agent is accessed via its own path:
 
 ---
 
+## Routing to independent Agents
+
+A hub Agent often owns an open-ended set of independent peers: one Durable Object per chat, document, or session for a user. `RoutedAgents` from `agents/routing` codifies that topology as a Lifecycle capability. The hub keeps a durable catalog of public IDs mapped to opaque physical names, and forwards requests under one route segment to the selected Agent:
+
+```typescript
+import { Agent, callable, routeAgentRequest } from "agents";
+import { RoutedAgents } from "agents/routing";
+
+export class ChatAgent extends Agent<Env> {
+  // An ordinary top-level Agent: its own storage, alarms, and placement.
+}
+
+export class UserAgent extends Agent<Env> {
+  readonly chats = new RoutedAgents<ChatAgent, { title: string }>({
+    namespace: this.env.ChatAgent,
+    route: "chats"
+  });
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.lifecycle.use(this.chats);
+  }
+
+  @callable()
+  createChat(title: string) {
+    return this.chats.create({ metadata: { title } });
+  }
+
+  @callable()
+  listChats() {
+    return this.chats.list();
+  }
+
+  @callable()
+  deleteChat(id: string) {
+    return this.chats.delete(id);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Routes both /agents/user-agent/{id} and the forwarded
+    // /agents/user-agent/{id}/chats/{id}/... paths — RoutedAgents claims
+    // the latter from inside UserAgent once the request reaches it.
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+The client keeps one connection to the hub and one to the active chat, both addressed through the hub:
+
+```
+/agents/user-agent/alice                    -> UserAgent "alice"
+/agents/user-agent/alice/chats/{id}         -> the ChatAgent behind that entry
+/agents/user-agent/alice/chats/{id}/...     -> same ChatAgent, suffix preserved
+```
+
+```tsx
+const user = useAgent({ agent: "UserAgent", name: "alice" });
+const chat = useAgent({
+  agent: "ChatAgent",
+  basePath: `agents/user-agent/alice/chats/${encodeURIComponent(chatId)}`
+});
+```
+
+What the capability guarantees:
+
+- `create()`, `list()`, and `setMetadata()` touch only the hub's SQLite. No target wakes.
+- `list()` orders most-recently-updated first, ties broken by write order rather than by the random entry ID. Each write scans the route's own entries to derive that order — an intentional trade for a route sized like one owner's own catalog, not a route meant to hold thousands of entries.
+- `get(id)` returns an initialized, typed stub for RPC, or `null` for an unknown or deleted ID.
+- A WebSocket upgrade is answered by the target, which then owns the socket. Chat frames never wake the hub. This is the same two-socket shape as connecting to the chat directly, but the hub stays the authority that resolves an ID, so it can gate, migrate, or redirect entries later.
+- `delete(id)` hides the entry first, condemns the target, then removes the row. The target wipes its own storage on its next wake, moments later, and the condemned marker survives interruption. A failed call leaves a hidden row, and calling `delete` again retries.
+- Physical names are random UUIDs that never leave the hub. Clients only ever see entry IDs.
+- `namespace` is any `DurableObjectNamespace`, including a binding to a class exported by another Worker via `script_name`, so the hub and its targets can be deployed and scaled independently.
+- Destroying the hub retries condemning every remaining entry before its own storage is wiped, but this is best-effort: the platform wipes the hub's storage right after disposal regardless of outcome, so a target that is still unreachable after retries is orphaned, with no catalog row left to retry from later.
+
+The catalog stores existence, ownership, and application metadata. Conversation data stays in the target, and a target that needs its hub calls back with `getAgentByName(this.env.UserAgent, ownerName)`. When to prefer this over facets is covered in [Dynamic agents](./sub-agents.md#when-to-use-dynamic-agents).
+
+Two sharp edges to design around:
+
+- **Pick a route that can't collide.** Forwarding matches every occurrence of the route segment anywhere in the path, so if the hub's own name, class, or another one of its own routes is also literally `"chats"`, a coincidental match with no active entry behind it returns `404` instead of reaching the hub's own handler for that path.
+- **A routed suffix can't address a target's own dynamic agents.** `Agent.fetch()` resolves a `/sub/{class}/{name}` marker against the _hub's_ exported classes before this capability's request handling ever runs, so `/chats/{id}/sub/{class}/{name}` is served as a facet of the hub, not forwarded to the chat. Reach a target's dynamic agents through a direct connection to that target instead of through the hub's route.
+
+---
+
 ## Routing with Authentication
 
 Check authentication before routing to agents:
@@ -737,6 +825,23 @@ Get an agent instance by name for server-side RPC or request forwarding.
 
 **Returns:** `Promise<DurableObjectStub<T>>` - Typed stub for calling agent methods or forwarding requests
 
+### `new RoutedAgents(options)` (from `agents/routing`)
+
+A Lifecycle capability installed on a hub Agent with `this.lifecycle.use(...)`. See [Routing to independent Agents](#routing-to-independent-agents).
+
+| Parameter           | Type                        | Description                                      |
+| ------------------- | --------------------------- | ------------------------------------------------ |
+| `options.namespace` | `DurableObjectNamespace<T>` | Target binding the entries are created in        |
+| `options.route`     | `string`                    | One URL-safe path segment this capability claims |
+
+| Method                      | Returns                                              | Description                                           |
+| --------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| `create(options?)`          | `Promise<RoutedAgentEntry<Metadata>>`                | Create an entry without waking the target             |
+| `get(id)`                   | `Promise<DurableObjectStub<T> \| null>`              | Resolve an active entry to an initialized stub        |
+| `list()`                    | `Promise<ReadonlyArray<RoutedAgentEntry<Metadata>>>` | Active entries, most recently updated first           |
+| `setMetadata(id, metadata)` | `Promise<boolean>`                                   | Replace an active entry's metadata                    |
+| `delete(id)`                | `Promise<boolean>`                                   | Hide the entry, condemn the target, then drop the row |
+
 ### `useAgent(options)` / `AgentClient` Options
 
 Client connection options:

package/docs/scheduling.md

@@ -15,6 +15,91 @@ The scheduling system supports four modes:
 
 Under the hood, scheduling uses [Durable Object alarms](https://developers.cloudflare.com/durable-objects/api/alarms/) to wake the agent at the right time. Tasks are stored in a SQLite table and executed in order.
 
+## Scheduler Lifecycle primitive
+
+> **Experimental.** The `Scheduler` primitive and the `agents/lifecycle`
+> surface it builds on may change between releases. Agent's established
+> scheduling methods (`this.schedule()` and friends) are stable.
+
+`Scheduler` is a reusable Lifecycle capability. A plain Lifecycle Object can
+install it without extending `Agent`:
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+import { Lifecycle } from "agents/lifecycle";
+import { Scheduler, type Schedule } from "agents/schedules";
+
+export class ReminderObject extends DurableObject<Env> {
+  readonly scheduler = new Scheduler({
+    callbacks: {
+      sendReminder: (
+        payload: { message: string },
+        schedule: Schedule<{ message: string }>
+      ) => {
+        console.log(schedule.id, payload.message);
+      }
+    }
+  });
+
+  readonly lifecycle = Lifecycle.install(this).use(this.scheduler);
+
+  async createReminder(message: string): Promise<string> {
+    const schedule = await this.scheduler.set(300, "sendReminder", {
+      message
+    });
+    return schedule.id;
+  }
+}
+```
+
+Lifecycle owns the physical Durable Object alarm. Scheduler contributes its
+earliest pending task or hung-interval recheck. Lifecycle selects the earliest
+contribution from Scheduler, other capabilities, and the host, then rearms after
+every alarm phase. A future Fiber or MCP capability can contribute its own wake
+time without storing work in Scheduler or depending on it.
+
+Scheduler's primary API is small: callbacks are registered by name in the
+constructor, `set()` and `every()` create schedules typed against that
+registration, and `get()`, `list()`, and `cancel()` manage them. All of these
+are asynchronous and work inside routed sub-agents.
+
+Scheduler Lifecycle hooks run without ambient host context. Registered
+callbacks are user code, so they run inside the host invocation context with
+the Lifecycle Object available through `getCurrentAgent()`.
+
+## Using Scheduler through Agent
+
+Every `Agent` constructs and installs the same primitive at `this.scheduler`.
+Existing Agent applications continue to use the established methods:
+
+- `this.schedule()` and `this.scheduleEvery()` create schedules.
+- `this.getScheduleById()` and `this.listSchedules()` read schedules.
+- `this.cancelSchedule()` removes a schedule.
+
+These methods delegate to `this.scheduler`; no setup or migration is required.
+Agent registers no callbacks map — a composition-root resolver keeps
+`this.schedule(60, "methodName")` dispatching to Agent methods. Agent passes
+only policy options (retry defaults, hung-interval timeout, error routing) and
+adapts Lifecycle's event sink, facet transport, and host invocation boundary
+at its composition root — there is no Agent-specific Scheduler adapter. Scheduler contributes its next wake time to the same Lifecycle alarm
+selection as Agent keep-alive, fibers, sub-agent work, and deferred
+destruction.
+
+Import `Scheduler` and runtime schedule types from the dependency-light entry
+point:
+
+```typescript
+import {
+  Scheduler,
+  type Schedule,
+  type ScheduleCriteria
+} from "agents/schedules";
+```
+
+Natural-language parsing helpers use Zod and live under
+`agents/schedules/parser`. The previous `agents/schedule` path remains as a
+deprecated compatibility alias.
+
 ## Quick Start
 
 ```typescript
@@ -299,9 +384,9 @@ This is the recommended approach since you cannot forget to dispose the heartbea
 
 ### How it works
 
-`keepAlive()` uses an in-memory reference count and the Durable Object alarm system directly. Each call increments the count; the disposer decrements it. While the count is above zero, `_scheduleNextAlarm()` ensures an alarm fires every 30 seconds, which resets the inactivity timer. No schedule rows are created and no observability events are emitted — the heartbeat is invisible to `listSchedules()` and the `agents:schedule` diagnostics channel.
+`keepAlive()` uses an in-memory reference count. Each call increments the count; the disposer decrements it. While the count is above zero, Agent contributes a wake time every 30 seconds to Lifecycle. No schedule rows are created and no observability events are emitted, so the heartbeat is invisible to `listSchedules()` and the scheduling diagnostics channel.
 
-The heartbeat does not conflict with your own schedules — the alarm system multiplexes all schedules and the keepAlive heartbeat through a single alarm slot.
+The heartbeat does not conflict with scheduled work. Lifecycle selects one physical alarm from both contributions.
 
 Inside sub-agents, `keepAlive()` delegates that heartbeat ref to the top-level parent because facets do not have independent alarm slots. `keepAliveWhile()` works the same way because it calls `keepAlive()` and automatically disposes the delegated ref when the scoped work completes.
 
@@ -642,14 +727,14 @@ class TimezoneAgent extends Agent {
 
 ## AI-Assisted Scheduling
 
-The SDK includes utilities for parsing natural language scheduling requests with AI.
+The SDK includes utilities for parsing natural language scheduling requests with AI. Import them from `agents/schedules/parser`.
 
 ### getSchedulePrompt()
 
 Returns a system prompt for parsing natural language into scheduling parameters:
 
 ```typescript
-import { getSchedulePrompt, scheduleSchema } from "agents";
+import { getSchedulePrompt, scheduleSchema } from "agents/schedules/parser";
 import { generateObject } from "ai";
 import { openai } from "@ai-sdk/openai";
 
@@ -703,7 +788,7 @@ class SmartScheduler extends Agent {
 A Zod schema for validating parsed scheduling data:
 
 ```typescript
-import { scheduleSchema } from "agents";
+import { scheduleSchema } from "agents/schedules/parser";
 
 // The schema uses a discriminated union on `when.type`:
 // {
@@ -751,7 +836,81 @@ When using this schema with OpenAI models via the AI SDK, you must pass `provide
 
 ## API Reference
 
-### schedule()
+Two surfaces share these semantics: the experimental `Scheduler` primitive
+(`agents/schedules`, methods on the scheduler instance) and the stable `Agent`
+methods (on the Agent class, delegating to `this.scheduler`).
+
+### Scheduler primitive
+
+#### `new Scheduler(options?)`
+
+```typescript
+new Scheduler({
+  callbacks?,
+  retry?,
+  hungScheduleTimeoutSeconds?,
+  onError?
+});
+```
+
+- `callbacks` registers scheduled callbacks by name. `set()` and `every()`
+  type both the name and the payload against this map, and dispatch runs the
+  registered function — the typed scheduling surface and the runtime dispatch
+  target are the same object.
+- Lifecycle supplies storage, readiness, startup state, alarm coordination,
+  the host invocation boundary, events, and routing.
+- `retry` supplies callback retry defaults. The defaults are three attempts,
+  100 ms base delay, and 3,000 ms maximum delay.
+- `hungScheduleTimeoutSeconds` defaults to 30 seconds.
+- `onError` observes terminal callback failures outside ambient host context.
+
+Install the constructed object with `Lifecycle.use()` before use. Scheduler
+starts Lifecycle automatically when its asynchronous API is entered. It
+publishes `schedule:*` events through Lifecycle's best-effort event bus. A plain
+Lifecycle Object writes them to the existing `agents:schedule` diagnostics
+channel; `Agent` sends them through its existing observability implementation.
+
+#### set()
+
+```typescript
+async set(when, callback, payload?, options?): Promise<Schedule<Payload>>
+```
+
+Create a one-shot or cron schedule. `when`, `options`, idempotency, and return
+value follow [`schedule()`](#schedule) below. `callback` must be a name
+registered in the constructor's `callbacks` map, and `payload` is typed
+against that callback's first parameter.
+
+#### every()
+
+```typescript
+async every(intervalSeconds, callback, payload?, options?): Promise<Schedule<Payload>>
+```
+
+Create a fixed-interval schedule. Semantics follow
+[`scheduleEvery()`](#scheduleevery) below, and `every()` also accepts
+`options.idempotent` to opt out of interval dedup.
+
+#### get() / list() / cancel()
+
+```typescript
+async get(id): Promise<Schedule<unknown> | undefined>
+async list(criteria?): Promise<Schedule<unknown>[]>
+async cancel(id): Promise<boolean>
+```
+
+Read and cancel schedules — the primitive's equivalents of
+[`getScheduleById()`](#getschedulebyid), [`listSchedules()`](#listschedules),
+and [`cancelSchedule()`](#cancelschedule) below. (Internal synchronous
+variants on the Scheduler back Agent's deprecated `getSchedule()` and
+`getSchedules()`; they are not part of the primitive's contract.)
+
+### Agent methods
+
+Methods on the `Agent` class, delegating to `this.scheduler`. Callback names
+resolve to methods on the Agent.
+
+#### schedule()
 
 ```typescript
 async schedule<T = string>(
@@ -789,7 +948,7 @@ class MyAgent extends Agent {
 }
 ```
 
-### scheduleEvery()
+#### scheduleEvery()
 
 ```typescript
 async scheduleEvery<T = string>(
@@ -800,7 +959,8 @@ async scheduleEvery<T = string>(
 ): Promise<Schedule<T>>
 ```
 
-Schedule a task to run repeatedly at a fixed interval.
+Schedule a task to run repeatedly at a fixed interval. Idempotent by design
+(the primitive's `every()` accepts `options.idempotent` to opt out).
 
 **Parameters:**
 
@@ -819,7 +979,7 @@ Schedule a task to run repeatedly at a fixed interval.
 - If callback throws an error, the interval continues
 - Cancel with `cancelSchedule(id)` to stop the entire interval
 
-### getScheduleById()
+#### getScheduleById()
 
 ```typescript
 async getScheduleById(id: string): Promise<Schedule<unknown> | undefined>
@@ -827,7 +987,7 @@ async getScheduleById(id: string): Promise<Schedule<unknown> | undefined>
 
 Get a scheduled task by ID. This method works in both top-level agents and sub-agents.
 
-### listSchedules()
+#### listSchedules()
 
 ```typescript
 async listSchedules(criteria?: {
@@ -839,7 +999,7 @@ async listSchedules(criteria?: {
 
 Get scheduled tasks matching the criteria. This method works in both top-level agents and sub-agents.
 
-### getSchedule()
+#### getSchedule()
 
 ```typescript
 getSchedule<T = string>(id: string): Schedule<T> | undefined
@@ -847,7 +1007,7 @@ getSchedule<T = string>(id: string): Schedule<T> | undefined
 
 Deprecated. Get a scheduled task by ID synchronously. This method only works in top-level agents; use `await this.getScheduleById(id)` instead.
 
-### getSchedules()
+#### getSchedules()
 
 ```typescript
 getSchedules<T = string>(criteria?: {
@@ -859,7 +1019,7 @@ getSchedules<T = string>(criteria?: {
 
 Deprecated. Get scheduled tasks matching the criteria synchronously. This method only works in top-level agents; use `await this.listSchedules(criteria)` instead.
 
-### cancelSchedule()
+#### cancelSchedule()
 
 ```typescript
 async cancelSchedule(id: string): Promise<boolean>
@@ -867,7 +1027,7 @@ async cancelSchedule(id: string): Promise<boolean>
 
 Cancel a scheduled task. Returns `true` if cancelled, `false` if not found.
 
-### keepAlive()
+#### keepAlive()
 
 ```typescript
 async keepAlive(): Promise<() => void>
@@ -877,7 +1037,7 @@ Create an alarm-backed heartbeat that prevents the Durable Object from being evi
 
 See [Keeping the Agent Alive](#keeping-the-agent-alive) for usage details.
 
-### keepAliveWhile()
+#### keepAliveWhile()
 
 ```typescript
 async keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>

package/docs/server-driven-messages.md

@@ -457,7 +457,7 @@ Pre-aborted signals short-circuit before any model work runs.
 ### Limitations
 
 - **Signals cannot cross Durable Object boundaries.** `AbortSignal` is not an RPC-serializable type. Construct the controller inside the DO that calls `saveMessages`. For Think child-agent orchestration, use [Agent Tools](./agent-tools.md); `runAgentTool()` bridges parent aborts into the child run. For lower-level custom RPC, return a `ReadableStream` from the child and let the parent cancel it — workerd propagates the cancel back to the source's `cancel` callback.
-- **Hibernation drops the listener.** The signal lives in memory. If the DO hibernates mid-turn and `chatRecovery` is enabled, the recovered turn usually calls `continueLastTurn()` internally without the original signal — an abort fired after restart has no effect on the recovered turn. For pre-stream interruptions, recovery can instead retry the latest unanswered user message automatically. This is true for top-level agents and sub-agents; sub-agent recovery still works, but the original caller's in-memory signal is gone. Override `onChatRecovery` (Think) or set `chatRecovery = false` for callers that need stronger guarantees.
+- **Hibernation drops the listener.** The signal lives in memory. After the DO restarts, durable recovery usually calls `continueLastTurn()` without the original signal, so an abort fired after restart has no effect. For pre-stream interruptions, recovery can instead retry the latest unanswered user message automatically. This is true for top-level agents and sub-agents. If cancellation must survive restart, persist the cancellation intent in agent state or SQL, check it in `onChatRecovery()`, and return `{ continue: false }`. Durable recovery cannot be disabled.
 
 This is the integration point for agent-tool orchestration where the parent's AI SDK abort signal needs to propagate into a child DO's `saveMessages` call. See [`cloudflare/agents#1406`](https://github.com/cloudflare/agents/issues/1406) for the original use case.