agents 0.28.1 → 0.29.0

package/docs/chat-agents.md

@@ -652,7 +652,7 @@ Durable bookkeeping stays enabled even when automatic continuation is not approp
 
 - **Retries or side effects are unsafe:** override `onChatRecovery()` and return `{ continue: false }`. Persist idempotency keys or completion records before external side effects so a recovered turn can tell whether work already happened.
 - **Cancellation must survive eviction:** an `AbortSignal` only cancels the current in-memory turn. Also persist cancellation intent in agent state or SQL, read it in `onChatRecovery()`, and return `{ continue: false }` when cancellation was requested.
-- **Cost must be bounded:** set `maxAttempts`, `noProgressTimeoutMs`, `maxRecoveryWork`, and `maxOomRetries`. Use `shouldKeepRecovering` with durable spend data to stop later attempts. The predicate is not bound to the agent instance, so read spend from a store keyed by `ctx.recoveryRootRequestId`.
+- **Cost must be bounded:** set `maxAttempts`, `noProgressTimeoutMs`, `maxRecoveryWork`, and `maxInterruptedAttempts`. Use `shouldKeepRecovering` with durable spend data to stop later attempts. The predicate is not bound to the agent instance, so read spend from a store keyed by `ctx.recoveryRootRequestId`.
 - **A provider can resume without a new model call:** use `this.stash()` to save its response ID, retrieve that response in `onChatRecovery()`, and return `{ persist: false, continue: false }`.
 
 `chatRecovery` can be configured with budgets and terminal behavior:
@@ -669,10 +669,10 @@ override chatRecovery = {
   // 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.
-  maxOomRetries: 3,
+  // How many of one turn's attempts may die before recovery gives up, for
+  // example to a memory-limit reset on every run. Defaults to 5, counting
+  // the original turn.
+  maxInterruptedAttempts: 5,
   // Caller policy consulted from the second recovery attempt onward. Return
   // false to stop recovery. This is where you enforce a token/cost budget.
   // Note: this is called as `config.shouldKeepRecovering(ctx)`, so it is not
@@ -689,16 +689,16 @@ override chatRecovery = {
 
 **`chatRecovery` configuration:**
 
-| Field                  | Default           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ---------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `maxAttempts`          | `10`              | Attempt cap before terminal exhaustion. Resets on forward progress, so it catches a tight no-progress alarm loop, not a healthy long turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `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`      | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Field                    | Default           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `maxAttempts`            | `10`              | Attempt cap before terminal exhaustion. Resets on forward progress, so it catches a tight no-progress alarm loop, not a healthy long turn.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `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`        | `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.                                                                                                                                                                                                                                                              |
+| `maxInterruptedAttempts` | `5`               | How many of one turn's attempts may be interrupted before recovery gives up (`interrupted_attempts_exceeded`). An attempt is interrupted when its isolate dies before it finishes: a Durable Object memory-limit reset, a deploy, or any other reset. The original turn counts, so the default runs the model at most five times for a turn that dies every time. The count is taken when the next isolate picks the turn up, before it re-runs anything, because an isolate killed by a memory-limit reset cannot record anything. Progress never resets it. A memory-limit reset and a deploy look the same from the next isolate, so a turn interrupted by five deploys in a row is also sealed. Values below `1` are read as `1`; `Infinity` disables the bound. Replaces `maxOomRetries`, which is still read as `maxInterruptedAttempts: maxOomRetries + 1`. |
+| `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`):
 
@@ -713,12 +713,13 @@ override chatRecovery = {
 | `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:
+A progressing turn survives repeated interruption (for example a dense deploy window) as long as it keeps making forward progress, stays under the `maxRecoveryWork` backstop, and fewer than `maxInterruptedAttempts` of its attempts die. Recovery is sealed only by one of these `ctx.reason` values:
 
 - `no_progress_timeout` — no forward progress within the no-progress window (a stuck turn).
 - `max_attempts_exceeded` — the attempt cap was spent on a tight no-progress alarm loop.
 - `work_budget_exceeded` — the turn kept producing content but exceeded `maxRecoveryWork` (a runaway loop).
-- `out_of_memory` — recovery attempts kept hitting a Durable Object memory-limit reset until the tight `maxOomRetries` budget drained.
+- `interrupted_attempts_exceeded` — the turn's attempts kept dying before they finished (for example a memory-limit reset on every run) until `maxInterruptedAttempts` of them had been interrupted.
+- `out_of_memory` — the alarm memory-limit circuit breaker sealed the recovery after repeated memory-limit resets.
 - `recovery_aborted` — your `shouldKeepRecovering` hook returned `false`.
 - `stable_timeout` — recovery attempts kept timing out waiting for stable state until the budget drained (extreme churn).
 
@@ -736,7 +737,7 @@ The unit is only meaningful relative to another `ctx.work` reading, so to choose
 
 > **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.
+> **Out-of-memory crash loops.** A turn that exceeds the Durable Object's 128 MB limit on every run is bounded by `maxInterruptedAttempts`: each run that dies is counted when the next isolate picks the turn up, before it re-runs anything, and the fifth seals the turn with `interrupted_attempts_exceeded`. The isolate that hit the limit cannot record anything itself, because every storage call after the reset fails. The alarm boundary also catches memory-limit resets so the platform does not retry the alarm in a tight loop, and emits an `alarm:memory_limit_reset` observability event. Its strike counter (`maxAlarmMemoryLimitStrikes`, a base `Agent` static option, default `3`) only advances while storage still accepts writes, for example when the reset came from another isolate such as D1. None of this shrinks the working set: a turn whose context no longer fits in 128 MB needs a smaller transcript or fewer or smaller tool results.
 
 #### Turns waiting on a human are not sealed
 

package/docs/harnesses/pi.md

@@ -14,7 +14,7 @@ Pi owns everything about a run: the transcript, the inbox of steers and follow-u
 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).
+Both Pi packages are optional peer dependencies of `agents`, at `~1.3.0`. pi-durable is experimental, and its API can change in minor releases, so `agents` supports one Pi minor at a time. 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
 
@@ -27,6 +27,9 @@ import { Agent } from "agents";
 import { PiHarness } from "agents/harness/pi";
 import { createAI } from "agents/models/pi-ai";
 
+// Skip Pi's idle caches (refer to the note below).
+const settings = { contextRetentionMs: 0, documentRetentionMs: 0 };
+
 export class Assistant extends Agent<Env> {
   ai = createAI({ binding: this.env.AI });
   registry = createRegistry();
@@ -37,7 +40,7 @@ export class Assistant extends Agent<Env> {
       models.setProvider(this.ai.provider);
       return Harness.open(
         storage,
-        { models, registry: this.registry },
+        { models, registry: this.registry, settings },
         context
       );
     },
@@ -63,6 +66,8 @@ export class Assistant extends Agent<Env> {
 | `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. |
 
+Set Pi's `contextRetentionMs` and `documentRetentionMs` settings to `0`. Pi keeps idle caches behind timers that default to ten minutes, and a pending timer keeps a Durable Object in memory: it cannot hibernate or be evicted, and it is billed for that time. The object's SQLite is local, so the caches save little.
+
 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.
@@ -89,7 +94,7 @@ const wordCount: ToolRegistration<typeof WordCount> = {
   // `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) }] };
