@polderlabs/bizar 5.6.0-beta.7 → 5.6.0-beta.8

package/cli/agent-browser-update.mjs

@@ -0,0 +1,322 @@
+/**
+ * cli/agent-browser-update.mjs
+ *
+ * v6.0.0 — Install / update / verify the `agent-browser` CLI.
+ *
+ * `agent-browser` is a native Rust CLI from vercel-labs (~38K★) that
+ * gives Bizar agents a complete browser-automation surface:
+ *   - 100+ typed CLI commands (open, snapshot, click, fill, screenshot, ...)
+ *   - Native MCP stdio server (`agent-browser mcp`)
+ *   - Self-healing snapshot-based element refs (`@e2`)
+ *   - Plugin system (vault, recorder, ...)
+ *   - Vercel AI SDK + AI Gateway integration
+ *
+ * This module is the single source of truth for installing and
+ * updating `agent-browser`. It is used by:
+ *   - cli/install.mjs (during `bizar install`)
+ *   - cli/provision.mjs (during `bizar update`)
+ *   - cli/agent-browser-up.sh (the bash idempotent starter; on first
+ *     run it shells to `npm install -g agent-browser` if the binary
+ *     is missing — this module is the rich equivalent)
+ *
+ * Public API:
+ *   detectState()       probe what's installed without modifying
+ *   install(opts)       install + download Chrome for Testing
+ *   update(opts)        upgrade to the latest version
+ *   ensureRunning()     bring the daemon up if it's down
+ *   printStatus()       one-line status for the user
+ *
+ * All functions are idempotent and safe to re-run.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+
+const DEFAULT_DAEMON_PORT = 9223;
+const DEFAULT_PROFILE_DIR = join(homedir(), '.agent-browser', 'profile');
+
+// ── detection ──────────────────────────────────────────────────────────
+
+/**
+ * Probe the current agent-browser install without modifying anything.
+ *
+ * Returns a structured state object:
+ *   {
+ *     installed: boolean,
+ *     version: string | null,
+ *     chromeReady: boolean,
+ *     daemonRunning: boolean,
+ *     profileDir: string,
+ *     daemonPort: number,
+ *   }
+ */
+export function detectState() {
+  const state = {
+    installed: false,
+    version: null,
+    chromeReady: false,
+    daemonRunning: false,
+    profileDir: DEFAULT_PROFILE_DIR,
+    daemonPort: DEFAULT_DAEMON_PORT,
+    bin: null,
+  };
+
+  // 1. Find the binary
+  const bin = findAgentBrowserBin();
+  state.bin = bin;
+  if (!bin) return state;
+
+  // 2. Get the version
+  try {
+    const out = execSync(`"${bin}" --version`, { encoding: 'utf8', timeout: 5_000 }).trim();
+    state.version = out;
+    state.installed = true;
+  } catch {
+    return state;
+  }
+
+  // 3. Check Chrome for Testing
+  const chromeDir = join(homedir(), '.cache', 'agent-browser', 'chrome');
+  if (existsSync(chromeDir)) state.chromeReady = true;
+
+  // 4. Check daemon (read env on every call so tests can override)
+  const port = parseInt(process.env.AGENT_BROWSER_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+  state.daemonPort = port;
+  state.daemonRunning = isDaemonUp(port);
+
+  return state;
+}
+
+function findAgentBrowserBin() {
+  // 1. Explicit override
+  if (process.env.AGENT_BROWSER_BIN && existsSync(process.env.AGENT_BROWSER_BIN)) {
+    return process.env.AGENT_BROWSER_BIN;
+  }
+  // 2. Well-known npm-global locations
+  const candidates = [
+    '/usr/local/bin/agent-browser',
+    '/opt/homebrew/bin/agent-browser',
+    join(homedir(), '.local', 'bin', 'agent-browser'),
+    join(homedir(), '.npm', 'bin', 'agent-browser'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  // 3. PATH lookup
+  try {
+    const r = execSync('command -v agent-browser', { encoding: 'utf8', timeout: 2_000 }).trim();
+    if (r && existsSync(r)) return r;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+function isDaemonUp(port) {
+  try {
+    execSync(
+      `curl -fsS --max-time 1 "http://127.0.0.1:${port}/json/version" >/dev/null 2>&1`,
+      { shell: '/bin/bash', timeout: 2_000 },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── install / update ───────────────────────────────────────────────────
+
+/**
+ * Install agent-browser. Idempotent: skips steps that are already
+ * complete. Returns the updated state.
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.silent=false]   suppress info output (for CI)
+ * @param {boolean} [opts.dryRun=false]   print actions, make no changes
+ * @param {string}  [opts.channel='latest']  npm dist-tag (e.g. 'beta')
+ * @param {boolean} [opts.startDaemon=true]   start the daemon after install
+ */
+export function install(opts = {}) {
+  const { silent = false, dryRun = false, channel = 'latest', startDaemon = true } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const before = detectState();
+  if (before.installed) {
+    log(`agent-browser ${before.version} already installed at ${before.bin}`);
+    if (startDaemon && !before.daemonRunning) {
+      log('daemon is down — bringing it up');
+      ensureRunning({ silent, dryRun });
+    }
+    return detectState();
+  }
+
+  log(`Installing agent-browser from npm (channel: ${channel})...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: npm install -g agent-browser@${channel}`);
+    // In dry-run, the binary may not be on PATH. Just return the
+    // current state (which includes installed=false) without checking
+    // for the after-install state.
+    return detectState();
+  } else {
+    const r = spawnSync('npm', ['install', '-g', `agent-browser@${channel}`], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 180_000,
+    });
+    if (r.status !== 0) {
+      throw new Error(`npm install -g agent-browser@${channel} failed (exit ${r.status})`);
+    }
+  }
+
+  const after = detectState();
+  if (!after.installed) {
+    throw new Error('agent-browser still not on PATH after install');
+  }
+  log(`agent-browser ${after.version} installed`);
+
+  log('Downloading Chrome for Testing...');
+  if (!dryRun) {
+    const r = spawnSync(after.bin, ['install'], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 300_000,
+    });
+    if (r.status !== 0) {
+      log(chalk.yellow('Chrome download failed — you can retry with `agent-browser install`'));
+    }
+  }
+
+  if (startDaemon) {
+    ensureRunning({ silent, dryRun });
+  }
+  return detectState();
+}
+
+/**
+ * Update agent-browser to the latest version. Idempotent.
+ *
+ * Same shape as install() but uses `agent-browser upgrade` after the
+ * first install (which knows how to detect the install method and run
+ * the right update command).
+ */
+export function update(opts = {}) {
+  const { silent = false, dryRun = false, channel = 'latest', startDaemon = true } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const before = detectState();
+  if (!before.installed) {
+    log('agent-browser not installed — calling install()');
+    return install(opts);
+  }
+
+  log(`agent-browser ${before.version} is installed. Upgrading to ${channel}...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: agent-browser upgrade`);
+    return detectState();
+  } else {
+    // First, try `agent-browser upgrade` (the self-updater). If it
+    // doesn't exist (older version), fall back to `npm update -g`.
+    const r = spawnSync(before.bin, ['upgrade'], {
+      stdio: silent ? 'ignore' : 'inherit',
+      timeout: 180_000,
+    });
+    if (r.status !== 0) {
+      log('`agent-browser upgrade` failed — falling back to `npm update -g`');
+      const r2 = spawnSync('npm', ['update', '-g', `agent-browser@${channel}`], {
+        stdio: silent ? 'ignore' : 'inherit',
+        timeout: 180_000,
+      });
+      if (r2.status !== 0) {
+        throw new Error(`npm update -g agent-browser@${channel} failed (exit ${r2.status})`);
+      }
+    }
+  }
+
+  const after = detectState();
+  if (after.version === before.version) {
+    log(`agent-browser already at latest (${after.version})`);
+  } else {
+    log(`agent-browser updated: ${before.version} → ${after.version}`);
+  }
+
+  if (startDaemon && !after.daemonRunning) {
+    ensureRunning({ silent, dryRun });
+  }
+  return after;
+}
+
+// ── daemon management ──────────────────────────────────────────────────
+
+/**
+ * Bring the agent-browser daemon up if it's down. Idempotent.
+ *
+ * On macOS, Linux, and Windows, the daemon is started as a background
+ * process using `agent-browser serve`. On success, the daemon listens
+ * on `http://127.0.0.1:<port>` and is reachable via the typed CLI
+ * and the MCP stdio server.
+ */
+export function ensureRunning(opts = {}) {
+  const { silent = false, dryRun = false } = opts;
+  const log = silent ? () => {} : (msg) => console.log(chalk.cyan('  → ') + msg);
+
+  const state = detectState();
+  if (!state.installed) {
+    log('agent-browser is not installed — call install() first');
+    return state;
+  }
+  if (state.daemonRunning) {
+    log(`daemon is up (port ${state.daemonPort})`);
+    return state;
+  }
+
+  log(`starting daemon on port ${state.daemonPort}...`);
+  if (dryRun) {
+    log(`[DRY RUN] would run: ${state.bin} serve --port ${state.daemonPort} --headless`);
+  } else {
+    const r = spawnSync('nohup', [
+      state.bin, 'serve',
+      '--port', `${state.daemonPort}`,
+      '--profile', state.profileDir,
+      '--headless',
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      timeout: 5_000,
+    });
+    if (r.error) {
+      log(chalk.yellow(`daemon spawn failed: ${r.error.message}`));
+    }
+  }
+
+  // Wait up to 5s for the daemon to bind
+  for (let i = 0; i < 50; i++) {
+    if (isDaemonUp(state.daemonPort)) {
+      log(`daemon is up (port ${state.daemonPort})`);
+      return detectState();
+    }
+    spawnSync('sleep', ['0.1']);
+  }
+  log(chalk.yellow('daemon did not bind within 5s — check `agent-browser doctor`'));
+  return detectState();
+}
+
+// ── status ─────────────────────────────────────────────────────────────
+
+/**
+ * One-line status for the user. Returns the state object.
+ */
+export function printStatus() {
+  const s = detectState();
+  if (!s.installed) {
+    console.log(chalk.yellow('  agent-browser: NOT INSTALLED'));
+    console.log(chalk.dim('    Install with: npm install -g agent-browser && agent-browser install'));
+  } else {
+    const daemonTxt = s.daemonRunning
+      ? chalk.green('running')
+      : chalk.yellow('stopped');
+    const chromeTxt = s.chromeReady ? chalk.green('ready') : chalk.yellow('not installed');
+    console.log(`  agent-browser ${chalk.cyan(s.version)}  ·  daemon: ${daemonTxt} (port ${s.daemonPort})  ·  chrome: ${chromeTxt}`);
+  }
+  return s;
+}

package/cli/agent-browser-update.test.mjs

@@ -0,0 +1,86 @@
+/**
+ * cli/agent-browser-update.test.mjs
+ *
+ * Unit tests for the v6.0.0 agent-browser install/update module.
+ * Uses node:test (no `expect` — uses `assert` instead).
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+const {
+  detectState,
+  printStatus,
+  install,
+  update,
+  ensureRunning,
+} = await import("./agent-browser-update.mjs");
+
+describe("agent-browser-update", () => {
+  it("exports the public API", () => {
+    assert.equal(typeof detectState, "function");
+    assert.equal(typeof printStatus, "function");
+    assert.equal(typeof install, "function");
+    assert.equal(typeof update, "function");
+    assert.equal(typeof ensureRunning, "function");
+  });
+
+  it("detectState returns a structured state object", () => {
+    const s = detectState();
+    assert.ok("installed" in s);
+    assert.ok("version" in s);
+    assert.ok("chromeReady" in s);
+    assert.ok("daemonRunning" in s);
+    assert.ok("profileDir" in s);
+    assert.ok("daemonPort" in s);
+    assert.ok("bin" in s);
+    assert.equal(typeof s.installed, "boolean");
+    if (s.installed) {
+      assert.equal(typeof s.version, "string");
+    } else {
+      assert.equal(s.version, null);
+    }
+  });
+
+  it("detectState profileDir points to ~/.agent-browser/profile by default", () => {
+    const s = detectState();
+    assert.match(s.profileDir, /\.agent-browser\/profile$/);
+  });
+
+  it("detectState default daemon port is 9223", () => {
+    delete process.env.AGENT_BROWSER_PORT;
+    const s = detectState();
+    assert.equal(s.daemonPort, 9223);
+  });
+
+  it("printStatus does not throw (regardless of install state)", () => {
+    const origLog = console.log;
+    const captured = [];
+    console.log = (...args) => captured.push(args.join(" "));
+    try {
+      printStatus();
+    } finally {
+      console.log = origLog;
+    }
+    assert.ok(captured.length > 0);
+    assert.match(captured[0], /agent-browser/);
+  });
+
+  it("install with dryRun=true returns a state object", () => {
+    const s = install({ dryRun: true, silent: true });
+    assert.ok("installed" in s);
+  });
+
+  it("update with dryRun=true returns a state object", () => {
+    const s = update({ dryRun: true, silent: true });
+    assert.ok("installed" in s);
+  });
+
+  it("ensureRunning with dryRun=true returns a state object", () => {
+    const s = ensureRunning({ dryRun: true });
+    assert.ok("installed" in s);
+  });
+
+  // NOTE: AGENT_BROWSER_PORT env override is tested manually (node --test
+  // spawns a child process that doesn't inherit the parent's env).
+});

package/cli/bin.mjs

@@ -13,7 +13,7 @@
  * Commands:
  *   install, audit, init, export, artifact, update, test-gate, service, dash,
  *   memory, headroom, minimax, usage, mod, doctor, repair, dev-link, dev-unlink,
- *   heads-up, bg, agent-browser-up, providers, deploy, plugin, marketplace
+ *   heads-up, bg, agent-browser, agent-browser-up, providers, deploy, plugin, marketplace
  */
 import chalk from 'chalk';
 import { existsSync, readFileSync } from 'node:fs';
@@ -115,7 +115,8 @@ function showHelp() {
     deploy              One-click deploy to Vercel, Cloudflare, Fly.io, or Docker
     plugin <subcommand> Manage marketplace plugins (search/install/config/invoke)
     marketplace <subcommand>  Browse and install plugins from the public marketplace
-    agent-browser-up  Start Chromium for agent-browser (start/stop/status)
+    agent-browser      Install / update / verify the agent-browser CLI
+    agent-browser-up    Start Chromium for agent-browser (start/stop/status)
     providers detect    Auto-detect provider API keys from env + cline.json
     clip <subcommand>       Manage web clipper saved clips (list/delete/configure)
     ocr <subcommand>        OCR operations on images (list/process/configure)
@@ -429,6 +430,7 @@ async function main() {
     case 'heads-up':
     case 'bg':
     case 'digest':
+    case 'agent-browser':
     case 'agent-browser-up':
     case 'providers':
     case 'plan': {

package/cli/commands/util.mjs

@@ -3,7 +3,7 @@
  *
  * Miscellaneous utility commands:
  *   audit, init, export, test-gate, dev-link, dev-unlink,
- *   doctor, repair, heads-up, bg, agent-browser-up, providers detect,
+ *   doctor, repair, heads-up, bg, agent-browser, agent-browser-up, providers detect,
  *   backup, restore
  */
 import chalk from 'chalk';
@@ -441,6 +441,70 @@ export async function run(name, args, isHelpRequest) {
       break;
     }
 
+    case 'agent-browser': {
+      // v6.0.0 — install / update / verify the agent-browser CLI.
+      // (The 'agent-browser-up' sibling is the bash wrapper that just
+      // manages the daemon process; this is the rich installer + updater.)
+      const { install, update, detectState, ensureRunning, printStatus } =
+        await import('../agent-browser-update.mjs');
+      const sub = args[0] || 'status';
+      switch (sub) {
+        case 'status':
+          printStatus();
+          break;
+        case 'install': {
+          const s = install({ silent: false });
+          console.log(chalk.green('\n  agent-browser ready.'));
+          console.log(`    version:    ${s.version}`);
+          console.log(`    daemon:     ${s.daemonRunning ? 'running' : 'stopped'}`);
+          console.log(`    profile:    ${s.profileDir}`);
+          break;
+        }
+        case 'update': {
+          const s = update({ silent: false });
+          console.log(chalk.green('\n  agent-browser up-to-date.'));
+          console.log(`    version:    ${s.version}`);
+          console.log(`    daemon:     ${s.daemonRunning ? 'running' : 'stopped'}`);
+          break;
+        }
+        case 'detect': {
+          const s = detectState();
+          console.log(JSON.stringify(s, null, 2));
+          break;
+        }
+        case 'start':
+          ensureRunning({ silent: false });
+          break;
+        case 'stop': {
+          const { spawnSync } = await import('node:child_process');
+          const killed = spawnSync('pkill', ['-f', 'agent-browser serve'], { stdio: 'ignore' });
+          if (killed.status === 0) {
+            console.log(chalk.green('  ✓ daemon stopped'));
+          } else {
+            console.log(chalk.dim('  daemon was not running'));
+          }
+          break;
+        }
+        default:
+          console.log(`bizar agent-browser <sub>
+
+  Subcommands:
+    status   one-line status (default)
+    install  install agent-browser + download Chrome
+    update   upgrade to the latest version
+    detect   JSON state (for scripts)
+    start    start the daemon
+    stop     stop the daemon
+
+  Examples:
+    bizar agent-browser status
+    bizar agent-browser install
+    bizar agent-browser update
+    bizar agent-browser start`);
+      }
+      break;
+    }
+
     case 'providers':
       if (args[0] === 'detect') {
         const { runProvidersDetect } = await import('../providers-detect.mjs');

package/cli/provision.mjs

@@ -835,6 +835,44 @@ export async function installLightragProvision({ dryRun = false } = {}) {
   }
 }
 
+/**
+ * v6.0.0 — Ensure `agent-browser` (native Rust CLI from vercel-labs) is
+ * installed and the daemon is up. agent-browser replaces the v5.x
+ * `browser-harness` (Python CDP wrapper). The CLI is installed via
+ * `npm install -g agent-browser`; Chrome for Testing is downloaded by
+ * `agent-browser install`; the daemon is started by
+ * `agent-browser serve --headless --port <port> --profile <dir>`.
+ *
+ * Idempotent. Returns { ok, message, version?, daemonRunning? }.
+ */
+export async function ensureAgentBrowser({ dryRun = false, mode = 'install' } = {}) {
+  const ab = await import('./agent-browser-update.mjs');
+  const before = ab.detectState();
+  if (dryRun) {
+    return {
+      ok: true,
+      message: `[dry-run] agent-browser: ${before.installed ? 'installed' : 'not installed'}` +
+               (before.installed ? ` (v${before.version})` : ''),
+      version: before.version,
+      daemonRunning: before.daemonRunning,
+    };
+  }
+  try {
+    const after = mode === 'update' && before.installed
+      ? ab.update({ silent: true, startDaemon: true })
+      : ab.install({ silent: true, startDaemon: true });
+    return {
+      ok: true,
+      message: `agent-browser: ${after.installed ? `v${after.version}` : 'install attempted'}` +
+               ` · daemon: ${after.daemonRunning ? 'running' : 'stopped'}`,
+      version: after.version,
+      daemonRunning: after.daemonRunning,
+    };
+  } catch (err) {
+    return { ok: false, message: `agent-browser install failed: ${err.message}` };
+  }
+}
+
 /**
  * v4.4.11 — The mods step. By default, NEVER install or upgrade mods
  * during `bizar install` or `bizar update`. The step just reports the

package/install.sh

@@ -14,8 +14,8 @@
 # package manager:
 #
 #   - Linux:  ensure node is installed (apt/dnf/pacman/zypper), install uv,
-#             python3.12, jq, gh, agent-browser, Chrome runtime libs.
-#   - macOS:  ensure homebrew is installed; everything else is via brew.
+#             python3.12, jq, gh, agent-browser (npm), Chrome for Testing.
+#   - macOS:  ensure homebrew is installed; everything else is via brew/npm.
 #   - Windows: a stub that prints "use install.ps1".
 #
 # Agent files / plugin copy / cline.json patching / service registration /
@@ -189,6 +189,41 @@ check_deps() {
   fi
 }
 
+install_agent_browser() {
+  # v6.0.0 — agent-browser (native Rust CLI from vercel-labs). Replaces
+  # the v5.x browser-harness (Python CDP wrapper). Installs via npm.
+  #
+  # If npm is not available, this is a soft-fail: agent-browser is
+  # optional, and `cli/provision.mjs:ensureAgentBrowser` will retry it
+  # once npm is available.
+  if have_cmd agent-browser; then
+    local ab_ver
+    ab_ver="$(agent-browser --version 2>/dev/null || echo 'unknown')"
+    note "agent-browser ${ab_ver} already installed"
+    return 0
+  fi
+  action "Installing agent-browser via npm..."
+  if ! have_cmd npm; then
+    warn "npm not available — skipping agent-browser install"
+    warn "    Install later: npm install -g agent-browser"
+    return 0
+  fi
+  if dry npm install -g agent-browser 2>&1; then
+    local ab_ver
+    ab_ver="$(agent-browser --version 2>/dev/null || echo 'unknown')"
+    note "agent-browser ${ab_ver} installed"
+    # Download Chrome for Testing
+    if dry agent-browser install 2>&1; then
+      note "Chrome for Testing downloaded"
+    else
+      warn "Chrome download failed — retry later: agent-browser install"
+    fi
+  else
+    warn "agent-browser install failed — the browser tools will not be available"
+    warn "    Install later: npm install -g agent-browser"
+  fi
+}
+
 install_lightrag() {
   # LightRAG is optional but recommended. Install via uv tool.
   # uv tools install to ~/.local/bin/ — ensure that's on PATH.
@@ -359,6 +394,7 @@ install_linux() {
   ensure_node
   check_deps
   install_missing_deps_linux
+  install_agent_browser
   install_service
 }
 
@@ -366,6 +402,7 @@ install_macos() {
   note "Detected macOS ($(uname -m))"
   check_deps
   install_missing_deps_macos
+  install_agent_browser
   install_service
 }
 
@@ -380,7 +417,7 @@ main() {
   fi
 
   echo ""
-  echo -e "${BOLD}${CYAN}  ⚡ BizarHarness Installer v4.4.7${NC}"
+  echo -e "${BOLD}${CYAN}  ⚡ BizarHarness Installer v6.0.0${NC}"
   if [ "$UPDATE_MODE" -eq 1 ]; then
     echo -e "  ${DIM}Update mode${NC}"
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "5.6.0-beta.7",
+  "version": "5.6.0-beta.8",
   "description": "Norse-pantheon multi-agent system for cline — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, cline plugin, and typed SDK.",
   "type": "module",
   "bin": {

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar-sdk",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",