@boardwalk-labs/runner 0.1.12 → 0.1.14

package/README.md

@@ -38,6 +38,24 @@ finishes, nothing new is claimed. Useful flags: `--once` (execute one run, then
 and `HTTPS_PROXY` set; the daemon and the run processes both honor it. Runs inherit this
 machine's network — a model or service reachable from the box is reachable from the run.
 
+### Browser tier (computer use)
+
+`computer.openBrowser()` and `agent({ session })` drive an in-VM browser. On the hosted
+runners the environment ships it; on a self-hosted machine you provide the pieces and point the
+runner at them with a small env contract — the same contract the hosted image sets, so the code
+path is identical:
+
+| Variable                        | Meaning                                                                                                                                                                  |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BOARDWALK_BROWSER_TIER=1`      | Enable the per-run browser-session manager. Unset (the default) means `computer.openBrowser()` fails with a clear "not available on this runner".                        |
+| `BOARDWALK_BROWSER_CHROME_PATH` | Path to a Chromium/Chrome binary the run launches with a CDP endpoint (headful, so it renders on a display).                                                             |
+| `BOARDWALK_BROWSER_MCP_COMMAND` | Command to launch [Playwright MCP](https://github.com/microsoft/playwright-mcp) (e.g. a `playwright-mcp` bin, or `npx`). The runner attaches it to the browser over CDP. |
+| `DISPLAY`                       | The X display the browser renders on (e.g. a headless `Xvfb :0`).                                                                                                        |
+
+So a self-hosted machine that wants the browser tier installs Chromium + Playwright MCP, runs a
+display (e.g. `Xvfb`), and sets those variables. Nothing else changes; a machine without them
+runs every non-browser workflow exactly as before.
+
 ## Security model
 
 This part of the contract is settled, even though the client isn't built yet:

package/dist/runtime/browser_session.d.ts

@@ -0,0 +1,59 @@
+import type { ArtifactRef, BrowserSession, BrowserSessionOptions, McpServerRef } from "@boardwalk-labs/workflow/runtime";
+/** One MCP tool result content block (the subset we consume). */
+export interface McpContentBlock {
+    type: string;
+    text?: string;
+    /** base64 for `type: "image"`. */
+    data?: string;
+    mimeType?: string;
+}
+export interface McpToolResult {
+    content: readonly McpContentBlock[];
+    isError: boolean;
+}
+/** A live MCP client bound to one session's Playwright MCP server (the PROGRAM's channel). */
+export interface SessionMcpCaller {
+    callTool: (name: string, args: Record<string, unknown>) => Promise<McpToolResult>;
+    close: () => Promise<void>;
+}
+/** A launched browser process: the CDP endpoint + the Playwright MCP HTTP URL the agent binds to. */
+export interface BrowserProcess {
+    /** e.g. `http://127.0.0.1:9222` (program-internal, never exposed). */
+    readonly cdpUrl: string;
+    /** e.g. `http://127.0.0.1:9333/mcp` — the agent's MCP endpoint. */
+    readonly mcpUrl: string;
+    /** Terminate Chromium + the Playwright MCP server. Idempotent. */
+    kill: () => Promise<void>;
+}
+/** Spawns Chromium (headful on the guest display) + a per-session Playwright MCP attached to it,
+ *  with the arbitrary-JS tools (`browser_evaluate`, `browser_run_code_unsafe`) DISABLED for the
+ *  agent — page-eval stays program-only. Production impl in browser_session_backend.ts. */
+export interface BrowserBackend {
+    launch: (opts: BrowserSessionOptions | undefined) => Promise<BrowserProcess>;
+}
+/** Store a captured screenshot as a run artifact; returns its ref (the same store `artifacts.write` uses). */
+export type ScreenshotArtifactWriter = (name: string, contentType: string, base64: string, metadata: Record<string, unknown>) => Promise<ArtifactRef>;
+export interface BrowserSessionManagerDeps {
+    backend: BrowserBackend;
+    /** Open the PROGRAM's MCP client to a session's Playwright MCP HTTP URL. */
+    connect: (mcpUrl: string) => Promise<SessionMcpCaller>;
+    writeArtifact: ScreenshotArtifactWriter;
+    /** Monotonic session-id source (injected for determinism in tests). */
+    nextId: () => string;
+}
+/**
+ * Per-run manager of browser sessions. Opens them (spawn + connect + handle), resolves a session to
+ * its agent-facing MCP ref for `agent({ session })` binding, and reaps every open session at run end.
+ */
+export declare class BrowserSessionManager {
+    private readonly deps;
+    private readonly sessions;
+    constructor(deps: BrowserSessionManagerDeps);
+    open(opts?: BrowserSessionOptions): Promise<BrowserSession>;
+    /** The agent-facing MCP ref for a session handle, or null if it isn't a live session of this run
+     *  (e.g. already closed, or a foreign object). The host appends this to the leaf's `mcp`. */
+    mcpRefFor(session: BrowserSession): McpServerRef | null;
+    /** Tear down every still-open session. Called once when the run ends (best-effort per session). */
+    closeAll(): Promise<void>;
+    private reap;
+}

package/dist/runtime/browser_session.js

