agents 0.14.5 → 0.16.0

package/dist/browser/ai.js

@@ -1,21 +1,85 @@
-import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-wyII629d.js";
-import { tool } from "ai";
-import { z } from "zod";
+import { i as DurableBrowserSessionStore, t as BrowserConnector } from "../connector-D6yYzYHg.js";
+import { DynamicWorkerExecutor, createCodemodeRuntime, truncateResult } from "@cloudflare/codemode";
 //#region src/browser/ai.ts
+let didWarnExperimental = false;
+function connectorOptions(options) {
+	if (options.cdpUrl) return {
+		cdpUrl: options.cdpUrl,
+		cdpHeaders: options.cdpHeaders,
+		timeout: options.timeout
+	};
+	if (!options.browser) throw new Error("Either 'browser' (Fetcher binding) or 'cdpUrl' must be provided");
+	return {
+		browser: options.browser,
+		store: options.store ?? new DurableBrowserSessionStore(options.ctx.storage),
+		session: options.session,
+		timeout: options.timeout
+	};
+}
+/**
+* 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();
+*   }
+* }
+* ```
+*/
+function createBrowserRuntime(options) {
+	if (!didWarnExperimental) {
+		didWarnExperimental = true;
+		console.warn("[agents/browser] Browser tools are experimental and may change in a future release.");
+	}
+	const connector = new BrowserConnector(options.ctx, connectorOptions(options));
+	const runtime = createCodemodeRuntime({
+		ctx: options.ctx,
+		executor: new DynamicWorkerExecutor({
+			loader: options.loader,
+			timeout: options.timeout
+		}),
+		connectors: [connector],
+		name: options.name ?? "browser",
+		transformResult: truncateResult
+	});
+	return {
+		runtime,
+		connector,
+		tools: { browser_execute: runtime.tool() }
+	};
+}
 /**
 * Create AI SDK tools for browser automation via CDP code mode.
 *
-* Returns a `ToolSet` with `search` (query the CDP spec) and
-* `execute` (run CDP commands against a live browser).
+* 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({
-*   browser: env.BROWSER,
-*   loader: env.LOADER,
+*   ctx: this.ctx,
+*   browser: this.env.BROWSER,
+*   loader: this.env.LOADER,
 * });
 *
 * const result = await generateText({
@@ -26,29 +90,9 @@ import { z } from "zod";
 * ```
 */
 function createBrowserTools(options) {
-	const handlers = createBrowserToolHandlers(options);
-	return {
-		browser_search: tool({
-			description: SEARCH_DESCRIPTION,
-			inputSchema: z.object({ code: z.string().describe("JavaScript async arrow function that queries the CDP spec") }),
-			execute: async ({ code }) => {
-				const result = await handlers.search(code);
-				if (result.isError) throw new Error(result.text);
-				return result.text;
-			}
-		}),
-		browser_execute: tool({
-			description: EXECUTE_DESCRIPTION,
-			inputSchema: z.object({ code: z.string().describe("JavaScript async arrow function that uses the cdp helper") }),
-			execute: async ({ code }) => {
-				const result = await handlers.execute(code);
-				if (result.isError) throw new Error(result.text);
-				return result.text;
-			}
-		})
-	};
+	return createBrowserRuntime(options).tools;
 }
 //#endregion
-export { createBrowserTools };
+export { createBrowserRuntime, createBrowserTools };
 
 //# sourceMappingURL=ai.js.map