+    return { output: [{ type: "text", text: String(words) }] };
   }
 };
 
@@ -119,7 +124,11 @@ 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);
+  return Harness.open(
+    storage,
+    { models, registry: this.registry, settings },
+    context
+  );
 };
 ```
 
@@ -142,7 +151,11 @@ harness: async ({ storage, context }) => {
       browserTool({ ctx: this.ctx, browser: this.browser, loader: this.env.LOADER })
     ]
   });
-  return Harness.open(storage, { models, registry: this.registry }, context);
+  return Harness.open(
+    storage,
+    { models, registry: this.registry, settings },
+    context
+  );
 };
 
 readonly lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
@@ -169,24 +182,40 @@ const receipt = await session.submit("Summarize the latest report", {
 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.                                                                                                                                                                  |
+| Call                                              | What it does                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `prompt(input)`                                   | Submits and waits: the answer, and the transcript after it.                                                                                                                                                                                                                                                                          |
+| `submit(input, { operationId, whenBusy, entry })` | Hands the input to Pi and returns as soon as Pi has saved it, without waiting for the model. If the session is already working, the input waits until that work finishes. With `whenBusy: "steer"`, it joins the running work instead, after the current round of tool calls. `entry` records where the input came from (see below). |
+| `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.
 
+### Label input the user did not type
+
+Pi records every submitted input as a `pi.user` entry, as if the user typed it. Your code often submits input of its own, such as a prompt from a scheduled job, a webhook payload or the outcome of an approval. To record where that input came from, pass `entry` with a `kind` of your own and any `data` you want to keep with it:
+
+```ts
+await session.submit("The deploy was approved. Run the migration.", {
+  entry: { kind: "app.approval", data: { approved: true, by: "ben" } }
+});
+```
+
+The model sees no difference: it still gets the text as a user message. Only the transcript changes. The input is stored with your `kind` and `data` instead of `pi.user`, and `messages()` and `events()` return both, so your UI can show it differently, for example as "Approved by ben" rather than as something the user said. Pi reserves kinds that start with `pi.`, so use a prefix of your own, such as `app.`.
+
+The kind is a label, not a permission. It records what your code said the input was, and nothing checks it. The model reads the input as if the user wrote it, so do not put anything in it that you would not let the user send.
+
+The example app folds the transcript into chat messages, ignores `kind` and `data`, and shows every input as a user message. To show labelled input differently, read them from the entry.
+
 ## 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.

