agents 0.28.1 → 0.30.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

@@ -11,10 +11,10 @@ Pi owns everything about a run: the transcript, the inbox of steers and follow-u
 ## Install the Pi packages
 
 ```sh
-npm install agents @earendil-works/pi-durable @earendil-works/pi-ai
+npm install agents @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
 ```
 
-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).
+The three Pi packages are optional peer dependencies of `agents`, at `~1.4.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
 
@@ -32,12 +32,12 @@ export class Assistant extends Agent<Env> {
   registry = createRegistry();
 
   harness = new PiHarness({
-    harness: ({ storage, context }) => {
+    harness: ({ storage, context, onWake }) => {
       const models = createModels();
       models.setProvider(this.ai.provider);
       return Harness.open(
         storage,
-        { models, registry: this.registry },
+        { models, registry: this.registry, onWake },
         context
       );
     },
@@ -58,12 +58,14 @@ export class Assistant extends Agent<Env> {
 }
 ```
 
-| 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. |
+| Option     | What it is                                                                                                                                                                                                                                                                                                                          |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `harness`  | Required. Receives `{ storage, context, onWake }` and returns Pi's `Harness`, usually from `Harness.open`. Pass `onWake` to `Harness.open`, so the object can hibernate while Pi's tasks sleep (see [How recovery works](#how-recovery-works)). 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.
+Create the registry per object, as the `registry` field above does, not at module scope: Pi keeps every `Harness` subscribed to its registry until the `Harness` closes, and an evicted object never closes it.
+
+The factory runs once per open: at startup, and again after a storage error (see [How recovery works](#how-recovery-works)), so keep it safe to run more than once. 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,18 +91,22 @@ 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) }] };
   }
 };
 
-const registry = createRegistry();
-registry.install({
-  name: "writing",
-  sections: [
-    { key: "preamble", render: () => "You are an editor.", tag: false }
-  ],
-  tools: [wordCount]
-});
+// One per object, as a field: `registry = createWritingRegistry();`
+function createWritingRegistry() {
+  const registry = createRegistry();
+  registry.install({
+    name: "writing",
+    sections: [
+      { key: "preamble", render: () => "You are an editor.", tag: false }
+    ],
+    tools: [wordCount]
+  });
+  return registry;
+}
 ```
 
 - **Tool arguments are typed from the schema.** Type a tool as `ToolRegistration<typeof Parameters>`; a bare `ToolRegistration` types its arguments as `unknown`.
@@ -117,9 +123,13 @@ Pi's extensions can do more: hooks on model requests and tool calls (`hook(ToolT
 ```ts
 import { skills } from "agents/harness/pi";
 
-harness: async ({ storage, context }) => {
+harness: async ({ storage, context, onWake }) => {
   this.registry.install(await skills(sources));
-  return Harness.open(storage, { models, registry: this.registry }, context);
+  return Harness.open(
+    storage,
+    { models, registry: this.registry, onWake },
+    context
+  );
 };
 ```
 
@@ -135,14 +145,18 @@ import { browserTool } from "agents/browser/pi";
 
 readonly browser = new Browser({ provider: browserRun(this.env.BROWSER) });
 
-harness: async ({ storage, context }) => {
+harness: async ({ storage, context, onWake }) => {
   this.registry.install({
     name: "browser",
     tools: [
       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, onWake },
+    context
+  );
 };
 
 readonly lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
@@ -169,27 +183,76 @@ 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.                                                                                                                                                                  |
-
-`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.
+| 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, part of the running work, or `parked` (see [How recovery works](#how-recovery-works)).                                                                                                                                                                                                    |
+| `retry()`                                         | Runs again the tasks Pi's restart limit parked in the session's work. Resolves `false` when nothing was parked.                                                                                                                                                                                                                      |
+| `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()`, `retry()`, `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.
+
+### Inputs queued behind a failed run
+
+A run fails with `model_error` when the model errors and Pi does not retry or the error outlasts its retries, and with `no_model` when the session has no usable model. Its own operation settles `unanswered` with that reason. Pi's `settings.afterFailedRun` decides what happens to the inputs queued behind it. Refer to [Failures and Recovery](https://github.com/earendil-works/pi/tree/main/packages/durable#failures-and-recovery) in the pi-durable README for what each value does. Set it in the factory:
+
+```ts
+harness: ({ storage, context, onWake }) =>
+  Harness.open(
+    storage,
+    {
+      models,
+      registry: this.registry,
+      onWake,
+      settings: { afterFailedRun: "withdraw" }
+    },
+    context
+  );
+```
+
+| Value            | What callers see                                                                                                                                                                                               |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keep` (default) | `pending()` lists the inputs as `queued`, `busy()` is `false`, and `wait()` keeps waiting. The next `submit()` runs them first, in order, then the new input. The next `reset()` runs them in the new context. |
+| `continue`       | `wait()` returns their results as usual. If the cause persists, such as a missing model, each queued input fails in its own run.                                                                               |
+| `withdraw`       | `wait()` returns `{ status: "unanswered", reason: "run_failed" }`, and `pending()` no longer lists them.                                                                                                       |
+
+With `keep`, the kept inputs are not work to Pi: its `wake()` counts tasks, not queued inputs. The wake job completes, and the object can hibernate until the next `submit()` or `reset()`. Pass a `signal` to `wait()` if a caller should not wait that long. To withdraw a kept input, call `abort(operationId)`, which settles it `unanswered` with reason `aborted`. `session.abort()` with no id stops the whole session, which withdraws every kept input too.
+
 ## 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.
+The harness schedules one lifecycle job, driven by Pi's `wake()`. While Pi has work running, the job waits on it and refreshes itself as a heartbeat. While Pi's tasks sleep, such as a retry backoff, the job is due when the first one wakes. Pi says when through the `onWake` the factory passes to `Harness.open`, and sets no in-memory timer of its own, so the object can hibernate until then. Without `onWake` the harness still works, but Pi's timer keeps the object in memory, and billed, while a task sleeps, and the harness logs a warning. When Pi has nothing to do, the job completes. 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.
+
+A task that keeps crashing the object would restart it forever, so Pi parks a task cut off by a crash or eviction `settings.restartLimit` times in a row (default 5) without progress. A parked task is not work: the job completes and the object can hibernate. Its operations show as `parked` in `pending()`, and `wait()` keeps waiting. If your factory passes `onReport` to `Harness.open`, Pi reports it there as `task_parked`. Once you have dealt with the cause, `session.retry()` runs it again and wakes the harness; `session.abort()` gives up on it instead.
+
+A storage error closes Pi for good: the call that hit it rejects with the error, and calls and `events()` streams already underway end with Pi's `SessionFailed`, so retry them. If your factory passes `onReport` to `Harness.open`, Pi reports the failure there as `session_failed`. Once the failed Pi has closed, the harness opens Pi again, which runs the factory again, on the next call or the job's next step. Closing waits for running task code, such as a tool call, to return, so code that ignores its abort signal delays the reopen. Pi recovers from what it committed and resumes its work the same way.
+
+If a step of the job fails, such as when the factory throws, the job is not dropped. It tries again after 30 seconds, doubling the delay with each failure in a row up to 10 minutes, and goes back to its usual schedule once a step succeeds. A Durable Object memory-limit reset that fails Pi while the job waits on it counts against the alarm's memory-limit circuit breaker. Lifecycle backs the job off and drops it after repeated resets. The next call opens Pi again and pushes the job again, so Pi's restart limit is what eventually parks a task that keeps causing resets.
 
 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.
 

package/docs/lifecycle.md

@@ -234,7 +234,13 @@ physical alarm automatically — there is no explicit rearm call. When the
 alarm fires, Lifecycle drives due jobs in due order as an event loop, then
 runs host `onAlarm()`, then re-arms from queue state. Before driving any job
 it arms a deadman pre-alarm so an isolate death mid-drive still wakes the
-object to resume.
+object to resume. While the queue holds jobs, it also arms a fallback alarm
+before startup runs, at the next job's time but at least 30 seconds out. An
+alarm whose startup throws still leaves that wake, whether or not the
+platform's own alarm retries run, so the failed startup is retried then. A
+startup that pushes or reschedules jobs and then throws, from an alarm or a
+request, arms the same fallback from the queue as it stands, so those jobs
+keep a wake too.
 
 A job's drive result decides what happens next: returning nothing completes
 and deletes it, `{ rescheduleAt }` suspends it until a future time, and

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
@@ -144,6 +166,10 @@ A session stores its model as `{ provider, modelId }`, not as a model object, so
 `@cf/…` and `<provider>/<id>` forms there. Options given to `ai(model, options)` do not reach a
 session; set them on `createAI` instead.
 
+A model stream that is cut off, or that sends nothing for `streamIdleTimeoutMs`, ends in an error
+pi-ai's `isRetryableAssistantError()` treats as transient, so the harness retries the turn under
+its retry settings rather than failing it.
+
 `ai.streamFn` is `streamSimple`, bound, for frameworks that take a stream function, such as
 pi-agent-core's `Agent({ streamFn })`.
 
@@ -179,7 +205,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 +237,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 +301,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 +324,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 +370,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.4.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.