@@ -0,0 +1,188 @@
+// Browser-tier computer use — the runtime backing for `computer.openBrowser()` (the SDK surface)
+// and `agent({ session })`. See docs/COMPUTER_USE_SESSION.md.
+//
+// A session is a program-owned, in-VM Chromium with a CDP endpoint, plus a per-session Playwright
+// MCP HTTP server attached to that endpoint. The agent drives the browser through that MCP server
+// (the ENGINE connects to it — binding a session is just adding its http MCP ref to the leaf's
+// `mcp`, which passes assertHostedMcpAllowed unchanged since it's http + a valid localhost URL).
+// The trusted PROGRAM drives/inspects the same browser through this module's own MCP client (the
+// `BrowserSession` handle methods).
+//
+// The process spawn (Chromium + Playwright MCP, on the guest display) and the MCP client are behind
+// injected seams (`BrowserBackend`, `SessionMcpCaller`) so the manager + handle logic is unit-tested
+// without a guest; the production seams (browser_session_backend.ts) run against the guest image.
+import { AppError, ErrorCode } from "./support/index.js";
+/** Browser tools hidden from the AGENT: arbitrary page JS (`browser_evaluate`) and arbitrary
+ *  Playwright driver code (`browser_run_code_unsafe`). The engine drops them from the agent's tool
+ *  set (McpServerRef.excludeTools), while the trusted program keeps them via its own MCP client (the
+ *  SessionMcpCaller connects to the same server directly, unfiltered) — so `session.eval()` still
+ *  works and the model can't run arbitrary code. Least privilege; see docs/COMPUTER_USE_SESSION.md. */
+const AGENT_EXCLUDED_BROWSER_TOOLS = ["browser_evaluate", "browser_run_code_unsafe"];
+/**
+ * Per-run manager of browser sessions. Opens them (spawn + connect + handle), resolves a session to
+ * its agent-facing MCP ref for `agent({ session })` binding, and reaps every open session at run end.
+ */
+export class BrowserSessionManager {
+    deps;
+    sessions = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async open(opts) {
+        const id = this.deps.nextId();
+        const proc = await this.deps.backend.launch(opts);
+        let caller;
+        try {
+            caller = await this.deps.connect(proc.mcpUrl);
+        }
+        catch (err) {
+            await proc.kill();
+            throw err;
+        }
+        const mcpRef = {
+            name: `browser-${id}`,
+            transport: "http",
+            url: proc.mcpUrl,
+            excludeTools: AGENT_EXCLUDED_BROWSER_TOOLS,
+        };
+        const handle = makeBrowserSessionHandle(id, caller, this.deps.writeArtifact, () => this.reap(id));
+        this.sessions.set(id, { handle, mcpRef, proc, caller });
+        return handle;
+    }
+    /** The agent-facing MCP ref for a session handle, or null if it isn't a live session of this run
+     *  (e.g. already closed, or a foreign object). The host appends this to the leaf's `mcp`. */
+    mcpRefFor(session) {
+        return this.sessions.get(session.id)?.mcpRef ?? null;
+    }
+    /** Tear down every still-open session. Called once when the run ends (best-effort per session). */
+    async closeAll() {
+        const open = [...this.sessions.keys()];
+        await Promise.allSettled(open.map((id) => this.reap(id)));
+    }
+    async reap(id) {
+        const s = this.sessions.get(id);
+        if (s === undefined)
+            return;
+        this.sessions.delete(id);
+        // Close the client first (unblocks the server), then kill the processes. Both best-effort.
+        await Promise.allSettled([s.caller.close(), s.proc.kill()]);
+    }
+}
+/** Text of a tool result (all text blocks joined). */
+function textOf(result) {
+    return result.content
+        .map((c) => (typeof c.text === "string" ? c.text : ""))
+        .filter((t) => t.length > 0)
+        .join("\n");
+}
+function assertOk(result, tool) {
+    if (result.isError) {
+        throw new AppError(ErrorCode.INTERNAL_ERROR, `browser ${tool} failed: ${textOf(result)}`, {
+            kind: "browser_tool_error",
+            tool,
+        });
+    }
+    return result;
+}
+/** Parse a single `Field: value` line out of a Playwright MCP `browser_snapshot` header. */
+function fieldFromSnapshot(snapshot, field) {
+    const re = new RegExp(`^\\s*-?\\s*${field}:\\s*(.+)$`, "m");
+    return re.exec(snapshot)?.[1]?.trim() ?? "";
+}
+function makeBrowserSessionHandle(id, caller, writeArtifact, onClose) {
+    const call = (name, args = {}) => caller.callTool(name, args);
+    let closed = false;
+    const live = () => {
+        if (closed) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, `browser session ${id} is closed`, {
+                kind: "browser_session_closed",
+            });
+        }
+    };
+    return {
+        id,
+        async navigate(url) {
+            live();
+            assertOk(await call("browser_navigate", { url }), "navigate");
+        },
+        async url() {
+            live();
+            return fieldFromSnapshot(textOf(assertOk(await call("browser_snapshot"), "snapshot")), "Page URL");
+        },
+        async title() {
+            live();
+            return fieldFromSnapshot(textOf(assertOk(await call("browser_snapshot"), "snapshot")), "Page Title");
+        },
+        async screenshot(opts) {
+            live();
+            const res = assertOk(await call("browser_take_screenshot", { fullPage: opts?.fullPage ?? false }), "screenshot");
+            const image = res.content.find((c) => c.type === "image" && typeof c.data === "string");
+            if (image?.data === undefined) {
+                throw new AppError(ErrorCode.INTERNAL_ERROR, "browser screenshot returned no image", {
+                    kind: "browser_screenshot_no_image",
+                });
+            }
+            return await writeArtifact(`screenshot-${id}-${Date.now().toString(36)}.png`, image.mimeType ?? "image/png", image.data, { kind: "screenshot", session_id: id });
+        },
+        async console() {
+            live();
+            return parseConsole(textOf(assertOk(await call("browser_console_messages"), "console")));
+        },
+        async network() {
+            live();
+            return parseNetwork(textOf(assertOk(await call("browser_network_requests"), "network")));
+        },
+        async eval(expression) {
+            live();
+            // Playwright MCP's browser_evaluate takes a `function` (a JS arrow) — wrap the expression.
+            const res = assertOk(await call("browser_evaluate", { function: `() => (${expression})` }), "eval");
+            const text = textOf(res).trim();
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await onClose();
+        },
+    };
+}
+const CONSOLE_LINE = /^\s*\[?(LOG|INFO|WARN(?:ING)?|ERROR|DEBUG)\]?\s*[:-]?\s*(.*)$/i;
+function parseConsole(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        const m = CONSOLE_LINE.exec(line);
+        const level = (m?.[1] ?? "log").toLowerCase();
+        out.push({
+            level: level.startsWith("warn")
+                ? "warn"
+                : (["log", "info", "error", "debug"].includes(level)
+                    ? level
+                    : "log"),
+            text: m?.[2] ?? line.trim(),
+            timestamp: 0,
+        });
+    }
+    return out;
+}
+const NETWORK_LINE = /\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b\s+(\S+)(?:.*?\b(\d{3})\b)?/;
+function parseNetwork(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const m = NETWORK_LINE.exec(line);
+        if (m === null)
+            continue;
+        const entry = { method: m[1], url: m[2], timestamp: 0 };
+        if (m[3] !== undefined)
+            entry.status = Number(m[3]);
+        out.push(entry);
+    }
+    return out;
+}

