@runuai/host 0.4.2 → 0.5.0

package/lib/agents/transport.ts

@@ -0,0 +1,229 @@
+/**
+ * Agent transport selection (ADR-061). Adapters call createAgentTransport()
+ * where they used to build a LineProcess directly; it returns either:
+ *
+ *  - legacy pipes (`docker exec -i <cli>`, LineProcess) when
+ *    UAI_DURABLE_SESSIONS=0, or
+ *  - the durable path: an in-container runner owning the CLI, driven through
+ *    inbox/outbox files on the workspace mount (DurableProcess).
+ *
+ * Durable mode makes host restarts transparent WITHOUT orchestrator
+ * changes: the orchestrator's lazy respawn calls factory.create as always,
+ * and this helper quietly ATTACHES to a still-live runner (fresh heartbeat +
+ * a `running` host_agent_sessions row) at the persisted outbox offset
+ * instead of spawning a new CLI — the agent's in-memory context survives.
+ * Adapters that re-handshake per process (codex) pass allowAttach:false and
+ * get a fresh runner each create — the stale predecessor is asked to stop
+ * via its inbox first.
+ *
+ * The runner script is COPIED into each session dir (not bind-mounted):
+ * every existing container already sees the workspace at its identical host
+ * path, so durable sessions work for containers created before this
+ * feature, and each spawn ships the runner version matching this host.
+ */
+
+import { copyFileSync, mkdirSync, statSync, promises as fsp } from "node:fs";
+import { join } from "node:path";
+
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../db";
+import { taskWorkspaceDir } from "../env";
+import { DurableProcess, runnerScriptPath } from "./durable-proc";
+import { LineProcess, dockerExecArgs, type ExitHandler, type LineHandler } from "./proc";
+
+/** The shared surface adapters program against (LineProcess's shape). */
+export interface LineTransport {
+  onLine(handler: LineHandler): void;
+  onExit(handler: ExitHandler): void;
+  writeLine(value: unknown): void;
+  readonly stderrTail: string;
+  readonly isClosed: boolean;
+  close(): Promise<void>;
+}
+
+export interface AgentTransportOptions {
+  taskId: string;
+  agentId: string;
+  containerName: string;
+  /** CLI + args exactly as they'd follow `docker exec -i <container>`. */
+  cli: string;
+  cliArgs: string[];
+  /** Env names forwarded from the host's own env (`-e NAME`). */
+  passEnv?: string[];
+  /** Explicit per-exec env values (`-e NAME=value`). */
+  explicitEnv?: Record<string, string>;
+  /**
+   * Whether a live runner from a previous host process may be attached to.
+   * True for stateless adapters (claude); false for ones whose host-side
+   * protocol state can't outlive the host process (codex handshake).
+   */
+  allowAttach: boolean;
+  kind: string;
+  debugLabel?: string;
+}
+
+/** Runner heartbeat is 5 s; older than this = not attachable. */
+const ATTACH_HEARTBEAT_FRESH_MS = 20_000;
+
+function durableEnabled(): boolean {
+  return process.env.UAI_DURABLE_SESSIONS !== "0";
+}
+
+export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
+  if (!durableEnabled()) {
+    const { command, args } = dockerExecArgs(
+      opts.containerName,
+      opts.cli,
+      opts.cliArgs,
+      opts.passEnv ?? [],
+      opts.explicitEnv ?? {},
+    );
+    return new LineProcess({ command, args, debugLabel: opts.debugLabel });
+  }
+
+  const db = getDb();
+  const row = db
+    .select()
+    .from(schema.hostAgentSessions)
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, opts.taskId),
+        eq(schema.hostAgentSessions.agentId, opts.agentId),
+      ),
+    )
+    .get();
+
+  const persistOffset = (offset: number): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ outboxOffset: offset, updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+  const markClosed = (): void => {
+    db.update(schema.hostAgentSessions)
+      .set({ status: "closed", updatedAt: Date.now() })
+      .where(
+        and(
+          eq(schema.hostAgentSessions.taskId, opts.taskId),
+          eq(schema.hostAgentSessions.agentId, opts.agentId),
+        ),
+      )
+      .run();
+  };
+
+  // ---- Attach: a previous host process left this agent's runner alive. ----
+  if (opts.allowAttach && row && row.status === "running" && heartbeatFresh(row.sessionDir)) {
+    const proc = new DurableProcess({
+      hostSessionDir: row.sessionDir,
+      initialOutboxOffset: row.outboxOffset,
+      onOffsetAdvance: persistOffset,
+      onCloseRequested: markClosed,
+      debugLabel: opts.debugLabel,
+    });
+    proc.onExit(markClosed);
+    return proc;
+  }
+
+  // ---- Spawn a fresh runner, asking any predecessor to stop. --------------
+  // Unconditional (not gated on row.status): a runner falsely marked closed
+  // by a stale-heartbeat verdict may still be alive, and a stop appended to
+  // a dead session's inbox is harmless — this is what guarantees one live
+  // CLI per (task, agent).
+  if (row) {
+    void fsp
+      .appendFile(join(row.sessionDir, "inbox.jsonl"), '{"__uai":"stop"}\n')
+      .catch(() => {
+        // Dir already gone / runner already dead — nothing to stop.
+      });
+  }
+
+  const sessionDir = join(
+    taskWorkspaceDir(opts.taskId),
+    ".uai",
+    "sessions",
+    opts.agentId,
+    String(Date.now()),
+  );
+  mkdirSync(sessionDir, { recursive: true });
+  // Ship this host's runner with the session: works in containers created
+  // before this feature (the workspace is mounted at its host path) and
+  // never skews against the host version.
+  const runnerInSession = join(sessionDir, "runner.mjs");
+  copyFileSync(runnerScriptPath(), runnerInSession);
+
+  const envArgs: string[] = [];
+  for (const name of opts.passEnv ?? []) {
+    if (process.env[name]) envArgs.push("-e", name);
+  }
+  for (const [name, value] of Object.entries(opts.explicitEnv ?? {})) {
+    envArgs.push("-e", `${name}=${value}`);
+  }
+
+  const proc = new DurableProcess({
+    hostSessionDir: sessionDir,
+    onOffsetAdvance: persistOffset,
+    onCloseRequested: markClosed,
+    debugLabel: opts.debugLabel,
+    spawnCommand: {
+      command: "docker",
+      args: [
+        "exec",
+        "-d",
+        ...envArgs,
+        opts.containerName,
+        "node",
+        runnerInSession, // identical path in-container (workspace self-mount)
+        sessionDir,
+        "--",
+        opts.cli,
+        ...opts.cliArgs,
+      ],
+    },
+  });
+
+  const now = Date.now();
+  db.insert(schema.hostAgentSessions)
+    .values({
+      taskId: opts.taskId,
+      agentId: opts.agentId,
+      sessionDir,
+      containerName: opts.containerName,
+      kind: opts.kind,
+      outboxOffset: 0,
+      status: "running",
+      createdAt: now,
+      updatedAt: now,
+    })
+    .onConflictDoUpdate({
+      target: [schema.hostAgentSessions.taskId, schema.hostAgentSessions.agentId],
+      set: {
+        sessionDir,
+        containerName: opts.containerName,
+        kind: opts.kind,
+        outboxOffset: 0,
+        status: "running",
+        updatedAt: now,
+      },
+    })
+    .run();
+
+  proc.onExit(markClosed);
+  return proc;
+}
+
+function heartbeatFresh(sessionDir: string): boolean {
+  try {
+    return (
+      Date.now() - statSync(join(sessionDir, "heartbeat")).mtimeMs <
+      ATTACH_HEARTBEAT_FRESH_MS
+    );
+  } catch {
+    return false;
+  }
+}

