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

package/bizar-dash/skills/agent-browser/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: agent-browser
+description: Self-healing browser automation CLI for AI agents — drives Chrome for Testing via 100+ typed CLI commands, native MCP stdio server, snapshot-based element refs (`@e2`), and a plugin system.
+version: "1.0.0"
+status: active
+created_by: sprint MS-2026-05
+use_count: 0
+failure_count: 0
+last_used: null
+---
+
+# agent-browser
+
+`agent-browser` is a **native Rust CLI** from [vercel-labs](https://github.com/vercel-labs/agent-browser)
+(~38K★) that exposes a complete browser-automation surface to AI agents.
+
+## Why this skill
+
+- Bizar dispatches a browser-primary agent (`agent-browser`) for any task
+  that requires real-browser verification of a web app: clicking buttons,
+  filling forms, taking screenshots, reading accessibility trees.
+- agent-browser replaces the v5.x `browser-harness` (Python + uv) which
+  was slow, fragile, and lacked MCP integration. See `docs/migration-guide.md`
+  for the migration rationale.
+
+## When to use
+
+Use this skill when the task requires:
+
+- "Take a screenshot of `<url>`"
+- "Click button X, verify the result"
+- "Fill in the login form, click submit"
+- "Find a bug that's only visible in the rendered page"
+- "Verify the dashboard's tab navigation works end-to-end"
+
+Do not use this skill for:
+
+- Editing code (the browser-primary agent has edit/write **denied**)
+- Long-running background automation (use Cline agent teams instead)
+- Non-Chromium browsers (Chrome for Testing only)
+
+## Quick start
+
+```bash
+# Install (one-time)
+npm install -g agent-browser
+agent-browser install        # downloads Chrome for Testing
+
+# Ensure the daemon is up
+bizar browser-agent-up start # wrapper around cli/agent-browser-up.sh
+
+# Drive the browser
+agent-browser open example.com
+agent-browser snapshot --json
+agent-browser click @e2
+agent-browser fill @e3 "hello"
+agent-browser screenshot page.png
+agent-browser close
+```
+
+## Command reference
+
+The full command set has 100+ commands. The most common:
+
+| Command | Purpose |
+| --- | --- |
+| `agent-browser open <url>` | Launch + navigate (aliases: `goto`, `navigate`) |
+| `agent-browser read [url]` | Fetch agent-readable text from URL or active tab |
+| `agent-browser snapshot [--json]` | Accessibility tree with refs (`@e1`, `@e2`, ...) |
+| `agent-browser click <sel>` | Click — accepts ref (`@e2`) or selector (`#submit`) |
+| `agent-browser fill <sel> <text>` | Clear + fill |
+| `agent-browser type <sel> <text>` | Type without clear |
+| `agent-browser press <key>` | Press key (Enter, Tab, Control+a) |
+| `agent-browser get <what> <sel>` | Get text / html / attr |
+| `agent-browser screenshot <path>` | Screenshot to file (PNG) |
+| `agent-browser find role/label/text` | Semantic find (returns ref) |
+| `agent-browser wait <what>` | Wait for selector / load / network idle |
+| `agent-browser eval <js>` | Evaluate JavaScript |
+| `agent-browser tab list/open/close/switch` | Tab management |
+| `agent-browser close` | Close the browser |
+| `agent-browser doctor` | Self-diagnostics |
+| `agent-browser mcp` | Start MCP stdio server |
+| `agent-browser chat "..."` | Natural-language browser tasks |
+| `agent-browser skills list/get` | Bundled skills (this skill is in the catalog) |
+
+## MCP integration
+
+Cline registers `agent-browser` as an MCP tool server at session start via
+`.cline/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "agent-browser",
+      "args": ["mcp", "--tools", "core"]
+    }
+  }
+}
+```
+
+Tool profiles:
+
+- `core` — Default. Navigation, snapshots, interaction, waits, reads, screenshots,
+  JavaScript eval, close, tab basics, profile discovery. Small MCP context.
+- `network` — Routes, request inspection, HAR, headers, credentials, offline.
+- `state` — Cookies, storage, auth, sessions, profiles, skills.
+- `debug` — Console/errors, tracing, profiling, recording, clipboard, plugins,
+  doctor, dashboard, install, upgrade, chat, batch.
+- `tabs` — Back/forward/reload, tabs, windows, frames, dialogs.
+- `react` — React tree/inspect, vitals, pushstate.
+- `mobile` — Viewport/device/geolocation, touch, swipe, mouse, keyboard.
+- `all` — Every MCP tool.
+
+## Plugin system
+
+```json
+{
+  "plugins": [
+    {
+      "name": "vault",
+      "command": "agent-browser-plugin-vault",
+      "capabilities": ["credential.read"]
+    }
+  ]
+}
+```
+
+## Patterns
+
+### Stable selectors
+
+Prefer **refs** (`@e2`) over CSS selectors — refs survive snapshot churn.
+
+```bash
+agent-browser snapshot --json > snap.json
+agent-browser click @e2
+```
+
+### Headless vs headed
+
+Default is headless. Use `--headed` for visual debugging.
+
+### Persistent profile
+
+Set `--profile <dir>` to keep cookies / storage across runs. Default
+is `~/.agent-browser/profile`.
+
+### Natural-language chat
+
+```bash
+AI_GATEWAY_API_KEY=... agent-browser chat "summarize the page at /pricing"
+```
+
+This streams a structured response from the configured LLM provider.
+
+## Configuration
+
+Layered config (lowest → highest priority):
+
+1. `~/.agent-browser/config.json` — user-level
+2. `./agent-browser.json` — project-level
+3. `AGENT_BROWSER_*` env vars
+4. CLI flags
+
+## Lessons / known limitations
+
+- Chrome for Testing only (no Firefox / Safari / WebKit).
+- `agent-browser install` requires network access to download Chrome
+  the first time (~150MB).
+- The chat endpoint requires `AI_GATEWAY_API_KEY` from Vercel.
+- The daemon binds to `127.0.0.1` by default; use `--host` to expose
+  publicly (only on trusted networks).
+
+## See also
+
+- [config/agents/agent-browser.md](../../config/agents/agent-browser.md) — the Cline primary agent
+- [cli/agent-browser-up.sh](../../cli/agent-browser-up.sh) — idempotent starter
+- https://github.com/vercel-labs/agent-browser — upstream README
+- [docs/migration-guide.md](../../docs/migration-guide.md) — browser-harness → agent-browser rationale
+- [research/agent-harness-survey/round-9-memory/bizar-memory-redesign.md](../../research/agent-harness-survey/round-9-memory/bizar-memory-redesign.md)

package/bizar-dash/src/server/mods-loader.mjs

@@ -978,7 +978,7 @@ async function fetchInstructionDir(baseUrl, destDir) {
   const candidates = [
     'thor.md', 'tyr.md', 'odin.md', 'heimdall.md', 'mimir.md',
     'frigg.md', 'vor.md', 'hermod.md', 'baldr.md', 'forseti.md',
-    'vidarr.md', 'quick.md', 'browser-harness.md', 'semble-search.md',
+    'vidarr.md', 'quick.md', 'agent-browser.md', 'semble-search.md',
     'plan.md', 'review.md', 'audit.md', 'init.md', 'learn.md',
     'explain.md', 'visual-plan.md', 'tailscale-serve.md',
     'README.md', 'AGENTS.md', 'COMMANDS.md', 'INSTRUCTIONS.md',

package/bizar-dash/tests/{no-agent-browser.node.test.mjs → no-browser-harness.node.test.mjs}

@@ -1,18 +1,19 @@
 /**
- * no-agent-browser.node.test.mjs — regression test for the v3.20.7 cleanup.
+ * no-browser-harness.node.test.mjs — regression test for the v6.0.0 migration.
  *
- * The `agent-browser` MCP tool was the previous browser-automation path.
- * v3.20.7 replaced it with `browser-harness` (the Python tool from
- * https://github.com/browser-use/browser-harness). This test ensures
- * no agent-browser references leak back into the shipped config or
- * the install/bootstrap scripts.
+ * v6.0.0 replaces the v5.x `browser-harness` (Python tool from
+ * https://github.com/browser-use/browser-harness) with `agent-browser`
+ * (native Rust CLI from vercel-labs, ~38K★ — https://github.com/vercel-labs/agent-browser).
+ *
+ * This test ensures no `browser-harness` references leak back into the
+ * shipped config, the install/bootstrap scripts, or the dashboard code.
  *
  * Allowed exceptions:
- *   - .bizar/AGENTS_SELF_IMPROVEMENT.md (historical rule entry documenting
- *     the v3.20.7 migration)
+ *   - .bizar/AGENTS_SELF_IMPROVEMENT.md (historical rule entry)
  *   - CHANGELOG.md (historical release notes)
+ *   - docs/migration-guide.md (documents the v5.x → v6.0.0 migration)
  *
- * Run with: node --test tests/no-agent-browser.node.test.mjs
+ * Run with: node --test tests/no-browser-harness.node.test.mjs
  */
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
@@ -24,6 +25,7 @@ const REPO = resolve(import.meta.dirname, '..', '..');
 const SCAN_DIRS = [
   'config',
   'cli',
+  'plugins',
   'bizar-dash/src',
   'install.sh',
 ];
@@ -31,10 +33,13 @@ const SCAN_EXTENSIONS = ['.mjs', '.ts', '.tsx', '.json', '.sh', '.md', '.mdx', '
 const ALLOW_FILES = new Set([
   '.bizar/AGENTS_SELF_IMPROVEMENT.md', // historical rule entry
   'CHANGELOG.md',                       // historical release notes
+  'docs/migration-guide.md',            // documents the migration rationale
+  'MILESTONES.md',                      // strategic roadmap (references legacy)
+  'IMPLEMENTATION_PLAN.md',             // tactical plan (references legacy)
 ]);
 const PATTERNS = [
-  /agent[-_]?browser/i,                 // agent-browser, agent_browser, agentBrowser
-  /agent_browser_/i,                    // agent_browser_open etc.
+  /browser[-_]?harness/i,               // browser-harness, browser_harness, browserHarness
+  /browser_harness_/i,                  // browser_harness_open etc.
 ];
 
 function isAllowed(relPath) {
@@ -49,7 +54,6 @@ function* walkFiles(root) {
     return;
   }
   if (!stat.isDirectory()) return;
-  // Skip noise
   if (root.includes('node_modules')) return;
   if (root.includes('.git')) return;
   for (const entry of readdirSync(root)) {
@@ -57,7 +61,7 @@ function* walkFiles(root) {
   }
 }
 
-describe('no agent-browser references in shipped code', () => {
+describe('no browser-harness references in shipped code (v6.0.0+ uses agent-browser)', () => {
   const violations = [];
 
   for (const target of SCAN_DIRS) {
@@ -80,19 +84,15 @@ describe('no agent-browser references in shipped code', () => {
     }
   }
 
-  it('reports zero violations', () => {
-    if (violations.length > 0) {
-      const msg = violations
-        .map((v) => `  ${v.file}: matched "${v.match}"`)
-        .join('\n');
-      assert.fail(`agent-browser references found in shipped code:\n${msg}`);
-    }
-  });
+  if (violations.length > 0) {
+    const lines = violations.map((v) => `  - ${v.file}: matched "${v.match}"`);
+    assert.fail(
+      `Found ${violations.length} browser-harness reference(s) in shipped code:\n${lines.join('\n')}\n` +
+      `Use agent-browser instead. See docs/migration-guide.md.`
+    );
+  }
 
-  it('documents the explicit allow-list', () => {
-    // Sanity: the allow-list itself shouldn't be empty (we have real
-    // historical references that should be preserved).
-    assert.ok(ALLOW_FILES.size >= 2,
-      'expected ALLOW_FILES to include at least AGENTS_SELF_IMPROVEMENT.md + CHANGELOG.md');
+  it('has no browser-harness references in shipped config / code / install scripts', () => {
+    assert.equal(violations.length, 0);
   });
 });

package/cli/agent-browser-up.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+#
+# cli/agent-browser-up.sh — install/launch agent-browser for Cline.
+# v6.0.0 — Replaces browser-harness (Python, v3.20.7-v5.6.0) with
+# agent-browser (native Rust CLI from vercel-labs, ~38K★).
+#
+# agent-browser is a thin CLI wrapper around Chrome for Testing that
+# gives agents access to:
+#   - 100+ typed CLI commands (open, snapshot, click, fill, screenshot, …)
+#   - Native MCP stdio server (`agent-browser mcp`)
+#   - Self-healing snapshot-based element detection
+#   - Plugins (vault, recorder, …)
+#   - Vercel AI SDK + AI Gateway integration (natural-language `chat`)
+#
+# Install:  npm install -g agent-browser
+#           agent-browser install        # downloads Chrome for Testing
+#
+# This script ensures the daemon is up before Bizar agents try to
+# drive the browser. Idempotent: re-running is a no-op if already up.
+#
+# Usage:
+#   cli/agent-browser-up.sh                 # start if not running
+#   cli/agent-browser-up.sh status          # print status
+#   cli/agent-browser-up.sh stop            # kill daemon
+#   cli/agent-browser-up.sh restart         # stop + start
+#   cli/agent-browser-up.sh install         # install + bootstrap
+#   cli/agent-browser-up.sh doctor          # run agent-browser doctor
+#
+# Environment overrides:
+#   AB_PROFILE      — user-data-dir (default: ~/.agent-browser/profile)
+#   AGENT_BROWSER_API_KEY — for natural-language chat
+#
+# Exit codes:
+#   0   started / already running / status clean
+#   1   failed to start (missing binary, port busy, etc.)
+#
+set -euo pipefail
+
+AB_BIN="${AB_BIN:-$(command -v agent-browser || true)}"
+AB_DAEMON_HOST="127.0.0.1"
+AB_DAEMON_PORT="${AB_DAEMON_PORT:-9223}"
+AB_PROFILE="${AB_PROFILE:-$HOME/.agent-browser/profile}"
+
+log()  { echo "[agent-browser-up] $*" >&2; }
+fail() { log "FAIL: $*"; exit 1; }
+
+ensure_binary() {
+  if [ -z "$AB_BIN" ] || ! [ -x "$AB_BIN" ]; then
+    log "agent-browser not on PATH. Installing via npm..."
+    command -v npm >/dev/null || fail "npm not found — install Node.js 24+ first"
+    npm install -g agent-browser
+    AB_BIN="$(command -v agent-browser)"
+    [ -x "$AB_BIN" ] || fail "agent-browser install failed"
+  fi
+  log "agent-browser binary: $AB_BIN"
+  log "version: $($AB_BIN --version 2>/dev/null || echo 'unknown')"
+}
+
+ensure_chrome() {
+  if [ -d "$AB_PROFILE" ] && [ -f "$AB_PROFILE/SingletonLock" ]; then
+    log "Chrome profile already exists: $AB_PROFILE"
+    return 0
+  fi
+  log "Bootstrapping Chrome for Testing via agent-browser install"
+  $AB_BIN install --silent || true
+}
+
+is_daemon_running() {
+  $AB_BIN status --quiet 2>/dev/null && return 0
+  # Fallback: check the daemon HTTP endpoint
+  curl -fsS --max-time 2 "http://${AB_DAEMON_HOST}:${AB_DAEMON_PORT}/json/version" >/dev/null 2>&1
+}
+
+start_daemon() {
+  log "Starting agent-browser daemon (profile: $AB_PROFILE, port: $AB_DAEMON_PORT)..."
+  mkdir -p "$AB_PROFILE"
+
+  # Spawn the daemon detached so it survives parent shell exit
+  setsid nohup "$AB_BIN" serve \
+      --port "$AB_DAEMON_PORT" \
+      --profile "$AB_PROFILE" \
+      --headless \
+      >"$AB_PROFILE/daemon.log" 2>&1 < /dev/null &
+  local pid=$!
+  echo $pid > "$AB_PROFILE/daemon.pid"
+  disown $pid 2>/dev/null || true
+
+  # Wait for the daemon to bind
+  local retries=30
+  while [ $retries -gt 0 ]; do
+    if curl -fsS --max-time 2 "http://${AB_DAEMON_HOST}:${AB_DAEMON_PORT}/json/version" >/dev/null 2>&1; then
+      log "agent-browser daemon is up (pid $pid)"
+      return 0
+    fi
+    sleep 1
+    retries=$((retries - 1))
+  done
+  fail "agent-browser daemon did not bind to ${AB_DAEMON_HOST}:${AB_DAEMON_PORT}"
+}
+
+stop_daemon() {
+  local pidfile="$AB_PROFILE/daemon.pid"
+  if [ -f "$pidfile" ]; then
+    local pid
+    pid="$(cat "$pidfile" 2>/dev/null || true)"
+    if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+      log "Stopping agent-browser daemon (pid $pid)"
+      kill "$pid" 2>/dev/null || true
+      sleep 1
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+    rm -f "$pidfile"
+  fi
+  # Belt-and-braces: kill any orphan agent-browser processes
+  pkill -f 'agent-browser serve' 2>/dev/null || true
+}
+
+print_status() {
+  if is_daemon_running; then
+    echo "agent-browser: RUNNING  (http://${AB_DAEMON_HOST}:${AB_DAEMON_PORT})"
+    $AB_BIN doctor 2>&1 | tail -20 || true
+  else
+    echo "agent-browser: STOPPED"
+    echo "Start with: cli/agent-browser-up.sh start"
+  fi
+}
+
+case "${1:-start}" in
+  start)   ensure_binary; ensure_chrome; is_daemon_running && { log "already running"; exit 0; }; start_daemon ;;
+  stop)    stop_daemon ;;
+  restart) stop_daemon; sleep 1; ensure_binary; ensure_chrome; start_daemon ;;
+  status)  ensure_binary; print_status ;;
+  doctor)  ensure_binary; $AB_BIN doctor ;;
+  install) ensure_binary; ensure_chrome; $AB_BIN install ;;
+  *)       fail "unknown command: $1 (use start|stop|restart|status|doctor|install)" ;;
+esac