agents/dist/browser/ai.d.ts

A home for your AI agents

import {
  I as BrowserBinding,
  f as BrowserSessionStore,
  r as BrowserConnectorSessionOptions,
  t as BrowserConnector,
  v as QuickActionBinding,
  y as QuickActionCommonOptions
} from "../connector-v2M1zlZp.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). Pass an object to configure them, or `false` to disable.
   * 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 {
  BrowserRuntime,
  CreateBrowserToolsOptions,
  CreateQuickActionToolsOptions,
  QuickActionToolName,
  createBrowserRuntime,
  createBrowserTools,
  createQuickActionTools
};
//# sourceMappingURL=ai.d.ts.map