agents 0.26.0 → 0.28.0

package/README.md

@@ -121,24 +121,23 @@ AI           Chat agents · Agent tools · Tool calling · MCP servers & clients
 Platform     Observability · Cross-domain auth · Resumable streams
 ```
 
-### Voice and messaging channels
+### Voice and Channels
 
-Voice and provider-neutral messaging use separate entry points so applications
-only load the integrations they import:
+Voice and Channels use separate entry points so applications only load the
+integrations they import:
 
 ```typescript
 import { withVoice } from "agents/voice";
 import { VoiceClient } from "agents/voice/client";
 import { useVoiceAgent } from "agents/voice/react";
 
-import { ChannelHost } from "agents/channels";
-import { email } from "agents/channels/email";
-import { slack } from "agents/channels/slack";
-import { telegram } from "agents/channels/telegram";
+import { ChannelGateway, Channels } from "agents/experimental/channels";
+import { email } from "agents/experimental/channels/email";
+import { slack } from "agents/experimental/channels/slack";
+import { telegram } from "agents/experimental/channels/telegram";
 ```
 
-See the [Voice](../../docs/agents/voice.md) and
-[Channels](../../docs/agents/channels.md) references.
+See the [Voice](../../docs/agents/voice.md) reference.
 
 ### State Management
 

package/dist/abortable-C1SpfVoi.js

@@ -0,0 +1,21 @@
+//#region src/web/abortable.ts
+/**
+* Shared by the `web_search` and `web_fetch` tools. Internal — not an entry
+* point.
+*/
+/** Settle with `promise`, or reject with the signal's reason once it aborts. */
+function abortable(promise, signal) {
+	if (!signal) return promise;
+	signal.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", onAbort);
+		});
+	});
+}
+//#endregion
+export { abortable as t };
+
+//# sourceMappingURL=abortable-C1SpfVoi.js.map

package/dist/abortable-C1SpfVoi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortable-C1SpfVoi.js","names":[],"sources":["../src/web/abortable.ts"],"sourcesContent":["/**\n * Shared by the `web_search` and `web_fetch` tools. Internal — not an entry\n * point.\n */\n\n/** Settle with `promise`, or reject with the signal's reason once it aborts. */\nexport function abortable<T>(\n  promise: Promise<T>,\n  signal?: AbortSignal\n): Promise<T> {\n  if (!signal) return promise;\n  signal.throwIfAborted();\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = () => reject(signal.reason);\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n    promise.then(resolve, reject).finally(() => {\n      signal.removeEventListener(\"abort\", onAbort);\n    });\n  });\n}\n"],"mappings":";;;;;;AAMA,SAAgB,UACd,SACA,QACY;CACZ,IAAI,CAAC,QAAQ,OAAO;CACpB,OAAO,eAAe;CACtB,OAAO,IAAI,SAAY,SAAS,WAAW;EACzC,MAAM,gBAAgB,OAAO,OAAO,MAAM;EAC1C,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,QAAQ,KAAK,SAAS,MAAM,CAAC,CAAC,cAAc;GAC1C,OAAO,oBAAoB,SAAS,OAAO;EAC7C,CAAC;CACH,CAAC;AACH"}

package/dist/{agent-routing-0DR0Tk2v.d.ts → agent-routing-QDcchcQP.d.ts}

@@ -8,13 +8,13 @@ import {
   u as LifecycleRouteAddress,
   v as LifecycleJobOutcome,
   x as Connection
-} from "./capability-runner-DBAnGr6L.js";
+} from "./capability-runner-BiVUtjqC.js";
 import { t as RetryOptions } from "./retries-CV6AkXmQ.js";
 import {
   r as LifecycleRouteEnvelope,
   t as Lifecycle
-} from "./durable-object-lifecycle-HhgOMWq9.js";
-import { n as CurrentAgentContext } from "./current-agent-vAk_5JMt.js";
+} from "./durable-object-lifecycle-DOI_bzCH.js";
+import { n as CurrentAgentContext } from "./current-agent-CKgT5d1O.js";
 import { t as AgentEmail } from "./internal_context-BlxFEWfn.js";
 import { r as EmailResolver, s as SendEmailOptions } from "./email-7TatiTnl.js";
 import {
@@ -22,7 +22,7 @@ import {
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
 } from "./index-YSKgfgg9.js";
-import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-Tmf1vgKz.js";
+import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-DfsUcpc3.js";
 import {
   a as McpAuthContext,
   c as CORSOptions,
@@ -41,10 +41,10 @@ import {
   i as Schedule,
   o as ScheduleOptions,
   t as Scheduler
-} from "./scheduler-RdACNXDP.js";
+} from "./scheduler-BCLESHSC.js";
 import { i as QueueItem } from "./types-BA4anrjI.js";
-import { l as TaskHandlers, r as Tasks } from "./tasks-9YxYtByh.js";
-import { t as State } from "./index-BreL0YrQ.js";
+import { l as TaskHandlers, r as Tasks } from "./tasks-E89KdwkS.js";
+import { t as State } from "./index-BEL3ZV-s.js";
 import { t as CallableMetadata } from "./callable-decorator-DP__HhBA.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import {
@@ -2763,8 +2763,7 @@ type MCPServerFilter = {
 };
 /**
  * A Durable Object capability that persists and aggregates MCP client
- * connections. Installing it directly on a Lifecycle (outside `agent.mcp`)
- * is experimental: that capability surface may change before stabilizing.
+ * connections. Install it on any Lifecycle, or use `agent.mcp` on an Agent.
  */
 declare class MCPClientManager extends LifecycleCapability {
   private readonly _name;
@@ -3087,6 +3086,11 @@ declare class MCPClientManager extends LifecycleCapability {
    * Remove an MCP server - closes connection if active and removes from storage.
    */
   removeServer(serverId: string): Promise<void>;
+  /**
+   * Rebuild a server's auth provider from its stored row, as restore does,
+   * for a server with no live connection.
+   */
+  private authProviderFromStorage;
   /**
    * List all MCP servers from storage
    */
@@ -4516,8 +4520,6 @@ declare class Agent<
 > extends DurableObject<Env> {
   /**
    * Runtime lifecycle and reusable durable capabilities for this Agent.
-   *
-   * @experimental The API surface may change before stabilizing.
    */
   readonly lifecycle: Lifecycle<Env, Props>;
   /**
@@ -4659,10 +4661,8 @@ declare class Agent<
   private _ParentClass;
   /**
    * Durable scheduling capability installed into this Agent's Lifecycle.
-   *
-   * @experimental The API surface may change before stabilizing. Agent's
-   * schedule()/scheduleEvery()/getScheduleById()/listSchedules()/
-   * cancelSchedule() methods are the stable surface.
+   * Agent's schedule()/scheduleEvery()/getScheduleById()/listSchedules()/
+   * cancelSchedule() methods delegate to it.
    */
   readonly scheduler: Scheduler;
   /**
@@ -7035,4 +7035,4 @@ export {
   AgentToolEventState as z,
   MCPClientOAuthResult as zt
 };
-//# sourceMappingURL=agent-routing-0DR0Tk2v.d.ts.map
+//# sourceMappingURL=agent-routing-QDcchcQP.d.ts.map

package/dist/agent-routing.d.ts

@@ -4,7 +4,7 @@ import {
   n as AgentOptions,
   r as RoutingRetryOptions,
   t as AgentGetOptions
-} from "./agent-routing-0DR0Tk2v.js";
+} from "./agent-routing-QDcchcQP.js";
 export {
   AgentGetOptions,
   AgentOptions,

package/dist/agent-tool-types.d.ts

@@ -27,7 +27,7 @@ import {
   rt as RunAgentToolResult,
   tt as DetachedRunAgentToolResult,
   z as AgentToolEventState
-} from "./agent-routing-0DR0Tk2v.js";
+} from "./agent-routing-QDcchcQP.js";
 export {
   AGENT_TOOL_MILESTONE_PART,
   AGENT_TOOL_PROGRESS_PART,

package/dist/{agent-tools-YrATZJu2.d.ts → agent-tools-DHL2XI7u.d.ts}

@@ -4,7 +4,7 @@ import {
   W as AgentToolProgress,
   Z as AgentToolStoredChunk,
   z as AgentToolEventState
-} from "./agent-routing-0DR0Tk2v.js";
+} from "./agent-routing-QDcchcQP.js";
 
 //#region src/chat/agent-tools.d.ts
 type AgentToolProgressEmitResult = "emitted" | "coalesced" | "inactive";
@@ -144,4 +144,4 @@ export {
   interceptAgentToolBroadcast as s,
   AgentToolBroadcastHooks as t
 };
-//# sourceMappingURL=agent-tools-YrATZJu2.d.ts.map
+//# sourceMappingURL=agent-tools-DHL2XI7u.d.ts.map

package/dist/agent-tools.d.ts

@@ -20,7 +20,7 @@ import {
   rt as RunAgentToolResult,
   tt as DetachedRunAgentToolResult,
   z as AgentToolEventState
-} from "./agent-routing-0DR0Tk2v.js";
+} from "./agent-routing-QDcchcQP.js";
 import { FlexibleSchema, InferSchema, Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/ai-ahruGw7e.d.ts

@@ -0,0 +1,239 @@
+import {
+  d as BrowserBinding,
+  n as BrowserSessionStore
+} from "./session-store-DoPY12xM.js";
+import {
+  l as QuickActionBinding,
+  r as BrowserConnectorSessionOptions,
+  t as BrowserConnector,
+  u as QuickActionCommonOptions
+} from "./connector-DEXzVoaY.js";
+import { ToolSet } from "ai";
+import { CodemodeRuntimeHandle } from "@cloudflare/codemode";
+
+//#region src/browser/ai.d.ts
+interface CreateBrowserToolsOptions {
+  /**
+   * Durable Object state. The codemode runtime that backs the browser tool
+   * lives in a facet of this DO, and browser session ids are stored in its
+   * storage — so the tool must be created from inside a Durable Object
+   * (e.g. an Agent).
+   *
+   * Optional: when omitted, it is resolved from the current Agent via
+   * `getCurrentAgent()`, so inside an Agent method you can just pass `browser`
+   * and `loader`. Pass it explicitly outside an Agent context.
+   *
+   * The worker must export the `CodemodeRuntime` class (the
+   * `@cloudflare/codemode/vite` plugin does this automatically, or add
+   * `export { CodemodeRuntime } from "@cloudflare/codemode"` to your entry).
+   */
+  ctx?: DurableObjectState;
+  /**
+   * WorkerLoader binding for sandboxed code execution.
+   *
+   * Requires `"worker_loaders": [{ "binding": "LOADER" }]` in wrangler.jsonc.
+   */
+  loader: WorkerLoader;
+  /**
+   * Browser Rendering binding (Fetcher).
+   *
+   * This is the primary way to connect — works both locally in
+   * `wrangler dev` and when deployed to Cloudflare Workers.
+   *
+   * Requires `"browser": { "binding": "BROWSER" }` in wrangler.jsonc.
+   */
+  browser?: BrowserBinding;
+  /**
+   * Optional CDP base URL override (e.g. `http://localhost:9222`).
+   *
+   * Use when connecting to a manually managed Chrome instance or
+   * a remote CDP endpoint behind a tunnel.
+   */
+  cdpUrl?: string;
+  /**
+   * Headers to send with CDP URL discovery requests.
+   * Useful when the CDP endpoint requires authentication
+   * (e.g. Cloudflare Access headers).
+   */
+  cdpHeaders?: Record<string, string>;
+  /**
+   * Browser session lifecycle (binding-backed only). Defaults to one fresh
+   * session per codemode execution (`one-shot`).
+   */
+  session?: BrowserConnectorSessionOptions;
+  /**
+   * Durable store for Browser Run session ids. Defaults to a
+   * {@link DurableBrowserSessionStore} over `ctx.storage`.
+   */
+  store?: BrowserSessionStore;
+  /**
+   * Sandbox execution timeout in milliseconds. Defaults to 30000 (30s).
+   * Also used as the per-CDP-command timeout.
+   */
+  timeout?: number;
+  /**
+   * Codemode runtime name — the durable identity of the tool's executions
+   * and snippets. Defaults to `"browser"`.
+   */
+  name?: string;
+  /**
+   * Also expose stateless {@link createQuickActionTools | Quick Action} tools
+   * (`browser_markdown`, `browser_extract`, …) alongside the durable
+   * `browser_execute` tool.
+   *
+   * Enabled by default whenever a Browser Run `browser` binding is available
+   * (they share it), except when `session.browser` selects Kitesurf because
+   * the binding RPC cannot select that engine. Pass `true` or an object to
+   * explicitly add Chromium Quick Actions alongside Kitesurf, or `false` to
+   * disable them. The Quick Action binding defaults to `browser`; override it via
+   * `quickActions.browser`. When only `cdpUrl` is set (no binding), the
+   * defaults are skipped silently — pass `quickActions: { browser }` to force
+   * them.
+   */
+  quickActions?:
+    | boolean
+    | {
+        browser?: QuickActionBinding;
+        actions?: QuickActionToolName[];
+        maxChars?: number;
+        options?: QuickActionCommonOptions;
+      };
+}
+/**
+ * The browser tool's moving parts, for hosts that need more than the tools:
+ *
+ * - `runtime` — the codemode runtime handle (approve/reject paused runs,
+ *   `expirePaused`, audit via `executions()`, snippets).
+ * - `connector` — host-side session helpers: `sessionInfo()`,
+ *   `closeSession()`, and `sweep()` for a recurring cleanup task.
+ * - `tools` — what `createBrowserTools` returns.
+ */
+interface BrowserRuntime {
+  runtime: CodemodeRuntimeHandle;
+  connector: BrowserConnector;
+  tools: ToolSet;
+}
+/**
+ * Create the browser codemode runtime: the `browser_execute` tool plus the
+ * runtime handle and connector for host-side wiring (approvals, session info,
+ * sweeps).
+ *
+ * @example
+ * ```ts
+ * export class MyAgent extends Agent<Env> {
+ *   get browser() {
+ *     return createBrowserRuntime({
+ *       ctx: this.ctx,
+ *       browser: this.env.BROWSER,
+ *       loader: this.env.LOADER,
+ *       session: { mode: "dynamic" }
+ *     });
+ *   }
+ *
+ *   @callable()
+ *   async closeBrowserSession() {
+ *     await this.browser.connector.closeSession();
+ *   }
+ * }
+ * ```
+ */
+declare function createBrowserRuntime(
+  options: CreateBrowserToolsOptions
+): BrowserRuntime;
+/**
+ * Create AI SDK tools for browser automation via CDP code mode.
+ *
+ * Returns a `ToolSet` with a single durable `browser_execute` tool backed by
+ * a codemode runtime: the model writes TypeScript against the `cdp` connector
+ * (`cdp.send`, `cdp.attachToTarget`, `cdp.spec`, …), executions are recorded
+ * for abort-and-replay, and browser sessions survive pauses.
+ *
+ * @example
+ * ```ts
+ * import { createBrowserTools } from "agents/browser/ai";
+ * import { generateText } from "ai";
+ *
+ * // inside a Durable Object / Agent:
+ * const browserTools = createBrowserTools({
+ *   ctx: this.ctx,
+ *   browser: this.env.BROWSER,
+ *   loader: this.env.LOADER,
+ * });
+ *
+ * const result = await generateText({
+ *   model,
+ *   tools: { ...browserTools, ...otherTools },
+ *   messages,
+ * });
+ * ```
+ */
+declare function createBrowserTools(
+  options: CreateBrowserToolsOptions
+): ToolSet;
+/** A Quick Action exposed as an AI SDK tool. */
+type QuickActionToolName =
+  | "markdown"
+  | "extract"
+  | "links"
+  | "scrape"
+  | "content";
+interface CreateQuickActionToolsOptions {
+  /**
+   * Browser Run binding with Quick Actions support (`env.BROWSER`). Requires a
+   * Worker `compatibility_date` of `2026-03-24`+ and `remote: true` for local
+   * `wrangler dev`.
+   */
+  browser: QuickActionBinding;
+  /**
+   * Which tools to expose. Defaults to the text-returning, model-friendly set
+   * (`markdown`, `extract`, `links`, `scrape`). `content` (raw HTML) is opt-in
+   * since it is large and rarely what a model wants.
+   */
+  actions?: QuickActionToolName[];
+  /**
+   * Bound every result to roughly this many characters before returning it to
+   * the model, to protect the context window, preserving each result's shape:
+   * text (markdown/content) is truncated to a string, oversized arrays
+   * (links/scrape) are trimmed but stay arrays, and only an opaque oversized
+   * object degrades to a truncated-preview summary. Set to `0` to disable.
+   * Defaults to 50000.
+   */
+  maxChars?: number;
+  /**
+   * Common Browser Run options merged into every request — e.g. `cookies`,
+   * `authenticate`, or `setExtraHTTPHeaders` for authenticated pages, and
+   * `gotoOptions` / `viewport` for JavaScript-heavy pages. The model only ever
+   * supplies the page (`url`/`html`) and action-specific fields; these
+   * host-supplied options are never exposed to it.
+   */
+  options?: QuickActionCommonOptions;
+}
+/**
+ * Create AI SDK tools for Browser Run [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/):
+ * stateless one-shot browsing (read a page as Markdown, extract structured
+ * data with AI, list links, scrape elements). Unlike `createBrowserTools`,
+ * these need only the `browser` binding — no Durable Object, loader, or
+ * sandbox — so they work from any Worker.
+ *
+ * @example
+ * ```ts
+ * import { createQuickActionTools } from "agents/browser/ai";
+ *
+ * const tools = createQuickActionTools({ browser: this.env.BROWSER });
+ * const result = await generateText({ model, tools, messages });
+ * ```
+ */
+declare function createQuickActionTools(
+  options: CreateQuickActionToolsOptions
+): ToolSet;
+//#endregion
+export {
+  createBrowserRuntime as a,
+  QuickActionToolName as i,
+  CreateBrowserToolsOptions as n,
+  createBrowserTools as o,
+  CreateQuickActionToolsOptions as r,
+  createQuickActionTools as s,
+  BrowserRuntime as t
+};
+//# sourceMappingURL=ai-ahruGw7e.d.ts.map