Skip to content

Agent Zero AI framework

Harden internal Browser against bot detection

Alessandroe2f43a3fb8df
diff --git a/docker/run/fs/ins/install_additional.sh b/docker/run/fs/ins/install_additional.sh
index e9c844be7..257247d17 100644
--- a/docker/run/fs/ins/install_additional.sh
+++ b/docker/run/fs/ins/install_additional.sh
@@ -99,6 +99,7 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
x11-xserver-utils \
xdotool \
xauth \
+ xvfb \
dbus-x11 \
fonts-dejavu \
fonts-liberation \
diff --git a/docker/run/fs/ins/install_playwright.sh b/docker/run/fs/ins/install_playwright.sh
index ca257004a..d5fc31e42 100644
--- a/docker/run/fs/ins/install_playwright.sh
+++ b/docker/run/fs/ins/install_playwright.sh
@@ -4,13 +4,10 @@ set -e
# activate venv
. "/ins/setup_venv.sh" "$@"
-# install playwright if not installed (should be from requirements.txt)
-uv pip install playwright
-
# set PW installation path to temporary Browser runtime storage
export PLAYWRIGHT_BROWSERS_PATH=/a0/tmp/playwright
mkdir -p "$PLAYWRIGHT_BROWSERS_PATH"
-# install chromium with dependencies
+# preinstall Chromium for fresh images; the Browser hook also reconciles self-updated installs
apt-get install -y fonts-unifont libnss3 libnspr4 libatk1.0-0 libatspi2.0-0 libxcomposite1 libxdamage1 libatk-bridge2.0-0 libcups2
-playwright install chromium
+patchright install chromium --no-shell
diff --git a/docs/guides/browser.md b/docs/guides/browser.md
index a005c252a..586384228 100644
--- a/docs/guides/browser.md
+++ b/docs/guides/browser.md
@@ -234,7 +234,7 @@ See [MCP Setup](mcp-setup.md) for MCP setup.
## Troubleshooting
-- **Browser says Playwright is missing:** Docker installs already include the browser. In local development, let Agent Zero install it on first use or preinstall it with `PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium`.
+- **Browser says Chromium is missing:** Docker installs already include the browser. In local development, let Agent Zero install it on first use or preinstall it with `PLAYWRIGHT_BROWSERS_PATH=tmp/playwright patchright install chromium --no-shell`.
- **The Browser surface does not open automatically:** That is expected. Open the Browser surface manually or ask the agent to show it.
- **The Canvas does not follow the agent:** Enable **Autofocus active page** in Browser settings.
- **Bring Your Own Browser cannot start:** Keep A0 CLI connected, verify Browser location is **Bring Your Own Browser**, and check `/browser status` in A0 CLI.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 21f8e979e..05a3cf02f 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -26,7 +26,7 @@ Refer to the [Choosing your LLMs](../setup/installation.md#installing-and-using-
**7. How can I make Agent Zero retain memory between sessions?**
Use **Settings -> Backup & Restore** and avoid mapping the entire `/a0` directory. See [How to update Agent Zero](../setup/installation.md#how-to-update-agent-zero).
-**8. My browser tool fails or says Playwright is missing. What now?**
+**8. My browser tool fails or says Chromium is missing. What now?**
In normal Docker installs, the Browser already includes what it needs.
@@ -35,7 +35,7 @@ browser the first time it is needed. To install it ahead of time, run this from
the project root after installing Python requirements:
```bash
-PLAYWRIGHT_BROWSERS_PATH=tmp/playwright playwright install chromium
+PLAYWRIGHT_BROWSERS_PATH=tmp/playwright patchright install chromium --no-shell
```
If **Bring Your Own Browser** mode fails:
diff --git a/docs/setup/dev-setup.md b/docs/setup/dev-setup.md
index 5fd35fa17..d1390d0de 100644
--- a/docs/setup/dev-setup.md
+++ b/docs/setup/dev-setup.md
@@ -68,12 +68,12 @@ Now when you select one of the python files in the project, you should see prope
```bash
pip install -r requirements.txt
-PLAYWRIGHT_BROWSERS_PATH=./tmp/playwright playwright install chromium
+PLAYWRIGHT_BROWSERS_PATH=./tmp/playwright patchright install chromium --no-shell
```
The first command installs Python dependencies.
-The second command installs full Playwright Chromium into `./tmp/playwright`,
+The second command installs full Patchright Chromium into `./tmp/playwright`,
relative to the project root. Docker images use the absolute path
`/a0/tmp/playwright` and ship Chromium preinstalled.
diff --git a/plugins/_browser/AGENTS.md b/plugins/_browser/AGENTS.md
index b790991e4..bfe481621 100644
--- a/plugins/_browser/AGENTS.md
+++ b/plugins/_browser/AGENTS.md
@@ -32,6 +32,9 @@
- Do not hardcode user-specific browser paths or secrets.
- Browser model-preset selection resolves omitted preset fields from `_model_config`'s global `Default` preset, not from an unrelated currently scoped model selection.
- Internal-browser proxy settings map directly to Playwright's persistent-context proxy option, never to Bring Your Own Browser, and changes must restart active internal runtimes.
+- Run internal Chromium headful through Patchright on the private virtual display; do not add user-agent or header spoofing on top of the patched driver.
+- Browser startup and on-demand launch must converge on the Chromium revision declared by Patchright; let its installer select the host architecture rather than hardcoding x64 or ARM downloads.
+- `hooks.prepare_playwright_cache()` owns reconciliation of the pinned Patchright package and Chromium binary so repository self-updates and fresh images use the same setup path.
## Work Guidance
diff --git a/plugins/_browser/extensions/python/startup_migration/_20_browser_playwright_cache.py b/plugins/_browser/extensions/python/startup_migration/_20_browser_playwright_cache.py
index c30aa4b57..e76a19856 100644
--- a/plugins/_browser/extensions/python/startup_migration/_20_browser_playwright_cache.py
+++ b/plugins/_browser/extensions/python/startup_migration/_20_browser_playwright_cache.py
@@ -33,7 +33,7 @@ def _start_background_cache_migration() -> threading.Thread:
def _migrate_cache_safely() -> None:
try:
- _log_cache_migration_result(hooks.cleanup_playwright_cache())
+ _log_cache_migration_result(hooks.prepare_playwright_cache())
except Exception as exc:
PrintStyle.warning("Browser Playwright cache migration failed:", exc)
diff --git a/plugins/_browser/helpers/config.py b/plugins/_browser/helpers/config.py
index e412b652c..589eeeb31 100644
--- a/plugins/_browser/helpers/config.py
+++ b/plugins/_browser/helpers/config.py
@@ -30,11 +30,6 @@ DEFAULT_MAX_OPEN_TABS = 32
MIN_MAX_OPEN_TABS = 1
HARD_MAX_OPEN_TABS = 50
DEFAULT_HOST_BROWSER_PRIVACY_POLICY = "allow"
-BASE_BROWSER_ARGS = [
- "--no-sandbox",
- "--disable-dev-shm-usage",
- "--disable-gpu",
-]
def _normalize_extension_paths(value: Any) -> list[str]:
@@ -388,7 +383,7 @@ def describe_browser_extensions(settings: dict[str, Any] | None) -> dict[str, An
def build_browser_launch_config(settings: dict[str, Any] | None) -> dict[str, Any]:
config = normalize_browser_config(settings)
extensions = describe_browser_extensions(config)
- args = list(BASE_BROWSER_ARGS)
+ args: list[str] = []
channel: str | None = None
browser_mode = "chromium"
proxy = None
diff --git a/plugins/_browser/helpers/playwright.py b/plugins/_browser/helpers/playwright.py
index f1c91014f..f0463e4fa 100644
--- a/plugins/_browser/helpers/playwright.py
+++ b/plugins/_browser/helpers/playwright.py
@@ -1,12 +1,20 @@
+import atexit
+import json
import os
+import re
+import select
+import shutil
import subprocess
+import sys
+import threading
+from importlib import resources
from pathlib import Path
from helpers import files
FULL_CHROMIUM_PATTERNS = (
- "chromium-*/chrome-linux/chrome",
- "chromium-*/chrome-win/chrome.exe",
+ "chromium-*/chrome-linux*/chrome",
+ "chromium-*/chrome-win*/chrome.exe",
)
PLAYWRIGHT_CACHE_ENV = "A0_BROWSER_PLAYWRIGHT_CACHE_DIR"
PLAYWRIGHT_CACHE_DIR = ("tmp", "playwright")
@@ -14,6 +22,10 @@ RETIRED_PLAYWRIGHT_CACHE_DIRS = (
("usr", "plugins", "_browser", "playwright"),
("usr", "browser", "playwright"),
)
+_INSTALL_LOCK = threading.Lock()
+_DISPLAY_LOCK = threading.Lock()
+_DISPLAY_PROCESS: subprocess.Popen | None = None
+_DISPLAY_NAME = ""
def _primary_cache_dir() -> Path:
@@ -52,33 +64,139 @@ def configure_playwright_env() -> str:
return cache_dir
-def find_playwright_binary(cache_dir: Path) -> Path | None:
- for pattern in FULL_CHROMIUM_PATTERNS:
- binary = next(cache_dir.glob(pattern), None)
- if binary and binary.exists():
- return binary
- return None
+def ensure_browser_display() -> str:
+ global _DISPLAY_NAME, _DISPLAY_PROCESS
+
+ with _DISPLAY_LOCK:
+ if _DISPLAY_PROCESS and _DISPLAY_PROCESS.poll() is None:
+ return _DISPLAY_NAME
+
+ xvfb = shutil.which("Xvfb")
+ if not xvfb:
+ return ""
+
+ read_fd, write_fd = os.pipe()
+ try:
+ process = subprocess.Popen(
+ [
+ xvfb,
+ "-displayfd",
+ str(write_fd),
+ "-screen",
+ "0",
+ "1365x768x24",
+ "+extension",
+ "GLX",
+ "-nolisten",
+ "tcp",
+ "-noreset",
+ "-ac",
+ ],
+ stdin=subprocess.DEVNULL,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ pass_fds=(write_fd,),
+ )
+ except OSError:
+ os.close(read_fd)
+ return ""
+ finally:
+ os.close(write_fd)
+
+ try:
+ ready, _, _ = select.select([read_fd], [], [], 5)
+ display_number = os.read(read_fd, 32).decode().strip() if ready else ""
+ finally:
+ os.close(read_fd)
+
+ if not display_number.isdigit() or process.poll() is not None:
+ _terminate_browser_display(process)
+ return ""
+
+ _DISPLAY_PROCESS = process
+ _DISPLAY_NAME = f":{display_number}"
+ return _DISPLAY_NAME
+
+
+def close_browser_display() -> None:
+ global _DISPLAY_NAME, _DISPLAY_PROCESS
+
+ with _DISPLAY_LOCK:
+ process = _DISPLAY_PROCESS
+ _DISPLAY_PROCESS = None
+ _DISPLAY_NAME = ""
+ if process:
+ _terminate_browser_display(process)
+
+
+def _terminate_browser_display(process: subprocess.Popen) -> None:
+ if process.poll() is not None:
+ return
+ process.terminate()
+ try:
+ process.wait(timeout=2)
+ except subprocess.TimeoutExpired:
+ process.kill()
+ process.wait(timeout=2)
+
+
+def find_playwright_binary(cache_dir: Path, revision: str = "") -> Path | None:
+ prefix = f"chromium-{revision}" if revision.isdigit() else "chromium-*"
+ binaries = [
+ binary
+ for pattern in FULL_CHROMIUM_PATTERNS
+ for binary in cache_dir.glob(pattern.replace("chromium-*", prefix))
+ if binary.exists()
+ ]
+ return max(binaries, key=_chromium_revision) if binaries else None
+
+
+def _chromium_revision(binary: Path) -> int:
+ match = re.search(r"chromium-(\d+)", binary.as_posix())
+ return int(match.group(1)) if match else -1
def get_playwright_binary() -> Path | None:
- return find_playwright_binary(_primary_cache_dir())
+ cache_dir = _primary_cache_dir()
+ binary = find_playwright_binary(_primary_cache_dir())
+ revision = get_playwright_chromium_revision()
+ if revision and (not binary or _chromium_revision(binary) != int(revision)):
+ return find_playwright_binary(cache_dir, revision=revision)
+ return binary
+
+
+def get_playwright_chromium_revision() -> str:
+ try:
+ manifest = resources.files("patchright").joinpath("driver/package/browsers.json")
+ browsers = json.loads(manifest.read_text(encoding="utf-8"))["browsers"]
+ revision = next(
+ str(browser.get("revision", ""))
+ for browser in browsers
+ if browser.get("name") == "chromium"
+ )
+ except (ImportError, FileNotFoundError, KeyError, StopIteration, TypeError, ValueError):
+ return ""
+ return revision if revision.isdigit() else ""
def ensure_playwright_binary() -> Path:
- binary = get_playwright_binary()
- if binary:
+ with _INSTALL_LOCK:
+ binary = get_playwright_binary()
+ if binary:
+ return binary
+
+ cache_dir = configure_playwright_env()
+ env = os.environ.copy()
+ env["PLAYWRIGHT_BROWSERS_PATH"] = cache_dir
+ subprocess.check_call(
+ [sys.executable, "-m", "patchright", "install", "chromium", "--no-shell"],
+ env=env,
+ )
+
+ binary = get_playwright_binary()
+ if not binary:
+ raise RuntimeError("Patchright Chromium binary not found after installation")
return binary
- cache_dir = configure_playwright_env()
- env = os.environ.copy()
- env["PLAYWRIGHT_BROWSERS_PATH"] = cache_dir
- install_command = ["playwright", "install", "chromium"]
- subprocess.check_call(
- install_command,
- env=env,
- )
-
- binary = get_playwright_binary()
- if not binary:
- raise RuntimeError("Playwright Chromium binary not found after installation")
- return binary
+
+atexit.register(close_browser_display)
diff --git a/plugins/_browser/helpers/runtime.py b/plugins/_browser/helpers/runtime.py
index f5ac52866..040503cba 100644
--- a/plugins/_browser/helpers/runtime.py
+++ b/plugins/_browser/helpers/runtime.py
@@ -27,7 +27,9 @@ from plugins._browser.helpers.config import (
build_browser_launch_config,
get_browser_config,
)
-from plugins._browser.helpers.playwright import configure_playwright_env, ensure_playwright_binary
+from plugins._browser.helpers.playwright import (
+ ensure_browser_display,
+)
from plugins._browser.helpers.url import normalize_url
@@ -591,6 +593,7 @@ class _BrowserRuntimeCore:
self._closing = False
self._pending_popups: list[asyncio.Future[int]] = []
self._background_popup_pages: set[int] = set()
+ self._bootstrap_page: Any | None = None
def _ensure_registry_lock(self) -> asyncio.Lock:
if self._registry_lock is None:
@@ -773,6 +776,7 @@ class _BrowserRuntimeCore:
waiter.set_exception(RuntimeError("Browser context closed."))
self._pending_popups.clear()
self._background_popup_pages.clear()
+ self._bootstrap_page = None
self.pages.clear()
self.last_interacted_browser_id = None
for screencast in self.screencasts.values():
@@ -797,20 +801,26 @@ class _BrowserRuntimeCore:
self.playwright = None
async def _start(self) -> None:
- from playwright.async_api import async_playwright
+ from plugins._browser import hooks
+
+ preparation = hooks.prepare_playwright_cache()
+ if preparation.get("errors") or not preparation.get("binary"):
+ problem = preparation.get("errors") or "missing binary"
+ raise RuntimeError(f"Browser setup failed: {problem}")
+ from patchright.async_api import async_playwright
self.profile_dir.mkdir(parents=True, exist_ok=True)
self.downloads_dir.mkdir(parents=True, exist_ok=True)
self._release_orphaned_profile_singleton()
browser_config = get_browser_config()
launch_config = build_browser_launch_config(browser_config)
- configure_playwright_env()
- browser_binary = ensure_playwright_binary()
+ browser_binary = Path(preparation["binary"])
+ browser_display = ensure_browser_display()
self.playwright = await async_playwright().start()
launch_kwargs: dict[str, Any] = {
"user_data_dir": str(self.profile_dir),
- "headless": True,
+ "headless": not bool(browser_display),
"accept_downloads": True,
"downloads_path": str(self.downloads_dir),
"viewport": DEFAULT_VIEWPORT,
@@ -818,6 +828,8 @@ class _BrowserRuntimeCore:
"no_viewport": False,
"args": launch_config["args"],
}
+ if browser_display:
+ launch_kwargs["env"] = {**os.environ, "DISPLAY": browser_display}
if launch_config["channel"]:
launch_kwargs["channel"] = launch_config["channel"]
else:
@@ -840,11 +852,12 @@ class _BrowserRuntimeCore:
self.context.set_default_navigation_timeout(30000)
self.context.on("close", self._on_context_closed)
self.context.on("page", self._on_new_page_sync)
- await self.context.add_init_script(path=str(DOM_HELPER_PATH))
- await self.context.add_init_script(path=str(CONTENT_HELPER_PATH))
for page in list(self.context.pages):
if page.url == "about:blank":
+ if browser_display and self._bootstrap_page is None:
+ self._bootstrap_page = page
+ continue
try:
await page.close()
except Exception:
@@ -915,7 +928,10 @@ class _BrowserRuntimeCore:
async def open(self, url: str = "") -> dict[str, Any]:
await self.ensure_started()
self._ensure_can_open_page()
- page = await self.context.new_page()
+ page = self._bootstrap_page
+ self._bootstrap_page = None
+ if not page or page.is_closed():
+ page = await self.context.new_page()
browser_page = await self._register_page(page)
self.last_interacted_browser_id = browser_page.id
target_url = self._initial_url(url)
@@ -1296,6 +1312,7 @@ class _BrowserRuntimeCore:
result = await page.evaluate(
"(payload) => globalThis.__spaceBrowserPageContent__.capture(payload || null)",
payload or None,
+ isolated_context=True,
)
self._maybe_promote(resolved_id)
return result or {}
@@ -1308,6 +1325,7 @@ class _BrowserRuntimeCore:
result = await page.evaluate(
"(ref) => globalThis.__spaceBrowserPageContent__.detail(ref)",
reference_id,
+ isolated_context=True,
)
self._maybe_promote(resolved_id)
return result or {}
@@ -1324,6 +1342,7 @@ class _BrowserRuntimeCore:
result = await page.evaluate(
"(payload) => globalThis.__spaceBrowserPageContent__.annotate(payload || null)",
payload or None,
+ isolated_context=True,
)
self._maybe_promote(resolved_id)
return result or {}
@@ -1332,7 +1351,7 @@ class _BrowserRuntimeCore:
await self.ensure_started()
resolved_id = self._resolve_browser_id(browser_id)
page = self._page(resolved_id)
- result = await page.evaluate(str(script or "undefined"))
+ result = await page.evaluate(str(script or "undefined"), isolated_context=False)
self._maybe_promote(resolved_id)
return {"result": result, "state": await self._state(resolved_id)}
@@ -1364,6 +1383,7 @@ class _BrowserRuntimeCore:
box = await page.evaluate(
"(ref) => globalThis.__spaceBrowserPageContent__.boundingBoxFor(ref)",
reference_id,
+ isolated_context=True,
)
background = focus_popup is False or (
@@ -1515,6 +1535,7 @@ class _BrowserRuntimeCore:
"action": normalized_action,
"text": str(text or ""),
},
+ isolated_context=False,
) or {}
except Exception as exc:
clipboard_result = {
@@ -1779,6 +1800,7 @@ class _BrowserRuntimeCore:
"useOffsets": bool(offset_x or offset_y),
},
},
+ isolated_context=True,
)
if not point or not isinstance(point, dict):
raise ValueError(f"Could not resolve Browser ref {reference_id!r} to a viewport point")
@@ -1995,6 +2017,7 @@ class _BrowserRuntimeCore:
"ref": ref,
"values": values if values is not None else value,
},
+ isolated_context=True,
)
await self._settle(page, short=True)
self._maybe_promote(resolved_id)
@@ -2016,6 +2039,7 @@ class _BrowserRuntimeCore:
"ref": ref,
"checked": bool(checked),
},
+ isolated_context=True,
)
await self._settle(page, short=True)
self._maybe_promote(resolved_id)
@@ -2036,12 +2060,14 @@ class _BrowserRuntimeCore:
metadata = await page.evaluate(
"(ref) => globalThis.__spaceBrowserPageContent__.fileInputFor(ref)",
ref,
+ isolated_context=True,
)
handle = None
try:
handle = await page.evaluate_handle(
"(ref) => globalThis.__spaceBrowserPageContent__.fileInputElementFor(ref)",
ref,
+ isolated_context=True,
)
element = handle.as_element() if handle else None
if element:
@@ -2198,11 +2224,13 @@ class _BrowserRuntimeCore:
action = await page.evaluate(
"(args) => globalThis.__spaceBrowserPageContent__[args.method](args.ref)",
{"method": helper_method, "ref": reference_id},
+ isolated_context=True,
)
else:
action = await page.evaluate(
"(args) => globalThis.__spaceBrowserPageContent__[args.method](args.ref, args.text)",
{"method": helper_method, "ref": reference_id, "text": text},
+ isolated_context=True,
)
await self._settle(page, short=False)
self._maybe_promote(resolved_id)
@@ -2215,8 +2243,8 @@ class _BrowserRuntimeCore:
*,
wait_until: str = "domcontentloaded",
) -> None:
- from playwright.async_api import Error as PlaywrightError
- from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+ from patchright.async_api import Error as PlaywrightError
+ from patchright.async_api import TimeoutError as PlaywrightTimeoutError
try:
await page.goto(url, wait_until=wait_until, timeout=30000)
@@ -2227,8 +2255,8 @@ class _BrowserRuntimeCore:
await self._settle(page, short=wait_until == "commit")
async def _settle(self, page: Any, short: bool = False) -> None:
- from playwright.async_api import Error as PlaywrightError
- from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+ from patchright.async_api import Error as PlaywrightError
+ from patchright.async_api import TimeoutError as PlaywrightTimeoutError
try:
await page.wait_for_load_state(
@@ -2249,7 +2277,10 @@ class _BrowserRuntimeCore:
except Exception:
title = ""
try:
- history_length = await page.evaluate("() => globalThis.history?.length || 0")
+ history_length = await page.evaluate(
+ "() => globalThis.history?.length || 0",
+ isolated_context=False,
+ )
except Exception:
history_length = 0
return {
@@ -2384,13 +2415,14 @@ class _BrowserRuntimeCore:
async def _ensure_content_helper(self, page: Any) -> None:
await self._ensure_dom_helper(page)
has_helper = await page.evaluate(
- "() => Boolean(globalThis.__spaceBrowserPageContent__?.ready?.())"
+ "() => Boolean(globalThis.__spaceBrowserPageContent__?.ready?.())",
+ isolated_context=True,
)
if has_helper:
return
if self._content_helper_source is None:
self._content_helper_source = CONTENT_HELPER_PATH.read_text(encoding="utf-8")
- await page.evaluate(self._content_helper_source)
+ await page.evaluate(self._content_helper_source, isolated_context=True)
async def _ensure_dom_helper(self, page: Any) -> None:
if self._dom_helper_source is None:
@@ -2408,13 +2440,13 @@ class _BrowserRuntimeCore:
targets = frames
for target in targets:
try:
- has_helper = await target.evaluate(ready_script)
+ has_helper = await target.evaluate(ready_script, isolated_context=True)
except Exception:
continue
if has_helper:
continue
with contextlib.suppress(Exception):
- await target.evaluate(source)
+ await target.evaluate(source, isolated_context=True)
_runtimes: dict[str, BrowserRuntime] = {}
_runtime_lock = threading.RLock()
diff --git a/plugins/_browser/hooks.py b/plugins/_browser/hooks.py
index 257917f2b..8ccd83981 100644
--- a/plugins/_browser/hooks.py
+++ b/plugins/_browser/hooks.py
@@ -1,6 +1,12 @@
from __future__ import annotations
+import importlib
+import importlib.metadata
+import importlib.util
import shutil
+import subprocess
+import sys
+import threading
from pathlib import Path
from helpers import files, plugins, yaml as yaml_helper
@@ -10,6 +16,7 @@ from plugins._browser.helpers.config import (
normalize_browser_config,
)
from plugins._browser.helpers.playwright import (
+ ensure_playwright_binary,
find_playwright_binary,
get_playwright_cache_dir,
get_retired_playwright_cache_dirs,
@@ -17,6 +24,11 @@ from plugins._browser.helpers.playwright import (
from plugins._browser.helpers.runtime import close_all_runtimes_sync
+_SETUP_LOCK = threading.Lock()
+_PLUGIN_DIR = Path(__file__).resolve().parent
+_ROOT_REQUIREMENTS_FILE = _PLUGIN_DIR.parents[1] / "requirements.txt"
+
+
def _load_saved_browser_config(project_name: str = "", agent_profile: str = "") -> dict:
entries = plugins.find_plugin_assets(
plugins.CONFIG_FILE_NAME,
@@ -95,6 +107,59 @@ def cleanup_playwright_cache() -> dict:
return result
+def prepare_playwright_cache() -> dict:
+ with _SETUP_LOCK:
+ _ensure_patchright_dependency()
+ result = cleanup_playwright_cache()
+ if result["errors"]:
+ return result
+ result["binary"] = str(ensure_playwright_binary())
+ return result
+
+
+def install() -> dict:
+ return prepare_playwright_cache()
+
+
+def _ensure_patchright_dependency() -> None:
+ requirement = _patchright_requirement()
+ if _patchright_is_current(requirement):
+ return
+
+ uv = shutil.which("uv")
+ if not uv:
+ raise RuntimeError("Browser plugin requires 'uv' to install Patchright automatically")
+
+ subprocess.check_call(
+ [uv, "pip", "install", "--python", sys.executable, requirement],
+ cwd=str(_PLUGIN_DIR),
+ )
+ importlib.invalidate_caches()
+ if not _patchright_is_current(requirement):
+ raise RuntimeError(
+ f"Browser dependency {requirement!r} is unavailable after installation"
+ )
+
+
+def _patchright_requirement() -> str:
+ if _ROOT_REQUIREMENTS_FILE.is_file():
+ for line in _ROOT_REQUIREMENTS_FILE.read_text(encoding="utf-8").splitlines():
+ requirement = line.strip()
+ if requirement.startswith("patchright=="):
+ return requirement
+ raise RuntimeError(f"Browser Patchright requirement not found in {_ROOT_REQUIREMENTS_FILE}")
+
+
+def _patchright_is_current(requirement: str) -> bool:
+ expected_version = requirement.partition("==")[2]
+ if not expected_version or importlib.util.find_spec("patchright") is None:
+ return False
+ try:
+ return importlib.metadata.version("patchright") == expected_version
+ except importlib.metadata.PackageNotFoundError:
+ return False
+
+
def _best_playwright_cache(candidates: list[Path]) -> Path | None:
valid = [path for path in candidates if path.is_dir() and find_playwright_binary(path)]
if not valid:
diff --git a/requirements.txt b/requirements.txt
index 5c4381828..fb90e1e44 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -26,7 +26,7 @@ markdown==3.7
mcp==1.27.0
newspaper3k==0.2.8
paramiko==3.5.0
-playwright==1.52.0
+patchright==1.61.2
pypdf==6.0.0
python-dotenv==1.1.0
pytz==2024.2
diff --git a/tests/test_browser_agent_regressions.py b/tests/test_browser_agent_regressions.py
index eaa49ef4a..2c546b421 100644
--- a/tests/test_browser_agent_regressions.py
+++ b/tests/test_browser_agent_regressions.py
@@ -110,6 +110,7 @@ from plugins._browser.helpers.runtime import (
)
import plugins._browser.helpers.runtime as browser_runtime_module
from plugins._browser.helpers.playwright import (
+ ensure_playwright_binary,
get_playwright_binary,
get_playwright_cache_dir,
)
@@ -331,6 +332,9 @@ def test_browser_launch_config_uses_full_chromium_for_all_sessions(tmp_path):
assert default_launch["requires_full_browser"] is True
assert default_launch["proxy"] is None
assert not any(arg.startswith("--load-extension=") for arg in default_launch["args"])
+ assert "--no-sandbox" not in default_launch["args"]
+ assert "--disable-dev-shm-usage" not in default_launch["args"]
+ assert "--disable-gpu" not in default_launch["args"]
assert "--headless=new" not in default_launch["args"]
extension_dir = tmp_path / "extension"
@@ -357,6 +361,102 @@ def _patch_playwright_cache_root(monkeypatch, tmp_path):
"get_abs_path",
lambda *parts: str(tmp_path.joinpath(*parts)),
)
+ monkeypatch.setattr(
+ browser_playwright_module,
+ "get_playwright_chromium_revision",
+ lambda: "1169",
+ )
+
+
+def test_browser_uses_patchright_revision_when_newer_playwright_cache_exists(
+ monkeypatch, tmp_path
+):
+ _patch_playwright_cache_root(monkeypatch, tmp_path)
+ monkeypatch.setattr(
+ browser_playwright_module,
+ "get_playwright_chromium_revision",
+ lambda: "1228",
+ )
+ cache_dir = Path(get_playwright_cache_dir())
+ expected = cache_dir / "chromium-1228" / "chrome-linux64" / "chrome"
+ other = cache_dir / "chromium-1234" / "chrome-linux64" / "chrome"
+ expected.parent.mkdir(parents=True)
+ other.parent.mkdir(parents=True)
+ expected.touch()
+ other.touch()
+
+ assert get_playwright_binary() == expected
+
+
[email protected]("platform_dir", ["chrome-linux", "chrome-linux64"])
+def test_browser_installs_current_patchright_chromium_for_host_architecture(
+ monkeypatch, tmp_path, platform_dir
+):
+ _patch_playwright_cache_root(monkeypatch, tmp_path)
+ monkeypatch.setattr(
+ browser_playwright_module,
+ "get_playwright_chromium_revision",
+ lambda: "1234",
+ )
+ old_binary = (
+ tmp_path / "tmp" / "playwright" / "chromium-1169" / "chrome-linux" / "chrome"
+ )
+ old_binary.parent.mkdir(parents=True)
+ old_binary.touch()
+ expected = (
+ tmp_path / "tmp" / "playwright" / "chromium-1234" / platform_dir / "chrome"
+ )
+
+ def install(command, *, env):
+ assert command == [
+ sys.executable,
+ "-m",
+ "patchright",
+ "install",
+ "chromium",
+ "--no-shell",
+ ]
+ assert env["PLAYWRIGHT_BROWSERS_PATH"] == str(tmp_path / "tmp" / "playwright")
+ expected.parent.mkdir(parents=True)
+ expected.touch()
+
+ monkeypatch.setattr(browser_playwright_module.subprocess, "check_call", install)
+
+ assert ensure_playwright_binary() == expected
+
+
+def test_browser_hook_installs_patchright_for_existing_self_updated_runtime(monkeypatch):
+ current = False
+
+ def is_current(requirement):
+ assert requirement == "patchright==1.61.2"
+ return current
+
+ def install(command, *, cwd):
+ nonlocal current
+ assert command == [
+ "/usr/local/bin/uv",
+ "pip",
+ "install",
+ "--python",
+ sys.executable,
+ "patchright==1.61.2",
+ ]
+ assert cwd == str(PROJECT_ROOT / "plugins" / "_browser")
+ current = True
+
+ monkeypatch.setattr(
+ browser_hooks_module,
+ "_patchright_requirement",
+ lambda: "patchright==1.61.2",
+ )
+ monkeypatch.setattr(browser_hooks_module, "_patchright_is_current", is_current)
+ monkeypatch.setattr(browser_hooks_module.shutil, "which", lambda name: "/usr/local/bin/uv")
+ monkeypatch.setattr(browser_hooks_module.subprocess, "check_call", install)
+
+ browser_hooks_module._ensure_patchright_dependency()
+
+ assert current is True
def _write_playwright_binary(cache_dir: Path) -> Path:
@@ -1705,23 +1805,18 @@ def test_browser_runtime_requires_current_content_helper_for_modifier_clicks():
).read_text(encoding="utf-8")
assert "__spaceBrowserPageContent__?.ready?.()" in runtime
+ assert "context.add_init_script" not in runtime
+ assert "isolated_context=False" in runtime
@pytest.mark.anyio
async def test_browser_dom_helper_clicks_content_ref_inside_iframe():
- pytest.importorskip("playwright.async_api")
- from playwright.async_api import async_playwright
+ pytest.importorskip("patchright.async_api")
+ from patchright.async_api import async_playwright
browser_binary = get_playwright_binary()
if not browser_binary:
- pytest.skip("Playwright Chromium binary is not installed")
-
- dom_helper = (
- PROJECT_ROOT / "plugins" / "_browser" / "assets" / "browser-dom-helper.js"
- ).read_text(encoding="utf-8")
- content_helper = (
- PROJECT_ROOT / "plugins" / "_browser" / "assets" / "browser-page-content.js"
- ).read_text(encoding="utf-8")
+ pytest.skip("Patchright Chromium binary is not installed")
async with async_playwright() as playwright:
try:
@@ -1731,12 +1826,10 @@ async def test_browser_dom_helper_clicks_content_ref_inside_iframe():
args=["--no-sandbox"],
)
except Exception as exc:
- pytest.skip(f"Playwright Chromium could not launch: {exc}")
+ pytest.skip(f"Patchright Chromium could not launch: {exc}")
try:
context = await browser.new_context()
- await context.add_init_script(dom_helper)
- await context.add_init_script(content_helper)
page = await context.new_page()
await page.set_content(
"""
@@ -1755,9 +1848,8 @@ async def test_browser_dom_helper_clicks_content_ref_inside_iframe():
</html>
"""
)
- await page.wait_for_function(
- "() => Boolean(document.querySelector('iframe')?.contentWindow?.__spaceBrowserDomHelper__)"
- )
+ core = _BrowserRuntimeCore("patchright-helper")
+ await core._ensure_content_helper(page)
captured = await page.evaluate(
"(payload) => globalThis.__spaceBrowserPageContent__.capture(payload || null)",
@@ -2093,13 +2185,32 @@ def test_browser_docker_installs_full_chromium_to_tmp_cache():
script = (
PROJECT_ROOT / "docker" / "run" / "fs" / "ins" / "install_playwright.sh"
).read_text(encoding="utf-8")
+ requirements = (PROJECT_ROOT / "requirements.txt").read_text(encoding="utf-8")
assert "PLAYWRIGHT_BROWSERS_PATH=/a0/tmp/playwright" in script
- assert "playwright install chromium" in script
+ assert "patchright install chromium --no-shell" in script
+ assert "playwright install chromium" not in script
+ assert "uv pip install" not in script
+ assert "patchright==1.61.2" in requirements
assert "--only-shell" not in script
+ runtime = (PROJECT_ROOT / "plugins" / "_browser" / "helpers" / "runtime.py").read_text(
+ encoding="utf-8"
+ )
+ assert "from patchright.async_api import async_playwright" in runtime
+ assert "from playwright.async_api import async_playwright" not in runtime
+ assert runtime.index("hooks.prepare_playwright_cache()") < runtime.index(
+ "from patchright.async_api import async_playwright"
+ )
+ install_additional = (
+ PROJECT_ROOT / "docker" / "run" / "fs" / "ins" / "install_additional.sh"
+ ).read_text(encoding="utf-8")
+ assert '"headless": not bool(browser_display)' in runtime
+ assert 'launch_kwargs["env"] = {**os.environ, "DISPLAY": browser_display}' in runtime
+ assert " xvfb \\" in install_additional
+
-def test_browser_startup_migration_runs_playwright_cache_cleanup():
+def test_browser_startup_migration_prepares_current_playwright_binary():
extension = (
PROJECT_ROOT
/ "plugins"
@@ -2111,7 +2222,7 @@ def test_browser_startup_migration_runs_playwright_cache_cleanup():
).read_text(encoding="utf-8")
assert "class BrowserPlaywrightCacheMigration(Extension)" in extension
- assert "hooks.cleanup_playwright_cache()" in extension
+ assert "hooks.prepare_playwright_cache()" in extension
assert "PrintStyle.warning" in extension
@@ -2135,6 +2246,55 @@ def test_browser_runtime_removes_stale_profile_singletons(monkeypatch, tmp_path)
)
+async def test_browser_first_open_reuses_headful_bootstrap_page(monkeypatch):
+ class BootstrapPage:
+ url = "about:blank"
+
+ @staticmethod
+ def is_closed():
+ return False
+
+ page = BootstrapPage()
+
+ class Context:
+ pages = [page]
+
+ @staticmethod
+ async def new_page():
+ raise AssertionError("The first headful tab must reuse Chrome's bootstrap page")
+
+ core = _BrowserRuntimeCore("headful")
+ core.context = Context()
+ core._bootstrap_page = page
+
+ async def register(registered_page):
+ assert registered_page is page
+ browser_page = BrowserPage(id=1, page=registered_page)
+ core.pages[1] = browser_page
+ return browser_page
+
+ async def settle(_page, short=False):
+ return None
+
+ async def state(browser_id):
+ return {"id": browser_id, "currentUrl": "about:blank"}
+
+ core._register_page = register
+ core._settle = settle
+ core._state = state
+ monkeypatch.setattr(
+ browser_runtime_module,
+ "get_browser_config",
+ lambda: {"default_homepage": "about:blank", "max_open_tabs": 8},
+ )
+
+ result = await core.open()
+
+ assert result == {"id": 1, "state": {"id": 1, "currentUrl": "about:blank"}}
+ assert core._bootstrap_page is None
+
+
@pytest.mark.anyio
async def test_browser_runtime_restarts_when_cached_context_is_stale():
starts = []
@@ -2780,7 +2940,12 @@ async def test_browser_viewer_subscribe_returns_initial_snapshot(monkeypatch):
result = await handler.process(
"browser_viewer_subscribe",
- {"context_id": "ctx", "browser_id": 1, "viewport_width": 900, "viewport_height": 600},
+ {
+ "context_id": "ctx",
+ "browser_id": 1,
+ "viewport_width": 900,
+ "viewport_height": 600,
+ },
"sid-snapshot",
)
@@ -3202,7 +3367,7 @@ async def test_browser_runtime_screenshot_file_defaults_to_chat_scoped_artifact(
async def title(self):
return "Blank"
- async def evaluate(self, script, payload=None):
+ async def evaluate(self, script, payload=None, **kwargs):
return 1
core = _BrowserRuntimeCore("ctx/id")
@@ -3321,7 +3486,7 @@ async def test_browser_runtime_ref_point_resolution_applies_offsets():
def __init__(self):
self.mouse = FakeMouse()
- async def evaluate(self, script, payload=None):
+ async def evaluate(self, script, payload=None, **kwargs):
eval_payloads.append((script, payload))
if payload and "offsets" in payload:
return {
@@ -3392,7 +3557,7 @@ async def test_browser_runtime_clipboard_paste_uses_dom_bridge():
def __init__(self):
self.keyboard = FakeKeyboard()
- async def evaluate(self, script, payload=None):
+ async def evaluate(self, script, payload=None, **kwargs):
if payload is not None:
eval_payloads.append((script, payload))
return {
@@ -3442,7 +3607,7 @@ async def test_browser_runtime_clipboard_paste_falls_back_to_keyboard_insert_tex
def __init__(self):
self.keyboard = FakeKeyboard()
- async def evaluate(self, script, payload=None):
+ async def evaluate(self, script, payload=None, **kwargs):
if payload is not None:
return {
"action": "paste",