feat: auto-launch Chromium-family browser for CDP

cli.py

@@ -105,6 +105,7 @@
 from hermes_constants import get_hermes_home, display_hermes_home
 from hermes_cli.browser_connect import (
     DEFAULT_BROWSER_CDP_URL,
+    is_browser_debug_ready,
     manual_chrome_debug_command,
     try_launch_chrome_debug,
 )
@@ -8454,10 +8455,10 @@ def _bg_thinking(text: str) -> None:
 
     @staticmethod
     def _try_launch_chrome_debug(port: int, system: str) -> bool:
-        """Try to launch Chrome/Chromium with remote debugging enabled.
+        """Try to launch a Chromium-family browser with remote debugging enabled.
 
         Uses a dedicated user-data-dir so the debug instance doesn't conflict
-        with an already-running Chrome using the default profile.
+        with an already-running browser using the default profile.
 
         Returns True if a launch command was executed (doesn't guarantee success).
         """
@@ -8502,7 +8503,7 @@ def _handle_bundles_command(self, cmd: str) -> None:
         )
 
     def _handle_browser_command(self, cmd: str):
-        """Handle /browser connect|disconnect|status — manage live Chrome CDP connection."""
+        """Handle /browser connect|disconnect|status — manage live Chromium-family CDP connection."""
         import platform as _plat
 
         parts = cmd.strip().split(None, 1)
@@ -8556,56 +8557,42 @@ def _handle_browser_command(self, cmd: str):
 
             print()
 
-            # Check if Chrome is already listening on the debug port
-            import socket
-            _already_open = False
-            try:
-                s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-                s.settimeout(1)
-                s.connect((_host, _port))
-                s.close()
-                _already_open = True
-            except (OSError, socket.timeout):
-                pass
+            # Check if a Chromium-family browser is already serving CDP on the debug port
+            _already_open = is_browser_debug_ready(cdp_url, timeout=1.0)
 
             if _already_open:
-                print(f"   ✓ Chrome is already listening on port {_port}")
+                print(f"   ✓ Chromium-family browser is already listening on port {_port}")
             elif cdp_url == _DEFAULT_CDP:
-                # Try to auto-launch Chrome with remote debugging
-                print("   Chrome isn't running with remote debugging — attempting to launch...")
+                # Try to auto-launch a Chromium-family browser with remote debugging
+                print("   Chromium-family browser isn't running with remote debugging — attempting to launch...")
                 _launched = self._try_launch_chrome_debug(_port, _plat.system())
                 if _launched:
-                    # Wait for the port to come up
+                    # Wait for the DevTools discovery endpoint to come up
                     for _wait in range(10):
-                        try:
-                            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-                            s.settimeout(1)
-                            s.connect((_host, _port))
-                            s.close()
+                        if is_browser_debug_ready(cdp_url, timeout=1.0):
                             _already_open = True
                             break
-                        except (OSError, socket.timeout):
-                            time.sleep(0.5)
+                        time.sleep(0.5)
                     if _already_open:
-                        print(f"   ✓ Chrome launched and listening on port {_port}")
+                        print(f"   ✓ Chromium-family browser launched and listening on port {_port}")
                     else:
-                        print(f"   ⚠ Chrome launched but port {_port} isn't responding yet")
+                        print(f"   ⚠ Browser launched but port {_port} isn't responding yet")
                         print("     Try again in a few seconds — the debug instance may still be starting")
                 else:
-                    print("   ⚠ Could not auto-launch Chrome")
+                    print("   ⚠ Could not auto-launch a Chromium-family browser")
                     sys_name = _plat.system()
                     chrome_cmd = manual_chrome_debug_command(_port, sys_name)
                     if chrome_cmd:
-                        print(f"     Launch Chrome manually:")
+                        print(f"     Launch a Chromium-family browser manually:")
                         print(f"     {chrome_cmd}")
                     else:
-                        print("     No Chrome/Chromium executable found in this environment")
+                        print("     No supported Chromium-family browser executable found in this environment")
             else:
                 print(f"   ⚠ Port {_port} is not reachable at {cdp_url}")
 
             if not _already_open:
                 print()
-                print("Browser not connected — start Chrome with remote debugging and retry /browser connect")
+                print("Browser not connected — start a Chromium-family browser with remote debugging and retry /browser connect")
                 print()
                 return
 
@@ -8618,20 +8605,23 @@ def _handle_browser_command(self, cmd: str):
             except Exception:
                 pass
             print()
-            print("🌐 Browser connected to live Chrome via CDP")
+            print("🌐 Browser connected to live Chromium-family browser via CDP")
             print(f"   Endpoint: {cdp_url}")
             print()
 
-            # Inject context message so the model knows
+            # Inject context message so the model knows this slash command
+            # intentionally makes the dev/debug CDP browser available for use.
             if hasattr(self, '_pending_input'):
                 self._pending_input.put(
-                    "[System note: The user has connected your browser tools to their live Chrome browser "
-                    "via Chrome DevTools Protocol. Your browser_navigate, browser_snapshot, browser_click, "
-                    "and other browser tools now control their real browser — including any pages they have "
-                    "open, logged-in sessions, and cookies. They likely opened specific sites or logged into "
-                    "services before connecting. Please await their instruction before attempting to operate "
-                    "the browser. When you do act, be mindful that your actions affect their real browser — "
-                    "don't close tabs or navigate away from pages without asking.]"
+                    "[System note: The user invoked /browser connect and connected your browser tools to "
+                    "a Chromium-family dev/debug browser via Chrome DevTools Protocol. "
+                    "Your browser_navigate, browser_snapshot, browser_click, and other browser tools now "
+                    "control that CDP browser. The command itself is a signal that using browser tools for "
+                    "their current browser-related request is expected; do not wait for separate permission "
+                    "just because CDP is connected. This is typically a Hermes-managed isolated debug "
+                    "profile, not the user's main everyday browser. It is still user-visible and may contain "
+                    "pages, logged-in sessions, or cookies in that debug profile, so avoid destructive actions, "
+                    "closing tabs, or navigating away unless the user's task calls for it.]"
                 )
 
         elif sub == "disconnect":
@@ -8644,24 +8634,24 @@ def _handle_browser_command(self, cmd: str):
                 except Exception:
                     pass
                 print()
-                print("🌐 Browser disconnected from live Chrome")
+                print("🌐 Browser disconnected from live Chromium-family browser")
                 print("   Browser tools reverted to default mode (local headless or cloud provider)")
                 print()
 
                 if hasattr(self, '_pending_input'):
                     self._pending_input.put(
-                        "[System note: The user has disconnected the browser tools from their live Chrome. "
+                        "[System note: The user has disconnected the browser tools from their live Chromium-family browser. "
                         "Browser tools are back to default mode (headless local browser or cloud provider).]"
                     )
             else:
                 print()
-                print("Browser is not connected to live Chrome (already using default mode)")
+                print("Browser is not connected to a live Chromium-family browser (already using default mode)")
                 print()
 
         elif sub == "status":
             print()
             if current:
-                print("🌐 Browser: connected to live Chrome via CDP")
+                print("🌐 Browser: connected to live Chromium-family browser via CDP")
                 print(f"   Endpoint: {current}")
 
                 _port = 9222
@@ -8677,7 +8667,7 @@ def _handle_browser_command(self, cmd: str):
                     s.close()
                     print("   Status: ✓ reachable")
                 except (OSError, Exception):
-                    print("   Status: ⚠ not reachable (Chrome may not be running)")
+                    print("   Status: ⚠ not reachable (browser may not be running)")
             else:
                 try:
                     from tools.browser_tool import _get_cloud_provider
@@ -8697,21 +8687,21 @@ def _handle_browser_command(self, cmd: str):
                     if engine == "lightpanda":
                         print("🌐 Browser: local Lightpanda (agent-browser --engine lightpanda)")
                         print("   ⚡ Lightpanda: faster navigation, no screenshot support")
-                        print("   Automatic Chrome fallback for screenshots and failed commands")
+                        print("   Automatic Chromium fallback for screenshots and failed commands")
                     elif engine == "chrome":
-                        print("🌐 Browser: local headless Chrome (agent-browser --engine chrome)")
+                        print("🌐 Browser: local headless Chromium (agent-browser --engine chrome)")
                     else:
                         print("🌐 Browser: local headless Chromium (agent-browser)")
             print()
-            print("   /browser connect      — connect to your live Chrome")
+            print("   /browser connect      — connect to your live Chromium-family browser")
             print("   /browser disconnect   — revert to default")
             print()
 
         else:
             print()
             print("Usage: /browser connect|disconnect|status")
             print()
-            print("   connect      Connect browser tools to your live Chrome session")
+            print("   connect      Connect browser tools to your live Chromium-family browser session")
             print("   disconnect   Revert to default browser backend")
             print("   status       Show current browser mode")
             print()

hermes_cli/browser_connect.py

@@ -1,4 +1,4 @@
-"""Shared helpers for attaching Hermes to a local Chrome CDP port."""
+"""Shared helpers for attaching Hermes to a local Chromium-family CDP port."""
 
 from __future__ import annotations
 
@@ -21,23 +21,53 @@
     "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
 )
 
-_WINDOWS_INSTALL_PARTS = (
-    ("Google", "Chrome", "Application", "chrome.exe"),
-    ("Chromium", "Application", "chrome.exe"),
-    ("Chromium", "Application", "chromium.exe"),
-    ("BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
-    ("Microsoft", "Edge", "Application", "msedge.exe"),
+_WINDOWS_BROWSER_GROUPS = (
+    (("chrome.exe", "chrome"), (("Google", "Chrome", "Application", "chrome.exe"),)),
+    (
+        ("chromium.exe", "chromium"),
+        (("Chromium", "Application", "chrome.exe"), ("Chromium", "Application", "chromium.exe")),
+    ),
+    (("brave.exe", "brave"), (("BraveSoftware", "Brave-Browser", "Application", "brave.exe"),)),
+    (("msedge.exe", "msedge"), (("Microsoft", "Edge", "Application", "msedge.exe"),)),
 )
 
-_LINUX_BIN_NAMES = (
-    "google-chrome", "google-chrome-stable", "chromium-browser",
-    "chromium", "brave-browser", "microsoft-edge",
+_WINDOWS_BIN_NAMES = tuple(name for names, _ in _WINDOWS_BROWSER_GROUPS for name in names)
+_WINDOWS_INSTALL_PARTS = tuple(parts for _, group in _WINDOWS_BROWSER_GROUPS for parts in group)
+
+_LINUX_BROWSER_GROUPS = (
+    (
+        ("google-chrome", "google-chrome-stable"),
+        ("/opt/google/chrome/chrome", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable"),
+    ),
+    (
+        ("chromium-browser", "chromium"),
+        ("/usr/bin/chromium-browser", "/usr/bin/chromium"),
+    ),
+    (
+        ("brave-browser", "brave-browser-stable", "brave"),
+        (
+            "/usr/bin/brave-browser",
+            "/usr/bin/brave-browser-stable",
+            "/usr/bin/brave",
+            "/snap/bin/brave",
+            "/opt/brave.com/brave/brave-browser",
+            "/opt/brave.com/brave/brave",
+            "/opt/brave-bin/brave",
+        ),
+    ),
+    (
+        ("microsoft-edge", "microsoft-edge-stable", "msedge"),
+        (
+            "/usr/bin/microsoft-edge",
+            "/usr/bin/microsoft-edge-stable",
+            "/opt/microsoft/msedge/microsoft-edge",
+            "/opt/microsoft/msedge/msedge",
+        ),
+    ),
 )
 
-_WINDOWS_BIN_NAMES = (
-    "chrome.exe", "msedge.exe", "brave.exe", "chromium.exe",
-    "chrome", "msedge", "brave", "chromium",
-)
+_LINUX_BIN_NAMES = tuple(name for names, _ in _LINUX_BROWSER_GROUPS for name in names)
+_LINUX_INSTALL_PATHS = tuple(path for _, paths in _LINUX_BROWSER_GROUPS for path in paths)
 
 
 def get_chrome_debug_candidates(system: str) -> list[str]:
@@ -53,29 +83,40 @@ def add(path: str | None) -> None:
         candidates.append(path)
         seen.add(normalized)
 
-    def add_install_paths(bases: tuple[str | None, ...]) -> None:
-        for base in filter(None, bases):
-            for parts in _WINDOWS_INSTALL_PARTS:
-                add(os.path.join(base, *parts))
+    def add_windows_install_paths(
+        bases: tuple[str | None, ...],
+        install_groups: tuple[tuple[tuple[str, ...], tuple[tuple[str, ...], ...]], ...],
+    ) -> None:
+        for _, group in install_groups:
+            for base in filter(None, bases):
+                for parts in group:
+                    add(os.path.join(base, *parts))
 
     if system == "Darwin":
         for app in _DARWIN_APPS:
             add(app)
         return candidates
 
     if system == "Windows":
-        for name in _WINDOWS_BIN_NAMES:
-            add(shutil.which(name))
-        add_install_paths((
+        install_bases = (
             os.environ.get("ProgramFiles"),
             os.environ.get("ProgramFiles(x86)"),
             os.environ.get("LOCALAPPDATA"),
-        ))
+        )
+        for names, install_parts in _WINDOWS_BROWSER_GROUPS:
+            for name in names:
+                add(shutil.which(name))
+            for base in filter(None, install_bases):
+                for parts in install_parts:
+                    add(os.path.join(base, *parts))
         return candidates
 
-    for name in _LINUX_BIN_NAMES:
-        add(shutil.which(name))
-    add_install_paths(("/mnt/c/Program Files", "/mnt/c/Program Files (x86)"))
+    for names, paths in _LINUX_BROWSER_GROUPS:
+        for name in names:
+            add(shutil.which(name))
+        for path in paths:
+            add(path)
+    add_windows_install_paths(("/mnt/c/Program Files", "/mnt/c/Program Files (x86)"), _WINDOWS_BROWSER_GROUPS)
     return candidates
 
 
@@ -92,6 +133,42 @@ def _chrome_debug_args(port: int) -> list[str]:
     ]
 
 
+def is_browser_debug_ready(url: str, timeout: float = 1.0) -> bool:
+    """Return True when ``url`` exposes a reachable Chrome DevTools endpoint."""
+    import socket
+    import urllib.request
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url if "://" in url else f"http://{url}")
+    try:
+        port = parsed.port or (443 if parsed.scheme in {"https", "wss"} else 80)
+    except ValueError:
+        return False
+
+    if parsed.scheme in {"ws", "wss"} and parsed.path.startswith("/devtools/browser/"):
+        if not parsed.hostname:
+            return False
+        try:
+            with socket.create_connection((parsed.hostname, port), timeout=timeout):
+                return True
+        except OSError:
+            return False
+
+    scheme = {"ws": "http", "wss": "https"}.get(parsed.scheme, parsed.scheme)
+    if scheme not in {"http", "https"} or not parsed.netloc:
+        return False
+
+    root = f"{scheme}://{parsed.netloc}".rstrip("/")
+    for probe in (f"{root}/json/version", f"{root}/json"):
+        try:
+            with urllib.request.urlopen(probe, timeout=timeout) as resp:
+                if 200 <= getattr(resp, "status", 200) < 300:
+                    return True
+        except Exception:
+            continue
+    return False
+
+
 def manual_chrome_debug_command(port: int = DEFAULT_BROWSER_CDP_PORT, system: str | None = None) -> str | None:
     system = system or platform.system()
     candidates = get_chrome_debug_candidates(system)
@@ -126,13 +203,15 @@ def try_launch_chrome_debug(port: int = DEFAULT_BROWSER_CDP_PORT, system: str |
         return False
 
     os.makedirs(chrome_debug_data_dir(), exist_ok=True)
-    try:
-        subprocess.Popen(
-            [candidates[0], *_chrome_debug_args(port)],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            **_detach_kwargs(system),
-        )
-        return True
-    except Exception:
-        return False
+    for candidate in candidates:
+        try:
+            subprocess.Popen(
+                [candidate, *_chrome_debug_args(port)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                **_detach_kwargs(system),
+            )
+            return True
+        except Exception:
+            continue
+    return False