@boardwalk-labs/runner 0.1.17 → 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/index.js

@@ -49,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";
@@ -130,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

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.17",
+  "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": {