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

browser_agent/server.py

@@ -0,0 +1,250 @@
+"""Local HTTP daemon (127.0.0.1:8765) for system-wide Browser Agent access.
+
+The daemon owns a single real-Chrome session (``BrowserCoordinator``),
+guards it with a global mutex and hibernates Chrome + Xvfb after an idle
+timeout so a small VPS can keep the listener resident at ~12 MB RAM.
+
+Public HTTP contract — API version 1 (see docs/api.md):
+    GET  /status   (aliases: /, /health)
+    POST /fetch
+    POST /action
+    POST /agent
+"""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .chrome import RealChromeSession, is_warp_proxy_ready
+from .vision_agent import run_vision_agent
+
+log = logging.getLogger("browser_agent.server")
+
+try:
+    __version__ = _pkg_version("browser-agent-server")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0.0.0+local"
+
+#: Version of the public HTTP contract exposed by this daemon.
+API_VERSION = 1
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = int(os.environ.get("BROWSER_AGENT_PORT", "8765"))
+DEFAULT_IDLE_TIMEOUT = int(os.environ.get("BROWSER_AGENT_IDLE_SEC", "60"))
+
+
+class BrowserCoordinator:
+    """Thread-safe single-tab Chrome + X11 manager with automatic idle hibernation."""
+
+    def __init__(self, idle_timeout_sec: int = DEFAULT_IDLE_TIMEOUT):
+        self.lock = threading.RLock()
+        self.session = RealChromeSession()
+        self.idle_timeout_sec = max(15, int(idle_timeout_sec))
+        self._stop_reaper = threading.Event()
+        self._reaper = threading.Thread(target=self._reap_loop, daemon=True)
+        self._reaper.start()
+
+    def _reap_loop(self) -> None:
+        while not self._stop_reaper.wait(5.0):
+            if self.lock.acquire(blocking=False):
+                try:
+                    if (
+                        (self.session.is_running() or self.session.x11.is_running())
+                        and time.time() - self.session.last_used > self.idle_timeout_sec
+                    ):
+                        log.info(
+                            "Idle timeout (%ds) reached — hibernating Chrome & Xvfb to free RAM",
+                            self.idle_timeout_sec,
+                        )
+                        self.session.stop()
+                finally:
+                    self.lock.release()
+
+    def status(self) -> dict:
+        return {
+            "ok": True,
+            "api_version": API_VERSION,
+            "version": __version__,
+            "chrome_running": self.session.is_running(),
+            "x11_running": self.session.x11.is_running(),
+            "display": self.session.x11.display,
+            "resolution": f"{self.session.x11.width}x{self.session.x11.height}",
+            "mouse_pos": list(self.session.x11.mouse_pos),
+            "warp_proxy_ready": is_warp_proxy_ready(),
+            "idle_seconds": round(time.time() - self.session.last_used, 1),
+            "idle_timeout_sec": self.idle_timeout_sec,
+        }
+
+    def fetch(self, payload: dict) -> dict:
+        with self.lock:
+            url = str(payload.get("url") or "").strip()
+            if not url:
+                raise ValueError("Missing 'url' parameter")
+            return self.session.fetch_page(
+                url=url,
+                wait_sec=float(payload.get("wait_sec", 3.5)),
+                solve_cloudflare=bool(payload.get("solve_cloudflare", True)),
+                use_proxy=payload.get("use_proxy"),
+                include_screenshot=bool(payload.get("include_screenshot", False)),
+            )
+
+    def action(self, payload: dict) -> dict:
+        with self.lock:
+            act = str(payload.get("action") or "").strip().lower()
+            self.session.last_used = time.time()
+
+            if act == "stop":
+                self.session.stop()
+                return {"ok": True, "stopped": True}
+            if act == "vnc_start":
+                ok = self.session.x11.start_vnc(int(payload.get("port", 5900)))
+                return {"ok": ok, "vnc_port": int(payload.get("port", 5900))}
+            if act == "vnc_stop":
+                self.session.x11.stop_vnc()
+                return {"ok": True}
+
+            self.session.start(use_proxy=payload.get("use_proxy"))
+
+            if act == "goto":
+                url = str(payload.get("url") or "").strip()
+                cdp = self.session._connect_page_cdp()
+                try:
+                    cdp.call("Page.navigate", {"url": url})
+                finally:
+                    cdp.close()
+                time.sleep(float(payload.get("wait_sec", 2.5)))
+                if payload.get("solve_cloudflare", True):
+                    self.session.solve_cloudflare_if_present()
+                cur_url, title, _ = self.session.get_html_and_title()
+                return {"ok": True, "url": cur_url, "title": title}
+
+            if act == "move":
+                pos = self.session.x11.move_mouse(int(payload["x"]), int(payload["y"]))
+                return {"ok": True, "mouse_pos": list(pos)}
+
+            if act == "click":
+                pos = self.session.x11.click(
+                    x=int(payload["x"]) if payload.get("x") is not None else None,
+                    y=int(payload["y"]) if payload.get("y") is not None else None,
+                    button=int(payload.get("button", 1)),
+                    double=bool(payload.get("double", False)),
+                )
+                return {"ok": True, "mouse_pos": list(pos)}
+
+            if act == "type":
+                self.session.x11.type_text(str(payload.get("text") or ""), submit=bool(payload.get("submit", False)))
+                return {"ok": True}
+
+            if act == "key":
+                self.session.x11.press_key(str(payload.get("key") or "Return"))
+                return {"ok": True}
+
+            if act == "scroll":
+                self.session.x11.scroll(
+                    clicks=int(payload.get("clicks", 4)),
+                    direction=str(payload.get("direction", "down")),
+                    x=int(payload["x"]) if payload.get("x") is not None else None,
+                    y=int(payload["y"]) if payload.get("y") is not None else None,
+                )
+                return {"ok": True}
+
+            if act == "screenshot":
+                raw = self.session.x11.screenshot_bytes()
+                return {"ok": True, "screenshot_b64": base64.b64encode(raw).decode("ascii")}
+
+            if act == "html":
+                cur_url, title, html = self.session.get_html_and_title()
+                return {"ok": True, "url": cur_url, "title": title, "html": html}
+
+            raise ValueError(f"Unknown action: {act!r}")
+
+    def agent(self, payload: dict) -> dict:
+        with self.lock:
+            url = str(payload.get("url") or "").strip()
+            goal = str(payload.get("goal") or "").strip()
+            if not goal:
+                raise ValueError("Missing 'goal' parameter")
+            return run_vision_agent(
+                session=self.session,
+                url=url,
+                goal=goal,
+                max_steps=int(payload.get("max_steps", 8)),
+                use_proxy=payload.get("use_proxy"),
+            )
+
+    def shutdown(self) -> None:
+        self._stop_reaper.set()
+        with self.lock:
+            self.session.stop()
+
+
+def make_handler(coord: BrowserCoordinator):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, fmt: str, *args) -> None:
+            log.info("%s - %s", self.address_string(), fmt % args)
+
+        def _send_json(self, code: int, data: dict) -> None:
+            body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _read_json(self) -> dict:
+            length = int(self.headers.get("Content-Length") or 0)
+            if length <= 0:
+                return {}
+            return json.loads(self.rfile.read(length).decode("utf-8"))
+
+        def do_GET(self) -> None:  # noqa: N802
+            if self.path.rstrip("/") in ("", "/health", "/status"):
+                self._send_json(200, coord.status())
+            else:
+                self._send_json(404, {"ok": False, "error": "Not found"})
+
+        def do_POST(self) -> None:  # noqa: N802
+            try:
+                payload = self._read_json()
+                path = self.path.rstrip("/")
+                if path == "/fetch":
+                    self._send_json(200, coord.fetch(payload))
+                elif path == "/action":
+                    self._send_json(200, coord.action(payload))
+                elif path == "/agent":
+                    self._send_json(200, coord.agent(payload))
+                else:
+                    self._send_json(404, {"ok": False, "error": f"Unknown endpoint {path}"})
+            except Exception as e:  # noqa: BLE001
+                log.warning("Request %s failed: %s", self.path, e)
+                self._send_json(500, {"ok": False, "error": str(e)})
+
+    return Handler
+
+
+def serve(host: str = DEFAULT_HOST, port: int = DEFAULT_PORT, idle_timeout: int = DEFAULT_IDLE_TIMEOUT) -> int:
+    """Run the localhost HTTP daemon in the foreground. Returns process exit code."""
+    coord = BrowserCoordinator(idle_timeout_sec=idle_timeout)
+    srv = ThreadingHTTPServer((host, port), make_handler(coord))
+    log.info("Browser Agent daemon listening on http://%s:%d (idle_timeout=%ds)", host, port, idle_timeout)
+    try:
+        srv.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        coord.shutdown()
+    return 0
+
+
+if __name__ == "__main__":
+    # Compatibility with `python -m browser_agent.server ...`
+    from .cli import main
+
+    raise SystemExit(main())

