@boardwalk-labs/runner 0.1.11 → 0.1.13

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";
@@ -52,6 +53,13 @@ export interface ChildDispatcher {
 export interface SecretAccessor {
     get(name: string): Promise<string>;
 }
+/** Register-without-release: register a HELD HITL gate so it is
+ *  answerable while the run keeps running, and poll for the answer. Backed by the broker's
+ *  `inputs` endpoints. Absent ⇒ a held gate is only answerable once it freezes. */
+export interface HeldInputPort {
+    register(seq: number, gate: SuspendSignal["humanInput"]): Promise<unknown>;
+    poll(seq: number): Promise<Record<string, unknown>>;
+}
 /** Holds the process for `ms` milliseconds. The seam exists so tests don't wait on real time. An
  *  abort fires the hold REJECT (with the signal's RunAbortedError) and clears the timer — so a
  *  multi-day sleep aborted early doesn't leave a live timer pinning the event loop open. */
@@ -96,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
@@ -135,6 +147,11 @@ export interface WorkerWorkflowHostDeps {
      * stream, and work arriving while a freeze is pending queues until the wake.
      */
     freeze?: FreezeCoordinator;
+    /** Register-without-release for HELD human-input gates. Only
+     *  meaningful alongside `freeze`; absent ⇒ a held gate is answerable only once it freezes. */
+    heldInput?: HeldInputPort;
+    /** Poll interval for a held gate's answer (default 3s). */
+    heldPollIntervalMs?: number;
     /**
      * The highest journaled seq at claim (0 on a fresh run). While re-running seams up to this
      * frontier on a resume, the host is REPLAYING and observability (phase markers, program logs) is
@@ -147,6 +164,7 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     private readonly sleeper;
     private readonly now;
     private readonly maxSleepMs;
+    private readonly heldPollIntervalMs;
     /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
     private readonly seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
@@ -167,6 +185,25 @@ export declare class WorkerWorkflowHost implements WorkflowHost {
     /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
      *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
     private freezeWait;
+    /**
+     * Snapshot-substrate `humanInput()` with REGISTER-WITHOUT-RELEASE.
+     * A gate reached while a sibling seam is still in flight HOLDS (the quiescence gate won't freeze
+     * yet), but a human must still be able to answer during that hold. So: register the gate with the
+     * broker immediately (it surfaces in the inbox/API at once), then race two outcomes —
+     *   - the answer arrives (brokered poll) while holding ⇒ WITHDRAW the freeze wait and resolve
+     *     in-process (the run never froze); or
+     *   - quiescence is reached with no answer ⇒ the wait freezes, and the wake carries the answer.
+     * Once frozen the poll is frozen too (same process), so the race is only live during the hold.
+     * A register/poll failure degrades to the plain freeze wait — the gate still works, just without
+     * the answerable-while-held property.
+     */
+    private freezeHumanInput;
+    /** Poll the broker for a held gate's answer until it arrives or the wait withdraws. Resolves with
+     *  the answer value; never rejects the run (a transient poll error just retries next tick). Runs
+     *  OUTSIDE the quiescence gate (it is not run work — it must not block a freeze). */
+    private pollHeldAnswer;
+    /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
+    private resolveFreezeAnswer;
     /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
      *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
      *  failed loudly, never a retry. */
@@ -201,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

@@ -1,7 +1,7 @@
 // WorkerWorkflowHost — the real WorkflowHost the worker installs onto @boardwalk-labs/workflow
 // before running a program (the workflow runtime design). The program's hooks delegate here:
 //
-//   agent(prompt, opts)        → an ephemeral Strands agent leaf (the demoted agent loop)
+//   agent(prompt, opts)        → an ephemeral agent leaf (the demoted agent loop)
 //   sleep(arg)                 → an IN-PROCESS hold (hold-and-pay; no checkpoint, no exit)
 //   workflows.call(slug, in)   → a durable child run (parent holds while it runs)
 //   secrets.get(name)          → the run's fail-closed secret resolver
@@ -67,6 +67,7 @@ export class WorkerWorkflowHost {
     sleeper;
     now;
     maxSleepMs;
+    heldPollIntervalMs;
     /** Synchronous durable-seam counter + silent-replay live flag (the durable-suspension design). */
     seq;
     /** Run context + on-demand public-API bearer the SDK `runtime` accessor reads off the host. */
@@ -76,6 +77,7 @@ export class WorkerWorkflowHost {
         this.sleeper = deps.sleeper ?? new TimerSleepController();
         this.now = deps.now ?? Date.now;
         this.maxSleepMs = deps.maxSleepMs ?? MAX_SLEEP_MS;
+        this.heldPollIntervalMs = deps.heldPollIntervalMs ?? 3_000;
         this.seq = new SeamSequencer(deps.replayFrontier ?? 0);
         this.runtime = deps.runtime;
     }
@@ -118,15 +120,78 @@ export class WorkerWorkflowHost {
     }
     /** A suspending seam's freeze wait: step out of the "work" count around the park (the wait itself
      *  is what the gate waits FOR, not work that blocks it), then rejoin on resume. */
-    async freezeWait(freeze, signal) {
+    async freezeWait(freeze, signal, abort) {
         freeze.endWork();
         try {
-            return await freeze.suspendingWait(signal);
+            return await freeze.suspendingWait(signal, abort);
         }
         finally {
             freeze.beginWork();
         }
     }
+    /**
+     * Snapshot-substrate `humanInput()` with REGISTER-WITHOUT-RELEASE.
+     * A gate reached while a sibling seam is still in flight HOLDS (the quiescence gate won't freeze
+     * yet), but a human must still be able to answer during that hold. So: register the gate with the
+     * broker immediately (it surfaces in the inbox/API at once), then race two outcomes —
+     *   - the answer arrives (brokered poll) while holding ⇒ WITHDRAW the freeze wait and resolve
+     *     in-process (the run never froze); or
+     *   - quiescence is reached with no answer ⇒ the wait freezes, and the wake carries the answer.
+     * Once frozen the poll is frozen too (same process), so the race is only live during the hold.
+     * A register/poll failure degrades to the plain freeze wait — the gate still works, just without
+     * the answerable-while-held property.
+     */
+    async freezeHumanInput(freeze, signal, key) {
+        const held = this.deps.heldInput;
+        if (held === undefined) {
+            // No held-input port wired: the gate can only be answered once it freezes.
+            return this.resolveFreezeAnswer(await this.freezeWait(freeze, signal), key);
+        }
+        await held.register(signal.seq, signal.humanInput);
+        const withdraw = new AbortController();
+        const poll = this.pollHeldAnswer(held, signal.seq, key, withdraw.signal);
+        const outcome = await Promise.race([
+            poll.then((answer) => ({ kind: "answered", answer })),
+            this.freezeWait(freeze, signal, withdraw.signal).then((o) => ({ kind: "froze", o })),
+        ]);
+        if (outcome.kind === "answered") {
+            withdraw.abort(); // withdraw the still-holding freeze wait (no-op if it already froze)
+            return normalizeHumanInputResult(outcome.answer);
+        }
+        withdraw.abort(); // stop the poll loop; the wake path carries the answer
+        return this.resolveFreezeAnswer(outcome.o, key);
+    }
+    /** Poll the broker for a held gate's answer until it arrives or the wait withdraws. Resolves with
+     *  the answer value; never rejects the run (a transient poll error just retries next tick). Runs
+     *  OUTSIDE the quiescence gate (it is not run work — it must not block a freeze). */
+    async pollHeldAnswer(held, seq, key, abort) {
+        for (;;) {
+            if (abort.aborted)
+                return await new Promise(() => undefined); // frozen path won: never resolve
+            try {
+                const answers = await held.poll(seq);
+                if (key in answers)
+                    return answers[key];
+            }
+            catch {
+                /* transient — retry next tick */
+            }
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, this.heldPollIntervalMs);
+                abort.addEventListener("abort", () => {
+                    clearTimeout(t);
+                    resolve();
+                }, { once: true });
+            });
+        }
+    }
+    /** Map a froze/aborted freeze outcome to the gate's answer (or throw on an unexpected abort). */
+    resolveFreezeAnswer(outcome, key) {
+        if (outcome.kind !== "wake") {
+            throw new AppError(ErrorCode.INTERNAL_ERROR, `Freeze wait for a human-input gate ended unexpectedly (${outcome.kind})`, { kind: "unexpected_freeze_outcome", key });
+        }
+        return normalizeHumanInputResult(this.gateAnswer(outcome.wake, key));
+    }
     /** The wake's answer for one gate key. A wake whose value is missing the parked gate means the
      *  control plane and the snapshot disagree about what this run was waiting for — a platform bug,
      *  failed loudly, never a retry. */
@@ -172,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",
@@ -256,12 +325,7 @@ export class WorkerWorkflowHost {
         };
         const freeze = this.deps.freeze;
         if (freeze !== undefined) {
-            // Snapshot substrate: park in place; the wake carries the validated answer.
-            const outcome = await this.freezeWait(freeze, signal);
-            if (outcome.kind !== "wake") {
-                throw new AppError(ErrorCode.INTERNAL_ERROR, "Suspend aborted surfaced to a human-input seam (the coordinator retries these)", { kind: "unexpected_abort", seq });
-            }
-            return normalizeHumanInputResult(this.gateAnswer(outcome.wake, key));
+            return await this.freezeHumanInput(freeze, signal, key);
         }
         return this.suspend(signal);
     }
