browser-agent-server 1.0.0__py3-none-any.whl

browser_agent/cli.py

@@ -0,0 +1,414 @@
+"""Command line interface: ``browser-agent …``.
+
+Subcommands:
+    serve    Run the localhost HTTP daemon (what systemd starts)
+    status   Show daemon & X11 status
+    stop     Hibernate Chrome and Xvfb immediately
+    fetch    Open a URL in real Chrome and print text/html/JSON
+    click / move / type   Hardware-level X11 input
+    agent    Vision-guided computer-use loop
+    vnc      Start/stop localhost VNC for live viewing over SSH
+    setup    Provision a Linux host (apt packages, Google Chrome, systemd unit)
+    doctor   Self-check this host and the running daemon
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from importlib import resources
+from pathlib import Path
+
+from .chrome import find_chrome_binary, is_warp_proxy_ready
+from .server import API_VERSION, DEFAULT_HOST, DEFAULT_IDLE_TIMEOUT, DEFAULT_PORT, serve
+
+log = logging.getLogger("browser_agent.cli")
+
+APT_PACKAGES = ("xvfb", "openbox", "xdotool", "scrot", "x11vnc")
+STATE_HOME = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state")) / "browser-agent"
+
+
+# ---------------------------------------------------------------------------
+# HTTP helpers for client-side subcommands
+# ---------------------------------------------------------------------------
+
+def _api_request(
+    method: str,
+    path: str,
+    payload: dict | None = None,
+    port: int = DEFAULT_PORT,
+    timeout: float = 90.0,
+) -> dict | None:
+    url = f"http://{DEFAULT_HOST}:{port}{path}"
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    headers = {"Content-Type": "application/json"} if data is not None else {}
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            return json.loads(e.read().decode("utf-8"))
+        except Exception:  # noqa: BLE001
+            return {"ok": False, "error": str(e)}
+    except OSError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# setup
+# ---------------------------------------------------------------------------
+
+def _load_unit_template() -> str:
+    return (
+        resources.files("browser_agent.data")
+        .joinpath("browser-agent.service")
+        .read_text(encoding="utf-8")
+    )
+
+
+def _run(cmd: list[str], sudo: list[str], dry_run: bool = False) -> bool:
+    full = sudo + cmd
+    print(f"  $ {' '.join(full)}")
+    if dry_run:
+        return True
+    res = subprocess.run(full, check=False)
+    return res.returncode == 0
+
+
+def _install_chrome_apt(sudo: list[str], dry_run: bool) -> bool:
+    """Add Google's apt repo and install google-chrome-stable."""
+    steps = [
+        "install -m 0755 -d /usr/share/keyrings",
+        "sh -c 'curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /usr/share/keyrings/google-chrome.gpg'",
+        "sh -c 'echo deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] https://dl.google.com/linux/chrome/deb/ stable main > /etc/apt/sources.list.d/google-chrome.list'",
+        "apt-get update",
+        "apt-get install -y google-chrome-stable",
+    ]
+    ok = True
+    for s in steps:
+        ok = _run(["sh", "-c", s] if s.startswith(("install", "sh")) else s.split(), sudo, dry_run) and ok
+    return ok
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    dry = args.dry_run
+    euid = os.geteuid() if hasattr(os, "geteuid") else None
+    sudo: list[str] = [] if euid == 0 else (["sudo"] if shutil.which("sudo") else [])
+    if euid != 0 and not sudo:
+        print("setup needs root (or sudo). Re-run as root.", file=sys.stderr)
+        return 2
+
+    print("== browser-agent setup ==")
+
+    if not args.no_apt:
+        print(f"-> apt packages: {' '.join(APT_PACKAGES)}")
+        _run(["apt-get", "update"], sudo, dry)
+        _run(["apt-get", "install", "-y", *APT_PACKAGES], sudo, dry)
+    else:
+        print("-> skipping apt (--no-apt)")
+
+    try:
+        chrome = find_chrome_binary()
+        print(f"-> chrome found: {chrome}")
+    except FileNotFoundError:
+        chrome = ""
+        if args.with_chrome:
+            print("-> installing google-chrome-stable from Google's apt repo")
+            _install_chrome_apt(sudo, dry)
+        else:
+            print("-> WARNING: no Chrome/Chromium binary found.", file=sys.stderr)
+            print("   Re-run with --with-chrome to install google-chrome-stable automatically,", file=sys.stderr)
+            print("   or install it yourself: https://www.google.com/chrome/", file=sys.stderr)
+
+    if args.no_unit:
+        print("-> skipping systemd unit (--no-unit)")
+        return 0
+
+    exec_start = shutil.which("browser-agent") or f"{sys.executable} -m browser_agent.server"
+    env_file = args.env_file
+    unit = (
+        _load_unit_template()
+        .replace("{{EXEC_START}}", exec_start)
+        .replace("{{ENV_FILE}}", env_file)
+        .replace("{{USER}}", args.user or getpass.getuser())
+        .replace("{{PORT}}", str(args.port))
+        .replace("{{IDLE}}", str(args.idle_timeout))
+        .replace("{{MEMORY_HIGH}}", args.memory_high)
+        .replace("{{MEMORY_MAX}}", args.memory_max)
+    )
+    unit_path = Path("/etc/systemd/system/browser-agent.service")
+    print(f"-> writing {unit_path}")
+    print("   ExecStart:", exec_start)
+    if not dry:
+        proc = subprocess.run(
+            [*sudo, "tee", str(unit_path)], input=unit.encode(), stdout=subprocess.DEVNULL, check=False
+        )
+        if proc.returncode != 0:
+            print("failed to write the unit file", file=sys.stderr)
+            return 1
+
+        env_path = Path(env_file)
+        if not env_path.exists() and str(env_path).startswith("/etc/"):
+            seed = "# browser-agent environment (chmod 600 — put API keys here)\n# GEMINI_API_KEYS=key1,key2\n"
+            subprocess.run([*sudo, "sh", "-c", f"printf '%s' '{seed}' > {env_path} && chmod 600 {env_path}"], check=False)
+
+        _run(["systemctl", "daemon-reload"], sudo)
+        if not args.no_start:
+            _run(["systemctl", "enable", "--now", "browser-agent.service"], sudo)
+
+    print()
+    print("Done. Next steps:")
+    print(f"  1. Put Gemini key(s) into {env_file} if you plan to use `browser-agent agent`")
+    print("  2. Run: browser-agent doctor")
+    print("  3. Optional live view: browser-agent vnc start  (+ ssh -L 5900:127.0.0.1:5900 …)")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# doctor
+# ---------------------------------------------------------------------------
+
+def _check(name: str, ok: bool, detail: str = "", required: bool = True) -> dict:
+    return {"name": name, "ok": bool(ok), "required": required, "detail": detail}
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    checks: list[dict] = []
+
+    vi = sys.version_info
+    checks.append(_check("python>=3.12", vi >= (3, 12), f"running {vi.major}.{vi.minor}.{vi.micro}"))
+
+    for b in ("Xvfb", "openbox", "xdotool", "scrot"):
+        p = shutil.which(b)
+        checks.append(_check(f"binary:{b}", bool(p), p or "not found on PATH"))
+    p = shutil.which("x11vnc")
+    checks.append(_check("binary:x11vnc", bool(p), p or "optional — needed only for `vnc`", required=False))
+
+    try:
+        chrome = find_chrome_binary()
+        checks.append(_check("chrome-binary", True, chrome))
+    except FileNotFoundError as e:
+        checks.append(_check("chrome-binary", False, str(e).split(".")[0]))
+
+    lock = Path("/tmp/.X99-lock")
+    checks.append(_check("display :99 free", not lock.exists(), "stale /tmp/.X99-lock present" if lock.exists() else "no lock", False))
+
+    try:
+        STATE_HOME.mkdir(parents=True, exist_ok=True)
+        checks.append(_check("state dir writable", os.access(STATE_HOME, os.W_OK), str(STATE_HOME)))
+    except OSError as e:
+        checks.append(_check("state dir writable", False, f"{STATE_HOME}: {e}"))
+
+    total_gb = 0.0
+    try:
+        for line in Path("/proc/meminfo").read_text().splitlines():
+            if line.startswith("MemTotal"):
+                total_gb = int(line.split()[1]) / 1024 / 1024
+    except OSError:
+        pass
+    checks.append(_check(
+        "ram", total_gb >= 1.4 or total_gb == 0,
+        f"{total_gb:.1f} GB total" + (" — tight; keep MemoryMax low and avoid parallel tabs" if 0 < total_gb < 1.4 else ""),
+        required=False,
+    ))
+
+    checks.append(_check("warp proxy (127.0.0.1:40000)", is_warp_proxy_ready(), "optional — fallback when the datacenter IP is blocked", False))
+
+    keys = [v for v in ("GEMINI_API_KEY", "GEMINI_API_KEYS", "LLM_API_KEY") if os.environ.get(v)]
+    keys += [f"GEMINI_API_KEY_{i}" for i in range(1, 11) if os.environ.get(f"GEMINI_API_KEY_{i}")]
+    checks.append(_check("gemini key(s) for `agent`", bool(keys), ", ".join(keys) if keys else "optional — vision agent needs one", False))
+
+    unit_active = subprocess.run(["systemctl", "is-active", "browser-agent.service"], capture_output=True, text=True, check=False).stdout.strip() if shutil.which("systemctl") else "n/a"
+    checks.append(_check("systemd unit", unit_active == "active", f"is-active: {unit_active}", False))
+
+    res = _api_request("GET", "/status", port=args.port, timeout=3.0)
+    if res is None:
+        checks.append(_check("daemon http api", False, f"no answer on 127.0.0.1:{args.port} (start: systemctl start browser-agent)", False))
+    else:
+        api_ok = res.get("ok") and res.get("api_version") == API_VERSION
+        detail = f"api_version={res.get('api_version')} version={res.get('version')} chrome={res.get('chrome_running')} x11={res.get('x11_running')}"
+        if res.get("api_version") != API_VERSION:
+            detail += f" (this CLI speaks api_version={API_VERSION} — upgrade/downgrade to match)"
+        checks.append(_check("daemon http api", api_ok, detail))
+
+    if args.json:
+        failed = [c for c in checks if c["required"] and not c["ok"]]
+        print(json.dumps({"ok": not failed, "checks": checks}, indent=2))
+    else:
+        print("== browser-agent doctor ==")
+        for c in checks:
+            mark = "✓" if c["ok"] else ("✗" if c["required"] else "!")
+            opt = "" if c["required"] else " (optional)"
+            print(f" {mark} {c['name']}{opt}" + (f" — {c['detail']}" if c["detail"] else ""))
+        failed = [c for c in checks if c["required"] and not c["ok"]]
+        print()
+        print("OK" if not failed else f"FAIL: {len(failed)} required check(s) failed: " + ", ".join(c["name"] for c in failed))
+    return 0 if not any(c["required"] and not c["ok"] for c in checks) else 1
+
+
+# ---------------------------------------------------------------------------
+# argument parsing & dispatch
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--port", type=int, default=DEFAULT_PORT, help="Daemon HTTP port (default: 8765)")
+
+    parser = argparse.ArgumentParser(prog="browser-agent", description="Real Chrome + X11 Mouse Agent", parents=[common])
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_serve = sub.add_parser("serve", parents=[common], help="Run the localhost HTTP daemon (127.0.0.1:8765)")
+    p_serve.add_argument("--idle-timeout", type=int, default=DEFAULT_IDLE_TIMEOUT)
+
+    sub.add_parser("status", parents=[common], help="Show Browser Agent daemon & X11 status")
+    sub.add_parser("stop", parents=[common], help="Hibernate Chrome and Xvfb immediately to free RAM")
+
+    p_fetch = sub.add_parser("fetch", parents=[common], help="Open URL in real Chrome, solve Cloudflare, extract page")
+    p_fetch.add_argument("url")
+    p_fetch.add_argument("--wait", type=float, default=3.5, help="Wait seconds after navigation")
+    p_fetch.add_argument("--text", action="store_true", help="Print extracted article text only")
+    p_fetch.add_argument("--html", action="store_true", help="Print outer HTML only")
+    p_fetch.add_argument("--screenshot", type=str, default="", help="Save PNG screenshot to path")
+    p_fetch.add_argument("--proxy", action="store_true", help="Route through local WARP SOCKS5 (127.0.0.1:40000)")
+
+    p_click = sub.add_parser("click", parents=[common], help="Move real X11 mouse along a Bezier curve and click (x, y)")
+    p_click.add_argument("x", type=int)
+    p_click.add_argument("y", type=int)
+    p_click.add_argument("--double", action="store_true")
+
+    p_move = sub.add_parser("move", parents=[common], help="Move real X11 mouse along a Bezier curve to (x, y)")
+    p_move.add_argument("x", type=int)
+    p_move.add_argument("y", type=int)
+
+    p_type = sub.add_parser("type", parents=[common], help="Type text via the X11 keyboard")
+    p_type.add_argument("text")
+    p_type.add_argument("--submit", action="store_true")
+
+    p_agent = sub.add_parser("agent", parents=[common], help="Run the vision-guided computer-use agent on a URL")
+    p_agent.add_argument("url")
+    p_agent.add_argument("goal")
+    p_agent.add_argument("--max-steps", type=int, default=8)
+    p_agent.add_argument("--proxy", action="store_true")
+
+    p_vnc = sub.add_parser("vnc", parents=[common], help="Start or stop the localhost VNC server (127.0.0.1:5900)")
+    p_vnc.add_argument("mode", choices=["start", "stop"], default="start", nargs="?")
+
+    p_setup = sub.add_parser("setup", parents=[common], help="Provision a Linux host (apt, Chrome, systemd unit)")
+    p_setup.add_argument("--no-apt", action="store_true", help="Do not install apt packages")
+    p_setup.add_argument("--with-chrome", action="store_true", help="Install google-chrome-stable from Google's apt repo")
+    p_setup.add_argument("--no-unit", action="store_true", help="Do not write the systemd unit")
+    p_setup.add_argument("--no-start", action="store_true", help="Write the unit but do not enable/start it")
+    p_setup.add_argument("--user", default="", help="User for the systemd unit (default: current user)")
+    p_setup.add_argument("--env-file", default="/etc/browser-agent.env", help="EnvironmentFile for the unit")
+    p_setup.add_argument("--memory-high", default="450M")
+    p_setup.add_argument("--memory-max", default="600M")
+    p_setup.add_argument("--idle-timeout", type=int, default=DEFAULT_IDLE_TIMEOUT)
+    p_setup.add_argument("--dry-run", action="store_true", help="Print what would happen, change nothing")
+
+    p_doctor = sub.add_parser("doctor", parents=[common], help="Self-check this host and the running daemon")
+    p_doctor.add_argument("--json", action="store_true", help="Machine-readable output")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(name)s] %(message)s", datefmt="%H:%M:%S")
+    args = build_parser().parse_args(argv)
+
+    if args.cmd == "serve":
+        return serve(port=args.port, idle_timeout=args.idle_timeout)
+
+    if args.cmd == "status":
+        res = _api_request("GET", "/status", port=args.port, timeout=5.0)
+        if res is None:
+            print(json.dumps({"ok": False, "daemon_running": False}, indent=2))
+            return 1
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+        return 0
+
+    if args.cmd == "stop":
+        res = _api_request("POST", "/action", {"action": "stop"}, port=args.port, timeout=10.0)
+        print(json.dumps(res or {"ok": True, "note": "daemon not running"}, indent=2))
+        return 0
+
+    if args.cmd == "fetch":
+        payload = {
+            "url": args.url,
+            "wait_sec": args.wait,
+            "solve_cloudflare": True,
+            "use_proxy": True if args.proxy else None,
+            "include_screenshot": bool(args.screenshot),
+        }
+        res = _api_request("POST", "/fetch", payload, port=args.port, timeout=90.0)
+        if res is None:
+            # Fallback: run a one-shot coordinator in-process when the daemon is down
+            from .server import BrowserCoordinator
+
+            coord = BrowserCoordinator()
+            try:
+                res = coord.fetch(payload)
+            finally:
+                coord.shutdown()
+        if args.screenshot and res.get("screenshot_b64"):
+            Path(args.screenshot).write_bytes(base64.b64decode(res["screenshot_b64"]))
+            res["screenshot_saved"] = args.screenshot
+            res.pop("screenshot_b64", None)
+        if args.text:
+            print(res.get("text") or "")
+        elif args.html:
+            print(res.get("html") or "")
+        else:
+            out = {k: v for k, v in res.items() if k != "html"}
+            out["html_len"] = len(res.get("html") or "")
+            print(json.dumps(out, indent=2, ensure_ascii=False))
+        return 0 if res.get("ok") else 1
+
+    if args.cmd in ("click", "move", "type", "vnc"):
+        if args.cmd == "click":
+            act_payload = {"action": "click", "x": args.x, "y": args.y, "double": args.double}
+        elif args.cmd == "move":
+            act_payload = {"action": "move", "x": args.x, "y": args.y}
+        elif args.cmd == "type":
+            act_payload = {"action": "type", "text": args.text, "submit": args.submit}
+        else:
+            act_payload = {"action": f"vnc_{args.mode}"}
+        res = _api_request("POST", "/action", act_payload, port=args.port, timeout=30.0)
+        if res is None:
+            print("Error: browser-agent daemon is not running (start with: systemctl start browser-agent)", file=sys.stderr)
+            return 1
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+        return 0 if res.get("ok") else 1
+
+    if args.cmd == "agent":
+        payload = {"url": args.url, "goal": args.goal, "max_steps": args.max_steps, "use_proxy": True if args.proxy else None}
+        res = _api_request("POST", "/agent", payload, port=args.port, timeout=180.0)
+        if res is None:
+            from .server import BrowserCoordinator
+
+            coord = BrowserCoordinator()
+            try:
+                res = coord.agent(payload)
+            finally:
+                coord.shutdown()
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+        return 0 if res.get("ok") else 1
+
+    if args.cmd == "setup":
+        return cmd_setup(args)
+    if args.cmd == "doctor":
+        return cmd_doctor(args)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

browser_agent/data/browser-agent.service

@@ -0,0 +1,26 @@
+[Unit]
+Description=browser-agent: Real Chrome + X11 Mouse daemon (localhost:{{PORT}})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User={{USER}}
+EnvironmentFile=-{{ENV_FILE}}
+Environment=BROWSER_AGENT_PORT={{PORT}}
+Environment=BROWSER_AGENT_IDLE_SEC={{IDLE}}
+# Memory discipline: the daemon must never starve co-tenant services on a
+# small VPS. Chrome auto-hibernates after {{IDLE}}s of idle time (~12 MB
+# resting state). Tune for your box with `browser-agent setup --memory-*`.
+MemoryHigh={{MEMORY_HIGH}}
+MemoryMax={{MEMORY_MAX}}
+OOMScoreAdjust=500
+ExecStart={{EXEC_START}} serve --port {{PORT}} --idle-timeout {{IDLE}}
+Restart=on-failure
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=browser-agent
+
+[Install]
+WantedBy=multi-user.target