pi-roundtable-browser 0.0.0-stage → 0.22.1

package/src/agent-browser-driver.ts

@@ -0,0 +1,448 @@
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { PluginError } from "pi-roundtable";
+import { Type } from "typebox";
+import { refuseAgentBrowserCommand } from "./agent-browser-commands.ts";
+import { docker, firstLine, requireDocker } from "./docker.ts";
+import {
+	type BrowserDriver,
+	type BrowserSkill,
+	type BrowserTaskContext,
+	type BrowserTaskKit,
+	BrowserToolError,
+	browserTool,
+} from "./driver.ts";
+import { EgressProxy } from "./egress-proxy.ts";
+
+const PACKAGE_DIR = resolve(dirname(new URL(import.meta.url).pathname), "..");
+const VERSION = (
+	JSON.parse(readFileSync(join(PACKAGE_DIR, "package.json"), "utf8")) as {
+		version: string;
+	}
+).version;
+
+/** The Dockerfile's folder, for the host's build command. */
+export const BROWSER_IMAGE_CONTEXT = join(PACKAGE_DIR, "docker");
+/** The image the default driver runs unless told otherwise; the version is this package's. */
+export const DEFAULT_BROWSER_IMAGE = `pi-roundtable-browser:${VERSION}`;
+
+/** The command that builds the image the default driver needs. */
+export function browserImageBuildCommand(
+	image = DEFAULT_BROWSER_IMAGE,
+): string {
+	return `docker build -t ${image} -f ${join(BROWSER_IMAGE_CONTEXT, "Dockerfile")} ${BROWSER_IMAGE_CONTEXT}`;
+}
+
+export interface AgentBrowserDriverOptions {
+	/** The image to run; default `DEFAULT_BROWSER_IMAGE`, built with `browserImageBuildCommand()`. */
+	image?: string;
+	/** The Docker CLI; default `docker`. */
+	binary?: string;
+	/** The user and group the container runs as; default the host process's. Never root. */
+	user?: { uid: number; gid: number };
+	/** Container memory in MiB; default 1024. */
+	memoryMb?: number;
+	/** Container CPUs; default 1.5. */
+	cpus?: number;
+	/** Processes the container may run; default 512. */
+	pids?: number;
+	/** Destination ports the browser may reach; default 80 and 443. */
+	ports?: readonly number[];
+	/** Time one agent-browser command may take, in milliseconds; default 60,000. */
+	commandTimeoutMs?: number;
+	/** Told about each request the egress proxy refused: the destination and why. */
+	onRefused?: (destination: string, reason: string) => void;
+}
+
+const LABEL = "pi-roundtable.browser";
+const PROXY_PORT = 3128;
+const SCREENSHOT_DIR = "/tmp/shots";
+
+export interface BrowserContainerSpec {
+	name: string;
+	image: string;
+	/** The host folder holding the egress proxy's socket, mounted read-only at /egress. */
+	egressDir: string;
+	uid: number;
+	gid: number;
+	memoryMb: number;
+	cpus: number;
+	pids: number;
+	/** Seconds the container may live; it exits by itself after that, even if the host is gone. */
+	lifetimeSeconds: number;
+	maxOutputChars: number;
+	hostPid: number;
+}
+
+/**
+ * `docker run` arguments of one task's browser. The container has no network interface but
+ * loopback; the only way out is the proxy socket mounted at /egress, relayed to 127.0.0.1:3128.
+ * It runs unprivileged on a read-only root with a small tmpfs, and the browser's policy (in the
+ * image) refuses downloads and local files.
+ */
+export function browserContainerArgs(spec: BrowserContainerSpec): string[] {
+	if (
+		!/^[a-z0-9][a-z0-9_.-]{0,90}$/.test(spec.name) ||
+		!spec.image ||
+		spec.image.startsWith("-") ||
+		/\s/.test(spec.image)
+	)
+		throw new PluginError("browser container name or image is not valid.");
+	if (
+		!Number.isInteger(spec.uid) ||
+		spec.uid <= 0 ||
+		!Number.isInteger(spec.gid) ||
+		spec.gid <= 0
+	)
+		throw new PluginError(
+			"the browser container must run as a non-root user and group: run the host as one, or pass docker: { user: { uid, gid } }.",
+		);
+	if (!isAbsolute(spec.egressDir) || /[,\n\r]/.test(spec.egressDir))
+		throw new PluginError("the egress folder must be an absolute path.");
+	const proxy = `http://127.0.0.1:${PROXY_PORT}`;
+	const env: Record<string, string> = {
+		HOME: "/tmp/home",
+		HTTP_PROXY: proxy,
+		HTTPS_PROXY: proxy,
+		http_proxy: proxy,
+		https_proxy: proxy,
+		AGENT_BROWSER_PROXY: proxy,
+		AGENT_BROWSER_SESSION: "task",
+		AGENT_BROWSER_EXECUTABLE_PATH: "/usr/bin/chromium",
+		AGENT_BROWSER_ARGS: [
+			"--no-sandbox",
+			"--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+		].join("\n"),
+		AGENT_BROWSER_CONTENT_BOUNDARIES: "1",
+		AGENT_BROWSER_MAX_OUTPUT: String(spec.maxOutputChars),
+		BROWSER_LIFETIME_SECONDS: String(spec.lifetimeSeconds),
+	};
+	return [
+		"run",
+		"--detach",
+		"--rm",
+		"--init",
+		"--pull",
+		"never",
+		"--name",
+		spec.name,
+		"--label",
+		`${LABEL}=1`,
+		"--label",
+		`${LABEL}.pid=${spec.hostPid}`,
+		"--network",
+		"none",
+		"--read-only",
+		"--cap-drop",
+		"ALL",
+		"--security-opt",
+		"no-new-privileges:true",
+		"--user",
+		`${spec.uid}:${spec.gid}`,
+		"--memory",
+		`${spec.memoryMb}m`,
+		"--memory-swap",
+		`${spec.memoryMb}m`,
+		"--cpus",
+		String(spec.cpus),
+		"--pids-limit",
+		String(spec.pids),
+		"--ulimit",
+		"nofile=1024:1024",
+		"--shm-size",
+		"256m",
+		"--tmpfs",
+		"/tmp:rw,nosuid,nodev,size=512m,mode=1777",
+		"--mount",
+		`type=bind,src=${spec.egressDir},dst=/egress,readonly,bind-propagation=rprivate`,
+		...Object.entries(env).flatMap(([key, value]) => [
+			"--env",
+			`${key}=${value}`,
+		]),
+		spec.image,
+	];
+}
+
+function ownerOf(options: AgentBrowserDriverOptions): {
+	uid: number;
+	gid: number;
+} {
+	return (
+		options.user ?? {
+			uid: process.getuid?.() ?? 0,
+			gid: process.getgid?.() ?? 0,
+		}
+	);
+}
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Removes containers a host that is gone left behind. */
+async function sweepStale(binary: string): Promise<void> {
+	try {
+		const listed = await docker(
+			binary,
+			[
+				"ps",
+				"--all",
+				"--filter",
+				`label=${LABEL}`,
+				"--format",
+				`{{.Names}} {{.Label "${LABEL}.pid"}}`,
+			],
+			{ timeoutMs: 15_000 },
+		);
+		if (listed.code !== 0) return;
+		for (const line of new TextDecoder().decode(listed.stdout).split("\n")) {
+			const [name, pid] = line.trim().split(" ");
+			if (name && Number(pid) > 0 && !isAlive(Number(pid)))
+				await docker(binary, ["rm", "--force", name], { timeoutMs: 15_000 });
+		}
+	} catch {
+		// Best effort: a container left behind exits by itself when its lifetime ends.
+	}
+}
+
+const SKILL_FRONT_MATTER = /^---\n[\s\S]*?\n---\n/;
+
+const INSTRUCTIONS = [
+	'You drive the task\'s browser with one tool, `agent_browser`, which runs one agent-browser command per call. `args` is the list of arguments after `agent-browser`, for example ["open", "https://example.com"], ["snapshot", "-i"], ["click", "@e3"] or ["fill", "@e2", "some text"]. It is not a shell: write no quotes around arguments, and use no pipes, redirects, environment variables or `export`. For `eval --stdin`, put the script in `stdin`. The browser session is already set up and closes itself when the task ends.',
+	"The guide below is agent-browser's own; its examples are shell commands, so turn each into an `args` list, and skip what this tool refuses: downloads, uploads, installs, cookies and saved state, the auth vault, plugins, and changes to the browser's network, proxy or launch settings. Its references are served by `skills get core --full`.",
+	"To look at a page, call `snapshot` (add `-i` for interactive elements only) or `screenshot`. A screenshot is shown to you; set `keep: true` on the `screenshot` call to also attach it to the reply of the agent that handed you this task, which is how the agent shows what the page looked like. Keep only what the task needs.",
+].join("\n\n");
+
+const AGENT_BROWSER_TOOL = {
+	name: "agent_browser",
+	description:
+		'Run one agent-browser command in this task\'s browser and get its output. `args` are the arguments after `agent-browser`, as a list (not a shell line), such as ["open", "https://example.com"] or ["snapshot", "-i"]. `screenshot` takes no path; set `keep` to attach the image to the reply. Downloads, uploads, installs, cookie or state import and export, logins, plugins and network or proxy settings are refused.',
+	parameters: Type.Object({
+		args: Type.Array(Type.String({ maxLength: 4_000 }), {
+			minItems: 1,
+			maxItems: 64,
+			description:
+				"The arguments after `agent-browser`, one list item per argument.",
+		}),
+		stdin: Type.Optional(
+			Type.String({
+				maxLength: 65_536,
+				description:
+					"Text for the command's standard input, such as the script of `eval --stdin`.",
+			}),
+		),
+		keep: Type.Optional(
+			Type.Boolean({
+				description:
+					"With `screenshot`: also attach the image to the reply. Ignored by other commands.",
+			}),
+		),
+	}),
+} as const;
+
+/**
+ * The default driver: agent-browser and Chromium in a Docker container started for each task and
+ * removed after it, with no network but a unix socket to a proxy on the host that refuses every
+ * destination that is not a public address. See the package README for the isolation it gives.
+ */
+export function agentBrowserDriver(
+	options: AgentBrowserDriverOptions = {},
+): BrowserDriver {
+	const binary = options.binary ?? "docker";
+	const image = options.image ?? DEFAULT_BROWSER_IMAGE;
+	const commandTimeoutMs = options.commandTimeoutMs ?? 60_000;
+	return {
+		async check() {
+			await requireDocker(binary);
+			const { uid } = ownerOf(options);
+			if (uid <= 0)
+				throw new PluginError(
+					"the browser container must run as a non-root user: run the host as one, or pass docker: { user: { uid, gid } }.",
+				);
+			const found = await docker(
+				binary,
+				["image", "inspect", image, "--format", "{{.Id}}"],
+				{
+					timeoutMs: 15_000,
+				},
+			);
+			if (found.code !== 0)
+				throw new PluginError(
+					`the browser image ${image} is not built on this machine. Build it once with: ${browserImageBuildCommand(image)}`,
+				);
+			await sweepStale(binary);
+		},
+
+		async start(context: BrowserTaskContext): Promise<BrowserTaskKit> {
+			const { signal, limits } = context;
+			const name = `pi-roundtable-browser-${randomBytes(6).toString("hex")}`;
+			const dir = mkdtempSync(join(tmpdir(), "prb-"));
+			let proxy: EgressProxy | undefined;
+			const remove = async () => {
+				const failures: string[] = [];
+				const removed = await docker(binary, ["rm", "--force", name], {
+					timeoutMs: 20_000,
+				}).catch((error: unknown) => ({
+					code: 1,
+					stderr: String(error),
+				}));
+				if (removed.code !== 0 && !/No such container/i.test(removed.stderr))
+					failures.push(
+						`the container ${name} was not removed (${firstLine(removed.stderr)}); remove it with \`${binary} rm --force ${name}\``,
+					);
+				await proxy?.close().catch(() => undefined);
+				rmSync(dir, { recursive: true, force: true });
+				if (failures.length > 0) throw new Error(failures.join("; "));
+			};
+			try {
+				proxy = await EgressProxy.listen({
+					socketPath: join(dir, "proxy.sock"),
+					...(options.ports ? { ports: options.ports } : {}),
+					...(options.onRefused ? { onRefused: options.onRefused } : {}),
+				});
+				const { uid, gid } = ownerOf(options);
+				const started = await docker(
+					binary,
+					browserContainerArgs({
+						name,
+						image,
+						egressDir: dir,
+						uid,
+						gid,
+						memoryMb: options.memoryMb ?? 1024,
+						cpus: options.cpus ?? 1.5,
+						pids: options.pids ?? 512,
+						lifetimeSeconds: Math.ceil(limits.timeoutMs / 1000) + 120,
+						maxOutputChars: limits.maxOutputChars,
+						hostPid: process.pid,
+					}),
+					{ signal, timeoutMs: 60_000 },
+				);
+				if (started.code !== 0)
+					throw new Error(
+						`the browser container did not start (${firstLine(started.stderr)}). If the image is missing, build it with: ${browserImageBuildCommand(image)}`,
+					);
+				await exec(["mkdir", "-p", SCREENSHOT_DIR]);
+				const guide = await exec(["agent-browser", "skills", "get", "core"], {
+					maxBytes: 512 * 1024,
+				});
+				if (guide.code !== 0)
+					throw new Error(
+						`the browser image does not serve agent-browser's guide (${firstLine(guide.stderr)}); rebuild it with: ${browserImageBuildCommand(image)}`,
+					);
+				const skill: BrowserSkill = {
+					name: "agent-browser core guide",
+					content: new TextDecoder()
+						.decode(guide.stdout)
+						.replace(SKILL_FRONT_MATTER, ""),
+				};
+				return makeKit(skill);
+			} catch (error) {
+				await remove().catch(() => undefined);
+				throw error;
+			}
+
+			function exec(
+				args: readonly string[],
+				extra: { stdin?: string; maxBytes?: number } = {},
+			) {
+				return docker(
+					binary,
+					[
+						"exec",
+						...(extra.stdin === undefined ? [] : ["--interactive"]),
+						"--workdir",
+						"/tmp",
+						name,
+						...args,
+					],
+					{
+						signal,
+						timeoutMs: commandTimeoutMs,
+						maxBytes: extra.maxBytes ?? limits.maxOutputChars * 4,
+						...(extra.stdin === undefined ? {} : { stdin: extra.stdin }),
+					},
+				);
+			}
+
+			function makeKit(skill: BrowserSkill): BrowserTaskKit {
+				// One command at a time: the worker may emit several calls in one message.
+				let queue: Promise<unknown> = Promise.resolve();
+				let shots = 0;
+				const serial = <T>(work: () => Promise<T>): Promise<T> => {
+					const next = queue.then(work, work);
+					queue = next.catch(() => undefined);
+					return next;
+				};
+				/** Runs one agent-browser command; a failure is an error the worker reads. */
+				const agentBrowser = async (
+					args: readonly string[],
+					stdin?: string,
+				): Promise<string> => {
+					const result = await exec(
+						["agent-browser", ...args],
+						stdin === undefined ? {} : { stdin },
+					);
+					const text = new TextDecoder().decode(result.stdout).trim();
+					if (result.code !== 0)
+						throw new BrowserToolError(
+							`agent-browser exited with ${result.code}: ${(result.stderr.trim() || text).slice(0, 4_000)}`,
+						);
+					return text;
+				};
+				/** Takes a screenshot into the container, reads it back, and optionally keeps it for the reply. */
+				const screenshot = async (flags: readonly string[], keep: boolean) => {
+					if (flags.some((flag) => flag !== "--full" && flag !== "--annotate"))
+						throw new BrowserToolError(
+							"screenshot takes no path and only the flags --full and --annotate; the image is shown to you, and keep: true attaches it to the reply.",
+						);
+					const path = `${SCREENSHOT_DIR}/${++shots}.png`;
+					await agentBrowser(["screenshot", ...flags, path]);
+					const image = await exec(["cat", path], {
+						maxBytes: limits.maxScreenshotBytes + 1,
+					});
+					void exec(["rm", "-f", path]).catch(() => undefined);
+					if (image.code !== 0 || image.truncated)
+						throw new BrowserToolError(
+							image.truncated
+								? `The screenshot is over ${limits.maxScreenshotBytes} bytes. Take it without --full, or scroll to what you need first.`
+								: "The screenshot could not be read back.",
+						);
+					const picture = { mimeType: "image/png", data: image.stdout };
+					if (!keep) return { text: "Screenshot taken.", images: [picture] };
+					const kept = context.keepScreenshot(picture);
+					return {
+						text: `Screenshot taken and kept for the reply (${kept} of at most ${limits.maxScreenshots}).`,
+						images: [picture],
+					};
+				};
+				return {
+					prompt: INSTRUCTIONS,
+					skills: [skill],
+					tools: [
+						browserTool({
+							...AGENT_BROWSER_TOOL,
+							execute: ({ args, stdin, keep }) =>
+								serial(async () => {
+									const refusal = refuseAgentBrowserCommand(args);
+									if (refusal) throw new BrowserToolError(refusal);
+									if (args[0] === "screenshot")
+										return screenshot(args.slice(1), keep === true);
+									const result = await agentBrowser(args, stdin);
+									return { text: result || "(no output)" };
+								}),
+						}),
+					],
+					dispose: remove,
+				};
+			}
+		},
+	};
+}

package/src/docker.ts

@@ -0,0 +1,131 @@
+import { PluginError } from "pi-roundtable";
+
+export interface ExecResult {
+	code: number;
+	stdout: Uint8Array;
+	stderr: string;
+	/** Output was cut at `maxBytes`. */
+	truncated: boolean;
+}
+
+async function readBounded(
+	stream: ReadableStream<Uint8Array>,
+	maxBytes: number,
+	onFull: () => void,
+): Promise<{ data: Uint8Array; truncated: boolean }> {
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	let truncated = false;
+	for await (const chunk of stream) {
+		if (truncated) continue;
+		const room = maxBytes - size;
+		if (chunk.byteLength > room) {
+			chunks.push(chunk.subarray(0, room));
+			size = maxBytes;
+			truncated = true;
+			onFull();
+		} else {
+			chunks.push(chunk);
+			size += chunk.byteLength;
+		}
+	}
+	return { data: Buffer.concat(chunks), truncated };
+}
+
+/**
+ * Runs `docker <args>` and returns its bounded output. Aborting, or running past `timeoutMs`,
+ * kills the Docker client at once (SIGKILL: SIGTERM can be proxied into a container's PID 1 and
+ * ignored) and rejects with the signal's reason, or a timeout error, without waiting for output
+ * that something else still holds open.
+ */
+export async function docker(
+	binary: string,
+	args: readonly string[],
+	options: {
+		signal?: AbortSignal;
+		stdin?: string;
+		maxBytes?: number;
+		timeoutMs?: number;
+	} = {},
+): Promise<ExecResult> {
+	options.signal?.throwIfAborted();
+	const child = Bun.spawn([binary, ...args], {
+		stdin: options.stdin === undefined ? "ignore" : "pipe",
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const kill = () => child.kill("SIGKILL");
+	const stop = new AbortController();
+	stop.signal.addEventListener("abort", kill, { once: true });
+	const forward = () => stop.abort(options.signal?.reason);
+	options.signal?.addEventListener("abort", forward, { once: true });
+	const timer = options.timeoutMs
+		? setTimeout(
+				() =>
+					stop.abort(
+						new Error(
+							`\`${binary} ${args[0] ?? ""}\` did not finish within ${options.timeoutMs} ms`,
+						),
+					),
+				options.timeoutMs,
+			)
+		: undefined;
+	const gone = new Promise<never>((_resolve, reject) =>
+		stop.signal.addEventListener("abort", () => reject(stop.signal.reason), {
+			once: true,
+		}),
+	);
+	try {
+		if (options.stdin !== undefined && child.stdin) {
+			child.stdin.write(options.stdin);
+			await child.stdin.end();
+		}
+		const maxBytes = options.maxBytes ?? 1024 * 1024;
+		const work = Promise.all([
+			readBounded(child.stdout, maxBytes, kill),
+			readBounded(child.stderr, 64 * 1024, () => undefined),
+			child.exited,
+		]);
+		work.catch(() => undefined);
+		const [out, err, code] = await Promise.race([work, gone]);
+		return {
+			code,
+			stdout: out.data,
+			stderr: new TextDecoder().decode(err.data),
+			truncated: out.truncated,
+		};
+	} finally {
+		clearTimeout(timer);
+		options.signal?.removeEventListener("abort", forward);
+		kill();
+		await child.exited;
+	}
+}
+
+/** The first line of Docker's complaint, short enough for a message. */
+export function firstLine(text: string): string {
+	return (text.trim().split("\n")[0] ?? "").slice(0, 300);
+}
+
+/** Throws a PluginError naming the fix unless a Docker daemon answers. */
+export async function requireDocker(binary: string): Promise<void> {
+	let result: ExecResult | undefined;
+	let failure = "";
+	try {
+		result = await docker(
+			binary,
+			["version", "--format", "{{.Server.Version}}"],
+			{ timeoutMs: 15_000 },
+		);
+	} catch (error) {
+		failure = error instanceof Error ? error.message : String(error);
+	}
+	if (result?.code !== 0)
+		throw new PluginError(
+			`the browser worker needs Docker, and ${
+				result
+					? `the daemon did not answer (${firstLine(result.stderr)})`
+					: `\`${binary}\` could not run (${firstLine(failure)})`
+			}. Install Docker and start its daemon (\`${binary} info\` must work), or pass docker: { binary } with the path of its CLI.`,
+		);
+}

package/src/driver.ts

@@ -0,0 +1,109 @@
+import type { Static, TSchema } from "typebox";
+
+/** What a task may use, each with a safe default. */
+export interface BrowserLimits {
+	/** The whole task, from the first tool call to the report, in milliseconds; default 5 minutes. */
+	timeoutMs: number;
+	/** Tool calls the worker may make; the next one is refused. Default 40. */
+	maxSteps: number;
+	/** Screenshots the worker may keep for the agent's reply; default 4. */
+	maxScreenshots: number;
+	/** The largest screenshot, kept or only looked at, in bytes; default 4 MiB. */
+	maxScreenshotBytes: number;
+	/** The longest text one tool call may hand the worker, in characters; default 24,000. */
+	maxOutputChars: number;
+}
+
+export const DEFAULT_BROWSER_LIMITS: Readonly<BrowserLimits> = Object.freeze({
+	timeoutMs: 5 * 60_000,
+	maxSteps: 40,
+	maxScreenshots: 4,
+	maxScreenshotBytes: 4 * 1024 * 1024,
+	maxOutputChars: 24_000,
+});
+
+/** A screenshot, or any image, as bytes. */
+export interface BrowserImage {
+	/** `image/png`, `image/jpeg`, `image/gif` or `image/webp`. */
+	mimeType: string;
+	data: Uint8Array;
+}
+
+/** What one tool call returns to the worker: text, and images it can look at. */
+export interface BrowserToolResult {
+	text: string;
+	images?: readonly BrowserImage[];
+}
+
+/**
+ * A call the worker should correct, such as a command the driver refuses: its message becomes the
+ * tool's error result. Any other error also fails the call, with its text scrubbed of secrets.
+ */
+export class BrowserToolError extends Error {
+	override name = "BrowserToolError";
+}
+
+/** One tool of the worker. The worker's model reads `description` and fills `parameters`. */
+export interface BrowserTool<Schema extends TSchema = TSchema> {
+	/** Lowercase words joined by underscores; unique within the task. */
+	name: string;
+	description: string;
+	/** The arguments as a Typebox schema; the call is checked against it before `execute` runs. */
+	parameters: Schema;
+	/** Aborted when the task is cancelled, times out, or the host stops. */
+	execute(
+		input: Static<Schema>,
+		signal: AbortSignal,
+	): Promise<BrowserToolResult>;
+}
+
+/** Types a tool's `input` from its schema, and fits it in the list of a kit's tools. */
+export function browserTool<Schema extends TSchema>(
+	tool: BrowserTool<Schema>,
+): BrowserTool {
+	// SAFETY: the host checks every call against `parameters` before `execute`, so the input has the schema's type.
+	return tool as unknown as BrowserTool;
+}
+
+/** Instructions the worker reads as part of its system prompt, such as a tool's usage guide. */
+export interface BrowserSkill {
+	name: string;
+	/** The full text, without front matter. */
+	content: string;
+}
+
+/** What a driver is told about a task. */
+export interface BrowserTaskContext {
+	/** Aborted when the turn is cancelled, the time limit passes, or the host stops. */
+	signal: AbortSignal;
+	limits: Readonly<BrowserLimits>;
+	/**
+	 * Keeps an image for the agent's reply, once the task ends. Throws a `BrowserToolError` when the
+	 * screenshot count or size limit refuses it; the message tells the worker why. Returns how many
+	 * images are kept so far.
+	 */
+	keepScreenshot(image: BrowserImage): number;
+}
+
+/** The worker's tools and instructions for one task, and the means to clean up after it. */
+export interface BrowserTaskKit {
+	tools: readonly BrowserTool[];
+	skills?: readonly BrowserSkill[];
+	/** Added to the worker's system prompt after the standing rules, for example how to keep a screenshot. */
+	prompt?: string;
+	/** Closes the task's browser and removes everything it made. Called once, whether the task succeeded, failed or was cancelled. */
+	dispose(): Promise<void>;
+}
+
+/**
+ * The extension point: how a task gets a browser. A driver builds, for one task, the tools and
+ * skills the worker may use, and cleans up after it. The package's default drives agent-browser in
+ * a Docker container; another driver can drive any browser, as long as it keeps the task's
+ * browser from reaching what the host should not expose.
+ */
+export interface BrowserDriver {
+	/** Runs at startup; throws a `PluginError` naming the fix when the driver cannot work. */
+	check?(): Promise<void>;
+	/** Prepares one task's browser. A rejection leaves nothing behind that `dispose` would remove. */
+	start(context: BrowserTaskContext): Promise<BrowserTaskKit>;
+}