agents 0.29.0 → 0.30.1

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.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).
+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
 
@@ -27,20 +27,17 @@ 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();
 
   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, settings },
+        { models, registry: this.registry, onWake },
         context
       );
     },
@@ -61,14 +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.                                                                                                                                             |
 
-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.
+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 as part of startup, once per isolate. If it throws the operation that triggered it fails and the next operation tries again.
+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.
 
@@ -98,14 +95,18 @@ const wordCount: ToolRegistration<typeof WordCount> = {
   }
 };
 
-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`.
@@ -122,11 +123,11 @@ 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, settings },
+    { models, registry: this.registry, onWake },
     context
   );
 };
@@ -144,7 +145,7 @@ 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: [
@@ -153,7 +154,7 @@ harness: async ({ storage, context }) => {
   });
   return Harness.open(
     storage,
-    { models, registry: this.registry, settings },
+    { models, registry: this.registry, onWake },
     context
   );
 };
@@ -189,14 +190,15 @@ const result = await session.wait(receipt.operationId);
 | `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.                                                                                                                                                                                                                                                              |
+| `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()`, `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.
+`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.
 
@@ -216,9 +218,41 @@ The kind is a label, not a permission. It records what your code said the input
 
 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. A task that sleeps while other work runs, such as a compaction retry during a generation, is resumed from the job's wait when it is due. 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/human-in-the-loop.md

@@ -32,7 +32,6 @@ Agents SDK supports multiple human-in-the-loop patterns. Choose based on your us
 | OpenAI Agents SDK      | `needsApproval`       | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   |
 | Client-side tools      | `onToolCall`          | Tools that need browser APIs or user interaction   | Pattern below                                                                                                  |
 | Stateless servers      | Stateless Elicitation | Current MCP tools requesting structured input      | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) |
-| Legacy servers         | Legacy Elicitation    | Existing sessionful MCP deployments                | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           |
 
 ### Decision Guide
 
@@ -40,7 +39,7 @@ Agents SDK supports multiple human-in-the-loop patterns. Choose based on your us
 Is this part of a multi-step workflow?
 ├── Yes → Use Workflow Approval (waitForApproval)
 └── No → Are you building an MCP server?
-         ├── Yes → Use MCP Elicitation (elicitInput)
+         ├── Yes → Use MCP Elicitation (inputRequired)
          └── No → Is this an AI chat interaction?
                   ├── Yes → Does the tool need browser APIs?
                   │        ├── Yes → Use onToolCall (client-side execution)
