agents 0.25.0 → 0.27.0

package/docs/harnesses/think.md

@@ -0,0 +1,215 @@
+---
+title: Think harness (Experimental)
+pcx_content_type: reference
+description: Run Think's agent loop in a Durable Object with the experimental ThinkHarness lifecycle capability. Durable transcripts and turns that survive eviction.
+---
+
+`ThinkHarness` runs Think's agent loop as a Lifecycle capability. It has the same shape as the [Pi harness](./pi.md): `harness.prompt()`, `harness.sessions` and `harness.session(id)`. The engine is the AI SDK. The harness owns its storage, so you install only the harness:
+
+- Each session's transcript is kept as AI SDK `UIMessage`s, in the same tables the `Sessions` capability uses.
+- The output of a model call is kept while it streams, in the same tables the `Streams` capability uses.
+- One Lifecycle job per session wakes the object after an eviction.
+
+It is experimental. The API may change in any release.
+
+## Create the harness
+
+Install the harness on the Lifecycle:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { tool } from "ai";
+import { z } from "zod";
+import { ThinkHarness } from "agents/harness/think";
+import { Lifecycle } from "agents/lifecycle";
+import { createAI } from "agents/models/ai-sdk";
+
+export class Assistant extends DurableObject<Env> {
+  ai = createAI({ binding: this.env.AI });
+
+  harness = new ThinkHarness({
+    model: this.ai("@cf/moonshotai/kimi-k2.7-code"),
+    system: "You are a helpful assistant.",
+    tools: {
+      weather: {
+        ...tool({
+          description: "Get the weather for a city",
+          inputSchema: z.object({ city: z.string() }),
+          execute: async ({ city }) => `Sunny in ${city}`
+        }),
+        // Safe to run again if an eviction cuts a call short.
+        recovery: "rerun"
+      }
+    }
+  });
+
+  lifecycle = Lifecycle.install(this).use(this.harness);
+
+  async ask(prompt: string) {
+    const result = await this.harness.prompt(prompt);
+    return result.status === "done" ? result.text : result.reason;
+  }
+}
+```
+
+On an `Agent`, call `this.lifecycle.use(this.harness)` in the constructor. Do not also install a `Sessions` capability that writes the harness's sessions: the harness caches what it wrote.
+
+| Option                 | What it is                                                                                                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`                | Required. An AI SDK `LanguageModel`, or a function of `{ session }` that returns one.                                                                                       |
+| `system`               | The system prompt, or a function of `{ session }`.                                                                                                                          |
+| `tools`                | An AI SDK `ToolSet`, or a function of `{ session }`. Tools with `execute` run on the server. Tools without it run on a client. A server tool may carry `recovery: "rerun"`. |
+| `maxSteps`             | Most model calls one operation makes. Default 10.                                                                                                                           |
+| `toolApproval`         | Decide per call whether a tool needs approval. A tool's own `needsApproval` also applies.                                                                                   |
+| `recovery`             | The budget for recovering interrupted work: `maxAttempts`, `backoffMs`, `stallTimeoutMs`. Refer to [Recovery](#recovery).                                                   |
+| `reservedMetadataKeys` | Message-metadata keys only the server may write; stripped from input submitted with `source: "client"`.                                                                     |
+| `configureSession`     | Called with each session's `Session` handle the first time the harness uses it. Set compaction here with `onCompaction()` and `compactAfter()`.                             |
+| `hooks`                | Callbacks into the turn loop. Refer to [Hooks](#hooks).                                                                                                                     |
+
+## Submit and wait
+
+```ts
+const session = this.harness.session(); // the root session, id ""
+
+// Durable before the model runs. The same operationId twice returns the same receipt.
+const receipt = await session.submit("Summarize the README", {
+  operationId: requestId
+});
+const result = await session.wait(receipt.operationId);
+
+// Or both in one call, with the transcript after it.
+const { text, messages } = await session.prompt("Hello");
+```
+
+`submit()` accepts a string, a `UIMessage` or an array of them, the shared harness input `{ parts }`, or a tool answer. A submission made while the session is busy waits its turn. Steering the running turn is not supported: `whenBusy: "steer"` throws `SteerNotSupportedError`.
+
+| Method                       | What it does                                                                                                                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `submit(input, options)`     | Durably queue input. Returns `{ operationId, session, accepted }`.                                                                                                                           |
+| `prompt(input, options)`     | `submit`, then `wait`, then the transcript.                                                                                                                                                  |
+| `wait(operationId, signal?)` | Resolve when the operation settles: `done` with `text`, or `unanswered` with a `reason`.                                                                                                     |
+| `inspect(operationId)`       | The operation's status, or `undefined`.                                                                                                                                                      |
+| `chat(input, callback)`      | Stream the answer to `onStart`, `onEvent(json)`, then `onDone` or `onError`, like Think's `chat()`.                                                                                          |
+| `abort(operationId?)`        | Withdraw a queued operation or abort a running one. With no id, everything open in the session.                                                                                              |
+| `regenerate(messageId?)`     | Answer a user message again, as a new branch. `Session.getBranches()` still reads the earlier answers.                                                                                       |
+| `continue()`                 | Call the model again to continue the latest message.                                                                                                                                         |
+| `reset(handoff?)`            | Abort everything and clear the transcript, optionally leaving a system note.                                                                                                                 |
+| `messages()`                 | The active transcript.                                                                                                                                                                       |
+| `pending()`                  | Operations not settled yet, oldest first.                                                                                                                                                    |
+| `subscribe(listener)`        | Live events in the AI SDK's vocabulary: chunks, persisted messages, operation status, run start and end, reset, and `transcript` (deleted messages or a compaction; re-read the transcript). |
+| `inFlight()`                 | The running operation and its model call's chunks so far, including chunks an eviction left in storage.                                                                                      |
+| `watch()`                    | The shared harness interface's watch, so a Channels host can serve the session.                                                                                                              |
+
+`harness.sessions` has `create()`, `fork(from)` and `list()`. A fork copies the source session's active path.
+
+A session also reads and shapes its transcript:
+
+| Method                     | What it does                                                                                            |
+| -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `branches(messageId)`      | The answers to a message, its children in the tree. A regenerated answer is a branch beside the others. |
+| `search(query, { limit })` | Full-text search over the session's messages.                                                           |
+| `compact()`                | Summarize older messages with the compaction function set in `configureSession`.                        |
+
+`configureSession` receives each session's `Session` handle from `agents/sessions`, for compaction settings and for writing messages without starting a turn. Those writes still reach `subscribe()` listeners and `ThinkChat` clients: an append or update as a `message` event, a deletion or compaction as a `transcript` event.
+
+## Tools, approvals and client tools
+
+The harness runs every server tool call itself. The model only sees tool definitions, so each model call ends at its tool calls. The harness then runs those calls in parallel and calls the model again with their results. All of this stays in one assistant message.
+
+A call that needs approval is recorded as `approval-requested` and the operation settles. Submit the answer to continue:
+
+```ts
+await session.submit({ type: "approval", approvalId, approved: true });
+await session.submit({
+  type: "tool-result",
+  toolCallId,
+  result: { ok: true, output: "42" }
+});
+```
+
+A client tool call works the same way: the operation settles with the call `input-available`, and the client's result continues the turn. Pass `autoContinue: false` with an answer to record it without continuing. Tool schemas a browser sends are kept with the session through `submit(..., { clientTools })`.
+
+Input submitted with `source: "client"` is untrusted:
+
+- It may only add `user` messages. Any other role ends the operation `unanswered` with reason `client_role`.
+- A message whose id is already stored, on any branch, is dropped rather than rewritten.
+- A client tool never replaces a server tool of the same name.
+- A tool result answers only a client tool. A result for a server tool call ends `unanswered` with reason `not_client_tool`, so a server tool's result always comes from running it under its approval policy.
+
+## Recovery
+
+Every step of a turn reads only durable state, so a restarted object continues where the last write left off.
+
+- **During a model call.** Chunks are written to a stream as they arrive. When the call ends, the harness persists the message and deletes the stream in one SQLite transaction. After an eviction, the harness rebuilds the partial message from the stream, keeps it, and calls the model again to continue the same message. Tool calls whose input never finished streaming are dropped.
+- **During a tool call.** The harness records each call before it runs. After an eviction, a call with a record and no result was cut short. A tool that carries `recovery: "rerun"` runs again. Any other tool (`"report"`, the default) has the call recorded as failed with an "interrupted" error and the model decides what to do. Use `rerun` only for tools that are safe to repeat.
+- **Budget.** `recovery.maxAttempts` (default 10) counts interruptions without progress. A finished model call or tool call resets the count. Past the budget the operation settles `unanswered` with reason `interrupted`. Retries after the first back off from `recovery.backoffMs` (default 1000), doubling up to a minute.
+- **Stalls.** A model stream that sends nothing for `recovery.stallTimeoutMs` (default 120000) is treated as interrupted.
+- **Memory limits.** The wake jobs are flagged for the Lifecycle's alarm memory-limit breaker, so a turn that keeps running out of memory is backed off. When the breaker seals, the running operation is settled `unanswered` with reason `out_of_memory` on the next start, keeping any partial answer, rather than run again. A restart keeps a wake already set for later, so backoff survives a deploy.
+
+## Hooks
+
+| Hook             | When                                                                                                                                               |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `beforeTurn`     | Before every model call. Return `model`, `system`, `messages`, `activeTools`, `toolChoice`, `providerOptions`, `maxOutputTokens` or `temperature`. |
+| `beforeToolCall` | Before each server tool call. Return `{ action: "block", reason }`, `{ action: "substitute", output }`, or `{ action: "run", input }`.             |
+| `afterToolCall`  | After each server tool call, with its result.                                                                                                      |
+| `onStepFinish`   | After each model call's message is persisted.                                                                                                      |
+| `onChunk`        | For each UI chunk the model streams.                                                                                                               |
+| `onTurnEnd`      | After an operation settles.                                                                                                                        |
+| `onError`        | Observe a model call's error.                                                                                                                      |
+| `classifyError`  | Return `fail`, `retry`, or `context-overflow`. `classifyContextOverflow` matches the common providers' overflow errors.                            |
+| `onRecovery`     | Return `continue` or `abandon` for an interrupted model call.                                                                                      |
+
+`beforeTurn` runs before every model call because a turn makes several, and after an eviction the harness has no memory of what an earlier call returned. On `context-overflow` the harness compacts the session with its compaction function and calls the model again, once.
+
+## Serve useAgentChat
+
+`ThinkChat` speaks Think's chat WebSocket protocol for one session, so `useAgentChat` works unchanged. It also answers `GET …/get-messages`:
+
+```ts
+import { ThinkChat } from "agents/harness/think";
+import { WebSockets } from "agents/websockets";
+
+webSockets = new WebSockets();
+chat = new ThinkChat({ harness: this.harness, webSockets: this.webSockets });
+
+lifecycle = Lifecycle.install(this)
+  .use(this.harness)
+  .use(this.webSockets)
+  .use(this.chat);
+```
+
+It handles chat requests (`submit-message` and `regenerate-message`), cancel, clear, client tool results, approvals, and stream resume after a reconnect or an eviction.
+
+## Compared with Think
+
+`ThinkHarness` is meant to replace the engine inside `@cloudflare/think`. It reads and writes the same Sessions and Streams tables Think uses, and the root session is Think's conversation. Work in flight when an agent moves over is not carried across.
+
+| Think                                                                      | ThinkHarness                                                        |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `getModel()`, `getSystemPrompt()`, `getTools()`                            | `model`, `system`, `tools` options                                  |
+| `beforeTurn`, `beforeToolCall`, `afterToolCall`, `onStepFinish`, `onChunk` | Hooks of the same names                                             |
+| `beforeStep`                                                               | `beforeTurn`, which runs before every model call                    |
+| `onChatResponse`, `onChatError`, `classifyChatError`                       | `onTurnEnd`, `onError`, `classifyError`                             |
+| `onChatRecovery`, `chatRecovery`                                           | `onRecovery`, `recovery`                                            |
+| `submitMessages`, `waitForSubmission`, `inspectSubmission`                 | `submit`, `wait`, `inspect`                                         |
+| `saveMessages`, `runTurn`                                                  | `prompt`                                                            |
+| `chat(message, callback)`                                                  | `session.chat(input, callback)`                                     |
+| `cancelChat`, `cancelSubmission`, `cancelAllChats`                         | `abort(operationId)`, `abort()`                                     |
+| `continueLastTurn`, regeneration                                           | `continue()`, `regenerate()`                                        |
+| `clearMessages`, `getMessages`, `messages`                                 | `reset()`, `messages()`                                             |
+| `configureSession`, compaction                                             | `configureSession`                                                  |
+| `useAgentChat` protocol                                                    | `ThinkChat`                                                         |
+| One conversation per Durable Object                                        | Many sessions per object, with `create`, `fork` and `list`          |
+| Tools run inside `streamText`; interrupted calls are repaired              | The harness runs each call; a tool can opt into `recovery: "rerun"` |
+
+Not supported yet:
+
+- Steering a running turn. `submit()` throws `SteerNotSupportedError` for `whenBusy: "steer"` rather than queue the input as a follow-up.
+- `messageConcurrency` strategies other than queueing (`latest`, `merge`, `drop`, debounce).
+- Context blocks from `configureContext()`. Compute the system prompt in `system` or `beforeTurn`.
+- Read-time truncation of older tool results and media eviction.
+- Workspace tools, `getActions()` with its ledger, agent tools, skills, extensions, MCP tools, messengers, channels policy, scheduled tasks, and workflows. Pass the tools these produce in `tools`; the higher-level features are not ported.
+- `listSubmissions` and `deleteSubmissions`. `pending()` lists open operations.
+- Client tool ownership by participant, and the `cf_agent_chat_recovering` frame.
+- `configure()` and `getConfig()`.

package/docs/index.md

@@ -58,7 +58,6 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Push Notifications](./push-notifications.md) - Browser push notifications via Web Push API and scheduled delivery
 - TODO: [SMS](./sms.md) - Text message integration (Twilio, etc.)
 - [Voice Agents](./voice.md) - Build voice agents with real-time speech-to-text, text-to-speech, and conversation persistence
-- [Channels](./channels.md) - Send and receive messages through Slack, Telegram, email, browser voice, or custom adapters
 - [Chat SDK State](./chat-sdk.md) - Store Chat SDK subscriptions, locks, queues, and history in Agents sub-agents
 
 ## Background Processing
@@ -80,8 +79,9 @@ The differentiator is not "we have durable state" — it is what happens when a
 - [Server-Driven Messages](./server-driven-messages.md) - Autonomous agent workflows: scheduled follow-ups, queue processing, webhooks, chained reasoning
 - TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
 - [Models (Experimental)](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
-- [Models for pi-ai (Experimental)](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
-- [Pi harness (Experimental)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
+- [Models for pi-ai (Beta)](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
+- [Pi harness (Beta)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
+- [Think harness (Experimental)](./harnesses/think.md) - Run Think's agent loop as a Lifecycle capability, with transcripts in Sessions, output in Streams, and turns that survive eviction
 - TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
 - [Sessions (Experimental)](./sessions.md) - Durable message trees, streamed history, compaction, search, and lossless attachment offload
 - [Context (Experimental)](./context.md) - System-prompt blocks, frozen prompts, writable/searchable/loadable providers, and their tools
@@ -128,6 +128,7 @@ The differentiator is not "we have durable state" — it is what happens when a
 ## Compute Environments
 
 - [Browse the Web (Experimental)](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
+- [Search the Web (Beta)](./search-the-web.md) - A `websearch` tool over Cloudflare's Web Search API for the pi harness, the AI SDK, and TanStack AI
 - TODO: [Cloudflare Sandboxes](./sandboxes.md) - Isolated environments for coding agents, ffmpeg, and heavy compute
 
 ## Advanced Topics

package/docs/lifecycle.md

@@ -156,6 +156,46 @@ Host-specific bindings, authentication, and protocol adapters remain explicit
 constructor dependencies. Lifecycle never grants a capability the complete
 host implicitly.
 
+A capability's public operations can run before startup, because
+[native RPC](#native-rpc) bypasses the automatic startup on fetch, alarm and
+WebSocket events. If an operation starts work that `onStart` also awaits, such
+as lazily opening a store, it must call `await this.lifecycle.ready()` first:
+
+```ts
+class Store extends LifecycleCapability {
+  #opening: Promise<Database> | undefined;
+
+  constructor() {
+    super("store");
+  }
+
+  async onStart(): Promise<void> {
+    await this.#open();
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const db = await this.#open();
+    return db.get(key);
+  }
+
+  async #open(): Promise<Database> {
+    // Without this, an RPC that calls get() before startup begins the open
+    // outside startup, and onStart then waits on it behind a closed gate.
+    await this.lifecycle.ready();
+    this.#opening ??= openDatabase(this.lifecycle.storage);
+    return this.#opening;
+  }
+}
+```
+
+Startup holds the input gate (`blockConcurrencyWhile`) while `onStart` runs, so
+work begun outside startup has its timers and I/O held back and never finishes.
+`onStart` waits on it until startup times out after 30 seconds and the object
+is reset. Whether it happens depends on whether the RPC arrives first, so it
+shows up as an intermittent timeout. `ready()` resolves immediately inside
+startup, so `onStart` can call the same guarded method. `Tasks`, `Streams`,
+`Scheduler`, `Queue` and `PiHarness` guard their operations this way.
+
 Capability hooks run outside host context, but user callbacks run through
 `this.lifecycle.runInHostContext(fn)` inside the host invocation context.
 Scheduler and Queue dispatch their registered callbacks through this

package/docs/models-pi-ai.md

@@ -1,4 +1,4 @@
-# Models for pi-ai (Experimental)
+# Models for pi-ai (Beta)
 
 `agents/models/pi-ai` is the [pi-ai](https://github.com/earendil-works/pi/tree/main/packages/ai)
 twin of [`agents/models/ai-sdk`](./models.md): the same `createAI` factory, the same options,
@@ -45,7 +45,7 @@ design: a model this package cannot name exactly is yours to construct.
    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.
-5. Everything here is experimental and may change in a minor release.
+5. Everything here is in beta and may change in a minor release.
 
 ## Quick start
 
@@ -311,10 +311,10 @@ Image generation is Workers AI only. The knobs a model takes are the model's:
 in a `cloudflare-compat` diagnostic on the result rather than sent and ignored.
 Every other model in the catalog takes the full set.
 
-## Experimental
+## Beta
 
-This subpath needs `@earendil-works/pi-ai@^0.99.2`, an optional peer of `agents`. `agents`
-takes no vendor package as a dependency, optional or otherwise. The surface is experimental
+This subpath needs `@earendil-works/pi-ai@^1.0.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.
 

package/docs/search-the-web.md

@@ -0,0 +1,133 @@
+# Search the Web (Beta)
+
+`agents/websearch` gives a model a `web_search` tool over Cloudflare's [Web Search API](https://developers.cloudflare.com/web-search/), called through the `AI` binding and billed by the account's AI Gateway. The same tool is available for the pi harness, the AI SDK, and TanStack AI.
+
+This page covers what the SDK adds on top of the API. For the binding, the providers, pricing, payment, and the error codes, see the [Web Search API docs](https://developers.cloudflare.com/web-search/).
+
+> **Beta** — this feature may have breaking changes in future releases.
+
+## Quick Start
+
+You need:
+
+- An `AI` binding: `"ai": { "binding": "AI" }` in `wrangler.jsonc`.
+- workerd 1.20260924.1 or later, which is where `env.AI.websearch()` arrived. It ships with wrangler 4.141.0 and `@cloudflare/vite-plugin` 1.60.2.
+- AI Gateway credits or a provider key on the gateway, in the account the Worker runs in. That account pays for every search. The `AI` binding always calls Cloudflare, so under `wrangler dev` searches run against, and bill, the account you are logged in to.
+
+Then add the tool to your harness. Every adapter takes the same options; the TanStack AI adapter also takes `name`, because TanStack AI tools carry their name in the definition.
+
+Pi harness:
+
+```ts
+import { webSearchTool } from "agents/websearch/pi";
+
+this.registry.install({
+  name: "tools",
+  tools: [webSearchTool({ binding: this.env.AI, provider: "exa" })]
+});
+```
+
+AI SDK:
+
+```ts
+import { webSearchTool } from "agents/websearch/ai-sdk";
+
+const result = streamText({
+  model,
+  tools: { web_search: webSearchTool({ binding: this.env.AI }) },
+  messages
+});
+```
+
+If you convert UI messages yourself, pass the same tools to `convertToModelMessages(messages, { tools })`. Without them, the AI SDK sends earlier search results back to the model as the full JSON response instead of the trimmed text. `AiSdkHarness` does this for you.
+
+TanStack AI:
+
+```ts
+import { webSearchTool } from "agents/websearch/tanstack-ai";
+
+const tools = [webSearchTool({ binding: this.env.AI })];
+```
+
+## Options
+
+The model's input is `{ query, limit? }` and nothing else. The host fixes everything that affects cost or data handling. An invalid `limit`, `maxDescriptionChars`, `timeoutMs`, or `byokAlias` throws a `RangeError` when the tool is created:
+
+| Option                | Default              | Notes                                                                                                                                                     |
+| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `binding`             | —                    | The `AI` binding. Or pass `source` instead (see [Other sources](#other-sources)).                                                                         |
+| `gateway`             | `"default"`          | AI Gateway id.                                                                                                                                            |
+| `provider`            | platform default     | `"ceramic"`, `"exa"`, or `"linkup"`. The model cannot choose or change it.                                                                                |
+| `byokAlias`           | —                    | Bill a provider key stored on the gateway. Passed through as the API defines it.                                                                          |
+| `limit`               | `5`                  | Results per search when the model does not ask for a count, and the most it gets when it asks for more. The tool description tells the model this number. |
+| `maxDescriptionChars` | `600`                | Per-result description length in the model's view. `Infinity` passes descriptions through whole.                                                          |
+| `description`         | built-in description | Replaces the tool description the model sees.                                                                                                             |
+| `timeoutMs`           | `30000`              | Give up on a search after this long, as a retryable `web_search_timeout` failure.                                                                         |
+
+## Model Interface
+
+The model gets text: a numbered list of title, URL, and description, with descriptions trimmed to `maxDescriptionChars`. Some providers return descriptions of several thousand characters per result, so the default keeps a five-result search to a few kilobytes of context.
+
+```
+3 results for "cloudflare web search api":
+
+1. Introducing the Web Search API
+https://blog.cloudflare.com/introducing-web-search-api/
+Today we are launching the Web Search API in open beta…
+
+2. …
+```
+
+The host gets the full API response, without trimming, as `WebSearchToolOutput`: `items` with their whole descriptions and every documented field, `metadata` with `requestId` and `latencyMs`, plus `provider`. Items without a URL are dropped, a missing title falls back to the URL, and fields the API does not document are left out:
+
+- **Pi**: in the tool result's `details`, as `{ ok: true, output }`. The tool is `replay: "safe"`: if a search is interrupted mid-call, for example by an eviction, pi runs it again when the session recovers, and that is a second billed search. Completed results are stored and not searched again.
+- **AI SDK**: as the return value of `execute`, so `onFinish`, UI message parts, and logs see the full response. `toModelOutput` renders the text for the model.
+- **TanStack AI**: the server tool returns the rendered text, so the host gets the same text the model does.
+
+`renderWebSearchResults(output, { maxDescriptionChars })` from `agents/websearch` is the renderer, if you want the same text elsewhere.
+
+The API has no pagination. The tool description tells the model to search again with a rephrased query when it wants more or different results.
+
+## Failures
+
+A failed search becomes a `WebSearchError` with `status`, `code`, `retryable`, and `requestId` (AI Gateway's id for the request, for the gateway log). Every error has a `code`: the API's own when it sends one, for example `web_search_payment_required`, otherwise one derived from the HTTP status, such as `web_search_rate_limited` or `web_search_unavailable`. On a runtime older than the one above, the binding has no `websearch()` and the search fails with code `web_search_unsupported_runtime`.
+
+The error's `message` is written for you, and can say to top up credits or configure a key. The model gets different text that tells it what to do next: fix the query, retry once, or carry on without search.
+
+- **Pi**: the tool returns an error result with the model's text, and `details` is `{ ok: false, message, status, code, retryable, requestId }`.
+- **AI SDK** and **TanStack AI**: the tool throws a `WebSearchError`, which is how those frameworks report tool errors. Its `message` is the model's text, and its `cause` is the original error with the API's detail.
+
+Every adapter entry point re-exports `WebSearchError`, so `instanceof` checks do not need a second import.
+
+If the harness cancels the call, the search is aborted and the abort propagates instead of becoming a failed result.
+
+## Other sources
+
+`createAIWebSearch` and `createHTTPWebSearch` from `agents/websearch` return a `WebSearchSource`: an object whose `search({ query, limit? }, { signal? })` returns the API response (`limit` defaults to 5), with no model involved. Use them from scheduled jobs, or outside Workers:
+
+```ts
+import { createHTTPWebSearch } from "agents/websearch";
+
+const search = createHTTPWebSearch({
+  accountId: env.CF_ACCOUNT_ID,
+  apiToken: env.CF_API_TOKEN,
+  provider: "linkup"
+});
+const { items } = await search.search({
+  query: "cloudflare agents sdk",
+  limit: 3
+});
+```
+
+Any `WebSearchSource` can be passed to a tool as `source` instead of `binding`. That is how tests substitute a fake, and how you wrap a source with caching or logging. Spread the source you wrap so its `provider` is kept:
+
+```ts
+webSearchTool({
+  source: {
+    search: async ({ query }) => ({
+      items: [{ url: "https://example.com", title: query }],
+      metadata: { query, requestId: "test", latencyMs: 0 }
+    })
+  }
+});
+```