browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/refs/resolver.py

@@ -0,0 +1,214 @@
+"""Semantic ref resolver adapted from bridgic-browser."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from browser_cli.refs.models import LocatorSpec, RefData
+
+
+class SemanticRefResolver:
+    INTERACTIVE_ROLES = {
+        "application",
+        "alertdialog",
+        "button",
+        "checkbox",
+        "combobox",
+        "dialog",
+        "grid",
+        "gridcell",
+        "link",
+        "listbox",
+        "menu",
+        "menubar",
+        "menuitem",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "option",
+        "progressbar",
+        "radio",
+        "radiogroup",
+        "scrollbar",
+        "search",
+        "searchbox",
+        "slider",
+        "spinbutton",
+        "switch",
+        "tab",
+        "tablist",
+        "tabpanel",
+        "textbox",
+        "tree",
+        "treegrid",
+        "treeitem",
+    }
+    ROLE_TEXT_MATCH_ROLES = {
+        "cell",
+        "columnheader",
+        "gridcell",
+        "listitem",
+        "row",
+        "rowheader",
+    }
+    STRUCTURAL_NOISE_ROLES = {"generic", "group", "none", "presentation"}
+    TEXT_LEAF_ROLES = {"text"}
+    STRUCTURAL_NOISE_CSS = {
+        "generic": 'div:not([role]), legend, [role="generic"]',
+        "group": 'fieldset, details, optgroup, [role="group"]',
+        "none": '[role="none"]',
+        "presentation": '[role="presentation"]',
+    }
+    STRUCTURAL_NOISE_CSS_NAMED = {
+        **STRUCTURAL_NOISE_CSS,
+        "generic": 'div:not([role]), span:not([role]), legend, [role="generic"]',
+    }
+
+    @staticmethod
+    def parse_ref(arg: str) -> str | None:
+        raw = arg.strip()
+        if raw.startswith("@"):
+            raw = raw[1:]
+        elif raw.startswith("ref="):
+            raw = raw[4:]
+        if re.fullmatch(r"[0-9a-fA-F]{8}", raw):
+            return raw.lower()
+        return None
+
+    @staticmethod
+    def _text_pattern(value: str, *, exact: bool) -> re.Pattern[str]:
+        parts = [re.escape(part) for part in re.split(r"\s+", value.strip()) if part]
+        joined = r"\s+".join(parts) if parts else ""
+        if exact:
+            return re.compile(rf"^\s*{joined}\s*$")
+        return re.compile(joined)
+
+    def get_locator(
+        self,
+        page: Any,
+        ref_arg: str,
+        refs: dict[str, RefData],
+    ) -> Any | None:
+        locator_spec = self.build_locator_spec(ref_arg, refs)
+        if locator_spec is None:
+            return None
+        return self.get_locator_from_spec(page, locator_spec)
+
+    def get_locator_from_spec(
+        self,
+        page: Any,
+        locator_spec: LocatorSpec,
+    ) -> Any | None:
+        if not locator_spec.role:
+            return None
+
+        normalized_name = (
+            locator_spec.name.strip() if locator_spec.name and locator_spec.name.strip() else None
+        )
+        normalized_text = (
+            locator_spec.text_content.strip()
+            if locator_spec.text_content and locator_spec.text_content.strip()
+            else None
+        )
+        match_text = locator_spec.match_text
+        child_text = locator_spec.child_text
+
+        scope: Any = page
+        if locator_spec.frame_path:
+            for local_nth in locator_spec.frame_path:
+                scope = scope.frame_locator("iframe").nth(local_nth)
+
+        skip_nth = False
+
+        if (
+            normalized_name
+            and locator_spec.role not in self.ROLE_TEXT_MATCH_ROLES
+            and locator_spec.role not in self.STRUCTURAL_NOISE_ROLES
+            and locator_spec.role not in self.TEXT_LEAF_ROLES
+        ):
+            locator = scope.get_by_role(locator_spec.role, name=normalized_name, exact=True)
+        elif locator_spec.role in self.ROLE_TEXT_MATCH_ROLES and match_text:
+            if locator_spec.role == "row":
+                locator = scope.get_by_role("row").filter(
+                    has_text=self._text_pattern(match_text, exact=False)
+                )
+            else:
+                locator = scope.get_by_role(locator_spec.role).filter(
+                    has_text=self._text_pattern(match_text, exact=True)
+                )
+        elif locator_spec.role in self.TEXT_LEAF_ROLES and match_text:
+            locator = scope.get_by_text(match_text, exact=True)
+            skip_nth = True
+        elif locator_spec.role in self.STRUCTURAL_NOISE_ROLES and match_text:
+            css = self.STRUCTURAL_NOISE_CSS.get(locator_spec.role)
+            if css:
+                locator = scope.locator(css).filter(
+                    has_text=self._text_pattern(match_text, exact=True)
+                )
+            else:
+                locator = scope.get_by_text(match_text, exact=True)
+                skip_nth = True
+        elif locator_spec.role in self.STRUCTURAL_NOISE_ROLES:
+            if child_text:
+                css = self.STRUCTURAL_NOISE_CSS.get(locator_spec.role)
+                if css:
+                    locator = scope.locator(css).filter(
+                        has_text=self._text_pattern(child_text, exact=True)
+                    )
+                else:
+                    locator = scope.get_by_text(child_text, exact=True)
+                skip_nth = True
+            else:
+                locator = scope.get_by_role(locator_spec.role)
+        elif normalized_text:
+            locator = scope.get_by_text(normalized_text, exact=True)
+            skip_nth = True
+        else:
+            locator = scope.get_by_role(locator_spec.role, name=re.compile(r"^$"))
+
+        if not skip_nth and locator_spec.nth is not None:
+            locator = locator.nth(locator_spec.nth)
+        return locator
+
+    def build_locator_spec(self, ref_arg: str, refs: dict[str, RefData]) -> LocatorSpec | None:
+        ref = self.parse_ref(ref_arg)
+        if not ref:
+            return None
+        ref_data = refs.get(ref)
+        if ref_data is None:
+            return None
+        normalized_name = ref_data.name.strip() if ref_data.name and ref_data.name.strip() else None
+        normalized_text = (
+            ref_data.text_content.strip()
+            if ref_data.text_content and ref_data.text_content.strip()
+            else None
+        )
+        match_text = normalized_name or normalized_text
+        child_text = None
+        if ref_data.role in self.STRUCTURAL_NOISE_ROLES:
+            child_text = next(
+                (
+                    (child.name or child.text_content or "").strip()
+                    for child in refs.values()
+                    if child.parent_ref == ref
+                    and (
+                        child.role in self.TEXT_LEAF_ROLES
+                        or child.role in self.STRUCTURAL_NOISE_ROLES
+                    )
+                    and (child.name or child.text_content)
+                ),
+                None,
+            )
+        return LocatorSpec(
+            ref=ref,
+            role=ref_data.role,
+            name=normalized_name,
+            text_content=normalized_text,
+            match_text=match_text,
+            child_text=child_text,
+            nth=ref_data.nth,
+            tag=ref_data.tag,
+            interactive=ref_data.interactive,
+            frame_path=ref_data.frame_path,
+            selector_recipe=ref_data.selector_recipe,
+        )

browser_cli/tabs/__init__.py

@@ -0,0 +1,5 @@
+"""Tab registry primitives."""
+
+from .registry import BusyState, TabRecord, TabRegistry
+
+__all__ = ["BusyState", "TabRecord", "TabRegistry"]

browser_cli/tabs/registry.py

@@ -0,0 +1,283 @@
+"""Agent-scoped tab ownership and conflict tracking."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+
+from browser_cli.errors import BusyTabError, NoActiveTabError, TabNotFoundError
+
+
+@dataclass(slots=True)
+class BusyState:
+    request_id: str
+    command: str
+    agent_id: str
+    started_at: float
+
+
+@dataclass(slots=True)
+class TabRecord:
+    page_id: str
+    owner_agent_id: str
+    created_at: float
+    last_used_at: float
+    url: str = ""
+    title: str = ""
+    busy: BusyState | None = None
+    last_snapshot_refs: set[str] = field(default_factory=set)
+    last_snapshot_id: str | None = None
+    last_snapshot_ref_count: int = 0
+    last_snapshot_url: str = ""
+    last_snapshot_at: float | None = None
+
+
+class TabRegistry:
+    def __init__(self) -> None:
+        self._tabs: dict[str, TabRecord] = {}
+        self._active_tab_by_agent: dict[str, str] = {}
+        self._lock = asyncio.Lock()
+
+    async def add_tab(
+        self,
+        *,
+        page_id: str,
+        owner_agent_id: str,
+        url: str = "",
+        title: str = "",
+    ) -> TabRecord:
+        now = time.time()
+        async with self._lock:
+            record = TabRecord(
+                page_id=page_id,
+                owner_agent_id=owner_agent_id,
+                created_at=now,
+                last_used_at=now,
+                url=url,
+                title=title,
+            )
+            self._tabs[page_id] = record
+            self._active_tab_by_agent[owner_agent_id] = page_id
+            return record
+
+    async def update_tab(
+        self,
+        page_id: str,
+        *,
+        url: str | None = None,
+        title: str | None = None,
+        last_snapshot_refs: set[str] | None = None,
+        last_snapshot_id: str | None = None,
+        last_snapshot_ref_count: int | None = None,
+        last_snapshot_url: str | None = None,
+        last_snapshot_at: float | None = None,
+    ) -> TabRecord:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None:
+                raise TabNotFoundError()
+            record.last_used_at = time.time()
+            if url is not None:
+                record.url = url
+            if title is not None:
+                record.title = title
+            if last_snapshot_refs is not None:
+                record.last_snapshot_refs = set(last_snapshot_refs)
+            if last_snapshot_id is not None:
+                record.last_snapshot_id = last_snapshot_id
+            if last_snapshot_ref_count is not None:
+                record.last_snapshot_ref_count = last_snapshot_ref_count
+            if last_snapshot_url is not None:
+                record.last_snapshot_url = last_snapshot_url
+            if last_snapshot_at is not None:
+                record.last_snapshot_at = last_snapshot_at
+            return record
+
+    async def list_tabs(self, agent_id: str) -> list[TabRecord]:
+        async with self._lock:
+            active_page_id = self._active_tab_by_agent.get(agent_id)
+            visible = [
+                self._copy_record(record)
+                for record in self._tabs.values()
+                if record.owner_agent_id == agent_id
+            ]
+            visible.sort(key=lambda item: item.created_at)
+            if active_page_id:
+                visible.sort(key=lambda item: item.page_id != active_page_id)
+            return visible
+
+    async def has_tabs(self, agent_id: str) -> bool:
+        async with self._lock:
+            return any(record.owner_agent_id == agent_id for record in self._tabs.values())
+
+    async def get_active_tab(self, agent_id: str) -> TabRecord:
+        async with self._lock:
+            page_id = self._active_tab_by_agent.get(agent_id)
+            if page_id is None:
+                raise NoActiveTabError()
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise NoActiveTabError()
+            return self._copy_record(record)
+
+    async def set_active_tab(self, agent_id: str, page_id: str) -> TabRecord:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise TabNotFoundError()
+            self._active_tab_by_agent[agent_id] = page_id
+            record.last_used_at = time.time()
+            return self._copy_record(record)
+
+    async def get_tab(self, agent_id: str, page_id: str) -> TabRecord:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise TabNotFoundError()
+            return self._copy_record(record)
+
+    async def remove_tab(self, agent_id: str, page_id: str) -> TabRecord:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise TabNotFoundError()
+            removed = self._tabs.pop(page_id)
+            active_page_id = self._active_tab_by_agent.get(agent_id)
+            if active_page_id == page_id:
+                replacement = self._find_latest_page_id_locked(agent_id)
+                if replacement is None:
+                    self._active_tab_by_agent.pop(agent_id, None)
+                else:
+                    self._active_tab_by_agent[agent_id] = replacement
+            return self._copy_record(removed)
+
+    async def current_active_page_id(self, agent_id: str) -> str:
+        return (await self.get_active_tab(agent_id)).page_id
+
+    async def snapshot_state(self) -> tuple[list[TabRecord], dict[str, str]]:
+        async with self._lock:
+            records = [self._copy_record(record) for record in self._tabs.values()]
+            records.sort(key=lambda item: item.created_at)
+            return records, dict(self._active_tab_by_agent)
+
+    async def replace_tab_ids(self, replacements: dict[str, str]) -> None:
+        if not replacements:
+            return
+        async with self._lock:
+            new_tabs: dict[str, TabRecord] = {}
+            for old_page_id, record in list(self._tabs.items()):
+                new_page_id = replacements.get(old_page_id, old_page_id)
+                new_record = self._copy_record(record)
+                new_record.page_id = new_page_id
+                new_tabs[new_page_id] = new_record
+            self._tabs = new_tabs
+            for agent_id, page_id in list(self._active_tab_by_agent.items()):
+                self._active_tab_by_agent[agent_id] = replacements.get(page_id, page_id)
+
+    async def clear_snapshot_state(self) -> None:
+        async with self._lock:
+            for record in self._tabs.values():
+                record.last_snapshot_refs = set()
+                record.last_snapshot_id = None
+                record.last_snapshot_ref_count = 0
+                record.last_snapshot_url = ""
+                record.last_snapshot_at = None
+
+    async def clear(self) -> None:
+        async with self._lock:
+            self._tabs.clear()
+            self._active_tab_by_agent.clear()
+
+    async def is_visible(self, agent_id: str, page_id: str) -> bool:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            return bool(record and record.owner_agent_id == agent_id)
+
+    @asynccontextmanager
+    async def claim_active_tab(
+        self,
+        *,
+        agent_id: str,
+        request_id: str,
+        command: str,
+    ) -> AsyncIterator[TabRecord]:
+        page_id: str
+        async with self._lock:
+            page_id = self._active_tab_by_agent.get(agent_id, "")
+            if not page_id:
+                raise NoActiveTabError()
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise NoActiveTabError()
+            if record.busy and record.busy.request_id != request_id:
+                raise BusyTabError()
+            record.busy = BusyState(
+                request_id=request_id,
+                command=command,
+                agent_id=agent_id,
+                started_at=time.time(),
+            )
+            record.last_used_at = time.time()
+            claimed = self._copy_record(record)
+        try:
+            yield claimed
+        finally:
+            await self.release_tab(page_id=page_id, request_id=request_id)
+
+    async def claim_page(
+        self,
+        *,
+        agent_id: str,
+        page_id: str,
+        request_id: str,
+        command: str,
+    ) -> TabRecord:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None or record.owner_agent_id != agent_id:
+                raise TabNotFoundError()
+            if record.busy and record.busy.request_id != request_id:
+                raise BusyTabError()
+            record.busy = BusyState(
+                request_id=request_id,
+                command=command,
+                agent_id=agent_id,
+                started_at=time.time(),
+            )
+            record.last_used_at = time.time()
+            return self._copy_record(record)
+
+    async def release_tab(self, *, page_id: str, request_id: str) -> None:
+        async with self._lock:
+            record = self._tabs.get(page_id)
+            if record is None:
+                return
+            if record.busy and record.busy.request_id == request_id:
+                record.busy = None
+
+    def _find_latest_page_id_locked(self, agent_id: str) -> str | None:
+        candidates = [record for record in self._tabs.values() if record.owner_agent_id == agent_id]
+        if not candidates:
+            return None
+        candidates.sort(key=lambda item: item.last_used_at, reverse=True)
+        return candidates[0].page_id
+
+    @staticmethod
+    def _copy_record(record: TabRecord) -> TabRecord:
+        return TabRecord(
+            page_id=record.page_id,
+            owner_agent_id=record.owner_agent_id,
+            created_at=record.created_at,
+            last_used_at=record.last_used_at,
+            url=record.url,
+            title=record.title,
+            busy=record.busy,
+            last_snapshot_refs=set(record.last_snapshot_refs),
+            last_snapshot_id=record.last_snapshot_id,
+            last_snapshot_ref_count=record.last_snapshot_ref_count,
+            last_snapshot_url=record.last_snapshot_url,
+            last_snapshot_at=record.last_snapshot_at,
+        )

