agents 0.30.1 → 0.32.0

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

@@ -1,6 +1,6 @@
-import { n as browserScreenshotOutput, t as browserExecuteModelOutput } from "../../tool-helpers-O5BDVEAY.js";
+import { n as browserScreenshotOutput, t as browserExecuteModelOutput } from "../../tool-helpers-BI7ifO2S.js";
 import { createBrowserRuntime } from "../ai.js";
-import { n as createBrowserToolCore } from "../../browser-tool-B1mhifin.js";
+import { t as createBrowserToolCore } from "../../browser-tool-DRan7Lk6.js";
 import { z } from "zod";
 import { toolDefinition } from "@tanstack/ai";
 //#region src/browser/tanstack-ai.ts
@@ -38,6 +38,10 @@ import { toolDefinition } from "@tanstack/ai";
 *   messages,
 * });
 * ```
+*
+* @deprecated Use `browserTool` from `agents/browser/ai-sdk`,
+* `agents/browser/tanstack-ai` or `agents/browser/pi`. See
+* https://github.com/cloudflare/agents/blob/main/docs/agents/browse-the-web.md#persistent-browser
 */
 function createBrowserTools(options) {
 	const { tools } = createBrowserRuntime({
@@ -99,8 +103,8 @@ function browserToolModelResult(output) {
 *
 * 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`. The tool is named `browser` unless you pass `name`.
+* model last worked in, and a replaced browser is reported in the
+* result's `notice`. The tool is named `browser` unless you pass `name`.
 *
 * Unlike the AI SDK tool, the host gets the same output as the model, and
 * screenshots aren't supported: a returned screenshot is replaced by a

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

