agents 0.30.0 → 0.31.0

package/dist/browser/ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai.js","names":[],"sources":["../../src/browser/ai.ts"],"sourcesContent":["import { tool, type ToolSet } from \"ai\";\nimport { z } from \"zod\";\nimport {\n  createCodemodeRuntime,\n  DynamicWorkerExecutor,\n  type CodemodeRuntimeHandle\n} from \"@cloudflare/codemode\";\nimport type { BrowserBinding } from \"./browser-run\";\nimport {\n  browserContent,\n  browserExtract,\n  browserLinks,\n  browserMarkdown,\n  browserScrape,\n  type QuickActionBinding,\n  type QuickActionCommonOptions,\n  type QuickActionPage\n} from \"./quick-actions\";\nimport {\n  BrowserConnector,\n  type BrowserConnectorOptions,\n  type BrowserConnectorSessionOptions\n} from \"./connector\";\nimport {\n  DurableBrowserSessionStore,\n  type BrowserSessionStore\n} from \"./session-store\";\nimport {\n  browserExecuteModelOutput,\n  resolveCtx,\n  transformBrowserResult\n} from \"./tool-helpers\";\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   * Optional: when omitted, it is resolved from the current Agent via\n   * `getCurrentAgent()`, so inside an Agent method you can just pass `browser`\n   * and `loader`. Pass it explicitly outside an Agent context.\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   * Also expose stateless {@link createQuickActionTools | Quick Action} tools\n   * (`browser_markdown`, `browser_extract`, …) alongside the durable\n   * `browser_execute` tool.\n   *\n   * Enabled by default whenever a Browser Run `browser` binding is available\n   * (they share it), except when `session.browser` selects Kitesurf because\n   * the binding RPC cannot select that engine. Pass `true` or an object to\n   * explicitly add Chromium Quick Actions alongside Kitesurf, or `false` to\n   * disable them. The Quick Action binding defaults to `browser`; override it via\n   * `quickActions.browser`. When only `cdpUrl` is set (no binding), the\n   * defaults are skipped silently — pass `quickActions: { browser }` to force\n   * them.\n   */\n  quickActions?:\n    | boolean\n    | {\n        browser?: QuickActionBinding;\n        actions?: QuickActionToolName[];\n        maxChars?: number;\n        options?: QuickActionCommonOptions;\n      };\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;\nlet didDebugQuickActionSkip = false;\n\nfunction connectorOptions(\n  options: CreateBrowserToolsOptions,\n  ctx: DurableObjectState\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(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 ctx = resolveCtx(options);\n  if (!ctx) {\n    throw new Error(\n      \"createBrowserRuntime requires a Durable Object 'ctx' — pass it explicitly, or call from within an Agent so it can be resolved via getCurrentAgent()\"\n    );\n  }\n\n  const connector = new BrowserConnector(ctx, connectorOptions(options, ctx));\n  const runtime = createCodemodeRuntime({\n    ctx,\n    executor: new DynamicWorkerExecutor({\n      loader: options.loader,\n      timeout: options.timeout\n    }),\n    connectors: [connector],\n    name: options.name ?? \"browser\",\n    transformResult: transformBrowserResult\n  });\n\n  // `connectorOptions` drops `session` when a custom endpoint is used, so the\n  // connector is plain Chromium there whatever the session options say.\n  const isKitesurf = !options.cdpUrl && options.session?.browser === \"kitesurf\";\n  const browserExecute = runtime.tool({\n    connectorHints: {\n      cdp: isKitesurf\n        ? 'Kitesurf one-shot Browser CDP. Call codemode.describe(\"cdp\") for connector types and Kitesurf execution rules. codemode.search indexes connector methods and snippets, not underlying CDP commands. Complete the task in one execution and do not pause. Return screenshots as { type: \"browser_screenshot\", mediaType: \"image/png\", data: screenshot.data }.'\n        : \"Browser CDP. Return screenshots as { type: 'browser_screenshot', mediaType: 'image/png', data: screenshot.data }; the UI keeps the image while the model receives a compact summary.\"\n    }\n  });\n  const tools: ToolSet = {\n    browser_execute: {\n      ...browserExecute,\n      toModelOutput: ({ output }: { output: unknown }) =>\n        browserExecuteModelOutput(output)\n    }\n  };\n\n  // Quick Actions ride the same `browser` binding, so they are on by default\n  // for Chromium. The binding RPC cannot select Kitesurf, so selecting\n  // Kitesurf disables the defaults rather than silently adding Chromium tools.\n  // Callers can still request a mixed-engine toolset explicitly.\n  const enableQuickActions =\n    options.quickActions !== false &&\n    (!isKitesurf || options.quickActions !== undefined);\n  // `env.BROWSER` satisfies both the CDP `BrowserBinding` (fetch) and the\n  // `QuickActionBinding` (quickAction) surfaces; our narrower option type only\n  // sees the former, so reuse it here unless an explicit binding wins.\n  if (enableQuickActions) {\n    const qa =\n      typeof options.quickActions === \"object\" ? options.quickActions : {};\n    const quickActionBrowser =\n      qa.browser ??\n      (options.browser as unknown as QuickActionBinding | undefined);\n    if (quickActionBrowser) {\n      Object.assign(\n        tools,\n        createQuickActionTools({\n          browser: quickActionBrowser,\n          actions: qa.actions,\n          maxChars: qa.maxChars,\n          options: qa.options\n        })\n      );\n    } else if (options.quickActions) {\n      // Explicitly requested but no binding to back them.\n      throw new Error(\n        \"quickActions requires a Browser Run binding — set 'browser' (env.BROWSER) or 'quickActions.browser'\"\n      );\n    } else if (!didDebugQuickActionSkip) {\n      // Defaulted on, but only `cdpUrl` is set: there is no binding to call\n      // Quick Actions through, so they are skipped. Surface it once so a user\n      // expecting `browser_markdown` et al. isn't left wondering.\n      didDebugQuickActionSkip = true;\n      console.debug(\n        \"[agents/browser] Quick Action tools skipped — no Browser Run binding (only 'cdpUrl' is set). Pass 'browser' or 'quickActions.browser' to enable them.\"\n      );\n    }\n  }\n\n  return { runtime, connector, tools };\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\n/** A Quick Action exposed as an AI SDK tool. */\nexport type QuickActionToolName =\n  | \"markdown\"\n  | \"extract\"\n  | \"links\"\n  | \"scrape\"\n  | \"content\";\n\nexport interface CreateQuickActionToolsOptions {\n  /**\n   * Browser Run binding with Quick Actions support (`env.BROWSER`). Requires a\n   * Worker `compatibility_date` of `2026-03-24`+ and `remote: true` for local\n   * `wrangler dev`.\n   */\n  browser: QuickActionBinding;\n\n  /**\n   * Which tools to expose. Defaults to the text-returning, model-friendly set\n   * (`markdown`, `extract`, `links`, `scrape`). `content` (raw HTML) is opt-in\n   * since it is large and rarely what a model wants.\n   */\n  actions?: QuickActionToolName[];\n\n  /**\n   * Bound every result to roughly this many characters before returning it to\n   * the model, to protect the context window, preserving each result's shape:\n   * text (markdown/content) is truncated to a string, oversized arrays\n   * (links/scrape) are trimmed but stay arrays, and only an opaque oversized\n   * object degrades to a truncated-preview summary. Set to `0` to disable.\n   * Defaults to 50000.\n   */\n  maxChars?: number;\n\n  /**\n   * Common Browser Run options merged into every request — e.g. `cookies`,\n   * `authenticate`, or `setExtraHTTPHeaders` for authenticated pages, and\n   * `gotoOptions` / `viewport` for JavaScript-heavy pages. The model only ever\n   * supplies the page (`url`/`html`) and action-specific fields; these\n   * host-supplied options are never exposed to it.\n   */\n  options?: QuickActionCommonOptions;\n}\n\nconst DEFAULT_QUICK_ACTION_TOOLS: QuickActionToolName[] = [\n  \"markdown\",\n  \"extract\",\n  \"links\",\n  \"scrape\"\n];\n\nconst DEFAULT_QUICK_ACTION_MAX_CHARS = 50_000;\n\nconst pageInputSchema = z\n  .object({\n    url: z.string().url().optional().describe(\"URL of the page to load\"),\n    html: z\n      .string()\n      .optional()\n      .describe(\"Raw HTML to render instead of loading a URL\")\n  })\n  .refine((value) => Boolean(value.url) || Boolean(value.html), {\n    message: \"Provide either 'url' or 'html'\"\n  });\n\nfunction toPage(\n  input: { url?: string; html?: string },\n  options?: QuickActionCommonOptions\n): QuickActionPage {\n  const page = input.url ? { url: input.url } : { html: input.html as string };\n  return { ...options, ...page } as QuickActionPage;\n}\n\nfunction truncate(text: string, maxChars: number): string {\n  if (maxChars <= 0 || text.length <= maxChars) return text;\n  return `${text.slice(0, maxChars)}\\n\\n[truncated ${text.length - maxChars} characters]`;\n}\n\n/**\n * Keep a tool result within a rough character budget so a single browse cannot\n * blow the model's context window — while preserving the result's shape so the\n * model sees a consistent type across calls:\n *\n * - strings (markdown/content) are truncated to a string;\n * - arrays (links/scrape) are trimmed from the end but stay arrays;\n * - only an opaque oversized object (e.g. a sprawling `extract`) degrades to a\n *   `{ truncated, note, preview }` summary, since it cannot be trimmed safely.\n */\nfunction boundResult(value: unknown, maxChars: number): unknown {\n  if (maxChars <= 0) return value;\n  if (typeof value === \"string\") return truncate(value, maxChars);\n  let json: string;\n  try {\n    json = JSON.stringify(value);\n  } catch {\n    return value;\n  }\n  if (json.length <= maxChars) return value;\n  if (Array.isArray(value)) {\n    const trimmed = boundArray(value, maxChars);\n    // If even the first element overflows the budget, `trimmed` is empty —\n    // returning `[]` would read as \"no results\" rather than \"too large\", so\n    // fall through to the explicit truncated-preview summary instead.\n    if (trimmed.length > 0) return trimmed;\n  }\n  return {\n    truncated: true,\n    note: `Result is too large (${json.length} characters); narrow the request.`,\n    preview: `${json.slice(0, maxChars)}…`\n  };\n}\n\n/**\n * Take as many leading items as fit within `maxChars` (measured against their\n * JSON length), returning a trimmed array of the same element type. Silent by\n * design: the model gets fewer, valid items rather than a reshaped result.\n */\nfunction boundArray(value: unknown[], maxChars: number): unknown[] {\n  const out: unknown[] = [];\n  let size = 2; // the enclosing \"[]\"\n  for (const item of value) {\n    const itemSize = JSON.stringify(item).length + 1; // + a separating comma\n    if (size + itemSize > maxChars) break;\n    out.push(item);\n    size += itemSize;\n  }\n  return out;\n}\n\n/**\n * Create AI SDK tools for Browser Run [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/):\n * stateless one-shot browsing (read a page as Markdown, extract structured\n * data with AI, list links, scrape elements). Unlike `createBrowserTools`,\n * these need only the `browser` binding — no Durable Object, loader, or\n * sandbox — so they work from any Worker.\n *\n * @example\n * ```ts\n * import { createQuickActionTools } from \"agents/browser/ai\";\n *\n * const tools = createQuickActionTools({ browser: this.env.BROWSER });\n * const result = await generateText({ model, tools, messages });\n * ```\n */\nexport function createQuickActionTools(\n  options: CreateQuickActionToolsOptions\n): ToolSet {\n  const { browser } = options;\n  const requestOptions = options.options;\n  const enabled = new Set(options.actions ?? DEFAULT_QUICK_ACTION_TOOLS);\n  const maxChars = options.maxChars ?? DEFAULT_QUICK_ACTION_MAX_CHARS;\n  const tools: ToolSet = {};\n\n  if (enabled.has(\"markdown\")) {\n    tools.browser_markdown = tool({\n      description:\n        \"Load a web page (or render raw HTML) and return its content as Markdown. Best for reading articles, docs, or any page as text.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserMarkdown(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"extract\")) {\n    tools.browser_extract = tool({\n      description:\n        \"Extract structured data from a web page using AI. Describe what you want in 'prompt'. Passing a JSON Schema in 'schema' is strongly recommended — without one the extractor often fails to produce JSON.\",\n      inputSchema: z\n        .object({\n          url: z.string().url().optional().describe(\"URL of the page to load\"),\n          html: z\n            .string()\n            .optional()\n            .describe(\"Raw HTML to render instead of loading a URL\"),\n          prompt: z\n            .string()\n            .optional()\n            .describe(\"What to extract, in natural language\"),\n          schema: z\n            .record(z.string(), z.unknown(), {\n              error: \"Schema must be a JSON object\"\n            })\n            .optional()\n            .describe(\"Optional JSON Schema describing the desired output\")\n        })\n        .refine((value) => Boolean(value.url) || Boolean(value.html), {\n          message: \"Provide either 'url' or 'html'\"\n        })\n        .refine((value) => Boolean(value.prompt) || Boolean(value.schema), {\n          message: \"Provide either 'prompt' or 'schema'\"\n        }),\n      execute: async (input) =>\n        boundResult(\n          await browserExtract(browser, {\n            ...toPage(input, requestOptions),\n            prompt: input.prompt,\n            response_format: input.schema\n              ? { type: \"json_schema\", json_schema: input.schema }\n              : undefined\n          }),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"links\")) {\n    tools.browser_links = tool({\n      description:\n        \"Return every link found on a web page (including ones not visible). Useful for discovering pages to follow.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserLinks(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"scrape\")) {\n    tools.browser_scrape = tool({\n      description:\n        \"Scrape specific elements from a web page by CSS selector. Returns the matched elements' text, HTML, and attributes.\",\n      inputSchema: z\n        .object({\n          url: z.string().url().optional().describe(\"URL of the page to load\"),\n          html: z\n            .string()\n            .optional()\n            .describe(\"Raw HTML to render instead of loading a URL\"),\n          selectors: z\n            .array(z.string())\n            .min(1)\n            .describe(\"CSS selectors to extract\")\n        })\n        .refine((value) => Boolean(value.url) || Boolean(value.html), {\n          message: \"Provide either 'url' or 'html'\"\n        }),\n      execute: async (input) =>\n        boundResult(\n          await browserScrape(browser, {\n            ...toPage(input, requestOptions),\n            elements: input.selectors.map((selector) => ({ selector }))\n          }),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"content\")) {\n    tools.browser_content = tool({\n      description:\n        \"Load a web page and return its fully rendered HTML (after JavaScript runs). Prefer 'browser_markdown' unless you need the raw HTML.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserContent(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  return tools;\n}\n"],"mappings":"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"}
+{"version":3,"file":"ai.js","names":[],"sources":["../../src/browser/ai.ts"],"sourcesContent":["import { tool, type ToolSet } from \"ai\";\nimport { z } from \"zod\";\nimport {\n  createCodemodeRuntime,\n  DynamicWorkerExecutor,\n  type CodemodeRuntimeHandle\n} from \"@cloudflare/codemode\";\nimport type { BrowserBinding } from \"./browser-run\";\nimport {\n  browserContent,\n  browserExtract,\n  browserLinks,\n  browserMarkdown,\n  browserScrape,\n  type QuickActionBinding,\n  type QuickActionCommonOptions,\n  type QuickActionPage\n} from \"./quick-actions\";\nimport {\n  BrowserConnector,\n  type BrowserConnectorOptions,\n  type BrowserConnectorSessionOptions\n} from \"./connector\";\nimport {\n  DurableBrowserSessionStore,\n  type BrowserSessionStore\n} from \"./session-store\";\nimport {\n  browserExecuteModelOutput,\n  resolveCtx,\n  transformBrowserResult\n} from \"./tool-helpers\";\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   * Optional: when omitted, it is resolved from the current Agent via\n   * `getCurrentAgent()`, so inside an Agent method you can just pass `browser`\n   * and `loader`. Pass it explicitly outside an Agent context.\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   * Also expose stateless {@link createQuickActionTools | Quick Action} tools\n   * (`browser_markdown`, `browser_extract`, …) alongside the durable\n   * `browser_execute` tool.\n   *\n   * Enabled by default whenever a Browser Run `browser` binding is available\n   * (they share it), except when `session.browser` selects Kitesurf because\n   * the binding RPC cannot select that engine. Pass `true` or an object to\n   * explicitly add Chromium Quick Actions alongside Kitesurf, or `false` to\n   * disable them. The Quick Action binding defaults to `browser`; override it via\n   * `quickActions.browser`. When only `cdpUrl` is set (no binding), the\n   * defaults are skipped silently — pass `quickActions: { browser }` to force\n   * them.\n   */\n  quickActions?:\n    | boolean\n    | {\n        browser?: QuickActionBinding;\n        actions?: QuickActionToolName[];\n        maxChars?: number;\n        options?: QuickActionCommonOptions;\n      };\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;\nlet didDebugQuickActionSkip = false;\n\nfunction connectorOptions(\n  options: CreateBrowserToolsOptions,\n  ctx: DurableObjectState\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(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 *\n * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,\n * `agents/browser/tanstack-ai` or `agents/browser/pi`. See\n * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser\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 ctx = resolveCtx(options);\n  if (!ctx) {\n    throw new Error(\n      \"createBrowserRuntime requires a Durable Object 'ctx' — pass it explicitly, or call from within an Agent so it can be resolved via getCurrentAgent()\"\n    );\n  }\n\n  const connector = new BrowserConnector(ctx, connectorOptions(options, ctx));\n  const runtime = createCodemodeRuntime({\n    ctx,\n    executor: new DynamicWorkerExecutor({\n      loader: options.loader,\n      timeout: options.timeout\n    }),\n    connectors: [connector],\n    name: options.name ?? \"browser\",\n    transformResult: transformBrowserResult\n  });\n\n  // `connectorOptions` drops `session` when a custom endpoint is used, so the\n  // connector is plain Chromium there whatever the session options say.\n  const isKitesurf = !options.cdpUrl && options.session?.browser === \"kitesurf\";\n  const browserExecute = runtime.tool({\n    connectorHints: {\n      cdp: isKitesurf\n        ? 'Kitesurf one-shot Browser CDP. Call codemode.describe(\"cdp\") for connector types and Kitesurf execution rules. codemode.search indexes connector methods and snippets, not underlying CDP commands. Complete the task in one execution and do not pause. Return screenshots as { type: \"browser_screenshot\", mediaType: \"image/png\", data: screenshot.data }.'\n        : \"Browser CDP. Return screenshots as { type: 'browser_screenshot', mediaType: 'image/png', data: screenshot.data }; the UI keeps the image while the model receives a compact summary.\"\n    }\n  });\n  const tools: ToolSet = {\n    browser_execute: {\n      ...browserExecute,\n      toModelOutput: ({ output }: { output: unknown }) =>\n        browserExecuteModelOutput(output)\n    }\n  };\n\n  // Quick Actions ride the same `browser` binding, so they are on by default\n  // for Chromium. The binding RPC cannot select Kitesurf, so selecting\n  // Kitesurf disables the defaults rather than silently adding Chromium tools.\n  // Callers can still request a mixed-engine toolset explicitly.\n  const enableQuickActions =\n    options.quickActions !== false &&\n    (!isKitesurf || options.quickActions !== undefined);\n  // `env.BROWSER` satisfies both the CDP `BrowserBinding` (fetch) and the\n  // `QuickActionBinding` (quickAction) surfaces; our narrower option type only\n  // sees the former, so reuse it here unless an explicit binding wins.\n  if (enableQuickActions) {\n    const qa =\n      typeof options.quickActions === \"object\" ? options.quickActions : {};\n    const quickActionBrowser =\n      qa.browser ??\n      (options.browser as unknown as QuickActionBinding | undefined);\n    if (quickActionBrowser) {\n      Object.assign(\n        tools,\n        createQuickActionTools({\n          browser: quickActionBrowser,\n          actions: qa.actions,\n          maxChars: qa.maxChars,\n          options: qa.options\n        })\n      );\n    } else if (options.quickActions) {\n      // Explicitly requested but no binding to back them.\n      throw new Error(\n        \"quickActions requires a Browser Run binding — set 'browser' (env.BROWSER) or 'quickActions.browser'\"\n      );\n    } else if (!didDebugQuickActionSkip) {\n      // Defaulted on, but only `cdpUrl` is set: there is no binding to call\n      // Quick Actions through, so they are skipped. Surface it once so a user\n      // expecting `browser_markdown` et al. isn't left wondering.\n      didDebugQuickActionSkip = true;\n      console.debug(\n        \"[agents/browser] Quick Action tools skipped — no Browser Run binding (only 'cdpUrl' is set). Pass 'browser' or 'quickActions.browser' to enable them.\"\n      );\n    }\n  }\n\n  return { runtime, connector, tools };\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 *\n * @deprecated Use `browserTool` from `agents/browser/ai-sdk`,\n * `agents/browser/tanstack-ai` or `agents/browser/pi`. See\n * https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ToolSet {\n  return createBrowserRuntime(options).tools;\n}\n\n/**\n * A Quick Action exposed as an AI SDK tool.\n *\n * @deprecated Quick Actions are deprecated and won't change. Use\n * `browserTool` to drive a browser, the `web_fetch` tool from\n * `agents/webfetch` to read a page, or call the binding's\n * `quickAction()` directly.\n */\nexport type QuickActionToolName =\n  | \"markdown\"\n  | \"extract\"\n  | \"links\"\n  | \"scrape\"\n  | \"content\";\n\n/**\n * @deprecated Quick Actions are deprecated and won't change. Use\n * `browserTool` to drive a browser, the `web_fetch` tool from\n * `agents/webfetch` to read a page, or call the binding's\n * `quickAction()` directly.\n */\nexport interface CreateQuickActionToolsOptions {\n  /**\n   * Browser Run binding with Quick Actions support (`env.BROWSER`). Requires a\n   * Worker `compatibility_date` of `2026-03-24`+ and `remote: true` for local\n   * `wrangler dev`.\n   */\n  browser: QuickActionBinding;\n\n  /**\n   * Which tools to expose. Defaults to the text-returning, model-friendly set\n   * (`markdown`, `extract`, `links`, `scrape`). `content` (raw HTML) is opt-in\n   * since it is large and rarely what a model wants.\n   */\n  actions?: QuickActionToolName[];\n\n  /**\n   * Bound every result to roughly this many characters before returning it to\n   * the model, to protect the context window, preserving each result's shape:\n   * text (markdown/content) is truncated to a string, oversized arrays\n   * (links/scrape) are trimmed but stay arrays, and only an opaque oversized\n   * object degrades to a truncated-preview summary. Set to `0` to disable.\n   * Defaults to 50000.\n   */\n  maxChars?: number;\n\n  /**\n   * Common Browser Run options merged into every request — e.g. `cookies`,\n   * `authenticate`, or `setExtraHTTPHeaders` for authenticated pages, and\n   * `gotoOptions` / `viewport` for JavaScript-heavy pages. The model only ever\n   * supplies the page (`url`/`html`) and action-specific fields; these\n   * host-supplied options are never exposed to it.\n   */\n  options?: QuickActionCommonOptions;\n}\n\nconst DEFAULT_QUICK_ACTION_TOOLS: QuickActionToolName[] = [\n  \"markdown\",\n  \"extract\",\n  \"links\",\n  \"scrape\"\n];\n\nconst DEFAULT_QUICK_ACTION_MAX_CHARS = 50_000;\n\nconst pageInputSchema = z\n  .object({\n    url: z.string().url().optional().describe(\"URL of the page to load\"),\n    html: z\n      .string()\n      .optional()\n      .describe(\"Raw HTML to render instead of loading a URL\")\n  })\n  .refine((value) => Boolean(value.url) || Boolean(value.html), {\n    message: \"Provide either 'url' or 'html'\"\n  });\n\nfunction toPage(\n  input: { url?: string; html?: string },\n  options?: QuickActionCommonOptions\n): QuickActionPage {\n  const page = input.url ? { url: input.url } : { html: input.html as string };\n  return { ...options, ...page } as QuickActionPage;\n}\n\nfunction truncate(text: string, maxChars: number): string {\n  if (maxChars <= 0 || text.length <= maxChars) return text;\n  return `${text.slice(0, maxChars)}\\n\\n[truncated ${text.length - maxChars} characters]`;\n}\n\n/**\n * Keep a tool result within a rough character budget so a single browse cannot\n * blow the model's context window — while preserving the result's shape so the\n * model sees a consistent type across calls:\n *\n * - strings (markdown/content) are truncated to a string;\n * - arrays (links/scrape) are trimmed from the end but stay arrays;\n * - only an opaque oversized object (e.g. a sprawling `extract`) degrades to a\n *   `{ truncated, note, preview }` summary, since it cannot be trimmed safely.\n */\nfunction boundResult(value: unknown, maxChars: number): unknown {\n  if (maxChars <= 0) return value;\n  if (typeof value === \"string\") return truncate(value, maxChars);\n  let json: string;\n  try {\n    json = JSON.stringify(value);\n  } catch {\n    return value;\n  }\n  if (json.length <= maxChars) return value;\n  if (Array.isArray(value)) {\n    const trimmed = boundArray(value, maxChars);\n    // If even the first element overflows the budget, `trimmed` is empty —\n    // returning `[]` would read as \"no results\" rather than \"too large\", so\n    // fall through to the explicit truncated-preview summary instead.\n    if (trimmed.length > 0) return trimmed;\n  }\n  return {\n    truncated: true,\n    note: `Result is too large (${json.length} characters); narrow the request.`,\n    preview: `${json.slice(0, maxChars)}…`\n  };\n}\n\n/**\n * Take as many leading items as fit within `maxChars` (measured against their\n * JSON length), returning a trimmed array of the same element type. Silent by\n * design: the model gets fewer, valid items rather than a reshaped result.\n */\nfunction boundArray(value: unknown[], maxChars: number): unknown[] {\n  const out: unknown[] = [];\n  let size = 2; // the enclosing \"[]\"\n  for (const item of value) {\n    const itemSize = JSON.stringify(item).length + 1; // + a separating comma\n    if (size + itemSize > maxChars) break;\n    out.push(item);\n    size += itemSize;\n  }\n  return out;\n}\n\n/**\n * Create AI SDK tools for Browser Run [Quick Actions](https://developers.cloudflare.com/browser-run/quick-actions/):\n * stateless one-shot browsing (read a page as Markdown, extract structured\n * data with AI, list links, scrape elements). Unlike `createBrowserTools`,\n * these need only the `browser` binding — no Durable Object, loader, or\n * sandbox — so they work from any Worker.\n *\n * @example\n * ```ts\n * import { createQuickActionTools } from \"agents/browser/ai\";\n *\n * const tools = createQuickActionTools({ browser: this.env.BROWSER });\n * const result = await generateText({ model, tools, messages });\n * ```\n *\n * @deprecated Quick Actions are deprecated and won't change. Use\n * `browserTool` to drive a browser, the `web_fetch` tool from\n * `agents/webfetch` to read a page, or call the binding's\n * `quickAction()` directly.\n */\nexport function createQuickActionTools(\n  options: CreateQuickActionToolsOptions\n): ToolSet {\n  const { browser } = options;\n  const requestOptions = options.options;\n  const enabled = new Set(options.actions ?? DEFAULT_QUICK_ACTION_TOOLS);\n  const maxChars = options.maxChars ?? DEFAULT_QUICK_ACTION_MAX_CHARS;\n  const tools: ToolSet = {};\n\n  if (enabled.has(\"markdown\")) {\n    tools.browser_markdown = tool({\n      description:\n        \"Load a web page (or render raw HTML) and return its content as Markdown. Best for reading articles, docs, or any page as text.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserMarkdown(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"extract\")) {\n    tools.browser_extract = tool({\n      description:\n        \"Extract structured data from a web page using AI. Describe what you want in 'prompt'. Passing a JSON Schema in 'schema' is strongly recommended — without one the extractor often fails to produce JSON.\",\n      inputSchema: z\n        .object({\n          url: z.string().url().optional().describe(\"URL of the page to load\"),\n          html: z\n            .string()\n            .optional()\n            .describe(\"Raw HTML to render instead of loading a URL\"),\n          prompt: z\n            .string()\n            .optional()\n            .describe(\"What to extract, in natural language\"),\n          schema: z\n            .record(z.string(), z.unknown(), {\n              error: \"Schema must be a JSON object\"\n            })\n            .optional()\n            .describe(\"Optional JSON Schema describing the desired output\")\n        })\n        .refine((value) => Boolean(value.url) || Boolean(value.html), {\n          message: \"Provide either 'url' or 'html'\"\n        })\n        .refine((value) => Boolean(value.prompt) || Boolean(value.schema), {\n          message: \"Provide either 'prompt' or 'schema'\"\n        }),\n      execute: async (input) =>\n        boundResult(\n          await browserExtract(browser, {\n            ...toPage(input, requestOptions),\n            prompt: input.prompt,\n            response_format: input.schema\n              ? { type: \"json_schema\", json_schema: input.schema }\n              : undefined\n          }),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"links\")) {\n    tools.browser_links = tool({\n      description:\n        \"Return every link found on a web page (including ones not visible). Useful for discovering pages to follow.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserLinks(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"scrape\")) {\n    tools.browser_scrape = tool({\n      description:\n        \"Scrape specific elements from a web page by CSS selector. Returns the matched elements' text, HTML, and attributes.\",\n      inputSchema: z\n        .object({\n          url: z.string().url().optional().describe(\"URL of the page to load\"),\n          html: z\n            .string()\n            .optional()\n            .describe(\"Raw HTML to render instead of loading a URL\"),\n          selectors: z\n            .array(z.string())\n            .min(1)\n            .describe(\"CSS selectors to extract\")\n        })\n        .refine((value) => Boolean(value.url) || Boolean(value.html), {\n          message: \"Provide either 'url' or 'html'\"\n        }),\n      execute: async (input) =>\n        boundResult(\n          await browserScrape(browser, {\n            ...toPage(input, requestOptions),\n            elements: input.selectors.map((selector) => ({ selector }))\n          }),\n          maxChars\n        )\n    });\n  }\n\n  if (enabled.has(\"content\")) {\n    tools.browser_content = tool({\n      description:\n        \"Load a web page and return its fully rendered HTML (after JavaScript runs). Prefer 'browser_markdown' unless you need the raw HTML.\",\n      inputSchema: pageInputSchema,\n      execute: async (input) =>\n        boundResult(\n          await browserContent(browser, toPage(input, requestOptions)),\n          maxChars\n        )\n    });\n  }\n\n  return tools;\n}\n"],"mappings":"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"}

