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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.8.2
+Version: 0.8.3
 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.3}/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.3}/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.3}/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.3}/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.3
 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