agents 0.15.0 → 0.16.0

package/dist/{agent-tool-types-VPsjVYL0.d.ts → agent-tool-types-NofdbL9X.d.ts}

@@ -1,10 +1,10 @@
 import { n as AgentEmail } from "./internal_context-Dg4Cgjcu.js";
-import { t as RetryOptions } from "./retries-CF_HKSlJ.js";
+import { t as RetryOptions } from "./retries-CwlpAGet.js";
 import {
   n as Observability,
   r as ObservabilityEvent,
   s as MCPObservabilityEvent
-} from "./index-CPe1OtI0.js";
+} from "./index-B7IbEeze.js";
 import { t as AgentMcpOAuthProvider } from "./do-oauth-client-provider-D4ZwyBDu.js";
 import {
   _ as WorkflowPage,
@@ -2343,7 +2343,15 @@ interface AgentStaticOptions {
   /**
    * Maximum age in milliseconds of an unmanaged interrupted-fiber row before
    * recovery stops retrying a repeatedly-throwing `onFiberRecovered()` hook
-   * and discards the row. Set to `0` to retain rows indefinitely.
+   * and discards the row (emitting `fiber:recovery:skipped` with reason
+   * `max_age_exceeded`). Defaults to 24h.
+   *
+   * Set to `0` to retain rows indefinitely. NOTE: with `0`, a hook that keeps
+   * throwing is retried forever — the recovery alarm backs off exponentially
+   * (capped at 5 minutes) so it is not a busy-loop, but the Durable Object
+   * stays warm (never idle-evicts) for as long as the un-recoverable row
+   * exists. Prefer a finite age unless you intend to inspect/clear such rows
+   * yourself.
    */
   fiberRecoveryMaxAgeMs?: number;
   /**
@@ -2467,6 +2475,13 @@ declare class Agent<
   private _managedFiberTerminalWaiters;
   /** @internal Prevents re-entrant recovery from overlapping alarm ticks. */
   private _runFiberRecoveryInProgress;
+  /**
+   * @internal Consecutive runFiber-recovery scans that made NO forward progress
+   * while work was still pending. Drives the exponential backoff of the
+   * recovery follow-up alarm so a repeatedly-throwing recovery hook does not
+   * busy-loop the DO. Reset to 0 whenever a scan recovers anything.
+   */
+  private _recoveryNoProgressScans;
   /** @internal Single-flight background recovery for parent agent-tool rows. */
   private _agentToolRunRecoveryPromise;
   private _ParentClass;
@@ -3296,6 +3311,18 @@ declare class Agent<
     targetPath: ReadonlyArray<AgentPathStep>
   ): Promise<void>;
   private _executeScheduleCallback;
+  /**
+   * Whether any runFiber recovery work is still outstanding: orphaned
+   * `cf_agents_runs` rows left by a dead process (excluding fibers currently
+   * executing in memory, which already hold a keepAlive ref) or managed
+   * ledger fibers stuck in a non-terminal state with no live run row.
+   *
+   * Used by `_scheduleNextAlarm` to arm a follow-up alarm so multi-pass
+   * recovery (e.g. after a scan-deadline yield, or while retrying a throwing
+   * recovery hook) resumes instead of starving.
+   * @internal
+   */
+  private _hasPendingFiberRecovery;
   private _scheduleNextAlarm;
   /**
    * Override PartyServer's onAlarm hook as a no-op.
@@ -3861,6 +3888,32 @@ declare class Agent<
    * callers should treat it as fire-and-forget.
    */
   destroy(): Promise<void>;
+  /**
+   * @internal Defer this agent's destruction to its own alarm invocation
+   * instead of running it inline (#1625).
+   *
+   * `destroy()` is a multi-step I/O sequence (drop tables, delete alarm,
+   * delete all storage, dispose connections). Running it on the `waitUntil`
+   * of a request whose client has already disconnected — the MCP
+   * Streamable-HTTP session-DELETE path — gives it little to no
+   * post-invocation grace, so the runtime routinely cancels it mid-flight.
+   * This method instead performs two fast storage writes (a durable
+   * "condemned" marker and an immediate alarm) that the caller can await
+   * before responding; the alarm then fires as a fresh invocation with its
+   * own full execution budget and runs `destroy()` there. If even that
+   * invocation is interrupted, the marker survives and the next wake
+   * finishes teardown — see the `alarm()` preamble.
+   *
+   * Unlike `destroy()`, this method does not abort the isolate, so RPC
+   * callers don't need to swallow an abort error.
+   */
+  _cf_scheduleDestroy(): Promise<void>;
+  /**
+   * Whether a (deferred or interrupted) destroy is pending. Reads the
+   * durable marker directly — the in-memory `_isFacet` flag may not be
+   * hydrated yet at the call sites, but facets never write the marker.
+   */
+  private _hasPendingDestroy;
   /** @internal Drop every internal Agents SDK table during top-level destroy. */
   protected _dropInternalTablesForDestroy(): void;
   /**
@@ -4794,4 +4847,4 @@ export {
   MCPServer as z,
   WorkerTransport as zt
 };
-//# sourceMappingURL=agent-tool-types-VPsjVYL0.d.ts.map
+//# sourceMappingURL=agent-tool-types-NofdbL9X.d.ts.map

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

@@ -16,7 +16,7 @@ import {
   s as AgentToolInterruptedReason,
   t as AgentToolChildAdapter,
   u as AgentToolRunInspection
-} from "./agent-tool-types-VPsjVYL0.js";
+} from "./agent-tool-types-NofdbL9X.js";
 export {
   AgentToolChildAdapter,
   AgentToolDisplayMetadata,

package/dist/{agent-tools-BGpgfpJT.d.ts → agent-tools-DLquv-dp.d.ts}

@@ -1,7 +1,7 @@
 import {
   a as AgentToolEventState,
   i as AgentToolEventMessage
-} from "./agent-tool-types-VPsjVYL0.js";
+} from "./agent-tool-types-NofdbL9X.js";
 
 //#region src/chat/agent-tools.d.ts
 declare function createAgentToolEventState(): AgentToolEventState;
@@ -11,4 +11,4 @@ declare function applyAgentToolEvent(
 ): AgentToolEventState;
 //#endregion
 export { createAgentToolEventState as n, applyAgentToolEvent as t };
-//# sourceMappingURL=agent-tools-BGpgfpJT.d.ts.map
+//# sourceMappingURL=agent-tools-DLquv-dp.d.ts.map

package/dist/agent-tools.d.ts

@@ -16,7 +16,7 @@ import {
   s as AgentToolInterruptedReason,
   t as AgentToolChildAdapter,
   u as AgentToolRunInspection
-} from "./agent-tool-types-VPsjVYL0.js";
+} from "./agent-tool-types-NofdbL9X.js";
 import { Tool } from "ai";
 
 //#region src/agent-tools.d.ts

package/dist/browser/ai.d.ts

@@ -1,21 +1,133 @@
-import { t as BrowserToolsOptions } from "../shared-4CAYLCTO.js";
+import {
+  c as BrowserSessionStore,
+  f as BrowserBinding,
+  r as BrowserConnectorSessionOptions,
+  t as BrowserConnector
+} from "../connector-DXursxV5.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).
+   *
+   * 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;
+}
+/**
+ * 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 `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({
@@ -25,7 +137,14 @@ import { ToolSet } from "ai";
  * });
  * ```
  */
-declare function createBrowserTools(options: BrowserToolsOptions): ToolSet;
+declare function createBrowserTools(
+  options: CreateBrowserToolsOptions
+): ToolSet;
 //#endregion
-export { type BrowserToolsOptions, createBrowserTools };
+export {
+  BrowserRuntime,
+  CreateBrowserToolsOptions,
+  createBrowserRuntime,
+  createBrowserTools
+};
 //# sourceMappingURL=ai.d.ts.map

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