X5Browser 1.1.0__py3-none-any.whl

x5browser/__init__.py

@@ -0,0 +1,45 @@
+"""X5Browser: single-folder browser library for AI agents.
+
+Local package usage (no Docker)::
+
+    from x5browser import LiveBrowser
+
+    live = LiveBrowser()          # hidden Chrome + live link + timeline
+    await live.start()            # stack + agent + self-cleaning janitor
+    print(live.live_url)          # open / embed in any <iframe>
+    live.get_tools()              # catalog (full=True for all tools)
+    await live.navigate("https://example.com")  # screenshot per action
+    await live.take_control()     # user drives the same browser
+    await live.agent_control()    # agent resumes with fresh observe
+    await live.stop_browser()     # quiet close, data kept, reopen on demand
+    await live.stop()
+
+Lower layers stay importable directly (X5Browser + tool catalog,
+ControlManager, LiveStack, Janitor) for projects that wire their own UI.
+"""
+
+from .browser.api import X5Browser
+from .browser.tools import TOOL_SCHEMAS
+from .browser.types import ActionResult
+from .config import PROJECT_ROOT, BrowserConfig
+from .control.state import ControlManager
+from .live.stack import LiveStack
+from .live_browser import LiveBrowser
+from .maintenance import Janitor
+from .platform import default_profile_dir, detect_host
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "LiveBrowser",
+    "X5Browser",
+    "ActionResult",
+    "BrowserConfig",
+    "ControlManager",
+    "Janitor",
+    "LiveStack",
+    "TOOL_SCHEMAS",
+    "PROJECT_ROOT",
+    "default_profile_dir",
+    "detect_host",
+]

x5browser/browser/__init__.py

@@ -0,0 +1,5 @@
+"""Agent-facing page tools (M1): observation, navigation, interaction, waiting."""
+
+from .types import ActionResult, AgentSession, ElementRef, Observation
+
+__all__ = ["ActionResult", "AgentSession", "ElementRef", "Observation"]

x5browser/browser/actions.py

