agents 0.23.0 → 0.25.0

package/docs/browse-the-web.md

@@ -105,7 +105,7 @@ async () => {
 };
 ```
 
-To discover protocol surface, the model calls `cdp.spec()` — the live, normalized CDP protocol description (domains with commands, events, and types) — or uses the runtime's built-in `codemode.search` / `codemode.describe`.
+To discover protocol surface, the model calls `cdp.spec()` — the live, normalized CDP protocol description (domains with commands, events, and types, including each command's parameters and return values) — or uses the runtime's built-in `codemode.search` / `codemode.describe`.
 
 ## Use with an Agent
 
@@ -205,6 +205,57 @@ await connector.sweep(); // reclaim expired/stale sessions — call from a sched
 await runtime.expirePaused(); // reject stale never-approved pauses, freeing their sessions
 ```
 
+## Persistent browser
+
+`browserTool` gives the model one browser that stays open between turns, so tabs, cookies, and logins carry over. You create the browser once on your agent and pass it in; the model never starts or closes it. This example uses a [Think](../think/index.md) agent, whose `getTools()` runs every turn:
+
+```ts
+import { Think } from "@cloudflare/think";
+import { Browser, browserRun } from "agents/browser";
+import { browserTool } from "agents/browser/ai-sdk";
+
+export class MyAgent extends Think<Env> {
+  browser = new Browser({ provider: browserRun(this.env.BROWSER) });
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.lifecycle.use(this.browser);
+  }
+
+  getModel() {
+    return "@cf/moonshotai/kimi-k2.7-code";
+  }
+
+  getTools() {
+    return {
+      browser: browserTool({ browser: this.browser, loader: this.env.LOADER })
+    };
+  }
+}
+```
+
+- The model writes CDP code as with `createBrowserTools`. `sessionId: "active"` points at the tab it's working in, and that tab is remembered across turns.
+- Tabs the page opens itself come back as `newTabs` in the result.
+- If the browser was lost (idle past `keepAliveMs`, closed, or crashed), the code still runs in a new browser and the result includes `restarted: true`.
+- Call `this.browser.liveView()` to give a person a Live View link into the same browser, and `this.browser.close()` to shut it down.
+- Set `keepAliveMs`, `recording`, and `guardrails` on `browserRun(binding, options)`. Use a different `name` for each extra browser on the same agent.
+
+Only Chromium on a Browser Run binding is supported. It needs the same `LOADER` binding and `CodemodeRuntime` export as `createBrowserTools`.
+
+For TanStack AI, import `browserTool` from `agents/browser/tanstack-ai` instead. It takes the same options plus an optional `name` (default `"browser"`) and returns a `ServerTool`:
+
+```ts
+import { browserTool } from "agents/browser/tanstack-ai";
+
+const stream = chat({
+  adapter,
+  tools: [browserTool({ browser: this.browser, loader: this.env.LOADER })],
+  messages
+});
+```
+
+The TanStack AI tool doesn't support screenshots yet. TanStack AI gives the host and the model the same output, so if the model returns a screenshot, the tool replaces it with a note saying it was left out, and the tool's instructions tell the model to read the page with `Runtime.evaluate` instead.
+
 ## Quick Actions (stateless browsing)
 
 `browser_execute` drives a full, stateful CDP session — the right tool for interactive, multi-step automation. But a lot of agent browsing is really one-shot: _read this page as Markdown_, _extract these fields_, _list the links_. For those, [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/) are simpler, faster, and cheaper. They need only the `browser` binding — no Durable Object, Worker Loader, or sandbox — so they work from any Worker.
@@ -404,12 +455,12 @@ Either `browser` or `cdpUrl` must be provided. When both are set, `cdpUrl` takes
 For custom integrations, import the building blocks directly:
 
 ```ts
-import { BrowserConnector, CdpSession, connectUrl } from "agents/browser";
+import { BrowserConnector, CdpConnection, connectUrl } from "agents/browser";
 
 // Connect to a custom CDP endpoint
-const session = await connectUrl("http://localhost:9222");
-const version = await session.send("Browser.getVersion");
-session.close();
+const connection = await connectUrl("http://localhost:9222");
+const version = await connection.send("Browser.getVersion");
+connection.close();
 
 // Or plug the connector into your own codemode runtime
 const connector = new BrowserConnector(this.ctx, {
@@ -419,6 +470,37 @@ const connector = new BrowserConnector(this.ctx, {
 });
 ```
 
