@boardwalk-labs/runner 0.1.11 → 0.1.13

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/cancel_watcher.js

@@ -1,4 +1,4 @@
-// CancelWatcher — stops a run when the user cancels it mid-flight (the platform spec).
+// CancelWatcher — stops a run when the user cancels it mid-flight.
 //
 // The user-cancel counterpart to CreditWatcher. One per run session. On a timer it asks — through the
 // broker (`GET /cancel`, since the runner holds no DB/Redis credential) — whether the run has been

package/dist/runtime/credit_watcher.d.ts

@@ -4,7 +4,7 @@ export interface CreditWatcherDeps {
     /** The run being watched (for correlation/logging). */
     runId: string;
     /** Resolves true while the org can keep spending; false once it's out of credit. Brokered
-     *  (`RunnerControlClient.checkCredit` → `GET /credit`), so the runner never reads Stripe. */
+     *  (`RunnerControlClient.checkCredit` → `GET /credit`), so the runner never reads billing state directly. */
     isFunded: () => Promise<boolean>;
     /** Fired exactly once when the org is first seen to be out of credit. */
     onExhausted: () => void;

package/dist/runtime/credit_watcher.js

@@ -1,14 +1,14 @@
-// CreditWatcher — stops a run when its org runs out of prepaid credit mid-flight (the platform spec).
+// CreditWatcher — stops a run when its org runs out of prepaid credit mid-flight.
 //
 // One per run session. On a timer it asks — through the broker (`GET /credit`, since the runner holds
-// no Stripe credential) — whether the org is still funded; the FIRST time it isn't, it fires
+// no billing credential) — whether the org is still funded; the FIRST time it isn't, it fires
 // `onExhausted` once (the orchestrator wires this to `AbortController.abort`, which the WorkflowHost
 // honors cooperatively) and stops checking. This is the org-level counterpart to the per-run
-// BudgetMeter cap: the run can't see Stripe balances, so funding is enforced here, out of band,
+// BudgetMeter cap: the run can't see its billing balance, so funding is enforced here, out of band,
 // against the live balance that incremental token metering keeps fresh.
 //
-// "Prompt, not instant": Stripe meter aggregation is eventually-consistent and the host honors the
-// abort at the next hook boundary, so a run stops within ~one check interval (plus Stripe's lag) of
+// "Prompt, not instant": the platform's usage metering is eventually-consistent and the host honors the
+// abort at the next hook boundary, so a run stops within ~one check interval (plus metering lag) of
 // going unfunded — bounding overshoot, not eliminating it. Applies to MANAGED and BYOK runs alike,
 // since runtime always burns credit (the gate requires the runtime floor regardless of token billing).
 import { createLogger } from "./support/index.js";

package/dist/runtime/freeze_coordinator.d.ts

@@ -51,6 +51,11 @@ export type FreezeOutcome = {
 } | {
     kind: "aborted";
     reason: string;
+}
+/** The caller withdrew the wait via its abort signal BEFORE it froze (register-without-release:
+ *  a held gate got its answer during the hold, so it resolves in-process instead of freezing). */
+ | {
+    kind: "withdrawn";
 };
 export interface FreezeCoordinatorHooks {
     /** Runs at quiescence, immediately before the freeze is requested: flush billable runtime
@@ -104,7 +109,7 @@ export declare class FreezeCoordinator {
      * the abort (the seam then holds in-process); other reasons retry the freeze after a
      * backoff. Concurrent suspending waits serialize through an internal chain.
      */
-    suspendingWait(signal: SuspendSignal): Promise<FreezeOutcome>;
+    suspendingWait(signal: SuspendSignal, abort?: AbortSignal): Promise<FreezeOutcome>;
     /** Relay handler: a wake injection landed. Validates, runs the after-wake hook (token
      *  swap + meter rebase), confirms to init, and resolves the parked seam. A wake with no
      *  parked seam is a duplicate delivery — re-confirm (idempotent), never crash. */

package/dist/runtime/freeze_coordinator.js

@@ -126,7 +126,7 @@ export class FreezeCoordinator {
      * the abort (the seam then holds in-process); other reasons retry the freeze after a
      * backoff. Concurrent suspending waits serialize through an internal chain.
      */
-    suspendingWait(signal) {
+    suspendingWait(signal, abort) {
         const turn = this.chain;
         let release = () => undefined;
         this.chain = new Promise((resolve) => {
@@ -137,7 +137,14 @@ export class FreezeCoordinator {
             try {
                 let backoff = ABORT_RETRY_INITIAL_MS;
                 for (;;) {
-                    await this.awaitQuiescence();
+                    // Withdraw window: the abort can cancel the wait any time BEFORE it sends
+                    // suspend_request (once sent, the VM freezes and the abort is moot — the process is
+                    // paused). This is register-without-release: a held gate answered during the hold.
+                    // awaitQuiescence short-circuits when already aborted, so one check after it covers
+                    // both loop entry and a mid-hold abort.
+                    await this.awaitQuiescence(abort);
+                    if (abort?.aborted === true)
+                        return { kind: "withdrawn" };
                     try {
                         await this.hooks.onBeforeFreeze?.();
                     }
@@ -167,6 +174,10 @@ export class FreezeCoordinator {
                     this.releaseGate();
                     if (outcome.kind === "wake")
                         return outcome;
+                    // The park only ever resolves wake or aborted (never withdrawn — that returns before the
+                    // park). Narrow explicitly so `.reason` is safe and a stray outcome propagates.
+                    if (outcome.kind !== "aborted")
+                        return outcome;
                     if (signal.reason === "sleep")
                         return outcome;
                     log.warn("suspend_aborted_retrying", {
@@ -228,11 +239,14 @@ export class FreezeCoordinator {
         this.parked = null;
         resolve({ kind: "aborted", reason });
     }
-    awaitQuiescence() {
-        if (this.inFlight === 0)
+    awaitQuiescence(abort) {
+        if (this.inFlight === 0 || abort?.aborted === true)
             return Promise.resolve();
         return new Promise((resolve) => {
+            // Resolve on quiescence OR abort (a held wait wakes immediately to withdraw). Resolving
+            // twice is harmless; endWork may still call the queued waiter later.
             this.quiescenceWaiters.push(resolve);
+            abort?.addEventListener("abort", () => resolve(), { once: true });
         });
     }
     releaseGate() {

package/dist/runtime/index.d.ts

@@ -2,12 +2,13 @@ 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
  *  URL); everything else is reached through the Runner Control API (the Runner Credential Broker model). */
 export interface WorkerRuntime {
-    /** Stable worker identity stamped onto the lease (ECS task arn / hostname / run-derived). */
+    /** Stable worker identity stamped onto the lease (task ARN / hostname / run-derived). */
     workerId: string;
     /** Sandbox workspace root for filesystem/shell/git tools. */
     workspaceRoot: string;
@@ -32,14 +33,18 @@ 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 (run_step_events table) — live fan-out via the broker only. */
+/** 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
  *  worker acts on the org's behalf, so it carries the org + an owner role. Tool-level
  *  boundaries (the broker's server-side manifest allowlist) are the real guard.
  *
  *  source='workflow' (NOT 'session_jwt'): the program must never perform SESSION_JWT_ONLY
- *  credential mutations (§12.11), so a tool that ever exposed such a service is denied by
+ *  credential mutations, so a tool that ever exposed such a service is denied by
  *  construction regardless of the owner role. */
 export declare function workerAuthContext(run: Run): AuthContext;
 /**
@@ -57,10 +62,10 @@ export declare function workerAuthContext(run: Run): AuthContext;
  */
 export declare function tokenMeterIdentifiers(runId: string, sessionId: string): (leafIndex: number) => string;
 /** Pure wiring: build the full ProgramWorkerDeps from the control-plane handle. The runner reaches
- *  every privileged seam through the broker over its run token — no DB / Redis / Stripe / model creds. */
+ *  every privileged seam through the broker over its run token — no database, cache, billing, or model creds. */
 export declare function assembleWorkerDeps(runtime: WorkerRuntime): ProgramWorkerDeps;
 /**
- * The per-run platform values the dispatcher injects as container env (ecs_run_task_client.ts). They
+ * The per-run platform values the dispatcher injects as container env. They
  * are captured into private worker state at bootstrap and DELETED from `process.env` before any user
  * program / agent leaf / subprocess can run — the run token + API token are credentials, and nothing
  * untrusted run code touches should inherit them (the run env/credential rules). The user owns the rest
@@ -78,7 +83,7 @@ export interface PlatformContext {
     vcpus: number;
 }
 /** The public-API origin a run uses for raw API / MCP / CLI calls. The broker (Runner Control API)
- *  is hosted on the api-server, so the public API shares its origin; the program appends `/v1` or
+ *  shares an origin with the public API, so the program appends `/v1` or
  *  `/mcp/v1`. Falls back to the broker URL unchanged if it can't be parsed. */
 export declare function publicApiOrigin(controlPlaneBaseUrl: string): string;
 /**