package/dist/runtime/browser_session_backend.d.ts

@@ -0,0 +1,44 @@
+import type { BrowserBackend, McpContentBlock, SessionMcpCaller } from "./browser_session.js";
+/**
+ * The guest-image contract for the browser tier — the values the runner-images rootfs sets so this
+ * backend can launch Chromium + Playwright MCP without any network fetch (the run's egress is proxied,
+ * so a runtime `npx` download would fail). All but `chromePath` have safe defaults.
+ */
+export interface GuestBrowserConfig {
+    /** Absolute path to the Chromium/Chrome binary the image ships (BOARDWALK_BROWSER_CHROME_PATH). */
+    chromePath: string;
+    /** X display Chromium renders on (headful, so the desktop tier can mirror it). DISPLAY, default ":0". */
+    display: string;
+    /** How to launch the PRE-INSTALLED Playwright MCP. The per-session flags (--port/--cdp-endpoint/
+     *  --config) are appended. Default runs the pinned package via npx with fetching disabled. */
+    mcpCommand: string;
+    mcpBaseArgs: readonly string[];
+    /** Milliseconds to wait for Chromium's CDP endpoint / the MCP server to answer before failing. */
+    readyTimeoutMs: number;
+}
+/** True when the runner image declares the browser stack present (BOARDWALK_BROWSER_TIER=1). */
+export declare function browserTierEnabled(env: NodeJS.ProcessEnv): boolean;
+/** Read the guest browser config from env, or null when the tier is disabled / no Chrome path is set. */
+export declare function loadGuestBrowserConfig(env: NodeJS.ProcessEnv): GuestBrowserConfig | null;
+/** Bind an ephemeral port, read it, release it — then hand it to the child. A tiny TOCTOU window, but
+ *  each run owns its VM/container so nothing else competes for the loopback port. */
+export declare function freePort(): Promise<number>;
+/** Poll an HTTP URL until it answers (any status < 500 counts as "up" — Playwright MCP's localhost
+ *  guard returns 403 to a bare GET, which still proves the server is listening). */
+export declare function waitForHttp(url: string, timeoutMs: number): Promise<void>;
+/**
+ * Build the production BrowserBackend. Each `launch` allocates two loopback ports, spawns a
+ * program-owned Chromium (CDP endpoint, headful on the guest display, isolated profile) and a
+ * per-session Playwright MCP HTTP server attached to it, waits for both to answer, and returns the
+ * handle the manager wraps. On any failure it tears down everything it started (no leaked processes /
+ * temp profiles).
+ */
+export declare function makeGuestBrowserBackend(cfg: GuestBrowserConfig): BrowserBackend;
+/** Adapt one MCP tool-result content block (the SDK's loose shape) to the subset browser_session.ts reads. */
+export declare function toContentBlock(block: unknown): McpContentBlock;
+/**
+ * The program's MCP client factory: open a StreamableHTTP client to a session's Playwright MCP server
+ * (the trusted PROGRAM's channel, distinct from the engine's separate connection the AGENT uses). Wraps
+ * the SDK Client behind the manager's `SessionMcpCaller` seam. `mcpUrl` must be the `localhost` form.
+ */
+export declare function connectSessionMcp(mcpUrl: string): Promise<SessionMcpCaller>;

package/dist/runtime/browser_session_backend.js