package/dist/browser/index.d.ts

@@ -1,3 +1,18 @@
+import {
+  a as InternalHostRouterLoopback,
+  c as InternalWorkerHost,
+  d as TargetOf,
+  f as TargetSchema,
+  i as InternalHostRouter,
+  l as JsonSchemaObject,
+  n as InternalHostInfo,
+  o as InternalHostRouterProps,
+  p as TypedTargetSchema,
+  r as InternalHostMessage,
+  s as InternalHostsOptions,
+  t as InternalHost,
+  u as MAX_INTERNAL_HOSTS
+} from "../internal-hosts-Kfp5A392.js";
 import {
   A as CdpSendOptions,
   C as createBrowserSession,
@@ -31,7 +46,7 @@ import {
   w as deleteBrowserSession,
   x as connectBrowser,
   y as ConnectChromiumBrowserOptions
-} from "../session-store-_IK6dV-w.js";
+} from "../session-store-B7Ca-u1t.js";
 import {
   C as browserScrape,
   E as runQuickAction,
@@ -59,28 +74,40 @@ import {
   w as browserScreenshot,
   x as browserMarkdown,
   y as browserExtract
-} from "../connector-20DJ6p4k.js";
+} from "../connector-DZ71EjE-.js";
 import {
-  a as BrowserProvider,
-  c as ResolvedBrowser,
-  d as browserRun,
-  f as CdpField,
-  g as loadCdpSpec,
-  h as SearchableCdpSpec,
-  i as BrowserOptions,
-  l as BrowserRunOptions,
-  m as CdpSpecSource,
+  C as CdpItems,
+  E as loadCdpSpec,
+  S as CdpField,
+  T as SearchableCdpSpec,
+  _ as BrowserSessionReport,
+  a as BrowserOptions,
+  b as BrowserRunProvider,
+  c as MAX_BROWSER_SCOPES,
+  d as BrowserAttachInput,
+  f as BrowserDebugLogInput,
+  g as BrowserSessionOptions,
+  h as BrowserSession,
+  i as BrowserInternalHosts,
+  l as ResolvedBrowser,
+  m as BrowserSendInput,
   n as BrowserConnectOptions,
-  o as DEFAULT_BROWSER_SCOPE,
-  p as CdpItems,
+  o as BrowserProvider,
+  p as BrowserNewTab,
   r as BrowserConnection,
-  s as MAX_BROWSER_SCOPES,
+  s as DEFAULT_BROWSER_SCOPE,
   t as Browser,
-  u as BrowserRunProvider
-} from "../browser-DlXhSAdf.js";
+  u as ACTIVE_PAGE_SESSION,
+  v as BrowserSource,
+  w as CdpSpecSource,
+  x as browserRun,
+  y as BrowserRunOptions
+} from "../browser-D9RNpJuT.js";
 import { CodemodeRuntime } from "@cloudflare/codemode";
 export {
+  ACTIVE_PAGE_SESSION,
   Browser,
+  type BrowserAttachInput,
   type BrowserBinding,
   type BrowserConnectOptions,
   type BrowserConnection,
@@ -89,19 +116,27 @@ export {
   type BrowserConnectorSessionOptions,
   type BrowserConnectorSweepOptions,
   type BrowserConnectorSweepResult,
+  type BrowserDebugLogInput,
+  type BrowserInternalHosts,
   type BrowserLiveView,
   type BrowserLiveViewTarget,
   type BrowserLiveViewUrl,
+  type BrowserNewTab,
   type BrowserOptions,
   type BrowserProvider,
   type BrowserRecording,
   BrowserRenderingError,
   type BrowserRunOptions,
   type BrowserRunProvider,
+  type BrowserSendInput,
+  BrowserSession,
   type BrowserSessionGuardrails,
   type BrowserSessionInfo,
   type BrowserSessionLock,
+  type BrowserSessionOptions,
+  type BrowserSessionReport,
   type BrowserSessionStore,
+  type BrowserSource,
   type BrowserTargetInfo,
   type CdpAttachOptions,
   CdpConnection,
@@ -120,9 +155,19 @@ export {
   DEFAULT_EXEC_SWEEP_IDLE_MS,
   DEFAULT_SWEEP_IDLE_MS,
   DurableBrowserSessionStore,
+  type InternalHost,
+  type InternalHostInfo,
+  type InternalHostMessage,
+  InternalHostRouter,
+  type InternalHostRouterLoopback,
+  type InternalHostRouterProps,
+  type InternalHostsOptions,
+  type InternalWorkerHost,
+  type JsonSchemaObject,
   type ListableBrowserSessionStore,
   type LiveViewMode,
   MAX_BROWSER_SCOPES,
+  MAX_INTERNAL_HOSTS,
   type QuickAction,
   type QuickActionBinary,
   type QuickActionBinding,
@@ -137,6 +182,9 @@ export {
   type ResolvedBrowser,
   type SearchableCdpSpec,
   type StoredBrowserSession,
+  type TargetOf,
+  type TargetSchema,
+  type TypedTargetSchema,
   browserContent,
   browserExtract,
   browserLinks,

package/dist/browser/index.js

@@ -1,5 +1,5 @@
-import { S as connectUrl, _ as listBrowserTargets, c as BrowserRenderingError, d as connectBrowser, f as connectBrowserSession, h as getBrowserRecording, m as deleteBrowserSession, n as DurableBrowserSessionStore, p as createBrowserSession, r as loadCdpSpec, t as DEFAULT_SWEEP_IDLE_MS, x as CdpSession, y as CdpConnection } from "../session-store-yvwq1f9x.js";
-import { a as browserLinks, c as browserScrape, d as runQuickAction, i as browserExtract, l as browserScreenshot, n as DEFAULT_EXEC_SWEEP_IDLE_MS, o as browserMarkdown, r as browserContent, s as browserPdf, t as BrowserConnector, u as browserSnapshot } from "../connector-DAXBOIIi.js";
-import { i as browserRun, n as DEFAULT_BROWSER_SCOPE, r as MAX_BROWSER_SCOPES, t as Browser } from "../browser-DccPw_wW.js";
+import { S as CdpConnection, T as connectUrl, _ as deleteBrowserSession, a as DEFAULT_SWEEP_IDLE_MS, b as listBrowserTargets, d as BrowserRenderingError, g as createBrowserSession, h as connectBrowserSession, m as connectBrowser, n as BrowserSession, o as DurableBrowserSessionStore, s as loadCdpSpec, t as ACTIVE_PAGE_SESSION, v as getBrowserRecording, w as CdpSession } from "../session-7CDgVE0z.js";
+import { a as browserLinks, c as browserScrape, d as runQuickAction, i as browserExtract, l as browserScreenshot, n as DEFAULT_EXEC_SWEEP_IDLE_MS, o as browserMarkdown, r as browserContent, s as browserPdf, t as BrowserConnector, u as browserSnapshot } from "../connector-CM-uuxKM.js";
+import { a as InternalHostRouter, i as browserRun, n as DEFAULT_BROWSER_SCOPE, o as MAX_INTERNAL_HOSTS, r as MAX_BROWSER_SCOPES, t as Browser } from "../browser-1eUbPvC2.js";
 import { CodemodeRuntime } from "@cloudflare/codemode";
-export { Browser, BrowserConnector, BrowserRenderingError, CdpConnection, CdpSession, CodemodeRuntime, DEFAULT_BROWSER_SCOPE, DEFAULT_EXEC_SWEEP_IDLE_MS, DEFAULT_SWEEP_IDLE_MS, DurableBrowserSessionStore, MAX_BROWSER_SCOPES, browserContent, browserExtract, browserLinks, browserMarkdown, browserPdf, browserRun, browserScrape, browserScreenshot, browserSnapshot, connectBrowser, connectBrowserSession, connectUrl, createBrowserSession, deleteBrowserSession, getBrowserRecording, listBrowserTargets, loadCdpSpec, runQuickAction };
+export { ACTIVE_PAGE_SESSION, Browser, BrowserConnector, BrowserRenderingError, BrowserSession, CdpConnection, CdpSession, CodemodeRuntime, DEFAULT_BROWSER_SCOPE, DEFAULT_EXEC_SWEEP_IDLE_MS, DEFAULT_SWEEP_IDLE_MS, DurableBrowserSessionStore, InternalHostRouter, MAX_BROWSER_SCOPES, MAX_INTERNAL_HOSTS, browserContent, browserExtract, browserLinks, browserMarkdown, browserPdf, browserRun, browserScrape, browserScreenshot, browserSnapshot, connectBrowser, connectBrowserSession, connectUrl, createBrowserSession, deleteBrowserSession, getBrowserRecording, listBrowserTargets, loadCdpSpec, runQuickAction };

package/dist/browser/tools/ai-sdk.d.ts

@@ -2,79 +2,17 @@ import {
   i as QuickActionToolName,
   r as CreateQuickActionToolsOptions,
   s as createQuickActionTools
-} from "../../ai-iXw0uOGj.js";
+} from "../../ai-CDn3Abax.js";
+import {
+  p as BrowserNewTab,
+  v as BrowserSource
+} from "../../browser-D9RNpJuT.js";
 import {
-  a as BrowserSource,
-  i as BrowserNewTab,
   n as BrowserToolOptions,
   r as BrowserToolOutput,
   t as BrowserToolInput
-} from "../../browser-tool-Cxjk5sgG.js";
-import { FlexibleSchema, JSONValue } from "ai";
-
-//#region src/browser/tool-helpers.d.ts
-/** What the model sees in place of a browser tool's output. */
-type BrowserModelOutput =
-  | {
-      type: "text";
-      value: string;
-    }
-  | {
-      type: "json";
-      value: JSONValue;
-    };
-//#endregion
-//#region src/browser/tools/ai-sdk.d.ts
-/**
- * The AI SDK tool {@link browserTool} returns. Assignable to the AI SDK's
- * `Tool`, and `execute` / `toModelOutput` are always present.
- */
-interface BrowserTool {
-  description: string;
-  inputSchema: FlexibleSchema<BrowserToolInput>;
-  execute(
-    input: BrowserToolInput,
-    options: unknown
-  ): Promise<BrowserToolOutput>;
-  toModelOutput(options: { output: BrowserToolOutput }): BrowserModelOutput;
-}
-/**
- * Create an AI SDK tool that lets the model drive a persistent browser with
- * JavaScript and the Chrome DevTools Protocol.
- *
- * The browser outlives each run: tabs, cookies, and logins carry over. The
- * model never starts, closes, or resets it, and `sessionId: "active"`
- * addresses the tab it last worked in. If the browser had to be replaced
- * (it expired or was closed), the code still runs in the new browser and the
- * result says `restarted: true`.
- *
- * Browser Run only (Chromium). Guardrails, `keepAliveMs`, and recording are
- * set on the `Browser`'s provider.
- *
- * @example
- * ```ts
- * import { Browser, browserRun } from "agents/browser";
- * import { browserTool } from "agents/browser/ai-sdk";
- *
- * export class MyAgent extends Agent<Env> {
- *   browser = new Browser({ provider: browserRun(this.env.BROWSER) });
- *
- *   constructor(ctx: AgentContext, env: Env) {
- *     super(ctx, env);
- *     this.lifecycle.use(this.browser);
- *   }
- *
- *   async onChatMessage() {
- *     const tools = {
- *       browser: browserTool({ browser: this.browser, loader: this.env.LOADER })
- *     };
- *     // …pass `tools` to streamText / generateText
- *   }
- * }
- * ```
- */
-declare function browserTool(options: BrowserToolOptions): BrowserTool;
-//#endregion
+} from "../../browser-tool-BhjCcNVE.js";
+import { n as browserTool, t as BrowserTool } from "../../ai-sdk-hW3vntnk.js";
 export {
   type BrowserNewTab,
   type BrowserSource,
@@ -87,4 +25,3 @@ export {
   browserTool,
   createQuickActionTools
 };
-//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/browser/tools/ai-sdk.js

@@ -1,6 +1,6 @@
-import { t as browserExecuteModelOutput } from "../../tool-helpers-O5BDVEAY.js";
+import { t as browserExecuteModelOutput } from "../../tool-helpers-BodWi4gd.js";
 import { createQuickActionTools } from "../ai.js";
-import { n as createBrowserToolCore, t as browserReportNotes } from "../../browser-tool-B1mhifin.js";
+import { t as createBrowserToolCore } from "../../browser-tool-lGnvEBLJ.js";
 //#region src/browser/tools/ai-sdk.ts
 /**
 * Create an AI SDK tool that lets the model drive a persistent browser with
@@ -10,7 +10,7 @@ import { n as createBrowserToolCore, t as browserReportNotes } from "../../brows
 * model never starts, closes, or resets it, and `sessionId: "active"`
 * addresses the tab it last worked in. If the browser had to be replaced
 * (it expired or was closed), the code still runs in the new browser and the
-* result says `restarted: true`.
+* result's `notice` says so.
 *
 * Browser Run only (Chromium). Guardrails, `keepAliveMs`, and recording are
 * set on the `Browser`'s provider.
@@ -43,7 +43,7 @@ function browserTool(options) {
 		description: core.description,
 		inputSchema: core.inputSchema,
 		execute: (input) => core.execute(input),
-		toModelOutput: ({ output }) => browserExecuteModelOutput(output, browserReportNotes(output))
+		toModelOutput: ({ output }) => browserExecuteModelOutput(output, output.notice ? [output.notice] : [])
 	};
 }
 //#endregion

package/dist/browser/tools/ai-sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk.js","names":[],"sources":["../../../src/browser/tools/ai-sdk.ts"],"sourcesContent":["/**\n * `agents/browser/ai-sdk` — the AI SDK tool for a persistent `Browser`.\n *\n * The older `createBrowserTools` stays in `agents/browser/ai`.\n */\nimport type { FlexibleSchema } from \"ai\";\nimport {\n  browserReportNotes,\n  createBrowserToolCore,\n  type BrowserToolInput,\n  type BrowserToolOptions,\n  type BrowserToolOutput\n} from \"../browser-tool\";\nimport {\n  browserExecuteModelOutput,\n  type BrowserModelOutput\n} from \"../tool-helpers\";\n\nexport type {\n  BrowserToolInput,\n  BrowserToolOptions,\n  BrowserToolOutput\n} from \"../browser-tool\";\nexport type { BrowserNewTab, BrowserSource } from \"../session-connector\";\n\n// Stateless Quick Action tools, so one import covers both.\nexport {\n  createQuickActionTools,\n  type CreateQuickActionToolsOptions,\n  type QuickActionToolName\n} from \"../ai\";\n\n/**\n * The AI SDK tool {@link browserTool} returns. Assignable to the AI SDK's\n * `Tool`, and `execute` / `toModelOutput` are always present.\n */\nexport interface BrowserTool {\n  description: string;\n  inputSchema: FlexibleSchema<BrowserToolInput>;\n  execute(\n    input: BrowserToolInput,\n    options: unknown\n  ): Promise<BrowserToolOutput>;\n  toModelOutput(options: { output: BrowserToolOutput }): BrowserModelOutput;\n}\n\n/**\n * Create an AI SDK tool that lets the model drive a persistent browser with\n * JavaScript and the Chrome DevTools Protocol.\n *\n * The browser outlives each run: tabs, cookies, and logins carry over. The\n * model never starts, closes, or resets it, and `sessionId: \"active\"`\n * addresses the tab it last worked in. If the browser had to be replaced\n * (it expired or was closed), the code still runs in the new browser and the\n * result says `restarted: true`.\n *\n * Browser Run only (Chromium). Guardrails, `keepAliveMs`, and recording are\n * set on the `Browser`'s provider.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/ai-sdk\";\n *\n * export class MyAgent extends Agent<Env> {\n *   browser = new Browser({ provider: browserRun(this.env.BROWSER) });\n *\n *   constructor(ctx: AgentContext, env: Env) {\n *     super(ctx, env);\n *     this.lifecycle.use(this.browser);\n *   }\n *\n *   async onChatMessage() {\n *     const tools = {\n *       browser: browserTool({ browser: this.browser, loader: this.env.LOADER })\n *     };\n *     // …pass `tools` to streamText / generateText\n *   }\n * }\n * ```\n */\nexport function browserTool(options: BrowserToolOptions): BrowserTool {\n  const core = createBrowserToolCore(options, {\n    screenshotHint:\n      \"To show a screenshot, return { type: 'browser_screenshot', mediaType, data } with data from Page.captureScreenshot and mediaType 'image/png', or 'image/jpeg' if you captured with format: 'jpeg'. The user sees the image; you get a short text summary.\"\n  });\n  return {\n    description: core.description,\n    inputSchema: core.inputSchema,\n    execute: (input) => core.execute(input),\n    toModelOutput: ({ output }) =>\n      browserExecuteModelOutput(output, browserReportNotes(output))\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,YAAY,SAA0C;CACpE,MAAM,OAAO,sBAAsB,SAAS,EAC1C,gBACE,4PACJ,CAAC;CACD,OAAO;EACL,aAAa,KAAK;EAClB,aAAa,KAAK;EAClB,UAAU,UAAU,KAAK,QAAQ,KAAK;EACtC,gBAAgB,EAAE,aAChB,0BAA0B,QAAQ,mBAAmB,MAAM,CAAC;CAChE;AACF"}
+{"version":3,"file":"ai-sdk.js","names":[],"sources":["../../../src/browser/tools/ai-sdk.ts"],"sourcesContent":["/**\n * `agents/browser/ai-sdk` — the AI SDK tool for a persistent `Browser`.\n *\n * The older `createBrowserTools` stays in `agents/browser/ai`.\n */\nimport type { FlexibleSchema } from \"ai\";\nimport {\n  createBrowserToolCore,\n  type BrowserToolInput,\n  type BrowserToolOptions,\n  type BrowserToolOutput\n} from \"../browser-tool\";\nimport {\n  browserExecuteModelOutput,\n  type BrowserModelOutput\n} from \"../tool-helpers\";\n\nexport type {\n  BrowserToolInput,\n  BrowserToolOptions,\n  BrowserToolOutput\n} from \"../browser-tool\";\nexport type { BrowserNewTab, BrowserSource } from \"../session\";\n\n// Stateless Quick Action tools, so one import covers both.\nexport {\n  createQuickActionTools,\n  type CreateQuickActionToolsOptions,\n  type QuickActionToolName\n} from \"../ai\";\n\n/**\n * The AI SDK tool {@link browserTool} returns. Assignable to the AI SDK's\n * `Tool`, and `execute` / `toModelOutput` are always present.\n */\nexport interface BrowserTool {\n  description: string;\n  inputSchema: FlexibleSchema<BrowserToolInput>;\n  execute(\n    input: BrowserToolInput,\n    options: unknown\n  ): Promise<BrowserToolOutput>;\n  toModelOutput(options: { output: BrowserToolOutput }): BrowserModelOutput;\n}\n\n/**\n * Create an AI SDK tool that lets the model drive a persistent browser with\n * JavaScript and the Chrome DevTools Protocol.\n *\n * The browser outlives each run: tabs, cookies, and logins carry over. The\n * model never starts, closes, or resets it, and `sessionId: \"active\"`\n * addresses the tab it last worked in. If the browser had to be replaced\n * (it expired or was closed), the code still runs in the new browser and the\n * result's `notice` says so.\n *\n * Browser Run only (Chromium). Guardrails, `keepAliveMs`, and recording are\n * set on the `Browser`'s provider.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/ai-sdk\";\n *\n * export class MyAgent extends Agent<Env> {\n *   browser = new Browser({ provider: browserRun(this.env.BROWSER) });\n *\n *   constructor(ctx: AgentContext, env: Env) {\n *     super(ctx, env);\n *     this.lifecycle.use(this.browser);\n *   }\n *\n *   async onChatMessage() {\n *     const tools = {\n *       browser: browserTool({ browser: this.browser, loader: this.env.LOADER })\n *     };\n *     // …pass `tools` to streamText / generateText\n *   }\n * }\n * ```\n */\nexport function browserTool(options: BrowserToolOptions): BrowserTool {\n  const core = createBrowserToolCore(options, {\n    screenshotHint:\n      \"To show a screenshot, return { type: 'browser_screenshot', mediaType, data } with data from Page.captureScreenshot and mediaType 'image/png', or 'image/jpeg' if you captured with format: 'jpeg'. The user sees the image; you get a short text summary.\"\n  });\n  return {\n    description: core.description,\n    inputSchema: core.inputSchema,\n    execute: (input) => core.execute(input),\n    toModelOutput: ({ output }) =>\n      browserExecuteModelOutput(output, output.notice ? [output.notice] : [])\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgFA,SAAgB,YAAY,SAA0C;CACpE,MAAM,OAAO,sBAAsB,SAAS,EAC1C,gBACE,4PACJ,CAAC;CACD,OAAO;EACL,aAAa,KAAK;EAClB,aAAa,KAAK;EAClB,UAAU,UAAU,KAAK,QAAQ,KAAK;EACtC,gBAAgB,EAAE,aAChB,0BAA0B,QAAQ,OAAO,SAAS,CAAC,OAAO,MAAM,IAAI,CAAC,CAAC;CAC1E;AACF"}

package/dist/browser/tools/pi.d.ts

@@ -1,10 +1,12 @@
 import {
-  a as BrowserSource,
-  i as BrowserNewTab,
+  p as BrowserNewTab,
+  v as BrowserSource
+} from "../../browser-D9RNpJuT.js";
+import {
   n as BrowserToolOptions,
   r as BrowserToolOutput,
   t as BrowserToolInput
-} from "../../browser-tool-Cxjk5sgG.js";
+} from "../../browser-tool-BhjCcNVE.js";
 import { Type } from "@earendil-works/pi-ai";
 import { ToolExecutionApi, ToolRegistration } from "@earendil-works/pi-durable";
 
@@ -28,18 +30,12 @@ declare const browserToolParameters: Type.TObject<{
   code: Type.TString;
 }>;
 /**
- * What a UI can show about a run without reading the content: the run's
- * outcome and what happened to the browser.
+ * What a UI can show about a run without reading the content: its id and
+ * outcome.
  */
 type PiBrowserToolDetails = {
   executionId: string;
   status: BrowserToolOutput["status"];
-  restarted?: true;
-  newTabs?: {
-    targetId: string;
-    url?: string;
-    title?: string;
-  }[];
 };
 type PiBrowserTool<TName extends string = "browser"> = ToolRegistration<
   typeof browserToolParameters,
@@ -53,8 +49,8 @@ type PiBrowserTool<TName extends string = "browser"> = ToolRegistration<
  *
  * Works like `browserTool` in `agents/browser/ai-sdk`: tabs, cookies, and
  * logins carry over between runs, `sessionId: "active"` addresses the tab the
- * model last worked in, and a replaced browser is reported as
- * `restarted: true`. A returned screenshot comes back as an image part that
+ * model last worked in, and a replaced browser is reported in the
+ * result's `notice`. A returned screenshot comes back as an image part that
  * the model sees, when its model accepts images.
  *
  * Each conversation gets its own active tab (see
@@ -62,7 +58,6 @@ type PiBrowserTool<TName extends string = "browser"> = ToolRegistration<
  * time, since they share its tab, and the tool doesn't rerun after an
  * eviction (its code may have clicked or
  * submitted something): pi gives the model an interrupted result instead.
- * Pass `ctx` unless the tool is built inside an Agent.
  *
  * @example
  * ```ts
@@ -78,7 +73,6 @@ type PiBrowserTool<TName extends string = "browser"> = ToolRegistration<
  *         name: "browser",
  *         tools: [
  *           browserTool({
- *             ctx: this.ctx,
  *             browser: this.browser,
  *             loader: this.env.LOADER
  *           })

package/dist/browser/tools/pi.js

@@ -1,18 +1,12 @@
-import { n as browserScreenshotOutput, t as browserExecuteModelOutput } from "../../tool-helpers-O5BDVEAY.js";
-import { n as createBrowserToolCore } from "../../browser-tool-B1mhifin.js";
+import { n as browserScreenshotOutput, t as browserExecuteModelOutput } from "../../tool-helpers-BodWi4gd.js";
+import { t as createBrowserToolCore } from "../../browser-tool-lGnvEBLJ.js";
 import { Type } from "@earendil-works/pi-ai";
 //#region src/browser/tools/pi.ts
-const browserToolParameters = Type.Object({ code: Type.String({ description: "An async arrow function that drives the browser with `cdp`" }) });
+const browserToolParameters = Type.Object({ code: Type.String({ description: "An async arrow function that drives the browser with `browser`" }) });
 function details(output) {
 	return {
 		executionId: output.executionId,
-		status: output.status,
-		...output.restarted ? { restarted: true } : {},
-		...output.newTabs ? { newTabs: output.newTabs.map((tab) => ({
-			targetId: tab.targetId,
-			...tab.url === void 0 ? {} : { url: tab.url },
-			...tab.title === void 0 ? {} : { title: tab.title }
-		})) } : {}
+		status: output.status
 	};
 }
 function text(value) {
@@ -58,8 +52,8 @@ function conversationScope(api) {
 *
 * Works like `browserTool` in `agents/browser/ai-sdk`: tabs, cookies, and
 * logins carry over between runs, `sessionId: "active"` addresses the tab the
-* model last worked in, and a replaced browser is reported as
-* `restarted: true`. A returned screenshot comes back as an image part that
+* model last worked in, and a replaced browser is reported in the
+* result's `notice`. A returned screenshot comes back as an image part that
 * the model sees, when its model accepts images.
 *
 * Each conversation gets its own active tab (see
@@ -67,7 +61,6 @@ function conversationScope(api) {
 * time, since they share its tab, and the tool doesn't rerun after an
 * eviction (its code may have clicked or
 * submitted something): pi gives the model an interrupted result instead.
-* Pass `ctx` unless the tool is built inside an Agent.
 *
 * @example
 * ```ts
@@ -83,7 +76,6 @@ function conversationScope(api) {
 *         name: "browser",
 *         tools: [
 *           browserTool({
-*             ctx: this.ctx,
 *             browser: this.browser,
 *             loader: this.env.LOADER
 *           })

package/dist/browser/tools/pi.js.map

@@ -1 +1 @@
-{"version":3,"file":"pi.js","names":[],"sources":["../../../src/browser/tools/pi.ts"],"sourcesContent":["import {\n  Type,\n  type ImageContent,\n  type TextContent\n} from \"@earendil-works/pi-ai\";\nimport type {\n  ToolExecutionApi,\n  ToolExecutionResult,\n  ToolRegistration\n} from \"@earendil-works/pi-durable\";\nimport {\n  createBrowserToolCore,\n  type BrowserToolOptions,\n  type BrowserToolOutput\n} from \"../browser-tool\";\nimport type { BrowserNewTab } from \"../session-connector\";\nimport {\n  browserExecuteModelOutput,\n  browserScreenshotOutput\n} from \"../tool-helpers\";\n\nexport type {\n  BrowserToolInput,\n  BrowserToolOptions,\n  BrowserToolOutput\n} from \"../browser-tool\";\nexport type { BrowserNewTab, BrowserSource } from \"../session-connector\";\n\nexport interface PiBrowserToolOptions<\n  TName extends string = \"browser\"\n> extends Omit<BrowserToolOptions, \"scope\"> {\n  /** The tool's name. Default `\"browser\"`. */\n  name?: TName;\n  /**\n   * Which calls share an active tab: a string for every call, or a function\n   * of the call. Defaults to `conversation:<id>` for the calling\n   * conversation, so each\n   * conversation (and each fork or subagent) on the Durable Object keeps its\n   * own tab, while cookies and logins stay shared.\n   */\n  scope?: string | ((api: ToolExecutionApi) => string);\n}\n\nconst browserToolParameters = Type.Object({\n  code: Type.String({\n    description: \"An async arrow function that drives the browser with `cdp`\"\n  })\n});\n\n/**\n * What a UI can show about a run without reading the content: the run's\n * outcome and what happened to the browser.\n */\nexport type PiBrowserToolDetails = {\n  executionId: string;\n  status: BrowserToolOutput[\"status\"];\n  restarted?: true;\n  newTabs?: { targetId: string; url?: string; title?: string }[];\n};\n\nexport type PiBrowserTool<TName extends string = \"browser\"> = ToolRegistration<\n  typeof browserToolParameters,\n  PiBrowserToolDetails\n> & {\n  readonly name: TName;\n};\n\nfunction details(output: BrowserToolOutput): PiBrowserToolDetails {\n  return {\n    executionId: output.executionId,\n    status: output.status,\n    ...(output.restarted ? { restarted: true as const } : {}),\n    ...(output.newTabs\n      ? {\n          newTabs: output.newTabs.map((tab: BrowserNewTab) => ({\n            targetId: tab.targetId,\n            ...(tab.url === undefined ? {} : { url: tab.url }),\n            ...(tab.title === undefined ? {} : { title: tab.title })\n          }))\n        }\n      : {})\n  };\n}\n\nfunction text(value: unknown): TextContent {\n  return {\n    type: \"text\",\n    text: typeof value === \"string\" ? value : JSON.stringify(value)\n  };\n}\n\n/**\n * The tool result pi stores and sends: the model projection of the run as\n * JSON (no `calls` log, bounded `logs`), and a screenshot as an image part\n * after it. pi-ai only sends the image to models that accept images.\n */\nfunction browserToolResult(\n  output: BrowserToolOutput\n): ToolExecutionResult<PiBrowserToolDetails> {\n  const isError = output.status === \"error\";\n  const screenshot = browserScreenshotOutput(output);\n  if (!screenshot) {\n    return {\n      output: [text(browserExecuteModelOutput(output).value)],\n      details: details(output),\n      ...(isError ? { isError } : {})\n    };\n  }\n\n  // No size check: a screenshot comes from one cdp.send result, which\n  // codemode caps at 1 MB, well under what model providers accept.\n  const bytes = Math.floor((screenshot.data.length * 3) / 4).toLocaleString();\n  // Keep the rest of the result (status, restarted, notice, newTabs) around\n  // the sentence that replaces the screenshot.\n  const summary = browserExecuteModelOutput({\n    ...output,\n    result: `Screenshot attached as an image (${screenshot.mediaType}, approximately ${bytes} bytes). If you can't see it, read the page with Runtime.evaluate instead.`\n  }).value;\n  const image: ImageContent = {\n    type: \"image\",\n    data: screenshot.data,\n    mimeType: screenshot.mediaType\n  };\n  return {\n    output: [text(summary), image],\n    details: details(output)\n  };\n}\n\nfunction conversationScope(api: ToolExecutionApi): string {\n  return `conversation:${api.conversationId}`;\n}\n\n/**\n * Create a pi-durable tool that lets the model drive a persistent browser\n * with JavaScript and the Chrome DevTools Protocol.\n *\n * Works like `browserTool` in `agents/browser/ai-sdk`: tabs, cookies, and\n * logins carry over between runs, `sessionId: \"active\"` addresses the tab the\n * model last worked in, and a replaced browser is reported as\n * `restarted: true`. A returned screenshot comes back as an image part that\n * the model sees, when its model accepts images.\n *\n * Each conversation gets its own active tab (see\n * {@link PiBrowserToolOptions.scope}). A conversation's calls run one at a\n * time, since they share its tab, and the tool doesn't rerun after an\n * eviction (its code may have clicked or\n * submitted something): pi gives the model an interrupted result instead.\n * Pass `ctx` unless the tool is built inside an Agent.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/pi\";\n *\n * export class MyAgent extends DurableObject<Env> {\n *   readonly browser = new Browser({ provider: browserRun(this.env.BROWSER) });\n *   readonly registry = createRegistry();\n *   readonly harness = new PiHarness({\n *     harness: ({ storage, context, onWake }) => {\n *       this.registry.install({\n *         name: \"browser\",\n *         tools: [\n *           browserTool({\n *             ctx: this.ctx,\n *             browser: this.browser,\n *             loader: this.env.LOADER\n *           })\n *         ]\n *       });\n *       return Harness.open(\n *         storage,\n *         { models, registry: this.registry, onWake },\n *         context\n *       );\n *     }\n *   });\n *   readonly lifecycle = Lifecycle.install(this)\n *     .use(this.browser)\n *     .use(this.harness);\n * }\n * ```\n */\nexport function browserTool<TName extends string = \"browser\">(\n  options: PiBrowserToolOptions<TName>\n): PiBrowserTool<TName> {\n  const { scope = conversationScope, ...coreOptions } = options;\n  const core = createBrowserToolCore(coreOptions, {\n    screenshotHint:\n      \"To see a screenshot, return { type: 'browser_screenshot', mediaType, data } with data from Page.captureScreenshot and mediaType 'image/png', or 'image/jpeg' if you captured with format: 'jpeg'. The image is attached to the result.\"\n  });\n  return {\n    name: options.name ?? (\"browser\" as TName),\n    description: core.description,\n    parameters: browserToolParameters,\n    // A conversation's calls share its tab, so they must not interleave.\n    executionMode: \"sequential\",\n    // The code may have clicked or submitted something; don't run it twice.\n    replay: \"unsafe\",\n    async execute(args, api) {\n      const callScope = typeof scope === \"string\" ? scope : scope(api);\n      return browserToolResult(\n        await core.execute({ code: args.code }, callScope)\n      );\n    }\n  };\n}\n"],"mappings":";;;;AA2CA,MAAM,wBAAwB,KAAK,OAAO,EACxC,MAAM,KAAK,OAAO,EAChB,aAAa,6DACf,CAAC,EACH,CAAC;AAoBD,SAAS,QAAQ,QAAiD;CAChE,OAAO;EACL,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,GAAI,OAAO,YAAY,EAAE,WAAW,KAAc,IAAI,CAAC;EACvD,GAAI,OAAO,UACP,EACE,SAAS,OAAO,QAAQ,KAAK,SAAwB;GACnD,UAAU,IAAI;GACd,GAAI,IAAI,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI;GAChD,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;EACxD,EAAE,EACJ,IACA,CAAC;CACP;AACF;AAEA,SAAS,KAAK,OAA6B;CACzC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;CAChE;AACF;;;;;;AAOA,SAAS,kBACP,QAC2C;CAC3C,MAAM,UAAU,OAAO,WAAW;CAClC,MAAM,aAAa,wBAAwB,MAAM;CACjD,IAAI,CAAC,YACH,OAAO;EACL,QAAQ,CAAC,KAAK,0BAA0B,MAAM,CAAC,CAAC,KAAK,CAAC;EACtD,SAAS,QAAQ,MAAM;EACvB,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC/B;CAKF,MAAM,QAAQ,KAAK,MAAO,WAAW,KAAK,SAAS,IAAK,CAAC,CAAC,CAAC,eAAe;CAG1E,MAAM,UAAU,0BAA0B;EACxC,GAAG;EACH,QAAQ,oCAAoC,WAAW,UAAU,kBAAkB,MAAM;CAC3F,CAAC,CAAC,CAAC;CACH,MAAM,QAAsB;EAC1B,MAAM;EACN,MAAM,WAAW;EACjB,UAAU,WAAW;CACvB;CACA,OAAO;EACL,QAAQ,CAAC,KAAK,OAAO,GAAG,KAAK;EAC7B,SAAS,QAAQ,MAAM;CACzB;AACF;AAEA,SAAS,kBAAkB,KAA+B;CACxD,OAAO,gBAAgB,IAAI;AAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,YACd,SACsB;CACtB,MAAM,EAAE,QAAQ,mBAAmB,GAAG,gBAAgB;CACtD,MAAM,OAAO,sBAAsB,aAAa,EAC9C,gBACE,yOACJ,CAAC;CACD,OAAO;EACL,MAAM,QAAQ,QAAS;EACvB,aAAa,KAAK;EAClB,YAAY;EAEZ,eAAe;EAEf,QAAQ;EACR,MAAM,QAAQ,MAAM,KAAK;GACvB,MAAM,YAAY,OAAO,UAAU,WAAW,QAAQ,MAAM,GAAG;GAC/D,OAAO,kBACL,MAAM,KAAK,QAAQ,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,CACnD;EACF;CACF;AACF"}
+{"version":3,"file":"pi.js","names":[],"sources":["../../../src/browser/tools/pi.ts"],"sourcesContent":["import {\n  Type,\n  type ImageContent,\n  type TextContent\n} from \"@earendil-works/pi-ai\";\nimport type {\n  ToolExecutionApi,\n  ToolExecutionResult,\n  ToolRegistration\n} from \"@earendil-works/pi-durable\";\nimport {\n  createBrowserToolCore,\n  type BrowserToolOptions,\n  type BrowserToolOutput\n} from \"../browser-tool\";\nimport {\n  browserExecuteModelOutput,\n  browserScreenshotOutput\n} from \"../tool-helpers\";\n\nexport type {\n  BrowserToolInput,\n  BrowserToolOptions,\n  BrowserToolOutput\n} from \"../browser-tool\";\nexport type { BrowserNewTab, BrowserSource } from \"../session\";\n\nexport interface PiBrowserToolOptions<\n  TName extends string = \"browser\"\n> extends Omit<BrowserToolOptions, \"scope\"> {\n  /** The tool's name. Default `\"browser\"`. */\n  name?: TName;\n  /**\n   * Which calls share an active tab: a string for every call, or a function\n   * of the call. Defaults to `conversation:<id>` for the calling\n   * conversation, so each\n   * conversation (and each fork or subagent) on the Durable Object keeps its\n   * own tab, while cookies and logins stay shared.\n   */\n  scope?: string | ((api: ToolExecutionApi) => string);\n}\n\nconst browserToolParameters = Type.Object({\n  code: Type.String({\n    description:\n      \"An async arrow function that drives the browser with `browser`\"\n  })\n});\n\n/**\n * What a UI can show about a run without reading the content: its id and\n * outcome.\n */\nexport type PiBrowserToolDetails = {\n  executionId: string;\n  status: BrowserToolOutput[\"status\"];\n};\n\nexport type PiBrowserTool<TName extends string = \"browser\"> = ToolRegistration<\n  typeof browserToolParameters,\n  PiBrowserToolDetails\n> & {\n  readonly name: TName;\n};\n\nfunction details(output: BrowserToolOutput): PiBrowserToolDetails {\n  return {\n    executionId: output.executionId,\n    status: output.status\n  };\n}\n\nfunction text(value: unknown): TextContent {\n  return {\n    type: \"text\",\n    text: typeof value === \"string\" ? value : JSON.stringify(value)\n  };\n}\n\n/**\n * The tool result pi stores and sends: the model projection of the run as\n * JSON (no `calls` log, bounded `logs`), and a screenshot as an image part\n * after it. pi-ai only sends the image to models that accept images.\n */\nfunction browserToolResult(\n  output: BrowserToolOutput\n): ToolExecutionResult<PiBrowserToolDetails> {\n  const isError = output.status === \"error\";\n  const screenshot = browserScreenshotOutput(output);\n  if (!screenshot) {\n    return {\n      output: [text(browserExecuteModelOutput(output).value)],\n      details: details(output),\n      ...(isError ? { isError } : {})\n    };\n  }\n\n  // No size check: browserScreenshotOutput only accepts images up to 1 MB,\n  // well under what model providers accept.\n  const bytes = Math.floor((screenshot.data.length * 3) / 4).toLocaleString();\n  // Keep the rest of the result (status, notice) around\n  // the sentence that replaces the screenshot.\n  const summary = browserExecuteModelOutput({\n    ...output,\n    result: `Screenshot attached as an image (${screenshot.mediaType}, approximately ${bytes} bytes). If you can't see it, read the page with Runtime.evaluate instead.`\n  }).value;\n  const image: ImageContent = {\n    type: \"image\",\n    data: screenshot.data,\n    mimeType: screenshot.mediaType\n  };\n  return {\n    output: [text(summary), image],\n    details: details(output)\n  };\n}\n\nfunction conversationScope(api: ToolExecutionApi): string {\n  return `conversation:${api.conversationId}`;\n}\n\n/**\n * Create a pi-durable tool that lets the model drive a persistent browser\n * with JavaScript and the Chrome DevTools Protocol.\n *\n * Works like `browserTool` in `agents/browser/ai-sdk`: tabs, cookies, and\n * logins carry over between runs, `sessionId: \"active\"` addresses the tab the\n * model last worked in, and a replaced browser is reported in the\n * result's `notice`. A returned screenshot comes back as an image part that\n * the model sees, when its model accepts images.\n *\n * Each conversation gets its own active tab (see\n * {@link PiBrowserToolOptions.scope}). A conversation's calls run one at a\n * time, since they share its tab, and the tool doesn't rerun after an\n * eviction (its code may have clicked or\n * submitted something): pi gives the model an interrupted result instead.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/pi\";\n *\n * export class MyAgent extends DurableObject<Env> {\n *   readonly browser = new Browser({ provider: browserRun(this.env.BROWSER) });\n *   readonly registry = createRegistry();\n *   readonly harness = new PiHarness({\n *     harness: ({ storage, context, onWake }) => {\n *       this.registry.install({\n *         name: \"browser\",\n *         tools: [\n *           browserTool({\n *             browser: this.browser,\n *             loader: this.env.LOADER\n *           })\n *         ]\n *       });\n *       return Harness.open(\n *         storage,\n *         { models, registry: this.registry, onWake },\n *         context\n *       );\n *     }\n *   });\n *   readonly lifecycle = Lifecycle.install(this)\n *     .use(this.browser)\n *     .use(this.harness);\n * }\n * ```\n */\nexport function browserTool<TName extends string = \"browser\">(\n  options: PiBrowserToolOptions<TName>\n): PiBrowserTool<TName> {\n  const { scope = conversationScope, ...coreOptions } = options;\n  const core = createBrowserToolCore(coreOptions, {\n    screenshotHint:\n      \"To see a screenshot, return { type: 'browser_screenshot', mediaType, data } with data from Page.captureScreenshot and mediaType 'image/png', or 'image/jpeg' if you captured with format: 'jpeg'. The image is attached to the result.\"\n  });\n  return {\n    name: options.name ?? (\"browser\" as TName),\n    description: core.description,\n    parameters: browserToolParameters,\n    // A conversation's calls share its tab, so they must not interleave.\n    executionMode: \"sequential\",\n    // The code may have clicked or submitted something; don't run it twice.\n    replay: \"unsafe\",\n    async execute(args, api) {\n      const callScope = typeof scope === \"string\" ? scope : scope(api);\n      return browserToolResult(\n        await core.execute({ code: args.code }, callScope)\n      );\n    }\n  };\n}\n"],"mappings":";;;;AA0CA,MAAM,wBAAwB,KAAK,OAAO,EACxC,MAAM,KAAK,OAAO,EAChB,aACE,iEACJ,CAAC,EACH,CAAC;AAkBD,SAAS,QAAQ,QAAiD;CAChE,OAAO;EACL,aAAa,OAAO;EACpB,QAAQ,OAAO;CACjB;AACF;AAEA,SAAS,KAAK,OAA6B;CACzC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;CAChE;AACF;;;;;;AAOA,SAAS,kBACP,QAC2C;CAC3C,MAAM,UAAU,OAAO,WAAW;CAClC,MAAM,aAAa,wBAAwB,MAAM;CACjD,IAAI,CAAC,YACH,OAAO;EACL,QAAQ,CAAC,KAAK,0BAA0B,MAAM,CAAC,CAAC,KAAK,CAAC;EACtD,SAAS,QAAQ,MAAM;EACvB,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC/B;CAKF,MAAM,QAAQ,KAAK,MAAO,WAAW,KAAK,SAAS,IAAK,CAAC,CAAC,CAAC,eAAe;CAG1E,MAAM,UAAU,0BAA0B;EACxC,GAAG;EACH,QAAQ,oCAAoC,WAAW,UAAU,kBAAkB,MAAM;CAC3F,CAAC,CAAC,CAAC;CACH,MAAM,QAAsB;EAC1B,MAAM;EACN,MAAM,WAAW;EACjB,UAAU,WAAW;CACvB;CACA,OAAO;EACL,QAAQ,CAAC,KAAK,OAAO,GAAG,KAAK;EAC7B,SAAS,QAAQ,MAAM;CACzB;AACF;AAEA,SAAS,kBAAkB,KAA+B;CACxD,OAAO,gBAAgB,IAAI;AAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,YACd,SACsB;CACtB,MAAM,EAAE,QAAQ,mBAAmB,GAAG,gBAAgB;CACtD,MAAM,OAAO,sBAAsB,aAAa,EAC9C,gBACE,yOACJ,CAAC;CACD,OAAO;EACL,MAAM,QAAQ,QAAS;EACvB,aAAa,KAAK;EAClB,YAAY;EAEZ,eAAe;EAEf,QAAQ;EACR,MAAM,QAAQ,MAAM,KAAK;GACvB,MAAM,YAAY,OAAO,UAAU,WAAW,QAAQ,MAAM,GAAG;GAC/D,OAAO,kBACL,MAAM,KAAK,QAAQ,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,CACnD;EACF;CACF;AACF"}