browser_agent/vision_agent.py

@@ -0,0 +1,165 @@
+"""Vision-guided Computer Use loop powered by Gemini Flash and hardware-level X11 mouse/keyboard."""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import re
+import time
+import urllib.request
+
+from .chrome import RealChromeSession, _extract_text_from_html
+
+log = logging.getLogger("browser_agent.vision")
+
+VISION_MODELS = (
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+    "gemini-3-flash-preview",
+)
+
+SYSTEM_PROMPT = """You are a Linux X11 desktop browser agent controlling a real Chrome window (resolution 1280x720).
+Given the user's goal, current URL, action history, and current 1280x720 screenshot, return ONLY a JSON object with the next action:
+{
+  "thought": "Brief reasoning about what is visible on screen and what to do next",
+  "action": "click" | "type" | "scroll" | "key" | "wait" | "done",
+  "x": 640,          // integer X coordinate (0..1280) for click/scroll
+  "y": 360,          // integer Y coordinate (0..720) for click/scroll
+  "text": "...",     // text to type when action == "type"
+  "submit": true,    // press Enter after typing when action == "type"
+  "direction": "down", // "down" or "up" when action == "scroll"
+  "key": "Return",   // X11 key name when action == "key" (e.g. "Return", "Escape", "Tab", "Page_Down")
+  "result": "..."    // final extracted answer or summary when action == "done"
+}"""
+
+
+def _collect_api_keys() -> list[str]:
+    keys: list[str] = []
+    for var in ("GEMINI_API_KEY", "LLM_API_KEY", "GEMINI_API_KEYS", *[f"GEMINI_API_KEY_{i}" for i in range(1, 11)]):
+        val = os.environ.get(var, "").strip()
+        if val:
+            for part in re.split(r"[\s,;]+", val):
+                if part and part not in keys:
+                    keys.append(part)
+    return keys
+
+
+def _call_gemini_vision(screenshot_png: bytes, prompt_text: str, keys: list[str]) -> dict:
+    if not keys:
+        raise RuntimeError(
+            "No Gemini API key found in environment (set GEMINI_API_KEY or GEMINI_API_KEYS in .env)."
+        )
+    b64_img = base64.b64encode(screenshot_png).decode("ascii")
+    payload = json.dumps({
+        "contents": [{
+            "parts": [
+                {"text": f"{SYSTEM_PROMPT}\n\n{prompt_text}"},
+                {"inline_data": {"mime_type": "image/png", "data": b64_img}},
+            ],
+        }],
+        "generationConfig": {
+            "temperature": 0.2,
+            "maxOutputTokens": 1024,
+            "responseMimeType": "application/json",
+        },
+    }).encode("utf-8")
+
+    last_err = ""
+    for key in keys:
+        for model in VISION_MODELS:
+            url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={key}"
+            req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
+            try:
+                with urllib.request.urlopen(req, timeout=25) as resp:
+                    body = json.loads(resp.read().decode("utf-8"))
+                    parts = (body.get("candidates") or [])[0]["content"]["parts"]
+                    raw_text = "".join(p.get("text", "") for p in parts).strip()
+                    cleaned = re.sub(r"^```[a-zA-Z]*\s*|\s*```$", "", raw_text)
+                    obj, _ = json.JSONDecoder().raw_decode(cleaned.lstrip())
+                    if isinstance(obj, dict):
+                        return obj
+            except Exception as e:  # noqa: BLE001
+                last_err = f"{model}: {e}"
+                continue
+    raise RuntimeError(f"All Gemini Vision calls failed ({last_err})")
+
+
+def run_vision_agent(
+    session: RealChromeSession,
+    url: str,
+    goal: str,
+    max_steps: int = 8,
+    use_proxy: bool | None = None,
+) -> dict:
+    """Navigate to `url` and execute a Vision + X11 mouse/keyboard loop until `goal` is achieved."""
+    keys = _collect_api_keys()
+    session.start(use_proxy=use_proxy)
+
+    if url:
+        cdp = session._connect_page_cdp()
+        try:
+            cdp.call("Page.navigate", {"url": url})
+        finally:
+            cdp.close()
+        time.sleep(3.0)
+        session.solve_cloudflare_if_present()
+
+    history: list[dict] = []
+    final_result = ""
+
+    for step in range(1, max(1, min(20, int(max_steps))) + 1):
+        session.last_used = time.time()
+        cur_url, title, _ = session.get_html_and_title()
+        screenshot = session.x11.screenshot_bytes()
+
+        prompt = (
+            f"Goal: {goal}\n"
+            f"Current URL: {cur_url}\n"
+            f"Page Title: {title}\n"
+            f"Step: {step}/{max_steps}\n"
+            f"Previous actions: {json.dumps(history[-5:], ensure_ascii=False)}"
+        )
+        decision = _call_gemini_vision(screenshot, prompt, keys)
+        action = str(decision.get("action") or "done").lower()
+        thought = str(decision.get("thought") or "")
+        log.info("[Vision step %d/%d] action=%s thought=%s", step, max_steps, action, thought)
+        history.append({"step": step, **decision})
+
+        if action == "done":
+            final_result = str(decision.get("result") or thought)
+            break
+        if action == "click":
+            x = int(decision.get("x") or session.x11.width // 2)
+            y = int(decision.get("y") or session.x11.height // 2)
+            session.x11.click(x, y)
+            time.sleep(2.0)
+        elif action == "type":
+            if decision.get("x") is not None and decision.get("y") is not None:
+                session.x11.click(int(decision["x"]), int(decision["y"]))
+                time.sleep(0.3)
+            session.x11.type_text(str(decision.get("text") or ""), submit=bool(decision.get("submit", True)))
+            time.sleep(2.0)
+        elif action == "scroll":
+            session.x11.scroll(
+                clicks=int(decision.get("clicks") or 5),
+                direction=str(decision.get("direction") or "down"),
+                x=int(decision.get("x") or session.x11.width // 2),
+                y=int(decision.get("y") or session.x11.height // 2),
+            )
+            time.sleep(1.2)
+        elif action == "key":
+            session.x11.press_key(str(decision.get("key") or "Return"))
+            time.sleep(1.2)
+        elif action == "wait":
+            time.sleep(min(5.0, float(decision.get("seconds") or 2.0)))
+
+    cur_url, title, html = session.get_html_and_title()
+    return {
+        "ok": True,
+        "url": cur_url,
+        "title": title,
+        "result": final_result or (history[-1].get("thought", "") if history else ""),
+        "steps": history,
+        "text": _extract_text_from_html(html, cur_url)[:8000],
+    }

browser_agent/x11_input.py

@@ -0,0 +1,273 @@
+"""Hardware-level X11 display, window manager, screenshot, and human-like mouse/keyboard control."""
+from __future__ import annotations
+
+import logging
+import math
+import os
+import random
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+log = logging.getLogger("browser_agent.x11")
+
+
+def bezier_curve(
+    start: tuple[int, int],
+    end: tuple[int, int],
+    steps: int | None = None,
+    spread: float = 0.18,
+) -> list[tuple[int, int]]:
+    """Generate a human-like cubic Bezier mouse path with ease-in/out pacing and micro-jitter."""
+    x0, y0 = start
+    x3, y3 = end
+    dist = math.hypot(x3 - x0, y3 - y0)
+    if dist < 2:
+        return [(x3, y3)]
+
+    if steps is None:
+        steps = max(8, min(45, int(dist / 18)))
+
+    dx, dy = x3 - x0, y3 - y0
+    perp_x, perp_y = -dy, dx
+    offset1 = random.uniform(-spread, spread)
+    offset2 = random.uniform(-spread, spread)
+
+    x1 = x0 + dx * random.uniform(0.2, 0.35) + perp_x * offset1
+    y1 = y0 + dy * random.uniform(0.2, 0.35) + perp_y * offset1
+    x2 = x0 + dx * random.uniform(0.65, 0.85) + perp_x * offset2
+    y2 = y0 + dy * random.uniform(0.65, 0.85) + perp_y * offset2
+
+    points: list[tuple[int, int]] = []
+    for i in range(1, steps + 1):
+        raw_t = i / steps
+        # Smoothstep ease-in / ease-out velocity profile
+        t = raw_t * raw_t * (3.0 - 2.0 * raw_t)
+        u = 1.0 - t
+        bx = (u**3) * x0 + 3 * (u**2) * t * x1 + 3 * u * (t**2) * x2 + (t**3) * x3
+        by = (u**3) * y0 + 3 * (u**2) * t * y1 + 3 * u * (t**2) * y2 + (t**3) * y3
+        if i < steps:
+            bx += random.gauss(0, 0.6)
+            by += random.gauss(0, 0.6)
+        pt = (max(0, int(round(bx))), max(0, int(round(by))))
+        if not points or points[-1] != pt:
+            points.append(pt)
+
+    if points[-1] != (x3, y3):
+        points.append((x3, y3))
+    return points
+
+
+class X11Display:
+    """Manages an on-demand Xvfb virtual screen, openbox window manager, and xdotool input."""
+
+    def __init__(self, display: str = ":99", width: int = 1280, height: int = 720, depth: int = 24):
+        self.display = display
+        self.width = width
+        self.height = height
+        self.depth = depth
+        self._xvfb_proc: subprocess.Popen | None = None
+        self._wm_proc: subprocess.Popen | None = None
+        self._vnc_proc: subprocess.Popen | None = None
+        self.mouse_pos: tuple[int, int] = (width // 2, height // 2)
+
+    @property
+    def env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        env["DISPLAY"] = self.display
+        return env
+
+    def is_running(self) -> bool:
+        return self._xvfb_proc is not None and self._xvfb_proc.poll() is None
+
+    def start(self) -> None:
+        if self.is_running():
+            return
+        display_num = self.display.lstrip(":")
+        lock_file = Path(f"/tmp/.X{display_num}-lock")
+        socket_file = Path(f"/tmp/.X11-unix/X{display_num}")
+        if lock_file.exists():
+            try:
+                lock_file.unlink()
+            except OSError:
+                pass
+        if socket_file.exists():
+            try:
+                socket_file.unlink()
+            except OSError:
+                pass
+
+        self._xvfb_proc = subprocess.Popen(
+            [
+                "Xvfb",
+                self.display,
+                "-screen",
+                "0",
+                f"{self.width}x{self.height}x{self.depth}",
+                "-ac",
+                "-nolisten",
+                "tcp",
+                "-dpi",
+                "96",
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+        )
+        time.sleep(0.4)
+        if self._xvfb_proc.poll() is not None:
+            err = (self._xvfb_proc.stderr.read().decode("utf-8", errors="replace") if self._xvfb_proc.stderr else "").strip()
+            raise RuntimeError(f"Xvfb failed to start on {self.display} (rc={self._xvfb_proc.returncode}): {err[:300]}")
+        if shutil.which("openbox"):
+            self._wm_proc = subprocess.Popen(
+                ["openbox"],
+                env=self.env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            time.sleep(0.2)
+        log.info("X11 display %s started (%dx%d)", self.display, self.width, self.height)
+
+    def stop(self) -> None:
+        self.stop_vnc()
+        for proc in (self._wm_proc, self._xvfb_proc):
+            if proc and proc.poll() is None:
+                proc.terminate()
+                try:
+                    proc.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+        self._wm_proc = None
+        self._xvfb_proc = None
+
+    def start_vnc(self, port: int = 5900) -> bool:
+        """Start localhost-only x11vnc for live debugging over SSH tunnel."""
+        self.start()
+        if self._vnc_proc and self._vnc_proc.poll() is None:
+            return True
+        if not shutil.which("x11vnc"):
+            return False
+        self._vnc_proc = subprocess.Popen(
+            [
+                "x11vnc",
+                "-display",
+                self.display,
+                "-localhost",
+                "-nopw",
+                "-forever",
+                "-shared",
+                "-noxdamage",
+                "-rfbport",
+                str(port),
+                "-quiet",
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        return True
+
+    def stop_vnc(self) -> None:
+        if self._vnc_proc and self._vnc_proc.poll() is None:
+            self._vnc_proc.terminate()
+            try:
+                self._vnc_proc.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                self._vnc_proc.kill()
+        self._vnc_proc = None
+
+    def _xdotool(self, *args: str, timeout: float = 10.0) -> str:
+        self.start()
+        res = subprocess.run(
+            ["xdotool", *args],
+            env=self.env,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+        return res.stdout.strip()
+
+    def move_mouse(self, x: int, y: int, duration: float | None = None) -> tuple[int, int]:
+        """Move the real X11 cursor along a human-like Bezier trajectory to (x, y)."""
+        x = max(1, min(self.width - 2, int(x)))
+        y = max(1, min(self.height - 2, int(y)))
+        dist = math.hypot(x - self.mouse_pos[0], y - self.mouse_pos[1])
+        if dist < 2:
+            self._xdotool("mousemove", str(x), str(y))
+            self.mouse_pos = (x, y)
+            return self.mouse_pos
+
+        path = bezier_curve(self.mouse_pos, (x, y))
+        if duration is None:
+            duration = max(0.08, min(0.45, dist / 1600.0 + random.uniform(0.03, 0.10)))
+
+        step_delay = duration / max(1, len(path))
+        for px, py in path:
+            self._xdotool("mousemove", str(px), str(py))
+            time.sleep(max(0.003, step_delay * random.uniform(0.75, 1.25)))
+
+        self.mouse_pos = (x, y)
+        return self.mouse_pos
+
+    def click(
+        self,
+        x: int | None = None,
+        y: int | None = None,
+        button: int = 1,
+        double: bool = False,
+        jitter: int = 2,
+    ) -> tuple[int, int]:
+        """Move humanly to (x, y) if given and perform a hardware-level X11 mouse click."""
+        if x is not None and y is not None:
+            tx = int(x) + (random.randint(-jitter, jitter) if jitter > 0 else 0)
+            ty = int(y) + (random.randint(-jitter, jitter) if jitter > 0 else 0)
+            self.move_mouse(tx, ty)
+
+        time.sleep(random.uniform(0.03, 0.08))
+        clicks = 2 if double else 1
+        for i in range(clicks):
+            self._xdotool("mousedown", str(button))
+            time.sleep(random.uniform(0.055, 0.125))
+            self._xdotool("mouseup", str(button))
+            if i + 1 < clicks:
+                time.sleep(random.uniform(0.06, 0.11))
+        return self.mouse_pos
+
+    def scroll(self, clicks: int = 4, direction: str = "down", x: int | None = None, y: int | None = None) -> None:
+        if x is not None and y is not None:
+            self.move_mouse(x, y)
+        btn = "5" if direction.lower() in ("down", "d") else "4"
+        for _ in range(max(1, abs(int(clicks)))):
+            self._xdotool("click", btn)
+            time.sleep(random.uniform(0.04, 0.09))
+
+    def type_text(self, text: str, submit: bool = False) -> None:
+        delay_ms = random.randint(35, 75)
+        self._xdotool("type", "--clearmodifiers", "--delay", str(delay_ms), "--", text, timeout=30.0)
+        if submit:
+            time.sleep(random.uniform(0.08, 0.18))
+            self.press_key("Return")
+
+    def press_key(self, key: str) -> None:
+        self._xdotool("key", "--clearmodifiers", key)
+
+    def screenshot_bytes(self) -> bytes:
+        """Capture X11 screen via scrot into /tmp and immediately delete the temporary file."""
+        self.start()
+        tmp_path = Path(f"/tmp/ba_screen_{os.getpid()}_{int(time.time() * 1000)}.png")
+        try:
+            subprocess.run(
+                ["scrot", "--overwrite", str(tmp_path)],
+                env=self.env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+                check=True,
+            )
+            return tmp_path.read_bytes()
+        finally:
+            if tmp_path.exists():
+                try:
+                    tmp_path.unlink()
+                except OSError:
+                    pass