@@ -1 +1 @@
-{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../../src/browser/tanstack-ai.ts","../../../src/browser/tools/tanstack-ai.ts"],"sourcesContent":["/**\n * The legacy TanStack AI `createBrowserTools`. `agents/browser/tanstack-ai`\n * (`tools/tanstack-ai.ts`) re-exports it until it's retired.\n */\nimport { toolDefinition } from \"@tanstack/ai\";\nimport type { ServerTool } from \"@tanstack/ai\";\nimport type { ProxyToolOutput } from \"@cloudflare/codemode\";\nimport { z } from \"zod\";\nimport { createBrowserRuntime, type CreateBrowserToolsOptions } from \"./ai\";\n\nexport type { CreateBrowserToolsOptions } from \"./ai\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array with a single durable `browser_execute` `ServerTool`\n * backed by the same codemode runtime as `agents/browser/ai` — the model\n * writes TypeScript against the `cdp` connector and browser sessions\n * survive pauses.\n *\n * The stateless Quick Action tools are not surfaced through this TanStack\n * wrapper (it exposes only `browser_execute`); use `createQuickActionTools`\n * from `agents/browser/ai` if you want them.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n */\nexport function createBrowserTools(\n  options: CreateBrowserToolsOptions\n): ServerTool[] {\n  // This wrapper only surfaces `browser_execute`, so don't build the default-on\n  // Quick Action tools just to discard them.\n  const { tools } = createBrowserRuntime({ ...options, quickActions: false });\n  const executeTool = tools.browser_execute;\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description:\n      typeof executeTool.description === \"function\"\n        ? \"\"\n        : (executeTool.description ?? \"\"),\n    inputSchema: z.object({\n      code: z.string().meta({\n        description:\n          \"TypeScript async arrow function that uses the cdp connector\"\n      })\n    })\n  }).server(async ({ code }) => {\n    if (!executeTool.execute) {\n      throw new Error(\"browser_execute tool is not executable\");\n    }\n    const result = (await executeTool.execute({ code }, {\n      toolCallId: crypto.randomUUID(),\n      messages: [],\n      context: {}\n    } as never)) as ProxyToolOutput;\n    // TanStack has a single return channel, so what the host sees is what the\n    // model sees: apply the AI SDK path's `toModelOutput` projection so a\n    // screenshot's base64 cannot reach the model and the durable `calls` log\n    // stays out of its context. The execution envelope (status, executionId)\n    // is preserved either way.\n    const modelOutput = await executeTool.toModelOutput?.({\n      toolCallId: crypto.randomUUID(),\n      input: { code },\n      output: result\n    });\n    if (modelOutput?.type === \"error-text\") {\n      throw new Error(modelOutput.value);\n    }\n    if (modelOutput?.type === \"text\") {\n      return { ...result, result: modelOutput.value };\n    }\n    if (modelOutput?.type === \"json\") {\n      return modelOutput.value;\n    }\n    return result;\n  });\n\n  return [execute];\n}\n","/**\n * `agents/browser/tanstack-ai` — the TanStack AI tool for a persistent\n * `Browser`.\n *\n * The older `createBrowserTools` lives in `../tanstack-ai.ts` and is\n * re-exported here until it's retired.\n */\nimport { toolDefinition } from \"@tanstack/ai\";\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-connector\";\n\nexport interface TanStackBrowserToolOptions<\n  TName extends string = \"browser\"\n> extends BrowserToolOptions {\n  /** The tool's name. TanStack AI tools carry it in the definition. */\n  name?: TName;\n}\n\n/**\n * What the model sees from one run. TanStack AI has one return channel, so\n * the host gets this too: no `calls` log, bounded `logs`, and a screenshot\n * replaced by a sentence saying it was left out.\n */\nfunction browserToolModelResult(output: BrowserToolOutput): unknown {\n  const screenshot = browserScreenshotOutput(output);\n  if (!screenshot) return browserExecuteModelOutput(output).value;\n  const bytes = Math.floor((screenshot.data.length * 3) / 4);\n  // Keep the rest of the result (status, restarted, notice, newTabs).\n  return browserExecuteModelOutput({\n    ...output,\n    result: `Screenshot captured (${screenshot.mediaType}, approximately ${bytes.toLocaleString()} bytes), but this tool can't return images, so neither you nor the user can see it. Read the page with Runtime.evaluate instead.`\n  }).value;\n}\n\n/**\n * Create a TanStack AI 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`. The tool is named `browser` unless you pass `name`.\n *\n * Unlike the AI SDK tool, the host gets the same output as the model, and\n * screenshots aren't supported: a returned screenshot is replaced by a\n * sentence saying it was left out.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\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 stream = chat({\n *       adapter,\n *       tools: [browserTool({ browser: this.browser, loader: this.env.LOADER })],\n *       messages\n *     });\n *   }\n * }\n * ```\n */\nexport function browserTool<TName extends string = \"browser\">(\n  options: TanStackBrowserToolOptions<TName>\n) {\n  const core = createBrowserToolCore(options, {\n    screenshotHint:\n      \"This tool can't return images, so don't take screenshots; read the page with Runtime.evaluate (for example document.body.innerText) instead.\"\n  });\n  return toolDefinition({\n    name: options.name ?? (\"browser\" as TName),\n    description: core.description,\n    inputSchema: core.inputSchema\n  }).server(async (input) => browserToolModelResult(await core.execute(input)));\n}\n\nexport {\n  createBrowserTools,\n  type CreateBrowserToolsOptions\n} from \"../tanstack-ai\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,mBACd,SACc;CAGd,MAAM,EAAE,UAAU,qBAAqB;EAAE,GAAG;EAAS,cAAc;CAAM,CAAC;CAC1E,MAAM,cAAc,MAAM;CA6C1B,OAAO,CA3CS,eAAe;EAC7B,MAAM;EACN,aACE,OAAO,YAAY,gBAAgB,aAC/B,KACC,YAAY,eAAe;EAClC,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aACE,8DACJ,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,IAAI,CAAC,YAAY,SACf,MAAM,IAAI,MAAM,wCAAwC;EAE1D,MAAM,SAAU,MAAM,YAAY,QAAQ,EAAE,KAAK,GAAG;GAClD,YAAY,OAAO,WAAW;GAC9B,UAAU,CAAC;GACX,SAAS,CAAC;EACZ,CAAU;EAMV,MAAM,cAAc,MAAM,YAAY,gBAAgB;GACpD,YAAY,OAAO,WAAW;GAC9B,OAAO,EAAE,KAAK;GACd,QAAQ;EACV,CAAC;EACD,IAAI,aAAa,SAAS,cACxB,MAAM,IAAI,MAAM,YAAY,KAAK;EAEnC,IAAI,aAAa,SAAS,QACxB,OAAO;GAAE,GAAG;GAAQ,QAAQ,YAAY;EAAM;EAEhD,IAAI,aAAa,SAAS,QACxB,OAAO,YAAY;EAErB,OAAO;CACT,CAEc,CAAC;AACjB;;;;;;;;;;;;;;;AC1DA,SAAS,uBAAuB,QAAoC;CAClE,MAAM,aAAa,wBAAwB,MAAM;CACjD,IAAI,CAAC,YAAY,OAAO,0BAA0B,MAAM,CAAC,CAAC;CAC1D,MAAM,QAAQ,KAAK,MAAO,WAAW,KAAK,SAAS,IAAK,CAAC;CAEzD,OAAO,0BAA0B;EAC/B,GAAG;EACH,QAAQ,wBAAwB,WAAW,UAAU,kBAAkB,MAAM,eAAe,EAAE;CAChG,CAAC,CAAC,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,YACd,SACA;CACA,MAAM,OAAO,sBAAsB,SAAS,EAC1C,gBACE,+IACJ,CAAC;CACD,OAAO,eAAe;EACpB,MAAM,QAAQ,QAAS;EACvB,aAAa,KAAK;EAClB,aAAa,KAAK;CACpB,CAAC,CAAC,CAAC,OAAO,OAAO,UAAU,uBAAuB,MAAM,KAAK,QAAQ,KAAK,CAAC,CAAC;AAC9E"}
+{"version":3,"file":"tanstack-ai.js","names":[],"sources":["../../../src/browser/tanstack-ai.ts","../../../src/browser/tools/tanstack-ai.ts"],"sourcesContent":["/**\n * The legacy TanStack AI `createBrowserTools`. `agents/browser/tanstack-ai`\n * (`tools/tanstack-ai.ts`) re-exports it until it's retired.\n */\nimport { toolDefinition } from \"@tanstack/ai\";\nimport type { SchemaInput, ServerTool } from \"@tanstack/ai\";\nimport type { ProxyToolOutput } from \"@cloudflare/codemode\";\nimport { z } from \"zod\";\nimport { createBrowserRuntime, type CreateBrowserToolsOptions } from \"./ai\";\n\nexport type { CreateBrowserToolsOptions } from \"./ai\";\n\n/**\n * Create TanStack AI tools for browser automation via CDP code mode.\n *\n * Returns an array with a single durable `browser_execute` `ServerTool`\n * backed by the same codemode runtime as `agents/browser/ai` — the model\n * writes TypeScript against the `cdp` connector and browser sessions\n * survive pauses.\n *\n * The stateless Quick Action tools are not surfaced through this TanStack\n * wrapper (it exposes only `browser_execute`); use `createQuickActionTools`\n * from `agents/browser/ai` if you want them.\n *\n * @example\n * ```ts\n * import { createBrowserTools } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\n *\n * // inside a Durable Object / Agent:\n * const browserTools = createBrowserTools({\n *   ctx: this.ctx,\n *   browser: this.env.BROWSER,\n *   loader: this.env.LOADER,\n * });\n *\n * const stream = chat({\n *   adapter: openaiText(\"gpt-4o\"),\n *   tools: [...browserTools, ...otherTools],\n *   messages,\n * });\n * ```\n *\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): ServerTool<SchemaInput, SchemaInput>[] {\n  // This wrapper only surfaces `browser_execute`, so don't build the default-on\n  // Quick Action tools just to discard them.\n  const { tools } = createBrowserRuntime({ ...options, quickActions: false });\n  const executeTool = tools.browser_execute;\n\n  const execute = toolDefinition({\n    name: \"browser_execute\" as const,\n    description:\n      typeof executeTool.description === \"function\"\n        ? \"\"\n        : (executeTool.description ?? \"\"),\n    inputSchema: z.object({\n      code: z.string().meta({\n        description:\n          \"TypeScript async arrow function that uses the cdp connector\"\n      })\n    })\n  }).server(async ({ code }) => {\n    if (!executeTool.execute) {\n      throw new Error(\"browser_execute tool is not executable\");\n    }\n    const result = (await executeTool.execute({ code }, {\n      toolCallId: crypto.randomUUID(),\n      messages: [],\n      context: {}\n    } as never)) as ProxyToolOutput;\n    // TanStack has a single return channel, so what the host sees is what the\n    // model sees: apply the AI SDK path's `toModelOutput` projection so a\n    // screenshot's base64 cannot reach the model and the durable `calls` log\n    // stays out of its context. The execution envelope (status, executionId)\n    // is preserved either way.\n    const modelOutput = await executeTool.toModelOutput?.({\n      toolCallId: crypto.randomUUID(),\n      input: { code },\n      output: result\n    });\n    if (modelOutput?.type === \"error-text\") {\n      throw new Error(modelOutput.value);\n    }\n    if (modelOutput?.type === \"text\") {\n      return { ...result, result: modelOutput.value };\n    }\n    if (modelOutput?.type === \"json\") {\n      return modelOutput.value;\n    }\n    return result;\n  });\n\n  return [execute];\n}\n","/**\n * `agents/browser/tanstack-ai` — the TanStack AI tool for a persistent\n * `Browser`.\n *\n * The older `createBrowserTools` lives in `../tanstack-ai.ts` and is\n * re-exported here until it's retired.\n */\nimport { toolDefinition } from \"@tanstack/ai\";\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 TanStackBrowserToolOptions<\n  TName extends string = \"browser\"\n> extends BrowserToolOptions {\n  /** The tool's name. TanStack AI tools carry it in the definition. */\n  name?: TName;\n}\n\n/**\n * What the model sees from one run. TanStack AI has one return channel, so\n * the host gets this too: no `calls` log, bounded `logs`, and a screenshot\n * replaced by a sentence saying it was left out.\n */\nfunction browserToolModelResult(output: BrowserToolOutput): unknown {\n  const screenshot = browserScreenshotOutput(output);\n  if (!screenshot) return browserExecuteModelOutput(output).value;\n  const bytes = Math.floor((screenshot.data.length * 3) / 4);\n  // Keep the rest of the result (status, notice).\n  return browserExecuteModelOutput({\n    ...output,\n    result: `Screenshot captured (${screenshot.mediaType}, approximately ${bytes.toLocaleString()} bytes), but this tool can't return images, so neither you nor the user can see it. Read the page with Runtime.evaluate instead.`\n  }).value;\n}\n\n/**\n * Create a TanStack AI 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`. The tool is named `browser` unless you pass `name`.\n *\n * Unlike the AI SDK tool, the host gets the same output as the model, and\n * screenshots aren't supported: a returned screenshot is replaced by a\n * sentence saying it was left out.\n *\n * @example\n * ```ts\n * import { Browser, browserRun } from \"agents/browser\";\n * import { browserTool } from \"agents/browser/tanstack-ai\";\n * import { chat } from \"@tanstack/ai\";\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 stream = chat({\n *       adapter,\n *       tools: [browserTool({ browser: this.browser, loader: this.env.LOADER })],\n *       messages\n *     });\n *   }\n * }\n * ```\n */\nexport function browserTool<TName extends string = \"browser\">(\n  options: TanStackBrowserToolOptions<TName>\n) {\n  const core = createBrowserToolCore(options, {\n    screenshotHint:\n      \"This tool can't return images, so don't take screenshots; read the page with Runtime.evaluate (for example document.body.innerText) instead.\"\n  });\n  return toolDefinition({\n    name: options.name ?? (\"browser\" as TName),\n    description: core.description,\n    inputSchema: core.inputSchema\n  }).server(async (input) => browserToolModelResult(await core.execute(input)));\n}\n\nexport {\n  createBrowserTools,\n  type CreateBrowserToolsOptions\n} from \"../tanstack-ai\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,mBACd,SACwC;CAGxC,MAAM,EAAE,UAAU,qBAAqB;EAAE,GAAG;EAAS,cAAc;CAAM,CAAC;CAC1E,MAAM,cAAc,MAAM;CA6C1B,OAAO,CA3CS,eAAe;EAC7B,MAAM;EACN,aACE,OAAO,YAAY,gBAAgB,aAC/B,KACC,YAAY,eAAe;EAClC,aAAa,EAAE,OAAO,EACpB,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,EACpB,aACE,8DACJ,CAAC,EACH,CAAC;CACH,CAAC,CAAC,CAAC,OAAO,OAAO,EAAE,WAAW;EAC5B,IAAI,CAAC,YAAY,SACf,MAAM,IAAI,MAAM,wCAAwC;EAE1D,MAAM,SAAU,MAAM,YAAY,QAAQ,EAAE,KAAK,GAAG;GAClD,YAAY,OAAO,WAAW;GAC9B,UAAU,CAAC;GACX,SAAS,CAAC;EACZ,CAAU;EAMV,MAAM,cAAc,MAAM,YAAY,gBAAgB;GACpD,YAAY,OAAO,WAAW;GAC9B,OAAO,EAAE,KAAK;GACd,QAAQ;EACV,CAAC;EACD,IAAI,aAAa,SAAS,cACxB,MAAM,IAAI,MAAM,YAAY,KAAK;EAEnC,IAAI,aAAa,SAAS,QACxB,OAAO;GAAE,GAAG;GAAQ,QAAQ,YAAY;EAAM;EAEhD,IAAI,aAAa,SAAS,QACxB,OAAO,YAAY;EAErB,OAAO;CACT,CAEc,CAAC;AACjB;;;;;;;;;;;;;;;AC9DA,SAAS,uBAAuB,QAAoC;CAClE,MAAM,aAAa,wBAAwB,MAAM;CACjD,IAAI,CAAC,YAAY,OAAO,0BAA0B,MAAM,CAAC,CAAC;CAC1D,MAAM,QAAQ,KAAK,MAAO,WAAW,KAAK,SAAS,IAAK,CAAC;CAEzD,OAAO,0BAA0B;EAC/B,GAAG;EACH,QAAQ,wBAAwB,WAAW,UAAU,kBAAkB,MAAM,eAAe,EAAE;CAChG,CAAC,CAAC,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,YACd,SACA;CACA,MAAM,OAAO,sBAAsB,SAAS,EAC1C,gBACE,+IACJ,CAAC;CACD,OAAO,eAAe;EACpB,MAAM,QAAQ,QAAS;EACvB,aAAa,KAAK;EAClB,aAAa,KAAK;CACpB,CAAC,CAAC,CAAC,OAAO,OAAO,UAAU,uBAAuB,MAAM,KAAK,QAAQ,KAAK,CAAC,CAAC;AAC9E"}

package/dist/{browser-DccPw_wW.js → browser-1eUbPvC2.js}

@@ -1,7 +1,227 @@
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
 import { t as _classPrivateMethodInitSpec } from "./classPrivateMethodInitSpec-qMjJ6sHQ.js";
 import { t as LifecycleCapability } from "./capability-DBAKc6UZ.js";
-import { _ as listBrowserTargets, f as connectBrowserSession, g as isMissingBrowserSession, l as acquireBrowserSession, n as DurableBrowserSessionStore, o as createLiveView, r as loadCdpSpec, u as closeBrowserSession } from "./session-store-yvwq1f9x.js";
+import { t as browserCapabilityId } from "./capability-id-B3J8Nok_.js";
+import { b as listBrowserTargets, f as acquireBrowserSession, h as connectBrowserSession, n as BrowserSession, o as DurableBrowserSessionStore, p as closeBrowserSession, s as loadCdpSpec, u as createLiveView, y as isMissingBrowserSession } from "./session-7CDgVE0z.js";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { Validator } from "@cfworker/json-schema";
+//#region src/browser/internal-hosts.ts
+/**
+* Internal hostnames: sites only this agent's browser can open.
+*
+* A host maps a hostname such as `preview.internal` to code in your agent
+* (`fetch`) or to a deployed Worker (`worker`). Browser Run sends the
+* browser's requests for that hostname to it instead of the internet, so a
+* page can be served from a sandbox port or a workspace folder, without exposing anything publicly.
+*
+* How a request travels: Browser Run accepts only entrypoints of your own
+* Worker as routes, and keeps them for the whole browser session (observed
+* across redeploys and Durable Object eviction; Browser Run doesn't document
+* this yet). So every `fetch` host routes to {@link InternalHostRouter}, which
+* you export from your main module. Its props say which agent and browser
+* own the host, and nothing else. It calls the agent's `fetchInternalHost()`
+* over RPC, and the agent's `Browser` runs the host's `fetch`. `Agent` has
+* that method built in; a plain Durable Object adds it (see
+* {@link InternalHostMessage}). A `worker` host goes straight to the Worker
+* you gave it.
+*/
+/** The most hostnames one browser can have. A Browser Run limit. */
+const MAX_INTERNAL_HOSTS = 8;
+const HOSTNAME = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+/**
+* Suffixes reserved so they never resolve on the internet. A real domain
+* would be served by the host over http but reach the real site over https
+* (and Chrome tries https first), so internal hostnames must use one.
+* Single labels like `preview` would work, but Browser Run doesn't route
+* labels that are real TLDs (`docs`, `app`) and gives no error for them, so
+* they're rejected rather than checked against a TLD list.
+*/
+const RESERVED_SUFFIXES = [
+	".internal",
+	".test",
+	".example",
+	".invalid"
+];
+/** Why `host` can't be an internal hostname, or undefined when it can. */
+function hostnameProblem(host) {
+	if (host.includes("://")) return "drop the scheme";
+	if (host.includes("/")) return "drop the path";
+	if (host.includes(":")) return "drop the port (only port 80 is routed)";
+	if (host !== host.toLowerCase()) return "use lowercase";
+	if (/^\d+(\.\d+){3}$/.test(host)) return "use a name, not an IP address";
+	if (host === "localhost" || host.endsWith(".localhost")) return "Chrome sends localhost to the browser's own machine";
+	if (!HOSTNAME.test(host)) return "not a valid hostname";
+	if (!RESERVED_SUFFIXES.some((suffix) => host.endsWith(suffix))) return `use a name that can't be a real site: end it in ${RESERVED_SUFFIXES.join(", ")}`;
+}
+/**
+* Check `internalHosts` when the provider is created, so a mistake fails at
+* startup instead of at the first browser launch.
+*/
+function validateInternalHosts(options) {
+	const hosts = Object.entries(options.hosts);
+	if (hosts.length === 0) throw new Error("internalHosts.hosts needs at least one hostname");
+	if (hosts.length > 8) throw new Error(`internalHosts has ${hosts.length} hostnames; Browser Run allows at most 8 per browser`);
+	for (const [host, config] of hosts) {
+		const problem = hostnameProblem(host);
+		if (problem) throw new Error(`Internal hostname "${host}": ${problem}`);
+		const hasFetch = typeof config.fetch === "function";
+		const hasWorker = config.worker !== void 0;
+		if (hasFetch === hasWorker) throw new Error(`Internal hostname "${host}" needs exactly one of fetch or worker`);
+		if (hasWorker && config.target !== void 0) throw new Error(`Internal hostname "${host}": target needs fetch; a worker host can't be assigned`);
+		if (hasFetch && typeof options.router !== "function") throw new Error(`Internal hostname "${host}" uses fetch, which needs internalHosts.router: this.ctx.exports.InternalHostRouter (and \`export { InternalHostRouter } from "agents/browser"\` in your main module)`);
+		if (config.target !== void 0) targetJsonSchema(host, config.target);
+	}
+}
+/**
+* Identifies the set of hostnames and how each is routed. A browser started
+* with a different set is replaced: Browser Run fixes routes at launch.
+*/
+function internalHostsSignature(options) {
+	if (!options) return void 0;
+	return Object.entries(options.hosts).map(([host, config]) => `${host}=${config.worker ? "worker" : "fetch"}`).sort().join(",");
+}
+/**
+* The route Browser Run gets for a `worker` host. A `ctx.exports`
+* entrypoint is a loopback stub that Browser Run can't take as is, so it's
+* called (with empty props) to get a Fetcher it can.
+*/
+function workerRoute(worker) {
+	if (typeof worker !== "function") return worker;
+	return worker({ props: {} });
+}
+function isStandardSchema(schema) {
+	return typeof schema === "object" && schema !== null && "~standard" in schema;
+}
+/** A host's target schema as JSON Schema, for the model and for plain validation. */
+function targetJsonSchema(host, schema) {
+	if (!isStandardSchema(schema)) {
+		if (typeof schema !== "object" || schema === null) throw new Error(`Internal hostname "${host}": target must be a schema`);
+		return schema;
+	}
+	const { jsonSchema } = schema["~standard"];
+	if (!jsonSchema?.input) throw new Error(`Internal hostname "${host}": target needs a schema that can describe itself as JSON Schema (Standard JSON Schema, such as zod 4.2+), or a plain JSON Schema object`);
+	try {
+		return jsonSchema.input({ target: "draft-07" });
+	} catch {
+		return jsonSchema.input({ target: "draft-2020-12" });
+	}
+}
+const plainValidators = /* @__PURE__ */ new WeakMap();
+function formatIssues(issues) {
+	return issues.map((issue) => issue.path ? `${issue.path}: ${issue.message}` : issue.message).join("; ");
+}
+function pathString(path) {
+	if (!path?.length) return void 0;
+	return path.map((part) => String(typeof part === "object" ? part.key : part)).join(".");
+}
+function plainIssues(errors) {
+	const specific = errors.filter((error) => error.keyword !== "properties");
+	return (specific.length > 0 ? specific : errors).map((error) => ({
+		message: error.error,
+		path: error.instanceLocation.replace(/^#\/?/, "").replaceAll("/", ".") || void 0
+	}));
+}
+/**
+* Validate a target against a host's schema. Returns the validated value
+* (a Standard Schema's output, which may differ from its input), or a
+* message saying what's wrong.
+*/
+async function validateTarget(schema, value) {
+	if (isStandardSchema(schema)) {
+		const result = await schema["~standard"].validate(value);
+		if (result.issues) return {
+			ok: false,
+			error: formatIssues(result.issues.map((issue) => ({
+				message: issue.message,
+				path: pathString(issue.path)
+			})))
+		};
+		return {
+			ok: true,
+			value: result.value
+		};
+	}
+	let validator = plainValidators.get(schema);
+	if (!validator) {
+		validator = new Validator(schema, "7", false);
+		plainValidators.set(schema, validator);
+	}
+	const result = validator.validate(value);
+	return result.valid ? {
+		ok: true,
+		value
+	} : {
+		ok: false,
+		error: formatIssues(plainIssues(result.errors))
+	};
+}
+function isInternalHostMessage(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const message = value;
+	return typeof message.browser === "string" && typeof message.host === "string" && message.request instanceof Request;
+}
+/** A plain-text response the browser shows for a failed internal request. */
+function internalHostError(status, message) {
+	return new Response(message, {
+		status,
+		headers: { "content-type": "text/plain; charset=utf-8" }
+	});
+}
+/**
+* Whether an RPC call failed because the agent has no `fetchInternalHost()`.
+* workerd says: `The RPC receiver does not implement the method
+* "fetchInternalHost".` If that wording changes, the router falls back to its
+* generic 502, which names the method too.
+*/
+function isMissingMethod(error) {
+	return error instanceof Error && error.message.includes("fetchInternalHost") && /does not implement|is not a function/.test(error.message);
+}
+/**
+* Carries a browser's requests for an internal hostname to the agent that
+* owns it. Export it from your Worker's main module, so
+* `this.ctx.exports.InternalHostRouter` exists:
+*
+* ```ts
+* export { InternalHostRouter } from "agents/browser";
+* ```
+*
+* It trusts its props: Browser Run sets them from your routes, but another
+* Worker in your account with a service binding to this entrypoint could
+* set its own and reach any agent's hosts. That Worker could already call
+* your agents directly, so this grants nothing new.
+*
+* It holds no logic of its own: it calls the agent's `fetchInternalHost()`
+* with an {@link InternalHostMessage}, and the agent's `Browser` runs the
+* host's `fetch`. `Agent` has `fetchInternalHost()` built in; a plain
+* Durable Object adds it (see {@link InternalHostMessage}).
+*
+* @experimental The API may change before it stabilizes.
+*/
+var InternalHostRouter = class extends WorkerEntrypoint {
+	async fetch(request) {
+		const props = this.ctx.props;
+		if (!isRouterProps(props)) return internalHostError(502, "InternalHostRouter was called without route props. Only Browser Run calls it, with the routes browserRun({ internalHosts }) gives it.");
+		const namespace = this.ctx.exports?.[props.className];
+		if (!namespace?.getByName) return internalHostError(502, `${props.host}: the agent class "${props.className}" isn't exported from this Worker`);
+		try {
+			const response = await namespace.getByName(props.name).fetchInternalHost({
+				browser: props.browser,
+				host: props.host,
+				request
+			});
+			if (response instanceof Response) return response;
+			return internalHostError(502, `${props.host}: the agent didn't answer with a Response`);
+		} catch (error) {
+			if (isMissingMethod(error)) return internalHostError(502, `${props.host}: ${props.className} has no fetchInternalHost() method. Agent has it built in; on a plain Durable Object add: fetchInternalHost(message) { return this.browser.fetchInternalHost(message); }`);
+			console.error(`[agents/browser] ${props.className} failed to serve ${props.host}`, error);
+			return internalHostError(502, `${props.host}: the agent failed to serve this request`);
+		}
+	}
+};
+function isRouterProps(props) {
+	return props?.v === 1 && typeof props.className === "string" && typeof props.name === "string" && typeof props.browser === "string" && typeof props.host === "string";
+}
+//#endregion
 //#region src/browser/providers/provider-adapter.ts
 /**
 * Thrown by {@link BrowserProviderAdapter.connect} when the session no longer
@@ -24,12 +244,34 @@ var BrowserSessionGoneError = class extends Error {
 * ```
 */
 function browserRun(binding, options = {}) {
+	const erased = options;
+	if (erased.internalHosts) validateInternalHosts(erased.internalHosts);
 	return {
 		kind: "browser-run",
 		binding,
-		options
+		options: erased
 	};
 }
+function isDataCloneError(error) {
+	return error instanceof Error && error.name === "DataCloneError";
+}
+/** One `outboundByHost` route per internal hostname. */
+function internalHostRoutes(internalHosts, owner) {
+	const routes = {};
+	const hosts = Object.entries(internalHosts.hosts);
+	for (const [host, config] of hosts) {
+		if (config.worker) {
+			routes[host] = workerRoute(config.worker);
+			continue;
+		}
+		routes[host] = internalHosts.router({ props: {
+			v: 1,
+			...owner,
+			host
+		} });
+	}
+	return routes;
+}
 /** The code behind {@link browserRun}. */
 function browserRunAdapter(provider) {
 	const { binding, options } = provider;
@@ -38,12 +280,22 @@ function browserRunAdapter(provider) {
 		get keepAliveMs() {
 			return keepAliveMs();
 		},
-		async create() {
-			return acquireBrowserSession(binding, {
-				keepAliveMs: keepAliveMs(),
-				recording: options.recording,
-				guardrails: options.guardrails
-			});
+		internalHosts: options.internalHosts,
+		internalHostsSignature: internalHostsSignature(options.internalHosts),
+		async create(context) {
+			const { internalHosts } = options;
+			if (internalHosts && !context?.owner) throw new Error("Internal hostnames need the Browser installed with Lifecycle.use() on a top-level agent");
+			try {
+				return await acquireBrowserSession(binding, {
+					keepAliveMs: keepAliveMs(),
+					recording: options.recording,
+					guardrails: options.guardrails,
+					...internalHosts && context?.owner ? { outboundByHost: internalHostRoutes(internalHosts, context.owner) } : {}
+				});
+			} catch (error) {
+				if (internalHosts && isDataCloneError(error)) throw new Error("Browser Run couldn't take the internal hostname routes: a worker host must be a service binding or an entrypoint of this Worker (this.ctx.exports.Name), not a Dynamic Worker or another object it can't hold", { cause: error });
+				throw error;
+			}
 		},
 		async isAlive(sessionId) {
 			try {
@@ -119,6 +371,15 @@ function retiredBrowserSessionKey(name) {
 function browserScopeKeyPrefix(name) {
 	return `browser:scope:${name.length}:${name}:`;
 }
+/**
+* Where a browser's internal-host targets live: one key per host, under a
+* prefix per browser (length-prefixed like scope records, so one browser's
+* prefix never matches another's). Kept apart from the session record, so
+* targets survive the browser being replaced.
+*/
+function internalHostTargetsPrefix(name) {
+	return `browser:hosts:${name.length}:${name}:`;
+}
 /** The adapter behind a provider: one explicit case per provider kind. */
 function providerAdapterFor(provider) {
 	switch (provider.kind) {
@@ -151,7 +412,7 @@ var _Browser_brand = /* @__PURE__ */ new WeakSet();
 var Browser = class extends LifecycleCapability {
 	constructor(options) {
 		const name = options.name ?? "default";
-		super(`browser:${name}`);
+		super(browserCapabilityId(name));
 		_classPrivateMethodInitSpec(this, _Browser_brand);
 		_classPrivateFieldInitSpec(this, _options, void 0);
 		_classPrivateFieldInitSpec(this, _key, void 0);
@@ -180,7 +441,8 @@ var Browser = class extends LifecycleCapability {
 					...resolvedFields(session)
 				};
 			}
-			const alive = await _classPrivateFieldGet2(_adapter, this).isAlive(existing.sessionId);
+			const routesMatch = existing.internalHosts === _classPrivateFieldGet2(_adapter, this).internalHostsSignature;
+			const alive = routesMatch && await _classPrivateFieldGet2(_adapter, this).isAlive(existing.sessionId);
 			const lock = await _get_sessionStore.call(_assertClassBrand(_Browser_brand, this)).acquireLock(key);
 			try {
 				const current = await _get_sessionStore.call(_assertClassBrand(_Browser_brand, this)).get(key);
@@ -201,6 +463,7 @@ var Browser = class extends LifecycleCapability {
 			} finally {
 				await lock.release();
 			}
+			if (!routesMatch) await _assertClassBrand(_Browser_brand, this, _closeQuietly).call(this, existing.sessionId);
 		}
 		throw new Error(`Browser "${name}" kept changing concurrently — retry`);
 	}
@@ -237,6 +500,15 @@ var Browser = class extends LifecycleCapability {
 		}
 	}
 	/**
+	* Start a session on this browser for one run: connects on its first
+	* call, resolves `sessionId: "active"` to the scope's tab, and reports
+	* what happened to the browser when you close it. `browserTool` opens
+	* one per run.
+	*/
+	session(options) {
+		return new BrowserSession(this, options);
+	}
+	/**
 	* Close the browser: retire the record (so the next resolve reports
 	* `restarted: true`) and close its provider session. Returns `false` when
 	* there was nothing to close.
@@ -283,6 +555,83 @@ var Browser = class extends LifecycleCapability {
 		}
 		return view;
 	}
+	/**
+	* The browser's internal hostnames, or `undefined` when its provider has
+	* none. See {@link BrowserInternalHosts}.
+	*/
+	get internalHosts() {
+		const config = _classPrivateFieldGet2(_adapter, this).internalHosts;
+		if (!config) return void 0;
+		const hosts = config.hosts;
+		const describe = () => Object.entries(hosts).map(([host, entry]) => ({
+			host,
+			url: `http://${host}/`,
+			...entry.description ? { description: entry.description } : {},
+			assignable: entry.target !== void 0,
+			...entry.target !== void 0 ? { targetSchema: targetJsonSchema(host, entry.target) } : {}
+		}));
+		const assignable = (host) => {
+			const entry = hosts[host];
+			if (!entry || !Object.hasOwn(hosts, host)) throw new Error(`"${host}" isn't an internal hostname. The hostnames are: ${Object.keys(hosts).join(", ")}`);
+			if (entry.target === void 0) throw new Error(`"${host}" always serves the same thing; it has no target to assign`);
+			return entry.target;
+		};
+		return {
+			describe,
+			list: async () => {
+				const prefix = internalHostTargetsPrefix(this.name);
+				const stored = await this.lifecycle.storage.list({ prefix });
+				return describe().map((info) => {
+					const key = prefix + info.host;
+					return stored.has(key) ? {
+						...info,
+						target: stored.get(key)
+					} : info;
+				});
+			},
+			assign: async (host, target) => {
+				const schema = assignable(host);
+				if (target === void 0) throw new Error(`browser.assignHost needs a target for ${host}; use browser.clearHost to unassign it`);
+				const json = JSON.parse(JSON.stringify(target));
+				const checked = await validateTarget(schema, json);
+				if (!checked.ok) throw new Error(`Invalid target for ${host}: ${checked.error}`);
+				await this.lifecycle.storage.put(_assertClassBrand(_Browser_brand, this, _targetKey).call(this, host), json);
+				return { url: `http://${host}/` };
+			},
+			clear: async (host) => {
+				assignable(host);
+				return this.lifecycle.storage.delete(_assertClassBrand(_Browser_brand, this, _targetKey).call(this, host));
+			}
+		};
+	}
+	/**
+	* Serve one browser request to an internal hostname. `InternalHostRouter`
+	* calls the agent's `fetchInternalHost()` with the message; `Agent` passes
+	* it here on its own. A plain Durable Object passes it on itself:
+	*
+	* ```ts
+	* fetchInternalHost(message: InternalHostMessage) {
+	*   return this.browser.fetchInternalHost(message);
+	* }
+	* ```
+	*
+	* Answers 502 with the reason when this browser doesn't serve the host.
+	*/
+	async fetchInternalHost(message) {
+		if (message.browser !== this.name) return internalHostError(502, `${message.host} belongs to browser "${message.browser}", but was passed to browser "${this.name}"`);
+		return _assertClassBrand(_Browser_brand, this, _serveInternalHost).call(this, message.host, message.request);
+	}
+	/**
+	* `Agent.fetchInternalHost()` routes here through Lifecycle, so `Agent`
+	* needn't import the browser.
+	*
+	* @internal Called by Lifecycle; not part of the host API.
+	*/
+	async onRoute(context) {
+		const { payload } = context;
+		if (!isInternalHostMessage(payload)) throw new Error(`Browser "${this.name}" got an unknown routed message`);
+		return this.fetchInternalHost(payload);
+	}
 };
 function _connection(resolved, scope, cdp, entered) {
 	const { sessionId } = resolved;
@@ -316,6 +665,54 @@ async function _open(resolved) {
 		}
 	});
 }
+async function _serveInternalHost(host, request) {
+	const hosts = _classPrivateFieldGet2(_adapter, this).internalHosts?.hosts;
+	const entry = hosts && Object.hasOwn(hosts, host) ? hosts[host] : void 0;
+	if (!entry?.fetch) return internalHostError(502, `${host} is no longer an internal hostname of browser "${this.name}"`);
+	let target;
+	if (entry.target !== void 0) {
+		const assigned = await this.lifecycle.storage.get(_assertClassBrand(_Browser_brand, this, _targetKey).call(this, host));
+		if (assigned === void 0) return internalHostError(502, `${host} isn't pointed anywhere yet. Call browser.assignHost({ host: "${host}", target }) first.`);
+		const checked = await validateTarget(entry.target, assigned);
+		if (!checked.ok) return internalHostError(502, `${host}'s target no longer matches its schema (${checked.error}). Call browser.assignHost again.`);
+		target = checked.value;
+	}
+	const fetch = entry.fetch;
+	try {
+		const response = await this.lifecycle.runInHostContext(() => fetch(request, target), { request });
+		if (response instanceof Response) return response;
+		return internalHostError(502, `${host}: its fetch didn't return a Response`);
+	} catch (error) {
+		console.error(`[agents/browser] ${host}: its fetch threw`, error);
+		return internalHostError(502, `${host}: its fetch failed`);
+	}
+}
+/**
+* Which agent and browser the session's routes lead back to. `undefined`
+* without internal hostnames.
+*/
+function _internalHostOwner() {
+	if (!_classPrivateFieldGet2(_adapter, this).internalHosts) return void 0;
+	const services = this.lifecycleServices;
+	if (!services) throw new Error(`Browser "${this.name}" has internal hostnames, which need it installed with Lifecycle.use()`);
+	if (services.routes.source !== void 0) throw new Error(`Browser "${this.name}" has internal hostnames, which sub-agents don't support yet`);
+	return {
+		className: services.className,
+		name: services.name,
+		browser: this.name
+	};
+}
+/** The storage key of one host's target. */
+function _targetKey(host) {
+	return internalHostTargetsPrefix(this.name) + host;
+}
+async function _closeQuietly(sessionId) {
+	try {
+		await _classPrivateFieldGet2(_adapter, this).close(sessionId);
+	} catch (error) {
+		console.warn(`[agents/browser] Failed to close browser session ${sessionId}`, error);
+	}
+}
 /**
 * Capped at half the provider's keep-alive window: a browser with
 * continuous CDP traffic must never look older than the window the
@@ -466,12 +863,14 @@ async function _retire(current) {
 * was created and closed while this create was in flight.
 */
 async function _createAndCommit() {
-	const info = await _classPrivateFieldGet2(_adapter, this).create();
+	const info = await _classPrivateFieldGet2(_adapter, this).create({ owner: _assertClassBrand(_Browser_brand, this, _internalHostOwner).call(this) });
 	const now = Date.now();
+	const signature = _classPrivateFieldGet2(_adapter, this).internalHostsSignature;
 	const stored = {
 		sessionId: info.sessionId,
 		createdAt: now,
-		updatedAt: now
+		updatedAt: now,
+		...signature !== void 0 ? { internalHosts: signature } : {}
 	};
 	let winner;
 	let restarted;
@@ -527,6 +926,6 @@ function activeTargets(scopes, scope, sessionId) {
 	return targets;
 }
 //#endregion
-export { browserRun as i, DEFAULT_BROWSER_SCOPE as n, MAX_BROWSER_SCOPES as r, Browser as t };
+export { InternalHostRouter as a, browserRun as i, DEFAULT_BROWSER_SCOPE as n, MAX_INTERNAL_HOSTS as o, MAX_BROWSER_SCOPES as r, Browser as t };
 
-//# sourceMappingURL=browser-DccPw_wW.js.map
+//# sourceMappingURL=browser-1eUbPvC2.js.map