agents 0.24.0 → 0.26.0

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/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,173 @@
+---
+title: Pi harness (Beta)
+pcx_content_type: get-started
+description: Host pi-durable sessions in a Durable Object with the beta PiHarness lifecycle capability. Connect a pi-ai model, add tools and skills, and keep sessions running across eviction.
+---
+
+`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It opens Pi over the object's SQLite database and connects Pi's sessions to the Agents SDK lifecycle, which wakes sessions with work after eviction. The API is in beta and may change.
+
+Pi owns everything about a run: the transcript, the inbox of steers and follow-ups, generation, tool calls, retries, and crash recovery. `PiHarness` supplies the storage and the wake. It does not provide a chat protocol or user interface. Your application chooses how clients reach sessions, such as WebSockets, HTTP, or RPC.
+
+## Install the Pi packages
+
+```sh
+npm install agents @earendil-works/pi-durable @earendil-works/pi-ai
+```
+
+Both Pi packages are optional peer dependencies of `agents`, at `^1.0.0`. The examples use 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
+
+`PiHarness` uses a factory function to construct Pi's `Harness` so it can be instantiated lazily:
+
+```ts
+import { createModels } from "@earendil-works/pi-ai/models";
+import { createRegistry, Harness } from "@earendil-works/pi-durable";
+import { Agent } from "agents";
+import { PiHarness } from "agents/harness/pi";
+import { createAI } from "agents/models/pi-ai";
+
+export class Assistant extends Agent<Env> {
+  ai = createAI({ binding: this.env.AI });
+  registry = createRegistry();
+
+  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: this.ai("@cf/zai-org/glm-4.7-flash"),
+      thinkingLevel: "low"
+    }
+  });
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.lifecycle.use(this.harness);
+  }
+
+  async ask(prompt: string) {
+    return (await this.harness.prompt(prompt)).text;
+  }
+}
+```
+
+| Option     | What it is                                                                                                                                                                              |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `harness`  | Required. Receives `{ storage, context }` and returns Pi's `Harness`, usually from `Harness.open`. Models, the registry, `settings`, `env` and `onReport` are all yours to build here.  |
+| `defaults` | What a new session starts with: `model`, a pi-ai `Model` such as `ai("@cf/…")`, and `thinkingLevel`. Without a model, a session's prompts end unanswered (`no_model`) until one is set. |
+
+The factory runs as part of startup, once per isolate. If it throws the operation that triggered it fails and the next operation tries again.
+
+A model in `defaults` or `session.setModel()` is stored by its provider and id only. Pi resolves it at each request against the `Models` the factory opened Pi with, so it must be a model those `Models` list. Options passed to `ai(id, options)` there, such as `fallback`, are not applied.
+
+## Add tools and prompt sections
+
+Tools and system prompt sections are Pi extensions. An extension is a plain object with a `name`, `tools` and `sections`:
+
+```ts
+import { Type } from "@earendil-works/pi-ai";
+import {
+  createRegistry,
+  type ToolRegistration
+} from "@earendil-works/pi-durable";
+
+const WordCount = Type.Object({ text: Type.String() });
+
+const wordCount: ToolRegistration<typeof WordCount> = {
+  name: "word_count",
+  description: "Count the words in a text.",
+  parameters: WordCount,
+  // Pi may run it again after an eviction interrupted it.
+  replay: "safe",
+  // `text` is typed from `parameters` and is validated by Pi.
+  async execute({ text }) {
+    const words = text.split(/\s+/).filter(Boolean).length;
+    return { content: [{ type: "text", text: String(words) }] };
+  }
+};
+
+const registry = createRegistry();
+registry.install({
+  name: "writing",
+  sections: [
+    { key: "preamble", render: () => "You are an editor.", tag: false }
+  ],
+  tools: [wordCount]
+});
+```
+
+- **Tool arguments are typed from the schema.** Type a tool as `ToolRegistration<typeof Parameters>`; a bare `ToolRegistration` types its arguments as `unknown`.
+- **Replay safety.** `replay: "safe"` lets Pi run a call again after an eviction cut it off. Otherwise the model gets an interrupted result instead of a second run. The default is `"unsafe"`.
+- **What a running call can use.** `execute(args, api, context)` gets Pi's operations for the call: `api.output()` for running output, `api.details()` for a UI, and `api.memo()` for values that survive an eviction. `context.abortSignal` is aborted when the call is.
+- **Sections.** A section's `render` runs before each request, with the conversation, its agent and offered tools, and committed reads. It is wrapped in `<key>` tags unless `tag` is `false`.
+
+Pi's extensions can do more: hooks on model requests and tool calls (`hook(ToolTask, { beforeTool })`), durable tasks, wrapping another extension's tools, and choosing extensions per conversation. Refer to the [pi-durable README](https://github.com/earendil-works/pi/tree/main/packages/durable) for each. They all work on the registry `PiHarness` opens Pi with.
+
+### Skills
+
+`skills(sources)` turns `agents/skills` sources (refer to [Agent Skills](../../think/index.md#agent-skills)) into a Pi extension named `agents.skills`. It has two tools, `activate_skill` and `read_skill_resource`, and a `skills` section that lists the skills. Install it in the factory, since it reads the sources:
+
+```ts
+import { skills } from "agents/harness/pi";
+
+harness: async ({ storage, context }) => {
+  this.registry.install(await skills(sources));
+  return Harness.open(storage, { models, registry: this.registry }, context);
+};
+```
+
+The existing `@cloudflare/think` skills work out-of-the-box.
+
+## Work with sessions
+
+A session is a Pi conversation. Each has its own transcript, inbox, model and run, and they can run at the same time.
+
+```ts
+// The root session.
+const { text } = await this.harness.prompt("What is 47 × 19?");
+
+// Another session, on a cheaper model.
+const session = await this.harness.sessions.create();
+await session.setModel(this.ai("@cf/zai-org/glm-4.7-flash"));
+
+// Durable once it returns; the same operation id twice is one submission.
+const receipt = await session.submit("Summarize the latest report", {
+  operationId: "report-summary-42"
+});
+const result = await session.wait(receipt.operationId);
+```
+
+| Call                                       | What it does                                                                                                                                                                             |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt(input)`                            | Submits and waits: the answer, and the transcript after it.                                                                                                                              |
+| `submit(input, { operationId, whenBusy })` | Returns once Pi has durably accepted the input, before the model runs. A busy session queues it as a follow-up; `whenBusy: "steer"` joins the running work after its current tool round. |
+| `wait(operationId, signal?)`               | The operation's result once Pi settles it. Aborting `signal` stops only the wait, not the work.                                                                                          |
+| `steer(input)`                             | `submit` with `whenBusy: "steer"`.                                                                                                                                                       |
+| `abort(operationId?)`                      | Withdraws a queued operation, or with no id, stops everything running in the session.                                                                                                    |
+| `pending()`                                | Operations Pi has not settled yet: queued, or part of the running work.                                                                                                                  |
+| `messages()`                               | Pi's transcript entries since the newest reset.                                                                                                                                          |
+| `events()`                                 | Pi's agent events: a `snapshot`, then one batch per commit.                                                                                                                              |
+| `reset(handoff?)`                          | Starts a new context, optionally from a handoff note.                                                                                                                                    |
+| `setModel(model)`                          | Changes this session's model.                                                                                                                                                            |
+| `busy()`                                   | Whether a run is going.                                                                                                                                                                  |
+
+`harness.prompt()`, `submit()`, `wait()`, `abort()`, `messages()` and `pending()` act on the root session, or on `{ session }`. `harness.sessions` has `create()`, `fork(from)`, `get(id)` and `list()`, which includes sessions subagents created. `ROOT_SESSION` is the root's id.
+
+`messages()` and `events()` are Pi's own records, not a UI-ready chat transcript. The example below folds them into one.
+
+## How recovery works
+
+The harness schedules one lifecycle job per session with work. The job waits on Pi's tasks, refreshes itself as a heartbeat while they run, and completes when they settle. If the object is evicted or crashes, the job is still due, so its alarm restarts the object. Pi reopens its stored state and resumes the session's work: a replay-safe tool call runs again, and an unsafe one is reported to the model as interrupted.
+
+Every operation waits for the object's startup, which runs the factory. A call over RPC that arrives first waits for it rather than opening Pi on its own.
+
+## Run the example
+
+The [Pi harness example](https://github.com/cloudflare/agents/tree/main/examples/next/harnesses/pi) streams `session.events()` over WebSockets and folds Pi's entries into a browser transcript. Its tools come from a `Workspace` from `@cloudflare/computer`: files, `exec` for JavaScript in a Dynamic Worker, and git. It uses a Workers AI model.

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

@@ -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 (Beta)](./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 (Beta)](./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

package/docs/lifecycle.md

@@ -341,13 +341,17 @@ The capability speaks the Agent protocol on every connection, so a plain
 Durable Object is reachable from `useAgent` and `AgentClient` exactly like an
 `Agent`:
 
-- On connect it sends the identity frame, which resolves the client's
-  `ready` and `identified`, then the current state when `state` is set.
+- On connect it sends the identity frame, then the current state when
+  `state` is set. The identity frame says when a state frame follows it,
+  so the client's `ready` and `identified` wait for that state, and a
+  caller awaiting `ready` never reads the default value.
   `protocol` controls this: `true` (default) for every connection, a
   function to decide per connection — `false` marks it no-protocol, so it
   gets no protocol text frames on connect or by broadcast but still sends
   and receives ordinary messages and callables — or `false` to have the
-  host drive the sequence itself with `sendIdentity()` and `sendState()`.
+  host drive the sequence itself with `sendConnectFrames()`, or
+  `sendIdentity()` and `sendState()` separately (the client then resolves
+  `ready` on the identity alone).
   `Agent` passes `false`, because it must decide whether a connection
   belongs to a facet before any frame is sent.
 - `readonly` decides per connection whether state writes over the wire are
@@ -429,7 +433,19 @@ async runTask(): Promise<void> {
 }
 ```
 
-Agent's internal RPC entry points already enforce this boundary.
+An `Agent` enforces this boundary for you. Its internal RPC entry points and
+the public `async` methods your subclass exposes over RPC start the lifecycle
+before they run, so a cold instance does not serve those calls against
+uninitialized state. Synchronous methods are never deferred; if one reads state
+that `onStart` sets up, make it `async` or call `await this.lifecycle.start()`
+in it. Concurrent calls to `start()` share the same startup operation, and
+`lifecycle.isStarted()` returns `true` only after capabilities and `onStart()`
+have finished.
+
+Startup resolves the Durable Object name. An async RPC to an Agent addressed
+with `newUniqueId()` or `idFromString()` fails instead of running before
+initialization. Address the Agent by name with `getAgentByName()`, `getByName()`,
+or `idFromName()`.
 
 ## Object names