ai-dev-browser 0.9.0__tar.gz → 0.9.2__tar.gz

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.9.0
+Version: 0.9.2
 Summary: A browser for AI to develop web automation — human-like automation that works seamlessly in a world designed for humans
 Author: sudoprivacy
 License: AGPL-3.0
@@ -29,6 +29,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
 Provides-Extra: fuzzy
 Requires-Dist: rapidfuzz>=3.0; extra == "fuzzy"
+Provides-Extra: cleanup
+Requires-Dist: psutil>=5.9; extra == "cleanup"
 Dynamic: license-file
 
 # ai-dev-browser
@@ -75,7 +77,7 @@ convenient:
 
 Because both paths are generated from a single source, parameter
 changes flow to both at once and can't drift. See
-[cli-args-ssot](https://github.com/sudoprivacy/cli-args-ssot) for the
+[cli-steering-engineering](https://github.com/sudoprivacy/cli-steering-engineering) for the
 underlying decorator.
 
 Tools cover: navigation, element interaction, mouse, tabs, screenshots,
@@ -89,7 +91,7 @@ ls ai_dev_browser/tools/
 
 **One file per CLI command, by design.** Each CLI command gets its own
 `tools/<name>.py` (e.g. `tools/click_by_text.py`, `tools/click_by_xpath.py`).
-This deviates from cli-args-ssot's "domain-grouped subcommands" recommendation
+This deviates from cli-steering-engineering's "domain-grouped subcommands" recommendation
 because our invocation is `python -m ai_dev_browser.tools.<name>` — one file
 1:1 maps to one CLI path with no extra subcommand layer. The
 `<verb>_by_<spec>` family (`click_by_text`, `click_by_ref`, `click_by_html_id`,

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/README.md

@@ -42,7 +42,7 @@ convenient:
 
 Because both paths are generated from a single source, parameter
 changes flow to both at once and can't drift. See
-[cli-args-ssot](https://github.com/sudoprivacy/cli-args-ssot) for the
+[cli-steering-engineering](https://github.com/sudoprivacy/cli-steering-engineering) for the
 underlying decorator.
 
 Tools cover: navigation, element interaction, mouse, tabs, screenshots,
@@ -56,7 +56,7 @@ ls ai_dev_browser/tools/
 
 **One file per CLI command, by design.** Each CLI command gets its own
 `tools/<name>.py` (e.g. `tools/click_by_text.py`, `tools/click_by_xpath.py`).
-This deviates from cli-args-ssot's "domain-grouped subcommands" recommendation
+This deviates from cli-steering-engineering's "domain-grouped subcommands" recommendation
 because our invocation is `python -m ai_dev_browser.tools.<name>` — one file
 1:1 maps to one CLI path with no extra subcommand layer. The
 `<verb>_by_<spec>` family (`click_by_text`, `click_by_ref`, `click_by_html_id`,

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/__init__.py

@@ -93,6 +93,7 @@ __all__ = [
     # Tools
     "browser_start",
     "browser_stop",
+    "browser_cleanup",
     "connect_browser",
 ]
 
@@ -102,4 +103,4 @@ from . import cdp
 from .core import connect_browser
 
 # Core functions also available at package level
-from .core import browser_start, browser_stop
+from .core import browser_cleanup, browser_start, browser_stop

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/_cli.py

@@ -391,7 +391,7 @@ def wrap_core(core_func: Callable, result_key: str = "success") -> Callable:
             result = await core_func(*args, **kwargs)
         except Exception as e:
             # Verbatim message — Python `repr(e)` and CLI stdout stay in
-            # lockstep (cli-args-ssot rule 7: never re-render error text
+            # lockstep (cli-steering-engineering rule 7: never re-render error text
             # in tool files).
             out: dict = {"error": str(e)}
             if failure_hint:
@@ -408,7 +408,7 @@ def wrap_core(core_func: Callable, result_key: str = "success") -> Callable:
         if isinstance(result, dict):
             filtered = _filter_dict_for_json(result)
             # Auto-inject failure hint when the tool reports failure via
-            # result_key=False. Pairs with cli-args-ssot Rule 5a: failure
+            # result_key=False. Pairs with cli-steering-engineering Rule 5a: failure
             # steering goes through the return channel (100% reach at
             # invocation time), not docstring (only reaches on --help).
             if filtered.get(result_key) is False and failure_hint:

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/core/__init__.py

@@ -32,6 +32,9 @@ from .ax import (
 from .browser import browser_list, browser_start, browser_stop
 from .cdp import cdp_send
 
+# Orphan profile cleanup (optional psutil dep)
+from .cleanup import browser_cleanup
+
 # Chrome detection and launching
 from .chrome import find_chrome, launch_chrome
 
@@ -135,6 +138,7 @@ __all__ = [
     "browser_start",
     "browser_stop",
     "browser_list",
+    "browser_cleanup",
     # Config
     "DEFAULT_BASE_DIR",
     "DEFAULT_PROFILE_DIR",

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/core/browser.py

@@ -75,6 +75,8 @@ def browser_start(
     temp: bool = False,
     reuse: ReuseStrategy = DEFAULT_REUSE_STRATEGY,
     startup_timeout: float = 30.0,
+    extra_args: list[str] | None = None,
+    disable_default_args: list[str] | None = None,
 ) -> dict:
     """Start or reuse a browser instance.
 
@@ -92,6 +94,18 @@ def browser_start(
             "started but port not listening" on a known-good environment;
             lower it (e.g. 5s) for headless CI where startup is fast and
             you want to fail loud quickly.
+        extra_args: Additional Chrome command-line flags appended after
+            the defaults. Plain passthrough to `launch_chrome`.
+        disable_default_args: Default Chrome flags to strip before launch.
+            Composable with `extra_args` so callers can fully control
+            launch flags without forking — e.g. anti-bot fingerprint
+            tuning passes `disable_default_args=["--enable-automation"]`
+            + `extra_args=["--disable-blink-features=AutomationControlled"]`.
+            See `launch_chrome` docstring for which defaults are
+            load-bearing for ai-dev-browser's own connection / discovery
+            logic and what removing them costs (in particular,
+            `--enable-automation` removal makes the Chrome invisible to
+            `browser_list` workspace filter and `browser_cleanup`).
 
     Returns:
         dict with port, pid, headless, url, profile, reused, message
@@ -158,6 +172,8 @@ def browser_start(
         headless=headless,
         start_url=start_url,
         user_data_dir=str(user_data_dir) if user_data_dir else None,
+        extra_args=extra_args,
+        disable_default_args=disable_default_args,
     )
 
     # Wait for Chrome to bind its debug port.

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/core/chrome.py

@@ -130,6 +130,7 @@ def launch_chrome(
     user_data_dir: str | Path | None = None,
     profile_prefix: str = DEFAULT_PROFILE_PREFIX,
     extra_args: list[str] | None = None,
+    disable_default_args: list[str] | None = None,
     start_url: str = "about:blank",
     disable_session_restore: bool = True,
     disable_session_crashed_bubble: bool = True,
@@ -146,7 +147,25 @@ def launch_chrome(
         headless: Run in headless mode (default: False)
         user_data_dir: Custom user data directory. If None, creates a temp directory.
         profile_prefix: Prefix for temp profile directory name
-        extra_args: Additional Chrome command-line arguments
+        extra_args: Additional Chrome command-line arguments appended after defaults.
+        disable_default_args: List of default Chrome flags to remove before launch.
+            Match is exact for `--flag` form and prefix-equality for `--flag=value`
+            form (e.g. `["--enable-automation"]` strips both). Use this when a
+            default flag conflicts with what you want — most common case is
+            `["--enable-automation"]` for anti-bot fingerprint scenarios where
+            sites detect automation Chrome via that flag's side effects.
+
+            **Load-bearing defaults — do NOT remove these or ai-dev-browser's
+            connection / discovery logic breaks**:
+              - `--remote-debugging-port=...` — CDP transport
+              - `--user-data-dir=...` — profile isolation + workspace tagging
+              - `--remote-allow-origins=*` — CDP origin check
+              - `--enable-automation` — required for `Browser.getBrowserCommandLine`
+                cmdline readback. Removing it makes this Chrome **invisible to
+                `browser_list` workspace filter and `browser_cleanup` orphan
+                detection** (caller must manage the port themselves). That's
+                often acceptable in stealth / private-flow scenarios; just be
+                aware of the trade-off.
         start_url: Initial URL to open (default: "about:blank" for clean state)
         disable_session_restore: Prevent Chrome from restoring previous tabs (default: True).
                                 Sets restore_on_startup=5 in Preferences file.
@@ -218,6 +237,18 @@ def launch_chrome(
     if headless:
         args.append("--headless=new")
 
+    # Filter out defaults the caller explicitly disabled. Match exact OR
+    # `<prefix>=...` form so callers can disable both `--enable-automation`
+    # and `--user-data-dir=anything` with a single entry.
+    if disable_default_args:
+        disable_set = set(disable_default_args)
+        args = [
+            a
+            for a in args
+            if a not in disable_set
+            and not any(a.startswith(d + "=") for d in disable_set)
+        ]
+
     if extra_args:
         args.extend(extra_args)
 

ai_dev_browser-0.9.2/ai_dev_browser/core/cleanup.py

@@ -0,0 +1,149 @@
+"""Orphan Chrome cleanup for ai-dev-browser-managed profiles.
+
+Long sessions with `close_chrome=False` accumulate Chrome processes
+(main + helper/renderer children) holding `--user-data-dir` locks on
+our managed profile directories. When the next `browser_start` tries
+to launch a fresh Chrome on the same profile, the lockfile contention
+causes the new spawn to fail. `browser_cleanup` scans for and kills
+the orphans.
+
+`psutil` is the only reliable cross-platform way to read every
+chrome.exe's command line; we make it an optional extra so users who
+never need cleanup don't pay the install cost.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+from .config import (
+    DEFAULT_PROFILE_DIR,
+    DEFAULT_PROFILE_PREFIX,
+    get_workspace_profile_dir,
+)
+from .port import _query_chrome_cmdline, find_debug_chromes
+from .process import _kill_process_tree
+
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_path(path: str) -> str:
+    """Normalize a path for comparison (resolves separators + Windows case)."""
+    return os.path.normcase(os.path.normpath(path))
+
+
+def _is_managed_profile(user_data_dir_normalized: str) -> bool:
+    """True iff the user_data_dir is inside our managed namespace.
+
+    Two namespaces:
+      - Workspace profiles: under `DEFAULT_PROFILE_DIR`
+        (`~/.ai-dev-browser/profiles/...`)
+      - Temp profiles: directory name starts with `DEFAULT_PROFILE_PREFIX`
+        (`ai_dev_browser_<port>` in the system temp dir)
+    """
+    workspace_root = _normalize_path(str(DEFAULT_PROFILE_DIR))
+    if user_data_dir_normalized.startswith(workspace_root):
+        return True
+    name = Path(user_data_dir_normalized).name
+    return name.startswith(DEFAULT_PROFILE_PREFIX)
+
+
+def browser_cleanup(profile: str | None = None) -> dict:
+    """Use when: long sessions with `close_chrome=False` accumulated
+    orphan chrome.exe processes that hold workspace profile dir locks,
+    blocking new `browser_start` calls (typical symptom on Windows:
+    `browser_start` errors with "started but port not listening" even
+    after raising `startup_timeout`).
+
+    Scans every chrome.exe whose `--user-data-dir` argument points
+    into our managed profile namespace, then kills the process tree
+    of any whose user-data-dir has no live debug-ready Chrome owner.
+    Live Chromes (visible to `find_debug_chromes`) are left alone.
+
+    Returns `{killed, count, profile_dirs}` so you can verify what was
+    cleaned. Safe by construction — never touches Chrome processes
+    outside `~/.ai-dev-browser/profiles/...` or the temp profile
+    prefix `ai_dev_browser_*`.
+
+    Args:
+        profile: Workspace profile name to scope cleanup to. None →
+            all managed profiles for the current workspace + any
+            temp profiles in our namespace.
+
+    Returns:
+        dict with `killed` (list of PIDs), `count` (len of killed),
+        and `profile_dirs` (sorted list of user-data-dirs that had
+        orphans cleaned).
+
+    Failure:
+        Requires the `cleanup` extra for `psutil`. Install via:
+        `pip install 'ai-dev-browser[cleanup]'`. After install, retry.
+    """
+    try:
+        import psutil
+    except ImportError as e:
+        raise ImportError(
+            "browser_cleanup requires psutil. Install via: "
+            "pip install 'ai-dev-browser[cleanup]'"
+        ) from e
+
+    # 1. Snapshot user_data_dirs of currently live debug-ready Chromes.
+    #    These are NOT orphans — their lifecycle is owned by whoever
+    #    launched them, and killing them would surprise the caller.
+    alive_dirs: set[str] = set()
+    for port, _pid, _ws in find_debug_chromes():
+        cmdline = _query_chrome_cmdline(port)
+        if not cmdline:
+            continue
+        for arg in cmdline:
+            if arg.startswith("--user-data-dir="):
+                alive_dirs.add(_normalize_path(arg.split("=", 1)[1]))
+                break
+
+    # 2. Optional single-profile filter.
+    profile_filter: str | None = None
+    if profile:
+        profile_filter = _normalize_path(str(get_workspace_profile_dir(profile)))
+
+    # 3. Enumerate chrome processes; kill orphans whose --user-data-dir
+    #    is in our namespace and has no live debug owner.
+    killed: list[int] = []
+    profile_dirs_cleaned: set[str] = set()
+
+    for proc in psutil.process_iter(["pid", "name", "cmdline"]):
+        try:
+            name = (proc.info.get("name") or "").lower()
+            if "chrome" not in name:
+                continue
+            cmdline = proc.info.get("cmdline") or []
+            udd: str | None = None
+            for arg in cmdline:
+                if arg.startswith("--user-data-dir="):
+                    udd = _normalize_path(arg.split("=", 1)[1])
+                    break
+            if not udd:
+                # Helper / renderer subprocess inherits user-data-dir
+                # implicitly — _kill_process_tree on the main parent
+                # below catches these. Skip standalone matching here.
+                continue
+            if not _is_managed_profile(udd):
+                continue
+            if profile_filter and udd != profile_filter:
+                continue
+            if udd in alive_dirs:
+                continue  # debug-ready owner exists, not an orphan
+
+            pid = proc.info["pid"]
+            if _kill_process_tree(pid):
+                killed.append(pid)
+                profile_dirs_cleaned.add(udd)
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            # Process vanished mid-iteration or we lack rights — skip.
+            continue
+
+    return {
+        "killed": killed,
+        "count": len(killed),
+        "profile_dirs": sorted(profile_dirs_cleaned),
+    }

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser/tools/_generate.py

@@ -26,6 +26,8 @@ INTERNAL = {
     "graceful_close_browser",
     "connect_browser",
     "get_active_tab",
+    # destructive — Python-only API; not exposed to LLM tool discovery
+    "browser_cleanup",
 }
 
 # Per-tool metadata overrides. Key = function name, value = dict of overrides.

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.9.0
+Version: 0.9.2
 Summary: A browser for AI to develop web automation — human-like automation that works seamlessly in a world designed for humans
 Author: sudoprivacy
 License: AGPL-3.0
@@ -29,6 +29,8 @@ Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
 Provides-Extra: fuzzy
 Requires-Dist: rapidfuzz>=3.0; extra == "fuzzy"
+Provides-Extra: cleanup
+Requires-Dist: psutil>=5.9; extra == "cleanup"
 Dynamic: license-file
 
 # ai-dev-browser
@@ -75,7 +77,7 @@ convenient:
 
 Because both paths are generated from a single source, parameter
 changes flow to both at once and can't drift. See
-[cli-args-ssot](https://github.com/sudoprivacy/cli-args-ssot) for the
+[cli-steering-engineering](https://github.com/sudoprivacy/cli-steering-engineering) for the
 underlying decorator.
 
 Tools cover: navigation, element interaction, mouse, tabs, screenshots,
@@ -89,7 +91,7 @@ ls ai_dev_browser/tools/
 
 **One file per CLI command, by design.** Each CLI command gets its own
 `tools/<name>.py` (e.g. `tools/click_by_text.py`, `tools/click_by_xpath.py`).
-This deviates from cli-args-ssot's "domain-grouped subcommands" recommendation
+This deviates from cli-steering-engineering's "domain-grouped subcommands" recommendation
 because our invocation is `python -m ai_dev_browser.tools.<name>` — one file
 1:1 maps to one CLI path with no extra subcommand layer. The
 `<verb>_by_<spec>` family (`click_by_text`, `click_by_ref`, `click_by_html_id`,

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser.egg-info/SOURCES.txt

@@ -86,6 +86,7 @@ ai_dev_browser/core/ax.py
 ai_dev_browser/core/browser.py
 ai_dev_browser/core/cdp.py
 ai_dev_browser/core/chrome.py
+ai_dev_browser/core/cleanup.py
 ai_dev_browser/core/config.py
 ai_dev_browser/core/connection.py
 ai_dev_browser/core/cookies.py

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/ai_dev_browser.egg-info/requires.txt

@@ -3,6 +3,9 @@ websocket-client>=1.0
 Pillow>=10.0
 deprecated>=1.2
 
+[cleanup]
+psutil>=5.9
+
 [dev]
 pytest>=7.0
 pytest-asyncio>=0.21

{ai_dev_browser-0.9.0 → ai_dev_browser-0.9.2}/pyproject.toml

@@ -40,6 +40,9 @@ dev = [
 fuzzy = [
     "rapidfuzz>=3.0",  # Fast C-based Levenshtein for fuzzy_find/fuzzy_click
 ]
+cleanup = [
+    "psutil>=5.9",  # For browser_cleanup orphan-process scan
+]
 
 [project.urls]
 Homepage = "https://github.com/sudoprivacy/ai-dev-browser"