package/docs/models-pi-ai.md

@@ -43,8 +43,10 @@ design: a model this package cannot name exactly is yours to construct.
    created on first use.
 3. **No provider keys.** AI Gateway holds the credential — unified billing, or a key you
    store on the gateway (BYOK) — so nothing vendor-shaped needs a secret in your Worker.
-4. **The binding is the only way in.** Workers AI goes through `env.AI.run`, vendor models
-   through `env.AI.gateway(id).run`; there is no HTTP transport and no API token to hold.
+4. **The binding, or an account id and token.** Workers AI and catalog models go through
+   `env.AI.run`, other model objects through the binding's `fetch` to AI Gateway's
+   provider-native path. With [an account id and API token](#account-id-and-api-token) the
+   same requests go over HTTP instead.
 5. Everything here is in beta and may change in a minor release.
 
 ## Quick start
@@ -77,6 +79,26 @@ export default {
 };
 ```
 
+### Account id and API token
+
+To use a gateway in another account, or to call from outside a Worker, pass `accountId` and
+`apiToken` instead of `binding`. Everything else is the same, and the gateway still defaults to
+`default`:
+
+```ts
+const ai = createAI({
+  accountId: "27b146402af2103944379f33841b6234",
+  apiToken: env.CLOUDFLARE_API_TOKEN,
+  gateway: "project-gateway"
+});
+```
+
+Workers AI and catalog models go to AI Gateway's
+[REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/), which runs them on
+`/run` as `env.AI.run` does. Other model objects go to the provider-native path on
+`gateway.ai.cloudflare.com`, with the token as `cf-aig-authorization`. Create the token with
+**Workers AI Read** and **AI Gateway Run**; it is sent to those two hosts only.
+
 ## Where a model comes from
 
 ```ts
@@ -179,7 +201,7 @@ ai("anthropic/claude-opus-4.8", {
   eventId: "turn-17",
   requestTimeoutMs: 30_000,
   retries: { maxAttempts: 3, backoff: "exponential", retryDelayMs: 500 },
-  zdr: true, // Zero Data Retention, routed models on unified billing
+  byokAlias: "team-a", // which stored BYOK key, by alias
   fallback: ["@cf/zai-org/glm-4.7-flash"], // ids or models, in any mix
   headers: { "x-request-source": "docs" },
   sessionAffinity: "chat-42", // Workers AI prefix-cache routing
@@ -211,20 +233,29 @@ then model, then `createAI` settings.
 
 ## How a request travels
 
-| Model                    | `api`                | Transport                                 |
-| ------------------------ | -------------------- | ----------------------------------------- |
-| `@cf/…`                  | `cloudflare-ai`      | `env.AI.run` + Cloudflare's compat layer  |
-| Anthropic (any registry) | `anthropic-messages` | gateway universal → `v1/messages`         |
-| OpenAI (any registry)    | `openai-responses`   | gateway universal → `v1/responses`        |
-| Groq, DeepSeek, xAI, …   | `openai-completions` | gateway universal → `v1/chat/completions` |
-
-Everything that is not `@cf/` goes through **AI Gateway's universal request**: the vendor's
-own body, built by pi-ai's own converter, posted to the gateway with the provider slug taken
-from the model's `baseUrl` host. The gateway forwards it to the vendor with the credential it
-holds, and streams the vendor's own SSE back untouched — pi-ai's stream processors parse it,
-as they would if you had called the vendor directly, the thinking knobs aside (below). No
-credential header leaves your Worker, and the model's `api`, `provider` and `id` are never
-rewritten, so thinking signatures and encrypted reasoning items replay on the next turn.
+| Model                                   | `api`                | Through the binding                                       | With an account id and token                           |
+| --------------------------------------- | -------------------- | --------------------------------------------------------- | ------------------------------------------------------ |
+| `@cf/…`, `dynamic/…`                    | `cloudflare-ai`      | `env.AI.run` + Cloudflare's compat layer                  | the REST API + Cloudflare's compat layer               |
+| `anthropic/…` from pi's gateway catalog | `anthropic-messages` | `env.AI.run` → AI Gateway `/run`, Messages in and out     | the REST API's `/ai/v1/messages` → AI Gateway `/run`   |
+| `openai/…` from pi's gateway catalog    | `openai-responses`   | `env.AI.run` → AI Gateway `/run`, Responses in and out    | the REST API's `/ai/v1/responses` → AI Gateway `/run`  |
+| Any other model object                  | its own `api`        | the binding's `fetch` → AI Gateway's provider-native path | `gateway.ai.cloudflare.com` → the provider-native path |
+
+A model from pi's Cloudflare AI Gateway catalog runs on `env.AI.run` under the gateway's
+catalog id (`anthropic/claude-opus-4.8`). pi-ai spells Claude ids as Anthropic does
+(`claude-opus-4-8`), so `agents` lists and resolves them with the catalog's dot instead. The body is pi-ai's own,
+built by pi-ai's converter for the model's `api`, and it is sent in that format: `/run`
+converts nothing, so the answer, streams included, is the shape pi-ai's stream processors
+read. `/run` picks the provider and bills through Unified Billing or a key stored on the
+gateway.
+
+Any other model object — one from pi's Anthropic, OpenAI or Groq registry, with the vendor's
+own id — goes to AI Gateway's **provider-native path** through the binding's `fetch`, with the
+provider slug taken from the model's `baseUrl` host. The gateway forwards it to the vendor with
+the credential it holds and streams the vendor's own SSE back untouched.
+
+Either way no vendor credential leaves your Worker, and the model's `api`, `provider` and
+`id` are never rewritten, so thinking signatures and encrypted reasoning items replay on the
+next turn.
 
 The `api` markers in that table are the only ones this package routes, and the table is the
 whole list: `cloudflare-ai`, `anthropic-messages`, `openai-responses`, `openai-completions`.
@@ -266,8 +297,10 @@ gateway, an unpaid account) become a `CloudflareAIError`, so fallback and retry
 way they treat Workers AI failures. A model whose `api` is not one of the four routed markers
 never gets that far: the stream ends with an `error` event naming the `api`.
 
-`zdr` turns Zero Data Retention on or off for one request, whatever the gateway's own setting.
-It applies to a routed model on unified billing and is sent as `cf-aig-zdr`.
+`byokAlias` picks a stored key by alias when the gateway holds several for one provider. It is
+sent as `cf-aig-byok-alias` on a catalog model and on any other model object. `zdr` turns Zero
+Data Retention on or off for a Unified Billing request, and applies to model objects outside
+pi's gateway catalog only: `/run` does not read it.
 
 ## Observability
 
@@ -287,6 +320,15 @@ A failed dispatch ends the stream with an `error` event whose message carries a
 `cloudflare-error` diagnostic (`status`, `code`, `logId`), and `onResponse` fires with the raw
 status and headers for every request.
 
+## Stream resume
+
+Through the binding, a model from pi's AI Gateway catalog streams from `/run`, which names the run in
+`cf-aig-run-id` and keeps its events. If the connection drops, the provider reconnects through
+the binding and replays from the last complete event, so the stream continues with nothing lost
+or repeated. It gives up after five drops or once the gateway no longer holds the run, and an
+abort never resumes. Workers AI streams and models on the provider-native path have no run id
+and are not resumed. The run id is on the `cloudflare` diagnostic as `runId`.
+
 ## Fallback
 
 ```ts
@@ -324,7 +366,7 @@ Every other model in the catalog takes the full set.
 
 ## Beta
 
-This subpath needs `@earendil-works/pi-ai@^1.0.0`, an optional peer of `agents`. `agents`
+This subpath needs `@earendil-works/pi-ai@~1.3.0`, an optional peer of `agents`. `agents`
 takes no vendor package as a dependency, optional or otherwise. The surface is in beta
 and may change in a minor release. An unlisted `@cf/` id resolves with default metadata (a
 128k context window, 8192 output tokens, zero cost); pass overrides when you know better.