@@ -0,0 +1,535 @@
+"""Real-input page actions (M1, spec 9).
+
+Every function sends genuine CDP Input.* events only. No JavaScript is ever
+injected for interaction (spec non-negotiable). Each action resolves the ref
+against the current observation, verifies, acts, then waits stable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .types import AgentSession, ElementRef
+from ..input.keymap import (
+    MOD_ALT,
+    MOD_CTRL,
+    MOD_META,
+    MOD_SHIFT,
+    MODIFIERS,
+    NAMED_KEYS,
+    parse_key,
+    parse_modifiers,
+)
+
+
+def resolve_ref(session: AgentSession, ref: int) -> ElementRef:
+    """Fetch a ref from the current observation or raise a fix-hinted error."""
+    observation = session.observation
+    if observation is None or ref not in observation.refs:
+        raise ValueError(
+            f"error: ref_not_found - ref {ref} not found (page changed). "
+            "call page_snapshot()."
+        )
+    return observation.refs[ref]
+
+
+def element_session(session: AgentSession, element: ElementRef) -> str:
+    """Owning CDP session of an element (frame sessions fall back to main)."""
+    return element.session_id or session.session_id
+
+
+def quad_center(quad: list | None) -> tuple[float, float] | None:
+    """Center of a content quad, or None when geometry is unknown."""
+    if not quad or len(quad) < 8:
+        return None
+    xs = quad[0::2]
+    ys = quad[1::2]
+    return (sum(xs) / len(xs), sum(ys) / len(ys))
+
+
+async def _mouse(
+    client: Any, session_id: str, action: str, x: float, y: float, **extra: Any
+) -> None:
+    params: dict[str, Any] = {"type": action, "x": x, "y": y, **extra}
+    await client.send("Input.dispatchMouseEvent", params, session_id=session_id)
+
+
+async def _key(
+    client: Any,
+    session_id: str,
+    action: str,
+    key: str,
+    code: str,
+    windows_code: int = 0,
+    modifiers: int = 0,
+    text: str | None = None,
+) -> None:
+    params: dict[str, Any] = {
+        "type": action,
+        "key": key,
+        "code": code,
+        "windowsVirtualKeyCode": windows_code,
+        "modifiers": modifiers,
+    }
+    if text is not None:
+        params["text"] = text
+    await client.send("Input.dispatchKeyEvent", params, session_id=session_id)
+
+
+async def settle_scroll(client: Any, session_id: str) -> None:
+    """Wait until the scroll position stops changing (max ~1s).
+
+    scrollIntoView settles asynchronously against hit-testing: pressing on
+    quads read mid-settle can hit the wrong element (verified), so every
+    targeting path settles first.
+    """
+    last: tuple = ()
+    for _ in range(10):
+        try:
+            metrics = await client.send(
+                "Page.getLayoutMetrics", session_id=session_id
+            )
+            page = metrics.get("layoutViewport", {}) or {}
+            position = (page.get("pageX", 0), page.get("pageY", 0))
+        except Exception:  # noqa: BLE001 - a lost metrics call ends settling
+            return
+        if position == last:
+            return
+        last = position
+        import asyncio
+
+        await asyncio.sleep(0.1)
+
+
+async def element_center(
+    session: AgentSession, element: ElementRef
+) -> tuple[float, float]:
+    """Scroll into view, settle, and return the fresh page-space center."""
+    target = element_session(session, element)
+    center: tuple[float, float] | None = None
+    for _ in range(3):  # bounded retries (Absolute Rule 20)
+        await session.client.send(
+            "DOM.scrollIntoViewIfNeeded",
+            {"backendNodeId": element.backend_id},
+            session_id=target,
+        )
+        await settle_scroll(session.client, target)
+        try:
+            result = await session.client.send(
+                "DOM.getContentQuads",
+                {"backendNodeId": element.backend_id},
+                session_id=target,
+            )
+            quads = result.get("quads", [])
+            center = quad_center(list(quads[0])) if quads else None
+        except Exception:  # noqa: BLE001 - fall back to the observe-time quad
+            center = None
+        center = center or quad_center(element.quad)
+        if center is None:
+            break
+        owner = await coverage_owner(
+            session, center[0] + element.dx, center[1] + element.dy
+        )
+        if owner is None or await is_same_or_descendant(
+            session, element.backend_id, owner
+        ) or await is_frame_hit(session, element, owner):
+            break
+    if center is None:
+        raise ValueError(
+            f"error: element_not_visible - {element.role} {element.name!r} "
+            "has no geometry. call page_snapshot()."
+        )
+    return (center[0] + element.dx, center[1] + element.dy)
+
+
+async def is_same_or_descendant(
+    session: AgentSession, ancestor_backend: int, node_backend: int
+) -> bool:
+    """True when the hit-tested node is the target or inside it.
+
+    Hit-testing may return an inner text node instead of the element itself;
+    that is a hit, not a cover. Bounded subtree search (depth 5).
+    """
+    if ancestor_backend == node_backend:
+        return True
+    return await _backend_contains(
+        session, ancestor_backend, node_backend, session.session_id
+    )
+
+
+async def is_frame_hit(
+    session: AgentSession, element: ElementRef, node_backend: int
+) -> bool:
+    """True when the hit node is the frame element wrapping a frame target.
+
+    Main-target hit-testing stops at the iframe element (an ancestor of the
+    inner button), which can never occlude its own content. Accepted only
+    for frame elements and only when the owner is a genuine ancestor.
+    """
+    if not element.session_id and not element.dx and not element.dy:
+        return False
+    try:
+        described = await session.client.send(
+            "DOM.describeNode",
+            {"backendNodeId": node_backend, "depth": 5},
+            session_id=session.session_id,
+        )
+    except Exception:  # noqa: BLE001 - unknown tree means not verifiable
+        return False
+    node = described.get("node") or {}
+    if (node.get("nodeName", "") or "").upper() not in ("IFRAME", "OBJECT", "EMBED"):
+        return False
+    return await _backend_contains(
+        session, node_backend, element.backend_id, session.session_id
+    )
+
+
+async def _backend_contains(
+    session: AgentSession, ancestor_backend: int, node_backend: int,
+    target_session: str,
+) -> bool:
+    """Bounded subtree search for one backend id under another."""
+    for pierce in (True, False):
+        try:
+            described = await session.client.send(
+                "DOM.describeNode",
+                {"backendNodeId": ancestor_backend, "depth": 5,
+                 "pierce": pierce},
+                session_id=target_session,
+            )
+        except Exception:  # noqa: BLE001 - unknown tree means not verifiable
+            continue
+        if _subtree_has(described.get("node") or {}, node_backend):
+            return True
+    return False
+
+
+def _subtree_has(node: dict, node_backend: int) -> bool:
+    """Iterative search through children, content documents, and shadow roots."""
+    stack = [node]
+    while stack:
+        current = stack.pop()
+        if current.get("backendNodeId") == node_backend:
+            return True
+        stack.extend(
+            child for child in current.get("children", []) or []
+            if isinstance(child, dict)
+        )
+        content = current.get("contentDocument")
+        if isinstance(content, dict):
+            stack.extend(
+                child for child in content.get("children", []) or []
+                if isinstance(child, dict)
+            )
+        for shadow in current.get("shadowRoots", []) or []:
+            if isinstance(shadow, dict):
+                stack.extend(
+                    child for child in shadow.get("children", []) or []
+                    if isinstance(child, dict)
+                )
+    return False
+
+
+async def coverage_owner(
+    session: AgentSession, x: float, y: float
+) -> int | None:
+    """Backend id of the top node at viewport point (x, y), None when unknown.
+
+    getNodeForLocation expects DOCUMENT coordinates (verified: viewport
+    coords fail once scrolled), so the current scroll offset is added.
+    """
+    client = session.client
+    try:
+        metrics = await client.send(
+            "Page.getLayoutMetrics", session_id=session.session_id
+        )
+        page = metrics.get("layoutViewport", {}) or {}
+        doc_x = x + float(page.get("pageX", 0))
+        doc_y = y + float(page.get("pageY", 0))
+        result = await client.send(
+            "DOM.getNodeForLocation", {"x": int(doc_x), "y": int(doc_y)},
+            session_id=session.session_id,
+        )
+        backend_id = result.get("backendNodeId")
+        return backend_id if isinstance(backend_id, int) else None
+    except Exception:  # noqa: BLE001 - coverage check is best-effort
+        return None
+
+
+async def click_at(client: Any, session_id: str, x: float, y: float) -> None:
+    """Raw viewport click: move, press, release (left button)."""
+    await _mouse(client, session_id, "mouseMoved", x, y)
+    await _mouse(client, session_id, "mouseMoved", x, y)
+    await _mouse(
+        client, session_id, "mousePressed", x, y, button="left", clickCount=1
+    )
+    await _mouse(
+        client, session_id, "mouseReleased", x, y, button="left", clickCount=1
+    )
+
+
+async def element_href(session: AgentSession, element: ElementRef) -> str:
+    """Raw href of one element (CDP read only, never JS). Empty when none.
+
+    Reads the node's own attributes via DOM.describeNode; ancestors are
+    not walked (documented limit: wrapped inner spans fall back to clicks).
+    """
+    try:
+        described = await session.client.send(
+            "DOM.describeNode",
+            {"backendNodeId": element.backend_id, "depth": 0},
+            session_id=element_session(session, element),
+        )
+    except Exception:  # noqa: BLE001 - unknown node: no bypass
+        return ""
+    node = described.get("node", {}) if isinstance(described, dict) else {}
+    attrs = node.get("attributes", []) if isinstance(node, dict) else []
+    if not isinstance(attrs, list):
+        return ""
+    for index in range(0, len(attrs) - 1, 2):
+        if attrs[index] == "href" and isinstance(attrs[index + 1], str):
+            return attrs[index + 1]
+    return ""
+
+
+async def key_press(
+    client: Any, session_id: str, key: str, modifiers: list[str] | None = None
+) -> None:
+    """Press and release one key with optional modifiers (real key events)."""
+    name, code, windows_code = parse_key(key)
+    mods = parse_modifiers(modifiers)
+    await _key(client, session_id, "keyDown", name, code, windows_code, mods)
+    await _key(client, session_id, "keyUp", name, code, windows_code, mods)
+
+
+async def key_chars(
+    client: Any, session_id: str, text: str, delay: float = 0.0
+) -> None:
+    """Send text as char key events (for controls ignoring insertText).
+
+    With delay > 0 each character lands separately like manual typing
+    (human-like mode). Total time is bounded: 200 chars max, so even the
+    slowest supported delay keeps one call under ~15s.
+
+    Verified: native <select> type-ahead and date spinbuttons only react to
+    text (char) events, not to Input.insertText.
+    """
+    import asyncio
+
+    for char in text[:200]:
+        lowered = char.lower()
+        code = f"Key{char.upper()}" if char.isalpha() else (
+            f"Digit{char}" if char.isdigit() else ""
+        )
+        vk = ord(char.upper()) if char.isalnum() else 0
+        await _key(client, session_id, "rawKeyDown", lowered, code, vk)
+        await _key(client, session_id, "char", lowered, code, 0, text=char)
+        await _key(client, session_id, "keyUp", lowered, code, vk)
+        if delay > 0:
+            await asyncio.sleep(min(delay, 0.5))
+
+
+HUMAN_CHAR_DELAY = 0.05  # seconds between keystrokes in human-like mode
+
+
+async def type_text(
+    session: AgentSession,
+    element: ElementRef,
+    text: str,
+    clear: bool,
+    human: bool = False,
+) -> None:
+    """Focus the field, optionally clear it, insert text as real input.
+
+    Spinbuttons ignore insertText: they get char key events instead.
+    human=True types char-by-char with a small delay like manual typing
+    (slower, but indistinguishable from a keyboard for bot detection).
+    """
+    client = session.client
+    target = element_session(session, element)
+    try:
+        resolved = await client.send(
+            "DOM.resolveNode",
+            {"backendNodeId": element.backend_id},
+            session_id=target,
+        )
+        object_id = (resolved.get("object") or {}).get("objectId")
+    except Exception as exc:  # noqa: BLE001 - resolution failure is a stale ref
+        raise ValueError(
+            f"error: ref_stale - {element.role} {element.name!r} is gone. "
+            "call page_snapshot()."
+        ) from exc
+    if not isinstance(object_id, str):
+        raise ValueError(
+            f"error: ref_stale - {element.role} {element.name!r} is gone. "
+            "call page_snapshot()."
+        )
+    await client.send("DOM.focus", {"objectId": object_id}, session_id=target)
+    if clear:
+        await key_press(client, target, "a", ["ctrl"])
+        await key_press(client, target, "Backspace")
+    if element.role == "spinbutton":
+        await key_chars(client, target, text)
+    elif human:
+        await key_chars(client, target, text, delay=HUMAN_CHAR_DELAY)
+    else:
+        await client.send(
+            "Input.insertText", {"text": text}, session_id=target
+        )
+
+
+async def scroll_by(client: Any, session_id: str, dx: float, dy: float) -> None:
+    """Real wheel event at the viewport center."""
+    metrics = await client.send(
+        "Page.getLayoutMetrics", session_id=session_id
+    )
+    viewport = metrics.get("cssVisualViewport", {}) or {}
+    x = float(viewport.get("pageX", 0)) + float(viewport.get("width", 800)) / 2
+    y = float(viewport.get("pageY", 0)) + float(viewport.get("height", 600)) / 2
+    await _mouse(
+        client, session_id, "mouseWheel", x, y, deltaX=dx, deltaY=dy
+    )
+
+
+async def scroll_to(session: AgentSession, element: ElementRef) -> None:
+    """Bring the element into view with a margin for sticky headers."""
+    target = element_session(session, element)
+    await session.client.send(
+        "DOM.scrollIntoViewIfNeeded",
+        {"backendNodeId": element.backend_id},
+        session_id=target,
+    )
+    await scroll_by(session.client, session.session_id, 0.0, -80.0)
+    await settle_scroll(session.client, session.session_id)
+    # Near the page bottom the -80 margin can push a bottom element back
+    # below the fold (verified): re-reveal without margin when still hidden.
+    try:
+        result = await session.client.send(
+            "DOM.getContentQuads", {"backendNodeId": element.backend_id},
+            session_id=target,
+        )
+        quads = result.get("quads", [])
+        center = quad_center(list(quads[0])) if quads else None
+        if center is None:
+            return
+        metrics = await session.client.send(
+            "Page.getLayoutMetrics", session_id=session.session_id
+        )
+        viewport = metrics.get("cssVisualViewport", {}) or {}
+        height = float(viewport.get("height", 0) or 0)
+        if not height:
+            page = metrics.get("layoutViewport", {}) or {}
+            height = float(page.get("clientHeight", 0) or 0)
+        if height and not (0 <= center[1] <= height):
+            await session.client.send(
+                "DOM.scrollIntoViewIfNeeded",
+                {"backendNodeId": element.backend_id},
+                session_id=target,
+            )
+            await settle_scroll(session.client, session.session_id)
+    except Exception:  # noqa: BLE001 - re-reveal is best-effort
+        pass
+
+
+async def hover(session: AgentSession, element: ElementRef) -> None:
+    """Gradual mouse approach so hover menus appear (spec 11.23)."""
+    x, y = await element_center(session, element)
+    target = element_session(session, element)
+    steps = 8
+    await session.client.send(
+        "Input.dispatchMouseEvent",
+        {"type": "mouseMoved", "x": x - 40.0, "y": y - 20.0},
+        session_id=target,
+    )
+    for step in range(1, steps + 1):
+        await _mouse(
+            session.client, target, "mouseMoved",
+            x - 40.0 + 40.0 * step / steps, y - 20.0 + 20.0 * step / steps,
+        )
+
+
+async def select_option(
+    session: AgentSession, element: ElementRef, value: str
+) -> None:
+    """Native <select> via keyboard type-ahead (no JS). Caller verifies.
+
+    Type-ahead matching consumes text (char) events: rawKeyDown + char +
+    keyUp per character. Plain keyDown/Up alone does not drive matching,
+    and Enter would open the native popup instead.
+    """
+    if element.role != "combobox":
+        raise ValueError(
+            f"error: invalid_input - ref {element.ref} is {element.role}, "
+            "not a select box. For custom dropdowns: click, then click the option."
+        )
+    target = element_session(session, element)
+    await type_text(session, element, "", clear=False)
+    await key_chars(client=session.client, session_id=target, text=value[:30])
+    await key_press(session.client, target, "Tab")
+
+
+def combobox_value(element: ElementRef) -> str:
+    """Current value state of a select box element."""
+    for state in element.states:
+        if state.startswith('value="') and state.endswith('"'):
+            return state[len('value="') : -1]
+    return ""
+
+
+async def drag(
+    session: AgentSession, source: ElementRef, target_element: ElementRef
+) -> None:
+    """Press, graded moves, release. Both ends must share one session."""
+    if element_session(session, source) != element_session(session, target_element):
+        raise ValueError(
+            "error: invalid_input - drag ends live in different frames. "
+            "HTML5 cross-frame DnD is unsupported."
+        )
+    target = element_session(session, source)
+    x1, y1 = await element_center(session, source)
+    x2, y2 = await element_center(session, target_element)
+    client = session.client
+    await _mouse(client, target, "mouseMoved", x1, y1)
+    await _mouse(client, target, "mousePressed", x1, y1, button="left",
+                 clickCount=1)
+    for step in range(1, 13):
+        await _mouse(
+            client, target, "mouseMoved",
+            x1 + (x2 - x1) * step / 12, y1 + (y2 - y1) * step / 12,
+        )
+    await _mouse(client, target, "mouseReleased", x2, y2, button="left",
+                 clickCount=1)
+    # Synthetic mouse drags rarely complete the HTML5 drop handshake, which can
+    # leave hit-testing stuck on the last drag target (verified). Escape
+    # cancels any stuck drag operation.
+    await key_press(client, target, "Escape")
+
+
+async def upload_file(
+    session: AgentSession,
+    element: ElementRef,
+    path: str,
+    workspace_dir: str,
+) -> None:
+    """Set files on an <input type=file>. Path must live in the workspace."""
+    from pathlib import Path
+
+    candidate = Path(path).resolve()
+    root = Path(workspace_dir).resolve()
+    if root not in candidate.parents and candidate != root:
+        raise ValueError(
+            f"error: path_forbidden - {path!r} is outside the workspace. "
+            "upload_file paths must live inside the workspace."
+        )
+    if not candidate.is_file():
+        raise ValueError(f"error: file_not_found - no file at {path!r}.")
+    if "file" not in element.role and "button" not in element.role:
+        raise ValueError(
+            f"error: invalid_input - ref {element.ref} is {element.role}, "
+            "not a file input."
+        )
+    await session.client.send(
+        "DOM.setFileInputFiles",
+        {"files": [str(candidate)], "backendNodeId": element.backend_id},
+        session_id=element_session(session, element),
+    )