package/dist/browser/ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai.js","names":[],"sources":["../../src/browser/ai.ts"],"sourcesContent":["import { tool } from \"ai\";\nimport type { ToolSet } from \"ai\";\nimport { z } from \"zod\";\nimport {\n  createBrowserToolHandlers,\n  SEARCH_DESCRIPTION,\n  EXECUTE_DESCRIPTION,\n  type BrowserToolsOptions\n} from \"./shared\";\n\nexport type { BrowserToolsOptions } from \"./shared\";\n\n/**\n * Create AI SDK tools for browser automation via CDP code mode.\n *\n * Returns a `ToolSet` with `search` (query the CDP spec) and\n * `execute` (run CDP commands against a live browser).\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/ai\";\n * import { generateText } from \"ai\";\n *\n * const browserTools = createBrowserTools({\n *   browser: env.BROWSER,\n *   loader: env.LOADER,\n * });\n *\n * const result = await generateText({\n *   model,\n *   tools: { ...browserTools, ...otherTools },\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(options: BrowserToolsOptions): ToolSet {\n  const handlers = createBrowserToolHandlers(options);\n\n  return {\n    browser_search: tool({\n      description: SEARCH_DESCRIPTION,\n      inputSchema: z.object({\n        code: z\n          .string()\n          .describe(\"JavaScript async arrow function that queries the CDP spec\")\n      }),\n      execute: async ({ code }) => {\n        const result = await handlers.search(code);\n        if (result.isError) {\n          throw new Error(result.text);\n        }\n        return result.text;\n      }\n    }),\n\n    browser_execute: tool({\n      description: EXECUTE_DESCRIPTION,\n      inputSchema: z.object({\n        code: z\n          .string()\n          .describe(\"JavaScript async arrow function that uses the cdp helper\")\n      }),\n      execute: async ({ code }) => {\n        const result = await handlers.execute(code);\n        if (result.isError) {\n          throw new Error(result.text);\n        }\n        return result.text;\n      }\n    })\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,mBAAmB,SAAuC;CACxE,MAAM,WAAW,0BAA0B,OAAO;CAElD,OAAO;EACL,gBAAgB,KAAK;GACnB,aAAa;GACb,aAAa,EAAE,OAAO,EACpB,MAAM,EACH,OAAO,CAAC,CACR,SAAS,2DAA2D,EACzE,CAAC;GACD,SAAS,OAAO,EAAE,WAAW;IAC3B,MAAM,SAAS,MAAM,SAAS,OAAO,IAAI;IACzC,IAAI,OAAO,SACT,MAAM,IAAI,MAAM,OAAO,IAAI;IAE7B,OAAO,OAAO;GAChB;EACF,CAAC;EAED,iBAAiB,KAAK;GACpB,aAAa;GACb,aAAa,EAAE,OAAO,EACpB,MAAM,EACH,OAAO,CAAC,CACR,SAAS,0DAA0D,EACxE,CAAC;GACD,SAAS,OAAO,EAAE,WAAW;IAC3B,MAAM,SAAS,MAAM,SAAS,QAAQ,IAAI;IAC1C,IAAI,OAAO,SACT,MAAM,IAAI,MAAM,OAAO,IAAI;IAE7B,OAAO,OAAO;GAChB;EACF,CAAC;CACH;AACF"}
+{"version":3,"file":"ai.js","names":[],"sources":["../../src/browser/ai.ts"],"sourcesContent":["import type { ToolSet } from \"ai\";\nimport {\n  createCodemodeRuntime,\n  DynamicWorkerExecutor,\n  truncateResult,\n  type CodemodeRuntimeHandle\n} from \"@cloudflare/codemode\";\nimport type { BrowserBinding } from \"./browser-run\";\nimport {\n  BrowserConnector,\n  type BrowserConnectorOptions,\n  type BrowserConnectorSessionOptions\n} from \"./connector\";\nimport {\n  DurableBrowserSessionStore,\n  type BrowserSessionStore\n} from \"./session-manager\";\n\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Durable Object state. The codemode runtime that backs the browser tool\n   * lives in a facet of this DO, and browser session ids are stored in its\n   * storage — so the tool must be created from inside a Durable Object\n   * (e.g. an Agent).\n   *\n   * The worker must export the `CodemodeRuntime` class (the\n   * `@cloudflare/codemode/vite` plugin does this automatically, or add\n   * `export { CodemodeRuntime } from \"@cloudflare/codemode\"` to your entry).\n   */\n  ctx: DurableObjectState;\n\n  /**\n   * WorkerLoader binding for sandboxed code execution.\n   *\n   * Requires `\"worker_loaders\": [{ \"binding\": \"LOADER\" }]` in wrangler.jsonc.\n   */\n  loader: WorkerLoader;\n\n  /**\n   * Browser Rendering binding (Fetcher).\n   *\n   * This is the primary way to connect — works both locally in\n   * `wrangler dev` and when deployed to Cloudflare Workers.\n   *\n   * Requires `\"browser\": { \"binding\": \"BROWSER\" }` in wrangler.jsonc.\n   */\n  browser?: BrowserBinding;\n\n  /**\n   * Optional CDP base URL override (e.g. `http://localhost:9222`).\n   *\n   * Use when connecting to a manually managed Chrome instance or\n   * a remote CDP endpoint behind a tunnel.\n   */\n  cdpUrl?: string;\n\n  /**\n   * Headers to send with CDP URL discovery requests.\n   * Useful when the CDP endpoint requires authentication\n   * (e.g. Cloudflare Access headers).\n   */\n  cdpHeaders?: Record<string, string>;\n\n  /**\n   * Browser session lifecycle (binding-backed only). Defaults to one fresh\n   * session per codemode execution (`one-shot`).\n   */\n  session?: BrowserConnectorSessionOptions;\n\n  /**\n   * Durable store for Browser Run session ids. Defaults to a\n   * {@link DurableBrowserSessionStore} over `ctx.storage`.\n   */\n  store?: BrowserSessionStore;\n\n  /**\n   * Sandbox execution timeout in milliseconds. Defaults to 30000 (30s).\n   * Also used as the per-CDP-command timeout.\n   */\n  timeout?: number;\n\n  /**\n   * Codemode runtime name — the durable identity of the tool's executions\n   * and snippets. Defaults to `\"browser\"`.\n   */\n  name?: string;\n}\n\n/**\n * The browser tool's moving parts, for hosts that need more than the tools:\n *\n * - `runtime` — the codemode runtime handle (approve/reject paused runs,\n *   `expirePaused`, audit via `executions()`, snippets).\n * - `connector` — host-side session helpers: `sessionInfo()`,\n *   `closeSession()`, and `sweep()` for a recurring cleanup task.\n * - `tools` — what `createBrowserTools` returns.\n */\nexport interface BrowserRuntime {\n  runtime: CodemodeRuntimeHandle;\n  connector: BrowserConnector;\n  tools: ToolSet;\n}\n\nlet didWarnExperimental = false;\n\nfunction connectorOptions(\n  options: CreateBrowserToolsOptions\n): BrowserConnectorOptions {\n  if (options.cdpUrl) {\n    return {\n      cdpUrl: options.cdpUrl,\n      cdpHeaders: options.cdpHeaders,\n      timeout: options.timeout\n    };\n  }\n  if (!options.browser) {\n    throw new Error(\n      \"Either 'browser' (Fetcher binding) or 'cdpUrl' must be provided\"\n    );\n  }\n  return {\n    browser: options.browser,\n    store: options.store ?? new DurableBrowserSessionStore(options.ctx.storage),\n    session: options.session,\n    timeout: options.timeout\n  };\n}\n\n/**\n * Create the browser codemode runtime: the `browser_execute` tool plus the\n * runtime handle and connector for host-side wiring (approvals, session info,\n * sweeps).\n *\n * @example\n * ```ts\n * export class MyAgent extends Agent<Env> {\n *   get browser() {\n *     return createBrowserRuntime({\n *       ctx: this.ctx,\n *       browser: this.env.BROWSER,\n *       loader: this.env.LOADER,\n *       session: { mode: \"dynamic\" }\n *     });\n *   }\n *\n *   @callable()\n *   async closeBrowserSession() {\n *     await this.browser.connector.closeSession();\n *   }\n * }\n * ```\n */\nexport function createBrowserRuntime(\n  options: CreateBrowserToolsOptions\n): BrowserRuntime {\n  if (!didWarnExperimental) {\n    didWarnExperimental = true;\n    console.warn(\n      \"[agents/browser] Browser tools are experimental and may change in a future release.\"\n    );\n  }\n\n  const connector = new BrowserConnector(\n    options.ctx,\n    connectorOptions(options)\n  );\n  const runtime = createCodemodeRuntime({\n    ctx: options.ctx,\n    executor: new DynamicWorkerExecutor({\n      loader: options.loader,\n      timeout: options.timeout\n    }),\n    connectors: [connector],\n    name: options.name ?? \"browser\",\n    transformResult: truncateResult\n  });\n\n  return {\n    runtime,\n    connector,\n    tools: { browser_execute: runtime.tool() }\n  };\n}\n\n/**\n * Create AI SDK tools for browser automation via CDP code mode.\n *\n * Returns a `ToolSet` with a single durable `browser_execute` tool backed by\n * a codemode runtime: the model writes TypeScript against the `cdp` connector\n * (`cdp.send`, `cdp.attachToTarget`, `cdp.spec`, …), executions are recorded\n * for abort-and-replay, and browser sessions survive pauses.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/ai\";\n * import { generateText } from \"ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const result = await generateText({\n *   model,\n *   tools: { ...browserTools, ...otherTools },\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ToolSet {\n  return createBrowserRuntime(options).tools;\n}\n"],"mappings":";;;AAuGA,IAAI,sBAAsB;AAE1B,SAAS,iBACP,SACyB;CACzB,IAAI,QAAQ,QACV,OAAO;EACL,QAAQ,QAAQ;EAChB,YAAY,QAAQ;EACpB,SAAS,QAAQ;CACnB;CAEF,IAAI,CAAC,QAAQ,SACX,MAAM,IAAI,MACR,iEACF;CAEF,OAAO;EACL,SAAS,QAAQ;EACjB,OAAO,QAAQ,SAAS,IAAI,2BAA2B,QAAQ,IAAI,OAAO;EAC1E,SAAS,QAAQ;EACjB,SAAS,QAAQ;CACnB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,qBACd,SACgB;CAChB,IAAI,CAAC,qBAAqB;EACxB,sBAAsB;EACtB,QAAQ,KACN,qFACF;CACF;CAEA,MAAM,YAAY,IAAI,iBACpB,QAAQ,KACR,iBAAiB,OAAO,CAC1B;CACA,MAAM,UAAU,sBAAsB;EACpC,KAAK,QAAQ;EACb,UAAU,IAAI,sBAAsB;GAClC,QAAQ,QAAQ;GAChB,SAAS,QAAQ;EACnB,CAAC;EACD,YAAY,CAAC,SAAS;EACtB,MAAM,QAAQ,QAAQ;EACtB,iBAAiB;CACnB,CAAC;CAED,OAAO;EACL;EACA;EACA,OAAO,EAAE,iBAAiB,QAAQ,KAAK,EAAE;CAC3C;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,mBACd,SACS;CACT,OAAO,qBAAqB,OAAO,CAAC,CAAC;AACvC"}