+To load the normalized CDP protocol specification from Worker code, use `loadCdpSpec()`:
+
+```ts
+import { loadCdpSpec } from "agents/browser";
+
+const spec = await loadCdpSpec({
+  browser: this.env.BROWSER,
+  sessionId
+});
+```
+
+Pass a Browser Run binding in `browser` and the Browser Run session ID returned by `createBrowserSession()` in `sessionId`. If you omit `sessionId`, the helper creates a temporary session to fetch the specification, then deletes it. Pass an existing session ID to read the specification without creating another session. If you provide `cdpUrl`, the helper loads the specification from that URL instead; `cdpUrl` takes precedence over `browser` and `sessionId`.
+
+You can also manage Browser Rendering sessions directly. `createBrowserSession` accepts [hostname guardrails](https://developers.cloudflare.com/browser-run/features/guardrails/) that restrict which domains the session may reach — fixed at launch for every connection to the session, including Live View (not supported with Kitesurf):
+
+```ts
+import { createBrowserSession, connectBrowserSession } from "agents/browser";
+
+const { sessionId } = await createBrowserSession(this.env.BROWSER, {
+  guardrails: { allowedDomains: ["example.com", "*.example.com"] }
+});
+
+// Connect (and reconnect) without deleting the session on close:
+const session = await connectBrowserSession(this.env.BROWSER, sessionId, {
+  timeoutMs: 30_000,
+  onClose: () => {
+    /* the CDP socket closed; the session itself stays alive */
+  }
+});
+```
+
 ## Local development
 
 Recent Wrangler releases support Browser Rendering in local development. `npx wrangler dev` provisions the browser automatically, so the same `browser: env.BROWSER` setup works locally and when deployed.

package/docs/chat-agents.md

@@ -587,6 +587,8 @@ When a Durable Object is evicted mid-stream (code update, inactivity timeout, re
 
 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`.
 
+The same bounded recovery handles an `AIChatAgent` stream that fails while the agent stays up. If the response reader throws a platform transient error, such as `Network connection lost.`, the agent keeps the partial response and schedules a continuation instead of ending the turn with an error. If the error arrives before any response part, the agent re-runs the turn instead. The agent calls `onChatRecovery` first, so returning `{ continue: false }` ends the turn with the error. Each repeated transient error waits longer before the next attempt and counts against `maxAttempts`. Other reader errors still end the turn.
+
 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()`.
@@ -663,10 +665,10 @@ override chatRecovery = {
   // Primary stuck-turn bound. Resets on every progress-bearing attempt, so a
   // turn that keeps producing content survives unbounded interruption.
   noProgressTimeoutMs: 5 * 60 * 1000,
-  // Runaway-loop guard. Defaults to a finite backstop (1000). Set a different
-  // value to tune when a turn that keeps emitting content but never converges
-  // is sealed.
-  maxRecoveryWork: 200,
+  // Runaway-loop guard, counted in durable stream segments. Defaults to a
+  // finite backstop (10000). Set a different value to tune when a turn that
+  // keeps emitting content but never converges is sealed.
+  maxRecoveryWork: 2000,
   // Tight retry budget for a Durable Object memory-limit reset (the isolate
   // exceeded its 128 MB limit). Defaults to 3; an OOM usually re-OOMs on
   // re-run, so recovery seals it with `out_of_memory` after a few attempts.
@@ -693,23 +695,23 @@ override chatRecovery = {
 | `stableTimeoutMs`      | `10_000`          | How long a recovery attempt waits for the isolate to reach stable state before rescheduling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `terminalMessage`      | generic message   | The message shown to the user when recovery is given up on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `noProgressTimeoutMs`  | `300_000` (5 min) | Primary stuck-turn bound: how long an incident may go without forward progress before it is sealed (`no_progress_timeout`). **Resets on every progress-bearing attempt**, so a turn that keeps producing content survives unbounded interruption.                                                                                                                                                                                                                                                                                                                                                              |
-| `maxRecoveryWork`      | `1000`            | Runaway-loop guard. Maximum produced content/tool units since the incident began before a still-progressing turn is sealed (`work_budget_exceeded`). A generous finite backstop so an agent that keeps emitting a little content but never converges (for example an isolate that runs out of memory mid-stream on every recovery) cannot loop forever. Work only accrues from the first interruption until the turn completes. Set a higher value, or `Infinity`, for a very long agentic turn that legitimately needs more.                                                                                  |
+| `maxRecoveryWork`      | `10000`           | Runaway-loop guard. Maximum recovery work since the incident began before a still-progressing turn is sealed (`work_budget_exceeded`), counted in durable stream segments (see [Recovery work units](#recovery-work-units)). A generous finite backstop so an agent that keeps emitting a little content but never converges (for example an isolate that runs out of memory mid-stream on every recovery) cannot loop forever. Work only accrues from the first interruption until the turn completes. Set a higher value, or `Infinity`, for a very long agentic turn that legitimately needs more.          |
 | `maxOomRetries`        | `3`               | Tight retry budget for the specific case of a Durable Object isolate exceeding its memory limit and being reset mid-turn. An OOM is usually deterministic (the turn's working set no longer fits in 128 MB) so re-running re-OOMs, but a single OOM can be a transient spike — so recovery retries this many times before sealing with `out_of_memory`. Counts only attempts that ended in an OOM (not total attempts), so a turn interrupted by deploys is unaffected. Set `0` to seal on the first OOM. Far tighter than `maxRecoveryWork` because an OOM is attributable and each re-run re-runs the model. |
 | `shouldKeepRecovering` | —                 | Caller policy consulted from the second recovery attempt onward (never on the first detection, never once a hard bound has sealed the incident). Return `false` to stop recovery. The hook point for a token/cost budget — `ctx.work` is a coarse segment count, not tokens, so track real spend yourself.                                                                                                                                                                                                                                                                                                     |
 | `onExhausted`          | —                 | Called once when recovery is given up on, before the terminal message is delivered. Inspect `ctx.reason` for why.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 **`ChatRecoveryProgressContext`** (the `ctx` passed to `shouldKeepRecovering`):
 
-| Field                   | Type                    | Description                                                                                       |
-| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
-| `incidentId`            | `string`                | Stable ID for this recovery incident.                                                             |
-| `requestId`             | `string`                | Request ID for the current continuation (changes per chained continuation).                       |
-| `recoveryRootRequestId` | `string`                | Stable ID for the whole continuation chain — the right key for per-incident budget tracking.      |
-| `attempt`               | `number`                | Attempt number for this incident (2 or greater when this hook runs).                              |
-| `maxAttempts`           | `number`                | Configured attempt cap.                                                                           |
-| `recoveryKind`          | `"retry" \| "continue"` | Whether recovery retries an unanswered user turn or continues a partial assistant turn.           |
-| `work`                  | `number`                | Coarse, monotonic count of content/tool segments produced since the incident opened (not tokens). |
-| `ageMs`                 | `number`                | Wall-clock ms since the incident's first interruption.                                            |
+| Field                   | Type                    | Description                                                                                  |
+| ----------------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
+| `incidentId`            | `string`                | Stable ID for this recovery incident.                                                        |
+| `requestId`             | `string`                | Request ID for the current continuation (changes per chained continuation).                  |
+| `recoveryRootRequestId` | `string`                | Stable ID for the whole continuation chain — the right key for per-incident budget tracking. |
+| `attempt`               | `number`                | Attempt number for this incident (2 or greater when this hook runs).                         |
+| `maxAttempts`           | `number`                | Configured attempt cap.                                                                      |
+| `recoveryKind`          | `"retry" \| "continue"` | Whether recovery retries an unanswered user turn or continues a partial assistant turn.      |
+| `work`                  | `number`                | Monotonic count of durable stream segments produced since the incident opened (not tokens).  |
+| `ageMs`                 | `number`                | Wall-clock ms since the incident's first interruption.                                       |
 
 A progressing turn survives unbounded interruption (for example a dense deploy window) as long as it keeps making forward progress and stays under the `maxRecoveryWork` backstop. Recovery is sealed only by one of these `ctx.reason` values:
 
@@ -720,7 +722,19 @@ A progressing turn survives unbounded interruption (for example a dense deploy w
 - `recovery_aborted` — your `shouldKeepRecovering` hook returned `false`.
 - `stable_timeout` — recovery attempts kept timing out waiting for stable state until the budget drained (extreme churn).
 
-> `maxRecoveryWork` defaults to a generous finite backstop (`1000`) rather than no cap, so a runaway turn cannot loop forever out of the box. The default is far above what a healthy interrupted turn produces; if you lower it, pick a cap well above a healthy turn's output, and for a precise budget prefer `shouldKeepRecovering` with real token/cost accounting. A very long agentic turn that legitimately produces a large amount of content under heavy interruption can raise the cap or set it to `Infinity` to restore fully-unbounded recovery.
+> `maxRecoveryWork` defaults to a generous finite backstop (`10000`) rather than no cap, so a runaway turn cannot loop forever out of the box. The default is far above what a healthy interrupted turn produces; if you lower it, pick a cap well above a healthy turn's output, and for a precise budget prefer `shouldKeepRecovering` with real token/cost accounting. A very long agentic turn that legitimately produces a large amount of content under heavy interruption can raise the cap or set it to `Infinity` to restore fully-unbounded recovery.
+
+#### Recovery work units
+
+`maxRecoveryWork` and `ctx.work` count **durable stream segments**, not tokens, messages, or chunks. One unit is one of:
+
+- a flushed segment of the turn's stream log, which holds roughly ten packed streaming chunks;
+- a settled tool result, which is flushed as its own segment;
+- an explicit progress credit for output forwarded from a sub-agent.
+
+The unit is only meaningful relative to another `ctx.work` reading, so to choose a cap, log `ctx.work` from `shouldKeepRecovering` for a healthy interrupted turn and set `maxRecoveryWork` well above it.
+
+> **Upgrading an explicit `maxRecoveryWork`?** Releases before `agents@0.23.0` (`@cloudflare/ai-chat@0.12.0`, `@cloudflare/think@0.18.0`) counted "credited chunks" (one per tool call, one per text or reasoning segment start, and one per five seconds of streamed deltas), and the default was `1000`. The unit changed to durable segments and the default moved to `10000`. An explicit value is not recalibrated automatically, and there is no fixed conversion factor between the two units: a delta-heavy turn produces far more segments than it used to produce credits, while a turn dominated by tool calls changes much less. Measure `ctx.work` for your own turns before carrying an old value forward.
 
 > **Out-of-memory crash loops have a last-resort backstop.** A severe memory-limit reset can bypass the recovery budgets above entirely — for example if the Durable Object out-of-memories while _loading its state on wake_, before recovery even evaluates, or if the budget's own bookkeeping writes also out-of-memory. Left unhandled, the platform auto-retries the alarm forever, re-running the doomed (billable) turn each cycle. The SDK guards this at the alarm boundary: after `maxAlarmMemoryLimitStrikes` (a base `Agent` static option, default `3`) consecutive alarms end in a memory-limit reset, it seals the interrupted turn with `out_of_memory` and stops the loop, emitting an `alarm:memory_limit_reset` observability event. This bounds the blast radius (and the bill); it does not shrink the working set — a turn whose context genuinely no longer fits in 128 MB needs a smaller transcript/fewer or smaller tool results.
 
@@ -885,6 +899,7 @@ function Chat() {
 | ----------------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agent`                       | `ReturnType<typeof useAgent>`                   | Required | Agent connection from `useAgent`                                                                                                                                                   |
 | `onToolCall`                  | `({ toolCall, addToolOutput }) => void`         | —        | Handle client-side tool execution                                                                                                                                                  |
+| `onTurnEnd`                   | `(event: ChatTurnEndEvent) => void`             | —        | Called once for each chat request that ends, with its `messageIds` and `outcome`. See [Settle sends when a turn ends](#settle-sends-when-a-turn-ends)                              |
 | `autoContinueAfterToolResult` | `boolean`                                       | `true`   | Auto-continue conversation after client tool results and approvals                                                                                                                 |
 | `resume`                      | `boolean`                                       | `true`   | Enable automatic stream resumption on reconnect                                                                                                                                    |
 | `cancelOnClientAbort`         | `boolean`                                       | `false`  | Cancel the server turn when generic client stream abort/cleanup occurs. Explicit `stop()` always cancels the server turn                                                           |
@@ -909,6 +924,47 @@ function Chat() {
 | `isStreaming`             | `boolean`                          | `true` when any stream is active (client or server-initiated)                                                                                                                                                                                 |
 | `isRecovering`            | `boolean`                          | `true` while a durable turn is being recovered (interrupted and resuming). Distinct from `isStreaming` — a recovering turn is not producing tokens yet. Render a "recovering…" hint; most UIs treat `isStreaming \|\| isRecovering` as "busy" |
 
+### Settle sends when a turn ends
+
+An application that renders a send as pending before the server answers needs
+to know when that exact send is finished. `onTurnEnd` is called once for each
+chat request that ends, with the ids of the user messages it carried and how it
+ended:
+
+```tsx
+const chat = useAgentChat({
+  agent,
+  onTurnEnd: ({ messageIds, outcome, error }) => {
+    if (!messageIds) return;
+    for (const id of messageIds) {
+      settlePendingSend(id, outcome, error);
+    }
+  }
+});
+```
+
+The event has these fields:
+
+- `requestId`: the transport id of the request.
+- `messageIds`: the ids of the user messages the request ended with. These are
+  the ids the client minted when it sent them. Absent when the request did not
+  end with a user message.
+- `outcome`: `"completed"`, `"error"`, `"aborted"` (cancelled while it ran), or
+  `"skipped"` (it never ran, because a newer send superseded it or the
+  `messageConcurrency` policy dropped it).
+- `error`: the error message, when `outcome` is `"error"`.
+- `replay`: `true` when the outcome was replayed on reconnect rather than seen
+  live.
+
+`onTurnEnd` also fires for requests from other tabs and for outcomes replayed
+after a reconnect, so match `messageIds` against the sends this client is
+tracking. It does not fire when recovery continues a turn under a new request;
+the new request reports the same `messageIds` when it ends.
+
+A message id can appear in more than one event. With the `latest` or `merge`
+policies, a skipped send can still be answered by the turn that superseded it,
+which lists that id again. Treat the last event for an id as its outcome.
+
 ## Tools
 
 `AIChatAgent` supports three tool patterns, all using the AI SDK's `tool()` function:
@@ -989,6 +1045,8 @@ const { messages, sendMessage } = useAgentChat({
 
 When the LLM invokes `getLocation`, the stream pauses. The `onToolCall` callback fires, your code provides the output, and the conversation continues.
 
+`onToolCall` fires once the response stream ends, for each tool call that is still waiting for a result. A server tool runs and resolves in the same stream, so it never reaches `onToolCall`.
+
 ### Dynamic Client Tools (SDK/Platform Pattern)
 
 For SDKs and platforms where tools are defined dynamically by the embedding application at runtime, use the `tools` option on `useAgentChat` and `createToolsFromClientSchemas()` on the server:
@@ -1300,6 +1358,18 @@ For more details, see [Resumable Streaming](./resumable-streaming.md).
 
 ## Storage Management
 
+### Reconcile tool calls across transcript updates
+
+When a client resubmits a transcript, `AIChatAgent` reconciles assistant messages
+against server state before persisting them. This keeps tool results attached to
+the right turn when a provider reuses a `toolCallId`.
+
+Custom chat hosts that reconcile transcripts can use `reconcileMessages()` from
+`agents/chat`. It matches messages against server rows one-to-one and checks the
+tool name and input as well as the call ID. The older
+`resolveToolMergeId()` helper is deprecated because its conversation-wide
+lookup can match the wrong turn when call IDs repeat.
+
 ### Row Size Protection
 
 SQLite rows have a maximum size of 2 MB. When a message approaches this limit (for example, a tool returning a very large output), `AIChatAgent` automatically compacts the message:
@@ -1673,6 +1743,44 @@ The chat protocol uses typed JSON messages over WebSocket:
 | `CF_AGENT_STREAM_RESUMING`       | Server → Client | Notify of stream resumption |
 | `CF_AGENT_STREAM_RESUME_REQUEST` | Client → Server | Request stream resume check |
 
+#### Correlate terminal frames with sent messages
+
+A `CF_AGENT_USE_CHAT_RESPONSE` frame names its request by `id`. Terminal frames
+(`done: true` or `error: true`) also carry `messageIds`: the ids of the user
+messages at the end of the request's `messages`. One send carries one id, and
+queued sends that arrive together carry several. This applies to completion,
+errors before or during the stream, skipped and cancelled requests, and
+terminals replayed on reconnect.
+
+The final `done` frame of a request can also carry `outcome`: `"completed"`,
+`"error"`, `"aborted"`, `"skipped"`, or `"recovering"`. When it is absent, the
+request errored if that frame or an earlier frame for the request carried
+`error: true`, and completed otherwise. `"recovering"` means the request
+stopped but recovery continues the same turn under a new request, which reports
+the same `messageIds` when it ends.
+
+React applications should use [`onTurnEnd`](#settle-sends-when-a-turn-ends),
+which applies these rules for you. Without React, read the frames directly:
+
+```ts
+const erroredRequests = new Set<string>();
+
+agent.addEventListener("message", (event) => {
+  const frame = JSON.parse(event.data);
+  if (frame.type !== "cf_agent_use_chat_response") return;
+  if (frame.error) erroredRequests.add(frame.id);
+  if (!frame.done) return;
+  const errored = erroredRequests.delete(frame.id);
+  const outcome = frame.outcome ?? (errored ? "error" : "completed");
+  if (outcome !== "recovering" && frame.messageIds) {
+    settlePendingSends(frame.messageIds, outcome);
+  }
+});
+```
+
+`messageIds` is absent when the request did not end with a user message, or
+when the server no longer has a record of the request.
+
 ## Examples
 
 - [AI Chat Example](https://github.com/cloudflare/agents/tree/main/examples/ai-chat) — Modern example with server tools, client tools, and approval

package/docs/client-sdk.md

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

package/docs/context.md

@@ -96,6 +96,31 @@ const system = await context.freezeSystemPrompt();
 
 `refreshSystemPrompt()` reloads every provider, re-renders, and overwrites the stored prompt.
 
+### Reminders for changing blocks
+
+Some blocks go stale while the prompt is frozen: the current date, workspace state, project instructions. Refreshing the prompt keeps them current but throws away the cached prefix. Mark such a block `whenChanged: "remind"` to keep both:
+
+```ts
+const context = new ContextBlocks([
+  {
+    label: "environment",
+    provider: {
+      get: async () => `Today is ${new Date().toISOString().slice(0, 10)}.`
+    },
+    whenChanged: "remind"
+  }
+]);
+
+const system = await context.freezeSystemPrompt();
+const reminder = await context.reminder(); // null until the date changes
+```
+
+`reminder()` re-reads each such block and, for every one whose current rendering no longer appears in the frozen prompt, returns its current value under a short note saying it replaces the prompt's copy. Send that text after the cached prefix, for example at the end of the latest user message, and do not persist it. The frozen prompt does not change, and the reminder keeps coming back on every call until `refreshSystemPrompt()` promotes the value into the prompt. That refresh is the one deliberate cache bust.
+
+The comparison is against the stored prompt, not against in-memory state, so a reminder survives a restart. A remind block always has a section in the prompt, even when it is empty, so the model knows it exists and a later value has a copy to replace. Any difference in what the provider returns counts as a change, so return only what should count: a date rather than a timestamp.
+
+A standing reminder still costs a little cache: it moves to each new user message, so the previous user message falls out of the cached prefix. The system prompt and everything before that message stay cached.
+
 ## Tools
 
 `tools()` returns an AI SDK `ToolSet` wired from what the blocks can do:
@@ -126,6 +151,8 @@ A block declared without a provider is auto-wired to durable per-agent SQLite. T
 
 The assembled blocks are available as `this.context` after `onStart()`.
 
+Think sends reminders itself. Each turn it calls `reminder()` and adds the result to the last user message of the model request, or, when the request continues a partial reply, to the user message that asks the model to continue (`TurnContext.messages` in `beforeTurn` already includes it). Nothing is written to the transcript. Think refreshes the prompt after a compaction, which promotes any pending values.
+
 ## Related
 
 - [Sessions](./sessions.md) - durable message trees, streamed history, compaction, and attachment offload

package/docs/durable-execution.md

@@ -345,6 +345,7 @@ runFiber("work", fn)
   _checkRunFibers():
   ├─ SELECT * FROM cf_agents_runs
   ├─ For each orphaned row:
+  │    ├─ Body already finished (only its cleanup failed) → DELETE, no hook
   │    ├─ Parse snapshot from JSON
   │    ├─ Call onFiberRecovered(ctx)
   │    └─ DELETE the row after successful recovery
@@ -461,6 +462,7 @@ Key points:
 
 - **The original lambda is gone.** On recovery, you only have the `name` and `snapshot`. The lambda cannot be serialized — recovery logic must be in the hook.
 - **The row is deleted after the hook returns successfully.** If you want to continue the work, call `runFiber()` again inside the hook — this creates a new row.
+- **The hook is meant for interrupted work.** If the function returned or threw and only the row delete failed, the fiber records that it finished, and the next scan deletes the row without calling the hook. This is best-effort: if recording the finish also fails, the row looks interrupted and the hook runs anyway, so keep recovery idempotent.
 - **You control what recovery means.** Retry from the beginning, resume from a checkpoint, skip and notify the user, or do nothing. The framework does not impose a strategy.
 - **If the hook throws, the row is kept (up to a bound).** A later startup or alarm scan will try recovery again, which protects against transient storage or scheduling failures. Catch application-level errors yourself when you want to mark the work terminal instead of retrying. A hook that always throws is retried on a backing-off schedule (the recovery alarm uses an exponential delay capped at 5 minutes, so it is not a busy-loop) until the row exceeds `fiberRecoveryMaxAgeMs` (default 24h), after which it is discarded with a `fiber:recovery:skipped` (`reason: "max_age_exceeded"`) event. Setting `fiberRecoveryMaxAgeMs: 0` retains such rows indefinitely — recovery keeps retrying on the capped backoff, and the Durable Object never idle-evicts while an un-recoverable row exists, so prefer a finite age unless you intend to inspect or clear those rows yourself.
 

package/docs/harnesses/pi.md

@@ -0,0 +1,91 @@
+---
+title: Pi harness (Experimental)
+pcx_content_type: get-started
+description: Host pi-durable sessions in a Durable Object with the experimental PiHarness lifecycle capability. Connect a pi-ai model and keep sessions active across eviction.
+---
+
+`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It connects pi's SQLite-backed sessions to the Agents SDK lifecycle, which wakes active sessions after eviction. The API is experimental and may change.
+
+`PiHarness` does not provide a chat protocol or user interface. Your application chooses how clients reach sessions, such as through WebSockets, HTTP, or RPC. The harness exposes pi sessions and their event streams for your application to adapt.
+
+## Install the pi packages
+
+Install `agents` with pi-durable and pi-ai:
+
+```sh
+npm install agents @earendil-works/pi-durable @earendil-works/pi-ai
+```
+
+Both pi packages are optional peer dependencies of `agents`. The example below uses Workers AI through the `AI` binding. To configure the binding and choose other models, refer to [Models for pi-ai](../models-pi-ai.md).
+
+## Create the harness
+
+Open pi's `Harness` with the storage and background context that `PiHarness` provides. Register the pi-ai provider on a `Models` registry, then attach the capability to the object's lifecycle:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { createModels } from "@earendil-works/pi-ai/models";
+import { createRegistry, Harness } from "@earendil-works/pi-durable";
+import { PiHarness } from "agents/harnesses/pi";
+import { Lifecycle } from "agents/lifecycle";
+import { CLOUDFLARE_PROVIDER_ID, createAI } from "agents/models/pi-ai";
+
+export class Assistant extends DurableObject<Env> {
+  readonly ai = createAI({ binding: this.env.AI });
+  readonly registry = createRegistry();
+
+  readonly harness = new PiHarness({
+    harness: ({ storage, context }) => {
+      const models = createModels();
+      models.setProvider(this.ai.provider);
+      return Harness.open(
+        storage,
+        { models, registry: this.registry },
+        context
+      );
+    },
+    defaults: {
+      model: {
+        provider: CLOUDFLARE_PROVIDER_ID,
+        modelId: "@cf/zai-org/glm-4.7-flash"
+      }
+    }
+  });
+
+  readonly lifecycle = Lifecycle.install(this).use(this.harness);
+
+  async prompt(input: string) {
+    return this.harness.prompt(input);
+  }
+}
+```
+
+The `harness` factory receives a pi storage adapter backed by the Durable Object's SQLite database. It also receives a background context for opening pi. Configure pi's models, registry, and other `Harness.open` options in this factory.
+
+`defaults` applies when the harness creates a new session. You can change an individual session's model with `session.setModel()`. Without a model, the session cannot produce an answer until one is set.
+
+## Work with sessions
+
+The root session is available through `harness.prompt()` and `harness.submit()`. Create additional sessions with `harness.sessions.create()`, then use the returned session handle:
+
+```ts
+const session = await this.harness.sessions.create();
+const receipt = await session.submit("Summarize the latest report", {
+  operationId: "report-summary-42"
+});
+const result = await session.wait(receipt.operationId);
+```
+
+`submit()` returns after pi durably accepts the operation. `wait()` returns its result after pi finishes it. Reusing an `operationId` makes a submission idempotent. Set `whenBusy: "steer"` to join the running work after its current tool round; the default queues a follow-up.
+
+Use `session.events()` to read pi's snapshot and committed event batches. Your application can stream those events to clients and build its own view. `session.messages()` returns pi's transcript entries, not a UI-ready chat transcript.
+
+## How recovery works
+
+The harness schedules one lifecycle job for each session with active work. The job waits for pi's tasks, refreshes its wake while they remain active, and completes when they settle. If the Durable Object is evicted, the due job wakes it again; pi reopens its stored state and resumes the session's work.
+
+Pi owns the transcript, operation inbox, generation, tools, retries, and recovery. `PiHarness` supplies durable storage and wake scheduling. It does not move pi's orchestration into the Agents SDK.
+
+## Run the example
+
+The [Pi harness example](https://github.com/cloudflare/agents/tree/main/examples/next/harnesses/pi) connects `session.events()` to WebSockets and projects pi's entries into a browser transcript. It also demonstrates a replay-safe tool and model configuration with Workers AI.

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

@@ -361,6 +361,10 @@ A Durable Object can be evicted at any time (a deploy, an inactivity timeout, a
 
 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.
 
+### Repair an approved tool that never ran
+
+An approval can be recorded even if its tool continuation never starts. When a later user turn moves past that approval, `AIChatAgent` and Think repair the transcript so the model does not receive an unresolved tool call. An approved tool that never ran becomes an error result, and a denied tool becomes a denied result. An approval in the current final message is left for the AI SDK to execute.
+
 ## Client-Side Tool Execution with `onToolCall`
 
 For tools that need browser APIs (geolocation, camera, clipboard) or user interaction, define the tool on the server without an `execute` function and handle it on the client with `onToolCall`:

package/docs/index.md

@@ -63,7 +63,7 @@ The differentiator is not "we have durable state" — it is what happens when a
 
 ## Background Processing
 
-- [Queue](./queue.md) - Immediate background task execution
+- [Queue](./queue.md) - Durable background task execution
 - [Scheduling](./scheduling.md) - Delayed, scheduled, and cron-based tasks
 - [Retries](./retries.md) - Automatic retries with exponential backoff and jitter
 - [Durable Execution](./durable-execution.md) - `runFiber()`, `startFiber()`, `stash()`, and crash recovery for long tasks
@@ -79,6 +79,9 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Agent Tools](./agent-tools.md) - Run chat-capable sub-agents as tools with streaming child timelines
 - [Server-Driven Messages](./server-driven-messages.md) - Autonomous agent workflows: scheduled follow-ups, queue processing, webhooks, chained reasoning
 - TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
+- [Models (Experimental)](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
+- [Models for pi-ai (Experimental)](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
+- [Pi harness (Experimental)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
 - TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
 - [Sessions (Experimental)](./sessions.md) - Durable message trees, streamed history, compaction, search, and lossless attachment offload
 - [Context (Experimental)](./context.md) - System-prompt blocks, frozen prompts, writable/searchable/loadable providers, and their tools