@boardwalk-labs/runner 0.1.11 → 0.1.13

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/binding.gyp

@@ -0,0 +1,12 @@
+{
+  "targets": [
+    {
+      "target_name": "bw_reseed",
+      "sources": ["native/reseed.c"],
+      "include_dirs": ["<(node_root_dir)/deps/openssl/openssl/include"],
+      "conditions": [
+        ["OS=='linux'", { "cflags": ["-fvisibility=hidden"] }]
+      ]
+    }
+  ]
+}

package/dist/runtime/agent/budget.d.ts

@@ -74,7 +74,7 @@ export declare class BudgetMeter {
     constructor(opts: BudgetMeterOptions);
     /**
      * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
-     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * upstream cost the broker observed for this turn (the managed provider's per-request cost) — used
      * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
      * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
      * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
@@ -83,7 +83,7 @@ export declare class BudgetMeter {
     addUsage(delta: UsageDelta, realCostUsd?: number): void;
     /**
      * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
-     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * metering — which reports token deltas to the platform (deferred; not yet wired into the brokered
      * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
      */
     snapshot(): BudgetSnapshot;
@@ -92,7 +92,7 @@ export declare class BudgetMeter {
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
      * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
      * the whole run — not once per session. `snapshot()` stays session-local because
-     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     * per-session token metering reports token deltas; seeding it would double-report usage.
      */
     cumulative(): BudgetSnapshot;
     /**
@@ -116,8 +116,8 @@ export declare class BudgetMeter {
     /**
      * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
      * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
-     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
-     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     * Managed turns instead carry the managed provider's exact per-request cost through to {@link addUsage}. Public so
+     * the loop can stamp the per-step cost without re-deriving the rate table.
      */
     costFor(delta: UsageDelta): number;
 }

package/dist/runtime/agent/budget.js

@@ -5,12 +5,12 @@
 // `AppError(BUDGET_EXCEEDED)` and the loop tears down with a `turn_ended
 // reason='error'` event.
 //
-// USD here tracks the bill closely: for a MANAGED turn the meter is fed OpenRouter's exact per-request
-// `usage.cost` (already cache-discounted + model-correct), so the `max_usd` cap reflects real spend —
+// USD here tracks the bill closely: for a MANAGED turn the meter is fed the managed provider's exact
+// per-request cost (already cache-discounted + model-correct), so the `max_usd` cap reflects real spend —
 // not a hand-rolled token estimate. Only a BYO turn (no upstream price) or a managed turn whose cost
 // the broker couldn't read falls back to a single flat representative rate
 // (`model_rates.ts::BUDGET_GUARDRAIL_RATE`), since a per-`agent()`-model run has no one model. Actual
-// billing remains per-request cost pass-through via Stripe meters (the platform spec). The meter takes
+// billing is metered by the platform, not by the runner. The meter takes
 // the fallback rate as a constructor arg so tests inject a fixed rate.
 import { AppError, ErrorCode } from "../support/index.js";
 const ZERO_PRIOR = {
@@ -44,7 +44,7 @@ export class BudgetMeter {
     }
     /**
      * Add a usage delta to the accumulator + recompute USD. `realCostUsd`, when provided, is the EXACT
-     * upstream cost the broker observed for this turn (OpenRouter's per-request `usage.cost`) — used
+     * upstream cost the broker observed for this turn (the managed provider's per-request cost) — used
      * verbatim so the `max_usd` cap tracks ACTUAL spend (already cache-discounted, model-correct).
      * Omitted for a BYO turn (no upstream price) or a managed turn whose cost the broker couldn't read,
      * which fall back to the representative-rate {@link costFor} estimate. Token counts accumulate on
@@ -59,7 +59,7 @@ export class BudgetMeter {
     }
     /**
      * THIS SESSION's accumulator snapshot (excludes prior-session usage). Read by per-session token
-     * metering — which reports token deltas to Stripe (deferred; not yet wired into the brokered
+     * metering — which reports token deltas to the platform (deferred; not yet wired into the brokered
      * loop) — and by audit/post-run cost rollups. Cap enforcement uses {@link cumulative} instead.
      */
     snapshot() {
@@ -78,7 +78,7 @@ export class BudgetMeter {
      * construction. Cap enforcement ({@link assertWithinCaps}) and checkpoint persistence use
      * this so a run that resumes after a sleep/wait/crash is bounded by its declared caps across
      * the whole run — not once per session. `snapshot()` stays session-local because
-     * per-session token metering reports token deltas; seeding it would double-report to Stripe.
+     * per-session token metering reports token deltas; seeding it would double-report usage.
      */
     cumulative() {
         const s = this.snapshot();
@@ -159,8 +159,8 @@ export class BudgetMeter {
     /**
      * USD cost for a single delta — the representative-rate ESTIMATE used only when the broker reports
      * no real upstream cost for the turn (a BYO-provider turn, or a managed turn whose cost tap missed).
-     * Managed turns instead carry OpenRouter's exact `usage.cost` through to {@link addUsage}. Public so
-     * the loop can stamp the per-step `cost_usd` column on `run_steps` without re-deriving the rate table.
+     * Managed turns instead carry the managed provider's exact per-request cost through to {@link addUsage}. Public so
+     * the loop can stamp the per-step cost without re-deriving the rate table.
      */
     costFor(delta) {
         const inputCost = ((delta.inputTokens ?? 0) * this.rate.inputPerMillion) / 1_000_000;

package/dist/runtime/agent/model_rates.js

@@ -1,17 +1,16 @@
 // The flat budget-guardrail rate — the FALLBACK basis for the in-run `max_usd` cap (BudgetMeter).
 //
-// A MANAGED turn now caps on OpenRouter's EXACT per-request `usage.cost`, forwarded from the broker to
+// A MANAGED turn now caps on the managed provider's EXACT per-request cost, forwarded from the broker to
 // the worker (inference_proxy result frame → BudgetMeter.addUsage `realCostUsd`), so the cap tracks
 // real spend — already cache-discounted + model-correct. This flat rate is used ONLY when a turn has
 // no upstream cost: a BYO-provider turn (the org pays its own key), or a managed turn whose cost the
-// broker couldn't read. It bounds runaway loops; it is NOT the bill. Actual billing is per-request
-// COST PASS-THROUGH (OpenRouter's reported cost × margin) via Stripe meters (domain/billing +
-// run_usage_service). the platform spec
+// broker couldn't read. It bounds runaway loops; it is NOT the bill. Actual billing is metered by the
+// platform, not by the runner.
 //
 // Deliberately NOT a per-model table with a silent fallback: a lookup that returns a Sonnet-class
 // default for any unknown id only created the ILLUSION of precision. The real per-request cost (above)
 // is the precise path; this rate is just the model-agnostic backstop. Un-metered managed models are
-// rejected fail-closed at resolution (domain/inference/model_resolver), so the cap never has to price
+// rejected fail-closed at resolution by the broker, so the cap never has to price
 // a model we don't support.
 /**
  * The flat representative rate (USD / million tokens) the BudgetMeter applies to the `max_usd` cap

package/dist/runtime/agent/secret_redactor.js

@@ -1,4 +1,4 @@
-// SecretRedactor — scrubs known secret values from everything bound for an LLM (the platform spec).
+// SecretRedactor — scrubs known secret values from everything bound for an LLM.
 //
 // The architectural guarantee is structural: secrets live ONLY in the workflow PROGRAM (the trusted
 // deterministic tool layer), which holds them via `secrets.get` / `ctx.secrets.resolve`. The

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>;