browser_cli/task_runtime/__init__.py

@@ -0,0 +1,31 @@
+"""Thin Python runtime for Browser CLI-backed tasks."""
+
+from browser_cli.task_runtime.client import BrowserCliTaskClient
+from browser_cli.task_runtime.entrypoint import (
+    load_task_entrypoint,
+    parse_input_overrides,
+    run_task_entrypoint,
+    validate_task_dir,
+)
+from browser_cli.task_runtime.flow import Flow
+from browser_cli.task_runtime.models import (
+    FlowContext,
+    SnapshotRef,
+    SnapshotResult,
+    validate_task_metadata,
+)
+from browser_cli.task_runtime.read import ReadResult
+
+__all__ = [
+    "BrowserCliTaskClient",
+    "Flow",
+    "FlowContext",
+    "ReadResult",
+    "SnapshotRef",
+    "SnapshotResult",
+    "load_task_entrypoint",
+    "parse_input_overrides",
+    "run_task_entrypoint",
+    "validate_task_dir",
+    "validate_task_metadata",
+]

browser_cli/task_runtime/client.py

@@ -0,0 +1,107 @@
+"""Thin Browser CLI Python client for task execution."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from browser_cli.daemon.client import send_command
+from browser_cli.profiles.discovery import ChromeEnvironment
+from browser_cli.task_runtime.models import SnapshotResult
+from browser_cli.task_runtime.read import ReadRequest, ReadResult, run_read_request
+
+
+class BrowserCliTaskClient:
+    def __init__(self, *, chrome_environment: ChromeEnvironment | None = None) -> None:
+        self._chrome_environment = chrome_environment
+
+    def invoke(self, action: str, **args: Any) -> dict[str, Any]:
+        response = send_command(action, args)
+        return dict(response.get("data") or {})
+
+    def command(self, action: str, **args: Any) -> dict[str, Any]:
+        return self.invoke(action, **args)
+
+    def read(
+        self,
+        url: str,
+        *,
+        output_mode: str = "html",
+        scroll_bottom: bool = False,
+    ) -> ReadResult:
+        return asyncio.run(
+            run_read_request(
+                ReadRequest(
+                    url=url,
+                    output_mode=output_mode,
+                    scroll_bottom=scroll_bottom,
+                ),
+                chrome_environment=self._chrome_environment,
+            )
+        )
+
+    def open(self, url: str) -> dict[str, Any]:
+        return self.invoke("open", url=url).get("page", {})
+
+    def search(self, query: str, *, engine: str = "duckduckgo") -> dict[str, Any]:
+        return self.invoke("search", query=query, engine=engine).get("page", {})
+
+    def snapshot(self, *, interactive: bool = False, full_page: bool = True) -> SnapshotResult:
+        return SnapshotResult.from_payload(
+            self.invoke("snapshot", interactive=interactive, full_page=full_page)
+        )
+
+    def html(self) -> str:
+        return str(self.invoke("html").get("html") or "")
+
+    def click(self, ref: str) -> dict[str, Any]:
+        return self.invoke("click", ref=ref)
+
+    def fill(self, ref: str, text: str, *, submit: bool = False) -> dict[str, Any]:
+        return self.invoke("fill", ref=ref, text=text, submit=submit)
+
+    def select(self, ref: str, text: str) -> dict[str, Any]:
+        return self.invoke("select", ref=ref, text=text)
+
+    def check(self, ref: str) -> dict[str, Any]:
+        return self.invoke("check", ref=ref)
+
+    def uncheck(self, ref: str) -> dict[str, Any]:
+        return self.invoke("uncheck", ref=ref)
+
+    def focus(self, ref: str) -> dict[str, Any]:
+        return self.invoke("focus", ref=ref)
+
+    def hover(self, ref: str) -> dict[str, Any]:
+        return self.invoke("hover", ref=ref)
+
+    def wait(self, seconds: float) -> dict[str, Any]:
+        return self.invoke("wait", seconds=seconds)
+
+    def wait_text(
+        self, text: str, *, timeout: float = 5.0, gone: bool = False, exact: bool = False
+    ) -> dict[str, Any]:
+        return self.invoke("wait", seconds=timeout, text=text, gone=gone, exact=exact)
+
+    def eval(self, code: str) -> Any:
+        return self.invoke("eval", code=code).get("result")
+
+    def eval_on(self, ref: str, code: str) -> Any:
+        return self.invoke("eval-on", ref=ref, code=code).get("result")
+
+    def verify_text(
+        self, text: str, *, exact: bool = False, timeout: float = 5.0
+    ) -> dict[str, Any]:
+        return self.invoke("verify-text", text=text, exact=exact, timeout=timeout)
+
+    def verify_state(self, ref: str, state: str) -> dict[str, Any]:
+        return self.invoke("verify-state", ref=ref, state=state)
+
+    def verify_value(self, ref: str, expected: str) -> dict[str, Any]:
+        return self.invoke("verify-value", ref=ref, expected=expected)
+
+    def screenshot(self, path: str, *, full_page: bool = False) -> dict[str, Any]:
+        return self.invoke("screenshot", path=path, full_page=full_page)
+
+    def close(self) -> dict[str, Any]:
+        return self.invoke("close")