@@ -399,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/native/reseed.c

@@ -0,0 +1,52 @@
+/*
+ * bw_reseed — the clause-3 userspace-CSPRNG reseed (SNAPSHOT_UNIQUENESS_CONTRACT).
+ *
+ * A memory snapshot freezes OpenSSL's DRBG state, so two clones of one base snapshot hand every
+ * run byte-identical `crypto.*` output. The kernel CSPRNG diverges across clones (VMGenID), but
+ * that reseed never reaches OpenSSL. A pure-JS monkeypatch was proven insufficient (named ESM
+ * imports of node:crypto bypass it), so this native step reseeds OpenSSL's DRBG UNDERNEATH every
+ * caller — the only robust fix.
+ *
+ * OpenSSL 3 DRBG chain: the primary DRBG seeds from the OS entropy source; the public + private
+ * DRBGs (what RAND_bytes / Node crypto actually draw from) seed from the primary. We reseed the
+ * primary first (pulling the now-diverged OS entropy) then the public + private so the fresh
+ * entropy propagates immediately, and call RAND_poll() as a belt. Everything is guarded on NULL so
+ * a non-default RAND provider degrades to whatever succeeded rather than crashing.
+ *
+ * Symbols (RAND_get0_*, EVP_RAND_reseed, RAND_poll) come from the OpenSSL that Node links; on a
+ * Node build that does not export them the addon fails to load and the JS layer no-ops with a warn
+ * (uniqueness_reseed.ts). Linux-only in practice (the snapshot substrate is Linux microVMs).
+ */
+#include <node_api.h>
+#include <openssl/rand.h>
+#include <openssl/evp.h>
+
+static int reseed_ctx(EVP_RAND_CTX *ctx) {
+  if (ctx == NULL) return 1; /* absent layer: nothing to do, not a failure */
+  return EVP_RAND_reseed(ctx, /*prediction_resistance=*/0, NULL, 0, NULL, 0);
+}
+
+static napi_value Reseed(napi_env env, napi_callback_info info) {
+  int ok = 1;
+  /* Reseed the primary FIRST (it pulls fresh OS entropy), then the layers that serve draws. */
+  if (!reseed_ctx(RAND_get0_primary(NULL))) ok = 0;
+  if (!reseed_ctx(RAND_get0_public(NULL))) ok = 0;
+  if (!reseed_ctx(RAND_get0_private(NULL))) ok = 0;
+  /* Legacy belt: also nudge the default method's entropy pool. */
+  RAND_poll();
+
+  napi_value result;
+  napi_get_boolean(env, ok ? true : false, &result);
+  return result;
+}
+
+static napi_value Init(napi_env env, napi_value exports) {
+  napi_value fn;
+  if (napi_create_function(env, "reseed", NAPI_AUTO_LENGTH, Reseed, NULL, &fn) != napi_ok) {
+    return exports;
+  }
+  napi_set_named_property(env, exports, "reseed", fn);
+  return exports;
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -37,7 +37,10 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "native",
+    "binding.gyp",
+    "prebuilds"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -46,19 +49,24 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "vitest run --coverage",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "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",
-    "tar": "^7.5.16"
+    "@boardwalk-labs/engine": "^0.1.31",
+    "@boardwalk-labs/workflow": "^0.1.23",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "node-gyp-build": "^4.8.4",
+    "tar": "^7.5.16",
+    "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",