@@ -0,0 +1,221 @@
+// Production seams for the browser tier — the guest-coupled halves of browser_session.ts's injected
+// contracts: the `BrowserBackend` (spawn a program-owned CDP Chromium on the guest display + a
+// per-session Playwright MCP HTTP server attached to it) and the program's MCP client factory
+// (`connectSessionMcp`). See docs/COMPUTER_USE_SESSION.md.
+//
+// These only run where the runner IMAGE ships the browser stack (Chromium + a pre-installed
+// Playwright MCP + an X display). The composition root gates on `browserTierEnabled(env)` and only
+// constructs a BrowserSessionManager with this backend when the image opts in — elsewhere
+// `computer.openBrowser()` fails with a clear "not available on this runner image".
+//
+// Config proven against Playwright MCP 0.0.77 (spike, 2026-07-09):
+//   - HTTP mode (`--port`) + `--cdp-endpoint` attach + a StreamableHTTP client all work.
+//   - The agent's + the program's MCP URL MUST use `localhost` (not 127.0.0.1): the `/mcp` endpoint
+//     enforces a literal `localhost` Host as DNS-rebinding protection, and `--allowed-hosts '*'`
+//     does NOT lift it. So `mcpUrl` is built with `localhost`; the engine binds the same ref.
+//   - `capabilities:['core']` does NOT drop `browser_evaluate` / `browser_run_code_unsafe` — they
+//     are core tools. Excluding them from the AGENT (they stay available to the trusted program's
+//     `eval()`) is an engine-level `excludeTools` follow-up, tracked in COMPUTER_USE_SESSION.md.
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { AppError, ErrorCode, createLogger } from "./support/index.js";
+const log = createLogger("browser_backend");
+const DEFAULT_MCP_PACKAGE = "@playwright/mcp@0.0.77";
+/** True when the runner image declares the browser stack present (BOARDWALK_BROWSER_TIER=1). */
+export function browserTierEnabled(env) {
+    return env.BOARDWALK_BROWSER_TIER === "1";
+}
+/** Read the guest browser config from env, or null when the tier is disabled / no Chrome path is set. */
+export function loadGuestBrowserConfig(env) {
+    if (!browserTierEnabled(env))
+        return null;
+    const chromePath = env.BOARDWALK_BROWSER_CHROME_PATH?.trim();
+    if (chromePath === undefined || chromePath.length === 0) {
+        log.warn("browser_tier_missing_chrome_path");
+        return null;
+    }
+    // A custom command (a direct bin) takes no npx prefix; the default is `npx --no-install <pkg>`.
+    const command = env.BOARDWALK_BROWSER_MCP_COMMAND?.trim();
+    const baseArgs = command === undefined || command.length === 0
+        ? ["--yes", "--no-install", env.BOARDWALK_BROWSER_MCP_PACKAGE?.trim() || DEFAULT_MCP_PACKAGE]
+        : (env.BOARDWALK_BROWSER_MCP_ARGS ?? "").split(/\s+/).filter((a) => a.length > 0);
+    const timeout = Number(env.BOARDWALK_BROWSER_READY_TIMEOUT_MS);
+    return {
+        chromePath,
+        display: env.DISPLAY?.trim() || ":0",
+        mcpCommand: command !== undefined && command.length > 0 ? command : "npx",
+        mcpBaseArgs: baseArgs,
+        readyTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : 30_000,
+    };
+}
+/** Bind an ephemeral port, read it, release it — then hand it to the child. A tiny TOCTOU window, but
+ *  each run owns its VM/container so nothing else competes for the loopback port. */
+export async function freePort() {
+    return await new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr === null || typeof addr === "string") {
+                srv.close(() => reject(new Error("could not allocate a port")));
+                return;
+            }
+            const { port } = addr;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/** Poll an HTTP URL until it answers (any status < 500 counts as "up" — Playwright MCP's localhost
+ *  guard returns 403 to a bare GET, which still proves the server is listening). */
+export async function waitForHttp(url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "no response";
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(url);
+            if (res.status < 500)
+                return;
+            lastErr = `status ${String(res.status)}`;
+        }
+        catch (err) {
+            lastErr = err instanceof Error ? err.message : String(err);
+        }
+        await delay(200);
+    }
+    throw new AppError(ErrorCode.INTERNAL_ERROR, `browser backend: ${url} never came up (${lastErr})`, {
+        kind: "browser_backend_timeout",
+    });
+}
+function killProc(proc) {
+    try {
+        if (proc.exitCode === null && proc.signalCode === null)
+            proc.kill("SIGKILL");
+    }
+    catch {
+        // best-effort: a dead child must not throw out of teardown.
+    }
+}
+/**
+ * Build the production BrowserBackend. Each `launch` allocates two loopback ports, spawns a
+ * program-owned Chromium (CDP endpoint, headful on the guest display, isolated profile) and a
+ * per-session Playwright MCP HTTP server attached to it, waits for both to answer, and returns the
+ * handle the manager wraps. On any failure it tears down everything it started (no leaked processes /
+ * temp profiles).
+ */
+export function makeGuestBrowserBackend(cfg) {
+    return {
+        async launch(opts) {
+            const cdpPort = await freePort();
+            const mcpPort = await freePort();
+            const profileDir = await mkdtemp(join(tmpdir(), "bw-browser-"));
+            const cdpUrl = `http://127.0.0.1:${String(cdpPort)}`;
+            // localhost (NOT 127.0.0.1) — the Playwright MCP /mcp endpoint rejects any other Host (spike).
+            const mcpUrl = `http://localhost:${String(mcpPort)}/mcp`;
+            const started = [];
+            const cleanup = async () => {
+                for (const p of started)
+                    killProc(p);
+                await rm(profileDir, { recursive: true, force: true }).catch(() => undefined);
+            };
+            try {
+                // 1) Program-owned Chromium with a CDP endpoint, headful on the guest display so the desktop
+                //    tier + recording can mirror it. The isolated profile dir is this session's alone.
+                const chrome = spawn(cfg.chromePath, [
+                    `--remote-debugging-port=${String(cdpPort)}`,
+                    `--user-data-dir=${profileDir}`,
+                    "--no-first-run",
+                    "--no-default-browser-check",
+                    "--disable-features=Translate",
+                    ...(opts?.startUrl !== undefined ? [opts.startUrl] : ["about:blank"]),
+                ], { stdio: "ignore", env: { ...process.env, DISPLAY: cfg.display } });
+                started.push(chrome);
+                chrome.once("error", (err) => {
+                    log.error("browser_chrome_spawn_error", { error: err.message });
+                });
+                await waitForHttp(`${cdpUrl}/json/version`, cfg.readyTimeoutMs);
+                // 2) Per-session Playwright MCP in HTTP mode, attached to the CDP browser. `sharedBrowserContext`
+                //    so the program's client and the agent's engine connection drive the SAME browser context.
+                const configPath = join(profileDir, "pw-mcp.json");
+                await writeFile(configPath, JSON.stringify({ capabilities: ["core"], sharedBrowserContext: true }));
+                const mcp = spawn(cfg.mcpCommand, [
+                    ...cfg.mcpBaseArgs,
+                    "--port",
+                    String(mcpPort),
+                    "--host",
+                    "127.0.0.1",
+                    // Only loopback clients exist inside the VM; disable the DNS-rebinding host list (the
+                    // literal-localhost guard on /mcp still applies, which is why mcpUrl uses `localhost`).
+                    "--allowed-hosts",
+                    "*",
+                    "--cdp-endpoint",
+                    cdpUrl,
+                    "--config",
+                    configPath,
+                ], { stdio: ["ignore", "ignore", "inherit"], env: { ...process.env, DISPLAY: cfg.display } });
+                started.push(mcp);
+                mcp.once("error", (err) => {
+                    log.error("browser_mcp_spawn_error", { error: err.message });
+                });
+                await waitForHttp(`http://127.0.0.1:${String(mcpPort)}/mcp`, cfg.readyTimeoutMs);
+                let killed = false;
+                return {
+                    cdpUrl,
+                    mcpUrl,
+                    kill: async () => {
+                        if (killed)
+                            return;
+                        killed = true;
+                        await cleanup();
+                    },
+                };
+            }
+            catch (err) {
+                await cleanup();
+                throw err;
+            }
+        },
+    };
+}
+/** Adapt one MCP tool-result content block (the SDK's loose shape) to the subset browser_session.ts reads. */
+export function toContentBlock(block) {
+    if (block === null || typeof block !== "object")
+        return { type: "unknown" };
+    const b = block;
+    const out = { type: typeof b.type === "string" ? b.type : "unknown" };
+    if (typeof b.text === "string")
+        out.text = b.text;
+    if (typeof b.data === "string")
+        out.data = b.data;
+    if (typeof b.mimeType === "string")
+        out.mimeType = b.mimeType;
+    return out;
+}
+/**
+ * The program's MCP client factory: open a StreamableHTTP client to a session's Playwright MCP server
+ * (the trusted PROGRAM's channel, distinct from the engine's separate connection the AGENT uses). Wraps
+ * the SDK Client behind the manager's `SessionMcpCaller` seam. `mcpUrl` must be the `localhost` form.
+ */
+export async function connectSessionMcp(mcpUrl) {
+    const client = new Client({ name: "boardwalk-runner", version: "1" });
+    // The SDK's concrete transport types `sessionId` as `string | undefined`, which trips our
+    // exactOptionalPropertyTypes against the `Transport` interface's optional `sessionId?`. Cast at
+    // this one seam — a pure type-strictness artifact, not a runtime mismatch.
+    const transport = new StreamableHTTPClientTransport(new URL(mcpUrl));
+    await client.connect(transport);
+    return {
+        callTool: async (name, args) => {
+            const result = await client.callTool({ name, arguments: args });
+            const content = Array.isArray(result.content) ? result.content.map(toContentBlock) : [];
+            return { content, isError: result.isError === true };
+        },
+        close: async () => {
+            await client.close();
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -2,6 +2,7 @@ import type { AuthContext } from "./support/index.js";
 import type { Run } from "./wire/run.js";
 import { type IdentityRelay } from "./identity_relay.js";
 import type { ByoInferenceProvider } from "../contract.js";
+import { type BrowserBackend } from "./browser_session.js";
 import { type ProgramWorkerDeps } from "./program_worker.js";
 /** Constructed primitives the pure assembly consumes (real ones in main(), fakes in tests). The
  *  runner holds NO platform credential — only the per-run control-plane handle (run token + broker
@@ -32,6 +33,10 @@ export interface WorkerRuntime {
      *  boot). When set, the worker suspends by FREEZING — the FreezeCoordinator parks seams over this
      *  relay's suspend/wake channel — instead of the exit-and-replay path. */
     freezeRelay?: IdentityRelay;
+    /** The browser tier's process backend, present ONLY when the runner IMAGE ships the browser stack
+     *  (Chromium + a pre-installed Playwright MCP + an X display; gated by BOARDWALK_BROWSER_TIER).
+     *  When absent, `computer.openBrowser()` fails with a clear "not available on this runner image". */
+    browserBackend?: BrowserBackend;
 }
 /** Durable events are deferred (durable event storage) — live fan-out via the broker only. */
 /** Synthesize the run's AuthContext. The run was already authorized at trigger time; the

package/dist/runtime/index.js

@@ -39,6 +39,8 @@ import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagn
 import { FreezeCoordinator } from "./freeze_coordinator.js";
 import { reseedUserspaceCsprng } from "./uniqueness_reseed.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
+import { BrowserSessionManager } from "./browser_session.js";
+import { loadGuestBrowserConfig, makeGuestBrowserBackend, connectSessionMcp, } from "./browser_session_backend.js";
 import { runProgramWorker, } from "./program_worker.js";
 import { RunnerControlClient } from "./runner_control_client.js";
 import { BrokerChildDispatcher } from "./broker_child_dispatcher.js";
@@ -174,6 +176,26 @@ export function assembleWorkerDeps(runtime) {
         // Broker-backed artifact store (shared by the program's artifacts.write hook AND the engine's
         // host-backed `artifacts` tool). Presigned for large bodies; the runner holds no S3 creds.
         const artifactStore = new BrokerArtifactStore(broker);
+        // Browser tier (browser-session computer use): a per-run manager over the image's process backend.
+        // Only present when the runner image ships the browser stack (runtime.browserBackend set); else
+        // `computer.openBrowser()` throws "not available". A captured screenshot is stored as a run artifact
+        // through the SAME broker store — decoded from the MCP image block's base64 as binary bytes.
+        const browserSessions = runtime.browserBackend !== undefined
+            ? new BrowserSessionManager({
+                backend: runtime.browserBackend,
+                connect: connectSessionMcp,
+                writeArtifact: (name, contentType, base64, metadata) => artifactStore
+                    .write({
+                    name,
+                    contentType,
+                    body: base64,
+                    encoding: "base64",
+                    ...(metadata !== undefined ? { metadata } : {}),
+                })
+                    .then((res) => ({ id: res.id, name: res.name, url: res.signedUrl })),
+                nextId: () => newId(),
+            })
+            : undefined;
         // Backend for the engine's host-backed built-in tools (webfetch/web_search/artifacts): web_search
         // + artifact read-back go through the broker (no Tavily/S3 creds here); webfetch is an in-process
         // fetch already gated by the worker's egress proxy.
@@ -323,6 +345,9 @@ export function assembleWorkerDeps(runtime) {
                     },
                 }
                 : {}),
+            // Browser tier: `computer.openBrowser()` + `agent({ session })` resolve through this manager
+            // (absent ⇒ the host throws "not available on this runner image").
+            ...(browserSessions !== undefined ? { browserSessions } : {}),
             phases: phaseTracker,
         });
         // Late-bind the coordinator's per-run hooks now that the run-scoped objects exist.
@@ -379,6 +404,9 @@ export function assembleWorkerDeps(runtime) {
             // Resolves when a host seam suspends the run; the program runner races it against the body.
             suspendSignal,
             ...(workspaceStore !== undefined ? { workspace: workspaceStore } : {}),
+            // The orchestrator reaps every still-open browser session on terminal (kill Chromium + its
+            // Playwright MCP) so no browser process leaks past the run.
+            ...(browserSessions !== undefined ? { browserSessions } : {}),
         });
     };
     return {
@@ -585,6 +613,11 @@ export async function main() {
     const runId = platform.runId;
     const byoProviders = parseByoProviders(process.env.BOARDWALK_BYO_PROVIDERS);
     Reflect.deleteProperty(process.env, "BOARDWALK_BYO_PROVIDERS");
+    // Browser tier: only when the runner IMAGE declares the browser stack (BOARDWALK_BROWSER_TIER=1 +
+    // a Chrome path). The backend is run-independent (buildHost builds the per-run manager over it);
+    // absent ⇒ `computer.openBrowser()` fails clearly. Read here so env-reading stays out of the pure wiring.
+    const guestBrowserConfig = loadGuestBrowserConfig(process.env);
+    const browserBackend = guestBrowserConfig !== null ? makeGuestBrowserBackend(guestBrowserConfig) : undefined;
     const deps = assembleWorkerDeps({
         workerId: process.env.WORKER_ID ?? `worker-${runId}`,
         workspaceRoot: process.env.WORKSPACE_ROOT ?? "/workspace",
@@ -593,6 +626,7 @@ export async function main() {
         vcpus: platform.vcpus,
         ...(byoProviders.length > 0 ? { byoProviders } : {}),
         ...(freezeRelay !== undefined ? { freezeRelay } : {}),
+        ...(browserBackend !== undefined ? { browserBackend } : {}),
     });
     // The only thing to drain is the batched telemetry buffer — the runner opens no database, cache, or queue.
     const cleanup = async () => {

package/dist/runtime/program_worker.d.ts

@@ -97,6 +97,12 @@ export type ProgramHostBuilder = (run: Run, manifest: WorkflowManifest, signal:
      *  program runner so a suspend short-circuits the body out of band (the durable-suspension design). Absent ⇒
      *  no durable suspension on this path (a suspend then surfaces as a thrown SuspendError). */
     suspendSignal?: Promise<SuspendSignal>;
+    /** The run's browser-session manager (browser tier). The orchestrator reaps every still-open session
+     *  on EVERY terminal path so no Chromium / Playwright MCP process leaks past the run. `closeAll` is
+     *  best-effort + never throws. Absent on images without the browser stack. */
+    browserSessions?: {
+        closeAll(): Promise<void>;
+    };
 }>;
 /** Handle to a running per-session loop (metering or credit watch); `stop()` ends + drains it. */
 export interface RunSessionHandle {

package/dist/runtime/program_worker.js

@@ -111,6 +111,7 @@ export async function runProgramWorker(runId, deps) {
         return { kind: "failed", reason: "host_build_failed" };
     }
     const { host, redactor, workspace, phases, activity, setProgramDir, lsp, suspendSignal } = built;
+    const browserSessions = built.browserSessions;
     // Guarantee the /workspace sandbox dir exists for EVERY run (persist or not) so a program can write
     // to /workspace without a defensive mkdir. Runs before hydrate (whose extract targets the dir).
     // Best-effort — the image pre-creates the dir; a failure here would resurface at the program's write.
@@ -208,6 +209,16 @@ export async function runProgramWorker(runId, deps) {
         // is safe (it runs before the workspace snapshot, which is the slowest step).
         if (lsp !== undefined)
             await lsp.close();
+        // Reap every still-open browser session (kill Chromium + its Playwright MCP) on EVERY terminal
+        // path, before the workspace snapshot. Best-effort — a dead session must not mask the run's outcome.
+        if (browserSessions !== undefined) {
+            await browserSessions.closeAll().catch((err) => {
+                log.warn("browser_sessions_close_failed", {
+                    runId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
         // Snapshot the final /workspace so the workflow's NEXT run hydrates it. Best-effort.
         if (workspace !== undefined) {
             await workspace.persist();

package/dist/runtime/wire/inference_proxy.d.ts

@@ -47,8 +47,9 @@ export type InferenceFrame = {
 } | {
     kind: "ping";
 };
-/** Serialize the request body. (Binary message content — multimodal image/doc bytes — is not yet
- *  supported on this path; v0 agent flows are text + JSON tool results.) */
+/** Serialize the request body. Multimodal image content rides transparently: message content parts
+ *  (incl. `{ type: "image" }`) are plain JSON here — the broker's engine adapters render them per
+ *  provider (@boardwalk-labs/engine ≥ 0.1.32). */
 export declare function serializeInferenceRequest(req: InferenceProxyRequest): string;
 /** Parse + minimally validate the request body (the runner is semi-trusted; fail closed on shape).
  *  The conversation is shape-trusted past the array check — it was built by the engine loop on the

package/dist/runtime/wire/inference_proxy.js

@@ -31,8 +31,9 @@ export function runnerInferencePath(runId) {
 /** Response content type — newline-delimited JSON frames. */
 export const INFERENCE_NDJSON_CONTENT_TYPE = "application/x-ndjson";
 // ---- request serialize / parse ----
-/** Serialize the request body. (Binary message content — multimodal image/doc bytes — is not yet
- *  supported on this path; v0 agent flows are text + JSON tool results.) */
+/** Serialize the request body. Multimodal image content rides transparently: message content parts
+ *  (incl. `{ type: "image" }`) are plain JSON here — the broker's engine adapters render them per
+ *  provider (@boardwalk-labs/engine ≥ 0.1.32). */
 export function serializeInferenceRequest(req) {
     return JSON.stringify(req);
 }

package/dist/runtime/workflow_host.d.ts

@@ -1,4 +1,5 @@
-import type { WorkflowHost, AgentOptions, ArtifactBody, ArtifactRef, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, SleepArg } from "@boardwalk-labs/workflow/runtime";
+import type { WorkflowHost, AgentOptions, ArtifactBody, ArtifactRef, BrowserSession, BrowserSessionOptions, CallOptions, HumanInputOptions, HumanInputResult, PhaseOptions, SleepArg } from "@boardwalk-labs/workflow/runtime";
+import type { BrowserSessionManager } from "./browser_session.js";
 import { type LeafResume } from "@boardwalk-labs/engine/core";
 import { type JournalSeam, type SuspendSignal } from "./suspension.js";
 import type { FreezeCoordinator } from "./freeze_coordinator.js";
@@ -103,6 +104,10 @@ export interface WorkerWorkflowHostDeps {
     /** Persists a file artifact for the run (→ broker artifact store); resolves to its id + signed
      *  download URL. Absent ⇒ artifacts.write is unsupported and the host method rejects clearly. */
     writeArtifact?: (name: string, contentType: string, body: ArtifactBody, metadata: Record<string, unknown> | undefined) => Promise<ArtifactRef>;
+    /** Per-run browser-session manager (computer use, the browser tier). Absent ⇒ `computer.openBrowser`
+     *  is unsupported (no desktop/browser backend) and the host method rejects clearly. When present,
+     *  `agent({ session })` binds the session's in-VM Playwright MCP to the leaf. */
+    browserSessions?: BrowserSessionManager;
     /** Cooperative-cancellation signal for the run (credit exhaustion today; user cancel later). Every
      *  hook checks it at entry and unwinds (throws RunAbortedError); the spending/blocking hooks
      *  (`agent`/`sleep`/`callWorkflow`) thread it down so an in-flight op stops promptly. Absent ⇒ no
@@ -233,6 +238,15 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     scheduleWorkflow(slug: string, input: unknown, opts: ScheduleOptions): Promise<string>;
     getSecret(name: string): Promise<string>;
     writeArtifact(name: string, contentType: string, body: ArtifactBody, metadata: Record<string, unknown> | undefined): Promise<ArtifactRef>;
+    /** `computer.openBrowser()`: open a program-owned, in-VM browser session (the browser tier of
+     *  computer use). Not a durable seam — a session is a live resource, reaped at run end, never
+     *  journaled/replayed. Absent backend ⇒ a clear "not available" error. */
+    openBrowserSession(opts: BrowserSessionOptions | undefined): Promise<BrowserSession>;
+    /** Translate `agent({ session })` into the leaf's `mcp`: append the browser session's in-VM
+     *  Playwright MCP (its http ref, which passes assertHostedMcpAllowed and reaches localhost without
+     *  the egress proxy) and strip the `session` handle (the engine doesn't understand it). No-op when
+     *  no session is bound. */
+    private bindBrowserSession;
     sleep(arg: SleepArg): Promise<void>;
     /** A short sleep HOLDS the task in-process (cheaper than a release + replay round-trip); a long one
      *  (≥ {@link SUSPEND_THRESHOLD_MS}) SUSPENDS — releases the task, and a timer re-dispatches the run

package/dist/runtime/workflow_host.js

@@ -237,9 +237,13 @@ export class WorkerWorkflowHost {
                 resume = leafResumeSchema.parse(existing.result);
             }
         }
+        // Bind a computer-use session's tools (browser tier ⇒ its in-VM Playwright MCP) if one was passed.
+        // Done AFTER the fingerprint so the injected MCP never perturbs determinism (the fingerprint keys
+        // on provider/model/prompt/schema only — an mcp/session change must not invalidate a journal hit).
+        const effectiveOpts = this.bindBrowserSession(opts);
         for (;;) {
             try {
-                const result = await this.deps.leaf.run(prompt, opts, this.deps.signal, resume);
+                const result = await this.deps.leaf.run(prompt, effectiveOpts, this.deps.signal, resume);
                 await this.deps.journal?.put({
                     seq,
                     kind: "agent",
@@ -459,6 +463,32 @@ export class WorkerWorkflowHost {
             return ref;
         });
     }
+    /** `computer.openBrowser()`: open a program-owned, in-VM browser session (the browser tier of
+     *  computer use). Not a durable seam — a session is a live resource, reaped at run end, never
+     *  journaled/replayed. Absent backend ⇒ a clear "not available" error. */
+    openBrowserSession(opts) {
+        return this.guarded(async () => {
+            if (this.deps.browserSessions === undefined) {
+                throw new AppError(ErrorCode.VALIDATION_FAILED, "computer.openBrowser is not available in this runtime (no browser backend)");
+            }
+            return await this.deps.browserSessions.open(opts);
+        });
+    }
+    /** Translate `agent({ session })` into the leaf's `mcp`: append the browser session's in-VM
+     *  Playwright MCP (its http ref, which passes assertHostedMcpAllowed and reaches localhost without
+     *  the egress proxy) and strip the `session` handle (the engine doesn't understand it). No-op when
+     *  no session is bound. */
+    bindBrowserSession(opts) {
+        if (opts === undefined || opts.session === undefined)
+            return opts;
+        const ref = this.deps.browserSessions?.mcpRefFor(opts.session);
+        if (ref === null || ref === undefined) {
+            throw new AppError(ErrorCode.VALIDATION_FAILED, "agent({ session }) received a browser session that is not open in this run", { kind: "browser_session_not_open" });
+        }
+        const rest = { ...opts };
+        delete rest.session;
+        return { ...rest, mcp: [...(rest.mcp ?? []), ref] };
+    }
     sleep(arg) {
         return this.guarded(() => this.sleepSeam(arg));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -53,23 +53,24 @@
     "prebuild": "prebuildify --napi --strip -t 24.0.0"
   },
   "dependencies": {
-    "zod": "^4.0.0",
-    "@boardwalk-labs/engine": "^0.1.29",
-    "@boardwalk-labs/workflow": "^0.1.17",
+    "@boardwalk-labs/engine": "^0.1.34",
+    "@boardwalk-labs/workflow": "^0.1.24",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "node-gyp-build": "^4.8.4",
     "tar": "^7.5.16",
-    "node-gyp-build": "^4.8.4"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.6",
     "eslint": "^9.18.0",
+    "node-gyp": "^11.0.0",
+    "prebuildify": "^6.0.1",
     "prettier": "^3.4.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.20.0",
-    "vitest": "^3.0.0",
-    "prebuildify": "^6.0.1",
-    "node-gyp": "^11.0.0"
+    "vitest": "^3.0.0"
   },
   "bin": {
     "boardwalk-runner": "./dist/bin.js"