package/lib/browser-testing.ts

@@ -0,0 +1,235 @@
+/**
+ * ADR-053: in-container browser for agents — Playwright MCP wiring.
+ *
+ * When a task's project opted into browser testing, session start calls
+ * `setupBrowserTesting`, which (idempotently, via a versioned marker file)
+ * writes the MCP config for BOTH engines and kicks the installs in the
+ * background:
+ *
+ *   - `/workspace/.mcp.json` — Claude Code's project-scoped MCP config,
+ *     declaring the `browser` server (headFUL on DISPLAY :99).
+ *   - `/workspace/.claude/settings.json` — `enableAllProjectMcpServers` so
+ *     headless sessions load it without an approval prompt.
+ *   - `~/.codex/config.toml` — an `[mcp_servers.browser]` block (appended
+ *     once; the task owns a private copy of this file).
+ *
+ * Phase 2 (the WATCHABLE browser): Chromium runs headful under Xvfb (:99),
+ * mirrored by x11vnc → websockify/noVNC on container port 6080 — which the
+ * cloud surfaces as the synthetic "browser" preview, so the human can watch
+ * the agents click around from the preview menu. The viewer stack is
+ * (re)started on every setup call, pgrep-guarded, so it survives container
+ * restarts.
+ *
+ * Browser binaries land on the host-wide `uai-playwright` volume
+ * (PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers, mounted by the generated
+ * compose) so Chromium downloads once per HOST. Everything here is
+ * best-effort and never blocks session start.
+ *
+ * Hard-won asdf rules (2026-07-07): npx resolves ONLY where a .tool-versions
+ * applies → always `-w /workspace`; and root has no ~/.tool-versions →
+ * root execs also need `-e HOME=/home/node`.
+ */
+import { dockerCli } from "./docker-exec";
+
+// v3: self-sufficient MCP launcher + loop-wrapped viewer daemons. Bumping
+// re-runs setup on live channels; config writes stay `[ -f ] ||`-guarded so
+// a task keeps the configs it started with.
+const MARKER = "/workspace/.uai/.browser-mcp-ready-v3";
+
+const SERVER_DISPLAY = ":99";
+const XVFB_CMD = `Xvfb ${SERVER_DISPLAY} -screen 0 1440x900x24 -nolisten tcp`;
+
+/**
+ * The MCP server launcher — self-sufficient by design (learned live: a
+ * session that spawns while the apt installs are still running got a DEAD
+ * mcp server, and the agent had to improvise). It ensures its own display
+ * when Xvfb exists (headful → watchable), and falls back to a HEADLESS
+ * browser while the viewer packages are still installing — the agent always
+ * gets working tools. `sh -lc` + cd /workspace for the asdf shims. No
+ * single quotes in here: it's embedded in single-quoted JSON/TOML strings.
+ */
+// X's own lockfile is the display-up signal — no pgrep (pgrep -f guards
+// self-matched their launcher's cmdline and skipped every start; found
+// live 2026-07-08), and it also detects displays an AGENT started itself.
+const X_LOCK = `/tmp/.X${SERVER_DISPLAY.slice(1)}-lock`;
+
+const SERVER_LAUNCHER =
+  `cd /workspace; ` +
+  `if command -v Xvfb >/dev/null 2>&1; then ` +
+  `[ -e ${X_LOCK} ] || (nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+  `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+  `exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox; ` +
+  `else ` +
+  `exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox --headless; ` +
+  `fi`;
+
+const SERVER_COMMAND = "sh";
+const SERVER_ARGS = ["-lc", SERVER_LAUNCHER];
+
+const MCP_JSON = JSON.stringify(
+  {
+    mcpServers: {
+      browser: { command: SERVER_COMMAND, args: SERVER_ARGS },
+    },
+  },
+  null,
+  2,
+);
+
+const CLAUDE_SETTINGS_JSON = JSON.stringify(
+  { enableAllProjectMcpServers: true },
+  null,
+  2,
+);
+
+const CODEX_TOML = [
+  "",
+  "# uai ADR-053: in-container browser (Playwright MCP)",
+  "[mcp_servers.browser]",
+  `command = '${SERVER_COMMAND}'`,
+  `args = [${SERVER_ARGS.map((a) => `'${a}'`).join(", ")}]`,
+  "",
+].join("\n");
+
+/**
+ * Start the watchable-browser stack (Xvfb → x11vnc → noVNC on :6080) if its
+ * binaries are installed and it isn't already up. x11vnc and websockify run
+ * under tiny restart loops — x11vnc EXITS whenever the X server it watches
+ * isn't up yet (the race that killed the first live run), and the loops
+ * also reattach after the display owner changes. Safe to run repeatedly:
+ * every piece is pgrep-guarded, including the loops themselves.
+ */
+/**
+ * The viewer daemons, one docker-exec each (the single-line nohup shape is
+ * the only one that reliably survives `docker exec -d`). Guards use the X
+ * lockfile and PIDFILES — never pgrep: a pgrep -f guard sharing a cmdline
+ * with its own payload self-matches and skips the start (this exact bug
+ * kept the stack down in every container until 2026-07-08).
+ */
+const VIEWER_STEPS: string[] = [
+  // Xvfb — one-shot; the X lockfile is the truth (also set when an agent
+  // started the display itself). If it dies the lock clears and the next
+  // session ensure relaunches it.
+  `command -v Xvfb >/dev/null 2>&1 || exit 0; [ -e ${X_LOCK} ] || nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &`,
+  // x11vnc under a restart loop (it exits whenever the X server isn't up
+  // yet). Pidfile-guarded.
+  `command -v x11vnc >/dev/null 2>&1 || exit 0; [ -f /tmp/uai-x11vnc.pid ] && kill -0 "$(cat /tmp/uai-x11vnc.pid)" 2>/dev/null && exit 0; nohup sh -c 'echo $$ > /tmp/uai-x11vnc.pid; while true; do x11vnc -display ${SERVER_DISPLAY} -forever -shared -nopw -quiet >>/tmp/uai-x11vnc.log 2>&1; sleep 2; done' >/dev/null 2>&1 &`,
+  // websockify/noVNC under the same pattern.
+  `command -v websockify >/dev/null 2>&1 || exit 0; [ -f /tmp/uai-novnc.pid ] && kill -0 "$(cat /tmp/uai-novnc.pid)" 2>/dev/null && exit 0; nohup sh -c 'echo $$ > /tmp/uai-novnc.pid; while true; do websockify --web=/usr/share/novnc 0.0.0.0:6080 localhost:5900 >>/tmp/uai-websockify.log 2>&1; sleep 2; done' >/dev/null 2>&1 &`,
+];
+
+export async function setupBrowserTesting(
+  taskId: string,
+  containerName: string,
+  hasCodex: boolean,
+): Promise<void> {
+  try {
+    // The viewer stack restarts whenever it died (container restart, crash) —
+    // outside the marker guard on purpose. No-op until its packages install.
+    // ONE exec per daemon: the single-line nohup shape is the only one that
+    // reliably survives `docker exec -d`.
+    for (const step of VIEWER_STEPS) {
+      await dockerCli(["exec", "-d", containerName, "sh", "-c", step], {
+        timeoutMs: 10_000,
+      });
+    }
+
+    const marked = await dockerCli(
+      ["exec", containerName, "test", "-f", MARKER],
+      { timeoutMs: 5_000 },
+    );
+    if (marked.status === 0) return;
+
+    const script = [
+      "set -e",
+      "mkdir -p /workspace/.uai /workspace/.claude",
+      // Claude: project-scoped MCP config + auto-approve setting. The
+      // workspace is fresh per task, so plain writes are safe; keep them
+      // conditional anyway so a human's later edits survive re-runs.
+      `[ -f /workspace/.mcp.json ] || printf '%s\\n' ${shellQuote(MCP_JSON)} > /workspace/.mcp.json`,
+      `[ -f /workspace/.claude/settings.json ] || printf '%s\\n' ${shellQuote(CLAUDE_SETTINGS_JSON)} > /workspace/.claude/settings.json`,
+      ...(hasCodex
+        ? [
+            // Codex: append once to the task's PRIVATE config copy.
+            `grep -q "mcp_servers.browser" /home/node/.codex/config.toml 2>/dev/null || printf '%s' ${shellQuote(CODEX_TOML)} >> /home/node/.codex/config.toml`,
+          ]
+        : []),
+      `touch ${MARKER}`,
+    ].join(" && ");
+
+    const wrote = await dockerCli(
+      ["exec", containerName, "sh", "-lc", script],
+      { timeoutMs: 20_000 },
+    );
+    if (wrote.status !== 0) {
+      console.warn(
+        `[browser] task ${taskId}: MCP config write failed: ${wrote.stderr.slice(0, 300)}`,
+      );
+      return;
+    }
+
+    // Volume ownership, then the browser download as NODE (host-wide
+    // one-timer on the shared volume).
+    await dockerCli(
+      ["exec", "-u", "root", containerName, "chown", "node:node", "/opt/pw-browsers"],
+      { timeoutMs: 5_000 },
+    );
+    await dockerCli(
+      [
+        "exec",
+        "-d",
+        "-w",
+        "/workspace",
+        containerName,
+        "sh",
+        "-lc",
+        "npx -y playwright@latest install chromium >/tmp/uai-pw-browser.log 2>&1 || true",
+      ],
+      { timeoutMs: 10_000 },
+    );
+    // Chromium apt libs + the viewer stack packages, then start the stack —
+    // one ordered root chain, backgrounded, per-container.
+    await dockerCli(
+      [
+        "exec",
+        "-d",
+        "-u",
+        "root",
+        // HOME=/home/node is for asdf version resolution ONLY — without the
+        // cache redirect below, root's npx writes ROOT-OWNED entries into
+        // node's ~/.npm and breaks the node user's own npx (which launches
+        // the MCP server). Found live 2026-07-08.
+        "-e",
+        "HOME=/home/node",
+        "-e",
+        "npm_config_cache=/tmp/uai-root-npm-cache",
+        "-w",
+        "/workspace",
+        containerName,
+        "sh",
+        "-lc",
+        "{ npx -y playwright@latest install-deps chromium && " +
+          "apt-get install -y --no-install-recommends xvfb x11vnc novnc websockify && " +
+          // Older-image containers get their packages only HERE (post-apt),
+          // so kick the viewer daemons now. Each step subshelled: the steps'
+          // internal `exit 0` guards must not abort their siblings.
+          `su -s /bin/sh node -c '${VIEWER_STEPS.map((s) => `( ${s} )`)
+            .join("; ")
+            .replace(/'/g, `'\\''`)}'; ` +
+          // Heal any damage a pre-fix host already did to the cache.
+          "chown -R node:node /home/node/.npm 2>/dev/null; } " +
+          ">/tmp/uai-pw-deps.log 2>&1 || true",
+      ],
+      { timeoutMs: 10_000 },
+    );
+    console.log(`[browser] task ${taskId}: Playwright MCP wired (installs backgrounded)`);
+  } catch (err) {
+    // Best-effort by design — a task without a browser still runs.
+    console.warn(`[browser] task ${taskId}: setup failed`, err);
+  }
+}
+
+/** Single-quote for `sh -c` (POSIX-safe). */
+function shellQuote(text: string): string {
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}