ai-dev-browser 0.8.2__tar.gz → 0.8.4__tar.gz

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.8.2
+Version: 0.8.4
 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

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/_cli.py

@@ -88,6 +88,48 @@ def _parse_docstring_args(docstring: str) -> dict[str, str]:
     return args_section
 
 
+def _parse_docstring_failure(docstring: str) -> str | None:
+    """Extract the body of the Failure: section from a Google-style docstring.
+
+    Tool authors write failure-path steering once in the docstring's
+    `Failure:` section (parallel to `Args:` / `Returns:`). This parser
+    extracts it at wrap time; `wrap_core` then auto-injects it as the
+    `hint` field on any failure return — SSOT with auto-split across
+    `--help` (full docstring, reference surface) and failure `hint`
+    (just this section, runtime steering surface).
+
+    Rationale: guidance about "what to do if this tool fails" placed
+    only in the docstring reaches the LLM at most via `--help`, which
+    is an on-demand call the LLM rarely makes at invocation-failure
+    time. Routing the same authored text into the failure return is
+    the only channel with 100% reach at the moment the LLM needs to
+    recover.
+
+    Returns the flat concatenated hint text, or None if no Failure:
+    section is present.
+    """
+    if not docstring:
+        return None
+
+    in_failure = False
+    lines: list[str] = []
+    for raw in docstring.split("\n"):
+        stripped = raw.strip()
+        # Google-style section headers are single-word lines ending with ':'
+        is_section_header = stripped.endswith(":") and len(stripped.split()) == 1
+        if is_section_header:
+            if stripped == "Failure:":
+                in_failure = True
+                continue
+            if in_failure:
+                break  # next section ends the Failure block
+        elif in_failure:
+            lines.append(stripped)
+
+    text = " ".join(line for line in lines if line).strip()
+    return text or None
+
+
 def _get_param_type(hint) -> type | Callable[[str], bool]:
     """Convert type hint to argparse type."""
     import types
@@ -368,25 +410,38 @@ def wrap_core(core_func: Callable, result_key: str = "success") -> Callable:
         element_click = as_cli()(wrap_core(click, "clicked"))
     """
 
+    failure_hint = _parse_docstring_failure(core_func.__doc__ or "")
+
     @functools.wraps(core_func)
     async def wrapper(*args, **kwargs):
         try:
             result = await core_func(*args, **kwargs)
-            if isinstance(result, bool):
-                if result:
-                    return {result_key: True}
-                else:
-                    return {"error": "Operation failed"}
-            elif isinstance(result, dict):
-                # Filter out non-serializable values for CLI output
-                return _filter_dict_for_json(result)
-            else:
-                return {result_key: result}
         except Exception as e:
             # Verbatim message — Python `repr(e)` and CLI stdout stay in
-            # lockstep (cli-args-ssot rule 6: never re-render error text
+            # lockstep (cli-args-ssot rule 7: never re-render error text
             # in tool files).
-            return {"error": str(e)}
+            out: dict = {"error": str(e)}
+            if failure_hint:
+                out["hint"] = failure_hint
+            return out
+
+        if isinstance(result, bool):
+            if result:
+                return {result_key: True}
+            out = {"error": "Operation failed"}
+            if failure_hint:
+                out["hint"] = failure_hint
+            return out
+        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
+            # 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:
+                filtered.setdefault("hint", failure_hint)
+            return filtered
+        return {result_key: result}
 
     return wrapper
 
@@ -411,24 +466,30 @@ def wrap_core_sync(core_func: Callable, result_key: str = "success") -> Callable
         browser_start = as_cli(requires_tab=False)(wrap_core_sync(browser_start, "port"))
     """
 
+    failure_hint = _parse_docstring_failure(core_func.__doc__ or "")
+
     @functools.wraps(core_func)
     def wrapper(*args, **kwargs):
         try:
             result = core_func(*args, **kwargs)