@@ -460,7 +459,7 @@ See the complete example: [openai-sdk/human-in-the-loop/](https://github.com/clo
 
 ### MCP Elicitation
 
-**Stateless Elicitation** uses multi-round-trip requests (MRTR). A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
+MCP servers built with `createMcpHandler` use multi-round-trip requests (MRTR) for elicitation. A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
 
 ```typescript
 import {
@@ -517,8 +516,6 @@ The MCP client renders the JSON Schema form and the original operation remains p
 
 See the [Stateless Elicitation example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr).
 
-**Legacy Elicitation** in existing Legacy deployments uses pushed `elicitation/create` requests over a stateful transport. See the explicitly legacy [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example when retaining `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport`.
-
 ## State Patterns for Approvals
 
 Track pending approvals in agent state for UI rendering and persistence:
@@ -640,10 +637,9 @@ async submitForApproval(request: ApprovalRequest): Promise<string> {
 | AIChatAgent tools     | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           | Chat tool approval with needsApproval + onToolCall |
 | OpenAI Agents SDK     | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   | Conditional tool approval with modal               |
 | Stateless Elicitation | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) | Stateless multi-round input                        |
-| Legacy Elicitation    | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           | Stateful pushed input requests                     |
 
 For detailed API documentation, see:
 
 - [Workflows](./workflows.md) - `waitForApproval()`, `approveWorkflow()`, `rejectWorkflow()`
-- [MCP Servers](./mcp-servers.md) - `inputRequired()` and legacy `elicitInput()`
+- [MCP Servers](./mcp-servers.md) - `inputRequired()` elicitation
 - [Callable Methods](./callable-methods.md) - `@callable()` decorator for approval endpoints

package/docs/index.md

@@ -149,10 +149,10 @@ Building your own harness? Sessions stores the conversation, Streams holds durab
 
 ## MCP (Model Context Protocol)
 
-- [Creating MCP Servers](./mcp-servers.md) - Build MCP servers with `McpAgent`
+- [Creating MCP Servers](./mcp-servers.md) - Build stateless MCP servers with `createMcpHandler`
 - [Securing MCP Servers](./securing-mcp-servers.md) - OAuth and authentication for MCP
 - [Connecting to MCP Servers](./mcp-client.md) - `MCPClientManager` on a Durable Object, or `addMcpServer()` on an Agent
-- [MCP Transports](./mcp-transports.md) - Transport options: Streamable HTTP, SSE, and RPC
+- [MCP Transports](./mcp-transports.md) - Streamable HTTP on the server, and the transports an Agent can connect with
 
 ## Operations
 

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/mcp-client.md

@@ -51,19 +51,6 @@ callback URL to `registerServer()` and route that request to the same named
 Durable Object. The manager persists the URL and only intercepts a callback
 whose origin and pathname match it.
 
-An HTTP-only manager does not need `env`. Pass the Durable Object environment
-when the catalog can contain RPC servers so persisted binding names can be
-resolved after a wake:
-
-```ts
-readonly mcp = new MCPClientManager("my-object", "1.0.0", {
-  env: this.env
-});
-```
-
-If an RPC row exists without `env`, startup logs a warning identifying the
-server and does not recreate that connection.
-
 `Agent` installs this same capability object directly. Existing `this.mcp`,
 `addMcpServer()`, `removeMcpServer()`, and `getMcpServers()` APIs remain
 available.
@@ -188,7 +175,7 @@ These options are persisted and used when reconnecting after hibernation or afte
 
 ### Protocol negotiation and elicitation
 
-Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP, SSE, and RPC servers.
+Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP and SSE servers.
 
 MCP servers can request input from the client during `callTool`, `getPrompt`, or `readResource`. Stateless Elicitation returns an `input_required` result and completes through MRTR: the MCP SDK invokes the configured `elicitation/create` handler, sends its response, and continues the original request. Agents does not expose an intermediate continuation; the original call stays pending while human input is collected and eventually resolves to the ordinary tool, prompt, or resource result. Legacy Elicitation on Legacy servers continues to use pushed `elicitation/create` requests. Both generations share the same handlers.
 
@@ -243,8 +230,6 @@ MCP server URLs are validated before connection to prevent Server-Side Request F
 
 Loopback development URLs such as `localhost`, `127.0.0.1`, and `::1` are allowed.
 
-If you need to connect to another internal MCP server, use the [RPC transport](./mcp-transports.md) with a Durable Object binding instead of HTTP.
-
 ### Return Value
 
 `addMcpServer()` returns the connection state:
@@ -666,17 +651,6 @@ async addMcpServer(
   | { id: string; state: "authenticating"; authUrl: string }
 >
 
-// RPC transport (Durable Object binding — no HTTP overhead)
-async addMcpServer(
-  name: string,
-  binding: DurableObjectNamespace,
-  options?: {
-    props?: Record<string, unknown>; // passed to the McpAgent's onStart(props)
-    client?: ClientOptions;
-    retry?: RetryOptions;
-  }
-): Promise<{ id: string; state: "ready" }>
-
 // Legacy signature (still supported)
 async addMcpServer(
   name: string,
@@ -689,7 +663,7 @@ async addMcpServer(
 
 Add and connect to an MCP server. Throws if connection or discovery fails.
 
-`callbackHost` is automatically derived from the incoming HTTP request or WebSocket connection URI — you almost never need to set it explicitly. It is only needed when the auto-detected host does not match your desired OAuth callback origin (for example, behind a reverse proxy). For RPC transport, pass a `DurableObjectNamespace` binding instead of a URL. See [MCP Transports](./mcp-transports.md) for details.
+`callbackHost` is automatically derived from the incoming HTTP request or WebSocket connection URI — you almost never need to set it explicitly. It is only needed when the auto-detected host does not match your desired OAuth callback origin (for example, behind a reverse proxy). See [MCP Transports](./mcp-transports.md) for the transport options.
 
 Calling `addMcpServer` is idempotent when both the server name **and** URL match an existing active connection — the existing connection is returned without creating a duplicate. This makes it safe to call in `onStart()` without worrying about duplicate connections on restart.