package/dist/browser/index.d.ts

@@ -1,82 +1,94 @@
 import {
-  a as createBrowserToolHandlers,
-  i as ToolResult,
-  n as EXECUTE_DESCRIPTION,
-  r as SEARCH_DESCRIPTION,
-  t as BrowserToolsOptions
-} from "../shared-4CAYLCTO.js";
+  C as CdpSendOptions,
+  S as CdpAttachOptions,
+  T as connectUrl,
+  _ as connectBrowser,
+  a as BrowserConnectorSweepResult,
+  b as deleteBrowserSession,
+  c as BrowserSessionStore,
+  d as StoredBrowserSession,
+  f as BrowserBinding,
+  g as ConnectBrowserOptions,
+  h as BrowserTargetInfo,
+  i as BrowserConnectorSweepOptions,
+  l as DEFAULT_SWEEP_IDLE_MS,
+  m as BrowserSessionInfo,
+  n as BrowserConnectorOptions,
+  o as DEFAULT_EXEC_SWEEP_IDLE_MS,
+  p as BrowserRenderingError,
+  r as BrowserConnectorSessionOptions,
+  s as BrowserSessionLock,
+  t as BrowserConnector,
+  u as DurableBrowserSessionStore,
+  v as connectBrowserSession,
+  w as CdpSession,
+  x as listBrowserTargets,
+  y as createBrowserSession
+} from "../connector-DXursxV5.js";
+import { CodemodeRuntime } from "@cloudflare/codemode";
 