-            if isinstance(result, bool):
-                if result:
-                    return {result_key: True}
-                else:
-                    return {"error": "Operation failed"}
-            elif isinstance(result, dict):
-                # Filter out non-serializable values for CLI output
-                return _filter_dict_for_json(result)
-            else:
-                return {result_key: result}
         except Exception as e:
-            # Verbatim message — Python `repr(e)` and CLI stdout stay in
-            # lockstep (cli-args-ssot rule 6: never re-render error text
-            # in tool files).
-            return {"error": str(e)}
+            out: dict = {"error": str(e)}
+            if failure_hint:
+                out["hint"] = failure_hint
+            return out
+
+        if isinstance(result, bool):
+            if result:
+                return {result_key: True}
+            out = {"error": "Operation failed"}
+            if failure_hint:
+                out["hint"] = failure_hint
+            return out
+        if isinstance(result, dict):
+            filtered = _filter_dict_for_json(result)
+            if filtered.get(result_key) is False and failure_hint:
+                filtered.setdefault("hint", failure_hint)
+            return filtered
+        return {result_key: result}
 
     return wrapper

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/core/_tab.py

@@ -195,6 +195,10 @@ class Tab:
         """Register a CDP event handler."""
         self._connection.add_handler(event_type, handler)
 
+    def remove_handler(self, event_type, handler) -> bool:
+        """Unregister a CDP event handler (pair with add_handler)."""
+        return self._connection.remove_handler(event_type, handler)
+
     # =========================================================================
     # JavaScript evaluation
     # =========================================================================

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/core/_transport.py

@@ -242,6 +242,36 @@ class CDPConnection:
             else:
                 self.handlers[evt].append(handler)
 
+    def remove_handler(
+        self,
+        event_type: type,
+        handler: Callable,
+    ) -> bool:
+        """Unregister a previously-added event handler.
+
+        Counterpart to add_handler for short-lived captures (e.g.
+        `js_evaluate` subscribing to `Runtime.consoleAPICalled` for the
+        duration of a single eval then detaching). Without this, each
+        call leaks the handler closure and its captured state.
+
+        Args:
+            event_type: CDP event class the handler was registered on.
+                        Only single-class removal is supported; to undo a
+                        module-level add_handler, unregister per-class.
+            handler: The exact callable passed to add_handler.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        bucket = self.handlers.get(event_type)
+        if not bucket:
+            return False
+        try:
+            bucket.remove(handler)
+            return True
+        except ValueError:
+            return False
+
     # Domains that should never be removed by _register_handlers cleanup.
     # These are either always-on (target, storage, input_) or essential
     # for core operations (page, dom) — enabled by Tab._ensure_connected().

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/core/ax.py

@@ -309,8 +309,14 @@ async def click_by_ref(
         dict with clicked status, element info, and navigation feedback:
         `{clicked, ref, role, name, url_before, url_after, title_after, navigated}`.
         `navigated=True` means the top-level URL changed after the click
-        (SPA route change or full page load). Use this to confirm the click
-        had the intended side effect instead of chaining a screenshot + discover.
+        (SPA route change or full page load).
+
+    Failure:
+        Ref is stale (page navigated or element was removed between
+        the `page_discover` / `find_by_text` call that returned it
+        and this click). Re-run `page_discover` or `find_by_text` to
+        get a fresh ref, or use a stable locator — `click_by_html_id`
+        / `click_by_xpath` / `click_by_text`.
 
     Example:
         # First page_discover elements

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/core/elements.py

@@ -432,6 +432,15 @@ async def page_wait_element(
 
     Returns:
         dict with found, elapsed, message
+
+    Failure:
+        Element didn't appear within `timeout` seconds. Try a longer
+        timeout if the page is slow; a broader locator (partial text
+        instead of exact, less-specific CSS selector); or confirm the
+        element is expected on this page via `page_discover`. For
+        iframe-embedded targets with a text locator, note that
+        text-based wait scans the top frame only — use
+        `find_by_text` + `click_by_ref` pattern instead of waiting.
     """
     result = await _wait_for_element(tab, text=text, selector=selector, timeout=timeout)
 
