Skip to content

The agent that grows with you

refactor(browser)!: delete the built-in browser_* tools, agent-browser and bundled Camofox

Teknium68500d9ff945
diff --git a/agent/browser_provider.py b/agent/browser_provider.py
index f0f596a3271..95f60033924 100644
--- a/agent/browser_provider.py
+++ b/agent/browser_provider.py
@@ -1,15 +1,15 @@
"""Browser Provider ABC: pluggable cloud browser backends (Browserbase, Browser Use, Firecrawl, …).
Providers register via :meth:`PluginContext.register_browser_provider`; the active one (selected by
-``browser.cloud_provider``) services every cloud-mode ``browser_*`` tool call. They live in
+``browser.cloud_provider``) supplies the CDP browser ``browser_exec`` drives in cloud mode. They live in
``<repo>/plugins/browser/<name>/`` (built-in) or ``~/.hermes/plugins/browser/<name>/`` (user).
-Session metadata contract (legacy ``CloudBrowserProvider`` shape; ``tools.browser_tool`` needs no
-translation). ``bb_session_id`` is a legacy key name kept verbatim — it holds the provider's session ID
+Session metadata contract (legacy ``CloudBrowserProvider`` shape; ``tools.browser_session`` caches it
+as-is). ``bb_session_id`` is a legacy key name kept verbatim — it holds the provider's session ID
regardless of provider::
{
- "session_name": str, # unique name for agent-browser --session
+ "session_name": str, # unique session label (logs only)
"bb_session_id": str, # provider session ID (for close/cleanup)
"cdp_url": str, # CDP websocket URL
"expires_at": str, # optional provider-authoritative ISO timestamp
@@ -31,7 +31,7 @@ class BrowserProvider(ProviderBase):
Subclasses implement :attr:`name` (the ``browser.cloud_provider`` value), :meth:`is_available`, and
the lifecycle trio :meth:`create_session` / :meth:`close_session` / :meth:`emergency_cleanup`.
- ``get_setup_schema`` may add ``"post_setup"`` (e.g. ``"agent_browser"``) to trigger the install hook.
+ ``get_setup_schema`` may add ``"post_setup"`` naming a ``hermes tools`` install hook.
"""
@abc.abstractmethod
diff --git a/agent/browser_registry.py b/agent/browser_registry.py
index cde417c5f0a..11cfd1f6ff7 100644
--- a/agent/browser_registry.py
+++ b/agent/browser_registry.py
@@ -1,5 +1,5 @@
"""Browser provider registry: cloud browser backends registered by plugins via
-:meth:`PluginContext.register_browser_provider`, consumed by ``tools.browser_tool_cloud._get_cloud_provider``.
+:meth:`PluginContext.register_browser_provider`, consumed by ``tools.browser_session_cloud.get_cloud_provider``.
Active-provider precedence (see :func:`_resolve`): ``browser.cloud_provider`` in config.yaml wins
regardless of ``is_available()`` (so the dispatcher surfaces a typed "X_API_KEY is not set" error
diff --git a/evals/browser_use/benchmark_browser_eval.py b/evals/browser_use/benchmark_browser_eval.py
index d2cfc140750..1dbc94a97f8 100644
--- a/evals/browser_use/benchmark_browser_eval.py
+++ b/evals/browser_use/benchmark_browser_eval.py
@@ -1,6 +1,6 @@
-"""Quick benchmark: subprocess eval vs supervisor-WS eval.
+"""Quick benchmark: supervisor-WS ``Runtime.evaluate`` latency against a live Chrome.
-Runs both paths against the same live Chrome and prints a comparison table.
+Prints mean/median/min/max for the supervisor's persistent CDP WebSocket path.
Not a pytest — a script you run manually for the PR description.
Usage:
@@ -87,23 +87,6 @@ def main():
assert out.get("ok"), out
ws_times.append((t1 - t0) * 1000)
- # ── Bench 2: agent-browser subprocess path ────────────────────────
- # Skip if agent-browser isn't installed — the WS bench still tells
- # us what we need.
- if shutil.which("agent-browser") is None and shutil.which("npx") is None:
- print("agent-browser CLI not found — skipping subprocess bench.")
- sub_times = []
- else:
- from tools.browser_tool_session import _run_browser_command
- from tools.browser_tool import _last_session_key
- task_id = _last_session_key("bench-eval")
- sub_times = []
- for _ in range(args.iterations):
- t0 = time.monotonic()
- _run_browser_command(task_id, "eval", ["1 + 1"])
- t1 = time.monotonic()
- sub_times.append((t1 - t0) * 1000)
-
def fmt(name: str, ts: list[float]) -> str:
if not ts:
return f" {name:<40} (skipped)"
@@ -119,11 +102,6 @@ def main():
print(f"browser_eval benchmark — {args.iterations} iterations of `1 + 1`")
print("-" * 90)
print(fmt("supervisor WS (Runtime.evaluate)", ws_times))
- print(fmt("agent-browser subprocess (eval)", sub_times))
- if ws_times and sub_times:
- speedup = statistics.mean(sub_times) / statistics.mean(ws_times)
- print()
- print(f"Speedup: {speedup:.1f}x (mean)")
finally:
SUPERVISOR_REGISTRY.stop_all()
diff --git a/evals/vault_fill_live_e2e.py b/evals/vault_fill_live_e2e.py
index 5243b0be4cf..d1644d4ab46 100644
--- a/evals/vault_fill_live_e2e.py
+++ b/evals/vault_fill_live_e2e.py
@@ -132,11 +132,8 @@ def main() -> int:
return 0
finally:
SUPERVISOR_REGISTRY.stop_all()
- try:
- from tools.browser_tool_lifecycle import cleanup_all_browsers
- cleanup_all_browsers()
- except Exception:
- pass
+ from tools.browser_session_lifecycle import cleanup_all_browsers
+ cleanup_all_browsers()
srv.shutdown()
diff --git a/model_tools.py b/model_tools.py
index 011d32dc90c..2462d39656e 100644
--- a/model_tools.py
+++ b/model_tools.py
@@ -181,8 +181,6 @@ _LEGACY_TOOLSET_MAP = {
"vision_tools": ["vision_analyze"],
"image_tools": ["image_generate"],
"skills_tools": ["skills_list", "skill_view", "skill_manage"],
- "browser_tools": ["browser_navigate", "browser_snapshot", "browser_click", "browser_type", "browser_scroll",
- "browser_back", "browser_press", "browser_get_images", "browser_vision", "browser_console"],
"cronjob_tools": ["cronjob_manage"],
"file_tools": ["read_file", "write_file", "patch", "search_files"],
"tts_tools": ["text_to_speech"],
@@ -367,17 +365,6 @@ def _discord_rewriter(schema_fn_name: str):
return _rewrite
-def _rewrite_browser_navigate(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
- """Static schema is toolset-neutral; name the lightweight retrieval tools only when they are present
- (#39797: a hard "prefer web_search" overrode the user's SOUL.md and was hallucinated when web was off)."""
- web_tools = [name for name in ("web_search", "web_extract") if name in available]
- if not web_tools:
- return td
- noun = "tool" if len(web_tools) == 1 else "tools"
- hint = f" Available lightweight retrieval {noun}: {' and '.join(web_tools)}."
- return _fn_def({**td["function"], "description": td["function"].get("description", "") + hint})
-
-
def _rewrite_browser_cdp(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
"""Same rule for the CDP docs pointer: mention web_extract only when the session has it."""
if "web_extract" not in available:
@@ -424,14 +411,11 @@ _VAULT_INPUT_TOOL_HINT = "the browser's input tool"
def _rewrite_browser_vault(td: dict[str, Any], available: set) -> Optional[dict[str, Any]]:
- """Name the concrete input tool for typing the login identifier: `fill_input` inside browser_exec code, or
- browser_type on the built-in stack. Resolved here because the two live in different toolsets."""
- if "browser_exec" in available:
- concrete = "`fill_input` inside browser_exec"
- elif "browser_type" in available:
- concrete = "browser_type"
- else:
+ """Name the concrete input tool for typing the login identifier (`fill_input` inside browser_exec code).
+ Resolved here because the two live in different toolsets."""
+ if "browser_exec" not in available:
return td
+ concrete = "`fill_input` inside browser_exec"
fn = td["function"]
return _fn_def({**fn, "description": fn.get("description", "").replace(_VAULT_INPUT_TOOL_HINT, concrete)})
@@ -465,10 +449,8 @@ _DYNAMIC_SCHEMA_REWRITERS = {
"execute_code": _rewrite_execute_code,
"discord": _discord_rewriter("get_dynamic_schema_core"),
"discord_admin": _discord_rewriter("get_dynamic_schema_admin"),
- "browser_navigate": _rewrite_browser_navigate,
"browser_cdp": _rewrite_browser_cdp,
"browser_exec": _compose_rewriters(_rewrite_browser_exec, _rewrite_input_tool_for_vault),
- "browser_type": _rewrite_input_tool_for_vault,
"browser_vault": _rewrite_browser_vault,
"delegate_task": _rewrite_delegate_task,
}
@@ -880,7 +862,7 @@ def handle_function_call(
) -> str:
"""Route a tool call through hooks/middleware to the registry; returns a JSON string.
- task_id isolates terminal/browser sessions; user_task feeds browser_snapshot.
+ task_id isolates terminal/browser sessions; user_task is forwarded to every handler as a kwarg.
enabled_tools picks execute_code's sandbox tools (default: the process-global
``_last_resolved_tool_names``). skip_pre_tool_call_hook: caller already fired
it (single-fire contract). enabled/disabled_toolsets scope the Tool Search
diff --git a/plugins/browser/_common.py b/plugins/browser/_common.py
index 93bf0c89148..93c431484bf 100644
--- a/plugins/browser/_common.py
+++ b/plugins/browser/_common.py
@@ -140,6 +140,4 @@ class CloudBrowserProvider(BrowserProvider):
"badge": "paid",
"tag": self.setup_tag,
"env_vars": [dict(v) for v in self.setup_env_vars],
- # Cloud-scoped hook: installs the agent-browser CLI only (the vendor hosts Chromium).
- "post_setup": "browserbase",
}
diff --git a/plugins/browser/browser_use/provider.py b/plugins/browser/browser_use/provider.py
index 1d945befa05..568c28aaf57 100644
--- a/plugins/browser/browser_use/provider.py
+++ b/plugins/browser/browser_use/provider.py
@@ -64,8 +64,8 @@ class BrowserUseBrowserProvider(CloudBrowserProvider):
label = "Browser Use"
release_method = "patch"
release_path = "/browsers/{session_id}"
- # Hidden from the picker (its "Browser Use" row activates tools/browser_use_cli.py); stays
- # registered for the Nous gateway path and legacy cloud_provider configs.
+ # Hidden from the picker; stays registered for the Nous gateway path and legacy cloud_provider
+ # configs.
setup_tag = None
def is_available(self) -> bool:
diff --git a/tools/AGENTS.md b/tools/AGENTS.md
index 9679a81399e..c325705bd62 100644
--- a/tools/AGENTS.md
+++ b/tools/AGENTS.md
@@ -42,10 +42,10 @@ toggled without touching `tools/` or `toolsets.py` (`plugins/AGENTS.md`).
`_HERMES_CORE_TOOLS` is the default bundle every platform's base toolset inherits, not dead code.
Rules for tool code:
-- **Schema descriptions must not name tools from other toolsets** (`browser_navigate` saying "prefer
+- **Schema descriptions must not name tools from other toolsets** (a browser tool saying "prefer
web_search"). Those tools may be unavailable (missing key, disabled toolset) and the model
hallucinates calls to them. Cross-references are added dynamically in `get_tool_definitions()` in
- `model_tools.py` — see the `browser_navigate` / `execute_code` post-processing blocks.
+ `model_tools.py` — see the `browser_cdp` / `execute_code` post-processing blocks.
- **Paths in schema descriptions use `display_hermes_home()`** (schema is built at import; under
multiplex it shows the launch home, which is display-only). **State files use `get_hermes_home()`**
at call time, never `Path.home()/.hermes` and never a module constant, so each served profile gets
@@ -73,14 +73,27 @@ Single `TOOLSETS` dict. Keys today: `browser, clarify, code_execution, cronjob,
delegation, discord, discord_admin, feishu_doc, feishu_drive, file, image_gen,
kanban, memory, messaging, moa, rl, safe, search, session_search, skills, terminal, todo,
tts, video, vision, web, yuanbao` (don't assert the list in tests). Per-platform enable/disable via
-`hermes tools` (curses) or `tools.<platform>.enabled/disabled` in config.yaml. `browser_exec`
-replaces the other browser tools when `browser.backend` is `browser-use`.
+`hermes tools` (curses) or `tools.<platform>.enabled/disabled` in config.yaml. `browser_exec` is the
+one core browser tool (beside `browser_cdp` / `browser_dialog` / `browser_vault`, all CDP).
+
+## Browser runtime
+
+`browser_exec` (`browser_use_cli.py`) drives a browser over CDP through browser-harness. Where that
+CDP endpoint comes from is `browser_session.get_session_info(cache_key)`: operator `BU_CDP_*` env (in
+browser_exec) > CDP override (live `/browser connect` > `BROWSER_CDP_URL` > `browser.cdp_url`) >
+hybrid `::local` sidecar > cloud provider (failure → local session marked `fallback_from_cloud`) >
+real profile (consented) > Lightpanda > the packaged Chromium from `browser_launcher.launch_chromium`
+(one browser per cache key, `--remote-debugging-port=0` + `DevToolsActivePort`). State lives in
+`browser_session.py`; siblings late-import it inside functions. Every launched Chromium is stopped
+parent-first and recorded host-wide so a later process reaps a crashed owner's browser after checking
+pid + start time + its `--user-data-dir` argv token. `browser_tool.py` and `browser_tool_install.py`
+are frozen old-updater stubs only (see their docstrings); never grow them.
## Backends and providers inside tools/
Several tools front pluggable backends: terminal environments in `tools/environments/` (local,
docker, ssh, modal, daytona; `terminal_tool_backends.py`, `tool_backend_helpers.py`),
-browser (`browser_tool_*.py`: cdp, cloud, install, lifecycle, session, real_profile, vision), MCP
+browser (`browser_launcher.py` + `browser_session*.py`: lifecycle, cloud, cdp, real_profile, sandbox), MCP
client (`mcp_tool_*.py`: config, discovery, transport, registration, content, errors), TTS
(`tts_tool_providers.py`, `tts_command_provider.py`), skills hub sources (`skills_hub_official.py`
`OptionalSkillSource`). Adding a backend = a new sibling or provider entry in the existing table,
@@ -88,7 +101,7 @@ never an `elif` on a backend name (root shape rules). Remote-backend file visibi
fixed at the mount, not by adding a tool.
**Native vision embeds are history, not one-shot payloads.** `vision_tools.py::_vision_analyze_native`
-(and the browser screenshot twins in `browser_tool_vision.py` / `browser_use_cli.py`) bake the image
+(and the browser screenshot twin in `browser_use_cli.py`) bake the image
into a tool result that is re-sent on every later API call. Size and repeat policy live in
`vision_tools_history_budget.py` (config section `vision`: `embed_target_bytes`, `max_calls_per_image`);
the repeat counter is keyed on (session id, resolved source) so region crops share their file's count,
diff --git a/tools/browser_camofox.py b/tools/browser_camofox.py
deleted file mode 100644
index 390686a308e..00000000000
--- a/tools/browser_camofox.py
+++ /dev/null
@@ -1,602 +0,0 @@
-"""Camofox browser backend — local anti-detection browser via REST API.
-
-Camofox-browser (https://github.com/jo-inc/camofox-browser) is a self-hosted Node.js
-server wrapping Camoufox (Firefox fork with C++ fingerprint spoofing); its REST API maps
-1:1 to our browser tool interface (accessibility snapshots with element refs, click/type/
-scroll by ref, screenshots). Setup: ``npm start`` in a checkout or ``docker run -p 9377:9377
--e CAMOFOX_PORT=9377 jo-inc/camofox-browser``, then ``CAMOFOX_URL=http://localhost:9377`` in
-``~/.hermes/.env`` (Docker: see ``CAMOFOX_REWRITE_LOOPBACK_URLS`` below).
-"""
-
-from __future__ import annotations
-
-import base64
-import ipaddress
-import json
-import logging
-import os
-import re
-import threading
-import uuid
-from typing import Any, Callable, Dict, Optional
-from urllib.parse import SplitResult, urlsplit, urlunsplit
-
-import requests
-
-from agent.secret_scope import get_secret
-from hermes_cli.config import cfg_get, load_config, read_raw_config
-from hermes_constants import get_hermes_home_override, hermes_home_key
-from tools.browser_camofox_state import get_camofox_identity
-from tools.registry import tool_error
-
-logger = logging.getLogger(__name__)
-
-# ---- Configuration ----
-
-_DEFAULT_TIMEOUT = 30 # fallback when config is unreadable
-_NO_SESSION_ERROR = "No browser session. Call browser_navigate first."
-_vnc_url: Optional[str] = None # cached from /health response
-_vnc_url_checked = False # only probe once per process
-# Routed profiles (multiplexed gateway) each point CAMOFOX_URL at their own server, so the one-shot
-# slot above would hand the launch profile's VNC address to every other profile: memo per server URL.
-_vnc_url_by_camofox_url: dict[str, Optional[str]] = {}
-# browser.command_timeout, resolved lazily like browser_tool; keyed by profile home because the
-# multiplexed gateway serves every profile from one process.
-_cached_cmd_timeout: Optional[dict[str, int]] = None
-_cmd_timeout_resolved = False
-
-
-def _get_command_timeout() -> int:
- """``browser.command_timeout`` (floor 5s, default 30s), cached per profile home after first read."""
- global _cached_cmd_timeout, _cmd_timeout_resolved
- home = hermes_home_key()
- if _cached_cmd_timeout is None:
- _cached_cmd_timeout = {}
- if _cmd_timeout_resolved and home in _cached_cmd_timeout:
- return _cached_cmd_timeout[home]
- timeout = _DEFAULT_TIMEOUT
- try:
- val = cfg_get(read_raw_config(), "browser", "command_timeout")
- if val is not None:
- timeout = max(int(val), 5)
- except Exception as exc:
- logger.debug("Could not read browser.command_timeout: %s", exc)
- _cached_cmd_timeout[home] = timeout
- _cmd_timeout_resolved = True
- return timeout
-
-
-def _auth_headers() -> dict[str, str]:
- """Return Authorization header when CAMOFOX_API_KEY is set."""
- key = (get_secret("CAMOFOX_API_KEY", "") or "").strip()
- return {"Authorization": f"Bearer {key}"} if key else {}
-
-
-def get_camofox_url() -> str:
- """Return the configured Camofox server URL, or empty string."""
- return (get_secret("CAMOFOX_URL", "") or "").rstrip("/")
-
-
-def _config_cdp_url() -> str:
- """Persistent ``browser.cdp_url`` from config.yaml, or "" (read here, not via
- ``browser_tool_cdp._get_cdp_override`` — circular import)."""
- try:
- from hermes_cli.config import read_raw_config # late-bound: tests patch the source module
- browser_cfg = read_raw_config().get("browser", {})
- if isinstance(browser_cfg, dict):
- return str(browser_cfg.get("cdp_url", "") or "").strip()
- except Exception:
- pass
- return ""
-
-
-def is_camofox_mode() -> bool:
- """True when the Camofox backend is selected and no CDP override is active.
-
- Selection is ``browser.cloud_provider: camofox``; ``CAMOFOX_URL`` is only the address
- and never overrides a different stored selection (legacy: with no selection ever
- written, a set ``CAMOFOX_URL`` still activates Camofox). A CDP override (``BROWSER_CDP_URL``
- env or ``browser.cdp_url``, same precedence as ``browser_tool_cdp._get_cdp_override()``) wins.
- """
- from tools.browser_tool_cdp import env_cdp_url, live_cdp_override
- if live_cdp_override() or env_cdp_url() or _config_cdp_url():
- return False
- try:
- from tools.tool_backend_helpers import read_selection
- selected = read_selection("browser")
- except Exception: # pragma: no cover — helpers are in-repo
- selected = None
- if selected is not None:
- return selected == "camofox"
- return bool(get_camofox_url())
-
-
-def _vnc_url_from_health(url: str, resp: Any) -> Optional[str]:
- try:
- vnc_port = resp.json().get("vncPort")
- if isinstance(vnc_port, int) and 1 <= vnc_port <= 65535:
- return f"http://{urlsplit(url).hostname or 'localhost'}:{vnc_port}"
- except (ValueError, KeyError):
- pass
- return None
-
-
-def check_camofox_available() -> bool:
- """Verify the Camofox server is reachable (and cache its VNC URL once)."""
- global _vnc_url, _vnc_url_checked
- url = get_camofox_url()
- if not url:
- return False
- try:
- resp = requests.get(f"{url}/health", timeout=5)
- except Exception:
- return False
- if resp.status_code == 200:
- if get_hermes_home_override() is not None:
- if url not in _vnc_url_by_camofox_url:
- _vnc_url_by_camofox_url[url] = _vnc_url_from_health(url, resp)
- elif not _vnc_url_checked:
- _vnc_url = _vnc_url_from_health(url, resp) or _vnc_url
- _vnc_url_checked = True
- return resp.status_code == 200
-
-
-def get_vnc_url() -> Optional[str]:
- """Return the VNC URL if the Camofox server exposes one, or None."""
- if get_hermes_home_override() is not None:
- url = get_camofox_url()
- if url not in _vnc_url_by_camofox_url:
- check_camofox_available()
- return _vnc_url_by_camofox_url.get(url)
- if not _vnc_url_checked:
- check_camofox_available()
- return _vnc_url
-
-
-def _get_camofox_config() -> dict[str, Any]:
- """Return the ``browser.camofox`` config block, or an empty dict."""
- try:
- camofox_cfg = load_config().get("browser", {}).get("camofox", {})
- except Exception as exc:
- logger.warning("camofox config check failed, defaulting to disabled: %s", exc)
- return {}
- return camofox_cfg if isinstance(camofox_cfg, dict) else {}
-
-
-def _managed_persistence_enabled(camofox_cfg: Optional[dict[str, Any]] = None) -> bool:
- """``browser.camofox.managed_persistence``: stable profile-scoped userId vs random per session."""
- return bool((_get_camofox_config() if camofox_cfg is None else camofox_cfg).get("managed_persistence"))
-
-
-def _env_or_cfg(env_name: str, camofox_cfg: dict[str, Any], cfg_key: str, *, secret: bool = False) -> str:
- """Env/secret-scope value first, then the ``browser.camofox`` config key, else ""."""
- raw = get_secret(env_name, "") if secret else os.getenv(env_name, "")
- return (raw or "").strip() or str(camofox_cfg.get(cfg_key) or "").strip()
-
-
-def _camofox_identity_override(task_id: Optional[str], camofox_cfg: dict[str, Any]) -> Optional[dict[str, str]]:
- """Externally configured identity (integrations owning the visible Camofox browser
- share a user ID so Hermes uses the same profile), or None."""
- user_id = _env_or_cfg("CAMOFOX_USER_ID", camofox_cfg, "user_id", secret=True)
- if not user_id:
- return None
- session_key = _env_or_cfg("CAMOFOX_SESSION_KEY", camofox_cfg, "session_key", secret=True)
- return {"user_id": user_id, "session_key": session_key or f"task_{(task_id or 'default')[:16]}"}
-
-
-def _flag(env_name: str, camofox_cfg: dict[str, Any], cfg_key: str) -> bool:
- """Boolean toggle: env var wins when set to a valid value, else config key."""
- raw = os.getenv(env_name, "").strip().lower()
- if raw in {"1", "true", "yes", "on"}:
- return True
- if raw in {"0", "false", "no", "off"}:
- return False
- if raw:
- logger.debug("Ignoring invalid boolean env %s=%r", env_name, raw)
- return bool(camofox_cfg.get(cfg_key))
-
-
-def _is_loopback_hostname(hostname: Optional[str]) -> bool:
- if not hostname:
- return False
- host = hostname.strip().strip("[]").lower()
- if host in {"localhost", "localhost.localdomain"}:
- return True
- try:
- return ipaddress.ip_address(host).is_loopback
- except ValueError:
- return False
-
-
-def _rewrite_loopback_url_for_camofox(url: str) -> tuple[str, Optional[dict[str, str]]]:
- """Rewrite loopback page URLs for Docker-hosted Camofox, if configured.
-
- ``CAMOFOX_URL`` may point at a host-published Docker port, but page URLs are opened by
- the browser *inside* the container, where loopback is the container, not the host.
- Opt-in (``CAMOFOX_REWRITE_LOOPBACK_URLS`` / config) because non-Docker installs run the
- browser on the host. Returns ``(rewritten_url, metadata)``; ``metadata`` is present only
- when a rewrite happened so the tool result can disclose the change to the model.
- """
- camofox_cfg = _get_camofox_config()
- if not _flag("CAMOFOX_REWRITE_LOOPBACK_URLS", camofox_cfg, "rewrite_loopback_urls"):
- return url, None
- try:
- parsed = urlsplit(url)
- except ValueError:
- return url, None
- alias = _env_or_cfg("CAMOFOX_LOOPBACK_HOST_ALIAS", camofox_cfg, "loopback_host_alias") or "host.docker.internal"
- if parsed.scheme not in {"http", "https"} or not _is_loopback_hostname(parsed.hostname) or not alias:
- return url, None
- userinfo = (parsed.username + (f":{parsed.password}" if parsed.password else "") + "@") if parsed.username else ""
- host_part = f"[{alias}]" if ":" in alias and not alias.startswith("[") else alias
- port_part = f":{parsed.port}" if parsed.port else ""
- rewritten = urlunsplit(
- SplitResult(parsed.scheme, f"{userinfo}{host_part}{port_part}", parsed.path, parsed.query, parsed.fragment))
- return rewritten, {"from": parsed.hostname or "", "to": alias, "original_url": url, "rewritten_url": rewritten}
-
-
-# ---- Session management ----
-_sessions: dict[str, dict[str, Any]] = {} # task_id -> {"user_id": str, "tab_id": str|None, ...}
-_sessions_lock = threading.Lock()
-
-
-def _adopt_existing_tab(session: dict[str, Any]) -> dict[str, Any]:
- """Rehydrate tab_id from an already-open managed tab: gateway restarts empty the
- in-memory cache while Camofox still holds the integration-owned tab."""
- if session.get("tab_id") or not session.get("adopt_existing_tab") or not get_camofox_url():
- return session
- try:
- tabs = _get("/tabs", params=_user_params(session), timeout=5).get("tabs", [])
- except Exception as exc:
- logger.debug("Camofox tab adoption failed for %s: %s", session.get("user_id"), exc)
- return session
- dict_tabs = [tab for tab in tabs if isinstance(tab, dict)] if isinstance(tabs, list) else []
- candidates = [tab for tab in dict_tabs if tab.get("listItemId") == session.get("session_key")] or dict_tabs
- tab_id = candidates[-1].get("tabId") if candidates else None
- if isinstance(tab_id, str) and tab_id:
- session["tab_id"] = tab_id
- logger.debug("Adopted existing Camofox tab %s for %s", tab_id, session.get("user_id"))
- return session
-
-
-def _get_session(task_id: Optional[str]) -> dict[str, Any]:
- """Get or create the task's session. Identity precedence: external override
- (CAMOFOX_USER_ID / config) → profile-scoped identity when managed persistence
- is on → random ephemeral userId."""
- task_id = task_id or "default"
- with _sessions_lock:
- if task_id in _sessions:
- return _adopt_existing_tab(_sessions[task_id])
- camofox_cfg = _get_camofox_config()
- identity = _camofox_identity_override(task_id, camofox_cfg)
- if identity is None and _managed_persistence_enabled(camofox_cfg):
- identity = get_camofox_identity(task_id)
- if identity is None:
- identity = {"user_id": f"hermes_{uuid.uuid4().hex[:10]}", "session_key": f"task_{task_id[:16]}"}
- managed, adopt = False, False
- else:
- managed, adopt = True, _flag("CAMOFOX_ADOPT_EXISTING_TAB", camofox_cfg, "adopt_existing_tab")
- session = {"user_id": identity["user_id"], "tab_id": None, "session_key": identity["session_key"],
- "managed": managed, "adopt_existing_tab": adopt}
- _sessions[task_id] = session
- return _adopt_existing_tab(session)
-
-
-def _ensure_tab(task_id: Optional[str], url: str = "about:blank") -> dict[str, Any]:
- """Ensure a tab exists for the session, creating one if needed."""
- session = _get_session(task_id)
- if not session["tab_id"]:
- data = _post("/tabs", {"userId": session["user_id"], "listItemId": session["session_key"], "url": url})
- session["tab_id"] = data.get("tabId")
- return session
-
-
-def _drop_session(task_id: Optional[str]) -> Optional[dict[str, Any]]:
- """Remove and return session info."""
- with _sessions_lock:
- return _sessions.pop(task_id or "default", None)
-
-
-def camofox_soft_cleanup(task_id: Optional[str] = None) -> bool:
- """Drop only the local tracking entry (``True``) for managed profiles, which must
- survive across agent tasks; ``False`` for ephemeral sessions so the caller falls back
- to :func:`camofox_close`."""
- camofox_cfg = _get_camofox_config()
- if _managed_persistence_enabled(camofox_cfg) or _camofox_identity_override(task_id, camofox_cfg):
- _drop_session(task_id)
- logger.debug("Camofox soft cleanup for task %s (managed persistence)", task_id)
- return True
- return False
-
-
-# ---- HTTP helpers ----
-def _request(method: str, path: str, timeout: Optional[int] = None, **kwargs: Any) -> requests.Response:
- """Issue an authenticated request to camofox and return the raised-for-status response."""
- resp = getattr(requests, method)(f"{get_camofox_url()}{path}", headers=_auth_headers(),
- timeout=_get_command_timeout() if timeout is None else timeout, **kwargs)
- resp.raise_for_status()
- return resp
-
-
-def _post(path: str, body: dict, timeout: Optional[int] = None) -> dict:
- return _request("post", path, timeout, json=body).json()
-
-
-def _get(path: str, params: dict | None = None, timeout: Optional[int] = None) -> dict:
- return _request("get", path, timeout, params=params).json()
-
-
-def _get_raw(path: str, params: dict | None = None, timeout: Optional[int] = None) -> requests.Response:
- """GET and return the raw response (for binary data)."""
- return _request("get", path, timeout, params=params)
-
-
-def _delete(path: str, body: dict | None = None, timeout: Optional[int] = None) -> dict:
- return _request("delete", path, timeout, json=body).json()
-
-
-# ---- Tool implementations ----
-def _tab_path(session: dict[str, Any], suffix: str) -> str:
- return f"/tabs/{session['tab_id']}/{suffix}"
-
-
-def _user_params(session: dict[str, Any]) -> dict[str, str]:
- return {"userId": session["user_id"]}
-
-
-def _snapshot_data(session: dict[str, Any]) -> dict:
- return _get(_tab_path(session, "snapshot"), params=_user_params(session))
-
-
-def _parse_snapshot_images(snapshot: str) -> list[dict[str, str]]:
- """Images from an accessibility snapshot: ``img "alt" [eN]`` entries with the URL on
- the following ``/url:`` line (Camofox has no /images endpoint)."""
- images = []
- lines = snapshot.split("\n")
- for i, line in enumerate(lines):
- stripped = line.strip()
- if not stripped.startswith(("- img ", "img ")):
- continue
- alt_match = re.search(r'img\s+"([^"]*)"', stripped)
- url_match = re.search(r'/url:\s*(\S+)', lines[i + 1].strip()) if i + 1 < len(lines) else None
- alt, src = (alt_match.group(1) if alt_match else ""), (url_match.group(1) if url_match else "")
- if alt or src:
- images.append({"src": src, "alt": alt})
- return images
-
-
-def _fetch_snapshot(session: dict[str, Any]) -> tuple[str, int]:
- """``(snapshot_text, refs_count)`` truncated like the main browser tool (line boundaries,
- full tree stored to cache/web, read_file pointer appended). Lazy import: ``browser_tool``
- imports this module."""
- from tools.browser_tool_snapshot import _truncate_snapshot
- from tools.browser_tool import get_browser_snapshot_threshold
- data = _snapshot_data(session)
- snapshot, threshold = data.get("snapshot", ""), get_browser_snapshot_threshold()
- if len(snapshot) > threshold:
- snapshot = _truncate_snapshot(snapshot, max_chars=threshold)
- return snapshot, data.get("refsCount", 0)
-
-
-def _navigate_tab(task_id: Optional[str], browser_url: str) -> tuple[dict[str, Any], dict]:
- """Open ``browser_url`` in the task's tab (creating it if missing) and return
- ``(session, navigate_response)``. A 404 on the existing tab means the server
- garbage-collected it — recreate instead of failing."""
- session = _get_session(task_id)
- if session["tab_id"]:
- try:
- data = _post(_tab_path(session, "navigate"), {"userId": session["user_id"], "url": browser_url}, timeout=60)
- return session, data
- except requests.HTTPError as e:
- if e.response is None or e.response.status_code != 404:
- raise
- logger.warning("Camofox tab %s returned 404 — tab was garbage collected. Creating a fresh tab.",
- session["tab_id"])
- session["tab_id"] = None
- return _ensure_tab(task_id, browser_url), {"ok": True, "url": browser_url}
-
-
-def camofox_navigate(url: str, task_id: Optional[str] = None) -> str:
- """Navigate to a URL via Camofox."""
- try:
- browser_url, rewrite_info = _rewrite_loopback_url_for_camofox(url)
- session, data = _navigate_tab(task_id, browser_url)
- result = {"success": True, "url": data.get("url", browser_url), "title": data.get("title", "")}
- if rewrite_info:
- result["requested_url"], result["url_rewrite"] = url, rewrite_info
- result["warning"] = ("Rewrote loopback URL for Docker-hosted Camofox: "
- f"{rewrite_info['from']} -> {rewrite_info['to']}")
- vnc = get_vnc_url()
- if vnc:
- result["vnc_url"] = vnc
- result["vnc_hint"] = ("Browser is visible via VNC. "
- "Share this link with the user so they can watch the browser live.")
- try: # Auto-take a compact snapshot so the model can act immediately.
- result["snapshot"], result["element_count"] = _fetch_snapshot(session)
- except Exception:
- pass # Navigation succeeded; snapshot is a bonus
- return json.dumps(result)
- except requests.HTTPError as e:
- return tool_error(f"Navigation failed: {e}", success=False)
- except requests.ConnectionError:
- return json.dumps({"success": False, "error": (
- f"Cannot connect to Camofox at {get_camofox_url()}. "
- "Is the server running? Start with: npm start (in camofox-browser dir) "
- "or: docker run -p 9377:9377 -e CAMOFOX_PORT=9377 jo-inc/camofox-browser")})
- except Exception as e:
- return tool_error(str(e), success=False)
-
-
-def _camofox_private_page_block(session: dict[str, Any], task_id: Optional[str], action: str) -> Optional[str]:
- """Blocked payload when the current page is private/internal, else None.
-
- Mirrors the ``_camofox_eval`` guard in browser_tool.py: page-state reads on a non-local
- backend can leak an intranet/metadata page the terminal can't reach. Only active when
- the SSRF guard applies (non-local backend, not a local sidecar, ``allow_private_urls``
- unset); fail-open on probe failure like sibling guards. Lazy import (cycle).
- """
- from tools.browser_tool_eval_policy import _camofox_current_page_private_url, _eval_ssrf_guard_active
- if not _eval_ssrf_guard_active(task_id or "default"):
- return None
- blocked_url = _camofox_current_page_private_url(session["tab_id"], session["user_id"])
- if not blocked_url:
- return None
- return json.dumps({"success": False, "error": (
- "Blocked: page URL targets a private or internal address "
- f"({blocked_url}). Refusing to {action} on this page in this browser mode.")}, ensure_ascii=False)
-
-
-def _require_tab(task_id: Optional[str], action: Optional[str] = None) -> tuple[dict[str, Any], Optional[str]]:
- """Return ``(session, error_payload)``: error when no tab exists or, if ``action`` given, the page is private."""
- session = _get_session(task_id)
- if not session["tab_id"]:
- return session, tool_error(_NO_SESSION_ERROR, success=False)
- return session, (_camofox_private_page_block(session, task_id, action) if action is not None else None)
-
-
-def _with_tab(task_id: Optional[str], guard_action: Optional[str], body: Callable[[dict[str, Any]], str]) -> str:
- """Require a tab (+ private-page guard when ``guard_action`` is set), then run ``body(session)``;
- any exception becomes a ``tool_error``."""
- try:
- session, blocked = _require_tab(task_id, guard_action)
- if blocked:
- return blocked
- return body(session)
- except Exception as e:
- return tool_error(str(e), success=False)
-
-
-def _tab_action(task_id: Optional[str], guard_action: Optional[str], suffix: str,
- body: dict[str, Any], result: Callable[[dict], dict]) -> str:
- """Simple tab action: POST ``body`` to ``/tabs/<id>/<suffix>``, build the result."""
- return _with_tab(task_id, guard_action, lambda session: json.dumps(
- result(_post(_tab_path(session, suffix), {"userId": session["user_id"], **body}))))
-
-
-def camofox_snapshot(full: bool = False, task_id: Optional[str] = None, user_task: Optional[str] = None) -> str:
- """Accessibility tree snapshot. ``user_task`` is deprecated and ignored —
- oversized snapshots always truncate-and-store (no LLM summarization)."""
- def body(session):
- snapshot, refs_count = _fetch_snapshot(session)
- return json.dumps({"success": True, "snapshot": snapshot, "element_count": refs_count})
- return _with_tab(task_id, "read a page snapshot", body)
-
-
-def camofox_click(ref: str, task_id: Optional[str] = None) -> str:
- """Click an element by ref via Camofox."""
- clean_ref = ref.lstrip("@") # our tool convention prefixes refs with @
- return _tab_action(task_id, "click", "click", {"ref": clean_ref},
- lambda data: {"success": True, "clicked": clean_ref, "url": data.get("url", "")})
-
-
-def camofox_type(ref: str, text: str, task_id: Optional[str] = None) -> str:
- """Type text into an element by ref via Camofox."""
- try:
- session, blocked = _require_tab(task_id, "type")
- if blocked:
- return blocked
- clean_ref = ref.lstrip("@")
- _post(_tab_path(session, "type"), {"userId": session["user_id"], "ref": clean_ref, "text": text})
- from agent.display import redact_browser_typed_text_for_display, redact_tool_args_for_display
- # Match browser_tool.browser_type: the raw text is typed into the page, but the
- # returned display value is run through the secret-pattern redactor so API keys /
- # tokens don't leak into tool progress or chat history.
- display_text = (redact_tool_args_for_display("browser_type", {"text": text}) or {})["text"]
- response = {"success": True, "typed": display_text, "element": clean_ref}
- return json.dumps(redact_browser_typed_text_for_display(response, text))
- except Exception as e:
- from agent.display import redact_browser_typed_text_for_display
- return tool_error(redact_browser_typed_text_for_display(str(e), text), success=False)
-
-
-def camofox_scroll(direction: str, task_id: Optional[str] = None) -> str:
- """Scroll the page via Camofox."""
- return _tab_action(task_id, None, "scroll", {"direction": direction},
- lambda data: {"success": True, "scrolled": direction})
-
-
-def camofox_back(task_id: Optional[str] = None) -> str:
- """Navigate back via Camofox."""
- return _tab_action(task_id, None, "back", {}, lambda data: {"success": True, "url": data.get("url", "")})
-
-
-def camofox_press(key: str, task_id: Optional[str] = None) -> str:
- """Press a keyboard key via Camofox."""
- return _tab_action(task_id, "press", "press", {"key": key}, lambda data: {"success": True, "pressed": key})
-
-
-def camofox_close(task_id: Optional[str] = None) -> str:
- """Close the browser session via Camofox."""
- try:
- session = _drop_session(task_id)
- if session:
- _delete(f"/sessions/{session['user_id']}")
- return json.dumps({"success": True, "closed": True})
- except Exception as e:
- return json.dumps({"success": True, "closed": True, "warning": str(e)})
-
-
-def camofox_get_images(task_id: Optional[str] = None) -> str:
- """Get images on the current page via Camofox (parsed from the snapshot)."""
- def body(session):
- images = _parse_snapshot_images(_snapshot_data(session).get("snapshot", ""))
- return json.dumps({"success": True, "images": images, "count": len(images)})
- return _with_tab(task_id, "extract page images", body)
-
-
-def _vision_llm_settings() -> tuple[float, float]:
- """``auxiliary.vision`` ``(timeout, temperature)``; defaults 120s / 0.1 on any config error."""
- try:
- cfg = cfg_get(load_config(), "auxiliary", "vision", default={})
- return float(cfg.get("timeout", 120)), float(cfg.get("temperature", 0.1))
- except Exception:
- return 120.0, 0.1
-
-
-def _save_screenshot(content: bytes) -> str:
- """Write PNG bytes under ``$HERMES_HOME/browser_screenshots`` and return the path."""
- from hermes_constants import get_hermes_home
- screenshots_dir = get_hermes_home() / "browser_screenshots"
- screenshots_dir.mkdir(parents=True, exist_ok=True)
- screenshot_path = str(screenshots_dir / f"browser_screenshot_{uuid.uuid4().hex[:8]}.png")
- with open(screenshot_path, "wb") as f:
- f.write(content)
- return screenshot_path
-
-
-def camofox_vision(question: str, annotate: bool = False, task_id: Optional[str] = None) -> str:
- """Take a screenshot and analyze it with vision AI via Camofox."""
- def body(session):
- resp = _get_raw(_tab_path(session, "screenshot"), params=_user_params(session))
- screenshot_path = _save_screenshot(resp.content)
- img_b64 = base64.b64encode(resp.content).decode("utf-8")
- annotation_context = ""
- if annotate:
- try:
- snapshot = _snapshot_data(session).get("snapshot", "")
- annotation_context = f"\n\nAccessibility tree (element refs for interaction):\n{snapshot[:3000]}"
- except Exception:
- pass
- # The screenshot itself cannot be redacted, but the text-based accessibility snippet
- # sent alongside it must not leak secret values.
- from agent.redact import redact_sensitive_text
- from agent.auxiliary_client import call_llm
- vision_prompt = f"Analyze this browser screenshot and answer: {question}{redact_sensitive_text(annotation_context)}"
- timeout, temperature = _vision_llm_settings()
- response = call_llm(
- messages=[{"role": "user", "content": [
- {"type": "text", "text": vision_prompt},
- {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}}]}],
- task="vision", temperature=temperature, timeout=timeout)
- analysis = (response.choices[0].message.content or "").strip() if response.choices else ""
- # Redact secrets the vision LLM may have read from the screenshot.
- return json.dumps({"success": True, "analysis": redact_sensitive_text(analysis), "screenshot_path": screenshot_path})
- return _with_tab(task_id, "capture a screenshot", body)
-
-
-def camofox_console(clear: bool = False, task_id: Optional[str] = None) -> str:
- """Console output is not exposed by the Camofox REST API; return an empty result with a note."""
- return json.dumps({
- "success": True, "console_messages": [], "js_errors": [], "total_messages": 0, "total_errors": 0,
- "note": "Console log capture is not available with the Camofox backend. "
- "Use browser_snapshot or browser_vision to inspect page state."})
diff --git a/tools/browser_camofox_state.py b/tools/browser_camofox_state.py
deleted file mode 100644
index 2c616e2a2b4..00000000000
--- a/tools/browser_camofox_state.py
+++ /dev/null
@@ -1,27 +0,0 @@
-"""Hermes-managed Camofox state helpers.
-
-With managed persistence enabled, Hermes sends a deterministic userId derived from the
-active profile so Camofox maps it to the same persistent browser profile across restarts.
-"""
-
-from __future__ import annotations
-
-import uuid
-from pathlib import Path
-from typing import Dict, Optional
-
-from hermes_constants import get_hermes_home
-
-
-def get_camofox_state_dir() -> Path:
- """Return the profile-scoped root directory for Camofox persistence."""
- return get_hermes_home() / "browser_auth" / "camofox"
-
-
-def get_camofox_identity(task_id: Optional[str] = None) -> dict[str, str]:
- """Stable Hermes-managed Camofox identity: userId is profile-scoped, session key is
- scoped to the logical browser task so new tabs in the same profile reuse it."""
- scope_root = str(get_camofox_state_dir())
- user_digest = uuid.uuid5(uuid.NAMESPACE_URL, f"camofox-user:{scope_root}").hex[:10]
- session_digest = uuid.uuid5(uuid.NAMESPACE_URL, f"camofox-session:{scope_root}:{task_id or 'default'}").hex[:16]
- return {"user_id": f"hermes_{user_digest}", "session_key": f"task_{session_digest}"}
diff --git a/tools/browser_supervisor.py b/tools/browser_supervisor.py
index dddcd3e12f8..2d4e02cab98 100644
--- a/tools/browser_supervisor.py
+++ b/tools/browser_supervisor.py
@@ -4,7 +4,7 @@ One ``CDPSupervisor`` per Hermes ``task_id`` with a reachable CDP endpoint: one
persistent WebSocket, ``Page`` / ``Runtime`` / ``Target`` events on every attached
session (top page + auto-attached OOPIF / worker targets), pending dialogs + frame
tree exposed via a thread-safe snapshot. Not in the tool schema — output reaches the
-agent via ``browser_snapshot`` / ``browser_dialog``. Dialog capture and frame tracking
+agent via ``browser_exec`` results (``pending_dialogs``) / ``browser_dialog``. Dialog capture and frame tracking
are mixins (``browser_supervisor_dialogs`` / ``browser_supervisor_frames``).
Design spec: ``website/docs/developer-guide/browser-supervisor.md``.
"""
@@ -88,7 +88,7 @@ class SupervisorSnapshot:
task_id: str
def to_dict(self) -> dict[str, Any]:
- """Serialize for inclusion in ``browser_snapshot`` output."""
+ """Serialize for inclusion in tool output."""
out: dict[str, Any] = {"pending_dialogs": [d.to_dict() for d in self.pending_dialogs], "frame_tree": self.frame_tree}
if self.recent_dialogs:
out["recent_dialogs"] = [d.to_dict() for d in self.recent_dialogs]
diff --git a/tools/browser_tool.py b/tools/browser_tool.py
index 7dad4eb3a71..a7c3bc83fbd 100644
--- a/tools/browser_tool.py
+++ b/tools/browser_tool.py
@@ -1,1376 +1,11 @@
-#!/usr/bin/env python3
-"""Browser automation tools driven by the agent-browser CLI.
+"""Frozen old-updater compatibility stub (tests/compat/old_updater_surface.json, ``bare`` list).
-Backends — local headless Chromium, Browser Use / Browserbase / Firecrawl cloud
-(auto-detected from config + credentials), a user-supplied CDP endpoint, or Camofox —
-share one agent-facing behaviour: per-task sessions, accessibility-tree snapshots with
-``@eN`` refs, automatic cleanup. Settings live under ``browser.*`` in config.yaml.
-Sibling ``browser_tool_*`` modules hold extracted clusters.
+The built-in browser_* tools and agent-browser are gone; ``browser_exec`` (``tools/browser_use_cli.py``)
+is the browser. A pre-PM ``hermes update`` still running mid-swap imports this module and the name below
+from the NEW tree, so both must keep existing. Nothing else belongs here.
"""
-import atexit
-import json
-import logging
-import os
-import subprocess
-import sys
-import tempfile
-import threading
-import time
-from typing import Dict, Any, Optional, Union
-from pathlib import Path
-from agent.redact import redact_cdp_url
-from hermes_constants import get_hermes_home, hermes_home_key
-from utils import env_int
-from hermes_cli.config import DEFAULT_CONFIG, cfg_get
-from hermes_cli.observability.shared_metrics_loop import record_browser_call
-
-
-# Env keys re-added to the agent-browser subprocess AFTER credential stripping.
-# agent-browser is a Node process loading npm deps: a compromised transitive
-# dependency could read every Hermes secret from process.env.
-# Strip by default, then re-add only the browser-backend keys the worker legitimately needs. See #29157.
-_BROWSER_PASSTHROUGH_KEYS: tuple[str, ...] = (
- "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "BROWSER_USE_API_KEY",
- "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL", "FIRECRAWL_BROWSER_TTL",
-)
-
def warm_agent_browser_npx_cache(timeout: float = 60.0) -> bool:
- """Frozen old-updater surface (tests/compat/old_updater_surface.json): a pre-PM ``hermes update``
- still running mid-swap imports this from the NEW tree. Nothing is warmed — PM owns the browser
- runtime — and the permanent definition must live here, not behind the revert-scheduled compat
- pointer."""
+ """Frozen old-updater surface: nothing is warmed (there is no agent-browser to warm); always False."""
return False
-
-
-def _build_browser_env() -> dict:
- """Credential-scrubbed env for an agent-browser subprocess (deferred import: test
- harnesses stub the ``tools`` package). The passthrough keys are re-added from the active
- profile's secret scope, never ``os.environ``: under multiplex that holds the LAUNCH profile's
- Browserbase/Firecrawl keys, and a served profile's browser must run on its own (or none)."""
- from agent.secret_scope import current_secret_scope, get_secret, serves_routed_profile
- from tools.environments.local import served_profile_child_env
-
- from agent.proxy_bypass import add_loopback_no_proxy
-
- env = served_profile_child_env(inherit_credentials=False)
- # A routed profile (multiplex, or a Desktop/dashboard backend serving ``?profile=B`` with the
- # flag off) resolves from its bound scope only — a miss is "no key", never the launch profile's
- # ``os.environ`` value that ``get_secret`` falls through to while multiplexing is inactive.
- routed = serves_routed_profile()
- scope = (current_secret_scope() or {}) if routed else None
- for key in _BROWSER_PASSTHROUGH_KEYS:
- value = scope.get(key) if routed else get_secret(key)
- if value is not None:
- env[key] = value
- # The Browser Use harness dials the resolved local CDP URL over ``websockets``; without a
- # loopback NO_PROXY a macOS system proxy captures that dial (#110565).
- # Headed Chromium opens on this profile's Bot Desktop when one is running (human can take it over). Pure: this
- # builder also serves the npx cache warmer, the Chromium auto-installer and the Lightpanda engine, none of which
- # may bring a screen up — the auto-start hook lives at the headed Chromium spawn sites (browser_tool_session).
- from tools.bot_desktop.runtime import desktop_env as _bot_desktop_env
- env = add_loopback_no_proxy(_bot_desktop_env(env))
- # Chrome puts its SingletonSocket under $TMPDIR; a deep scratch dir overflows the AF_UNIX
- # path cap and Chrome dies at startup ("Socket path too long"), so browsers get the short root.
- env["TMPDIR"] = _socket_safe_tmpdir()
- return env
-
-
-try:
- from tools.website_policy import check_website_access
-except Exception:
- check_website_access = lambda url: None
-
-try:
- from tools.url_safety import (
- _is_declared_fake_ip,
- is_safe_url as _is_safe_url,
- is_always_blocked_url as _is_always_blocked_url,
- normalize_url_for_request as _normalize_url_for_request,
- )
-except Exception:
- _is_declared_fake_ip = lambda ip: False
- _is_safe_url = lambda url: False
- _is_always_blocked_url = lambda url: True
- _normalize_url_for_request = lambda url: url
-# Browser-provider ABC + registry; per-vendor providers live under
-# ``plugins/browser/<vendor>/``. The dispatcher consults the registry. See #25214.
-from agent.browser_provider import BrowserProvider
-try:
- from agent.browser_registry import registry_generation as _browser_registry_generation
-except ImportError:
- # Isolated compat tests install a minimal ``agent.browser_registry`` stub
- # with only ``get_provider``; no mutable registry → constant generation.
- def _browser_registry_generation(*, scope=None):
- return (0, 0)
-# Optional backends: Camofox (CAMOFOX_URL routes everything through its REST API)
-# and the Browser Use CLI.
-try:
- from tools.browser_camofox import is_camofox_mode as _is_camofox_mode
-except ImportError:
- _is_camofox_mode = lambda: False
-try:
- from tools.browser_use_cli import is_browser_use_cli_mode as _is_browser_use_cli_mode
-except ImportError:
- _is_browser_use_cli_mode = lambda: False
-
-logger = logging.getLogger(__name__)
-
-# Standard PATH entries for environments with minimal PATH (e.g. systemd services).
-# Includes macOS Homebrew locations for externally installed browser helpers.
-_SANE_PATH_DIRS = (
- "/opt/homebrew/bin",
- "/opt/homebrew/sbin",
- "/usr/local/sbin",
- "/usr/local/bin",
- "/usr/sbin",
- "/usr/bin",
- "/sbin",
- "/bin",
-)
-_SANE_PATH = os.pathsep.join(_SANE_PATH_DIRS)
-
-from tools import browser_tool_install as _install
-
-_last_screenshot_cleanup_by_dir: dict[str, float] = {} # throttles full directory scans
-
-# ----------------------------------------------------------------------------
-# Configuration
-# ----------------------------------------------------------------------------
-DEFAULT_COMMAND_TIMEOUT = 30 # seconds
-
-# Floors for ``open``: cold daemon + first Chromium launch can exceed the
-# generic command_timeout on slow or library-starved Linux hosts.
-MIN_OPEN_TIMEOUT = 60
-MIN_FIRST_OPEN_TIMEOUT = 120
-
-# Snapshot truncation budget — aligned with web_tools.DEFAULT_EXTRACT_CHAR_LIMIT
-# so the model gets the same per-page budget from both paths. Configurable via
-# ``browser.snapshot_threshold``.
-DEFAULT_SNAPSHOT_THRESHOLD = 15000
-MIN_SNAPSHOT_THRESHOLD = 1000
-# Ceiling on the stored full-snapshot file (mirrors web_tools.MAX_STORED_TEXT_CHARS):
-# the stored copy exists for read_file paging and must not be unbounded.
-MAX_STORED_SNAPSHOT_CHARS = 2_000_000
-_EMPTY_OK_COMMANDS: frozenset = frozenset({"close", "record"}) # legitimately empty stdout
-
-# Process caches (``_cached_X`` + ``_X_resolved`` pairs) for config-derived lookups;
-# reset by ``cleanup_all_browsers``. Written/read by the sibling modules via ``browser_tool_origin``.
-# The config-derived ones are keyed by profile home (``hermes_home_key()``): the multiplexed
-# gateway serves every profile from one process, so a single slot would hand the launch
-# profile's browser settings to every other profile.
-_cached_command_timeout: Optional[dict[str, int]] = None
-# Flip the resolved flag BEFORE nulling the cache so a concurrent reader never sees ``resolved=True`` with
-# ``cache=None`` (#14331).
-_command_timeout_resolved = False
-_cached_snapshot_threshold: Optional[dict[str, int]] = None
-_snapshot_threshold_resolved = False
-_cached_cloud_provider: Optional[BrowserProvider] = None
-_cloud_provider_resolved = False
-_cached_cloud_provider_scope: Optional[str] = None
-_cached_cloud_providers: dict[tuple[str, tuple[int, int]], Optional[BrowserProvider]] = {}
-_cloud_provider_cache_lock = threading.RLock()
-_allow_private_urls_resolved = False
-_cached_allow_private_urls: Optional[bool] = None
-_cached_browser_engine: Optional[str] = None # agent-browser v0.25.3+ ``--engine lightpanda``
-_browser_engine_resolved = False
-_auto_local_for_private_urls_resolved = False
-_cached_auto_local_for_private_urls: bool = True
-_cached_headed_mode: Optional[bool] = None
-_headed_mode_resolved = False
-_chromium_autoinstall_attempted = False # one-shot: a failed 170MB download must not retry per call
-
-# Mask secrets in logged CDP URLs; agent.redact.redact_cdp_url is the single policy.
-_sanitize_url_for_logs = redact_cdp_url
-
-
-def _browser_cfg(key: str, default, parse, log_label: str):
- """``parse(browser.<key>)`` from the RAW profile config (loader warnings must not
- leak into tool JSON); ``default`` when absent, not a mapping, or on any error."""
- try:
- from hermes_cli.config import read_raw_config
- browser_cfg = read_raw_config().get("browser", {})
- if isinstance(browser_cfg, dict) and key in browser_cfg:
- return parse(browser_cfg[key])
- except Exception as e:
- logger.debug("Could not read %s: %s", log_label, e)
- return default
-
-
-def _cached_browser_cfg(cache_name: str, flag_name: str, key: str, default, parse, log_label: str):
- """Process-cached ``_browser_cfg`` read, one slot per profile home (cleared by
- ``cleanup_all_browsers``). The value is stored BEFORE the resolved flag flips so a
- concurrent reader never sees ``resolved=True`` with an empty cache."""
- g = globals()
- home = hermes_home_key()
- cache = g[cache_name]
- if cache is None:
- cache = g[cache_name] = {}
- if g[flag_name] and cache.get(home) is not None:
- return cache[home]
- result = _browser_cfg(key, default, parse, log_label)
- cache[home] = result
- g[flag_name] = True
- return result
-
-
-def _get_command_timeout() -> int:
- """``browser.command_timeout`` (floored at 5s; default 30s)."""
- return _cached_browser_cfg(
- "_cached_command_timeout", "_command_timeout_resolved",
- "command_timeout", DEFAULT_COMMAND_TIMEOUT,
- lambda v: DEFAULT_COMMAND_TIMEOUT if v is None else max(int(v), 5),
- "command_timeout from config",
- )
-
-
-def _safe_command_timeout() -> int:
- """``_get_command_timeout`` guaranteed non-None (cache reset mid-flight); ``is not
- None`` rather than ``or`` so a configured ``0`` is preserved."""
- val = _get_command_timeout()
- return val if val is not None else DEFAULT_COMMAND_TIMEOUT
-
-
-def get_browser_snapshot_threshold() -> int:
- """``browser.snapshot_threshold`` (floored at MIN_SNAPSHOT_THRESHOLD)."""
- return _cached_browser_cfg(
- "_cached_snapshot_threshold", "_snapshot_threshold_resolved",
- "snapshot_threshold", DEFAULT_SNAPSHOT_THRESHOLD,
- lambda v: DEFAULT_SNAPSHOT_THRESHOLD if v is None else max(int(v), MIN_SNAPSHOT_THRESHOLD),
- "browser.snapshot_threshold",
- )
-
-
-def _get_open_command_timeout(*, first_open: bool = False) -> int:
- """Timeout for agent-browser ``open`` (navigation / daemon cold start)."""
- return max(_safe_command_timeout(), MIN_FIRST_OPEN_TIMEOUT if first_open else MIN_OPEN_TIMEOUT)
-
-
-from tools import browser_tool_session as _session
-
-
-def _get_vision_model() -> Optional[str]:
- """Model for browser_vision (screenshot analysis — multimodal)."""
- return os.getenv("AUXILIARY_VISION_MODEL", "").strip() or None
-
-
-from tools import browser_tool_cdp as _cdp
-
-from tools import browser_tool_cloud as _cloud
-
-from tools import browser_tool_lightpanda_fallback as _lp
-
-
-# Single shared real-profile copy-browser session: concurrent tasks reuse it
-# instead of each launching a rival Chromium on the same copied user-data-dir.
-_REAL_PROFILE_SESSION = "hermes-real-profile"
-# Keep lock contention well inside the agent's 420-second outer tool deadline.
-# The holder may be an abandoned daemon worker that Python cannot terminate.
-_REAL_PROFILE_CDP_LOCK_TIMEOUT_S = 30.0
-_real_profile_cdp_lock = threading.Lock()
-_real_profile_cdp_cache: dict = {}
-_real_profile_chrome_procs: list = [] # Popen handles of directly-launched real browsers
-
-
-
-_PRIVATE_HOST_SUFFIXES = (".localhost", ".local", ".lan", ".internal")
-
-
-def _url_is_private(url: str) -> bool:
- """True when the URL's host is (or resolves to) a private/LAN/loopback/CGNAT address.
- Routing oracle only: DNS failures are NOT private (the configured backend surfaces the
- error); obvious names short-circuit the DNS hop. A local proxy's declared fake-ip sentinel
- (``security.fake_ip_ranges``) is not private: the name is public, the cloud browser resolves
- it itself, so routing it to the local sidecar would send every URL local on such a host."""
- import ipaddress
- import socket
- from urllib.parse import urlparse
-
- def private(host: str) -> Optional[bool]: # None when ``host`` is not an IP literal
- try:
- ip = ipaddress.ip_address(host)
- except ValueError:
- return None
- if _is_declared_fake_ip(ip):
- return False
- return ip.is_private or ip.is_loopback or ip.is_link_local or ip in ipaddress.ip_network("100.64.0.0/10")
-
- try:
- hostname = (urlparse(url).hostname or "").strip().lower().rstrip(".")
- if not hostname:
- return False
- if (literal := private(hostname)) is not None:
- return literal
- if hostname == "localhost" or hostname.endswith(_PRIVATE_HOST_SUFFIXES):
- return True
- try:
- addr_info = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
- except socket.gaierror:
- return False
- return any(private(sockaddr[0]) for *_, sockaddr in addr_info)
- except Exception as exc:
- logger.debug("URL-privacy check failed for %s: %s", url, exc)
- return False
-
-
-def _hybrid_routes_locally(url: str) -> bool:
- """True when ``url`` belongs on the hybrid LOCAL sidecar instead of the cloud provider: a cloud provider
- configured, ``browser.auto_local_for_private_urls`` on, a private URL, no CDP override (it owns the
- whole session), Camofox off (already local-only). Shared by browser_navigate and browser_exec."""
- return (
- not _cdp._get_cdp_override_raw()
- and not _is_camofox_mode()
- and _cloud._get_cloud_provider() is not None
- and _cloud._auto_local_for_private_urls()
- and _url_is_private(url)
- )
-
-
-def _navigation_session_key(task_id: str, url: str) -> str:
- """Session key that should handle ``url`` for ``task_id``: ``f"{task_id}::local"`` (hybrid
- local sidecar while the cloud session keeps serving public URLs) when
- ``_hybrid_routes_locally`` holds for ``url``."""
- if task_id is None:
- task_id = "default"
- return f"{task_id}{_LOCAL_SUFFIX}" if _hybrid_routes_locally(url) else task_id
-
-
-def _is_local_sidecar_key(session_key: str) -> bool:
- return session_key.endswith(_LOCAL_SUFFIX)
-
-
-def _bare_task_id_for_session_key(session_key: str) -> str:
- return session_key[: -len(_LOCAL_SUFFIX)] if _is_local_sidecar_key(session_key) else session_key
-
-
-def _session_info_owned_by_task(session_info: dict[str, Any], task_id: str, session_key: str) -> bool:
- """Ownership check; entries without metadata (older in-memory / hot-reload) pass,
- any explicit mismatch fails before a non-nav tool can act on the wrong session."""
- owner = session_info.get("owner_task_id")
- key = session_info.get("session_key")
- return (owner is None or owner == task_id) and (key is None or key == session_key)
-
-
-def _last_session_key(task_id: str) -> str:
- """Session key a non-nav tool must use: the one that served the task's last navigation.
- If it was cleaned up or ownership no longer matches, fail closed by dropping the stale
- binding rather than recreating or mutating the wrong browser."""
- if task_id is None:
- task_id = "default"
- recorded_key = _last_active_session_key.get(task_id)
- if not recorded_key:
- return task_id
- with _cleanup_lock:
- session_info = _active_sessions.get(recorded_key)
- if session_info and _session_info_owned_by_task(session_info, task_id, recorded_key):
- return recorded_key
- _last_active_session_key.pop(task_id, None)
- logger.debug("browser session ownership: dropping stale/mismatched last-active binding %s -> %s",
- task_id, recorded_key)
- return task_id
-
-
-def _socket_safe_tmpdir() -> str:
- """Temp root short enough for the agent-browser socket dir and Chrome's SingletonSocket
- (``hermes_constants.socket_safe_tmpdir``)."""
- from hermes_constants import socket_safe_tmpdir
- return socket_safe_tmpdir()
-
-
-# Active sessions keyed by "session key": the bare task_id, or f"{task_id}::local"
-# for a hybrid-routing local sidecar (opaque to _run_browser_command / cleanup_browser).
-# Values: session_name (always), bb_session_id + cdp_url (cloud).
-_active_sessions: dict[str, dict[str, Any]] = {}
-_recording_sessions: set = set() # session_keys with active recordings
-# Most recent session_key per task_id (set by browser_navigate, read by every non-nav
-# tool) so click/snapshot land in the session that served the last navigation.
-_last_active_session_key: dict[str, str] = {}
-_LOCAL_SUFFIX = "::local"
-_cleanup_done = False
-
-# Inactivity timeout: config.yaml is authoritative; BROWSER_INACTIVITY_TIMEOUT
-# remains a legacy env fallback for unmigrated deployments.
-DEFAULT_SESSION_INACTIVITY_TIMEOUT = int(DEFAULT_CONFIG.get("browser", {}).get("inactivity_timeout", 120))
-
-
-def _get_session_inactivity_timeout() -> int:
- env_default = env_int("BROWSER_INACTIVITY_TIMEOUT", DEFAULT_SESSION_INACTIVITY_TIMEOUT)
- return _browser_cfg(
- "inactivity_timeout", env_default,
- lambda v: env_default if v is None else max(int(v), 30), # 30s floor: no instant reaping
- "inactivity_timeout from config",
- )
-
-
-BROWSER_SESSION_INACTIVITY_TIMEOUT = _get_session_inactivity_timeout()
-# Orphan reaper cadence: a startup-only reap can never recover from a leak that
-# appears after boot in a long-lived process.
-BROWSER_ORPHAN_REAP_INTERVAL = 300 # seconds
-# Idle ceiling for a daemon whose owner is alive but which fell out of in-memory
-# tracking (owner-alive alone would make it immortal); large multiple so a busy
-# session is never touched.
-BROWSER_ORPHAN_GRACE_SECONDS = max(3600, BROWSER_SESSION_INACTIVITY_TIMEOUT * 20)
-
-_session_last_activity: dict[str, float] = {}
-# Owner Hermes home per session: the janitor is one process-global thread, so each
-# teardown must re-enter the OWNING profile's scope (copy_context at spawn would
-# pin the first profile's secrets onto every other profile's teardown).
-# See #86402.
-_session_owner_homes: dict[str, str] = {}
-# Consecutive janitor failures per session; force-reaped after MAX_INACTIVITY_CLEANUP_FAILURES.
-# See #100738.
-_cleanup_failures: dict[str, int] = {}
-MAX_INACTIVITY_CLEANUP_FAILURES = 3
-
-# Session keys flagged suspect after a command timeout (written lock-free by
-# mark_suspect; consumed by ensure_healthy() at next use, which recycles).
-# See #72205.
-_suspect_browser_sessions: dict[str, str] = {}
-
-
-class _BrowserSessionBackend:
- """``agent.deadline.SuspectableBackend`` adapter for one cached session key: the
- timeout path calls ``mark_suspect`` inline; ``ensure_healthy`` runs at the top of
- ``_get_session_info`` — the choke point every command passes through."""
-
- __slots__ = ("_session_key",)
-
- def __init__(self, session_key: str) -> None:
- self._session_key = session_key
-
- def mark_suspect(self, reason: str) -> None:
- """MUST stay cheap and lock-free (runs inline on the timed-out caller's thread)."""
- _suspect_browser_sessions[self._session_key] = reason
-
- def ensure_healthy(self) -> bool:
- """Recycle the session when a prior timeout marked it suspect; False after teardown.
- The flag is popped BEFORE teardown: ``close`` re-enters ``_get_session_info``
- and must not recurse into another recycle."""
- reason = _suspect_browser_sessions.pop(self._session_key, None)
- if reason is None:
- return True
- logger.info("Recycling suspect browser session %s before reuse (%s)", self._session_key, reason)
- try:
- _lifecycle._cleanup_single_browser_session(self._session_key)
- except Exception:
- logger.warning("Teardown of suspect browser session %s failed; a fresh "
- "session will be created anyway", self._session_key, exc_info=True)
- return False
-
-
-_browser_session_backend = _BrowserSessionBackend
-
-_cleanup_thread = None
-_cleanup_running = False
-_cleanup_lock = threading.Lock() # protects _session_last_activity AND _active_sessions
-
-from tools import browser_tool_lifecycle as _lifecycle
-
-# atexit only — NO SIGINT/SIGTERM handlers calling sys.exit(): a SystemExit raised
-# inside a prompt_toolkit key-binding callback corrupts the coroutine state and
-# makes the process unkillable.
-atexit.register(_lifecycle._emergency_cleanup_all_sessions)
-atexit.register(_lifecycle._stop_browser_cleanup_thread)
-
-# ----------------------------------------------------------------------------
-# Tool Schemas
-# ----------------------------------------------------------------------------
-BROWSER_TOOL_SCHEMAS = [
- {
- "name": "browser_navigate",
- "description": "Navigate to a URL in the browser. Initializes the session and loads the page. Must be called before other browser tools. For simple information retrieval, prefer a lightweight retrieval tool when one is available (faster, cheaper). For plain-text endpoints — URLs ending in .md, .txt, .json, .yaml, .yml, .csv, .xml, raw.githubusercontent.com, or any documented API endpoint — prefer an available text-extraction or terminal-fetch tool; the browser stack is overkill and much slower for these. Use browser tools when you need to interact with a page (click, fill forms, dynamic content). Returns a compact page snapshot with interactive elements and ref IDs — no need to call browser_snapshot separately after navigating.",
- "parameters": {
- "type": "object",
- "properties": {
- "url": {
- "type": "string",
- "description": "The URL to navigate to (e.g., 'https://example.com')"
- }
- },
- "required": ["url"]
- }
- },
- {
- "name": "browser_snapshot",
- "description": "Get a text-based snapshot of the current page's accessibility tree. Returns interactive elements with ref IDs (like @e1, @e2) for browser_click and browser_type. full=false (default): compact view with interactive elements. full=true: complete page content. Snapshots over 15000 chars are truncated or LLM-summarized; when that happens the complete snapshot is saved to a file and the output includes its path so you can page through the rest with read_file. Requires browser_navigate first. Note: browser_navigate already returns a compact snapshot — use this to refresh after interactions that change the page, or with full=true for complete content.",
- "parameters": {
- "type": "object",
- "properties": {
- "full": {
- "type": "boolean",
- "description": "If true, returns complete page content. If false (default), returns compact view with interactive elements only.",
- "default": False
- }
- },
- "required": []
- }
- },
- {
- "name": "browser_click",
- "description": "Click on an element identified by its ref ID from the snapshot (e.g., '@e5'). The ref IDs are shown in square brackets in the snapshot output. Requires browser_navigate and browser_snapshot to be called first.",
- "parameters": {
- "type": "object",
- "properties": {
- "ref": {
- "type": "string",
- "description": "The element reference from the snapshot (e.g., '@e5', '@e12')"
- }
- },
- "required": ["ref"]
- }
- },
- {
- "name": "browser_type",
- "description": "Type text into an input field identified by its ref ID. Clears the field first, then types the new text. Requires browser_navigate and browser_snapshot to be called first.",
- "parameters": {
- "type": "object",
- "properties": {
- "ref": {
- "type": "string",
- "description": "The element reference from the snapshot (e.g., '@e3')"
- },
- "text": {
- "type": "string", "description": "The text to type into the field"
- }
- },
- "required": ["ref", "text"]
- }
- },
- {
- "name": "browser_scroll",
- "description": "Scroll the page in a direction. Use this to reveal more content that may be below or above the current viewport. Requires browser_navigate to be called first.",
- "parameters": {
- "type": "object",
- "properties": {
- "direction": {
- "type": "string", "enum": ["up", "down"], "description": "Direction to scroll"
- }
- },
- "required": ["direction"]
- }
- },
- {
- "name": "browser_back",
- "description": "Navigate back to the previous page in browser history. Requires browser_navigate to be called first.",
- "parameters": {
- "type": "object", "properties": {}, "required": []
- }
- },
- {
- "name": "browser_press",
- "description": "Press a keyboard key. Useful for submitting forms (Enter), navigating (Tab), or keyboard shortcuts. Requires browser_navigate to be called first.",
- "parameters": {
- "type": "object",
- "properties": {
- "key": {
- "type": "string",
- "description": "Key to press (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown')"
- }
- },
- "required": ["key"]
- }
- },
- {
- "name": "browser_get_images",
- "description": "Get a list of all images on the current page with their URLs and alt text. Useful for finding images to analyze with the vision tool. Requires browser_navigate to be called first.",
- "parameters": {
- "type": "object", "properties": {}, "required": []
- }
- },
- {
- "name": "browser_vision",
- "description": "Take a screenshot of the current page so you can inspect it visually. Use this when you need to understand what the page looks like - especially for CAPTCHAs, visual verification challenges, complex layouts, or cases where the text snapshot misses important visual information. When your active model has native vision, the screenshot is attached to your context directly and you inspect it on the next turn; otherwise Hermes falls back to an auxiliary vision model and returns a text analysis. Includes a screenshot_path that you can share with the user by including MEDIA:<screenshot_path> in your response. Requires browser_navigate to be called first.",
- "parameters": {
- "type": "object",
- "properties": {
- "question": {
- "type": "string",
- "description": "What you want to know about the page visually. Be specific about what you're looking for."
- },
- "annotate": {
- "type": "boolean",
- "default": False,
- "description": "If true, overlay numbered [N] labels on interactive elements. Each [N] maps to ref @eN for subsequent browser commands. Useful for QA and spatial reasoning about page layout."
- }
- },
- "required": ["question"]
- }
- },
- {
- "name": "browser_console",
- "description": "Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requires browser_navigate to be called first. When 'expression' is provided, evaluates JavaScript in the page context and returns the result — use this for DOM inspection, reading page state, or extracting data programmatically.",
- "parameters": {
- "type": "object",
- "properties": {
- "clear": {
- "type": "boolean",
- "default": False,
- "description": "If true, clear the message buffers after reading"
- },
- "expression": {
- "type": "string",
- "description": "JavaScript expression to evaluate in the page context. Runs in the browser like DevTools console — full access to DOM, window, document. Return values are serialized to JSON. Example: 'document.title' or 'document.querySelectorAll(\"a\").length'"
- }
- },
- "required": []
- }
- },
-]
-
-from tools import browser_tool_snapshot as _snapshot
-
-# ----------------------------------------------------------------------------
-# Browser Tool Functions
-# ----------------------------------------------------------------------------
-
-def _err(error: str, **extra) -> dict:
- return {"success": False, "error": error, **extra}
-
-
-def _dumps(payload: dict[str, Any], **kw) -> str:
- return json.dumps(payload, ensure_ascii=False, **kw)
-
-
-def _secret_url_error(url: str) -> Optional[dict]:
- """Refuse URLs embedding an API key/token (raw and URL-decoded, catching ``%2D``
- tricks) — a prompt injection could otherwise exfiltrate secrets via the URL."""
- import urllib.parse
- from agent.redact import _PREFIX_RE
-
- if _PREFIX_RE.search(url) or _PREFIX_RE.search(urllib.parse.unquote(url)):
- return _err("Blocked: URL contains what appears to be an API key or token. Secrets must not be sent in URLs.")
- return None
-
-
-def _url_policy_error(url: str, *, auto_local: bool = False) -> Optional[dict]:
- """Backend-aware URL checks on an already-normalized URL; None if allowed. Ordered floors:
- (1) cloud metadata / IMDS refused UNCONDITIONALLY (a local Chromium on a cloud VM still
- reaches the host IMDS); (2) private addresses refused unless local, sidecar-routed, or
- ``browser.allow_private_urls``; (3) website policy allow/deny lists.
-
- Credential-NAMED query params (``?token=``, ``?signature=``) are deliberately NOT a floor:
- magic links, OAuth callbacks and signed CDN assets are how the agent signs in and browses, and
- a cloud browser already sees every cookie and typed password of the session — refusing the
- URL protects nothing. Hermes' own secrets leaking into a URL are caught by ``_secret_url_error``."""
- local = _cloud._is_local_backend()
- # Always-blocked floor: cloud metadata / IMDS endpoints are denied regardless of backend, hybrid
- # routing, or allow_private_urls. There's no legitimate agent use case for navigating to 169.254.169.254
- # / metadata.google.internal / ECS task metadata via a browser, and routing those to a local Chromium
- # sidecar on an EC2/GCP/Azure host exfiltrates IAM credentials (#16234). The floor is UNCONDITIONAL — it
- # must fire for every backend, including the pure-local headless Chromium and off-host CDP cases (a
- # local Chromium on a cloud VM still reaches the host IMDS).
- if _is_always_blocked_url(url):
- return _err("Blocked: URL targets a cloud metadata endpoint")
- if not local and not auto_local and not _cloud._allow_private_urls() and not _is_safe_url(url):
- return _err("Blocked: URL targets a private or internal address")
- blocked = check_website_access(url)
- if blocked:
- return _err(blocked["message"],
- blocked_by_policy={"host": blocked["host"], "rule": blocked["rule"], "source": blocked["source"]})
- return None
-
-
-def _secret_url_error_normalized(url: str) -> tuple[str, Optional[dict]]:
- """Secret check on the raw URL, then again on the normalized one; returns ``(url, error)``."""
- err = _secret_url_error(url)
- if err is None:
- url = _normalize_url_for_request(url)
- err = _secret_url_error(url)
- return url, err
-
-
-def evaluate_url_safety(url: str, *, auto_local: bool = False) -> Optional[dict]:
- """Run URL safety checks; None if safe, else an error dict. ``auto_local`` (the URL is served by the
- hybrid local sidecar) relaxes only the private-address floor, never the cloud-metadata one."""
- url, err = _secret_url_error_normalized(url)
- return err or _url_policy_error(url, auto_local=auto_local)
-
-
-_BOT_DETECTION_TITLE_PATTERNS = (
- "access denied", "access to this page has been denied", "blocked", "bot detected", "verification required",
- "please verify", "are you a robot", "captcha", "cloudflare", "ddos protection", "checking your browser",
- "just a moment", "attention required",
-)
-
-
-def _post_redirect_block(nav_session_key: str, url: str, final_url: str, auto_local_this_nav: bool) -> Optional[str]:
- """Post-redirect SSRF check; blocked JSON payload or None. The page is moved to about:blank
- first so later snapshots can't read the internal content. The metadata floor fires for
- every backend; the private-address check is skipped for local, the sidecar, and
- ``browser.allow_private_urls``."""
- if not final_url or final_url == url:
- return None
- if _is_always_blocked_url(final_url):
- what = "a cloud metadata endpoint"
- elif (
- not _cloud._is_local_backend()
- and not auto_local_this_nav
- and not _cloud._allow_private_urls()
- and not _is_safe_url(final_url)
- ):
- what = "a private/internal address"
- else:
- return None
- _session._run_browser_command(nav_session_key, "open", ["about:blank"], timeout=10)
- return json.dumps(_err(f"Blocked: redirect landed on {what}"))
-
-
-def _snapshot_fields(snap_result: dict[str, Any]) -> dict[str, Any]:
- """``snapshot`` + ``element_count`` fields from a successful snapshot result; oversized
- snapshots truncate at line boundaries with the full tree stored for read_file paging."""
- data = snap_result.get("data", {})
- snapshot_text = data.get("snapshot", "")
- refs = data.get("refs", {})
- threshold = get_browser_snapshot_threshold()
- if len(snapshot_text) > threshold:
- snapshot_text = _snapshot._truncate_snapshot(snapshot_text, max_chars=threshold)
- return {"snapshot": _snapshot._redact_browser_output(snapshot_text), "element_count": len(refs) if refs else 0}
-
-
-def _merge_fallback_warning(response: dict[str, Any], result: dict[str, Any]) -> None:
- """Copy a secondary result's fallback warning only if the response has none yet."""
- if result.get("fallback_warning") and not response.get("fallback_warning"):
- _lp._copy_fallback_warning(response, result)
-
-
-def _attach_auto_snapshot(response: dict[str, Any], nav_session_key: str) -> None:
- """Add a compact snapshot to a navigate response so the model can act without browser_snapshot."""
- try:
- snap_result = _session._run_browser_command(nav_session_key, "snapshot", ["-c"])
- if snap_result.get("success"):
- response.update(_snapshot_fields(snap_result))
- _merge_fallback_warning(response, snap_result)
- except Exception as e:
- logger.debug("Auto-snapshot after navigate failed: %s", e)
-
-
-def browser_navigate(url: str, task_id: Optional[str] = None) -> str:
- """Navigate to ``url``; JSON with title, compact snapshot and, on first nav, stealth features.
- Hybrid routing decides BEFORE the safety checks whether this URL goes to a local sidecar
- (the cloud provider never sees it then, so the private-address checks are relaxed)."""
- url, safety_error = _secret_url_error_normalized(url)
- if safety_error is not None:
- return json.dumps(safety_error)
-
- effective_task_id = task_id or "default"
- nav_session_key = _navigation_session_key(effective_task_id, url)
- auto_local_this_nav = _is_local_sidecar_key(nav_session_key)
-
- safety_error = _url_policy_error(url, auto_local=auto_local_this_nav)
- if safety_error is not None:
- return json.dumps(safety_error)
-
- if _is_camofox_mode():
- return _camofox("camofox_navigate", url, task_id)
-
- if auto_local_this_nav:
- logger.info("browser_navigate: auto-routing %s to local Chromium sidecar (cloud provider %s stays on "
- "cloud for public URLs; set browser.auto_local_for_private_urls: false to disable)",
- url, type(_cloud._get_cloud_provider()).__name__ if _cloud._get_cloud_provider() else "none")
-
- session_info = _session._get_session_info(nav_session_key)
- is_first_nav = session_info.get("_first_nav", True)
- if is_first_nav:
- session_info["_first_nav"] = False
- _maybe_start_recording(nav_session_key)
-
- result = _session._run_browser_command(nav_session_key, "open", [url],
- timeout=_get_open_command_timeout(first_open=is_first_nav))
- if not result.get("success"):
- return _dumps(_err(result.get("error", "Navigation failed")))
-
- data = result.get("data", {})
- title = data.get("title", "")
- final_url = data.get("url", url)
- blocked = _post_redirect_block(nav_session_key, url, final_url, auto_local_this_nav)
- if blocked is not None:
- return blocked
-
- response = {"success": True, "url": final_url, "title": title}
- features = session_info.get("features") or {}
- if features.get("real_profile"): # auditability: this ran on the user's real-profile copy-browser
- response["used_real_profile"] = True
- elif session_info.get("real_profile_unavailable") and not session_info.get("_rp_note_shown"):
- session_info["_rp_note_shown"] = True # first SUCCESSFUL navigation carries it, failed opens don't eat it
- response["real_profile_unavailable"] = session_info["real_profile_unavailable"]
- # Only a successful, non-blocked navigation becomes the task owner: failed opens
- # and blocked redirects must not retarget follow-up clicks to an irrelevant session.
- _last_active_session_key[effective_task_id] = nav_session_key
- _lp._copy_fallback_warning(response, result)
- _add_navigate_warnings(response, title, session_info if is_first_nav else None)
- _attach_auto_snapshot(response, nav_session_key)
- return _dumps(response)
-
-
-def _add_navigate_warnings(response: dict[str, Any], title: str, first_nav_session: Optional[dict[str, Any]]) -> None:
- """Bot-detection hint from the page title; on first navigation, the session's stealth features."""
- title_lower = title.lower()
- if any(pattern in title_lower for pattern in _BOT_DETECTION_TITLE_PATTERNS):
- response["bot_detection_warning"] = (
- f"Page title '{title}' suggests bot detection. The site may have blocked this request. "
- "Options: 1) Try adding delays between actions, 2) Access different pages first, "
- "3) Enable advanced stealth (BROWSERBASE_ADVANCED_STEALTH=true, requires Scale plan), "
- "4) Some sites have very aggressive bot detection that may be unavoidable."
- )
- if first_nav_session is not None and "features" in first_nav_session:
- features = first_nav_session["features"]
- if not features.get("proxies"):
- response["stealth_warning"] = (
- "Running WITHOUT residential proxies. Bot detection may be more aggressive. "
- "Consider upgrading Browserbase plan for proxy support."
- )
- response["stealth_features"] = [k for k, v in features.items() if v]
-
-
-def browser_snapshot(
- full: bool = False, task_id: Optional[str] = None, user_task: Optional[str] = None
-) -> str:
- """Text snapshot of the page's accessibility tree (compact unless ``full``).
- ``user_task`` is deprecated and unused (oversized snapshots always truncate-and-store)."""
- if _is_camofox_mode():
- return _camofox("camofox_snapshot", full, task_id)
- effective_task_id = _last_session_key(task_id or "default")
- result = _session._run_browser_command(effective_task_id, "snapshot", [] if full else ["-c"])
- if not result.get("success"):
- return _failed_response(result, "Failed to get snapshot")
-
- blocked = _blocked_private_page_content(effective_task_id)
- if blocked is not None:
- return blocked
-
- response = {"success": True, **_snapshot_fields(result)}
- _lp._copy_fallback_warning(response, result)
-
- # Merge supervisor state (pending dialogs + frame tree) when a CDP supervisor is
- # attached. See website/docs/developer-guide/browser-supervisor.md.
- try:
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- _supervisor = SUPERVISOR_REGISTRY.get(effective_task_id)
- if _supervisor is not None:
- _sv_snap = _supervisor.snapshot()
- if _sv_snap.active:
- response.update(_snapshot._redact_browser_output(_sv_snap.to_dict()))
- except Exception as _sv_exc:
- logger.debug("supervisor snapshot merge failed: %s", _sv_exc)
-
- return _dumps(response)
-
-
-def _json_with_fallback(response: dict[str, Any], result: dict[str, Any]) -> str:
- """``json.dumps`` of ``response`` with the Lightpanda fallback metadata copied from ``result``."""
- return _dumps(_lp._copy_fallback_warning(response, result))
-
-
-def _failed_response(result: dict[str, Any], default_error: str) -> str:
- # ``code`` = machine-readable refusal (human_has_control), same shape as computer_use's.
- extra = {"code": result["code"]} if result.get("code") else {}
- return _json_with_fallback(_err(result.get("error", default_error), **extra), result)
-
-
-def _tool_response(result: dict[str, Any], ok: dict[str, Any], default_error: str) -> str:
- """``{"success": True, **ok}`` or ``{"success": False, "error": result.error or default}``, plus fallback metadata."""
- if not result.get("success"):
- return _failed_response(result, default_error)
- return _json_with_fallback({"success": True, **ok}, result)
-
-
-def _camofox(func_name: str, *args):
- """Call ``tools.browser_camofox.<func_name>(*args)`` (Camofox mode delegation)."""
- import importlib
- return getattr(importlib.import_module("tools.browser_camofox"), func_name)(*args)
-
-
-def _guarded_action(task_id: Optional[str], action: str, command: str, args: list, ok: dict[str, Any], err: str) -> str:
- """Input action on the task's current page, refused when the SSRF guard flags the page."""
- effective_task_id = _last_session_key(task_id or "default")
- blocked = _blocked_private_page_action(effective_task_id, action)
- if blocked is not None:
- return blocked
- return _tool_response(_session._run_browser_command(effective_task_id, command, args), ok, err)
-
-
-def _at_ref(ref: str) -> str:
- return ref if ref.startswith("@") else f"@{ref}"
-
-
-def browser_click(ref: str, task_id: Optional[str] = None) -> str:
- """Click the element ``ref`` (e.g. "@e5")."""
- if _is_camofox_mode():
- return _camofox("camofox_click", ref, task_id)
- ref = _at_ref(ref)
- return _guarded_action(task_id, "click", "click", [ref], {"clicked": ref}, f"Failed to click {ref}")
-
-
-def browser_type(ref: str, text: str, task_id: Optional[str] = None) -> str:
- """Type ``text`` into the element ``ref`` (fill: clears, then types)."""
- if _is_camofox_mode():
- return _camofox("camofox_type", ref, text, task_id)
- effective_task_id = _last_session_key(task_id or "default")
- blocked = _blocked_private_page_action(effective_task_id, "type")
- if blocked is not None:
- return blocked
- ref = _at_ref(ref)
- result = _session._run_browser_command(effective_task_id, "fill", [ref, text])
- from agent.display import redact_browser_typed_text_for_display, redact_tool_args_for_display
- # Typed text goes through the secret-pattern redactor so API keys / tokens don't
- # leak into tool progress or chat history (the raw value already went to the browser).
- display_text = (redact_tool_args_for_display("browser_type", {"text": text}) or {})["text"]
- if result.get("success"):
- response = {"success": True, "typed": display_text, "element": ref}
- else:
- response = _err(result.get("error", f"Failed to type into {ref}"))
- return _dumps(redact_browser_typed_text_for_display(_lp._copy_fallback_warning(response, result), text))
-
-
-def browser_scroll(direction: str, task_id: Optional[str] = None) -> str:
- """Scroll the page ``direction`` ("up"/"down") by about half a viewport."""
- if direction not in {"up", "down"}:
- return _dumps(_err(f"Invalid direction '{direction}'. Use 'up' or 'down'."))
- _SCROLL_PIXELS = 500 # ~half a viewport in one call instead of 5x subprocess calls
- if _is_camofox_mode(): # Camofox REST API has no pixel argument; use repeated calls
- return [_camofox("camofox_scroll", direction, task_id) for _ in range(5)][-1]
- effective_task_id = _last_session_key(task_id or "default")
- result = _session._run_browser_command(effective_task_id, "scroll", [direction, str(_SCROLL_PIXELS)])
- return _tool_response(result, {"scrolled": direction}, f"Failed to scroll {direction}")
-
-
-def browser_back(task_id: Optional[str] = None) -> str:
- """Navigate back in browser history."""
- if _is_camofox_mode():
- return _camofox("camofox_back", task_id)
- effective_task_id = _last_session_key(task_id or "default")
- result = _session._run_browser_command(effective_task_id, "back", [])
- if result.get("success"):
- # History can land on a private/internal/metadata address the navigate
- # preflight never saw (earlier redirect chain, manipulated client-side history).
- blocked = _blocked_private_page(effective_task_id, "Browser history navigation (back) landed on this address.")
- if blocked is not None:
- return blocked
- return _tool_response(result, {"url": result.get("data", {}).get("url", "")}, "Failed to go back")
-
-
-def browser_press(key: str, task_id: Optional[str] = None) -> str:
- """Press a keyboard key (e.g. "Enter", "Tab")."""
- if _is_camofox_mode():
- return _camofox("camofox_press", key, task_id)
- return _guarded_action(task_id, "press", "press", [key], {"pressed": key}, f"Failed to press {key}")
-
-
-def _blocked_private_page_json(blocked_url: str, why: str) -> str:
- """Refusal payload for a page whose URL targets a private/internal address."""
- return _dumps(_err(f"Blocked: page URL targets a private or internal address ({blocked_url}). {why}"))
-
-
-def _blocked_private_page(effective_task_id: str, why: str) -> Optional[str]:
- """Blocked payload when the SSRF guard is active and the current page is private, else
- None. Fail-open on probe failure (see ``_current_page_private_url``)."""
- if not _eval_policy._eval_ssrf_guard_active(effective_task_id):
- return None
- blocked_url = _eval_policy._current_page_private_url(effective_task_id)
- return _blocked_private_page_json(blocked_url, why) if blocked_url else None
-
-
-def _blocked_private_page_action(effective_task_id: str, action: str) -> Optional[str]:
- """Blocked payload when an unsafe cloud page would receive input."""
- return _blocked_private_page(effective_task_id, f"Refusing to {action} on this page in this browser mode.")
-
-
-_EVAL_NAVIGATED_WHY = "This may have been caused by a JavaScript navigation via browser_console."
-
-
-def _blocked_private_page_content(effective_task_id: str) -> Optional[str]:
- """Content-returning tools (snapshot/vision/eval/get_images): after an eval that may
- have moved ``location.href`` to a private address, returning content would expose it."""
- return _blocked_private_page(effective_task_id, _EVAL_NAVIGATED_WHY)
-
-
-def browser_console(clear: bool = False, expression: Optional[str] = None, task_id: Optional[str] = None) -> str:
- """Console messages + uncaught JS errors (optionally ``clear``ing the buffers),
- or — when ``expression`` is given — evaluate JS in the page like the DevTools console."""
- if expression is not None:
- policy_error = _eval_policy._enforce_browser_eval_policy(expression)
- if policy_error:
- return _dumps(_err(policy_error))
- return _browser_eval(expression, task_id)
-
- if _is_camofox_mode():
- return _camofox("camofox_console", clear, task_id)
-
- effective_task_id = _last_session_key(task_id or "default")
- blocked = _blocked_private_page_content(effective_task_id)
- if blocked is not None:
- return blocked
-
- clear_args = ["--clear"] if clear else []
- console_result = _session._run_browser_command(effective_task_id, "console", clear_args)
- errors_result = _session._run_browser_command(effective_task_id, "errors", clear_args)
-
- messages = [
- {"type": msg.get("type", "log"), "text": _snapshot._redact_browser_output(msg.get("text", "")), "source": "console"}
- for msg in console_result.get("data", {}).get("messages", [])
- ] if console_result.get("success") else []
- errors = [
- {"message": _snapshot._redact_browser_output(err.get("message", "")), "source": "exception"}
- for err in errors_result.get("data", {}).get("errors", [])
- ] if errors_result.get("success") else []
- response = {
- "success": True, "console_messages": messages, "js_errors": errors,
- "total_messages": len(messages), "total_errors": len(errors),
- }
- _lp._copy_fallback_warning(response, console_result)
- _merge_fallback_warning(response, errors_result)
- return _dumps(response)
-
-
-from tools import browser_tool_eval_policy as _eval_policy
-
-
-def _parse_eval_value(raw_result: Any) -> Any:
- """Eval returns the JS value as a string; parse valid JSON so the model gets structured data."""
- if isinstance(raw_result, str):
- try:
- return json.loads(raw_result)
- except (json.JSONDecodeError, ValueError):
- pass # keep as string
- return raw_result
-
-
-def _eval_ok_response(parsed: Any, **extra) -> dict[str, Any]:
- return {"success": True, "result": _snapshot._redact_browser_output(parsed), "result_type": type(parsed).__name__, **extra}
-
-
-def _eval_result_or_blocked(effective_task_id: str, parsed: Any, result: dict[str, Any], **extra) -> str:
- """Eval tool JSON, unless the post-eval page-URL recheck finds an eval navigated the
- page to a private address — then the result is withheld."""
- blocked = _blocked_private_page_content(effective_task_id)
- if blocked is not None:
- return blocked
- return _dumps(_lp._copy_fallback_warning(_eval_ok_response(parsed, **extra), result), default=str)
-
-
-def _eval_supervisor_fast_path(effective_task_id: str, expression: str) -> Optional[str]:
- """``Runtime.evaluate`` on the CDP supervisor's persistent WebSocket (no subprocess cost).
- Tool JSON when the supervisor gave a definitive answer (value, blocked page, or a real
- JS-side exception — NOT retried via subprocess, that would just reproduce it slower);
- None to fall through to the subprocess path."""
- try:
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- supervisor = SUPERVISOR_REGISTRY.get(effective_task_id)
- if supervisor is None:
- return None
- sup_result = supervisor.evaluate_runtime(expression)
- if sup_result.get("ok"):
- return _eval_result_or_blocked(
- effective_task_id, _parse_eval_value(sup_result.get("result")), {}, method="cdp_supervisor")
- err = sup_result.get("error") or "evaluate_runtime failed"
- if "supervisor" not in err.lower():
- return _dumps(_err(err))
- logger.debug("browser_eval: supervisor path unavailable (%s), falling back to subprocess", err)
- except ImportError:
- pass
- except Exception as exc: # pragma: no cover — defensive
- logger.debug("browser_eval: supervisor path errored (%s), falling back", exc)
- return None
-
-
-def _eval_failure_response(result: dict[str, Any]) -> str:
- """Tool JSON for a failed ``agent-browser eval``, with actionable rewrites of known errors."""
- err = result.get("error", "eval failed")
- if any(hint in err.lower() for hint in ("unknown command", "not supported", "not found", "no such command")):
- err = f"JavaScript evaluation is not supported by this browser backend. {err}"
- elif "reference chain is too long" in err.lower():
- # A live DOM node / NodeList / Window can't be JSON-serialized by CDP. The
- # supervisor path retries with returnByValue=false; the CLI can't.
- err = (
- "Expression returned a live DOM node / NodeList / Window, "
- "which can't be serialized. Extract a primitive value "
- "(e.g. .innerText, .href, .src, .value) or use "
- "JSON.stringify() / a snapshot tool instead."
- )
- return json.dumps(_lp._copy_fallback_warning(_err(err), result))
-
-
-def _browser_eval(expression: str, task_id: Optional[str] = None) -> str:
- """Evaluate JS in the page context. Private-network guard in two halves: the literal
- pre-scan closes direct fetches (they never update ``location.href``); the post-eval
- page-URL recheck closes navigate-then-read."""
- effective_task_id = _last_session_key(task_id or "default")
-
- if _eval_policy._eval_ssrf_guard_active(effective_task_id):
- blocked_literal = _eval_policy._expression_targets_private_url(expression)
- if blocked_literal:
- return _dumps(_err(
- "Blocked: JavaScript expression targets a private or "
- f"internal address ({blocked_literal}). Reading internal "
- "endpoints via browser_console is not permitted in this "
- "browser mode."
- ))
-
- # Camofox keeps its own raw-task_id-keyed session map, so pass the raw id.
- if _is_camofox_mode():
- return _camofox_eval(expression, task_id)
-
- # The supervisor answers over its own WebSocket and never reaches _run_browser_command, so the Bot
- # Desktop lease fence has to bracket it here too — otherwise the one command that reads arbitrary
- # page state is the one a human's takeover does not stop. Same fence, same session identity.
- fenced = _session.run_fenced(_active_sessions.get(effective_task_id) or {},
- lambda: {"fast": _eval_supervisor_fast_path(effective_task_id, expression)})
- if fenced.get("code") == "human_has_control":
- return _dumps(fenced)
- if fenced["fast"] is not None:
- return fenced["fast"]
-
- result = _session._run_browser_command(effective_task_id, "eval", [expression])
- if not result.get("success"):
- return _eval_failure_response(result)
- return _eval_result_or_blocked(effective_task_id, _parse_eval_value(result.get("data", {}).get("result")), result)
-
-
-def _camofox_eval(expression: str, task_id: Optional[str] = None) -> str:
- """Evaluate JS via Camofox's /tabs/{tab_id}/evaluate endpoint (if available)."""
- from tools.browser_camofox import _ensure_tab, _post
- try:
- tab_info = _ensure_tab(task_id or "default")
- tab_id = tab_info.get("tab_id") or tab_info.get("id")
- user_id = tab_info["user_id"]
- resp = _post(f"/tabs/{tab_id}/evaluate", body={"expression": expression, "userId": user_id})
- parsed = _parse_eval_value(resp.get("result") if isinstance(resp, dict) else resp)
-
- if _eval_policy._eval_ssrf_guard_active(task_id or "default"):
- _blocked_url = _eval_policy._camofox_current_page_private_url(tab_id, user_id)
- if _blocked_url:
- return _blocked_private_page_json(_blocked_url, _EVAL_NAVIGATED_WHY)
-
- return _dumps(_eval_ok_response(parsed), default=str)
- except Exception as e:
- if any(code in str(e) for code in ("404", "405", "501")): # server without eval support
- return json.dumps(_err("JavaScript evaluation is not supported by this Camofox server. "
- "Use browser_snapshot or browser_vision to inspect page state."))
- return tool_error(str(e), success=False)
-
-
-def _maybe_start_recording(task_id: str):
- """Start recording if browser.record_sessions is enabled in config."""
- with _cleanup_lock:
- if task_id in _recording_sessions:
- return
- try:
- from hermes_cli.config import read_raw_config
- hermes_home = get_hermes_home()
- if not cfg_get(read_raw_config(), "browser", "record_sessions", default=False):
- return
- recordings_dir = hermes_home / "browser_recordings"
- recordings_dir.mkdir(parents=True, exist_ok=True)
- _lifecycle._cleanup_old_recordings(max_age_hours=72)
- recording_path = recordings_dir / f"session_{time.strftime('%Y%m%d_%H%M%S')}_{task_id[:16]}.webm"
- result = _session._run_browser_command(task_id, "record", ["start", str(recording_path)])
- if result.get("success"):
- with _cleanup_lock:
- _recording_sessions.add(task_id)
- logger.info("Auto-recording browser session %s to %s", task_id, recording_path)
- else:
- logger.debug("Could not start auto-recording: %s", result.get("error"))
- except Exception as e:
- logger.debug("Auto-recording setup failed: %s", e)
-
-
-def _maybe_stop_recording(task_id: str):
- """Stop recording if one is active for this session."""
- with _cleanup_lock:
- if task_id not in _recording_sessions:
- return
- try:
- result = _session._run_browser_command(task_id, "record", ["stop"])
- if result.get("success"):
- logger.info("Saved browser recording for session %s: %s", task_id, result.get("data", {}).get("path", ""))
- except Exception as e:
- logger.debug("Could not stop recording for %s: %s", task_id, e)
- finally:
- with _cleanup_lock:
- _recording_sessions.discard(task_id)
-
-
-_GET_IMAGES_JS = "JSON.stringify([...document.images].map(img => ({src: img.src, alt: img.alt || '', width: img.naturalWidth, height: img.naturalHeight})).filter(img => img.src && !img.src.startsWith('data:')))"
-
-
-def browser_get_images(task_id: Optional[str] = None) -> str:
- """List the page's images (src, alt, natural size), excluding data: URIs."""
- if _is_camofox_mode():
- return _camofox("camofox_get_images", task_id)
-
- effective_task_id = _last_session_key(task_id or "default")
- result = _session._run_browser_command(effective_task_id, "eval", [_GET_IMAGES_JS])
- if not result.get("success"):
- return _failed_response(result, "Failed to get images")
-
- blocked = _blocked_private_page_content(effective_task_id)
- if blocked is not None:
- return blocked
-
- raw_result = result.get("data", {}).get("result", "[]")
- try:
- images = json.loads(raw_result) if isinstance(raw_result, str) else raw_result
- return _json_with_fallback({"success": True, "images": _snapshot._redact_browser_output(images), "count": len(images)}, result)
- except json.JSONDecodeError:
- return _json_with_fallback({"success": True, "images": [], "count": 0, "warning": "Could not parse image data"}, result)
-
-
-_LP_VISION_FALLBACK_REASON = "Lightpanda has no graphical renderer for screenshots; used Chrome for vision capture."
-
-
-from tools import browser_tool_vision as _vision
-
-
-def _capture_vision_screenshot(effective_task_id: str, annotate: bool, screenshot_path: Path, lp_prerouted: bool):
- """Take (or adopt the pre-routed) screenshot; returns ``(result, path, error_json_or_None)``."""
- if lp_prerouted and screenshot_path.exists():
- result = _lp._annotate_lightpanda_fallback(
- {"success": True, "data": {"path": str(screenshot_path)}}, _LP_VISION_FALLBACK_REASON)
- else:
- # In the sandbox the CLI writes to ITS filesystem; the file is fetched back below.
- remote_path = _session.sandbox_screenshot_path(screenshot_path)
- screenshot_args = (["--annotate"] if annotate else []) + ["--full", remote_path or str(screenshot_path)]
- # A failed Lightpanda pre-route forces Chrome so _run_browser_command
- # doesn't trigger a redundant LP fallback.
- result = _session._run_browser_command(effective_task_id, "screenshot", screenshot_args,
- _engine_override="auto" if lp_prerouted else None)
- if remote_path and result.get("success"):
- try:
- _session.fetch_sandbox_file(str((result.get("data") or {}).get("path") or remote_path), screenshot_path)
- result.setdefault("data", {})["path"] = str(screenshot_path)
- except Exception as exc:
- logger.warning("could not fetch the sandbox screenshot %s: %s", remote_path, exc)
- if not result.get("success"):
- return result, screenshot_path, _json_with_fallback(_err(
- f"Failed to take screenshot ({_vision._vision_mode_label()} mode): {result.get('error', 'Unknown error')}"
- ), result)
- if result.get("data", {}).get("path"):
- screenshot_path = Path(result["data"]["path"])
- if not screenshot_path.exists():
- return result, screenshot_path, _dumps(_err(
- f"Screenshot file was not created at {screenshot_path} ({_vision._vision_mode_label()} mode). "
- f"This may indicate a socket path issue (macOS /var/folders/), "
- f"a missing Chromium install ('agent-browser install'), "
- f"or a stale daemon process."
- ))
- return result, screenshot_path, None
-
-
-def browser_vision(question: str, annotate: bool = False, task_id: Optional[str] = None) -> str | dict[str, Any]:
- """Screenshot the current page for visual inspection. Native-vision models get the image
- attached to the conversation; otherwise the auxiliary vision model returns a text
- analysis. The file is kept and its path returned (MEDIA:<path>)."""
- if _is_camofox_mode():
- return _camofox("camofox_vision", question, annotate, task_id)
-
- import uuid as uuid_mod
- from hermes_constants import get_hermes_dir
- screenshots_dir = get_hermes_dir("cache/screenshots", "browser_screenshots")
- screenshot_path = screenshots_dir / f"browser_screenshot_{uuid_mod.uuid4().hex}.png"
- effective_task_id = _last_session_key(task_id or "default")
- blocked = _blocked_private_page_content(effective_task_id)
- if blocked is not None:
- return blocked
-
- _lp_prerouted, _lp_fallback_warning, screenshot_path = _vision._lightpanda_vision_preroute(
- effective_task_id, annotate, screenshot_path)
- result: dict[str, Any] = {}
- try:
- screenshots_dir.mkdir(parents=True, exist_ok=True)
- _lifecycle._cleanup_old_screenshots(screenshots_dir, max_age_hours=24)
- result, screenshot_path, error = _capture_vision_screenshot(
- effective_task_id, annotate, screenshot_path, _lp_prerouted)
- if error is not None:
- return error
- # Native image routing: attach the screenshot directly instead of describing it
- # through an aux vision LLM (no information loss).
- from tools.vision_tools import _should_use_native_vision_fast_path
- if _should_use_native_vision_fast_path():
- return _vision._native_vision_result(screenshot_path, question, annotate, result, _lp_fallback_warning)
-
- analysis = _vision._analyze_screenshot_with_aux_llm(screenshot_path, question)
- response_data = {"success": True, "analysis": analysis or "Vision analysis returned no content.",
- "screenshot_path": str(screenshot_path)}
- _lp._copy_fallback_warning(response_data, result)
- if annotate and result.get("data", {}).get("annotations"):
- response_data["annotations"] = result["data"]["annotations"]
- return _dumps(response_data)
- except Exception as e:
- # Keep a captured screenshot — the failure is in the analysis, not the capture,
- # and deleting it loses evidence. The 24-hour cleanup bounds disk growth.
- logger.warning("browser_vision failed: %s", e, exc_info=True)
- error_info = _err(f"Error during vision analysis: {e!s}")
- if screenshot_path.exists():
- error_info["screenshot_path"] = str(screenshot_path)
- error_info["note"] = "Screenshot was captured but vision analysis failed. You can still share it via MEDIA:<path>."
- _lp._copy_fallback_warning(error_info, result)
- return _dumps(error_info)
-
-
-# ---------------------------------------------------------------------------
-# Registry
-# ---------------------------------------------------------------------------
-from tools.registry import registry, tool_error
-from tools.browser_extension_router import extension_controller_available, routed_browser_handler
-
-_BROWSER_SCHEMA_MAP = {s["name"]: s for s in BROWSER_TOOL_SCHEMAS}
-
-
-def check_browser_routed_requirements(action: str = "browser_snapshot") -> bool:
- """Availability gate for tools that can use either browser backend."""
- return _install.check_browser_requirements() or extension_controller_available(action)
-
-
-def _fallback_call(fn_name: str, arg_defaults: dict[str, Any], extra_kw: tuple = ()):
- """Adapter from the registry's ``(args, kw)`` to ``<fn_name>(**schema_args, task_id=...)``;
- the function is looked up in module globals at call time so monkeypatching works."""
- def call(args, kw):
- params = {a: args.get(a, d) for a, d in arg_defaults.items()}
- params["task_id"] = kw.get("task_id")
- for k in extra_kw:
- params[k] = kw.get(k)
- return globals()[fn_name](**params)
- return call
-
-
-# (tool name, emoji, availability gate, schema-arg defaults[, extra kw names]); the tool
-# function is the module global of the same name. Routed-through-extension tools (gate None)
-# use the per-action gate; get_images/console/vision keep the plain requirement checks.
-_BROWSER_TOOL_TABLE = (
- ("browser_navigate", "🌐", None, {"url": ""}),
- ("browser_snapshot", "📸", None, {"full": False}, ("user_task",)),
- ("browser_click", "👆", None, {"ref": ""}),
- ("browser_type", "⌨️", None, {"ref": "", "text": ""}),
- ("browser_scroll", "📜", None, {"direction": "down"}),
- ("browser_back", "◀️", None, {}),
- ("browser_press", "⌨️", None, {"key": ""}),
- ("browser_get_images", "🖼️", _install.check_browser_requirements, {}),
- ("browser_vision", "👁️", _install.check_browser_vision_requirements, {"question": "", "annotate": False}),
- ("browser_console", "🖥️", _install.check_browser_requirements, {"clear": False, "expression": None}),
-)
-
-
-def _routed_check_fn(name: str):
- """Per-action availability gate (a named function, as the registry expects)."""
- def check() -> bool:
- return check_browser_routed_requirements(name)
- check.__name__ = check.__qualname__ = f"check_{name}_requirements"
- return check
-
-
-def _routed_handler(name: str, fallback):
- def handler(args, **kw):
- return record_browser_call(lambda legacy: routed_browser_handler(
- name, args, fallback=lambda: legacy(lambda: fallback(args, kw)),
- task_id=kw.get("task_id"), session_id=kw.get("session_id"),
- ), _cloud.browser_backend_name)
- return handler
-
-
-for _name, _emoji, _check_fn, _defaults, *_extra in _BROWSER_TOOL_TABLE:
- if _check_fn is None: # also binds the legacy check_browser_<x>_requirements globals (tests + callers)
- _check_fn = globals()[f"check_{_name}_requirements"] = _routed_check_fn(_name)
- registry.register(name=_name, toolset="browser", schema=_BROWSER_SCHEMA_MAP[_name],
- handler=_routed_handler(_name, _fallback_call(_name, _defaults, *_extra)),
- check_fn=_check_fn, emoji=_emoji)
diff --git a/tools/browser_tool_cdp.py b/tools/browser_tool_cdp.py
deleted file mode 100644
index ff5126c37e8..00000000000
--- a/tools/browser_tool_cdp.py
+++ /dev/null
@@ -1,193 +0,0 @@
-"""User-supplied CDP endpoint resolution (browser.cdp_url / real-profile), dialog-policy config and the per-task CDP supervisor lifecycle.
-
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle."""
-
-import contextlib
-import os
-import threading
-from typing import Optional, Tuple
-
-from agent.proxy_bypass import loopback_request_kwargs
-from tools.browser_tool_origin import origin_module as _origin
-
-
-def _resolve_cdp_override(cdp_url: str) -> str:
- """Normalize a user-supplied CDP endpoint into a concrete websocket URL.
-
- Full ``ws://.../devtools/browser/...`` endpoints pass through; HTTP discovery roots and bare ``ws://host:port``
- resolve via ``/json/version`` → ``webSocketDebuggerUrl`` (falls back to the raw value with a warning).
- """
- _bt = _origin()
- raw = (cdp_url or "").strip()
- if not raw:
- return ""
- lowered = raw.lower()
- if "/devtools/browser/" in lowered:
- return raw
-
- discovery_url = raw
- if lowered.startswith(("ws://", "wss://")):
- if not (raw.count(":") == 2 and raw.rstrip("/").rsplit(":", 1)[-1].isdigit() and "/" not in raw.split(":", 2)[-1]):
- return raw
- discovery_url = ("http://" if lowered.startswith("ws://") else "https://") + raw.split("://", 1)[1]
- version_url = discovery_url if discovery_url.lower().endswith("/json/version") else discovery_url.rstrip("/") + "/json/version"
-
- san = _bt._sanitize_url_for_logs
- try:
- import requests # lazy — shared module object, test patches still apply
- response = requests.get(version_url, timeout=10, **loopback_request_kwargs(version_url))
- response.raise_for_status()
- payload = response.json()
- except Exception as exc:
- _bt.logger.warning("Failed to resolve CDP endpoint %s via %s: %s", san(raw), san(version_url), san(exc))
- return raw
- ws_url = str(payload.get("webSocketDebuggerUrl") or "").strip()
- if ws_url:
- _bt.logger.info("Resolved CDP endpoint %s -> %s", san(raw), san(ws_url))
- return ws_url
- _bt.logger.warning("CDP discovery at %s did not return webSocketDebuggerUrl; using raw endpoint", san(version_url))
- return raw
-
-
-# Live ``/browser connect`` endpoints, one per profile home (``hermes_home_key()``): a multiplexed
-# gateway serves every profile from this process, so a process-wide value would reach them all.
-_live_overrides: dict[str, str] = {}
-_live_overrides_lock = threading.Lock()
-
-
-def live_cdp_override() -> str:
- """The current profile's live ``/browser connect`` endpoint, or "".
-
- On a multiplexed gateway a context with no profile bound (a bare ``threading.Thread`` or stdlib
- executor that did not copy the caller's context) answers "" rather than the launch profile's
- endpoint, the way ``get_secret`` fails closed. Single-profile processes are unchanged."""
- from agent.secret_scope import is_multiplex_active
- from hermes_constants import get_hermes_home_override, hermes_home_key
- if get_hermes_home_override() is None and is_multiplex_active():
- return ""
- with _live_overrides_lock:
- return _live_overrides.get(hermes_home_key(), "")
-
-
-def set_live_cdp_override(url: Optional[str]) -> None:
- """Set (or with a falsy ``url`` clear) the current profile's live endpoint and bump its generation."""
- from hermes_constants import hermes_home_key
- key = hermes_home_key()
- with _live_overrides_lock:
- if url:
- _live_overrides[key] = url
- else:
- _live_overrides.pop(key, None)
- _live_generations[key] = _live_generations.get(key, 0) + 1
-
-
-# Per-profile count of live-endpoint publishes. A browser session records the value it saw before
-# resolving its endpoint; ``_get_session_info`` closes one whose profile published in between (it may
-# have resolved the old URL after ``/browser connect``'s second reap had already run).
-_live_generations: dict[str, int] = {}
-
-
-def live_cdp_generation(home_key: Optional[str] = None) -> int:
- """The current (or ``home_key``'s) profile's live-endpoint generation."""
- from hermes_constants import hermes_home_key
- with _live_overrides_lock:
- return _live_generations.get(home_key or hermes_home_key(), 0)
-
-
-def env_cdp_url() -> str:
- """``BROWSER_CDP_URL`` from this profile's secret scope. A routed profile (multiplex, or a scope
- bound for another home) reads only its own ``.env``: ``os.environ`` holds the launch profile's
- value. Single-profile reads fall through to ``os.environ`` as before (``get_secret``)."""
- from agent.secret_scope import current_secret_scope, get_secret, serves_routed_profile
- if serves_routed_profile():
- value = (current_secret_scope() or {}).get("BROWSER_CDP_URL")
- else:
- value = get_secret("BROWSER_CDP_URL")
- return (value or "").strip()
-
-
-def _get_cdp_override_raw() -> str:
- """Return the *configured* CDP override without any network I/O.
-
- Precedence: this profile's live ``/browser connect``, then its ``BROWSER_CDP_URL`` (:func:`env_cdp_url`),
- then ``browser.cdp_url``. Is-it-configured
- gates (check_fns, ``_is_local_mode`` / ``_is_local_backend``, ``hermes doctor``) MUST use this, not
- :func:`_get_cdp_override`: its 10s HTTP discovery against a stale ``cdp_url`` would stall every startup's
- schema build with no error.
- """
- env_override = live_cdp_override() or env_cdp_url()
- return env_override or _origin()._browser_cfg("cdp_url", "", lambda v: str(v or "").strip(), "browser.cdp_url from config")
-
-
-def _get_cdp_override() -> str:
- """Resolved CDP URL override, or "" (skips cloud AND local launch).
-
- May perform HTTP ``/json/version`` discovery — only call on paths about to *connect*; pure gates must use
- :func:`_get_cdp_override_raw`.
- """
- _bt = _origin()
- return _resolve_cdp_override(raw) if (raw := _get_cdp_override_raw()) else ""
-
-
-def _get_dialog_policy_config() -> tuple[str, float]:
- """Read ``browser.dialog_policy`` + ``browser.dialog_timeout_s``; supervisor defaults when absent/invalid."""
- _bt = _origin()
- # Deferred so browser_tool imports in minimal environments.
- from tools.browser_supervisor_dialogs import DEFAULT_DIALOG_POLICY, DEFAULT_DIALOG_TIMEOUT_S, _VALID_POLICIES
- policy, timeout_s = DEFAULT_DIALOG_POLICY, DEFAULT_DIALOG_TIMEOUT_S
- try:
- from hermes_cli.config import read_raw_config
- cfg = read_raw_config()
- browser_cfg = cfg.get("browser", {}) if isinstance(cfg, dict) else {}
- if not isinstance(browser_cfg, dict):
- return policy, timeout_s
- candidate = str(browser_cfg.get("dialog_policy") or DEFAULT_DIALOG_POLICY)
- if candidate in _VALID_POLICIES:
- policy = candidate
- else:
- _bt.logger.debug("Invalid browser.dialog_policy=%r; using default", candidate)
- timeout_raw = browser_cfg.get("dialog_timeout_s")
- try:
- timeout_s = float(timeout_raw) if timeout_raw is not None else DEFAULT_DIALOG_TIMEOUT_S
- if timeout_s <= 0:
- timeout_s = DEFAULT_DIALOG_TIMEOUT_S
- except (TypeError, ValueError):
- timeout_s = DEFAULT_DIALOG_TIMEOUT_S
- return policy, timeout_s
- except Exception:
- return DEFAULT_DIALOG_POLICY, DEFAULT_DIALOG_TIMEOUT_S
-
-
-def _ensure_cdp_supervisor(task_id: str) -> None:
- """Start a CDP supervisor for ``task_id`` if an endpoint is reachable.
-
- Idempotent (``get_or_start`` skips an existing ``(task_id, cdp_url)`` and restarts on URL change), so safe on
- every navigate / ``/browser connect``. URL precedence: the CDP override, then the session's own ``cdp_url``
- (cloud providers, e.g. Browserbase). Swallows all errors — a failed attach must not break the session;
- snapshots just lack ``pending_dialogs`` / ``frame_tree``.
- """
- _bt = _origin()
- cdp_url = _get_cdp_override()
- if not cdp_url:
- with _bt._cleanup_lock:
- session_info = _bt._active_sessions.get(task_id, {})
- maybe = str(session_info.get("cdp_url") or "")
- if maybe:
- cdp_url = _resolve_cdp_override(maybe)
- if not cdp_url:
- return
- try:
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- policy, timeout_s = _get_dialog_policy_config()
- SUPERVISOR_REGISTRY.get_or_start(task_id=task_id, cdp_url=cdp_url, dialog_policy=policy, dialog_timeout_s=timeout_s)
- except Exception as exc:
- _bt.logger.debug("CDP supervisor attach for task=%s failed (non-fatal): %s", task_id, exc)
-
-
-def _stop_cdp_supervisor(task_id: str) -> None:
- """Stop the CDP supervisor for ``task_id`` if one exists. No-op otherwise."""
- try:
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- SUPERVISOR_REGISTRY.stop(task_id)
- except Exception as exc:
- _origin().logger.debug("CDP supervisor stop for task=%s failed (non-fatal): %s", task_id, exc)
diff --git a/tools/browser_tool_cloud.py b/tools/browser_tool_cloud.py
deleted file mode 100644
index fa1f0bb10e1..00000000000
--- a/tools/browser_tool_cloud.py
+++ /dev/null
@@ -1,270 +0,0 @@
-"""Cloud browser provider resolution (explicit browser.cloud_provider, auto-detect, per-profile cache), backend/engine selection and headed-mode flags.
-
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle."""
-
-from __future__ import annotations
-
-import os
-from typing import Callable, Optional
-
-from agent.browser_provider import BrowserProvider as CloudBrowserProvider
-from agent.browser_registry import get_provider as _registry_get_browser_provider
-from hermes_constants import get_hermes_home_override, hermes_home_key
-from tools.tool_backend_helpers import normalize_browser_cloud_provider
-from utils import is_truthy_value
-from tools.browser_tool_origin import origin_module as _origin
-from tools import browser_tool_cdp as _cdp
-
-
-def _memo(_bt, resolved_attr: str, cache_attr: str, compute: Callable[[], object]):
- """Process-lifetime cache on ``_bt``: the resolved flag is set BEFORE computing, then the final value is stored.
-
- Under a routed profile (HERMES_HOME override, multiplexed gateway) the slot is NOT consulted: every
- ``_memo`` here caches a ``browser.*`` config read, and one process-wide slot would hand the launch
- profile's engine/headed/private-URL policy to every other profile (same rule as ``_allow_private_urls``).
- """
- if get_hermes_home_override() is not None:
- return compute()
- if not getattr(_bt, resolved_attr):
- setattr(_bt, resolved_attr, True)
- setattr(_bt, cache_attr, compute())
- return getattr(_bt, cache_attr)
-
-
-def _ensure_browser_plugins_loaded() -> None:
- """Idempotently trigger plugin discovery (standalone scripts/tests may never import ``model_tools``)."""
- try:
- from hermes_cli.plugins import _ensure_plugins_discovered
- _ensure_plugins_discovered()
- except Exception as exc:
- _origin().logger.debug("Browser plugin discovery failed (non-fatal): %s", exc)
-
-
-def _get_cloud_provider() -> Optional[CloudBrowserProvider]:
- """Return the provider cached for the active Hermes profile."""
- _bt = _origin()
- scope = hermes_home_key()
- with _bt._cloud_provider_cache_lock:
- # A cleared boolean (tests / legacy reset) is a full reset even if a scoped resolution is still mirrored here.
- if not _bt._cloud_provider_resolved:
- _bt._cached_cloud_provider_scope = None
- _bt._cached_cloud_providers.clear()
- while True:
- before_generation = _bt._browser_registry_generation(scope=scope)
- cache_key = (scope, before_generation)
- if cache_key in _bt._cached_cloud_providers:
- _bt._cached_cloud_provider = _bt._cached_cloud_providers[cache_key]
- _bt._cloud_provider_resolved = True
- _bt._cached_cloud_provider_scope = scope
- return _bt._cached_cloud_provider
- _bt._cached_cloud_provider = None
- _bt._cloud_provider_resolved = False
- resolved = _resolve_cloud_provider_uncached()
- after_generation = _bt._browser_registry_generation(scope=scope)
- if before_generation != after_generation: # force reload mid-resolution: discard, resolve again
- continue
- if _bt._cloud_provider_resolved:
- _bt._cached_cloud_provider_scope = scope
- for stale_key in [key for key in _bt._cached_cloud_providers if key[0] == scope]:
- _bt._cached_cloud_providers.pop(stale_key, None)
- _bt._cached_cloud_providers[cache_key] = resolved
- return resolved
-
-
-def _instantiate_explicit_cloud_provider(provider_key: str) -> Optional[CloudBrowserProvider]:
- """Build the provider named by ``browser.cloud_provider``.
-
- Strict: an unregistered name raises ``ValueError`` (never a silent reroute to auto-detect); any
- other instantiation error is logged and yields None so the next call retries.
- """
- _bt = _origin()
- try:
- _ensure_browser_plugins_loaded()
- resolved = _registry_get_browser_provider(provider_key)
- if resolved is None:
- from tools.tool_backend_helpers import selection_error
- raise ValueError(selection_error(
- "browser", f"'{provider_key}'",
- "no registered browser plugin has that name (install the corresponding plugin or fix the config key spelling)",
- ))
- return resolved
- except ValueError:
- raise
- except Exception:
- _bt.logger.warning("Failed to instantiate explicit cloud_provider %r; will retry on next call", provider_key, exc_info=True)
- return None
-
-
-def _autodetect_cloud_provider() -> Optional[CloudBrowserProvider]:
- """Auto-detect: Browser Use, then Browserbase; never raises.
-
- Third-party plugins are only reachable via explicit ``browser.cloud_provider: <name>``.
- """
- _bt = _origin()
- # Late import: this module is on run_agent's import path, and a core tool must not
- # execute bundled plugin code before a browser session is actually being resolved.
- from plugins.browser.browser_use.provider import BrowserUseBrowserProvider
- from plugins.browser.browserbase.provider import BrowserbaseBrowserProvider
- try:
- for cls in (BrowserUseBrowserProvider, BrowserbaseBrowserProvider):
- fallback_provider = cls()
- if fallback_provider.is_available():
- return fallback_provider
- except Exception: # pragma: no cover - defensive: never poison cache
- _bt.logger.debug("Cloud provider auto-detect failed", exc_info=True)
- return None
-
-
-def _resolve_cloud_provider_uncached() -> Optional[CloudBrowserProvider]:
- """Return the configured cloud browser provider, or None for local mode.
-
- Pins the cache only when definitive (explicit ``local``/``camofox`` or a resolved provider); a transient None
- (unreadable config, missing credentials) is NOT cached so it can self-heal. Auto-detect runs only when no
- selection was ever written.
- """
- _bt = _origin()
- resolved: Optional[CloudBrowserProvider] = None
- provider_key = None
- try:
- from hermes_cli.config import read_raw_config
- browser_cfg = read_raw_config().get("browser", {})
- if isinstance(browser_cfg, dict) and "cloud_provider" in browser_cfg:
- provider_key = normalize_browser_cloud_provider(browser_cfg.get("cloud_provider"))
- if provider_key in ("local", "camofox"):
- # Camofox runs through the built-in browser tools, not a cloud provider.
- _bt._cached_cloud_provider = None
- _bt._cloud_provider_resolved = True
- return None
- if provider_key == "nous":
- # Managed "Nous Subscription" is serviced by the Browser Use provider.
- provider_key = "browser-use"
- if provider_key:
- resolved = _instantiate_explicit_cloud_provider(provider_key)
- if resolved is None:
- return None
- except ValueError:
- raise
- except Exception as e:
- # Config may be temporarily unreadable; still try auto-detect (env/managed creds). Don't pin cache.
- _bt.logger.debug("Could not read cloud_provider from config: %s", e)
-
- if resolved is None and provider_key is None:
- resolved = _autodetect_cloud_provider()
- if resolved is None:
- return None
- _bt._cached_cloud_provider = resolved
- _bt._cloud_provider_resolved = True
- return _bt._cached_cloud_provider
-
-
-def _is_local_mode() -> bool:
- """Return True when the browser tool will use a local browser backend."""
- _bt = _origin()
- return not _cdp._get_cdp_override_raw() and _get_cloud_provider() is None
-
-
-def _is_local_backend() -> bool:
- """True when the browser runs locally AND the terminal is also local.
-
- SSRF protection only matters when the browser can reach networks the terminal cannot (cloud backends,
- containerized terminals). A CDP override is never trusted as local (that Chrome may live off-host) and MUST
- be checked before the Camofox short-circuit; ``_is_local_mode`` treats overrides the same way — keep the two
- in agreement.
- """
- _bt = _origin()
- if _cdp._get_cdp_override_raw():
- return False
- if _bt._is_camofox_mode():
- return True
- if _get_cloud_provider() is not None:
- return False
- # Scope-aware: under gateway multiplexing the routed profile's terminal backend lives in the per-turn scope.
- # When terminal runs in a container, browser on host can access internal networks the terminal can't →
- # treat as non-local. See #68559.
- from tools.terminal_scope import terminal_env
- return terminal_env("TERMINAL_ENV", "local").strip().lower() in ("local", "")
-
-
-def browser_backend_name() -> str:
- """Shared-metrics label for the backend legacy browser calls use in the active profile, in session-creation
- precedence (CDP override > Camofox > cloud provider > local engine). Config reads only, no network I/O."""
- _bt = _origin()
- if _cdp._get_cdp_override_raw():
- return "cdp"
- if _bt._is_camofox_mode():
- return "camofox"
- provider = _get_cloud_provider()
- if provider is not None:
- return str(getattr(provider, "name", "") or "other")
- return "lightpanda" if _get_browser_engine() == "lightpanda" else "local"
-
-
-def _get_browser_engine() -> str:
- """Return the browser engine: ``auto`` (no ``--engine`` flag), ``lightpanda`` or ``chrome``.
-
- ``browser.engine`` first, then ``AGENT_BROWSER_ENGINE``, then ``auto``; cached. Lightpanda is faster on
- navigation but has no graphical renderer (no screenshots).
- """
- _bt = _origin()
- def compute() -> str:
- engine = _bt._browser_cfg("engine", "auto", lambda v: str(v).strip().lower() if v and str(v).strip() else "auto", "browser.engine from config")
- if engine == "auto":
- engine = os.environ.get("AGENT_BROWSER_ENGINE", "").strip().lower() or engine
- # agent-browser only accepts "chrome" and "lightpanda".
- _VALID_ENGINES = {"auto", "lightpanda", "chrome"}
- if engine not in _VALID_ENGINES:
- _bt.logger.warning("Unknown browser engine %r (valid: %s), falling back to 'auto'", engine, ", ".join(sorted(_VALID_ENGINES)))
- engine = "auto"
- return engine
- return _memo(_bt, "_browser_engine_resolved", "_cached_browser_engine", compute)
-
-
-def _is_headed_mode() -> bool:
- """True when the browser should launch headed: ``browser.headed``, else ``AGENT_BROWSER_HEADED``; cached."""
- _bt = _origin()
- def compute() -> bool:
- headed = _bt._browser_cfg("headed", False, lambda v: False if v is None else str(v).strip().lower() in ("true", "1", "yes"), "browser.headed from config")
- return headed or os.environ.get("AGENT_BROWSER_HEADED", "").strip().lower() in ("true", "1", "yes")
- return _memo(_bt, "_headed_mode_resolved", "_cached_headed_mode", compute)
-
-
-def _should_inject_engine(engine: str) -> bool:
- """True when ``--engine`` should be added: explicit (non-``auto``) engine on a non-cloud, non-camofox local session."""
- _bt = _origin()
- return engine != "auto" and not _bt._is_camofox_mode() and _is_local_mode()
-
-
-def _auto_local_for_private_urls() -> bool:
- """``browser.auto_local_for_private_urls`` (default True), cached: route private/LAN URLs to a local sidecar even with a cloud provider."""
- _bt = _origin()
- return _memo(
- _bt, "_auto_local_for_private_urls_resolved", "_cached_auto_local_for_private_urls",
- lambda: _bt._browser_cfg("auto_local_for_private_urls", _bt._cached_auto_local_for_private_urls, bool, "auto_local_for_private_urls from config"),
- )
-
-
-def _use_real_profile() -> bool:
- """Whether the user consented to real-profile local browsing.
-
- Read on EVERY call: it is a consent switch (flipping it off must not need a restart) and each multiplexed
- profile must decide for itself. One YAML load per local session creation, so no hot-path cost.
- """
- return _origin()._browser_cfg("use_real_profile", False, bool, "use_real_profile from config")
-
-
-def _allow_private_urls() -> bool:
- """Whether the browser may navigate to private/internal addresses (default False: SSRF protection on).
-
- Single-profile calls cache for the process lifetime; multiplexed profile turns (ContextVar-scoped config)
- resolve on every call so one profile's opt-out is never reused by another.
- """
- _bt = _origin()
- if get_hermes_home_override() is not None:
- return _resolve_allow_private_urls()
- return _memo(_bt, "_allow_private_urls_resolved", "_cached_allow_private_urls", _resolve_allow_private_urls)
-
-
-def _resolve_allow_private_urls() -> bool:
- """Read the browser private-URL toggle from the active config scope."""
- _bt = _origin()
- return _bt._browser_cfg("allow_private_urls", False, lambda v: is_truthy_value(v, default=False), "allow_private_urls from config")
diff --git a/tools/browser_tool_eval_policy.py b/tools/browser_tool_eval_policy.py
deleted file mode 100644
index 28221d4cdd0..00000000000
--- a/tools/browser_tool_eval_policy.py
+++ /dev/null
@@ -1,167 +0,0 @@
-"""browser_console(expression=...) policy: SSRF guard gating, private-URL probes,
-and the opt-in sensitive-primitive denylist.
-
-Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import re
-from typing import Optional
-from utils import is_truthy_value
-from tools.browser_tool_origin import origin_module as _origin
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_session as _session
-
-
-def _eval_ssrf_guard_active(effective_task_id: str) -> bool:
- """Return True when eval-driven private-network access must be guarded.
-
- Same gating as ``browser_navigate`` / ``browser_snapshot`` / ``browser_vision``: the SSRF guard
- only matters for non-local backends (cloud browser, or a containerized terminal whose
- browser-on-host reaches networks the terminal can't); skipped for local sidecars / ``allow_private_urls``.
- """
- _bt = _origin()
- return not _cloud._is_local_backend() and not _bt._is_local_sidecar_key(effective_task_id) and not _cloud._allow_private_urls()
-
-
-def _url_blocked(_bt, url: str) -> bool:
- """True when ``url`` hits the always-blocked cloud-metadata floor or fails the SSRF guard."""
- return _bt._is_always_blocked_url(url) or not _bt._is_safe_url(url)
-
-
-# URL-shaped literals embedded in a JS expression (http/https only). fetch/XHR/navigate
-# to a private host never updates ``location.href``, so the post-eval page-URL recheck
-# can't see it; pre-screen the literals instead.
-_JS_URL_LITERAL_RE = re.compile(r"""https?://[^\s'"`)\]<>]+""", re.IGNORECASE)
-
-
-def _expression_targets_private_url(expression: str) -> Optional[str]:
- """Return the first private/always-blocked ``http(s)://`` literal in a JS expression (best-effort), else None."""
- _bt = _origin()
- literals = _JS_URL_LITERAL_RE.findall(expression) if isinstance(expression, str) else []
- return next((c for c in (m.rstrip(".,;") for m in literals) if _url_blocked(_bt, c)), None)
-
-
-def _current_page_private_url(effective_task_id: str) -> Optional[str]:
- """Return the current page URL when it targets a private/internal address (e.g. after a prior
- ``location.href = '...'`` eval). Fail-open on probe failure, matching the snapshot/vision guards."""
- _bt = _origin()
- try:
- url_result = _session._run_browser_command(effective_task_id, "eval", ["window.location.href"], timeout=5, _engine_override="auto")
- if url_result.get("success"):
- current_url = url_result.get("data", {}).get("result", "").strip().strip('"').strip("'")
- if current_url and _url_blocked(_bt, current_url):
- return current_url
- except Exception as exc:
- _bt.logger.debug("_current_page_private_url: probe failed (%s)", exc)
- return None
-
-
-_RISKY_BROWSER_EVAL_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
- (re.compile(r"\bdocument\s*\.\s*cookie\b", re.IGNORECASE), "document.cookie"),
- (re.compile(r"\b(?:localStorage|sessionStorage)\b", re.IGNORECASE), "web storage"),
- (re.compile(r"\bindexedDB\b", re.IGNORECASE), "IndexedDB"),
- (re.compile(r"\bcaches\s*\.\s*(?:open|match|keys)\b", re.IGNORECASE), "Cache Storage"),
- (re.compile(r"\bnavigator\s*\.\s*(?:clipboard|credentials|serviceWorker)\b", re.IGNORECASE), "navigator sensitive API"),
- (re.compile(r"\b(?:fetch|XMLHttpRequest|WebSocket|EventSource)\s*\(", re.IGNORECASE), "network request"),
- (re.compile(r"\bnavigator\s*\.\s*sendBeacon\s*\(", re.IGNORECASE), "network beacon"),
- (re.compile(r"\bdocument\s*\.\s*forms\b.*\bvalue\b", re.IGNORECASE | re.DOTALL), "form value extraction"),
- (re.compile(r"\bquerySelector(?:All)?\s*\([^)]*(?:input|textarea|password)[^)]*\).*\bvalue\b", re.IGNORECASE | re.DOTALL), "form value extraction"),
-)
-
-_JS_STRING_LITERAL_RE = re.compile(r"""'(?:\\.|[^'\\])*'|\"(?:\\.|[^\"\\])*\"|`(?:\\.|[^`\\])*`""", re.DOTALL)
-
-
-_SENSITIVE_BROWSER_EVAL_TOKENS: tuple[tuple[str, str], ...] = (
- ("cookie", "document.cookie"),
- ("localStorage", "web storage"), ("sessionStorage", "web storage"),
- ("indexedDB", "IndexedDB"), ("caches", "Cache Storage"),
- ("clipboard", "navigator sensitive API"), ("credentials", "navigator sensitive API"),
- ("serviceWorker", "navigator sensitive API"),
- ("fetch", "network request"), ("XMLHttpRequest", "network request"),
- ("WebSocket", "network request"), ("EventSource", "network request"),
- ("sendBeacon", "network beacon"),
-)
-
-
-def _browser_eval_flag(key: str) -> bool:
- """Read boolean ``browser.<key>`` (default False) through the origin's config reader."""
- _bt = _origin()
- return _bt._browser_cfg(key, False, lambda v: is_truthy_value(v, default=False), f"browser.{key} from config")
-
-
-def _allow_unsafe_browser_evaluate() -> bool:
- """Whether sensitive browser JS evaluation is explicitly allowed (overrides ``restrict_evaluate``)."""
- return _browser_eval_flag("allow_unsafe_evaluate")
-
-
-def _restrict_browser_evaluate() -> bool:
- """Whether the sensitive-primitive eval denylist is enabled (off by default).
-
- It blocks the *names* of common primitives (``fetch``, ``cookie``, ``querySelector(...input...)``),
- not actual exfiltration, so it also blocks much legitimate DOM extraction; egress is still gated
- by the SSRF/private-URL guards in ``_browser_eval`` regardless. Opt in via
- ``browser.restrict_evaluate: true`` (e.g. hostile pages with a logged-in profile).
- """
- return _browser_eval_flag("restrict_evaluate")
-
-
-def _decode_js_string_literal(literal: str) -> str:
- """Best-effort decode of a JS string literal (not a parser): normalizes escapes like ``"co\\x6fkie"``."""
- if len(literal) < 2:
- return literal
- try:
- return bytes(literal[1:-1], "utf-8").decode("unicode_escape")
- except Exception:
- return literal[1:-1]
-
-
-def _decoded_js_string_literals(expression: str) -> list[str]:
- return [_decode_js_string_literal(match.group(0)) for match in _JS_STRING_LITERAL_RE.finditer(expression)]
-
-
-def _sensitive_browser_eval_token_reason(expression: str) -> Optional[str]:
- """Risk reason for direct or quoted sensitive primitives: direct spellings alone miss
- ``document["cookie"]`` / ``globalThis["fetch"]``, so tokens are also matched inside the decoded,
- concatenated string literals (catches ``document["coo" + "kie"]``)."""
- literals = "".join(_decoded_js_string_literals(expression)).lower()
- return next((reason for token, reason in _SENSITIVE_BROWSER_EVAL_TOKENS
- if re.search(rf"\b{re.escape(token)}\b", expression, re.IGNORECASE) or token.lower() in literals), None)
-
-
-def _risky_browser_eval_reason(expression: str) -> Optional[str]:
- """Return a human-readable reason if a JS expression uses risky primitives."""
- if not expression:
- return None
- hit = next((reason for pattern, reason in _RISKY_BROWSER_EVAL_PATTERNS if pattern.search(expression)), None)
- return hit or _sensitive_browser_eval_token_reason(expression)
-
-
-def _enforce_browser_eval_policy(expression: str) -> Optional[str]:
- """Block sensitive browser JS evaluation when the opt-in denylist is on (opt-in because it gates on
- primitive *names*; private-address egress is enforced separately in ``_browser_eval``)."""
- if not _restrict_browser_evaluate() or _allow_unsafe_browser_evaluate():
- return None
- reason = _risky_browser_eval_reason(expression)
- if not reason:
- return None
- return ("Blocked: browser_console(expression=...) tried to use sensitive browser "
- f"JavaScript primitive ({reason}) while browser.restrict_evaluate is "
- "enabled. Use browser_snapshot/browser_get_images/browser_console "
- "without expression for normal inspection, or set "
- "browser.restrict_evaluate: false in config.yaml to allow programmatic evaluation.")
-
-
-def _camofox_current_page_private_url(tab_id: str, user_id: str) -> Optional[str]:
- """Camofox analogue of ``_current_page_private_url`` (evaluate endpoint instead of the CLI). Fail-open
- on probe failure, matching the snapshot/vision guards — do not make fail-closed without the sibling."""
- _bt = _origin()
- try:
- from tools.browser_camofox import _post
- data = _post(f"/tabs/{tab_id}/evaluate", body={"expression": "window.location.href", "userId": user_id})
- current_url = str(data.get("result") if isinstance(data, dict) else data or "")
- current_url = current_url.strip().strip('"').strip("'")
- if current_url and _url_blocked(_bt, current_url):
- return current_url
- except Exception as exc:
- _bt.logger.debug("_camofox_current_page_private_url: probe failed (%s)", exc)
- return None
diff --git a/tools/browser_tool_install.py b/tools/browser_tool_install.py
index b740b811327..36669e29fe1 100644
--- a/tools/browser_tool_install.py
+++ b/tools/browser_tool_install.py
@@ -1,185 +1,10 @@
-"""PM-owned agent-browser / Chromium discovery, acquisition and readiness.
+"""Frozen old-updater compatibility stub (tests/compat/old_updater_surface.json, ``bare`` list).
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle."""
-
-import functools
-import os
-import shutil
-
-from hermes_constants import agent_browser_runnable, is_termux as _is_termux_environment
-from tools.browser_tool_origin import origin_module as _origin
-from tools import browser_tool_cdp as _cdp
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_lightpanda_fallback as _lp
-
-
[email protected]_cache(maxsize=1)
-def _discover_homebrew_node_dirs() -> tuple[str, ...]:
- """Homebrew versioned Node bin dirs (node@20, ...) that ``brew`` may not link into /opt/homebrew/bin."""
- homebrew_opt = "/opt/homebrew/opt"
- try:
- entries = os.listdir(homebrew_opt) if os.path.isdir(homebrew_opt) else []
- except OSError:
- entries = []
- return tuple(
- bin_dir
- for entry in entries
- if entry.startswith("node") and entry != "node"
- if os.path.isdir(bin_dir := os.path.join(homebrew_opt, entry, "bin"))
- )
-
-
-def _browser_candidate_path_dirs() -> list[str]:
- """System PATH fallbacks for externally owned browser helpers."""
- _bt = _origin()
- return [*_discover_homebrew_node_dirs(), *_bt._SANE_PATH_DIRS]
-
-
-def _merge_browser_path(existing_path: str = "") -> str:
- """Prepend browser-specific PATH fallbacks without reordering existing entries."""
- path_parts = [p for p in (existing_path or "").split(os.pathsep) if p]
- prefix_parts: list[str] = []
- for part in _browser_candidate_path_dirs():
- if part and part not in path_parts and part not in prefix_parts and os.path.isdir(part):
- prefix_parts.append(part)
- return os.pathsep.join(prefix_parts + path_parts)
-
-
-def _browser_install_hint() -> str:
- if _is_termux_environment():
- return "npm install -g agent-browser && agent-browser install"
- return "hermes pm install agent-browser (system libraries: npx playwright install-deps chromium)"
-
-
-def _agent_browser_candidate_present(path: str | None) -> bool:
- if not path:
- return False
- return os.path.isfile(path) and (os.name == "nt" or os.access(path, os.X_OK))
-
-
-def _find_agent_browser(*, validate: bool = True) -> str:
- """Select PM's exact binary, then an external PATH/Homebrew installation.
-
- Termux owns its browser installation. Elsewhere PM may acquire a missing
- CLI at execution time, subject to its lazy-install policy. Readiness checks
- (``validate=False``) never execute or install anything. Selection is not
- cached: a new PM fact or profile must be visible immediately.
- """
- import pm
-
- termux = _is_termux_environment()
- if not termux:
- installed = pm.installed_package("agent-browser")
- if installed and installed.binary is not None:
- return str(installed.binary)
- usable = agent_browser_runnable if validate else _agent_browser_candidate_present
- for search_path in (None, _merge_browser_path("")):
- if search_path == "":
- continue
- candidate = shutil.which("agent-browser", path=search_path)
- if candidate and usable(candidate):
- return candidate
- hint = f"agent-browser CLI not found. Install it with: {_browser_install_hint()}"
- if validate and not termux:
- try:
- pm.ensure("agent-browser")
- except (pm.InstallError, OSError) as exc:
- raise FileNotFoundError(f"{hint}\n{exc}") from exc
- installed = pm.installed_package("agent-browser")
- if installed and installed.binary is not None:
- return str(installed.binary)
- raise FileNotFoundError(hint)
+The extraction-era home of ``warm_agent_browser_npx_cache``: a pre-PM ``hermes update`` still running
+mid-swap may import it from the NEW tree. agent-browser is gone; nothing else belongs here.
+"""
def warm_agent_browser_npx_cache(timeout: float = 60.0) -> bool:
- """Frozen old-updater surface names this module too (the extraction-era home); tools.browser_tool
- carries the permanent definition. No npx work is performed; relaunch instead."""
+ """Frozen old-updater surface: nothing is warmed (there is no agent-browser to warm); always False."""
return False
-
-
-def _chromium_installed() -> bool:
- """An explicit browser executable or PM's selected full Chromium exists."""
- from hermes_cli.browser_runtime import chromium_executable
-
- ab_path = chromium_executable()
- return bool(ab_path and (os.path.isfile(ab_path) or shutil.which(ab_path)))
-
-
-def _maybe_autoinstall_chromium() -> bool:
- """Install only PM's pinned full Chromium, never the upstream browser pair.
-
- Docker supplies the binary. Other installs require lazy-install consent.
- """
- _bt = _origin()
- if _bt._chromium_autoinstall_attempted:
- return _chromium_installed()
- _bt._chromium_autoinstall_attempted = True
- if _running_in_docker() or _is_termux_environment() or os.environ.get("AGENT_BROWSER_EXECUTABLE_PATH"):
- return False
- from pm import InstallError, ensure, lazy_installs_allowed
- if not lazy_installs_allowed():
- return False
- _bt.logger.info("browser: installing PM's pinned Chromium")
- try:
- ensure("chromium")
- except (InstallError, OSError) as exc:
- _bt.logger.warning("browser: Chromium auto-install failed: %s", exc)
- return False
- return _chromium_installed()
-
-
-def _running_in_docker() -> bool:
- """Best-effort detection of whether we're inside a Docker container."""
- if os.path.exists("/.dockerenv"):
- return True
- try:
- with open("/proc/1/cgroup", "rt", encoding="utf-8") as fp:
- return "docker" in fp.read()
- except OSError:
- return False
-
-
-def check_browser_requirements() -> bool:
- """Whether the browser tools should be advertised.
-
- Local mode needs the ``agent-browser`` CLI plus a Chromium build (except Lightpanda-only text workflows);
- cloud mode needs the CLI plus provider credentials (the provider hosts its own Chromium).
- """
- _bt = _origin()
- # Browser Use CLI backend: browser_exec replaces the whole browser_* surface (incl. browser_cdp/browser_dialog check_fns).
- if _bt._is_browser_use_cli_mode():
- return False
- # Camofox only needs the server URL, no agent-browser CLI.
- if _bt._is_camofox_mode():
- return True
- # CDP override needs no local binary. Raw (no-I/O) check: this runs during schema build, where a stale endpoint must not cost a blocking probe.
- if _cdp._get_cdp_override_raw():
- return True
- # Do not exec ``agent-browser --version`` here: Windows .cmd shims flash a console during Desktop startup. Execution paths still validate.
- try:
- _find_agent_browser(validate=False)
- except FileNotFoundError:
- return False
-
- # Cloud mode also requires provider credentials; no local Chromium needed.
- provider = _cloud._get_cloud_provider()
- if provider is not None:
- return provider.is_available()
- # Lightpanda provides text/navigation tools without Chromium; screenshots/vision still return install errors.
- if _lp._using_lightpanda_engine():
- return True
- # Local Chrome mode needs Chromium on disk or the CLI hangs until the command timeout.
- return _chromium_installed()
-
-
-def check_browser_vision_requirements() -> bool:
- """Advertise ``browser_vision`` only with BOTH a working browser AND a vision backend.
-
- Without the vision check, the tool stays in the model's tool list even when no vision provider is
- configured, then fails at call time with a cryptic provider-side error like ``unknown variant
- `image_url`, expected `text``` (issue #31179).
- """
- if not check_browser_requirements():
- return False
- from tools.vision_tools import check_vision_requirements
- return check_vision_requirements()
diff --git a/tools/browser_tool_lifecycle.py b/tools/browser_tool_lifecycle.py
deleted file mode 100644
index 098c182d209..00000000000
--- a/tools/browser_tool_lifecycle.py
+++ /dev/null
@@ -1,801 +0,0 @@
-"""Browser session lifecycle: inactivity janitor, orphan reaper, per-session teardown, atexit cleanup.
-
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import contextlib
-import os
-import shutil
-import signal
-import subprocess
-import threading
-import time
-from datetime import datetime, timezone, UTC
-from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
-
-from hermes_constants import get_hermes_home, reset_hermes_home_override, set_hermes_home_override
-from tools.browser_tool_origin import origin as _bt
-from tools import browser_tool_cdp as _cdp
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_session as _session
-from tools import browser_tool_install as _install
-from tools import browser_tool_real_profile as _real_profile
-
-
-def _session_expiry_timestamp(session_info: dict[str, Any]) -> Optional[float]:
- """Provider-authoritative session expiry as epoch seconds; None when absent or
- malformed (cloud providers may omit ``expires_at``; local browsers never have one)."""
- value = session_info.get("expires_at")
- if isinstance(value, (int, float)) and not isinstance(value, bool):
- return float(value)
- if not isinstance(value, str) or not value.strip():
- return None
-
- normalized = value.strip()
- if normalized.endswith(("Z", "z")):
- normalized = f"{normalized[:-1]}+00:00"
- try:
- parsed = datetime.fromisoformat(normalized)
- except ValueError:
- _bt.logger.warning("Ignoring invalid cloud browser session expiry timestamp")
- return None
- if parsed.tzinfo is None:
- parsed = parsed.replace(tzinfo=UTC)
- return parsed.timestamp()
-
-
-def _session_has_expired(
- session_info: dict[str, Any], *, now: Optional[float] = None
-) -> bool:
- """Whether a cached browser session crossed its provider deadline."""
- expires_at = _session_expiry_timestamp(session_info)
- if expires_at is None:
- return False
- return (time.time() if now is None else now) >= expires_at
-
-
-def _best_effort(label: str, fn) -> None:
- """Run ``fn()``; log (debug) and swallow any exception — teardown must never abort."""
- try:
- fn()
- except Exception as e:
- _bt.logger.debug("%s failed: %s", label, e)
-
-
-def _stop_all_lightpanda() -> None:
- from tools.browser_lightpanda import stop_all_lightpanda
- stop_all_lightpanda()
-
-
-def _emergency_cleanup_all_sessions():
- """atexit: close this process's sessions, then sweep orphans left by crashed
- hermes processes — every clean exit reaps accumulated orphans, not only
- processes that used the browser tool."""
- try:
- if _bt._cleanup_done:
- return
- _bt._cleanup_done = True
- except Exception:
- # Interpreter shutdown (or a half-updated tree mid-`hermes update` where the
- # origin's fresh import fails, e.g. #112437): no resolvable state, nothing to clean.
- return
-
- # Own sessions first so their owner_pid files are gone before the reaper scans.
- # Real-profile Chrome is launched directly (not by agent-browser), so the
- # session cleanup never reaps it.
- _best_effort("Real-profile chrome cleanup on exit", _real_profile._terminate_real_profile_chrome)
- if _bt._active_sessions:
- _bt.logger.info("Emergency cleanup: closing %s active session(s)...", len(_bt._active_sessions))
- try:
- cleanup_all_browsers()
- except Exception as e:
- _bt.logger.error("Emergency cleanup error: %s", e)
- finally:
- with _bt._cleanup_lock:
- _bt._active_sessions.clear()
- _bt._session_last_activity.clear()
- _bt._session_owner_homes.clear()
- _bt._cleanup_failures.clear()
- _bt._recording_sessions.clear()
- # Lightpanda servers we spawned that fell out of ``_active_sessions``.
- _best_effort("Lightpanda cleanup on exit", _stop_all_lightpanda)
- # Safe even if we never used the browser — owner_pid liveness protects daemons
- # owned by other live hermes processes.
- _best_effort("Orphan reap on exit", _reap_orphaned_browser_sessions)
-
-
-def _session_owner_scope(task_id: str):
- """Run under the Hermes home + secret scope owning ``task_id``'s session (no-op if unrecorded).
-
- The janitor thread is process-global, so each teardown must re-enter its OWN
- profile's scope rather than inherit the spawning profile's; never falls
- through to ``os.environ``.
- """
- owner_home = _bt._session_owner_homes.get(task_id)
- if owner_home is None:
- yield
- return
-
- from agent.secret_scope import build_profile_secret_scope, reset_secret_scope, set_secret_scope
- from hermes_cli.env_loader import hydrate_profile_secret_sources
-
- home_token = set_hermes_home_override(owner_home)
- try:
- hydrate_profile_secret_sources(Path(owner_home))
- secret_token = set_secret_scope(build_profile_secret_scope(Path(owner_home)), profile_home=owner_home)
- try:
- yield
- finally:
- reset_secret_scope(secret_token)
- finally:
- reset_hermes_home_override(home_token)
-
-
-def _forget_session_tracking(task_id: str, *, activity: bool = True, session: bool = False) -> None:
- """Drop the janitor's bookkeeping (and optionally the session entry) for ``task_id``."""
- with _bt._cleanup_lock:
- if session:
- _bt._active_sessions.pop(task_id, None)
- if activity:
- _bt._session_last_activity.pop(task_id, None)
- _bt._session_owner_homes.pop(task_id, None)
- _bt._cleanup_failures.pop(task_id, None)
-
-
-def _cleanup_inactive_browser_sessions():
- """Close sessions inactive longer than the timeout (cleanup thread).
-
- Each teardown runs under its owner profile's scope. A session whose cleanup
- keeps failing is force-reaped after MAX_INACTIVITY_CLEANUP_FAILURES attempts;
- only a successful cleanup clears its failure count.
-
- See #100738, #86402.
- """
- current_time = time.time()
-
- with _bt._cleanup_lock:
- sessions_to_cleanup = [task_id for task_id, last_time in list(_bt._session_last_activity.items())
- if current_time - last_time > _bt.BROWSER_SESSION_INACTIVITY_TIMEOUT]
-
- for task_id in sessions_to_cleanup:
- with _session_owner_scope(task_id):
- if _human_holds_shared_browser(task_id):
- # A human took the bot's screen (login, 2FA) — the agent is idle BECAUSE they are working.
- _update_session_activity(task_id)
- continue
- elapsed = int(current_time - _bt._session_last_activity.get(task_id, current_time))
- _bt.logger.info("Cleaning up inactive session for task: %s (inactive for %ss)", task_id, elapsed)
- try:
- with _session_owner_scope(task_id):
- cleanup_browser(task_id)
- _forget_session_tracking(task_id)
- except Exception as e:
- with _bt._cleanup_lock:
- failures = _bt._cleanup_failures[task_id] = _bt._cleanup_failures.get(task_id, 0) + 1
- if failures < _bt.MAX_INACTIVITY_CLEANUP_FAILURES:
- _bt.logger.warning("Error cleaning up inactive session %s (attempt %d/%d): %s",
- task_id, failures, _bt.MAX_INACTIVITY_CLEANUP_FAILURES, e)
- continue
- _bt.logger.error("Browser cleanup failed %d times for inactive session %s; "
- "force-reaping: %s", failures, task_id, e)
- try:
- with _session_owner_scope(task_id):
- _force_reap_browser_session(task_id)
- except Exception as reap_exc:
- _bt.logger.error("Force-reap of browser session %s failed: %s", task_id, reap_exc)
- finally:
- _forget_session_tracking(task_id, activity=False)
-
-
-def _human_holds_shared_browser(task_id: str) -> bool:
- """Lease check for the janitor, under the owner's profile scope (the lease is per profile)."""
- with _bt._cleanup_lock:
- session_info = _bt._active_sessions.get(task_id)
- if not session_info:
- return False
- return _session.human_holds_shared_browser(session_info)
-
-
-def _write_owner_pid(socket_dir: str, session_name: str) -> None:
- """Record this hermes PID in ``<socket_dir>/<session>.owner_pid`` so the orphan
- reaper can tell live-owner daemons from crashed-owner ones. Best-effort: an
- OSError falls back to the legacy ``tracked_names`` heuristic."""
- try:
- path = os.path.join(socket_dir, f"{session_name}.owner_pid")
- with open(path, "w", encoding="utf-8") as f:
- f.write(str(os.getpid()))
- except OSError as exc:
- _bt.logger.debug("Could not write owner_pid file for %s: %s", session_name, exc)
-
-
-def _argv_token_is_path(token: str, path: str) -> bool:
- """True when ``token`` (or its ``--flag=VALUE`` value) names exactly ``path``."""
- want = os.path.normpath(path).lower()
- candidate = token.split("=", 1)[1] if token.startswith("-") and "=" in token else token
- return bool(candidate) and os.path.normpath(candidate).lower() == want
-
-
-def _verify_reapable_browser_daemon(daemon_pid: int, socket_dir: str,
- session_name: str) -> bool:
- """Confirm a live PID is genuinely *this* session's agent-browser daemon (fail-closed).
-
- The ``.pid`` file sits in a world-writable temp dir: a planted or recycled PID
- would turn the tree-kill into an arbitrary-process DoS. Both must pass:
- (1) identity — ``agent-browser`` in name/cmdline; (2) binding — the socket dir in
- the cmdline or ``AGENT_BROWSER_SOCKET_DIR`` in its environ (the real spoof defense).
- """
- def refuse(reason: str, *args) -> bool:
- _bt.logger.warning("Refusing to reap browser daemon PID %d (session %s): " + reason,
- daemon_pid, session_name, *args)
- return False
-
- try:
- import psutil
- except ImportError: # psutil is a hard dep; defensive only
- return refuse("psutil unavailable for identity verification")
-
- try:
- proc = psutil.Process(daemon_pid)
- name = (proc.name() or "").lower()
- argv = list(proc.cmdline() or [])
- cmdline = " ".join(argv).lower()
- except psutil.NoSuchProcess:
- return False # vanished between the liveness check and now
- except (psutil.AccessDenied, OSError) as exc:
- return refuse("could not read process identity (%s)", exc)
-
- if "agent-browser" not in name and "agent-browser" not in cmdline:
- return refuse("not an agent-browser process (name=%r)", name)
-
- # Binding must be the FULL socket-dir path as an argv token (bare or `--flag=path`),
- # never a substring: the dir basename is predictable (`agent-browser-<session>`), so a
- # recycled PID running e.g. `grep agent-browser-h_x ...` would pass a basename check.
- bound = any(_argv_token_is_path(tok, socket_dir) for tok in argv)
- if not bound:
- try:
- env_dir = (proc.environ() or {}).get("AGENT_BROWSER_SOCKET_DIR", "")
- bound = bool(env_dir) and os.path.normpath(env_dir) == os.path.normpath(socket_dir)
- except (psutil.AccessDenied, psutil.NoSuchProcess, OSError):
- bound = False # environ() can be denied even same-user; cmdline already failed — fail closed
- if not bound:
- return refuse("not bound to session socket dir %s (possible recycled PID or planted pid file)", socket_dir)
- return True
-
-
-def _socket_dir_idle_seconds(socket_dir: str) -> Optional[float]:
- """Seconds since anything in ``socket_dir`` was last written; None if unknown (fail safe).
- Every command rewrites ``_stdout_<cmd>`` there — a restart-proof activity marker — and
- rewriting doesn't touch the dir mtime, so entries are scanned too."""
- try:
- latest = os.path.getmtime(socket_dir)
- except OSError:
- return None
-
- try:
- with os.scandir(socket_dir) as entries:
- for entry in entries:
- try:
- latest = max(latest, entry.stat().st_mtime)
- except OSError:
- continue
- except OSError:
- pass # dir mtime alone is still a usable lower bound
-
- return max(0.0, time.time() - latest)
-
-
-def _read_pid_file(path: str) -> Optional[int]:
- """Integer PID from ``path``; None when missing or corrupt."""
- try:
- return int(Path(path).read_text(encoding="utf-8-sig").strip())
- except (ValueError, OSError):
- return None
-
-
-def _owner_pid_alive(socket_dir: str, session_name: str) -> tuple[Optional[int], Optional[bool]]:
- """Read ``<session>.owner_pid`` and report ``(pid, alive)``; ``(None, None)`` when missing/corrupt."""
- owner_pid = _read_pid_file(os.path.join(socket_dir, f"{session_name}.owner_pid"))
- if owner_pid is None:
- return None, None
- # ``os.kill(pid, 0)`` is NOT a no-op on Windows; use the cross-platform check.
- from gateway.status import _pid_exists
- return owner_pid, _pid_exists(owner_pid)
-
-
-def _terminate_verified_daemon(daemon_pid: int, session_name: str, log) -> bool:
- """Tree-kill ``daemon_pid`` if it has a start-time fingerprint (so a PID swapped
- between check and kill is refused); False (logged via ``log``) when no fingerprint.
- Raises on OS errors."""
- from gateway.status import get_process_start_time
- from tools.process_registry import ProcessRegistry
- daemon_start = get_process_start_time(daemon_pid)
- if daemon_start is None:
- log("Refusing to reap browser daemon PID %d (session %s): no start-time fingerprint available",
- daemon_pid, session_name)
- return False
- ProcessRegistry._terminate_host_pid(daemon_pid, daemon_start)
- return True
-
-
-def _reap_socket_dir(socket_dir: str, session_name: str, tracked_names: set) -> bool:
- """Reap one ``agent-browser-<session>`` dir if orphaned; True when a daemon was killed.
-
- A live ``owner_pid`` means another hermes process owns it — leave it UNLESS untracked
- here and idle past ``BROWSER_ORPHAN_GRACE_SECONDS`` (owner-alive alone made leaked
- daemons immortal); no owner_pid (legacy) falls back to this process's tracking. A
- pidless dir is only stale after the grace period (deleting it immediately races the
- creator's first stdout open). The PID is identity-verified before any tree-kill.
- """
- owner_pid, owner_alive = _owner_pid_alive(socket_dir, session_name)
- if owner_alive is True:
- if session_name in tracked_names:
- return False
- idle_s = _socket_dir_idle_seconds(socket_dir)
- if idle_s is None or idle_s < _bt.BROWSER_ORPHAN_GRACE_SECONDS:
- return False # unknown age or within grace — fail safe
- _bt.logger.warning(
- "Browser session %s has a live owner (PID %s) but is untracked "
- "and idle for %ds (grace %ds) — treating as leaked and reaping",
- session_name, owner_pid, int(idle_s),
- _bt.BROWSER_ORPHAN_GRACE_SECONDS)
- elif owner_alive is None and session_name in tracked_names:
- return False
-
- pid_file = os.path.join(socket_dir, f"{session_name}.pid")
- if not os.path.isfile(pid_file):
- idle_s = _socket_dir_idle_seconds(socket_dir)
- if idle_s is None or idle_s < _bt.BROWSER_ORPHAN_GRACE_SECONDS:
- return False
- shutil.rmtree(socket_dir, ignore_errors=True)
- return False
-
- daemon_pid = _read_pid_file(pid_file)
- from gateway.status import _pid_exists
- if daemon_pid is None or not _pid_exists(daemon_pid):
- shutil.rmtree(socket_dir, ignore_errors=True)
- return False
-
- if not _verify_reapable_browser_daemon(daemon_pid, socket_dir, session_name):
- return False # leave process and dir for a later sweep once the imposter PID is gone
-
- # Tree-kill so Chromium children (renderer, GPU, ...) go too.
- reaped = False
- try:
- if not _terminate_verified_daemon(daemon_pid, session_name, _bt.logger.warning):
- return False
- _bt.logger.info("Reaped orphaned browser daemon PID %d (session %s)", daemon_pid, session_name)
- reaped = True
- except (ProcessLookupError, PermissionError, OSError):
- pass
- shutil.rmtree(socket_dir, ignore_errors=True)
- return reaped
-
-
-def _reap_orphaned_browser_sessions():
- """Kill agent-browser daemons whose owning hermes process is gone (an unclean exit loses
- ``_active_sessions`` but node + Chromium keep running). Scans the tmp dir for
- ``agent-browser-*`` socket dirs; safe from any context."""
- import glob
-
- # Lightpanda servers keep their own records (no socket dir); sweep them with the
- # same owner-liveness rule BEFORE the daemon scan, which may return early.
- def _reap_lp():
- from tools.browser_lightpanda import reap_orphaned_lightpanda
- reap_orphaned_lightpanda()
- _best_effort("Lightpanda orphan reap", _reap_lp)
-
- tmpdir = _bt._socket_safe_tmpdir()
- socket_dirs = []
- # The shared real-profile attach daemon is named, not ``<prefix>_<hex>``; list it explicitly.
- for prefix in ("agent-browser-h_*", "agent-browser-cdp_*", "agent-browser-hermes_*",
- f"agent-browser-{_bt._REAL_PROFILE_SESSION}"):
- socket_dirs += glob.glob(os.path.join(tmpdir, prefix))
- if not socket_dirs:
- return
-
- with _bt._cleanup_lock:
- tracked_names = {info.get("session_name") for info in _bt._active_sessions.values() if info.get("session_name")}
- # Browsing on the shared real-profile daemon runs through per-task ``rp_*`` sessions
- # (``--cdp``), so its own dir never shows activity; the idle escape hatch would misfire
- # under a live user. Owner liveness alone gates it — a dead owner still gets reaped.
- tracked_names.add(_bt._REAL_PROFILE_SESSION)
-
- reaped = 0
- for socket_dir in socket_dirs:
- session_name = os.path.basename(socket_dir).removeprefix("agent-browser-")
- if session_name and _reap_socket_dir(socket_dir, session_name, tracked_names):
- reaped += 1
-
- if reaped:
- _bt.logger.info("Reaped %d orphaned browser session(s) from previous run(s)", reaped)
-
-
-def _browser_cleanup_thread_worker():
- """Every 30s: close sessions idle past BROWSER_SESSION_INACTIVITY_TIMEOUT; reap
- orphans on startup AND every BROWSER_ORPHAN_REAP_INTERVAL seconds."""
- reap_every_cycles = max(1, round(_bt.BROWSER_ORPHAN_REAP_INTERVAL / 30))
- cycle = 0
-
- while _bt._cleanup_running:
- if cycle % reap_every_cycles == 0: # cycle 0 is the startup reap
- try:
- _reap_orphaned_browser_sessions()
- except Exception as e:
- _bt.logger.warning("Orphan reap error: %s", e)
- cycle += 1
-
- try:
- _cleanup_inactive_browser_sessions()
- except Exception as e:
- _bt.logger.warning("Cleanup thread error: %s", e)
-
- for _ in range(30): # 1s granularity so stop is quick
- if not _bt._cleanup_running:
- break
- time.sleep(1)
-
-
-def _start_browser_cleanup_thread():
- """Start the background cleanup thread if not already running."""
- with _bt._cleanup_lock:
- if _bt._cleanup_thread is None or not _bt._cleanup_thread.is_alive():
- _bt._cleanup_running = True
- _bt._cleanup_thread = threading.Thread(target=_browser_cleanup_thread_worker, daemon=True,
- name="browser-cleanup")
- _bt._cleanup_thread.start()
- _bt.logger.info("Started inactivity cleanup thread (timeout: %ss)", _bt.BROWSER_SESSION_INACTIVITY_TIMEOUT)
-
-
-def _stop_browser_cleanup_thread():
- """Stop the background cleanup thread."""
- try:
- _bt._cleanup_running = False
- thread = _bt._cleanup_thread
- except Exception:
- # Same unimportable-origin case as _emergency_cleanup_all_sessions (#112437):
- # no resolvable thread state, nothing to stop.
- return
- if thread is not None:
- # A second Ctrl+C during the timed join lands here as KeyboardInterrupt; the janitor is a
- # daemon thread, so letting it propagate only prints "Exception ignored in atexit callback".
- try:
- thread.join(timeout=5)
- except (SystemExit, KeyboardInterrupt):
- pass
-
-
-def _update_session_activity(task_id: str):
- """Touch the activity timestamp and record the owning Hermes home on first sight (the
- janitor tears down under the owner's scope). Does NOT reset ``_cleanup_failures``.
-
- See #86402.
- """
- with _bt._cleanup_lock:
- _bt._session_last_activity[task_id] = time.time()
- _bt._session_owner_homes.setdefault(task_id, str(get_hermes_home()))
-
-
-def _kill_process_tree(proc: subprocess.Popen) -> None:
- """Best-effort kill of *proc* and every descendant; never raises.
-
- ``Popen.kill()`` only signals the direct child; npm/npx helpers and the detached
- daemon grandchild keep a capture pipe open so ``communicate()`` never sees EOF, so
- the whole tree must go (no grace: the caller already burned its timeout). Delegates
- to :func:`agent.deadline.kill_process_tree`, falling back to the legacy kill.
-
- ``Popen.kill()`` only signals the direct child PID. npm/npx routinely fork further processes
- (registry-fetch helpers, npm's own lifecycle runner, agent-browser's own detached daemon grandchild)
- that can survive a plain ``kill()`` of the top-level PID and keep a ``capture_output``-style pipe open,
- hanging the caller's ``communicate()`` past the nominal timeout — the same orphaned-pipe hazard already
- hit in production on POSIX (see ``tools/process_registry.py``'s ``_reader_loop``, issue 68915: a
- backgrounded grandchild inheriting a pipe's write end kept it from ever reaching EOF). That hazard is
- cross-platform, not Windows-specific; what *is* Windows-specific is the lack of a remedy other than
- killing the tree — anonymous pipes there don't support overlapped I/O, so there's no ``select()``-style
- non-blocking read to poll around a stuck grandchild the way POSIX can. Killing the whole process
- group/tree the child was launched into reaches those descendants on both platforms. See #68915.
- """
- try:
- from agent.deadline import kill_process_tree as _deadline_kill_tree
-
- _deadline_kill_tree(proc.pid)
- except Exception:
- _legacy_kill_process_tree(proc)
-
-
-def _legacy_kill_process_tree(proc: subprocess.Popen) -> None:
- """Local tree-kill (fallback when agent.deadline is unavailable; tests pin
- the signal sequence). A child leading its own group gets SIGTERM then
- SIGKILL via killpg; a shared-group child can never be killpg'd (that is OUR
- group), so it and its psutil-snapshotted descendants are killed
- individually."""
- if os.name == "nt":
- try:
- subprocess.run(["taskkill", "/PID", str(proc.pid), "/T", "/F"],
- check=False, capture_output=True, stdin=subprocess.DEVNULL)
- except Exception:
- pass
- return
- # POSIX-only below (the nt guard returned), but resolve killpg/SIGKILL via
- # getattr so a future refactor dropping that guard degrades to plain kill().
- killpg = getattr(os, "killpg", None)
- if killpg is None: # windows-footgun: ok - non-POSIX fallback
- try:
- proc.kill()
- except Exception:
- pass
- return
- try:
- pgid = os.getpgid(proc.pid)
- except (ProcessLookupError, OSError):
- pgid = None
- # Signal the group only when the child leads it (start_new_session / process_group=0):
- # a child spawned into our group resolves pgid to OUR process group and killpg would
- # take the whole Hermes tree down with it, and a recycled PID can resolve to a foreign
- # group. The direct child still gets proc.kill() either way. Same ownership check as
- # hermes_cli/_subprocess_compat._legacy_kill_process_tree.
- descendants = []
- if pgid is not None and pgid == proc.pid:
- for sig in (signal.SIGTERM, getattr(signal, "SIGKILL", signal.SIGTERM)):
- try:
- killpg(pgid, sig)
- except (ProcessLookupError, PermissionError, OSError):
- break
- else:
- # No group signal is safe, so descendants are killed individually;
- # a bare proc.kill() would leave them holding the capture pipe's write
- # end open (the #68915 communicate() hang). The snapshot must precede
- # the parent kill: once the parent exits, children reparent and psutil
- # can no longer find them (process_registry._terminate_host_pid).
- try:
- import psutil
-
- descendants = psutil.Process(proc.pid).children(recursive=True)
- except Exception:
- descendants = []
- try:
- proc.kill()
- except Exception:
- pass
- for child in descendants:
- with contextlib.suppress(Exception):
- child.kill()
-
-
-def _pid_exists(pid: int) -> bool:
- """Best-effort 'is this PID alive' (cross-platform via gateway.status; zombies count as dead)."""
- if pid <= 0:
- return False
- from gateway.status import _pid_exists as _gateway_pid_exists
- return _gateway_pid_exists(pid)
-
-
-def _unlink_older_than(directory: Path, pattern: str, max_age_hours: float, label: str) -> None:
- """Delete ``directory/pattern`` files older than ``max_age_hours``; never raises."""
- try:
- cutoff = time.time() - (max_age_hours * 3600)
- for f in directory.glob(pattern):
- try:
- if f.stat().st_mtime < cutoff:
- f.unlink()
- except Exception as e:
- _bt.logger.debug("Failed to clean old %s %s: %s", label, f, e)
- except Exception as e:
- _bt.logger.debug("%s cleanup error (non-critical): %s", label.capitalize(), e)
-
-
-def _cleanup_old_screenshots(screenshots_dir, max_age_hours=24):
- """Prune old browser screenshots; throttled to once per hour per directory."""
- key = str(screenshots_dir)
- now = time.time()
- if now - _bt._last_screenshot_cleanup_by_dir.get(key, 0.0) < 3600:
- return
- _bt._last_screenshot_cleanup_by_dir[key] = now
- _unlink_older_than(screenshots_dir, "browser_screenshot_*.png", max_age_hours, "screenshot")
-
-
-def _cleanup_old_recordings(max_age_hours=72):
- """Prune old browser recordings."""
- try:
- recordings_dir = get_hermes_home() / "browser_recordings"
- except Exception as e:
- _bt.logger.debug("Recording cleanup error (non-critical): %s", e)
- return
- if recordings_dir.exists():
- _unlink_older_than(recordings_dir, "session_*.webm", max_age_hours, "recording")
-
-
-def _drop_last_active_binding(task_id: str) -> None:
- """Drop stale last-active ownership after cleaning ``task_id``: a bare task always, a
- sidecar only if it was still the recorded owner (a later click must not resurrect a
- cleaned sidecar while a primary-session binding is preserved)."""
- bare_task_id = _bt._bare_task_id_for_session_key(task_id)
- if bare_task_id == task_id or _bt._last_active_session_key.get(bare_task_id) == task_id:
- _bt._last_active_session_key.pop(bare_task_id, None)
-
-
-def cleanup_browser(task_id: Optional[str] = None) -> None:
- """Clean up browser session(s) for a task: a bare task id reaps BOTH the primary
- session and any hybrid local sidecar; a ``::local`` key reaps only that one."""
- if task_id is None:
- task_id = "default"
-
- session_keys = [task_id]
- sidecar_key = f"{task_id}{_bt._LOCAL_SUFFIX}"
- with _bt._cleanup_lock:
- if not _bt._is_local_sidecar_key(task_id) and sidecar_key in _bt._active_sessions:
- session_keys.append(sidecar_key)
- for session_key in session_keys:
- _cleanup_single_browser_session(session_key)
- _drop_last_active_binding(task_id)
-
-
-def _kill_verified_daemon(socket_dir: str, session_name: str) -> bool:
- """Tree-kill the daemon in ``<socket_dir>/<session>.pid`` if verifiably ours; True when
- a kill was issued. Never raises."""
- pid_file = os.path.join(socket_dir, f"{session_name}.pid")
- if not os.path.isfile(pid_file):
- return False
- try:
- daemon_pid = int(Path(pid_file).read_text(encoding="utf-8-sig").strip())
- if not _verify_reapable_browser_daemon(daemon_pid, socket_dir, session_name):
- _bt.logger.debug("Skipped daemon kill for %s: pid %s failed identity verification", session_name, daemon_pid)
- return False
- if not _terminate_verified_daemon(daemon_pid, session_name, lambda *_a: _bt.logger.debug(
- "Skipped daemon kill for %s: no start-time fingerprint for pid %s", session_name, daemon_pid)):
- return False
- _bt.logger.debug("Killed daemon pid %s for %s", daemon_pid, session_name)
- return True
- except (ProcessLookupError, ValueError, PermissionError, OSError):
- _bt.logger.debug("Could not kill daemon pid for %s (already dead or inaccessible)", session_name)
- return False
-
-
-def _release_session_resources(task_id: str, session_info: dict[str, Any]) -> None:
- """Untrack ``task_id``, close its cloud provider session, kill its daemon — the
- unconditional tail of a teardown, and the whole of the janitor's force-reap path.
-
- The unconditional tail of ``_cleanup_single_browser_session``; also the whole of the janitor's
- force-reap path (#100738), which skips the polite agent-browser/Camofox ``close`` that kept failing but
- must still release the cloud session and the local Chromium.
- """
- _forget_session_tracking(task_id, session=True)
- _release_session_backend(task_id, session_info)
-
-
-def _release_session_backend(task_id: str, session_info: dict[str, Any]) -> None:
- """Close ``session_info``'s cloud provider session and kill its daemon, by object: no shared
- session map is read or written (an unpublished session releases through this alone)."""
- bb_session_id = session_info.get("bb_session_id", "unknown")
- if bb_session_id: # cloud only — local sidecars have bb_session_id=None
- provider = _cloud._get_cloud_provider()
- if provider is not None:
- try:
- provider.close_session(bb_session_id)
- except Exception as e: # health: allow BLE001 -- teardown boundary moved unchanged from _release_session_resources; a provider error must never abort the daemon kill below
- _bt.logger.warning("Could not close cloud browser session: %s", e)
-
- session_name = session_info.get("session_name", "")
- if session_name:
- socket_dir = os.path.join(_bt._socket_safe_tmpdir(), f"agent-browser-{session_name}")
- if os.path.exists(socket_dir):
- _kill_verified_daemon(socket_dir, session_name)
- shutil.rmtree(socket_dir, ignore_errors=True)
-
-
-def _force_reap_browser_session(task_id: str) -> None:
- """Janitor last resort: skip the failing ``close`` round-trips, release resources directly.
-
- Janitor last resort after repeated cleanup failures (#100738).
- """
- _cdp._stop_cdp_supervisor(task_id)
- with _bt._cleanup_lock:
- session_info = _bt._active_sessions.get(task_id)
- _bt._session_last_activity.pop(task_id, None)
- _bt._recording_sessions.discard(task_id)
- if session_info:
- _release_session_resources(task_id, session_info)
- _drop_last_active_binding(task_id)
-
-
-def _cleanup_single_browser_session(task_id: str) -> None:
- """Reap a single browser session by its exact session key."""
- _cdp._stop_cdp_supervisor(task_id) # close our WebSocket BEFORE the backend tears down the endpoint
-
- # Camofox: managed persistence keeps the profile (cookies) across tasks; skip the full
- # close then — the inactivity reaper still frees idle resources.
- if _bt._is_camofox_mode():
- def _camofox_cleanup():
- from tools.browser_camofox import camofox_close, camofox_soft_cleanup
- if not camofox_soft_cleanup(task_id):
- camofox_close(task_id)
- _best_effort(f"Camofox cleanup for task {task_id}", _camofox_cleanup)
-
- _bt.logger.debug("cleanup_browser called for task_id: %s", task_id)
- _bt.logger.debug("Active sessions: %s", list(_bt._active_sessions.keys()))
-
- # Look up but don't remove yet — _run_browser_command needs the entry for ``close``.
- with _bt._cleanup_lock:
- session_info = _bt._active_sessions.get(task_id)
-
- if not session_info:
- _bt.logger.debug("No active session found for task_id: %s", task_id)
- return
-
- _bt.logger.debug("Found session for task %s: bb_session_id=%s", task_id, session_info.get("bb_session_id", "unknown"))
- _bt._maybe_stop_recording(task_id) # saves the file before close
-
- # Lightpanda sessions have no daemon to ``close``; an expired cloud CDP URL cannot
- # accept one and would make _get_session_info() renew the session mid-cleanup.
- if (session_info.get("features") or {}).get("lightpanda"):
- try:
- from tools.browser_lightpanda import stop_lightpanda
- stop_lightpanda(session_info.get("session_name", ""))
- except Exception as e:
- _bt.logger.warning("lightpanda stop failed for task %s: %s", task_id, e)
- elif _session_has_expired(session_info):
- _bt.logger.debug("Skipping agent-browser close for expired session %s", task_id)
- else:
- try:
- _session._run_browser_command(task_id, "close", [], timeout=10)
- _bt.logger.debug("agent-browser close command completed for task %s", task_id)
- except Exception as e:
- _bt.logger.warning("agent-browser close failed for task %s: %s", task_id, e)
-
- _release_session_resources(task_id, session_info)
- _bt.logger.debug("Removed task %s from active sessions", task_id)
-
-
-def cleanup_profile_browsers(home_key: str) -> None:
- """Close one profile home's browser sessions, CDP supervisors and harness daemons, and drop its
- cached config slots (``/browser connect`` on a multiplexed gateway). Other profiles' browsers stay."""
- with _bt._cleanup_lock:
- task_ids = [task for task, info in _bt._active_sessions.items() if info.get("home_key") == home_key]
- for task_id in task_ids:
- _cleanup_single_browser_session(task_id)
- _drop_last_active_binding(task_id)
-
- def _stop_supervisors():
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- SUPERVISOR_REGISTRY.stop_home(home_key)
- _best_effort("CDP supervisor stop", _stop_supervisors)
-
- def _stop_harness():
- from tools.browser_use_cli import stop_harness_daemons
- stop_harness_daemons(home_key)
- _best_effort("Browser Use harness daemon stop", _stop_harness)
- for cache in ("_cached_command_timeout", "_cached_snapshot_threshold"):
- with contextlib.suppress(AttributeError, TypeError):
- getattr(_bt, cache).pop(home_key, None)
-
-
-def cleanup_all_browsers() -> None:
- """Clean up all active browser sessions (shutdown) and reset cached lookups."""
- with _bt._cleanup_lock:
- task_ids = list(_bt._active_sessions.keys())
- for task_id in task_ids:
- cleanup_browser(task_id)
-
- try: # tear down CDP supervisors so background threads exit
- from tools.browser_supervisor import SUPERVISOR_REGISTRY # type: ignore[import-not-found]
- SUPERVISOR_REGISTRY.stop_all()
- except Exception:
- pass
-
- def _stop_harness():
- from tools.browser_use_cli import stop_harness_daemons
- stop_harness_daemons()
- _best_effort("Browser Use harness daemon stop", _stop_harness)
-
- _install._discover_homebrew_node_dirs.cache_clear()
- _bt._chromium_autoinstall_attempted = False
- # Each resolved flag flips BEFORE its cache is nulled so a concurrent reader never
- # sees ``resolved=True`` with ``cache=None``.
- for flag, cache in (
- ("_command_timeout_resolved", "_cached_command_timeout"),
- ("_snapshot_threshold_resolved", "_cached_snapshot_threshold"),
- ("_browser_engine_resolved", "_cached_browser_engine"),
- ):
- setattr(_bt, flag, False)
- setattr(_bt, cache, None)
diff --git a/tools/browser_tool_lightpanda_fallback.py b/tools/browser_tool_lightpanda_fallback.py
deleted file mode 100644
index 91688e7a553..00000000000
--- a/tools/browser_tool_lightpanda_fallback.py
+++ /dev/null
@@ -1,200 +0,0 @@
-"""Lightpanda engine status and the automatic Chrome fallback for browser commands
-that Lightpanda cannot serve (screenshots, empty snapshots, failed commands).
-
-Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import json
-import os
-import shutil
-import subprocess
-from typing import Any, Dict, List, Optional, Tuple
-from tools.browser_tool_origin import origin_module as _origin
-from tools import browser_tool_cdp as _cdp
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_install as _install
-from tools import browser_tool_session as _session
-
-# Commands where Chrome can meaningfully produce a different result. Session-management
-# commands (close, record) are tied to the engine's daemon and can't be retried elsewhere.
-_FALLBACK_ELIGIBLE = frozenset({"open", "snapshot", "screenshot", "eval", "click",
- "fill", "scroll", "back", "press", "console", "errors"})
-
-
-def _using_lightpanda_engine() -> bool:
- """Return True when local browser commands are configured for Lightpanda."""
- return _cloud._get_browser_engine() == "lightpanda"
-
-
-def lightpanda_engine_status() -> tuple[bool, str]:
- """Whether ``browser.engine: lightpanda`` is actually in effect, and why.
-
- ``(False, "")`` when the engine isn't lightpanda; else the reason names the setting shadowing
- it or the driver running it. Mirrors ``_should_inject_engine`` / ``_resolve_backend_cdp``
- precedence with config-only gates (no network I/O) for ``/browser status`` / ``hermes doctor``.
- """
- _bt = _origin()
- if not _using_lightpanda_engine():
- return False, ""
- if _cdp._get_cdp_override_raw():
- return False, "a CDP override is active (/browser connect or browser.cdp_url)"
- if _bt._is_camofox_mode():
- return False, "Camofox is the selected browser (CAMOFOX_URL)"
- # Real-profile before cloud provider: browser_exec resolves real-profile before
- # the backend, so with both set the real-profile toggle claims the session.
- if _cloud._use_real_profile():
- return False, "browser.use_real_profile is on (Lightpanda cannot load a Chromium profile)"
- try:
- provider = _cloud._get_cloud_provider()
- except Exception:
- provider = None
- if provider is not None:
- try:
- name = provider.display_name
- except Exception:
- name = type(provider).__name__
- return False, f"cloud provider {name} is selected (browser.cloud_provider, or auto-detected from credentials)"
- if not _bt._is_browser_use_cli_mode():
- return True, "built-in browser tools: agent-browser --engine lightpanda"
- try:
- from tools.browser_use_cli import _read_browser_cfg, is_legacy_browser_use_cloud_config
- if is_legacy_browser_use_cloud_config(_read_browser_cfg()):
- return False, "Browser Use cloud (BROWSER_USE_API_KEY) is selected"
- except Exception as e:
- _bt.logger.debug("legacy Browser Use cloud check failed: %s", e)
- return True, "Browser Use mode: Hermes spawns `lightpanda serve` per session"
-
-
-def _lightpanda_fallback_reason(engine: str, command: str, result: dict[str, Any]) -> Optional[str]:
- """User-visible reason a Lightpanda result needs the Chrome fallback (copied into the result), or None."""
- if engine != "lightpanda" or command not in _FALLBACK_ELIGIBLE:
- return None
- if not result.get("success"):
- return f"Lightpanda {command!r} failed ({str(result.get('error') or 'command failed').strip()}); retried with Chrome."
- data = result.get("data", {})
- if command == "snapshot" and len((data.get("snapshot", "") or "").strip()) < 20: # couldn't render
- return "Lightpanda returned an empty/too-short snapshot; retried with Chrome."
- if command == "screenshot" and data.get("path", ""):
- # Lightpanda returns a ~17 KB placeholder PNG (panda logo at 1920x1080); real Chromium is 100 KB+.
- try:
- size = os.path.getsize(data["path"])
- except OSError:
- return "Lightpanda screenshot file was missing/unreadable; retried with Chrome."
- if size < 20480:
- _origin().logger.debug("Lightpanda screenshot is suspiciously small (%d bytes), "
- "triggering Chrome fallback", size)
- return f"Lightpanda screenshot was suspiciously small ({size} bytes); " "retried with Chrome."
- return None
-
-
-def _needs_lightpanda_fallback(engine: str, command: str, result: dict[str, Any]) -> bool:
- """Check if a Lightpanda result should trigger an automatic Chrome fallback."""
- return _lightpanda_fallback_reason(engine, command, result) is not None
-
-
-def _annotate_lightpanda_fallback(result: dict[str, Any], reason: str) -> dict[str, Any]:
- """Add a user-visible Chrome fallback warning to a browser command result."""
- warning = "⚠ Lightpanda fallback: Chrome was used for this browser action. " f"{reason}"
- fields = {"fallback_warning": warning, "browser_engine": "chrome",
- "browser_engine_fallback": {"from": "lightpanda", "to": "chrome", "reason": reason}}
- annotated = {**result, **fields}
- data = annotated.get("data")
- if isinstance(data, dict):
- annotated["data"] = data = dict(data)
- for key, value in fields.items():
- data.setdefault(key, dict(value) if isinstance(value, dict) else value)
- return annotated
-
-
-def _copy_fallback_warning(target: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
- """Copy browser fallback metadata from an internal result into a tool response."""
- if result.get("fallback_warning"):
- target["fallback_warning"] = result["fallback_warning"]
- target["browser_engine"] = result.get("browser_engine")
- target["browser_engine_fallback"] = result.get("browser_engine_fallback")
- return target
-
-
-def _run_chrome_fallback_command(task_id: str, command: str, args: list[str], timeout: int) -> dict[str, Any]:
- """Run a browser command in a temporary Chrome session at the current URL.
-
- agent-browser locks the engine when a named daemon starts, so ``--engine chrome`` on the
- Lightpanda session is ignored: fresh temp Chrome session -> same URL -> ``command`` -> tear down.
- """
- _bt = _origin()
- import uuid
- # 1. Current URL from the Lightpanda session. ``get url`` is not fallback-eligible,
- # so this can't recurse; the explicit override strips Chromium-only env flags.
- url_result = _session._run_browser_command(task_id, "get", ["url"], timeout=10, _engine_override="lightpanda")
- current_url = str(url_result.get("data", {}).get("url", "")).strip() if url_result.get("success") else None
- if not current_url:
- _bt.logger.warning("Chrome fallback: could not determine current URL from LP session")
- return {"success": False, "error": "Chrome fallback failed: could not determine current URL"}
-
- # 2. Temporary Chrome session (bypasses _get_session_info's cache).
- tmp_session = f"h_cfb_{uuid.uuid4().hex[:8]}"
- try:
- browser_cmd = _install._find_agent_browser()
- except FileNotFoundError as e:
- return {"success": False, "error": str(e)}
-
- if not _install._chromium_installed():
- if _install._running_in_docker():
- hint = ("Chrome fallback requires Chromium, but it is missing. You're running in Docker — "
- "pull the latest image: docker pull ghcr.io/nousresearch/hermes-agent:latest")
- else:
- hint = ("Chrome fallback requires Chromium, but it is missing. Install it with: "
- "hermes pm install chromium")
- return {"success": False, "error": hint}
-
- base_args = _session._agent_browser_argv(browser_cmd) + ["--engine", "chrome", "--session", tmp_session, "--json"]
- task_socket_dir = _session._prepare_session_socket_dir(tmp_session)
- # Bypasses _run_browser_command, so apply the same Chromium sandbox/screen policy explicitly.
- _session._ensure_screen_for_headed_chromium()
- browser_env = _session._agent_browser_command_env(task_socket_dir)
- _session._apply_chromium_sandbox_args(browser_env)
- # #64867: the temp Chrome session is a background retry, so it launches
- # headless on Windows even in headed mode (no --headed argv exists here to
- # contradict; an explicit AGENT_BROWSER_HEADED is never overridden).
- browser_env = _session.windows_headless_browser_options(browser_env)
-
- def _run_tmp(cmd: str, cmd_args: list[str]) -> dict[str, Any]:
- proc = _session._popen_agent_browser(base_args + [cmd] + cmd_args, browser_env, task_socket_dir, cmd)
- stdout_path = os.path.join(task_socket_dir, f"_stdout_{cmd}")
- stderr_path = os.path.join(task_socket_dir, f"_stderr_{cmd}")
- try:
- proc.wait(timeout=timeout)
- except subprocess.TimeoutExpired:
- proc.kill()
- proc.wait()
- return {"success": False, "error": f"Chrome fallback '{cmd}' timed out"}
- try:
- with open(stdout_path, encoding="utf-8-sig") as f:
- stdout = f.read().strip()
- if stdout:
- return json.loads(stdout.split("\n")[-1])
- except Exception as exc:
- _bt.logger.debug("Chrome fallback tmp cmd '%s' error: %s", cmd, exc)
- finally:
- _session._unlink_command_output_files(stdout_path, stderr_path)
- return {"success": False, "error": f"Chrome fallback '{cmd}' failed"}
-
- try:
- # 3. Navigate Chrome to the same URL, then 4. run the requested command.
- nav = _run_tmp("open", [current_url])
- if not nav.get("success"):
- _bt.logger.warning("Chrome fallback: navigate failed: %s", nav.get("error"))
- return {"success": False, "error": f"Chrome fallback navigate failed: {nav.get('error')}"}
- return _run_tmp(command, args)
- finally:
- # 5. Tear down the temporary Chrome session and its socket directory.
- try:
- _run_tmp("close", [])
- except Exception:
- pass
- shutil.rmtree(task_socket_dir, ignore_errors=True)
-
-
-def _chrome_fallback_screenshot(task_id: str, args: list[str], timeout: int) -> dict[str, Any]:
- """Take a screenshot using a temporary Chrome session."""
- return _run_chrome_fallback_command(task_id, "screenshot", args, timeout)
diff --git a/tools/browser_tool_origin.py b/tools/browser_tool_origin.py
deleted file mode 100644
index 1fe7a9491f7..00000000000
--- a/tools/browser_tool_origin.py
+++ /dev/null
@@ -1,87 +0,0 @@
-"""Origin-module lookup shared by the ``tools.browser_tool_*`` extraction modules.
-
-Extracted code reads facade-owned state (caches, locks, session tables, facade-defined
-helpers) *through* ``tools.browser_tool`` and must not import it at import time (cycle) —
-hence the lazy :func:`origin_module` and the :data:`origin` proxy.
-"""
-
-import sys
-from types import ModuleType
-
-_ORIGIN_NAME = "tools.browser_tool"
-
-
-class _NamespaceView:
- """Live view over a module namespace whose module object is gone (a test purged
- ``sys.modules``): the old code still runs with its own globals, so hit *those*."""
-
- __slots__ = ("_g",)
-
- def __init__(self, g):
- object.__setattr__(self, "_g", g)
-
- def __getattr__(self, name):
- try:
- return self._g[name]
- except KeyError:
- raise AttributeError(name) from None
-
- def __setattr__(self, name, value):
- self._g[name] = value
-
-
-def _module_for_globals(g: dict):
- """The module object whose namespace is ``g`` (or a live view over it)."""
- import tools
-
- for mod in (sys.modules.get(_ORIGIN_NAME), getattr(tools, "browser_tool", None)):
- if mod is not None and mod.__dict__ is g:
- return mod
- return _NamespaceView(g)
-
-
-def origin_module(_depth: int = 2):
- """The ``tools.browser_tool`` instance the *calling* moved function belongs to, mirroring
- what in-file code would see: (1) the nearest enclosing frame executing origin code (the
- exact module copy, even after a test purged/reloaded ``sys.modules``); (2) an origin
- module referenced from a calling frame's globals; (3) ``sys.modules`` / ``tools``
- package attribute / fresh import. ``_depth`` is the frame of the moved function's caller."""
- try:
- start = sys._getframe(_depth)
- except ValueError: # called directly by the interpreter (atexit callback)
- start = None
- frame = start
- while frame is not None:
- if frame.f_globals.get("__name__") == _ORIGIN_NAME:
- return _module_for_globals(frame.f_globals)
- frame = frame.f_back
- frame = start
- while frame is not None:
- for value in list(frame.f_globals.values()):
- if isinstance(value, ModuleType) and getattr(value, "__name__", None) == _ORIGIN_NAME:
- return value
- frame = frame.f_back
- mod = sys.modules.get(_ORIGIN_NAME)
- if mod is None:
- import tools
-
- mod = getattr(tools, "browser_tool", None)
- if mod is None:
- import tools.browser_tool as mod
- return mod
-
-
-class _OriginProxy:
- """Module-level ``_bt`` stand-in: every attribute read/write forwards to the origin
- module resolved at that moment."""
-
- __slots__ = ()
-
- def __getattr__(self, name):
- return getattr(origin_module(3), name)
-
- def __setattr__(self, name, value):
- setattr(origin_module(3), name, value)
-
-
-origin = _OriginProxy()
diff --git a/tools/browser_tool_real_profile.py b/tools/browser_tool_real_profile.py
deleted file mode 100644
index 2ad6a1410c6..00000000000
--- a/tools/browser_tool_real_profile.py
+++ /dev/null
@@ -1,354 +0,0 @@
-"""Real-profile local browsing: snapshot the user's default Chromium profile into a
-hermes-owned copy, launch the real browser binary on it, and attach agent-browser.
-
-State (``_REAL_PROFILE_SESSION``, ``_real_profile_cdp_lock``, ``_real_profile_cdp_cache``,
-``_real_profile_chrome_procs``) lives in ``tools.browser_tool``; it is read
-through ``_bt`` (resolved per call — never import ``tools.browser_tool`` at import time).
-"""
-
-import os
-import re
-import subprocess
-import sys
-import time
-from typing import Optional, Tuple
-from agent.proxy_bypass import loopback_request_kwargs
-from tools.browser_tool_origin import origin_module as _origin
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_install as _install
-from tools import browser_tool_lightpanda_fallback as _lp
-from tools import browser_tool_session as _session
-
-_RP = "browser.use_real_profile is on, but "
-
-
-def _terminate_real_profile_chrome() -> None:
- """Terminate real-browser processes launched for real-profile sessions (idempotent, atexit-safe);
- agent-browser only ATTACHED to them, so its own session cleanup never kills them."""
- from tools.browser_lightpanda import _terminate
- _bt = _origin()
- while _bt._real_profile_chrome_procs:
- _terminate(_bt._real_profile_chrome_procs.pop(), what="real-profile chrome")
-
-
-def _cdp_http_ready(http_cdp: str) -> bool:
- """True when an ``http://host:port`` CDP discovery root answers."""
- from tools.browser_lightpanda import _cdp_ready
- return _cdp_ready(http_cdp, timeout=1.0)
-
-
-def _real_profile_daemon_env() -> tuple:
- """Reaper-visible socket dir + ``owner_pid`` claim like every other lane (agent-browser's
- default dir is invisible to the reaper — #100855). The daemon-side idle timeout is dropped:
- Chrome is launched by Hermes, not the daemon, so a self-exiting daemon would leave Chrome
- holding the copy dir under the next snapshot overlay. Returns ``(env, socket_dir)``."""
- _bt = _origin()
- socket_dir = _session._prepare_session_socket_dir(_bt._REAL_PROFILE_SESSION)
- env = _session._agent_browser_command_env(socket_dir)
- env.pop("AGENT_BROWSER_IDLE_TIMEOUT_MS", None)
- return env, socket_dir
-
-
-def _capture_agent_browser_cli(argv: list, timeout: float, tag: str) -> subprocess.CompletedProcess:
- """Run an agent-browser CLI argv once, capturing output through temp files (not pipes).
-
- The CLI forks a resident daemon that inherits its stdio and outlives the CLI, so with
- pipe capture the CLI can exit while its output never reaches EOF: POSIX burns the whole
- timeout draining pipes on every call, and Windows' ``TimeoutExpired`` cleanup re-drains
- with no timeout, blocking past the outer tool deadline (#96731). Same pattern as
- ``_popen_agent_browser``: wait for the CLI alone — a grandchild holding the inherited
- file handles is harmless. Raises ``TimeoutExpired`` after killing the CLI."""
- env, socket_dir = _real_profile_daemon_env()
- stdout_path = os.path.join(socket_dir, f"_stdout_{tag}")
- stderr_path = os.path.join(socket_dir, f"_stderr_{tag}")
- proc = _session._popen_agent_browser(argv, env, socket_dir, tag)
- timed_out = False
- try:
- proc.wait(timeout=timeout)
- except subprocess.TimeoutExpired:
- timed_out = True
- proc.kill()
- proc.wait()
- stdout, stderr = _session._read_command_output_files(stdout_path, stderr_path)
- _session._unlink_command_output_files(stdout_path, stderr_path)
- if timed_out:
- raise subprocess.TimeoutExpired(argv, timeout)
- return subprocess.CompletedProcess(argv, proc.returncode, stdout=stdout, stderr=stderr)
-
-
-def _agent_browser_session_cmd(session_name: str, *cmd: str, log_label: str) -> Optional[subprocess.CompletedProcess]:
- """Run ``agent-browser --session <name> <cmd...>``; None when agent-browser is missing or the run fails."""
- _bt = _origin()
- try:
- browser_cmd = _install._find_agent_browser()
- except FileNotFoundError:
- return None
- try:
- return _capture_agent_browser_cli(
- [*_session._agent_browser_argv(browser_cmd), "--session", session_name, *cmd],
- timeout=15, tag=f"rp-{log_label.replace(' ', '-')}",
- )
- except (subprocess.SubprocessError, OSError) as e:
- _bt.logger.debug("real-profile %s failed: %s", log_label, e)
- return None
-
-
-def _agent_browser_get_cdp(session_name: str) -> Optional[str]:
- """HTTP CDP discovery root of an agent-browser session (from its ``ws://`` cdp-url), or None."""
- proc = _agent_browser_session_cmd(session_name, "get", "cdp-url", log_label="get cdp-url")
- m = re.search(r"ws://127\.0\.0\.1:(\d+)/", (proc.stdout or "").strip()) if proc is not None else None
- return f"http://127.0.0.1:{m.group(1)}" if m else None
-
-
-def _read_devtools_port(data_dir: str) -> Optional[str]:
- """First line of Chrome's ``DevToolsActivePort`` in ``data_dir`` (None when unreadable)."""
- try:
- with open(os.path.join(data_dir, "DevToolsActivePort"), encoding="utf-8-sig") as fh:
- return fh.readline().strip()
- except OSError:
- return None
-
-
-def _surviving_chrome_cdp(data_dir: str) -> Optional[str]:
- """HTTP CDP root of a Chrome still running on ``data_dir``, or None. ``DevToolsActivePort``
- outlives a crashed Chrome and its port can be recycled by another local CDP server, so the
- file's browser id (line 2) must match what ``/json/version`` reports before it is trusted."""
- try:
- with open(os.path.join(data_dir, "DevToolsActivePort"), encoding="utf-8-sig") as fh:
- port, browser_path = fh.readline().strip(), fh.readline().strip()
- except OSError:
- return None
- if not port.isdigit() or not browser_path.startswith("/devtools/browser/"):
- return None
- http_cdp = f"http://127.0.0.1:{port}"
- try:
- import requests
- ws_url = str(requests.get(f"{http_cdp}/json/version", timeout=2, **loopback_request_kwargs(http_cdp))
- .json().get("webSocketDebuggerUrl") or "")
- except Exception:
- return None
- return http_cdp if ws_url.endswith(browser_path) else None
-
-
-def _cdp_on_data_dir(http_cdp: str, data_dir: str) -> bool:
- """True when the CDP endpoint's browser runs on ``data_dir`` (DevToolsActivePort match proves it
- is our profile copy, not a throwaway temp dir a raced/stale launch fell back to)."""
- m = re.search(r":(\d+)", http_cdp or "")
- return bool(m) and _read_devtools_port(data_dir) == m.group(1)
-
-
-def _agent_browser_close_session(session_name: str) -> None:
- """Best-effort close of an agent-browser session (stale/wrong-dir cleanup)."""
- _agent_browser_session_cmd(session_name, "close", log_label="session close")
-
-
-_REAL_PROFILE_CHROME_FLAGS = (
- "--remote-debugging-port=0", "--no-first-run", "--no-default-browser-check",
- "--disable-background-networking", "--disable-component-update", "--disable-default-apps",
- "--disable-hang-monitor", "--disable-popup-blocking", "--disable-prompt-on-repost",
- "--disable-sync", "--disable-features=Translate", "--no-startup-window",
-)
-
-
-def real_profile_fallback_note(err: str) -> str:
- """Tool-result note when the real profile can't load and a fresh browser serves instead: the
- browser keeps working (a consented user is never left with no browser), and the model is told
- it is signed out so it can say so rather than act as if the user's accounts were there."""
- return (f"{err} Using a fresh browser without the user's logins for this session instead; "
- "tell the user if the task needs their accounts.")
-
-
-def _real_profile_unsupported_reason(browser) -> Optional[str]:
- """Why the default browser's profile can't be used (the session falls back to a fresh browser), else None.
-
- A pre-release channel lives in a profile dir we don't resolve; normalizing to the stable
- family would drive a DIFFERENT profile/account (wrong-principal bug), so refuse rather than guess.
- """
- from hermes_cli.browser_connect import UNSUPPORTED_CHANNEL
- if browser is None:
- return (_RP + "your default browser is not a supported Chromium browser (Chrome, Edge, Brave, "
- "Brave Origin, Chromium). Real-profile browsing requires a Chromium default; set one or turn the toggle off.")
- if browser == UNSUPPORTED_CHANNEL:
- return (_RP + "your default browser is a pre-release Chromium channel (Beta / Dev / Canary), which "
- "real-profile browsing does not support. Set your default to a "
- "stable Chrome / Edge / Brave / Brave Origin / Chromium, or turn the toggle off.")
- return None
-
-
-def _real_profile_snapshot_error(err: str) -> str:
- """User-facing message for a failed profile snapshot; a locked profile adds the approved-close
- command, which the agent must ASK the user about first (it quits their browser)."""
- from hermes_cli.browser_connect import _PROFILE_LOCKED_PREFIX
- if err and err.startswith(_PROFILE_LOCKED_PREFIX):
- return (err[len(_PROFILE_LOCKED_PREFIX):] + " To close it (only after the user approves — it "
- "quits their browser and loses unsaved tabs), run: `hermes browser close-profile`; the next "
- "browser session then uses the profile.")
- return f"{_RP}{err}"
-
-
-def _launch_real_profile_chrome(real_binary: str, copy_dir: str) -> tuple[Optional[int], Optional[str]]:
- """Launch the user's REAL browser binary on the profile COPY; return (debug_port, error).
-
- agent-browser's own launch force-adds --use-mock-keychain / --password-store=basic, which makes
- macOS Chrome drop every keychain-encrypted cookie (signed-out copy); launching the real binary
- ourselves keeps the OS keychain path intact and agent-browser attaches via ``--cdp <port>``.
- Headless by default (a focus-stealing window defeats a background capability); Chrome's NEW
- headless shares the profile's cookie store (legacy --headless does not). browser.headed /
- AGENT_BROWSER_HEADED opts into a window, except on a display-less Linux host (launch would die).
- """
- _bt = _origin()
- try:
- os.unlink(os.path.join(copy_dir, "DevToolsActivePort")) # stale port confuses reuse probes
- except OSError:
- pass
- chrome_argv = [real_binary, f"--user-data-dir={copy_dir}", *_REAL_PROFILE_CHROME_FLAGS]
- _session._ensure_screen_for_headed_chromium()
- browser_env = _bt._build_browser_env() # carries the Bot Desktop DISPLAY when one is running
- _has_display = bool(browser_env.get("DISPLAY") or browser_env.get("WAYLAND_DISPLAY"))
- if not (_cloud._is_headed_mode() and (_has_display or not sys.platform.startswith("linux"))):
- chrome_argv.append("--headless=new")
- try:
- chrome_proc = subprocess.Popen(chrome_argv, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
- stdin=subprocess.DEVNULL, start_new_session=True, env=browser_env)
- except (subprocess.SubprocessError, OSError) as e:
- return None, f"{_RP}the launch failed: {e}"
- _bt._real_profile_chrome_procs.append(chrome_proc)
-
- deadline = time.monotonic() + 30.0
- while time.monotonic() < deadline:
- line = _read_devtools_port(copy_dir) or ""
- if line.isdigit():
- return int(line), None
- if chrome_proc.poll() is not None:
- _terminate_real_profile_chrome()
- return None, _RP + "Chrome exited during startup (another instance may hold the profile copy)."
- time.sleep(0.25)
- _terminate_real_profile_chrome()
- return None, _RP + "the real-profile browser did not expose a debug port in time. Retry, or turn the toggle off."
-
-
-def _attach_agent_browser_to_real_profile(port: int, copy_dir: str) -> tuple[Optional[str], Optional[str]]:
- """Make agent-browser ATTACH to the running Chrome (never launch its own); returns ``(http_cdp, error)``.
-
- The daemon may answer with the endpoint of a browser IT spawned (throwaway temp profile);
- the DevToolsActivePort OUR Chrome wrote is authoritative on disagreement.
- """
- _bt = _origin()
- try:
- browser_cmd = _install._find_agent_browser()
- except FileNotFoundError as e:
- return None, f"{_RP}the local browser engine (agent-browser) is not installed: {e}"
- argv = [*_session._agent_browser_argv(browser_cmd), "--session", _bt._REAL_PROFILE_SESSION,
- "--cdp", str(port), "open", "about:blank"]
- try:
- proc = _capture_agent_browser_cli(
- argv, timeout=_bt._get_open_command_timeout(first_open=True), tag="rp-open",
- )
- except subprocess.TimeoutExpired:
- return None, _RP + "the real-profile browser took too long to start. Retry, or turn the toggle off."
- except (subprocess.SubprocessError, OSError) as e:
- return None, f"{_RP}the launch failed: {e}"
- if proc.returncode != 0:
- tail = (proc.stderr or proc.stdout or "").strip().splitlines()
- return None, f"{_RP}the real-profile browser failed to start: {tail[-1] if tail else f'exit {proc.returncode}'}"
- cdp = _agent_browser_get_cdp(_bt._REAL_PROFILE_SESSION)
- our_port = _read_devtools_port(copy_dir)
- if our_port is not None and (m := re.search(r":(\d+)", cdp or "")) and m.group(1) != our_port:
- cdp = f"http://127.0.0.1:{our_port}"
- if not cdp:
- return None, _RP + "the real-profile browser started without exposing a devtools endpoint. Retry, or turn the toggle off."
- return cdp, None
-
-
-def _real_profile_cdp() -> tuple:
- """Resolve ``(cdp_url, error)`` for consented real-profile browsing.
-
- Snapshot -> launch real binary on the copy -> return its HTTP CDP endpoint. The copy is a
- non-default dir, so it sidesteps the Chrome >=136 default-profile remote-debugging block and
- never contends with the user's running browser. One shared agent-browser session is reused
- across calls (cached, re-validated). ``(None, message)`` when it can't (callers fall back to a fresh
- browser and report the message); ``(None, None)`` when consent is off.
- """
- _bt = _origin()
- if not _cloud._use_real_profile():
- # Consent is off: delete any snapshot store (copies of cookies/logins) so
- # revoking consent actually removes the credential copies.
- try:
- from hermes_cli.browser_connect import cleanup_real_profile_snapshots
- cleanup_real_profile_snapshots()
- except Exception as e:
- _bt.logger.debug("real-profile cleanup-on-consent-off failed: %s", e)
- _bt._real_profile_cdp_cache.pop("cdp", None)
- return None, None
-
- # Lightpanda rejects ``--profile``; check BEFORE default-browser detection so a
- # host with no Chromium default still reports the actionable engine conflict.
- if _lp._using_lightpanda_engine():
- return None, (_RP + "browser.engine is set to 'lightpanda', which cannot load a real Chromium profile. "
- "Set browser.engine to 'auto' or 'chrome' to use real-profile browsing, or turn the toggle off.")
-
- from hermes_cli.browser_connect import (chromium_executable, detect_default_chromium,
- real_profile_copy_dir, snapshot_real_profile)
-
- if not _bt._real_profile_cdp_lock.acquire(
- timeout=_bt._REAL_PROFILE_CDP_LOCK_TIMEOUT_S
- ):
- return None, (
- _RP + "the real-profile browser is already being prepared by another "
- "call that has not finished. Retry after that call completes, or "
- "restart Hermes if it was abandoned."
- )
- try:
- cached = _bt._real_profile_cdp_cache.get("cdp")
- if cached and _cdp_http_ready(cached):
- # Re-claim the shared daemon's socket dir so the orphan reaper's idle clock sees
- # this process still using it (a cache hit never runs a daemon command).
- _session._prepare_session_socket_dir(_bt._REAL_PROFILE_SESSION)
- return cached, None
- _bt._real_profile_cdp_cache.pop("cdp", None)
-
- browser = detect_default_chromium()
- unsupported = _real_profile_unsupported_reason(browser)
- if unsupported:
- return None, unsupported
-
- # Reuse BEFORE writing anything. CRITICAL: the snapshot overlay (truncates/rewrites
- # Cookies / Login Data) must NOT run while a live copy-browser (maybe from a previous
- # hermes process) holds the user-data-dir open — that corrupts the databases.
- copy_dir = real_profile_copy_dir(browser)
- existing = _agent_browser_get_cdp(_bt._REAL_PROFILE_SESSION)
- if existing and _cdp_http_ready(existing) and _cdp_on_data_dir(existing, copy_dir):
- _bt._real_profile_cdp_cache["cdp"] = existing
- return existing, None
- if existing: # stale/wrong-dir session: close it so nothing holds the dir open
- _agent_browser_close_session(_bt._REAL_PROFILE_SESSION)
- # A Chrome from an earlier hermes process can still hold the copy dir after its attach
- # daemon was reaped (that owner died). Re-attach to it rather than overlay a live profile;
- # if the daemon cannot attach, fail closed — never snapshot over an open profile. Not ours
- # to terminate (no Popen handle): it lives until the user closes it, by design.
- surviving = _surviving_chrome_cdp(copy_dir)
- if surviving:
- cdp, err = _attach_agent_browser_to_real_profile(int(surviving.rsplit(":", 1)[1]), copy_dir)
- if not cdp:
- return None, err
- _bt._real_profile_cdp_cache["cdp"] = cdp
- _bt.logger.info("real-profile: re-attached to surviving Chrome at %s (%s)", cdp, copy_dir)
- return cdp, None
-
- copy_dir, err = snapshot_real_profile(browser)
- if err or not copy_dir:
- return None, _real_profile_snapshot_error(err)
- real_binary = chromium_executable(browser)
- if real_binary is None:
- return None, f"{_RP}the real browser binary for '{browser}' could not be found. Reinstall it or turn the toggle off."
- port, err = _launch_real_profile_chrome(real_binary, copy_dir)
- if port is None:
- return None, err
- cdp, err = _attach_agent_browser_to_real_profile(port, copy_dir)
- if not cdp:
- return None, err
- _bt._real_profile_cdp_cache["cdp"] = cdp
- _bt.logger.info("real-profile browser ready for %s at %s (%s)", browser, cdp, copy_dir)
- return cdp, None
- finally:
- _bt._real_profile_cdp_lock.release()
diff --git a/tools/browser_tool_session.py b/tools/browser_tool_session.py
deleted file mode 100644
index 09e414471bb..00000000000
--- a/tools/browser_tool_session.py
+++ /dev/null
@@ -1,986 +0,0 @@
-"""agent-browser session management: daemon spawn, per-backend session creation
-(local/lightpanda/cdp/cloud), cached lookup, command execution + output interpretation.
-
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import base64
-import json
-import logging
-import os
-import shutil
-import subprocess
-import uuid
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
-
-from hermes_cli._subprocess_compat import windows_hide_flags
-from hermes_constants import hermes_home_key
-from tools.browser_tool_origin import origin as _bt
-from tools import browser_tool_cdp as _cdp
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_install as _install
-from tools import browser_tool_lifecycle as _lifecycle
-from tools import browser_tool_lightpanda_fallback as _lp
-from tools import browser_tool_real_profile as _real_profile
-from tools import browser_tool_snapshot as _snapshot
-
-_DOCKER_PULL = "docker pull ghcr.io/nousresearch/hermes-agent:latest"
-_CHROMIUM_INSTALL = "hermes pm install chromium (system libraries: npx playwright install-deps chromium)"
-_CHROMIUM_MISSING_DOCKER_HINT = ("Chromium browser is missing. You're running in Docker — pull the latest image "
- f"to get the bundled Chromium: {_DOCKER_PULL}")
-_CHROMIUM_MISSING_HINT = f"Chromium browser is missing. Install it with: {_CHROMIUM_INSTALL}"
-
-
-# THE Chromium startup flags for a host where its sandbox cannot work; agent-browser gets them through
-# AGENT_BROWSER_ARGS and the Bot Desktop dock's Browser icon (same binary, same profile) through
-# ``tools.bot_desktop.browser.dock_argv`` — one list, or the human's click dies while the agent's works.
-CHROMIUM_SANDBOX_BYPASS_ARGS = ("--no-sandbox", "--disable-dev-shm-usage")
-
-
-def apparmor_restricts_unprivileged_userns() -> bool:
- """Ubuntu 23.10+ default: unprivileged user namespaces are denied, so a Chromium whose
- ``chrome_sandbox`` helper is not setuid (Playwright's bundle) dies with 'No usable sandbox'."""
- try:
- with open("/proc/sys/kernel/apparmor_restrict_unprivileged_userns", encoding="utf-8") as f:
- return f.read().strip() == "1"
- except OSError:
- return False
-
-
-def _needs_chromium_sandbox_bypass() -> bool:
- """True when Chromium needs --no-sandbox to start reliably (root, Docker, AppArmor userns)."""
- if hasattr(os, "geteuid") and os.geteuid() == 0:
- return True
- if _install._running_in_docker():
- return True
- return apparmor_restricts_unprivileged_userns()
-
-
-def _apply_chromium_sandbox_args(browser_env: dict[str, str]) -> None:
- """Add required Chromium sandbox flags without overriding user settings."""
- if ("AGENT_BROWSER_ARGS" not in browser_env and "AGENT_BROWSER_CHROME_FLAGS" not in browser_env
- and _needs_chromium_sandbox_bypass()):
- _bt.logger.debug("browser: sandbox bypass needed (root/docker/AppArmor userns) — injecting --no-sandbox")
- browser_env["AGENT_BROWSER_ARGS"] = ",".join(CHROMIUM_SANDBOX_BYPASS_ARGS)
-
-
-def windows_headless_browser_options(browser_env: dict[str, str],
- is_windows: Optional[bool] = None) -> dict[str, str]:
- """(#64867) Pin local Chromium headless on Windows.
-
- Local mode is documented as zero-cost headless Chromium, but the agent-browser
- daemon inherits this env, and anything that resolves its ``--headed`` setting
- to a window (``--headed`` is agent-browser's documented boolean flag; this env
- var is its documented equivalent) turns a browser-tool turn into a blank
- top-level window over the Windows Desktop chat. Pure in ``(options, is_windows)``
- so the invariant is testable on any host; call sites pass nothing (they resolve
- ``os.name``) and skip non-Windows hosts entirely. Never overrides an explicit
- ``AGENT_BROWSER_HEADED`` — the opt-out stays the user's.
- """
- if is_windows is None:
- is_windows = os.name == "nt"
- if not is_windows or "AGENT_BROWSER_HEADED" in browser_env:
- return browser_env
- return {**browser_env, "AGENT_BROWSER_HEADED": "false"}
-
-
-def _read_command_output_files(stdout_path: str, stderr_path: str) -> tuple[str, str]:
- """Best-effort read of agent-browser stdout/stderr temp files."""
- out = []
- for path in (stdout_path, stderr_path):
- try:
- with open(path, "r", encoding="utf-8-sig") as f:
- out.append(f.read().strip())
- except OSError:
- out.append("")
- return out[0], out[1]
-
-
-def _unlink_command_output_files(*paths: str) -> None:
- for path in paths:
- try:
- os.unlink(path)
- except OSError:
- pass
-
-
-def _format_browser_timeout_error(
- command: str, timeout: int, stdout: str, stderr: str
-) -> str:
- """Actionable timeout message from captured daemon output."""
- parts = [f"Command timed out after {timeout} seconds"]
- detail = (stderr or stdout or "").strip()
- if detail:
- parts.append(detail[:1500])
-
- if "sandbox" in f"{stderr}\n{stdout}".lower():
- parts.append("Chromium sandbox launch failed. Set AGENT_BROWSER_ARGS="
- "'--no-sandbox,--disable-dev-shm-usage' in your environment, "
- "or run: npx playwright install-deps chromium")
- elif command == "open" and _cloud._is_local_mode():
- if _install._running_in_docker():
- parts.append("The browser daemon may still be starting or Chromium may be "
- f"missing. Pull the latest image: {_DOCKER_PULL}")
- else:
- parts.append("The browser daemon may still be starting, or Chromium may be "
- f"missing system libraries. Install/repair with: {_CHROMIUM_INSTALL}")
- return "\n".join(parts)
-
-
-def _agent_browser_argv(browser_cmd: str) -> list:
- """Keep the selected executable, including spaces, as one argv entry."""
- return [browser_cmd]
-
-
-def _shim_safe_args(argv0: str, command: str, args: list[str]) -> tuple[str, list[str], Optional[bytes]]:
- """``(spawn_command, spawn_args, stdin_payload)`` for one CLI command. Arguments that reach a
- ``.cmd``/``.bat`` shim (``npx.cmd``, npm's ``agent-browser.cmd`` on Windows) go through cmd.exe,
- which re-parses the child command line: a newline ends the argument and ``%VAR%`` expands even
- inside quotes, so a multi-line ``eval`` script arrives as its first line only (``SyntaxError:
- Unexpected end of input``) and multi-line ``fill`` text is truncated the same way. ``eval``
- scripts are sent base64-encoded (``agent-browser eval -b``); any other command whose argv carries
- a newline or ``%`` is wrapped as ``batch`` with the command as a JSON array on stdin — cmd.exe
- never sees the text (both forms present since the 0.26 floor). Every other spawn gets the raw
- argv and no stdin."""
- if not args or not argv0.lower().endswith((".cmd", ".bat")):
- return command, args, None
- if command == "eval":
- script, *rest = args
- return command, ["--base64", base64.b64encode(script.encode("utf-8")).decode("ascii"), *rest], None
- if command == "batch" or not any(ch in arg for arg in args for ch in "\r\n%"):
- return command, args, None
- return "batch", [], json.dumps([[command, *args]]).encode("utf-8")
-
-
-def _unwrap_batch_result(result: Any, command: str) -> dict[str, Any]:
- """``batch --json`` prints ``[{command, success, result, error}]``; reshape the single entry
- into the ``{success, data, error}`` dict every other command returns. Error dicts pass through."""
- if not isinstance(result, list):
- return result
- if len(result) != 1 or not isinstance(result[0], dict):
- return {"success": False, "error": f"Unexpected batch output for '{command}': {json.dumps(result)[:300]}"}
- entry = result[0]
- return {"success": bool(entry.get("success")), "data": entry.get("result"), "error": entry.get("error")}
-
-
-def _prepare_session_socket_dir(session_name: str) -> str:
- """Create the per-session socket dir (parallel workers must not share one) and claim it
- with our PID BEFORE first use — another hermes process's orphan reaper rmtree's any
- ownerless agent-browser-* dir in the shared tmpdir."""
- socket_dir = os.path.join(_bt._socket_safe_tmpdir(), f"agent-browser-{session_name}")
- os.makedirs(socket_dir, mode=0o700, exist_ok=True)
- _lifecycle._write_owner_pid(socket_dir, session_name)
- return socket_dir
-
-
-def _agent_browser_command_env(socket_dir: str) -> dict[str, str]:
- """Credential-scrubbed env for one command: PATH fallbacks, the session socket dir, and
- daemon-side idle self-termination (agent-browser 0.24+) mirroring the Python janitor
- unless the user set ``AGENT_BROWSER_IDLE_TIMEOUT_MS`` explicitly."""
- from pm import env_for
-
- env = _bt._build_browser_env()
- env["PATH"] = _install._merge_browser_path(env.get("PATH", ""))
- env = env_for("agent-browser", base_env=env)
- from hermes_cli.browser_runtime import chromium_executable
-
- executable = chromium_executable()
- if executable:
- env["AGENT_BROWSER_EXECUTABLE_PATH"] = executable
- env["AGENT_BROWSER_SOCKET_DIR"] = socket_dir
- if "AGENT_BROWSER_IDLE_TIMEOUT_MS" not in env:
- env["AGENT_BROWSER_IDLE_TIMEOUT_MS"] = str(_daemon_idle_timeout_seconds() * 1000)
- return env
-
-
-_SHARED_HEADED_DAEMON_IDLE_SECONDS = 24 * 3600
-
-
-def _daemon_idle_timeout_seconds() -> int:
- """The daemon's self-termination idle timer. The bot's headed Chromium on the Bot Desktop screen is
- shared with a human who may take the lease to log in: the agent is idle by definition then, so the
- daemon's own timer must not decide (it cannot see the lease); the lease-aware Python janitor owns that
- browser's lifetime, and a crashed hermes leaves it to the orphan reaper (#110064)."""
- if _cloud._is_headed_mode():
- from tools.bot_desktop.runtime import published_env
- if published_env().get("DISPLAY"):
- return _SHARED_HEADED_DAEMON_IDLE_SECONDS
- return _bt.BROWSER_SESSION_INACTIVITY_TIMEOUT
-
-
-def human_holds_shared_browser(session_info: dict[str, Any]) -> bool:
- """True while a human holds the Bot Desktop lease over the browser ``session_info`` shares with them.
- The janitor treats that as activity: reaping the browser mid-login is the human's session dying under
- them, not an idle agent's cleanup (#110064)."""
- if not _shares_bot_desktop_browser(session_info):
- return False
- from tools.bot_desktop import lease as _bd_lease
- return _bd_lease.human_holds()
-
-
-def _ensure_screen_for_headed_chromium() -> None:
- """Tool-call boundary for ``bot_desktop.auto_start`` (mirrors computer_use dispatch): a headed Chromium is
- about to be spawned for a real browser action, so a fresh headless profile gets its screen first. Headless
- browsing, Lightpanda and the env-only callers of ``_build_browser_env`` never bring one up."""
- if _cloud._is_headed_mode():
- from tools.bot_desktop.runtime import ensure_started_for_tool
- ensure_started_for_tool()
-
-
-def _popen_agent_browser(argv: list[str], env: dict[str, str], socket_dir: str, tag: str,
- stdin_payload: Optional[bytes] = None) -> subprocess.Popen:
- """Spawn agent-browser with stdout/stderr redirected to ``socket_dir/_std{out,err}_<tag>``;
- ``stdin_payload`` (a ``batch`` JSON body) is served from ``_stdin_<tag>`` the same way.
-
- Temp files, not pipes: the CLI forks a daemon that inherits its fds, so pipes never
- see EOF until the timeout. Windows: CREATE_NO_WINDOW only (CREATE_NEW_PROCESS_GROUP
- cancels asyncio's running task on 3.11), STARTF_USESTDHANDLES + close_fds so the child
- gets ONLY our three handles (leaked console handles kill the Rust daemon grandchild).
- """
- fds = [os.open(os.path.join(socket_dir, f"_{slot}_{tag}"), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
- for slot in ("stdout", "stderr")]
- stdin: Any = subprocess.DEVNULL
- if stdin_payload is not None:
- stdin_path = os.path.join(socket_dir, f"_stdin_{tag}")
- with open(stdin_path, "wb") as f:
- f.write(stdin_payload)
- fds.append(os.open(stdin_path, os.O_RDONLY))
- stdin = fds[-1]
- try:
- _popen_extra: dict = {}
- if os.name == "nt":
- _si = subprocess.STARTUPINFO()
- _si.dwFlags |= subprocess.STARTF_USESTDHANDLES
- _popen_extra = {"creationflags": windows_hide_flags(), "close_fds": True, "startupinfo": _si}
- return subprocess.Popen(argv, stdout=fds[0], stderr=fds[1], stdin=stdin, env=env, **_popen_extra)
- finally:
- for fd in fds:
- os.close(fd)
-
-
-def _session_record(prefix: str, cdp_url: Optional[str], features: dict[str, Any]) -> dict[str, Any]:
- """Fresh session dict with a random ``<prefix>_<hex10>`` session name."""
- return {"session_name": f"{prefix}_{uuid.uuid4().hex[:10]}", "bb_session_id": None,
- "cdp_url": cdp_url, "features": features}
-
-
-def real_profile_note(task_id: str) -> Optional[str]:
- """The real-profile fallback note on ``task_id``'s existing session; never creates or touches one."""
- with _bt._cleanup_lock:
- return (_bt._active_sessions.get(task_id) or {}).get("real_profile_unavailable")
-
-
-def _create_local_session(task_id: str, allow_real_profile: bool = True) -> dict[str, str]:
- """Local Chromium session; consented real-profile CDP attach when allowed.
-
- When the real profile can't be loaded (browser holding its cookies, non-Chromium default,
- launch failure) the session falls back to a fresh browser and carries the reason as
- ``real_profile_unavailable`` so the first navigation tells the model it is signed out. The
- hybrid private-URL sidecar passes ``allow_real_profile=False``: the user's cookie jar must
- not reach an arbitrary internal host the model chose.
- """
- fallback_note = None
- if allow_real_profile:
- cdp_url, err = _real_profile._real_profile_cdp()
- if err:
- _bt.logger.warning("real-profile unavailable for task %s, using a fresh browser: %s", task_id, err)
- fallback_note = _real_profile.real_profile_fallback_note(err)
- elif cdp_url:
- info = _session_record("rp", _cdp._resolve_cdp_override(cdp_url), {"local": True, "real_profile": True})
- _bt.logger.info("Created real-profile local session %s for task %s", info["session_name"], task_id)
- return info
-
- # Browser Use mode + ``browser.engine: lightpanda`` drives a Hermes-spawned
- # ``lightpanda serve`` (the built-in tools are hidden in that mode).
- if _bt._is_browser_use_cli_mode() and _lp._using_lightpanda_engine():
- info = _create_lightpanda_session(task_id)
- else:
- info = _session_record("h", None, {"local": True})
- _bt.logger.info("Created local browser session %s for task %s", info["session_name"], task_id)
- if fallback_note:
- info["real_profile_unavailable"] = fallback_note
- return info
-
-
-def _create_lightpanda_session(task_id: str) -> dict[str, Any]:
- """Spawn ``lightpanda serve`` for this session key (Browser Use mode)."""
- from tools.browser_lightpanda import launch_lightpanda
-
- info = _session_record("lp", None, {"local": True, "lightpanda": True})
- server, err = launch_lightpanda(info["session_name"], block_private_networks=not _cloud._is_local_backend())
- if err:
- raise RuntimeError(err)
- info["cdp_url"] = server.cdp_url
- _bt.logger.info("Created Lightpanda session %s (port %s) for task %s", info["session_name"], server.port, task_id)
- return info
-
-
-def _local_backend_process_dead(session_info: dict[str, Any]) -> bool:
- """True for a Lightpanda session whose ``lightpanda serve`` is gone."""
- if not (session_info.get("features") or {}).get("lightpanda"):
- return False
- from tools.browser_lightpanda import get_server
-
- server = get_server(session_info.get("session_name", ""))
- return server is None or not server.is_alive()
-
-
-def _create_cdp_session(task_id: str, cdp_url: str) -> dict[str, str]:
- """Session connecting to a user-supplied CDP endpoint."""
- info = _session_record("cdp", cdp_url, {"cdp_override": True})
- _bt.logger.info("Created CDP browser session %s → %s for task %s",
- info["session_name"], _bt._sanitize_url_for_logs(cdp_url), task_id)
- return info
-
-
-def _create_cloud_session_or_fallback(task_id: str, provider) -> dict[str, Any]:
- """Cloud session; fall back to local Chromium (marked degraded) on failure. ``cdp_url``
- is resolved here because some providers return an HTTP discovery URL, not a websocket."""
- try:
- session_info = provider.create_session(task_id)
- if not session_info or not isinstance(session_info, dict):
- raise ValueError(f"Cloud provider returned invalid session: {session_info!r}")
- if session_info.get("cdp_url"):
- session_info = dict(session_info)
- session_info["cdp_url"] = _cdp._resolve_cdp_override(str(session_info["cdp_url"]))
- return session_info
- except Exception as e:
- provider_name = type(provider).__name__
- _bt.logger.warning("Cloud provider %s failed (%s); attempting fallback to local Chromium for task %s",
- provider_name, e, task_id, exc_info=True)
- try:
- session_info = _create_local_session(task_id)
- except Exception as local_error:
- raise RuntimeError(f"Cloud provider {provider_name} failed ({e}) and local "
- f"fallback also failed ({local_error})") from e
- if isinstance(session_info, dict): # mark degraded for observability
- session_info = {**session_info, "fallback_from_cloud": True, "fallback_reason": str(e),
- "fallback_provider": provider_name}
- return session_info
-
-
-def _create_session_for_key(task_id: str, force_local: bool) -> dict[str, Any]:
- """Fresh session for ``task_id`` (runs OUTSIDE the lock: cloud mode makes a network call).
- Precedence: CDP override > hybrid local sidecar (never real-profile) > cloud > local."""
- cdp_override = _cdp._get_cdp_override()
- if cdp_override and not force_local:
- return _create_cdp_session(task_id, cdp_override)
- if force_local:
- return _create_local_session(task_id, allow_real_profile=False)
- provider = _cloud._get_cloud_provider()
- if provider is None:
- return _create_local_session(task_id)
- return _create_cloud_session_or_fallback(task_id, provider)
-
-
-# A session built while its profile published a new live endpoint is closed and rebuilt; bounded so a
-# flapping connect/disconnect loop cannot keep a tool call building browsers forever.
-_STALE_ENDPOINT_RETRIES = 2
-
-
-def _get_session_info(task_id: Optional[str] = None) -> dict[str, Any]:
- """Get or create session info for a session key (thread-safe); also starts the
- inactivity thread and touches activity. A ``::local`` key forces local Chromium
- even with a cloud provider configured."""
- if task_id is None:
- task_id = "default"
-
- _lifecycle._start_browser_cleanup_thread()
- _lifecycle._update_session_activity(task_id)
-
- with _bt._cleanup_lock:
- existing_session = _bt._active_sessions.get(task_id)
-
- def _replacement_after_teardown() -> Optional[dict[str, Any]]:
- # Teardown removes the activity entry; re-touch so the reaper tracks the
- # replacement. Another thread may already have re-created it — reuse that.
- _lifecycle._update_session_activity(task_id)
- with _bt._cleanup_lock:
- replacement = _bt._active_sessions.get(task_id)
- return replacement if replacement is not None and replacement is not existing_session else None
-
- if existing_session is not None:
- # Suspect recycle: a command timeout marked this session; the expensive recycle
- # lives here at next use, not on the timeout path (mark must stay cheap).
- if not _bt._browser_session_backend(task_id).ensure_healthy():
- replacement = _replacement_after_teardown()
- if replacement is not None:
- return replacement
- existing_session = None
- elif not _lifecycle._session_has_expired(existing_session) and not _local_backend_process_dead(existing_session):
- return existing_session
- else:
- _bt.logger.info("Replacing expired or dead browser session for task %s", task_id)
- _lifecycle._cleanup_single_browser_session(task_id)
- replacement = _replacement_after_teardown()
- if replacement is not None:
- return replacement
-
- force_local = _bt._is_local_sidecar_key(task_id)
- home_key = hermes_home_key()
- for attempt in range(_STALE_ENDPOINT_RETRIES + 1):
- generation = _cdp.live_cdp_generation(home_key)
- session_info = _create_session_for_key(task_id, force_local)
- with _bt._cleanup_lock:
- if task_id in _bt._active_sessions: # created concurrently during the network call — don't leak ours
- return _bt._active_sessions[task_id]
- # This profile published a new live endpoint while ours was being created: it may have
- # resolved the old one after /browser connect's second reap. Never publish it (a concurrent
- # caller would be handed a browser being closed); close it by object and build again.
- stale = _cdp.live_cdp_generation(home_key) != generation
- if not stale or attempt == _STALE_ENDPOINT_RETRIES:
- session_info = dict(session_info)
- session_info.setdefault("session_key", task_id)
- session_info.setdefault("owner_task_id", _bt._bare_task_id_for_session_key(task_id))
- session_info.setdefault("home_key", home_key) # the profile reaped on /browser connect
- _bt._active_sessions[task_id] = session_info
- _bt._suspect_browser_sessions.pop(task_id, None) # brand-new session is healthy by definition
- break
- _bt.logger.info("Browser endpoint changed during session creation for %s; recreating", task_id)
- _close_unpublished_session(task_id, session_info)
-
- # Lazy-start the CDP supervisor (idempotent). Skip local sidecars (no CDP URL) and
- # Lightpanda sessions (Browser Use mode hides the tools that consume supervisor state).
- if not force_local and not (session_info.get("features") or {}).get("lightpanda"):
- _cdp._ensure_cdp_supervisor(task_id)
-
- return session_info
-
-
-def _close_unpublished_session(task_id: str, session_info: dict[str, Any]) -> None:
- """Close a session that was never put in ``_active_sessions``, by object: its backend ``close``
- and resources only, never a lookup by key (that entry, if any, is another caller's session)."""
- if (session_info.get("features") or {}).get("lightpanda"): # no daemon to ``close``
- from tools.browser_lightpanda import stop_lightpanda
- stop_lightpanda(session_info.get("session_name", ""))
- else:
- preflight = _browser_command_preflight()
- if "browser_cmd" in preflight:
- run_fenced_pair(session_info, lambda: _dispatch_browser_command(
- task_id, session_info, preflight["browser_cmd"], "close", [], 10, None))
- _lifecycle._release_session_backend(task_id, session_info)
-
-
-def _discard_timed_out_browser_session(task_id: str, session_info: dict[str, Any], task_socket_dir: str) -> None:
- """Drop a stuck client generation without losing cloud cleanup state."""
- with _bt._cleanup_lock:
- if _bt._active_sessions.get(task_id) is not session_info:
- return
- _cdp._stop_cdp_supervisor(task_id)
- if session_info.get("bb_session_id") or session_info.get("cdp_url"):
- replacement = dict(session_info)
- replacement["session_name"] = f"h_{uuid.uuid4().hex[:10]}"
- replacement.pop("_first_nav", None)
- _bt._active_sessions[task_id] = replacement
- else:
- _bt._active_sessions.pop(task_id, None)
- _bt._session_last_activity.pop(task_id, None)
-
- bare_task_id = _bt._bare_task_id_for_session_key(task_id)
- if _bt._last_active_session_key.get(bare_task_id) == task_id:
- _bt._last_active_session_key.pop(bare_task_id, None)
-
- session_name = str(session_info.get("session_name") or "")
- if session_name and os.path.isfile(os.path.join(task_socket_dir, f"{session_name}.pid")):
- daemon_pid = _read_browser_daemon_pid(task_socket_dir, session_name)
- if daemon_pid is None: # corrupt pid file
- _bt.logger.debug("Could not kill timed-out browser daemon for %s", session_name)
- return
- if not _lifecycle._verify_reapable_browser_daemon(daemon_pid, task_socket_dir, session_name):
- return
- try:
- # Tree-kill: terminating only the daemon PID leaks the Chromium tree.
- # See #68139.
- from agent import deadline as _deadline
-
- _deadline.kill_process_tree(daemon_pid)
- except (ProcessLookupError, PermissionError, OSError):
- _bt.logger.debug("Could not kill timed-out browser daemon for %s", session_name)
- return
- shutil.rmtree(task_socket_dir, ignore_errors=True)
-
-
-def _read_browser_daemon_pid(task_socket_dir: str, session_name: str) -> Optional[int]:
- """Read the agent-browser daemon PID for a session (best-effort)."""
- pid_file = os.path.join(task_socket_dir, f"{session_name}.pid")
- try:
- return int(Path(pid_file).read_text(encoding="utf-8-sig").strip())
- except (OSError, ValueError):
- return None
-
-
-def _browser_daemon_responsive(task_socket_dir: str, probe_timeout_s: float = 1.0) -> bool:
- """Cheap liveness probe: a connect to the daemon's unix control socket proves the accept
- loop is alive (the command wedged page/CDP-side). Windows named pipes can't be probed →
- report unresponsive (tree-kill + respawn is the safe recovery)."""
- if os.name == "nt":
- return False
- import socket as socket_mod
-
- if not hasattr(socket_mod, "AF_UNIX"):
- return False
- try:
- entries = os.listdir(task_socket_dir)
- except OSError:
- return False
- for entry in (e for e in entries if e.endswith(".sock")):
- try:
- with socket_mod.socket(socket_mod.AF_UNIX, socket_mod.SOCK_STREAM) as s:
- s.settimeout(probe_timeout_s)
- s.connect(os.path.join(task_socket_dir, entry))
- return True
- except OSError:
- continue
- return False
-
-
-def _handle_browser_command_timeout(task_id: str, session_info: dict[str, Any], task_socket_dir: str) -> None:
- """Recover session state after a command timeout.
-
- Cloud/CDP: no daemon to probe — replace the stuck client generation now (same
- ``bb_session_id`` so cloud cleanup works). Local: ``_recycle_local_session``.
- See #68139, #72205, #72206.
- """
- if session_info.get("bb_session_id") or session_info.get("cdp_url"):
- _discard_timed_out_browser_session(task_id, session_info, task_socket_dir)
- return
- _recycle_local_session(task_id, session_info, task_socket_dir, "browser command timed out; session may be poisoned")
-
-
-def _recycle_local_session(task_id: str, session_info: dict[str, Any], task_socket_dir: str, reason: str) -> None:
- """Stop handing out a poisoned local session record (timeout or protocol-level failure).
-
- Daemon alive (PID live, verified as ours, control socket accepts): only the *command*
- wedged — mark suspect, recycle at next use through ``ensure_healthy``. Daemon wedged or
- dead: tree-kill and evict now (Chromium children would leak). Both branches
- ``mark_suspect`` first so the poisoned-cache invariant holds even if eviction races
- another thread's replacement.
- """
- _bt._browser_session_backend(task_id).mark_suspect(reason)
-
- session_name = str(session_info.get("session_name") or "")
- if _browser_in_sandbox():
- # The daemon lives in the sandbox: no host pid, no host socket. Ask the CLI there to close it, evict the record.
- _sandbox_close_daemon(session_name)
- with _bt._cleanup_lock:
- if _bt._active_sessions.get(task_id) is session_info:
- _bt._active_sessions.pop(task_id, None)
- _bt._session_last_activity.pop(task_id, None)
- _bt._suspect_browser_sessions.pop(task_id, None)
- return
- daemon_pid = _read_browser_daemon_pid(task_socket_dir, session_name) if session_name else None
- daemon_alive = (
- daemon_pid is not None
- and _lifecycle._pid_exists(daemon_pid)
- and _lifecycle._verify_reapable_browser_daemon(daemon_pid, task_socket_dir, session_name)
- and _browser_daemon_responsive(task_socket_dir)
- )
- if daemon_alive:
- _bt.logger.warning("browser daemon for %s is alive (%s); session marked suspect and will be "
- "recycled at next use", task_id, reason)
- return
-
- _bt.logger.warning("browser daemon for %s is wedged or dead (%s); tree-killing and evicting the session",
- task_id, reason)
- _discard_timed_out_browser_session(task_id, session_info, task_socket_dir)
- # The poisoned entry is gone either way; the flag must not poison a session
- # created later under the same key.
- _bt._suspect_browser_sessions.pop(task_id, None)
-
-
-def _sandbox_close_daemon(session_name: str) -> None:
- """``agent-browser --session <name> close`` inside the sandbox (best effort; the daemon's own idle timer and
- the sandbox's lifetime bound it otherwise)."""
- from tools.bot_desktop import runtime as _bd_runtime, sandbox_host
- from tools.environments import streams
- env = _bd_runtime._sandbox_env(create=False)
- if env is None or not session_name:
- return
- try:
- streams.run_in(env, [_SANDBOX_AGENT_BROWSER, "--session", session_name, "close"],
- child_env={"AGENT_BROWSER_SOCKET_DIR": _sandbox_socket_dir(env)}, user=sandbox_host._user_for(env),
- timeout=15)
- except (OSError, subprocess.SubprocessError) as exc:
- _bt.logger.debug("sandbox browser close for %s failed: %s", session_name, exc)
-
-
-def _sandbox_socket_dir(env) -> str:
- from tools.environments import streams
- return f"{streams.sandbox_temp_dir(env).rstrip('/')}/hermes-bot-desktop/agent-browser"
-
-
-def sandbox_screenshot_path(host_path: Path) -> Optional[str]:
- """Where the sandboxed CLI should write a screenshot (its own tmp), or None on a gateway-hosted browser."""
- if not _browser_in_sandbox():
- return None
- from tools.bot_desktop import runtime as _bd_runtime
- env = _bd_runtime._sandbox_env(create=False)
- if env is None:
- return None
- from tools.environments import streams
- return f"{streams.sandbox_temp_dir(env).rstrip('/')}/hermes-bot-desktop/shots/{host_path.name}"
-
-
-def fetch_sandbox_file(remote_path: str, local_dest: Path, *, max_bytes: int = 16 * 1024 * 1024) -> bool:
- """Copy a file the sandboxed browser wrote (a screenshot) to the host; False when not in sandbox mode."""
- if not _browser_in_sandbox():
- return False
- from tools.bot_desktop import runtime as _bd_runtime
- env = _bd_runtime._sandbox_env(create=False)
- if env is None:
- return False
- env.fetch_file(remote_path, local_dest, max_bytes=max_bytes)
- return True
-
-
-def _is_recoverable_local_backend_failure(session_info: dict[str, Any], result: dict[str, Any]) -> bool:
- """True when a finished command failed at the agent-browser level — nonzero exit (101 =
- the CLI panicked against a stale session daemon), or empty/non-JSON output from a dead
- daemon — on a plain local Chromium session. Parsed-JSON failures carry no ``returncode``
- (the backend answered; the page said no) and must not recycle; cloud/CDP/real-profile/
- Lightpanda sessions have their own recovery (#115184)."""
- feats = session_info.get("features") or {}
- if not feats.get("local") or feats.get("lightpanda") or feats.get("real_profile"):
- return False
- if session_info.get("cdp_url") or session_info.get("bb_session_id"):
- return False
- return result.get("returncode") is not None and not result.get("success")
-
-
-def _interpret_browser_command_output(command: str, stdout: str, stderr: str, returncode: int) -> dict[str, Any]:
- """Finished agent-browser process output → result dict. Empty stdout with rc=0 is a
- broken state (stale daemon) reported as failure except for ``_EMPTY_OK_COMMANDS``;
- non-JSON output is an error except ``screenshot``, whose path is recovered from prose."""
- if stderr and stderr.strip():
- level = logging.WARNING if returncode != 0 else logging.DEBUG
- _bt.logger.log(level, "browser '%s' stderr: %s", command, stderr.strip()[:500])
-
- stdout_text = stdout.strip()
- if not stdout_text:
- if returncode != 0:
- error_msg = stderr.strip() if stderr else f"Command failed with code {returncode}"
- _bt.logger.warning("browser '%s' failed (rc=%s): %s", command, returncode, error_msg[:300])
- return {"success": False, "error": error_msg, "returncode": returncode}
- if command not in _bt._EMPTY_OK_COMMANDS:
- _bt.logger.warning("browser '%s' returned empty output (rc=0)", command)
- return {"success": False, "error": f"Browser command '{command}' returned no output", "returncode": returncode}
- return {"success": True, "data": {}}
-
- try:
- parsed = json.loads(stdout_text)
- except json.JSONDecodeError:
- raw = stdout_text[:2000]
- _bt.logger.warning("browser '%s' returned non-JSON output (rc=%s): %s", command, returncode, raw[:500])
- if command == "screenshot":
- combined_text = "\n".join(part for part in [stdout_text, (stderr or "").strip()] if part)
- recovered_path = _snapshot._extract_screenshot_path_from_text(combined_text)
- if recovered_path and Path(recovered_path).exists():
- _bt.logger.info("browser 'screenshot' recovered file from non-JSON output: %s", recovered_path)
- return {"success": True, "data": {"path": recovered_path, "raw": raw}}
- return {"success": False, "error": f"Non-JSON output from agent-browser for '{command}': {raw}", "returncode": returncode}
-
- # Empty snapshot content is a common sign of daemon/CDP issues.
- if command == "snapshot" and parsed.get("success"):
- snap_data = parsed.get("data", {})
- if not snap_data.get("snapshot") and not snap_data.get("refs"):
- _bt.logger.warning("snapshot returned empty content. Possible stale daemon or CDP connection issue. "
- "returncode=%s", returncode)
- return parsed
-
-
-_SANDBOX_AGENT_BROWSER = "agent-browser" # the CLI baked into nousresearch/hermes-sandbox:desktop
-_SANDBOX_ENV_KEYS = ("AGENT_BROWSER_SOCKET_DIR", "AGENT_BROWSER_IDLE_TIMEOUT_MS", "AGENT_BROWSER_ARGS",
- "AGENT_BROWSER_PROFILE", "AGENT_BROWSER_EXECUTABLE_PATH", "AGENT_BROWSER_HEADED",
- "DISPLAY", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "ANONYMIZED_TELEMETRY", "TMPDIR")
-
-
-def _browser_in_sandbox() -> bool:
- """The bot's browser runs INSIDE the terminal backend when its screen is PLACED there (policy, not
- liveness: same Chromium a human takes over in the pane, same profile, and the host is never touched by a
- page the model chose — whether or not the screen happens to be up right now). ``_browser_command_preflight``
- is where the screen is brought up or the command refused."""
- from tools.bot_desktop import placement
- return placement.resolve().where == placement.TERMINAL
-
-
-def _sandbox_wrap(cmd_parts: list[str], browser_env: dict[str, str], task_socket_dir: str) -> tuple[list[str], dict[str, str]]:
- """Rewrite one agent-browser invocation to run inside the sandbox: exec prefix + the CLI by name, with the
- browser-relevant variables exported there (the daemon's socket dir mirrors the host path so the host-side
- liveness probes keep their shape) and a screen-published DISPLAY. Identity on a gateway-hosted screen."""
- if not _browser_in_sandbox():
- return cmd_parts, browser_env
- from tools.bot_desktop import runtime as _bd_runtime, sandbox_host
- from tools.environments import streams
- env = _bd_runtime._sandbox_env(create=True)
- if env is None:
- raise RuntimeError("the terminal backend's sandbox is not running, so there is nowhere to run the browser")
- published = _bd_runtime.published_env()
- if not published.get("DISPLAY"):
- # The sandbox died under a live screen (container removed, ssh host rebooted). Fail here rather than
- # let a DISPLAY-less agent-browser run headless inside a dead sandbox or, worse, fall back to the host.
- raise RuntimeError("the screen inside the terminal backend's sandbox is gone; start it again")
- remote_env = {k: v for k, v in browser_env.items() if k in _SANDBOX_ENV_KEYS}
- remote_env.update(published)
- remote_env["AGENT_BROWSER_SOCKET_DIR"] = _sandbox_socket_dir(env)
- remote_env.pop("AGENT_BROWSER_EXECUTABLE_PATH", None) # the sandbox image's Playwright Chromium, not a host path
- remote_env["AGENT_BROWSER_PROFILE"] = sandbox_host.browser_profile_dir(env) # persists with the container, not its tmpfs
- remote_env["TMPDIR"] = streams.sandbox_temp_dir(env)
- if not getattr(env, "_bd_browser_dirs_ready", False):
- streams.run_in(env, ["mkdir", "-p", _sandbox_socket_dir(env), f"{remote_env['TMPDIR'].rstrip('/')}/hermes-bot-desktop/shots",
- remote_env["AGENT_BROWSER_PROFILE"]], user=sandbox_host._user_for(env), timeout=15)
- env._bd_browser_dirs_ready = True
- remote_env["AGENT_BROWSER_ARGS"] = ",".join(CHROMIUM_SANDBOX_BYPASS_ARGS) # container: no userns for Chromium's own sandbox
- # cmd_parts = <agent-browser argv0 (+npx spec)> + backend args + command; keep everything after argv0.
- tail = cmd_parts[len(_agent_browser_argv(cmd_parts[0])):]
- wrapped = streams.remote_command(env, [_SANDBOX_AGENT_BROWSER, *tail], child_env=remote_env,
- user=sandbox_host._user_for(env), interactive=True)
- if wrapped is None:
- raise RuntimeError(f"{type(env).__name__} cannot host the browser")
- host_env = {"PATH": browser_env.get("PATH", os.environ.get("PATH", "")), "HOME": os.environ.get("HOME", "")}
- return wrapped, host_env
-
-
-def _browser_command_preflight() -> dict[str, Any]:
- """Fail fast before spawning (missing CLI, Termux gap, interrupt, no Chromium in local
- mode — else every call hangs for command_timeout). Error result, or ``{"browser_cmd": path}``."""
- from tools.bot_desktop import placement, runtime as _bd_runtime
- try:
- where = _bd_runtime.tool_placement() # starts the sandbox screen on demand; raises for refused / down
- except RuntimeError as e:
- return {"success": False, "error": f"The browser cannot run here: {e}"}
- if where == placement.TERMINAL:
- from tools.interrupt import is_interrupted
- if is_interrupted():
- return {"success": False, "error": "Interrupted"}
- return {"browser_cmd": _SANDBOX_AGENT_BROWSER} # resolved inside the sandbox, not on this host
- try:
- browser_cmd = _install._find_agent_browser()
- except FileNotFoundError as e:
- _bt.logger.warning("agent-browser CLI not found: %s", e)
- return {"success": False, "error": str(e)}
-
- # Skip when engine=lightpanda — LP doesn't need Chromium for navigation.
- if (
- _cloud._is_local_mode()
- and not _install._chromium_installed()
- and _cloud._get_browser_engine() != "lightpanda"
- and not _install._maybe_autoinstall_chromium()
- ):
- hint = _CHROMIUM_MISSING_DOCKER_HINT if _install._running_in_docker() else _CHROMIUM_MISSING_HINT
- _bt.logger.warning("browser command blocked: %s", hint)
- return {"success": False, "error": hint}
-
- from tools.interrupt import is_interrupted
- if is_interrupted():
- return {"success": False, "error": "Interrupted"}
- return {"browser_cmd": browser_cmd}
-
-
-def _spawn_and_collect(
- task_id: str, session_info: dict[str, Any], cmd_parts: list[str],
- command: str, engine: str, timeout: int, stdin_payload: Optional[bytes] = None,
-) -> dict[str, Any]:
- """Run the prepared agent-browser argv once and interpret its output (handles timeout)."""
- task_socket_dir = _prepare_session_socket_dir(session_info["session_name"])
- _bt.logger.debug("browser cmd=%s task=%s socket_dir=%s (%d chars)",
- command, task_id, task_socket_dir, len(task_socket_dir))
- if engine != "lightpanda":
- _ensure_screen_for_headed_chromium() # first command forks the daemon; a headed window needs the screen up
- browser_env = _agent_browser_command_env(task_socket_dir)
-
- # Lightpanda rejects Chromium-only launch flags: strip current and legacy vars;
- # Chrome commands and fallback use the shared Chromium policy.
- if engine == "lightpanda":
- stripped = [browser_env.pop(k, None) for k in ("AGENT_BROWSER_ARGS", "AGENT_BROWSER_CHROME_FLAGS")]
- if any(v is not None for v in stripped):
- _bt.logger.debug("browser: stripped Chromium-only AGENT_BROWSER_ARGS/AGENT_BROWSER_CHROME_FLAGS "
- "for Lightpanda command %s (agent-browser rejects them with --engine lightpanda)",
- command)
- else:
- _apply_chromium_sandbox_args(browser_env)
- # #64867: a local Chromium launch (no --cdp attach) must stay headless on
- # Windows; headed mode is the intentional opt-out (dispatch adds --headed).
- if not session_info.get("cdp_url") and not _cloud._is_headed_mode():
- browser_env = windows_headless_browser_options(browser_env)
-
- stdout_path = os.path.join(task_socket_dir, f"_stdout_{command}")
- stderr_path = os.path.join(task_socket_dir, f"_stderr_{command}")
- cmd_parts, browser_env = _sandbox_wrap(cmd_parts, browser_env, task_socket_dir)
- proc = _popen_agent_browser(cmd_parts, browser_env, task_socket_dir, command, stdin_payload)
-
- try:
- proc.wait(timeout=timeout)
- except subprocess.TimeoutExpired:
- proc.kill()
- proc.wait()
- stdout, stderr = _read_command_output_files(stdout_path, stderr_path)
- _unlink_command_output_files(stdout_path, stderr_path)
- _handle_browser_command_timeout(task_id, session_info, task_socket_dir)
- if stderr and stderr.strip():
- _bt.logger.warning("browser '%s' stderr after timeout: %s", command, stderr.strip()[:500])
- _bt.logger.warning("browser '%s' timed out after %ds (task=%s, socket_dir=%s)",
- command, timeout, task_id, task_socket_dir)
- return {"success": False, "error": _format_browser_timeout_error(command, timeout, stdout, stderr)}
- with open(stdout_path, "r", encoding="utf-8-sig") as f:
- stdout = f.read()
- with open(stderr_path, "r", encoding="utf-8-sig") as f:
- stderr = f.read()
- _unlink_command_output_files(stdout_path, stderr_path)
- return _interpret_browser_command_output(command, stdout, stderr, proc.returncode)
-
-
-def run_fenced(session_info: dict[str, Any], fn: Callable[[], dict[str, Any]]) -> dict[str, Any]:
- """Run ``fn`` under the Bot Desktop lease fence when ``session_info`` is the bot's LOCAL browser.
-
- That browser lives on the Bot Desktop screen, in the same profile a human who took over is typing
- into. While the human holds the lease every action AND read against it is refused (the page may show
- their credential); the fence brackets the whole run so a takeover mid-command also voids the result.
- Cloud / user-supplied CDP sessions are a different browser and run unfenced. This is THE fence: every
- path that reaches the page (agent-browser subprocess, CDP supervisor fast path) goes through here.
- """
- if not _shares_bot_desktop_browser(session_info):
- return fn()
- from tools.bot_desktop import lease as _bd_lease
- try:
- admitted = _bd_lease.assert_agent_may_act()
- except _bd_lease.HumanHasControl as e:
- return {"success": False, "error": str(e), "code": "human_has_control"}
- result = fn()
- if _bd_lease.get().epoch != admitted.epoch:
- return {"success": False, "code": "human_has_control",
- "error": "A human took over the bot's screen while this browser command ran; its result was "
- "discarded. Tell the user what you need; retry once they hand back."}
- return result
-
-
-def run_fenced_pair(session_info: dict[str, Any], fn: Callable[[], tuple[str, dict[str, Any]]]) -> tuple[str, dict[str, Any]]:
- """``run_fenced`` for the dispatch shape ``(engine, result)``; a refusal carries no engine (never ran)."""
- engine_box: list = []
-
- def _call() -> dict[str, Any]:
- engine, result = fn()
- engine_box.append(engine)
- return result
-
- result = run_fenced(session_info, _call)
- return (engine_box[0] if engine_box else "auto"), result
-
-
-def _shares_bot_desktop_browser(session_info: dict[str, Any]) -> bool:
- """Decided by provenance, not transport: every LOCAL session (plain ``--session``, real-profile CDP
- attach, Lightpanda) is a browser Hermes launched with this profile's Bot Desktop DISPLAY, so it is the
- screen a human who took over is typing into. Cloud / user-supplied CDP sessions are another browser.
- A human lease with the screen already gone (dead Xvnc) still fences — computer_use does the same."""
- if not (session_info.get("features") or {}).get("local"):
- return False
- from tools.bot_desktop import lease as _bd_lease, runtime as _bd_runtime
- return bool(_bd_runtime.published_env().get("DISPLAY")) or _bd_lease.human_holds()
-
-
-def _bot_desktop_attach_port(session_info: dict[str, Any]) -> Optional[int]:
- """DevTools port of a human-started Chromium on the Bot Desktop's shared profile, else ``None``."""
- if not _shares_bot_desktop_browser(session_info):
- return None
- from tools.bot_desktop import browser as _bd_browser
- return _bd_browser.running_instance_cdp_port(str(_bd_browser.profile_dir()),
- exclude_session=session_info["session_name"])
-
-
-def _dispatch_browser_command(
- task_id: str, session_info: dict[str, Any], browser_cmd: str, command: str, args: list[str],
- timeout: int, _engine_override: Optional[str],
-) -> tuple[str, dict[str, Any]]:
- """Build the agent-browser argv for ``session_info`` and run it once → ``(engine, result)``."""
- # Cleanup stops the supervisor before closing the backend; keep it stopped.
- if command != "close" and session_info.get("cdp_url"):
- _cdp._ensure_cdp_supervisor(task_id)
-
- # Every backend runs in this task's own daemon (``--session <name>``); Cloud/CDP adds
- # ``--cdp <ws_url>`` to attach it to the remote browser. Without --session every CDP task
- # shared agent-browser's default daemon, so one task's snapshot refs or close hit the others.
- # Engine injection keys off the resolved session backend, not global provider
- # state: hybrid routing can create a local sidecar while a cloud provider stays configured.
- engine = _engine_override or _cloud._get_browser_engine()
- backend_args = ["--session", session_info["session_name"]]
- if session_info.get("cdp_url"):
- backend_args += ["--cdp", session_info["cdp_url"]]
- else:
- if (bd_port := _bot_desktop_attach_port(session_info)) is not None:
- # A Chromium already runs on the Bot Desktop's shared profile (the human clicked the dock's
- # Browser first): a launch would be forwarded into it by Chromium's singleton and die without
- # a DevTools endpoint, so the session's daemon attaches to the port it advertises instead.
- # Same daemon (keyed by --session) either way, so snapshot refs stay valid across commands.
- backend_args += ["--cdp", str(bd_port)]
- if _cloud._is_headed_mode():
- backend_args.append("--headed")
- if engine != "auto" and not _bt._is_camofox_mode():
- backend_args += ["--engine", engine]
-
- argv = _agent_browser_argv(browser_cmd)
- spawn_command, spawn_args, stdin_payload = _shim_safe_args(argv[0], command, args)
- cmd_parts = argv + backend_args + ["--json", spawn_command] + spawn_args
-
- try:
- result = _unwrap_batch_result(
- _spawn_and_collect(task_id, session_info, cmd_parts, command, engine, timeout, stdin_payload), command)
- except Exception as e:
- _bt.logger.warning("browser '%s' exception: %s", command, e, exc_info=True)
- result = {"success": False, "error": str(e)}
- return engine, result
-
-
-def _run_browser_command(
- task_id: str,
- command: str,
- args: list[str] | None = None,
- timeout: Optional[int] = None,
- _engine_override: Optional[str] = None,
-) -> dict[str, Any]:
- """Run one agent-browser CLI command against the task's session; returns its parsed JSON.
- ``timeout=None`` reads ``browser.command_timeout``; ``_engine_override`` forces an engine
- for this call only (Lightpanda fallback retries with Chrome without touching global state)."""
- if timeout is None:
- timeout = _bt._safe_command_timeout()
- args = args or []
-
- preflight = _browser_command_preflight()
- if "browser_cmd" not in preflight:
- return preflight
- browser_cmd = preflight["browser_cmd"]
-
- for attempt in range(2):
- try:
- session_info = _get_session_info(task_id)
- except Exception as e:
- _bt.logger.warning("Failed to create browser session for task=%s: %s", task_id, e)
- return {"success": False, "error": f"Failed to create browser session: {e!s}"}
- engine, result = run_fenced_pair(session_info, lambda: _dispatch_browser_command(
- task_id, session_info, browser_cmd, command, args, timeout, _engine_override))
- if result.get("code") == "human_has_control":
- return result
- # #115184: a protocol-level failure (exit 101 on a stale session daemon, empty/non-JSON
- # output) poisons the cached local session record exactly like a timeout — recycle it
- # the same way and retry once on the replacement before handing the caller the error.
- # ``close`` is exempt: a dead daemon is already closed, and cleanup must never spawn
- # a fresh session just to close it.
- if attempt == 0 and command != "close" and _is_recoverable_local_backend_failure(session_info, result):
- _bt.logger.warning("browser '%s' failed at the backend level (task=%s, rc=%s); recycling the session "
- "and retrying once", command, task_id, result.get("returncode"))
- _recycle_local_session(task_id, session_info, _prepare_session_socket_dir(session_info["session_name"]),
- f"agent-browser '{command}' exited {result.get('returncode')}")
- continue
- break
-
- # Lightpanda automatic Chrome fallback — runs for ALL exit paths (timeout,
- # empty, non-JSON, nonzero rc, parsed).
- fallback_reason = _lp._lightpanda_fallback_reason(engine, command, result)
- if fallback_reason:
- _bt.logger.info("Lightpanda fallback: retrying '%s' with Chrome (task=%s): %s", command, task_id, fallback_reason)
- if command == "screenshot": # separate Chrome session to the same URL
- fallback_result = _lp._chrome_fallback_screenshot(task_id, args or [], timeout)
- else:
- fallback_result = _lp._run_chrome_fallback_command(task_id, command, args, timeout)
- return _lp._annotate_lightpanda_fallback(fallback_result, fallback_reason)
-
- return result
diff --git a/tools/browser_tool_snapshot.py b/tools/browser_tool_snapshot.py
deleted file mode 100644
index 0b95d77969d..00000000000
--- a/tools/browser_tool_snapshot.py
+++ /dev/null
@@ -1,138 +0,0 @@
-"""Snapshot post-processing for the browser tools: truncate-and-store of oversized
-accessibility trees, model-boundary secret redaction, screenshot-path recovery.
-
-Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import re
-from typing import Any, Optional
-from tools.browser_tool_origin import origin as _bt
-
-
-_SCREENSHOT_PATH_PATTERNS = (
- r"Screenshot saved to ['\"](?P<path>/[^'\"]+?\.png)['\"]",
- r"Screenshot saved to (?P<path>/\S+?\.png)(?:\s|$)",
- r"(?P<path>/\S+?\.png)(?:\s|$)",
-)
-
-
-def _extract_screenshot_path_from_text(text: str) -> Optional[str]:
- """Extract a screenshot file path from agent-browser human-readable output."""
- if not text:
- return None
-
- for pattern in _SCREENSHOT_PATH_PATTERNS:
- match = re.search(pattern, text)
- if match:
- path = match.group("path").strip().strip("'\"")
- if path:
- return path
- return None
-
-
-def _store_full_snapshot(snapshot_text: str) -> Optional[str]:
- """Write a full snapshot to cache/web and return its path (None on failure — best-effort).
-
- Mirrors ``web_tools._store_full_text``: cache/web is mounted read-only into
- remote backends, so read_file can page through the complete tree on any
- backend. The stored copy is force-redacted (page-rendered secrets must not
- hit disk unmasked) and named by content hash so identical snapshots dedupe.
- """
- try:
- import hashlib
- from hermes_constants import get_hermes_dir
- from agent.redact import redact_sensitive_text
-
- content = redact_sensitive_text(snapshot_text, force=True)
- if len(content) > _bt.MAX_STORED_SNAPSHOT_CHARS:
- content = (
- content[:_bt.MAX_STORED_SNAPSHOT_CHARS]
- + f"\n\n[... stored copy truncated at {_bt.MAX_STORED_SNAPSHOT_CHARS:,} chars "
- f"of {len(content):,} ...]"
- )
- from tools.spill_safety import ensure_spill_dir, write_text_exclusive
-
- cache_dir = get_hermes_dir("cache/web", "web_cache")
- ensure_spill_dir(cache_dir, private=False)
- digest = hashlib.sha256(content.encode("utf-8")).hexdigest()[:10]
- path = cache_dir / f"browser-snapshot-{digest}.txt"
- # Deterministic filename in a well-known dir: refuse symlinks (lstat-unlink +
- # exclusive create); same-content re-snapshots legitimately overwrite. Not
- # private: cache/web is bind-mounted into remote backends' container UID.
- write_text_exclusive(path, content, private=False, overwrite=True)
- return str(path)
- except Exception as exc:
- _bt.logger.debug("Failed to store full browser snapshot: %s", exc)
- return None
-
-
-def _truncate_snapshot(snapshot_text: str, max_chars: Optional[int] = None) -> str:
- """Truncate a snapshot at line boundaries (never mid-element) to ``max_chars``.
-
- Defaults to ``browser.snapshot_threshold``. The full snapshot is stored to
- cache/web and the appended note tells the agent how to page through it
- with read_file — element refs beyond the cut are in the file, not lost.
- """
- if max_chars is None:
- max_chars = _bt.get_browser_snapshot_threshold()
- if len(snapshot_text) <= max_chars:
- return snapshot_text
-
- stored_path = _store_full_snapshot(snapshot_text)
- if stored_path:
- # Agent-visible path: read_file runs inside the active backend (#72389).
- from tools.credential_files import to_agent_visible_cache_path
- stored_path = to_agent_visible_cache_path(stored_path)
-
- lines = snapshot_text.split('\n')
- result: list[str] = []
- chars = 0
- # Reserve space for the truncation note (the stored-path variant is the
- # longer of the two). Clamp so tiny max_chars values still keep content.
- reserve = min(110 + len(stored_path or ""), max_chars // 2)
- for line in lines:
- if chars + len(line) + 1 > max_chars - reserve:
- break
- result.append(line)
- chars += len(line) + 1
- remaining = len(lines) - len(result)
- if remaining > 0:
- if stored_path:
- next_line = len(result) + 1
- result.append(
- f'\n[... {remaining} more lines truncated — full snapshot: '
- f'read_file path="{stored_path}" offset={next_line} limit=200]'
- )
- else:
- result.append(f'\n[... {remaining} more lines truncated, use browser_snapshot for full content]')
- return '\n'.join(result)
-
-
-def _redact_browser_output(value: Any, *, _depth: int = 0) -> Any:
- """Force-redact secrets in browser-originated data (snapshots, console, eval
- results can carry page-rendered keys/cookies/tokens). Tool output is a model
- boundary, so this applies even when global log redaction is disabled.
-
- ``_depth`` stops a page-controlled tree from raising RecursionError. The
- unread remainder is replaced, not returned raw.
- """
- from agent.redact import (
- REDACT_WALK_DEPTH_MARKER,
- REDACT_WALK_MAX_DEPTH,
- redact_sensitive_text,
- )
-
- if _depth >= REDACT_WALK_MAX_DEPTH:
- return REDACT_WALK_DEPTH_MARKER
- if isinstance(value, str):
- return redact_sensitive_text(value, force=True)
- if isinstance(value, list):
- return [_redact_browser_output(item, _depth=_depth + 1) for item in value]
- if isinstance(value, tuple):
- return tuple(_redact_browser_output(item, _depth=_depth + 1) for item in value)
- if isinstance(value, dict):
- return {
- _redact_browser_output(key, _depth=_depth + 1): _redact_browser_output(item, _depth=_depth + 1)
- for key, item in value.items()
- }
- return value
diff --git a/tools/browser_tool_vision.py b/tools/browser_tool_vision.py
deleted file mode 100644
index 9c06c9133b5..00000000000
--- a/tools/browser_tool_vision.py
+++ /dev/null
@@ -1,144 +0,0 @@
-"""browser_vision helpers: Lightpanda pre-route, native provider vision, auxiliary-LLM screenshot analysis.
-
-Split out of ``tools/browser_tool.py``. Facade-owned state is read through ``_bt`` (``tools.browser_tool``, resolved per call) — no import cycle.
-"""
-
-import os
-import shutil
-from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
-
-from hermes_cli.config import cfg_get
-from tools.browser_tool_origin import origin as _bt
-from tools import browser_tool_cloud as _cloud
-from tools import browser_tool_lightpanda_fallback as _lp
-
-
-def _vision_mode_label() -> str:
- _cp = _cloud._get_cloud_provider()
- return "local" if _cp is None else f"cloud ({_cp.display_name})"
-
-
-def _lightpanda_vision_preroute(
- effective_task_id: str, annotate: bool, screenshot_path: Path,
-) -> tuple[bool, Optional[str], Path]:
- """Capture the vision screenshot via the Chrome fallback when Lightpanda is the engine
- (it has no graphical renderer). Returns ``(prerouted, fallback_warning, path)``;
- on fallback failure ``prerouted`` is False and the caller takes the normal
- screenshot path (forcing Chrome) so the standard fallback metadata still applies."""
- engine = _cloud._get_browser_engine()
- if engine != "lightpanda" or not _cloud._should_inject_engine(engine):
- return False, None, screenshot_path
- _bt.logger.debug("browser_vision: pre-routing screenshot to Chrome (engine=lightpanda)")
- screenshot_args = ["--annotate"] if annotate else []
- fb_result = _lp._chrome_fallback_screenshot(effective_task_id, screenshot_args, _bt._get_command_timeout())
- fb_result = _lp._annotate_lightpanda_fallback(fb_result, _bt._LP_VISION_FALLBACK_REASON)
- if not fb_result.get("success"):
- _bt.logger.warning("Lightpanda Chrome fallback vision screenshot failed: %s", fb_result.get("error"))
- return False, None, screenshot_path
- fb_path = fb_result.get("data", {}).get("path", "")
- if fb_path and os.path.exists(fb_path):
- import uuid as uuid_mod
- from hermes_constants import get_hermes_dir
-
- screenshots_dir = get_hermes_dir("cache/screenshots", "browser_screenshots")
- screenshots_dir.mkdir(parents=True, exist_ok=True)
- persistent_path = screenshots_dir / f"browser_screenshot_{uuid_mod.uuid4().hex}.png"
- shutil.copy2(fb_path, persistent_path)
- screenshot_path = persistent_path
- return True, fb_result.get("fallback_warning"), screenshot_path
-
-
-def _native_vision_result(
- screenshot_path: Path, question: str, annotate: bool,
- result: dict[str, Any], lp_fallback_warning: Optional[str],
-) -> dict[str, Any]:
- """Multimodal tool-result envelope: the main model inspects the pixels itself.
-
- The embed is baked into history and re-sent every later turn, so apply the same
- proactive resize as vision_analyze's native path (skipped when already under
- both caps; without Pillow it fails open to the raw bytes).
- """
- from tools.vision_tools import (
- _EMBED_MAX_DIMENSION,
- _build_native_vision_tool_result,
- _resize_image_for_vision,
- )
- from tools.vision_tools_history_budget import resolve_embed_target_bytes
-
- data_url = _resize_image_for_vision(screenshot_path, mime_type="image/png",
- max_base64_bytes=resolve_embed_target_bytes(),
- max_dimension=_EMBED_MAX_DIMENSION, force_jpeg=True)
- native_result = _build_native_vision_tool_result(image_url=str(screenshot_path), question=question,
- image_data_url=data_url,
- image_size_bytes=screenshot_path.stat().st_size)
- meta = native_result.setdefault("meta", {})
- meta["screenshot_path"] = str(screenshot_path)
- if lp_fallback_warning:
- meta["fallback_warning"] = lp_fallback_warning
- if annotate and result.get("data", {}).get("annotations"):
- meta["annotations"] = result["data"]["annotations"]
- native_result["text_summary"] = f"{native_result.get('text_summary', '')} Screenshot path: {screenshot_path}".strip()
- return native_result
-
-
-def _analyze_screenshot_with_aux_llm(screenshot_path: Path, question: str) -> str:
- """One-shot aux vision-LLM analysis (not baked into history), secret-redacted.
-
- Full resolution first; on a size-related provider rejection the image is
- downscaled once and retried. ``auxiliary.vision.timeout/temperature`` — local
- vision models can take well over 30s, so the default timeout is generous.
- """
- import base64
-
- vision_prompt = (
- f"You are analyzing a screenshot of a web browser.\n\n"
- f"User's question: {question}\n\n"
- f"Provide a detailed and helpful answer based on what you see in the screenshot. "
- f"If there are interactive elements, describe them. If there are verification challenges "
- f"or CAPTCHAs, describe what type they are and what action might be needed. "
- f"Focus on answering the user's specific question."
- )
- _screenshot_bytes = screenshot_path.read_bytes()
- _screenshot_b64 = base64.b64encode(_screenshot_bytes).decode("ascii")
- data_url = f"data:image/png;base64,{_screenshot_b64}"
- vision_model = _bt._get_vision_model()
- _bt.logger.debug("browser_vision: analysing screenshot (%d bytes)", len(_screenshot_bytes))
-
- vision_timeout = 120.0
- vision_temperature = 0.1
- try:
- from hermes_cli.config import load_config
- _vision_cfg = cfg_get(load_config(), "auxiliary", "vision", default={})
- if _vision_cfg.get("timeout") is not None:
- vision_timeout = float(_vision_cfg["timeout"])
- if _vision_cfg.get("temperature") is not None:
- vision_temperature = float(_vision_cfg["temperature"])
- except Exception:
- pass
-
- from agent.auxiliary_client import call_llm # lazy: heavy client, only needed on the vision path
-
- call_kwargs = {
- "task": "vision", "temperature": vision_temperature, "timeout": vision_timeout,
- "messages": [{"role": "user", "content": [
- {"type": "text", "text": vision_prompt},
- {"type": "image_url", "image_url": {"url": data_url}},
- ]}],
- }
- if vision_model:
- call_kwargs["model"] = vision_model
- try:
- response = call_llm(**call_kwargs)
- except Exception as _api_err:
- from tools.vision_tools import _is_image_size_error, _resize_image_for_vision, _RESIZE_TARGET_BYTES
- if not (_is_image_size_error(_api_err) and len(data_url) > _RESIZE_TARGET_BYTES):
- raise
- _bt.logger.info("Vision API rejected screenshot (%.1f MB); auto-resizing to ~%.0f MB and retrying...",
- len(data_url) / (1024 * 1024), _RESIZE_TARGET_BYTES / (1024 * 1024))
- data_url = _resize_image_for_vision(screenshot_path, mime_type="image/png")
- call_kwargs["messages"][0]["content"][1]["image_url"]["url"] = data_url
- response = call_llm(**call_kwargs)
-
- from agent.redact import redact_sensitive_text # the LLM may have read secrets off the screenshot
- return redact_sensitive_text((response.choices[0].message.content or "").strip())
diff --git a/tools/browser_use_cli.py b/tools/browser_use_cli.py
index 0cf4f26aa41..c83a1371619 100644
--- a/tools/browser_use_cli.py
+++ b/tools/browser_use_cli.py
@@ -305,7 +305,7 @@ def _native_screenshot_result(result: dict[str, Any], path: str) -> Optional[dic
if not _should_use_native_vision_fast_path():
return None
# History-reuse cap: this data URL bakes into the tool result and is re-sent every later turn —
- # same policy as the vision_analyze / browser_vision native embeds.
+ # same policy as the vision_analyze native embed.
data_url = _resize_image_for_vision(Path(path), mime_type="image/png",
max_base64_bytes=resolve_embed_target_bytes(),
max_dimension=_EMBED_MAX_DIMENSION, force_jpeg=True)
@@ -701,7 +701,7 @@ def browser_exec(code: str, session: str = "", timeout_s: int = _DEFAULT_TIMEOUT
if verdict.blocked:
return tool_error(verdict.blocked)
# One endpoint per call: any private URL sends the whole call to the local sidecar. A call with no URL
- # literal stays on the route the previous call took (browser_navigate's _last_session_key twin).
+ # literal stays on the route the previous call took.
route_key = _backend_cache_key(task_id, session)
local_sidecar = verdict.local_sidecar if _URL_RE.search(code) else _exec_route_is_sidecar.get(route_key, False)
diff --git a/tools/environments/docker.py b/tools/environments/docker.py
index 137513dc3e2..89c22bcc7d0 100644
--- a/tools/environments/docker.py
+++ b/tools/environments/docker.py
@@ -339,7 +339,7 @@ _BASE_SECURITY_ARGS = [
# Fork-bomb guard, applied only when the pids cgroup controller is available. The pids cgroup counts
# THREADS, and a sandbox that hosts the Bot Screen runs a desktop in here: measured on
# hermes-sandbox:desktop, the idle container is 2 tasks, Xvnc + Xfce + dbus 44, one Chromium with one
-# tab 212, plus the agent's own agent-browser Chromium with two tabs 488. The old 256 was hit in normal
+# tab 212, plus the agent's own Chromium with two tabs 488. The old 256 was hit in normal
# use and every further `docker exec` (browser command, cua-driver, thumbnail, CDP forward) died with
# runc's "procReady not received". 2048 leaves room for a working browser and is still three orders of
# magnitude under the host's pid_max.
diff --git a/tools/environments/local.py b/tools/environments/local.py
index 8272bb91082..6567d0d06dc 100644
--- a/tools/environments/local.py
+++ b/tools/environments/local.py
@@ -689,9 +689,8 @@ def _managed_runtime_path_entries() -> list[str]:
itself, so on a machine where Hermes provisioned its own toolchain a
command the agent runs resolves a system copy instead — or nothing at all:
- - the pm store's node/npm entries — installed to satisfy the desktop and
- browser toolchain. ``tools/browser_tool.py`` already does this for its own
- subprocesses; the agent's shell deserves the same.
+ - the pm store's node/npm entries — installed to satisfy the desktop
+ toolchain; the agent's shell deserves the same.
- ``$HERMES_HOME/bin`` — the managed ``uv``. ``install.sh`` writes it there
and nothing has ever put that directory on PATH, so an install whose only
uv is the managed one looks uv-less to both the agent and the model.
diff --git a/tools/environments/streams.py b/tools/environments/streams.py
index b50a342c30a..4d659657e80 100644
--- a/tools/environments/streams.py
+++ b/tools/environments/streams.py
@@ -2,8 +2,8 @@
``BaseEnvironment.execute`` is request/response: it captures output and returns. The desktop that
follows the terminal backend needs three things that are not: the RFB byte stream between the
-Desktop pane and the sandbox's Xvnc, cua-driver's MCP-over-stdio server, and agent-browser
-invocations whose daemon must outlive the call. All three are "spawn argv in the sandbox, keep
+Desktop pane and the sandbox's Xvnc, cua-driver's MCP-over-stdio server, and the bot's Chromium,
+which must outlive the call that started it. All three are "spawn argv in the sandbox, keep
stdin/stdout as pipes". Each spawn-per-call backend has a local argv prefix that gives exactly that
(``docker exec -i``, ``ssh``); this module is the one place that knows them.
diff --git a/tools/vision_tools.py b/tools/vision_tools.py
index c244fd4fa1e..ad6acbc06fb 100644
--- a/tools/vision_tools.py
+++ b/tools/vision_tools.py
@@ -945,8 +945,8 @@ def check_video_requirements() -> bool:
def check_vision_requirements() -> bool:
- """Image gate (``vision_analyze``, ``browser_vision``): an aux vision client OR the native fast
- path. Both handlers attach pixels straight to a vision-capable main model, so a main model on a
+ """Image gate (``vision_analyze``): an aux vision client OR the native fast
+ path. The handler attaches pixels straight to a vision-capable main model, so a main model on a
provider the aux resolver does not know (OAuth, local vLLM) must not hide a working tool (#47149).
``video_analyze`` keeps the aux-only gate — its handler has no native path.
"""
diff --git a/tools/web_tools_truncate.py b/tools/web_tools_truncate.py
index d3596ba659b..69317b7db44 100644
--- a/tools/web_tools_truncate.py
+++ b/tools/web_tools_truncate.py
@@ -121,7 +121,7 @@ def _truncate_with_footer(content: str, url: str, char_limit: int) -> tuple[str,
else:
footer_lines.append(
"Full text could not be stored; re-run web_extract on a more "
- "specific URL or use browser_navigate for the complete page."
+ "specific URL or open it in the browser for the complete page."
)
footer_lines.append("─" * 29)
model_text = head + "\n\n[... middle omitted — see footer ...]\n\n" + tail
diff --git a/toolsets.py b/toolsets.py
index 7572ad12850..e21d569f72c 100644
--- a/toolsets.py
+++ b/toolsets.py
@@ -14,12 +14,9 @@ _HERMES_CORE_TOOLS = [
"read_file", "write_file", "patch", "search_files",
"vision_analyze", "image_generate",
"skills_list", "skill_view", "skill_manage",
- "browser_navigate", "browser_snapshot", "browser_click",
- "browser_type", "browser_scroll", "browser_back",
- "browser_press", "browser_get_images",
- "browser_vision", "browser_console", "browser_cdp", "browser_dialog",
+ "browser_exec", # THE browser: Python over CDP (browser-harness)
+ "browser_cdp", "browser_dialog",
"browser_vault", # rides with the browser; deferred by default (tools.tool_search.defer)
- "browser_exec", # replaces the other browser tools when browser.backend is "browser-use"
"text_to_speech",
"todo_list", "memory",
"session_search",
@@ -110,8 +107,8 @@ TOOLSETS = {
# web_search from every session, because disabled toolsets are a strict
# end-of-pipeline subtraction (#17309, #64503).
"browser": _ts(
- "Browser automation for web interaction (navigate, click, type, scroll, "
- "iframes, hold-click)",
+ "Browser automation: drive a real browser with Python over CDP (navigate, "
+ "click, type, extract, screenshots), raw CDP, dialogs and vault logins",
[t for t in _HERMES_CORE_TOOLS if t.startswith("browser_")],
),
"cronjob": _ts(