-//#region src/browser/cdp-session.d.ts
-interface DebugEntry {
-  at: string;
-  type: string;
-  [key: string]: unknown;
+//#region src/browser/spec.d.ts
+interface SearchableCdpSpec {
+  domains: Array<{
+    name: string;
+    description?: string;
+    commands: Array<{
+      name: string;
+      method: string;
+      description?: string;
+    }>;
+    events: Array<{
+      name: string;
+      event: string;
+      description?: string;
+    }>;
+    types: Array<{
+      id: string;
+      name: string;
+      description?: string;
+    }>;
+  }>;
 }
-interface CdpSendOptions {
-  timeoutMs?: number;
-  sessionId?: string;
+interface CdpSpecSource {
+  /** Browser Rendering binding (Fetcher) — used in production */
+  browser?: BrowserBinding;
+  /** CDP base URL override (e.g. http://localhost:9222) */
+  cdpUrl?: string;
+  /** Headers to send with CDP URL discovery requests */
+  cdpHeaders?: Record<string, string>;
 }
-interface CdpAttachOptions {
-  timeoutMs?: number;
-}
-/**
- * A CDP session over an open WebSocket. Manages command correlation,
- * timeouts, target sessions, and a debug event ring buffer.
- *
- * Used host-side (not in the sandbox) — the sandbox calls into this
- * via DynamicWorkerExecutor's ToolDispatcher RPC.
- */
-declare class CdpSession {
-  #private;
-  constructor(
-    socket: WebSocket,
-    defaultTimeoutMs?: number,
-    dispose?: () => void
-  );
-  send(
-    method: string,
-    params?: unknown,
-    options?: CdpSendOptions
-  ): Promise<unknown>;
-  attachToTarget(targetId: string, options?: CdpAttachOptions): Promise<string>;
-  getDebugLog(limit?: number): DebugEntry[];
-  clearDebugLog(): void;
-  close(): void;
-}
-/**
- * Connect to a browser via the Browser Rendering binding (Fetcher).
- * Establishes a CDP WebSocket through the binding's fetch interface.
- */
-declare function connectBrowser(
-  browser: Fetcher,
-  timeoutMs?: number
-): Promise<CdpSession>;
-/**
- * Connect to a browser via a CDP base URL (e.g. http://localhost:9222).
- * Discovers the WebSocket debugger URL via /json/version,
- * rewrites localhost URLs to the base URL host, and opens the WebSocket.
- *
- * Useful for local development with `chrome --remote-debugging-port=9222`
- * or when connecting through a tunnel.
- */
-declare function connectUrl(
-  baseUrl: string,
-  options?: {
-    timeoutMs?: number;
-    headers?: Record<string, string>;
-  }
-): Promise<CdpSession>;
+/** Load the (cached) searchable CDP spec for a browser source. */
+declare function loadCdpSpec(source: CdpSpecSource): Promise<SearchableCdpSpec>;
 //#endregion
 export {
-  type BrowserToolsOptions,
+  type BrowserBinding,
+  BrowserConnector,
+  type BrowserConnectorOptions,
+  type BrowserConnectorSessionOptions,
+  type BrowserConnectorSweepOptions,
+  type BrowserConnectorSweepResult,
+  BrowserRenderingError,
+  type BrowserSessionInfo,
+  type BrowserSessionLock,
+  type BrowserSessionStore,
+  type BrowserTargetInfo,
   type CdpAttachOptions,
   type CdpSendOptions,
   CdpSession,
-  EXECUTE_DESCRIPTION,
-  SEARCH_DESCRIPTION,
-  type ToolResult,
+  type CdpSpecSource,
+  CodemodeRuntime,
+  type ConnectBrowserOptions,
+  DEFAULT_EXEC_SWEEP_IDLE_MS,
+  DEFAULT_SWEEP_IDLE_MS,
+  DurableBrowserSessionStore,
+  type SearchableCdpSpec,
+  type StoredBrowserSession,
   connectBrowser,
+  connectBrowserSession,
   connectUrl,
-  createBrowserToolHandlers
+  createBrowserSession,
+  deleteBrowserSession,
+  listBrowserTargets,
+  loadCdpSpec
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.js

@@ -1,2 +1,3 @@
-import { a as connectBrowser, i as CdpSession, n as SEARCH_DESCRIPTION, o as connectUrl, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-wyII629d.js";
-export { CdpSession, EXECUTE_DESCRIPTION, SEARCH_DESCRIPTION, connectBrowser, connectUrl, createBrowserToolHandlers };
+import { a as loadCdpSpec, c as connectBrowserSession, d as listBrowserTargets, f as CdpSession, i as DurableBrowserSessionStore, l as createBrowserSession, n as DEFAULT_EXEC_SWEEP_IDLE_MS, o as BrowserRenderingError, p as connectUrl, r as DEFAULT_SWEEP_IDLE_MS, s as connectBrowser, t as BrowserConnector, u as deleteBrowserSession } from "../connector-D6yYzYHg.js";
+import { CodemodeRuntime } from "@cloudflare/codemode";
+export { BrowserConnector, BrowserRenderingError, CdpSession, CodemodeRuntime, DEFAULT_EXEC_SWEEP_IDLE_MS, DEFAULT_SWEEP_IDLE_MS, DurableBrowserSessionStore, connectBrowser, connectBrowserSession, connectUrl, createBrowserSession, deleteBrowserSession, listBrowserTargets, loadCdpSpec };

package/dist/browser/tanstack-ai.d.ts

@@ -1,21 +1,25 @@
-import { t as BrowserToolsOptions } from "../shared-4CAYLCTO.js";
+import { CreateBrowserToolsOptions } from "./ai.js";
 import { ServerTool } from "@tanstack/ai";
 
 //#region src/browser/tanstack-ai.d.ts
 /**
  * Create TanStack AI tools for browser automation via CDP code mode.
  *
- * Returns an array of `ServerTool`s: `browser_search` (query the CDP spec)
- * and `browser_execute` (run CDP commands against a live browser).
+ * Returns an array with a single durable `browser_execute` `ServerTool`
+ * backed by the same codemode runtime as `agents/browser/ai` — the model
+ * writes TypeScript against the `cdp` connector and browser sessions
+ * survive pauses.
  *
  * @example
  * ```ts
  * import { createBrowserTools } from "agents/browser/tanstack-ai";
  * import { chat } from "@tanstack/ai";
  *
+ * // inside a Durable Object / Agent:
  * const browserTools = createBrowserTools({
- *   browser: env.BROWSER,
- *   loader: env.LOADER,
+ *   ctx: this.ctx,
+ *   browser: this.env.BROWSER,
+ *   loader: this.env.LOADER,
  * });
  *
  * const stream = chat({
@@ -25,7 +29,9 @@ import { ServerTool } from "@tanstack/ai";
  * });
  * ```
  */
-declare function createBrowserTools(options: BrowserToolsOptions): ServerTool[];
+declare function createBrowserTools(
+  options: CreateBrowserToolsOptions
+): ServerTool[];
 //#endregion
-export { type BrowserToolsOptions, createBrowserTools };
+export { type CreateBrowserToolsOptions, createBrowserTools };
 //# sourceMappingURL=tanstack-ai.d.ts.map

package/dist/browser/tanstack-ai.js

@@ -1,21 +1,25 @@
-import { n as SEARCH_DESCRIPTION, r as createBrowserToolHandlers, t as EXECUTE_DESCRIPTION } from "../shared-wyII629d.js";
+import { createBrowserRuntime } from "./ai.js";
 import { z } from "zod";
 import { toolDefinition } from "@tanstack/ai";
 //#region src/browser/tanstack-ai.ts
 /**
 * Create TanStack AI tools for browser automation via CDP code mode.
 *
-* Returns an array of `ServerTool`s: `browser_search` (query the CDP spec)
-* and `browser_execute` (run CDP commands against a live browser).
+* Returns an array with a single durable `browser_execute` `ServerTool`
+* backed by the same codemode runtime as `agents/browser/ai` — the model
+* writes TypeScript against the `cdp` connector and browser sessions
+* survive pauses.
 *
 * @example
 * ```ts
 * import { createBrowserTools } from "agents/browser/tanstack-ai";
 * import { chat } from "@tanstack/ai";
 *
+* // inside a Durable Object / Agent:
 * const browserTools = createBrowserTools({
-*   browser: env.BROWSER,
-*   loader: env.LOADER,
+*   ctx: this.ctx,
+*   browser: this.env.BROWSER,
+*   loader: this.env.LOADER,
 * });
 *
 * const stream = chat({
@@ -26,23 +30,18 @@ import { toolDefinition } from "@tanstack/ai";
 * ```
 */
 function createBrowserTools(options) {
-	const handlers = createBrowserToolHandlers(options);
+	const { tools } = createBrowserRuntime(options);
+	const executeTool = tools.browser_execute;
 	return [toolDefinition({
-		name: "browser_search",
-		description: SEARCH_DESCRIPTION,
-		inputSchema: z.object({ code: z.string().meta({ description: "JavaScript async arrow function that queries the CDP spec" }) })
-	}).server(async ({ code }) => {
-		const result = await handlers.search(code);
-		if (result.isError) throw new Error(result.text);
-		return { text: result.text };
-	}), toolDefinition({
 		name: "browser_execute",
-		description: EXECUTE_DESCRIPTION,
-		inputSchema: z.object({ code: z.string().meta({ description: "JavaScript async arrow function that uses the cdp helper" }) })
+		description: executeTool.description ?? "",
+		inputSchema: z.object({ code: z.string().meta({ description: "TypeScript async arrow function that uses the cdp connector" }) })
 	}).server(async ({ code }) => {
-		const result = await handlers.execute(code);
-		if (result.isError) throw new Error(result.text);
-		return { text: result.text };
+		if (!executeTool.execute) throw new Error("browser_execute tool is not executable");
+		return await executeTool.execute({ code }, {
+			toolCallId: crypto.randomUUID(),
+			messages: []
+		});
 	})];
 }
 //#endregion

package/dist/browser/tanstack-ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../src/browser/tanstack-ai.ts"],"sourcesContent":["import { toolDefinition } from \"@tanstack/ai\";\nimport type { ServerTool } from \"@tanstack/ai\";\nimport { z } from \"zod\";\nimport {\n  createBrowserToolHandlers,\n  SEARCH_DESCRIPTION,\n  EXECUTE_DESCRIPTION,\n  type BrowserToolsOptions\n} from \"./shared\";\n\nexport type { BrowserToolsOptions } from \"./shared\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array of `ServerTool`s: `browser_search` (query the CDP spec)\n * and `browser_execute` (run CDP commands against a live browser).\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * const browserTools = createBrowserTools({\n *   browser: env.BROWSER,\n *   loader: env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(options: BrowserToolsOptions): ServerTool[] {\n  const handlers = createBrowserToolHandlers(options);\n\n  const search = toolDefinition({\n    name: \"browser_search\" as const,\n    description: SEARCH_DESCRIPTION,\n    inputSchema: z.object({\n      code: z.string().meta({\n        description: \"JavaScript async arrow function that queries the CDP spec\"\n      })\n    })\n  }).server(async ({ code }) => {\n    const result = await handlers.search(code);\n    if (result.isError) {\n      throw new Error(result.text);\n    }\n    return { text: result.text };\n  });\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description: EXECUTE_DESCRIPTION,\n    inputSchema: z.object({\n      code: z.string().meta({\n        description: \"JavaScript async arrow function that uses the cdp helper\"\n      })\n    })\n  }).server(async ({ code }) => {\n    const result = await handlers.execute(code);\n    if (result.isError) {\n      throw new Error(result.text);\n    }\n    return { text: result.text };\n  });\n\n  return [search, execute];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,mBAAmB,SAA4C;CAC7E,MAAM,WAAW,0BAA0B,OAAO;CAkClD,OAAO,CAhCQ,eAAe;EAC5B,MAAM;EACN,aAAa;EACb,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aAAa,4DACf,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,MAAM,SAAS,MAAM,SAAS,OAAO,IAAI;EACzC,IAAI,OAAO,SACT,MAAM,IAAI,MAAM,OAAO,IAAI;EAE7B,OAAO,EAAE,MAAM,OAAO,KAAK;CAC7B,CAkBa,GAhBG,eAAe;EAC7B,MAAM;EACN,aAAa;EACb,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aAAa,2DACf,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,MAAM,SAAS,MAAM,SAAS,QAAQ,IAAI;EAC1C,IAAI,OAAO,SACT,MAAM,IAAI,MAAM,OAAO,IAAI;EAE7B,OAAO,EAAE,MAAM,OAAO,KAAK;CAC7B,CAEsB,CAAC;AACzB"}
+{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../src/browser/tanstack-ai.ts"],"sourcesContent":["import { toolDefinition } from \"@tanstack/ai\";\nimport type { ServerTool } from \"@tanstack/ai\";\nimport type { ProxyToolOutput } from \"@cloudflare/codemode\";\nimport { z } from \"zod\";\nimport { createBrowserRuntime, type CreateBrowserToolsOptions } from \"./ai\";\n\nexport type { CreateBrowserToolsOptions } from \"./ai\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array with a single durable `browser_execute` `ServerTool`\n * backed by the same codemode runtime as `agents/browser/ai` — the model\n * writes TypeScript against the `cdp` connector and browser sessions\n * survive pauses.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ServerTool[] {\n  const { tools } = createBrowserRuntime(options);\n  const executeTool = tools.browser_execute;\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description: executeTool.description ?? \"\",\n    inputSchema: z.object({\n      code: z.string().meta({\n        description:\n          \"TypeScript async arrow function that uses the cdp connector\"\n      })\n    })\n  }).server(async ({ code }) => {\n    if (!executeTool.execute) {\n      throw new Error(\"browser_execute tool is not executable\");\n    }\n    const result = (await executeTool.execute(\n      { code },\n      { toolCallId: crypto.randomUUID(), messages: [] }\n    )) as ProxyToolOutput;\n    return result;\n  });\n\n  return [execute];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,mBACd,SACc;CACd,MAAM,EAAE,UAAU,qBAAqB,OAAO;CAC9C,MAAM,cAAc,MAAM;CAsB1B,OAAO,CApBS,eAAe;EAC7B,MAAM;EACN,aAAa,YAAY,eAAe;EACxC,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aACE,8DACJ,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,IAAI,CAAC,YAAY,SACf,MAAM,IAAI,MAAM,wCAAwC;EAM1D,OAAO,MAJe,YAAY,QAChC,EAAE,KAAK,GACP;GAAE,YAAY,OAAO,WAAW;GAAG,UAAU,CAAC;EAAE,CAClD;CAEF,CAEc,CAAC;AACjB"}

package/dist/chat/index.d.ts

@@ -3,11 +3,11 @@ import {
   d as AgentToolRunState,
   i as AgentToolEventMessage,
   r as AgentToolEvent
-} from "../agent-tool-types-V25Z_HcX.js";
+} from "../agent-tool-types-NofdbL9X.js";
 import {
   n as createAgentToolEventState,
   t as applyAgentToolEvent
-} from "../agent-tools-C-9s151X.js";
+} from "../agent-tools-DLquv-dp.js";
 import { JSONSchema7, Tool, ToolSet, UIMessage } from "ai";
 import { Connection } from "agents";
 
@@ -277,17 +277,38 @@ type ClientToolSchema = {
   description?: Tool["description"] /** JSON Schema defining the tool's input parameters */;
   parameters?: JSONSchema7;
 };
+/**
+ * Executes a client-defined tool and returns its output.
+ *
+ * Used for the RPC path (e.g. a parent agent delegating to a Think sub-agent)
+ * where the caller can run the client tools itself, rather than the
+ * browser/WebSocket path where results are sent back asynchronously.
+ */
+type ClientToolExecutor = (call: {
+  /** The name of the client tool the model called. */ toolName: string /** The model-generated input for the tool call. */;
+  input: unknown /** The AI SDK tool-call id for the invocation. */;
+  toolCallId: string;
+}) => unknown | Promise<unknown>;
 /**
  * Converts client tool schemas to AI SDK tool format.
  *
- * These tools have no `execute` function — when the AI model calls them,
- * the tool call is sent back to the client for execution.
+ * By default these tools have no `execute` function — when the AI model calls
+ * them, the tool call is sent back to the client for execution.
+ *
+ * When `options.execute` is provided, each tool is built WITH an `execute` that
+ * delegates to it. This is used by the RPC path (e.g. a parent agent driving a
+ * Think sub-agent) so the model's client-tool call is resolved inline within
+ * the same turn.
  *
  * @param clientTools - Array of tool schemas from the client
+ * @param options - Optional `execute` delegate to run the tools inline
  * @returns Record of AI SDK tools that can be spread into your tools object
  */
 declare function createToolsFromClientSchemas(
-  clientTools?: ClientToolSchema[]
+  clientTools?: ClientToolSchema[],
+  options?: {
+    execute?: ClientToolExecutor;
+  }
 ): ToolSet;
 //#endregion
 //#region src/chat/lifecycle.d.ts
@@ -672,6 +693,12 @@ declare class ResumableStream {
    * DO was evicted.
    */
   private _isLive;
+  /**
+   * Whether the active stream is a continuation. Mirrors the durable
+   * `is_continuation` column so replay frames can carry the flag without a
+   * per-replay query; restored from SQLite after hibernation in restore().
+   */
+  private _activeIsContinuation;
   private _chunkBuffer;
   private _chunkBufferBytes;
   private _isFlushingChunks;
@@ -702,6 +729,7 @@ declare class ResumableStream {
     requestId: string,
     options?: {
       messageId?: string;
+      continuation?: boolean;
     }
   ): string;
   /**
@@ -768,6 +796,33 @@ declare class ResumableStream {
     connection: Connection,
     requestId: string
   ): boolean;
+  /**
+   * Replay the stored chunks of an errored stream for a request, WITHOUT a
+   * terminal frame — the caller follows up with the `done: true, error: true`
+   * frame carrying the durable terminal record's error text, mirroring what a
+   * live client observed (content chunks, then the error). Without this, a
+   * client that missed broadcast frames while disconnected has no other
+   * channel to the pre-error partial content: the server does not push
+   * messages on connect, and {@link replayCompletedChunksByRequestId} only
+   * serves `completed` streams (#1575).
+   *
+   * Returns true when the caller should proceed to send its terminal frame:
+   * either no errored stream existed (nothing to replay) or its chunks were
+   * replayed successfully. Returns false only when a send failed mid-replay,
+   * signalling the caller to skip the terminal frame — the connection is gone
+   * and the next reconnect retries the whole sequence.
+   */
+  replayErroredChunksByRequestId(
+    connection: Connection,
+    requestId: string
+  ): boolean;
+  /** Latest stream row for a request with the given terminal status. */
+  private _latestStreamForRequest;
+  /**
+   * Send a finished stream's stored chunks to a connection as replay frames.
+   * Returns false if the connection closed mid-replay.
+   */
+  private _replayStoredChunks;
   /**
    * Restore active stream state if the agent was restarted during streaming.
    * All streams are restored regardless of age — stale cleanup happens
@@ -782,7 +837,26 @@ declare class ResumableStream {
    * Drop all stream tables (called on destroy).
    */
   destroy(): void;
+  /**
+   * Force a sweep of aged stream buffers now, bypassing the lazy interval
+   * gate used by {@link _maybeCleanupOldStreams}. Intended to be driven by an
+   * alarm so idle/hibernated chat DOs still reclaim buffers even when no
+   * further stream ever completes to trigger the lazy path.
+   */
+  cleanup(now?: number): void;
+  /**
+   * True if any stream rows remain at all. Used by alarm-driven cleanup to
+   * decide whether to re-arm: once no rows remain there is nothing left to
+   * sweep, so the DO can stop waking itself.
+   */
+  hasReclaimableStreams(): boolean;
   private _maybeCleanupOldStreams;
+  /** Delete completed/errored buffers past the completion grace window, plus
+   *  abandoned "streaming" rows past the stale-in-flight window. The two use
+   *  different retentions: a completed buffer is redundant with the persisted
+   *  message and needs only a brief replay grace, whereas an in-flight buffer
+   *  must outlive resume/recovery before it is presumed dead. */
+  private _sweepOldStreams;
   /**
    * Return the stored chunks for a stream as individual chunk bodies in order,
    * unpacking packed segment rows. The returned `chunk_index` is a running
@@ -807,6 +881,13 @@ declare class ResumableStream {
   }>;
   /** @internal For testing only */
   insertStaleStream(streamId: string, requestId: string, ageMs: number): void;
+  /**
+   * Append a chunk to a stream dated `ageMs` in the past. Used to exercise the
+   * last-activity sweep threshold: a long-running streaming row with a *recent*
+   * chunk must survive even when its start time is older than the cutoff.
+   * @internal For testing only
+   */
+  insertChunkAt(streamId: string, body: string, ageMs: number): void;
 }
 //#endregion
 //#region src/chat/sql-batch.d.ts
@@ -1083,6 +1164,29 @@ declare function crossMessageToolResultUpdate(
   errorText?: string,
   preliminary?: boolean
 ): ToolPartUpdate;
+/**
+ * Build an update descriptor that replaces the output of a *paused durable
+ * execution* tool part (e.g. a codemode runtime tool that paused for
+ * approval).
+ *
+ * A paused execution completes its tool call normally — the part is already
+ * `output-available` with an output of `{ status: "paused", executionId }`.
+ * When the host later approves/rejects the execution, the new outcome
+ * (completed / rejected / paused-again) must replace that output in place.
+ *
+ * Matching is deliberately narrow and idempotent:
+ *
+ * - only `output-available` parts are considered;
+ * - the existing output must be a paused-execution object carrying the same
+ *   `executionId` — anything else (already replaced, different execution)
+ *   returns the *same part reference*, which callers treat as a no-op signal
+ *   (skip persist + broadcast), mirroring {@link crossMessageToolResultUpdate}.
+ */
+declare function pausedExecutionUpdate(
+  toolCallId: string,
+  executionId: string,
+  output: unknown
+): ToolPartUpdate;
 /**
  * Build an update descriptor for applying a tool approval.
  *
@@ -1278,6 +1382,7 @@ export {
   type ChatResponseResult,
   type ChunkAction,
   type ChunkResult,
+  type ClientToolExecutor,
   type ClientToolSchema,
   type ContinuationConnection,
   type ContinuationDeferred,
@@ -1318,6 +1423,7 @@ export {
   isReplayChunk,
   normalizeToolInput,
   parseProtocolMessage,
+  pausedExecutionUpdate,
   reconcileMessages,
   resolveToolMergeId,
   sanitizeMessage,