pi-roundtable-browser 0.0.0-stage → 0.22.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.22.1] - 2026-10-21
+
+- Release in lockstep with pi-roundtable 0.22.1; no package-specific behavior changes. The core peer range stays `>=0.22.0 <0.23.0`.
+
+## [0.22.0] - 2026-10-21
+
+- First release, in lockstep with pi-roundtable 0.22: `browserAgent(options)` and its `browser_task` tool, the `BrowserDriver` port (`start(context)` returns the worker's tools, skills and a `dispose`), and the default `agentBrowserDriver(options)`: agent-browser and Chromium in a Docker container with no network, a host-side egress proxy that refuses every non-public destination, one `agent_browser` tool with a command policy, and the agent-browser guide of the image's own version loaded into the worker. Requires pi-roundtable `>=0.22.0 <0.23.0`, whose `WORKER_SESSIONS` service it uses.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-roundtable-browser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# pi-roundtable-browser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A browser worker for [pi-roundtable][roundtable] agents.
+Source lives in [`packages/browser`][source] in the pi-roundtable repository and releases in lockstep with the core.
+The plugin adds one tool, `browser_task({ task, url? })`.
+It starts a fresh worker session whose only tools drive a real browser, lets it work for a few minutes, and returns its written report; the screenshots the worker chose to keep are attached to the agent's reply.
+The browser runs in a Docker container that is started for the task and removed after it, with no network of its own and no route to the host's loopback, link-local or private addresses.
+
+[roundtable]: https://github.com/wayne930242/pi-roundtable
+[source]: https://github.com/wayne930242/pi-roundtable/tree/master/packages/browser
+
+## Requirements
+
+- Bun 1.4.2 or later and pi-roundtable `>=0.22.0 <0.23.0`, which provides the `WORKER_SESSIONS` service the plugin runs its worker on.
+- A native Linux host with a local Docker daemon, and a non-root service account permitted to run Docker. The container runs as that account; root is refused.
+- The Docker image, built once on that host (below).
+
+macOS supports the offline tests and building the image.
+Browsing needs Linux: the container reaches the host's proxy through a bind-mounted Unix socket, and Docker Desktop does not share host Unix sockets into its Linux VM.
+Remote Docker daemons are unsupported for the same reason: the socket must exist on the host that runs the container.
+
+## Setup
+
+```sh
+bun add pi-roundtable-browser
+```
+
+Build the image from the installed package (the host builds it; the package publishes no image):
+
+```sh
+docker build -t pi-roundtable-browser:<version> \
+  -f node_modules/pi-roundtable-browser/docker/Dockerfile \
+  node_modules/pi-roundtable-browser/docker
+```
+
+`<version>` is the installed package's version; the default driver looks for exactly that tag.
+`browserImageBuildCommand()` prints the command with your paths filled in, and the error you get when the image is missing quotes it.
+To use another tag, build under it and pass `docker: { image }`.
+The image installs Debian's Chromium (Chrome for Testing has no Linux ARM64 build), CJK and emoji fonts, `socat`, and `agent-browser` at the version in the Dockerfile's `AGENT_BROWSER_VERSION` build argument.
+Rebuild it after upgrading the package.
+
+Add the plugin to `roundtable.config.ts`:
+
+```ts
+import { browserAgent } from "pi-roundtable-browser";
+
+export default {
+  // ...the settings created by pi-roundtable init...
+  plugins: [
+    browserAgent({
+      model: "anthropic/claude-sonnet-5-5", // default: the host's delegation.model
+      thinking: "medium",                    // default: the host's delegation.thinking
+    }),
+  ],
+};
+```
+
+Setup stops with a `PluginError` that names the fix when Docker is missing, its daemon does not answer, the image is not built, or the host runs as root.
+
+The tool needs the owner tier.
+Lower it with the host's `toolTiers`, for example `toolTiers: { browser_task: "admin" }`; remember that whoever may call it can make the host fetch any public page.
+It is not a held action: nothing waits for the owner's approval.
+Every task starts from a clean browser profile, so there are no stored logins, and the worker is told it has no credentials.
+
+## Options
+
+| Option | Default | What it does |
+|---|---|---|
+| `driver` | the agent-browser driver | How a task gets a browser; see [Another driver](#another-driver) |
+| `docker` | | Options of the default driver: `image`, `binary`, `user: { uid, gid }`, `memoryMb` (1024), `cpus` (1.5), `pids` (512), `ports` (80 and 443), `commandTimeoutMs` (60,000), `onRefused(destination, reason)` |
+| `model`, `thinking` | the host's delegation settings | The worker's model (`provider/model-id`) and thinking level |
+| `limits.timeoutMs` | 5 minutes | The whole task. Past it the task ends with a message and the screenshots kept so far are still attached |
+| `limits.maxSteps` | 40 | Tool calls. The call after the last gets an error telling the worker to report |
+| `limits.maxScreenshots` | 4 | Screenshots the worker may keep for the reply |
+| `limits.maxScreenshotBytes` | 4 MiB | The largest screenshot, kept or only looked at (at most 10 MiB, the core's limit for one reply file) |
+| `limits.maxOutputChars` | 24,000 | The longest text one tool call hands the worker |
+| `maxConcurrentTasks` | 2 | Tasks at once; the next call is refused until one ends |
+
+A bad value stops startup with a `PluginError` naming the option.
+Cancelling the turn, or stopping the host, aborts the worker and removes the task's container before the call settles.
+
+## What the worker gets
+
+The default driver gives the worker one tool, `agent_browser`, and the guide of the agent-browser the image holds.
+`args` is the argument list after `agent-browser` (never a shell), `stdin` feeds `eval --stdin`, and `keep: true` on a `screenshot` attaches that image to the reply.
+The guide is what `agent-browser skills get core` prints in the container, so the worker's instructions always match the binary it drives; the package adds a short note on translating the guide's shell examples into argument lists.
+
+The command policy (`refuseAgentBrowserCommand`) keeps the worker to browsing.
+It runs only commands on its list and refuses, with a reason the worker reads: downloads, uploads, installs and upgrades, cookies, storage and saved state, the auth vault, plugins, `connect`, `batch`, recording and tracing, and any flag that changes how the browser launches or what it trusts (`--proxy`, `--args`, `--cdp`, `--profile`, `--state`, `--ignore-https-errors`, `--headers` and the like).
+`open` and `tab new` take only http and https addresses.
+This is not the security boundary, which is the container's network; it keeps a worker from wasting steps on things that cannot work.
+
+## How the container is isolated
+
+- `--network none`: the container has a loopback interface and nothing else. There is no route to the host's loopback or private networks, to link-local addresses such as cloud metadata, or to the internet.
+- The browser's only way out is a Unix socket, bind-mounted read-only from a private folder (mode 0700) at `/egress`, which `socat` relays to `127.0.0.1:3128` inside the container. Chromium uses it as its HTTP proxy for every request: pages, redirects, subresources, `fetch`, and WebSockets (`CONNECT`).
+- On the host, the proxy resolves each destination itself, refuses it unless every address in the answer is a public unicast address (loopback, private, link-local, carrier-grade NAT, multicast, documentation and benchmarking ranges, IPv4-mapped and transition IPv6 forms are not), and connects to one of the vetted addresses. The browser's own DNS answer is never used, so a name that later resolves elsewhere (DNS rebinding) reaches nothing, and every redirect is a new request that is vetted again. Numeric forms of IPv4 addresses (`2130706433`, `0x7f.1`) are refused outright, and only ports 80 and 443 are open unless `docker.ports` adds more. A plain HTTP request is sent on its own connection, and every connection has idle and size limits.
+- WebRTC is disabled for non-proxied UDP (`--force-webrtc-ip-handling-policy=disable_non_proxied_udp`), and with no interface there is no other path for it.
+- Chromium runs under a managed policy that refuses downloads, local files, `chrome://` pages, file dialogs, sign-in, password saving and autofill. The agent-browser upload and download commands are refused as well.
+- The container is read-only with a small tmpfs, runs as the host's non-root user with all capabilities dropped and `no-new-privileges`, and has memory, CPU and process limits. It is created with `--rm` and labelled; it exits by itself shortly after the task's time limit even if the host dies, and a restarted host removes containers a dead host left.
+- A task that fails to clean up (for example the Docker daemon is down) logs a warning that names the container; the cleanup runs again when the host stops or restarts.
+
+Nothing in the container is a secret: no credentials, no cookies, no mounted host files except the proxy socket.
+What the worker reads on the web is untrusted, and its standing instructions say so; keep the `model` you give it in mind when the pages it reads may try to steer it.
+A public page the worker opens is fetched from your host's IP address.
+
+## Another driver
+
+`BrowserDriver` is the extension point:
+
+```ts
+import { Type } from "typebox";
+import { browserAgent, browserTool, type BrowserDriver } from "pi-roundtable-browser";
+
+const driver: BrowserDriver = {
+  async check() { /* throw a PluginError naming the fix if it cannot work */ },
+  async start({ signal, limits, keepScreenshot }) {
+    const session = await openMyBrowser(signal);
+    return {
+      tools: [browserTool({ name: "browser_open", description: "...", parameters: Type.Object({ url: Type.String() }), execute: async ({ url }) => ({ text: await session.open(url) }) })],
+      skills: [{ name: "my browser", content: "How to use these tools..." }],
+      prompt: "Optional instructions added after the standing rules.",
+      dispose: () => session.close(),
+    };
+  },
+};
+
+browserAgent({ driver });
+```
+
+`start` builds one task's tools, skills and instructions; `dispose` is called once when the task ends, however it ended.
+The package counts every tool call against `limits.maxSteps`, cuts text at `limits.maxOutputChars`, scrubs unexpected errors before the worker reads them, aborts `signal` on cancellation, time-out and shutdown, and enforces the screenshot count and size when a tool calls `keepScreenshot(image)`.
+A driver is responsible for keeping its browser away from what the host should not expose; the package cannot check that for it.
+
+## Testing
+
+`bun test` runs offline: the tool flow with a fake driver and scripted worker sessions, the limits, cancellation and cleanup, the egress proxy with a stand-in network, the command policy, and the driver against a fake `docker` binary.
+The Docker integration test builds the image, browses a public page, and proves that requests to the host's loopback, a private address and the metadata address fail.
+It is opt-in and runs on native Linux as a non-root user:
+
+```sh
+(cd packages/browser && BROWSER_DOCKER_TEST=1 bun test src/docker.integration.test.ts)
+```
+
+CI runs it on its Ubuntu runner and requires it to pass.

package/docker/Dockerfile

@@ -0,0 +1,25 @@
+# The browser worker's image: agent-browser and the distribution's Chromium, nothing else of use.
+# The host runs it with no network at all; see packages/browser/README.md.
+FROM node:24-bookworm-slim
+
+ARG AGENT_BROWSER_VERSION=0.39.1
+
+# Chromium comes from the distribution because Chrome for Testing has no Linux ARM64 build, and its
+# managed policy directory is /etc/chromium/policies/managed. socat relays the container's loopback
+# proxy port to the host's egress proxy socket.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends \
+    chromium socat ca-certificates fonts-liberation fonts-noto-cjk fonts-noto-color-emoji \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN npm install --global --allow-scripts=agent-browser "agent-browser@${AGENT_BROWSER_VERSION}" \
+ && rm -rf /root/.npm
+
+# Chromium refuses downloads, local files, and the pages that expose the browser's own state.
+COPY policies.json /etc/chromium/policies/managed/pi-roundtable.json
+
+COPY entrypoint.sh /usr/local/bin/pi-roundtable-browser-entrypoint
+RUN chmod 0755 /usr/local/bin/pi-roundtable-browser-entrypoint
+
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
+ENTRYPOINT ["/usr/local/bin/pi-roundtable-browser-entrypoint"]

package/docker/entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Relays 127.0.0.1:3128 to the host's egress proxy on the mounted unix socket, then idles.
+# The host drives the browser with `docker exec agent-browser ...`.
+set -eu
+socat TCP-LISTEN:3128,bind=127.0.0.1,fork,reuseaddr UNIX-CONNECT:/egress/proxy.sock &
+# Exits by itself once the task could not still be running, even if the host that started it is gone.
+exec sleep "${BROWSER_LIFETIME_SECONDS:-1200}"

package/docker/policies.json

@@ -0,0 +1,20 @@
+{
+	"DownloadRestrictions": 3,
+	"AllowFileSelectionDialogs": false,
+	"URLBlocklist": [
+		"file://*",
+		"chrome://*",
+		"chrome-extension://*",
+		"view-source:*",
+		"devtools://*",
+		"ftp://*"
+	],
+	"WebRtcIPHandling": "disable_non_proxied_udp",
+	"PasswordManagerEnabled": false,
+	"AutofillAddressEnabled": false,
+	"AutofillCreditCardEnabled": false,
+	"BrowserSignin": 0,
+	"SyncDisabled": true,
+	"DefaultBrowserSettingEnabled": false,
+	"MetricsReportingEnabled": false
+}

package/examples/roundtable.config.ts

@@ -0,0 +1,11 @@
+import { browserAgent } from "../src/index.ts";
+
+// Merge with the rest of the configuration generated by pi-roundtable init.
+export const browserPlugins = [
+	browserAgent({
+		// Default: the host's delegation.model and delegation.thinking.
+		model: "anthropic/claude-sonnet-5-5",
+		thinking: "medium",
+		limits: { timeoutMs: 5 * 60_000, maxSteps: 40, maxScreenshots: 4 },
+	}),
+];

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "pi-roundtable-browser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-roundtable-browser",
+	"version": "0.22.1",
+	"description": "A browser worker for pi-roundtable agents: agent-browser in a Docker container with no route to the host's networks",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/browser"
+	},
+	"engines": {
+		"bun": ">=1.4.2"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/testing",
+		"docker",
+		"examples",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check ."
+	},
+	"dependencies": {
+		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
+		"typebox": "1.3.37"
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.22.0 <0.23.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@types/bun": "1.4.3",
+		"pi-roundtable": "0.22.1",
+		"typescript": "7.0.2"
+	}
+}

package/src/address.ts

@@ -0,0 +1,69 @@
+import { isIP } from "node:net";
+
+/**
+ * Whether an address is a globally routable unicast one. Everything else is refused: loopback,
+ * private, link-local (cloud metadata lives there), carrier-grade NAT, documentation, benchmarking,
+ * multicast, reserved, and the IPv6 transition ranges that can wrap an IPv4 one (Teredo, 6to4,
+ * IPv4-mapped). A scoped IPv6 address (`fe80::1%eth0`) and anything that is not an IP literal is refused.
+ */
+export function isPublicAddress(raw: string): boolean {
+	let address = raw.toLowerCase().replace(/^\[|\]$/g, "");
+	if (address.includes("%")) return false;
+	if (isIP(address) === 4) {
+		const [a = 0, b = 0, c = 0] = address.split(".").map(Number);
+		return !(
+			a === 0 ||
+			a === 10 ||
+			a === 127 ||
+			a >= 224 ||
+			(a === 100 && b >= 64 && b <= 127) ||
+			(a === 169 && b === 254) ||
+			(a === 172 && b >= 16 && b <= 31) ||
+			(a === 192 &&
+				(b === 168 ||
+					(b === 0 && (c === 0 || c === 2)) ||
+					(b === 88 && c === 99))) ||
+			(a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+			(a === 203 && b === 0 && c === 113)
+		);
+	}
+	if (isIP(address) !== 6) return false;
+	// URL canonicalization normalizes expanded IPv6 and dotted IPv4-mapped representations.
+	address = new URL(`http://[${address}]/`).hostname.slice(1, -1);
+	if (address.startsWith("::ffff:")) {
+		const parts = address.slice(7).split(":");
+		if (parts.length !== 2) return false;
+		const high = Number.parseInt(parts[0] ?? "", 16);
+		const low = Number.parseInt(parts[1] ?? "", 16);
+		return isPublicAddress(
+			`${high >>> 8}.${high & 255}.${low >>> 8}.${low & 255}`,
+		);
+	}
+	// Only ordinary global IPv6, excluding documentation, benchmarking, Teredo and 6to4.
+	// Hextets are read numerically after expansion, so compressed forms such as 2001::1 are caught too.
+	const [head = "", tail = ""] = address.split("::");
+	const left = head ? head.split(":") : [];
+	const right = tail ? tail.split(":") : [];
+	const hextets = address.includes("::")
+		? [
+				...left,
+				...Array<string>(Math.max(0, 8 - left.length - right.length)).fill("0"),
+				...right,
+			]
+		: left;
+	const first = Number.parseInt(hextets[0] ?? "", 16);
+	const second = Number.parseInt(hextets[1] ?? "", 16);
+	return (
+		first >= 0x2000 &&
+		first <= 0x3fff &&
+		first !== 0x2002 &&
+		!(
+			first === 0x2001 &&
+			(second === 0 ||
+				second === 2 ||
+				second === 0xdb8 ||
+				(second >= 0x10 && second <= 0x2f))
+		) &&
+		first !== 0x3fff
+	);
+}

package/src/agent-browser-commands.ts

@@ -0,0 +1,176 @@
+/**
+ * What the worker may run. The browser container has no network of its own, so this list is not
+ * the security boundary; it keeps the worker to browsing: no downloads, uploads, installs, saved
+ * logins, cookie or state import and export, plugins, or changes to the browser's launch or
+ * network settings. Anything not listed is refused, so a command a later agent-browser adds starts
+ * out refused.
+ */
+
+/** Commands the worker may run, with the subcommands allowed where only some are. */
+const COMMANDS: Readonly<Record<string, readonly string[] | true>> = {
+	open: true,
+	read: true,
+	click: true,
+	dblclick: true,
+	type: true,
+	fill: true,
+	press: true,
+	keyboard: true,
+	hover: true,
+	focus: true,
+	check: true,
+	uncheck: true,
+	select: true,
+	drag: true,
+	scroll: true,
+	scrollintoview: true,
+	wait: true,
+	snapshot: true,
+	eval: true,
+	back: true,
+	forward: true,
+	reload: true,
+	find: true,
+	is: true,
+	mouse: true,
+	frame: true,
+	highlight: true,
+	pushstate: true,
+	console: true,
+	errors: true,
+	get: [
+		"text",
+		"html",
+		"value",
+		"attr",
+		"title",
+		"url",
+		"count",
+		"box",
+		"styles",
+	],
+	tab: true,
+	dialog: ["status", "accept", "dismiss"],
+	diff: ["snapshot"],
+	network: ["requests"],
+	set: ["viewport", "device", "geo", "media"],
+	skills: ["get", "list"],
+	webmcp: ["list", "invoke", "result", "cancel"],
+	// Handled by the driver itself, which picks where the image goes.
+	screenshot: true,
+};
+
+/** Why a command is not offered, for the ones a worker is likely to try. */
+const REASONS: Readonly<Record<string, string>> = {
+	download: "downloads are disabled",
+	upload: "file uploads are disabled",
+	pdf: "saving files is disabled",
+	install: "the browser is already installed",
+	upgrade: "the browser is already installed",
+	cookies: "cookies cannot be imported or exported",
+	storage: "web storage cannot be imported or exported",
+	state: "saved state cannot be imported or exported",
+	auth: "the browser has no stored logins and the worker has no credentials",
+	plugin: "plugins are disabled",
+	profiles: "browser profiles are disabled",
+	connect: "the task's browser cannot be replaced",
+	close: "the browser is closed for you when the task ends",
+	batch: "run each command with its own call, so each is checked",
+	record: "recording is disabled",
+	trace: "tracing is disabled",
+	profiler: "profiling is disabled",
+	stream: "streaming is disabled",
+	mcp: "the MCP server is disabled",
+	chat: "chat is disabled",
+	dashboard: "the dashboard is disabled",
+	session: "the task's session is fixed",
+	doctor: "diagnostics are disabled",
+	clipboard: "the clipboard is disabled",
+	inspect: "the inspector is disabled",
+};
+
+/** Flags that change how the browser launches, what it trusts, where it connects or what it saves. */
+const REFUSED_FLAGS = new Set([
+	"--profile",
+	"--restore",
+	"--restore-save",
+	"--restore-check-url",
+	"--restore-check-text",
+	"--restore-check-fn",
+	"--session-name",
+	"--state",
+	"--auto-connect",
+	"--cdp",
+	"--headers",
+	"--session",
+	"--namespace",
+	"--executable-path",
+	"--extension",
+	"--init-script",
+	"--enable",
+	"--args",
+	"--user-agent",
+	"--proxy",
+	"--proxy-bypass",
+	"--ignore-https-errors",
+	"--ca-cert",
+	"--no-ca-cert",
+	"--allow-file-access",
+	"--provider",
+	"-p",
+	"--device",
+	"--headed",
+	"--webgpu",
+	"--download-path",
+	"--screenshot-dir",
+	"--allowed-domains",
+	"--action-policy",
+	"--confirm-actions",
+	"--confirm-interactive",
+	"--engine",
+	"--config",
+	"--idle-timeout",
+	"--model",
+	"--pin-tab",
+	"--no-pin-tab",
+]);
+
+/** `--flag=value` and `--flag` name the same flag. */
+const flagName = (arg: string) => arg.split("=", 1)[0] ?? arg;
+
+/** Addresses of other kinds than http(s): `file:`, `javascript:`, `chrome://`, `data:` and the like. */
+const OTHER_SCHEME =
+	/^(?:[a-z][a-z0-9+.-]*:\/\/|(?:file|javascript|data|blob|about|chrome|view-source|devtools|ftp):)/i;
+
+/**
+ * The reason a command is refused, written for the worker, or undefined when it may run.
+ * `args` is the argument list after `agent-browser`.
+ */
+export function refuseAgentBrowserCommand(
+	args: readonly string[],
+): string | undefined {
+	const [command, sub] = args;
+	if (!command) return "Give a command, such as open, snapshot or click.";
+	if (command.startsWith("-")) return "Put the command first, then its flags.";
+	for (const arg of args.slice(1)) {
+		const flag = flagName(arg);
+		if (REFUSED_FLAGS.has(flag))
+			return `${flag} is refused: it changes how the task's browser launches, connects or saves state.`;
+	}
+	const allowed = COMMANDS[command];
+	if (allowed === undefined)
+		return REASONS[command]
+			? `${command} is refused: ${REASONS[command]}.`
+			: `${command} is not one of the commands this browser worker offers.`;
+	if (allowed !== true && (!sub || !allowed.includes(sub)))
+		return `${command} may only be followed by ${allowed.join(", ")}.`;
+	if (command === "open" || (command === "tab" && sub === "new"))
+		for (const arg of args.slice(command === "open" ? 1 : 2))
+			if (
+				!arg.startsWith("-") &&
+				OTHER_SCHEME.test(arg) &&
+				!/^https?:\/\//i.test(arg)
+			)
+				return "Only http and https pages open; other addresses (file:, javascript:, chrome: and the like) are refused.";
+	return undefined;
+}