@boardwalk-labs/runner 0.1.16 → 0.1.18

package/dist/runtime/browser_session_backend.js

@@ -162,7 +162,12 @@ export function makeGuestBrowserBackend(cfg) {
                 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);
+                // Probe the EXACT url the program's client will connect to (the `localhost` form), not a
+                // `127.0.0.1` stand-in: if `localhost` doesn't resolve in the guest, connectSessionMcp would
+                // otherwise throw a bare `TypeError: fetch failed` while this readiness check passed on a
+                // different address (masking the fault). Probing mcpUrl turns that into a diagnosable
+                // `browser_backend_timeout`. (The guest ships /etc/hosts mapping localhost → 127.0.0.1.)
+                await waitForHttp(mcpUrl, cfg.readyTimeoutMs);
                 let killed = false;
                 return {
                     cdpUrl,

package/dist/runtime/http_pool_reset.d.ts

@@ -0,0 +1,4 @@
+/** Discard the global HTTP connection pool so post-restore requests open fresh sockets. Never
+ *  throws (a wake must not fail on pool hygiene) and never blocks (the dead pool drains in the
+ *  background). Returns true if the dispatcher was swapped. */
+export declare function resetHttpConnectionPool(): boolean;

package/dist/runtime/http_pool_reset.js

@@ -0,0 +1,49 @@
+// Reset the global HTTP connection pool after a snapshot restore.
+//
+// The North Star substrate freezes the whole VM (memory + every socket) and restores it later,
+// possibly minutes or days on. Keep-alive TCP sockets do NOT survive that: undici pools them, but
+// on restore the frozen socket state is stale and the peer — the per-host egress proxy (a CONNECT
+// tunnel) and, through it, the broker — long since closed its end. undici would REUSE such a socket
+// for the next request, which then hangs (no bytes flow, no RST arrives on a half-dead tunnel) until
+// the control client's 30s AbortSignal.timeout fires and aborts it. On a woken run's FIRST broker
+// call (finalize) that abort crashes the run — the "socket is dead but never reset" gap the control
+// client's timeout only papered over (see runner_control_client.ts).
+//
+// The fix is to discard the dead pool on resume. Swapping in a fresh EnvHttpProxyAgent — which
+// re-reads the unchanged HTTP(S)_PROXY env, so proxying is preserved — means every post-wake request
+// opens a NEW socket instead of reusing a frozen one. Node's global `fetch` reads the same global
+// dispatcher, so this covers the control client, inference, artifacts, and any author fetch alike.
+import { EnvHttpProxyAgent, getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { createLogger } from "./support/index.js";
+const log = createLogger("http_pool_reset");
+/** Discard the global HTTP connection pool so post-restore requests open fresh sockets. Never
+ *  throws (a wake must not fail on pool hygiene) and never blocks (the dead pool drains in the
+ *  background). Returns true if the dispatcher was swapped. */
+export function resetHttpConnectionPool() {
+    try {
+        const prev = getGlobalDispatcher();
+        setGlobalDispatcher(new EnvHttpProxyAgent());
+        // Drain the old pool's dead sockets in the background; never block the wake on it.
+        const drain = async () => {
+            try {
+                await prev?.close?.();
+            }
+            catch {
+                try {
+                    await prev?.destroy?.(new Error("http pool reset on wake"));
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        };
+        void drain();
+        return true;
+    }
+    catch (err) {
+        log.warn("http_pool_reset_failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return false;
+    }
+}

package/dist/runtime/index.js

@@ -38,6 +38,7 @@ import { parseByoProviders } from "./direct_inference.js";
 import { applyIdentityToEnv, connectIdentityRelayFd, relayFdFromEnv, workerDiagnostics, } from "./identity_relay.js";
 import { FreezeCoordinator } from "./freeze_coordinator.js";
 import { reseedUserspaceCsprng } from "./uniqueness_reseed.js";
+import { resetHttpConnectionPool } from "./http_pool_reset.js";
 import { WorkerWorkflowHost } from "./workflow_host.js";
 import { BrowserSessionManager } from "./browser_session.js";
 import { loadGuestBrowserConfig, makeGuestBrowserBackend, connectSessionMcp, } from "./browser_session_backend.js";
@@ -48,6 +49,7 @@ import { RunnerControlClient } from "./runner_control_client.js";
 import { BrokerChildDispatcher } from "./broker_child_dispatcher.js";
 import { BrokerEventPublisher } from "./broker_event_publisher.js";
 import { createProgramLogSink } from "./program_log_capture.js";
+import { makeRunLogFileSink } from "./run_log_file_sink.js";
 import { BrokerArtifactStore } from "./broker_artifact_store.js";
 import { buildBrokerToolHost } from "./broker_tool_host.js";
 import { CreditWatcher } from "./credit_watcher.js";
@@ -129,7 +131,18 @@ export function assembleWorkerDeps(runtime) {
     // declared output, and every agent turn stamp through this emitter, so cursors are run-globally
     // monotonic with no separate program band. Frames publish as `{cursor, event}` rows via the
     // broker telemetry path. The claim wrapper below bumps it past a previous session's frames.
-    const runEvents = new WorkerRunEventEmitter({ runId: runtime.runId, publisher: eventPublisher });
+    // Optional on-screen mirror: append the (already-redacted) event stream to a local file an xterm in
+    // the ambient desktop tails, so the live-view/recording shows the run working. Opt-in via the env the
+    // desktop guest image sets (BOARDWALK_RUN_LOG_FILE); absent everywhere else, so no cost off-desktop.
+    const runLogFilePath = process.env.BOARDWALK_RUN_LOG_FILE?.trim();
+    const runLogLocalSink = runLogFilePath !== undefined && runLogFilePath !== ""
+        ? makeRunLogFileSink(runLogFilePath)
+        : undefined;
+    const runEvents = new WorkerRunEventEmitter({
+        runId: runtime.runId,
+        publisher: eventPublisher,
+        ...(runLogLocalSink !== undefined ? { localSink: runLogLocalSink } : {}),
+    });
     const phaseTracker = new PhaseTracker({ sink: runEvents });
     // The run's public-API credential (was BOARDWALK_API_KEY). It is NO LONGER in process.env — the
     // bootstrap captured + scrubbed it (capturePlatformContext) so the agent's bash / subprocesses
@@ -393,6 +406,10 @@ export function assembleWorkerDeps(runtime) {
                 // BEFORE the seam resolves, so no woken author code draws from the stale (pre-suspend) DRBG.
                 onAfterWake: (wake) => {
                     reseedUserspaceCsprng();
+                    // Keep-alive sockets (to the egress proxy + through it to the broker) do NOT survive the
+                    // freeze; discard the connection pool so the first post-wake broker call (finalize) opens a
+                    // fresh socket instead of hanging on a stale one until its 30s timeout crashes the run.
+                    resetHttpConnectionPool();
                     broker.swapRunToken(wake.run_token);
                     redactor.record(wake.run_token);
                     if (wake.api_token !== undefined && wake.api_token !== "") {

package/dist/runtime/run_event_emitter.d.ts

@@ -6,11 +6,16 @@ export interface RunEventEmitterOptions {
     resumeAfterCursor?: number;
     /** Injected clock for deterministic tests. Defaults to Date.now. */
     now?: () => number;
+    /** Optional local mirror of every (already-redacted) event — used to surface the run's output in an
+     *  on-screen terminal in the ambient desktop (docs/SCREEN_CAPTURE.md). Best-effort: a sink throw never
+     *  affects the run or the broker publish. Only fed events that already passed the run's redactor. */
+    localSink?: (event: RunEvent) => void;
 }
 export declare class WorkerRunEventEmitter {
     private readonly runId;
     private readonly publisher;
     private readonly now;
+    private readonly localSink;
     private turn;
     private seq;
     constructor(opts: RunEventEmitterOptions);

package/dist/runtime/run_event_emitter.js

@@ -20,12 +20,14 @@ export class WorkerRunEventEmitter {
     runId;
     publisher;
     now;
+    localSink;
     turn;
     seq;
     constructor(opts) {
         this.runId = opts.runId;
         this.publisher = opts.publisher;
         this.now = opts.now ?? Date.now;
+        this.localSink = opts.localSink;
         const max = opts.resumeAfterCursor ?? 0;
         this.turn = max > 0 ? Math.floor(max / TURN_CURSOR_STRIDE) + 1 : 0;
         this.seq = 0;
@@ -44,6 +46,14 @@ export class WorkerRunEventEmitter {
         this.publisher
             .publish(`run:${this.runId}`, JSON.stringify({ cursor, event }))
             .catch(() => undefined); // best-effort; the publisher logs its own failures
+        if (this.localSink !== undefined) {
+            try {
+                this.localSink(event); // best-effort on-screen mirror; must never affect the run
+            }
+            catch {
+                /* ignore */
+            }
+        }
         return event;
     }
     /** Restart resume: jump past the previous session's frames (claim carries the store max). */

package/dist/runtime/run_log_file_sink.d.ts

@@ -0,0 +1,9 @@
+import type { RunEvent } from "./agent/events.js";
+/** One readable, ANSI-colored line for a run event, or null to skip it (streaming text/reasoning
+ *  deltas are buffered by the sink, not formatted here). Reads only a few fields off the SDK's typed
+ *  event and degrades gracefully on anything unexpected. */
+export declare function formatRunEventLine(event: RunEvent): string | null;
+/** Build the {@link WorkerRunEventEmitter} local sink: append formatted lines to `path`, buffering
+ *  streaming agent text/reasoning into whole lines. Best-effort — a broken stream (full disk, closed
+ *  pipe) is swallowed and disables the sink; it never throws into the run. */
+export declare function makeRunLogFileSink(path: string): (event: RunEvent) => void;

package/dist/runtime/run_log_file_sink.js

@@ -0,0 +1,106 @@
+// On-screen run-output mirror. Formats the run's (already-redacted) event stream into readable,
+// ANSI-colored lines appended to a local file, which an xterm in the ambient desktop tails so the
+// live-view / recording shows the run working (docs/SCREEN_CAPTURE.md). Gated on
+// BOARDWALK_RUN_LOG_FILE — the desktop guest image sets it. This ONLY ever sees events that already
+// passed the run's redactor (the same stream the web run-detail renders), so the file is safe to
+// capture in a durable recording.
+import { createWriteStream } from "node:fs";
+function oneLine(s, n) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > n ? t.slice(0, n - 1) + "…" : t;
+}
+function safeJson(v) {
+    try {
+        return typeof v === "string" ? v : JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/** One readable, ANSI-colored line for a run event, or null to skip it (streaming text/reasoning
+ *  deltas are buffered by the sink, not formatted here). Reads only a few fields off the SDK's typed
+ *  event and degrades gracefully on anything unexpected. */
+export function formatRunEventLine(event) {
+    const e = event;
+    const k = typeof e.kind === "string" ? e.kind : "";
+    const s = (v) => (typeof v === "string" ? v : "");
+    switch (k) {
+        case "run_status":
+            return `\x1b[1;32m● ${s(e.status)}\x1b[0m`;
+        case "phase":
+            return `\x1b[1;36m▸ ${s(e.name)}\x1b[0m`;
+        case "program_output": {
+            const t = s(e.text).replace(/\s+$/, "");
+            return t ? `  ${t}` : null;
+        }
+        case "turn_started":
+            return `\x1b[35m· agent ${s(e.agentName) || s(e.agentId)}\x1b[0m`;
+        case "tool_call_start":
+            return `  \x1b[33m⚙ ${s(e.toolName)}\x1b[0m`;
+        case "tool_output_delta": {
+            const t = s(e.text).replace(/\s+$/, "");
+            return t ? `    \x1b[90m${oneLine(t, 200)}\x1b[0m` : null;
+        }
+        case "tool_call_result":
+            return `  \x1b[32m✓ done\x1b[0m`;
+        case "tool_call_error":
+            return `  \x1b[31m✗ tool error\x1b[0m`;
+        case "output":
+            return `\x1b[1;32m✔ output  ${oneLine(safeJson(e.value), 300)}\x1b[0m`;
+        case "human_input_requested":
+            return `\x1b[1;33m⏸ awaiting human input\x1b[0m`;
+        case "human_input_resolved":
+            return `\x1b[33m▶ input received\x1b[0m`;
+        case "suspended":
+            return `\x1b[90m⏸ suspended\x1b[0m`;
+        case "resumed":
+            return `\x1b[90m▶ resumed\x1b[0m`;
+        case "egress_denied":
+            return `  \x1b[31m⛔ egress denied\x1b[0m`;
+        default:
+            return null; // turn_ended, text_*, tool_call_input_*, tool_call_executing — noise for the terminal
+    }
+}
+/** Build the {@link WorkerRunEventEmitter} local sink: append formatted lines to `path`, buffering
+ *  streaming agent text/reasoning into whole lines. Best-effort — a broken stream (full disk, closed
+ *  pipe) is swallowed and disables the sink; it never throws into the run. */
+export function makeRunLogFileSink(path) {
+    let stream = null;
+    try {
+        stream = createWriteStream(path, { flags: "a" });
+        stream.on("error", () => {
+            stream = null;
+        });
+        stream.write("\n\x1b[1;36m── boardwalk run ──\x1b[0m\n");
+    }
+    catch {
+        stream = null;
+    }
+    let textBuf = "";
+    const flushText = () => {
+        if (textBuf.trim() !== "" && stream !== null) {
+            stream.write(`  \x1b[37m${oneLine(textBuf, 2000)}\x1b[0m\n`);
+        }
+        textBuf = "";
+    };
+    return (event) => {
+        if (stream === null)
+            return;
+        const e = event;
+        const k = typeof e.kind === "string" ? e.kind : "";
+        if (k === "text_delta" || k === "reasoning_delta") {
+            textBuf += typeof e.text === "string" ? e.text : "";
+            return;
+        }
+        if (k === "text_start")
+            return;
+        if (k === "text_end") {
+            flushText();
+            return;
+        }
+        flushText(); // a non-text event ends any in-flight text line
+        const line = formatRunEventLine(event);
+        if (line !== null)
+            stream.write(line + "\n");
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/runner",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Boardwalk self-hosted runner: execute cloud-scheduled runs on your own machines. Currently: the canonical runner contract types.",
   "license": "Apache-2.0",
   "repository": {
@@ -58,6 +58,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "node-gyp-build": "^4.8.4",
     "tar": "^7.5.16",
+    "undici": "^6.27.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {