agents 0.30.0 → 0.31.0

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