@@ -464,13 +473,6 @@ async def click_by_text(
     (form-validation error rendering, captcha pixels for OCR, final
     result view for the user).
 
-    **Top-frame only.** Unlike `click_by_html_id` / `click_by_xpath`
-    (which recurse through `window.frames`) and `find_by_text` (which
-    scans the full AX tree), this goes through CDP `DOM.performSearch`
-    and won't find text inside an iframe (nav menus in `<iframe>`,
-    embedded widgets). For those, use `find_by_text` → `click_by_ref`
-    or `click_by_xpath` / `click_by_html_id`.
-
     Prefer when text is unique / unambiguous and top-frame. For elements
     you already identified via `page_discover`, use `click_by_ref`.
 
@@ -483,8 +485,17 @@ async def click_by_text(
     Returns:
         dict with clicked, text, url_before, url_after, title_after, navigated.
         `navigated=True` means the top-level URL changed after the click
-        (SPA route change or full page load). Use this to confirm the click
-        had the intended side effect instead of chaining a screenshot + discover.
+        (SPA route change or full page load).
+
+    Failure:
+        Not found in the top frame. This tool uses CDP
+        `DOM.performSearch` on the main document only — it won't find
+        text inside iframes (nav menus in `<iframe>`, embedded
+        widgets). Try `find_by_text` → `click_by_ref` (scans
+        same-origin iframes and falls back to non-interactable AX
+        nodes like `<div onclick>`), or `click_by_xpath` /
+        `click_by_html_id` which recurse through `window.frames`
+        natively.
 
     Example:
         click_by_text("登录")
@@ -551,6 +562,15 @@ async def find_by_text(
     Returns:
         dict: `{found: True, ref, role, name, x, y, ...}` on hit,
               `{found: False, text}` otherwise.
+
+    Failure:
+        Text not found in main frame or any same-origin iframe, in
+        either the interactable or fallback tier. Check spelling /
+        case (match is case-insensitive substring); try a shorter
+        substring; or switch locator — `find_by_html_id` /
+        `find_by_xpath` if a DOM-level locator is known. For a broad
+        survey of what's on the page, run `page_discover` without a
+        text filter. Cross-origin iframes are not scanned.
     """
     from .snapshot import page_discover
 
@@ -606,6 +626,13 @@ async def type_by_text(
     Returns:
         dict with typed status
 
+    Failure:
+        Input with this accessible name not found in the top frame.
+        For iframe-embedded inputs, use `find_by_text` (AX-tree scan,
+        iframe-aware) to get a ref, then `type_by_ref`. If the input
+        lacks an accessible name, locate by html id with
+        `find_by_html_id` → `type_by_ref`.
+
     Example:
         type_by_text(name="用户名", text="myusername")
         type_by_text(name="Search", text="query", clear=True)
@@ -822,6 +849,12 @@ async def find_by_html_id(tab: Tab, html_id: str) -> dict:
         dict: `{found: true, tag, text, visible, attrs}` on hit,
               `{found: false}` otherwise.
 
+    Failure:
+        No element with this id in any same-origin frame. Use
+        `page_discover` to see the ids actually present, or switch
+        locator — `find_by_text` if you know the visible label,
+        `find_by_xpath` for attribute-predicate / positional lookups.
+
     Example:
         result = await find_by_html_id(tab, "submit-btn")
         if result["found"] and result["visible"]:
@@ -869,6 +902,13 @@ async def click_by_html_id(tab: Tab, html_id: str) -> dict:
     Returns:
         dict: `{clicked, html_id, url_before, url_after, title_after, navigated, error?}`.
         `navigated=True` means the top-level URL changed after the click.
+
+    Failure:
+        No element with this id found in any same-origin frame. Run
+        `find_by_html_id` first to verify existence and get attrs, or
+        switch locator — `click_by_text` (top frame only, use
+        `find_by_text` → `click_by_ref` for iframe targets) or
+        `click_by_xpath` for attribute / positional predicates.
     """
     url_before_state = await _capture_page_state(tab)
     url_before = url_before_state.get("url", "")
@@ -927,6 +967,14 @@ async def find_by_xpath(tab: Tab, xpath: str) -> dict:
     Returns:
         dict: `{found: true, tag, text, visible, attrs}` on hit,
               `{found: false}` otherwise.
+
+    Failure:
+        XPath returned no match in any same-origin frame. Shorten the
+        expression (e.g. `//button` instead of
+        `//button[@data-role='x']`) to verify the broader target
+        exists, or switch locator — `find_by_text` by visible label,
+        `find_by_html_id` if an id is known, or `page_discover` for a
+        structural survey.
     """
     expr = """
     (function(xpath) {
@@ -975,6 +1023,12 @@ async def click_by_xpath(tab: Tab, xpath: str) -> dict:
 
     Returns:
         dict: `{clicked, xpath, url_before, url_after, title_after, navigated, error?}`.
+
+    Failure:
+        XPath returned no match in any same-origin frame. Verify with
+        `find_by_xpath` first (returns the matched element's attrs
+        without clicking), or switch locator — `click_by_text` /
+        `click_by_html_id`, or `page_discover` → `click_by_ref`.
     """
     url_before_state = await _capture_page_state(tab)
     url_before = url_before_state.get("url", "")

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser/core/page.py

@@ -62,12 +62,14 @@ def read_screenshot_metadata(path: str) -> dict:
 
 
 async def js_evaluate(tab: Tab, expression: str) -> dict:
-    """Use when: NO specific tool fits — this is the last-resort raw JS
-    escape hatch. Returns `{result}` with whatever the expression evaluated
-    to (or `{error}`). Next step is interpreting that value yourself.
+    """Use when: NO specific tool fits — the last-resort raw JS escape
+    hatch. Works equally for **read** expressions (`document.title`,
+    `innerText`) and **side-effect** expressions (`.click()`, `.submit()`,
+    DOM mutations) — the return dict captures *everything* observable
+    during the eval, not just the expression value.
 
-    Before picking this: the locate+act combinations below cover almost all
-    intents atomically (and give you navigation feedback on clicks):
+    Before picking this: the locate+act combinations below cover almost
+    all intents atomically and are more specific:
 
       - Locate + act by html id:    `click_by_html_id` / `find_by_html_id`
       - Locate + act by XPath:      `click_by_xpath` / `find_by_xpath`
@@ -85,18 +87,136 @@ async def js_evaluate(tab: Tab, expression: str) -> dict:
 
     Args:
         tab: Tab instance
-        expression: JavaScript code to execute. Result of last expression is returned.
+        expression: JavaScript code to execute. Result of last expression
+            is returned. `console.log` / `warn` / `error` / `info` output
+            during the eval is captured separately.
 
     Returns:
-        dict with result (serializable) or error
+        dict with:
+
+          - `result`: the expression's evaluated value (may be `None` if
+            the expression is a void side-effect like `.click()`)
+          - `console`: list of `{level, text}` entries emitted during
+            the eval, if any (only present when non-empty)
+          - `url_before` / `url_after` / `title_after` / `navigated`:
+            top-level navigation observables, same shape as
+            `click_by_*`. `navigated=True` iff URL changed.
+          - `error`: `{message, description, stack}` if the expression
+            threw; absent on success.
+
+    Example:
+        # Read — result field carries the answer
+        await js_evaluate(tab, "document.title")
+        # → {"result": "...", "url_before": ..., "navigated": False}
+
+        # Side effect — navigated/url_after + console confirm what happened
+        await js_evaluate(tab, "document.querySelector('#login').click()")
+        # → {"result": None, "url_before": "/login", "url_after": "/home",
+        #    "navigated": True, "title_after": "Home"}
+
+        # Debugging — console lines captured
+        await js_evaluate(tab, "console.log('x=', x); x + 1")
+        # → {"result": 2, "console": [{"level": "log", "text": "x= 1"}], ...}
     """
-    result = await tab.evaluate(expression)
-    # Try to serialize result
+    from ai_dev_browser.cdp import runtime
+
+    from .elements import _POST_CLICK_NAV_DELAY, _capture_page_state
+
+    before = await _capture_page_state(tab)
+
+    console_msgs: list[dict] = []
+
+    def _stringify_arg(arg) -> str:
+        # Runtime.RemoteObject: value (primitive) / description / unserializable_value
+        val = getattr(arg, "value", None)
+        if val is not None:
+            try:
+                return json.dumps(val, ensure_ascii=False)
+            except (TypeError, ValueError):
+                return str(val)
+        desc = getattr(arg, "description", None)
+        if desc:
+            return str(desc)
+        unser = getattr(arg, "unserializable_value", None)
+        if unser:
+            return str(unser)
+        return ""
+
+    def on_console(event):
+        level = getattr(event, "type_", "log")
+        text = " ".join(_stringify_arg(a) for a in event.args)
+        console_msgs.append({"level": level, "text": text})
+
+    # Runtime.enable() is idempotent and required for consoleAPICalled events.
+    await tab.send(runtime.enable())
+    tab.add_handler(runtime.ConsoleAPICalled, on_console)
+
+    result_value: object = None
+    error_info: dict | None = None
     try:
-        json.dumps(result)
-        return {"result": result}
-    except (TypeError, ValueError):
-        return {"result": str(result)}
+        raw = await tab.evaluate(expression)
+    except Exception as e:
+        error_info = {"message": str(e)}
+    else:
+        # tab.evaluate returns ExceptionDetails on eval-time exceptions
+        # (not a Python raise), see _tab.py::evaluate.
+        if isinstance(raw, runtime.ExceptionDetails):
+            exc = getattr(raw, "exception", None)
+            stack = getattr(raw, "stack_trace", None)
+            error_info = {
+                "message": getattr(raw, "text", "") or "",
+                "description": getattr(exc, "description", None) if exc else None,
+                "stack": [
+                    {
+                        "function": f.function_name,
+                        "url": f.url,
+                        "line": f.line_number,
+                        "column": f.column_number,
+                    }
+                    for f in (stack.call_frames if stack else [])
+                ]
+                if stack
+                else None,
+            }
+        else:
+            try:
+                json.dumps(raw)
+                result_value = raw
+            except (TypeError, ValueError):
+                result_value = str(raw)
+
+    # Give any navigation triggered by the eval a moment to commit,
+    # mirroring click_by_*'s _POST_CLICK_NAV_DELAY so URL snapshots
+    # reflect the post-action state.
+    import asyncio as _asyncio
+
+    await _asyncio.sleep(_POST_CLICK_NAV_DELAY)
+
+    try:
+        after = await _capture_page_state(tab)
+    except Exception:
+        # Context destroyed mid-read (full-page nav) — we know URL changed
+        after = {"url": None, "title": None}
+
+    tab.remove_handler(runtime.ConsoleAPICalled, on_console)
+
+    url_before = before.get("url", "") if isinstance(before, dict) else ""
+    url_after = after.get("url") if isinstance(after, dict) else None
+    title_after = after.get("title", "") if isinstance(after, dict) else ""
+    navigated = bool(url_before) and url_after is not None and url_after != url_before
+
+    out: dict = {
+        "result": result_value,
+        "url_before": url_before,
+        "url_after": url_after,
+        "title_after": title_after,
+        "navigated": navigated,
+    }
+    if console_msgs:
+        out["console"] = console_msgs
+    if error_info is not None:
+        out["error"] = error_info
+    return out
 
 
 async def page_screenshot(

{ai_dev_browser-0.8.2 → ai_dev_browser-0.8.4}/ai_dev_browser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.8.2
+Version: 0.8.4
 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