mobilerun-core 0.3.0__py3-none-any.whl

mobilerun_core/__init__.py

@@ -0,0 +1,14 @@
+from mobilerun_core.connection import UnsupportedOperation
+from mobilerun_core.device import Device, DeviceHandle
+from mobilerun_core.hitl import HitlDenied, HitlGate
+from mobilerun_core.mobilerun import Mobilerun
+
+__all__ = [
+    "Mobilerun",
+    "Device",
+    "DeviceHandle",
+    "HitlGate",
+    "HitlDenied",
+    "UnsupportedOperation",
+]
+__version__ = "0.3.0"

mobilerun_core/_a11y.py

@@ -0,0 +1,197 @@
+"""A11y-tree walking and geometry helpers. Pure functions; no I/O.
+
+Split out of `device.py` so the public `Device` class stays focused on
+the device-control verbs. Imported by `Device.find_nodes`, `tap_node`,
+`screen_size`, `wait_for_idle`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator
+
+from mobilerun_core._utils import to_dict
+
+_TEXT_FIELDS = ("text",)
+_DESC_FIELDS = ("contentDescription", "content_description")
+_RID_FIELDS = ("resourceId", "resource_id", "accessibilityIdentifier")
+_CLASS_FIELDS = ("className", "class_name")
+_ANY_TEXT_FIELDS = _TEXT_FIELDS + _DESC_FIELDS + _RID_FIELDS
+
+_BOUNDS_FIELDS = (
+    "bounds",
+    "boundsInScreen",
+    "bounds_in_screen",
+    "rect",
+    "frame",
+)
+
+
+def normalize_tree(tree: Any) -> Any:
+    """Strip timestamp-ish fields so wait_for_idle doesn't see false diffs."""
+    d = to_dict(tree)
+    if isinstance(d, dict):
+        return {k: v for k, v in d.items() if k not in ("timestamp", "capturedAt")}
+    return d
+
+
+def walk_a11y(tree: Any) -> Iterator[dict[str, Any]]:
+    """Yield every node in the a11y tree. Accepts either a full UI response
+    (descends into `a11y_tree`) or a raw subtree. Tolerates top-level
+    `tree` / `root` / `nodes` containers, alternate response shapes."""
+    root = to_dict(tree)
+    if isinstance(root, dict) and "a11y_tree" in root:
+        root = to_dict(root["a11y_tree"])
+    if isinstance(root, dict):
+        for container in ("tree", "root", "nodes"):
+            v = root.get(container)
+            if isinstance(v, list):
+                yield from _visit_nodes(v)
+                return
+    yield from _visit_nodes(root)
+
+
+def _visit_nodes(node: Any) -> Iterator[dict[str, Any]]:
+    node = to_dict(node)
+    if isinstance(node, list):
+        for n in node:
+            yield from _visit_nodes(n)
+        return
+    if not isinstance(node, dict):
+        return
+    yield node
+    for child_field in ("children", "nodes", "subviews"):
+        children = node.get(child_field)
+        if children:
+            yield from _visit_nodes(children)
+
+
+def find_nodes(
+    tree: Any,
+    *,
+    text: str | None,
+    desc: str | None,
+    resource_id: str | None,
+    class_name: str | None,
+    text_contains: str | None,
+    desc_contains: str | None,
+    any_contains: str | None,
+) -> list[dict[str, Any]]:
+    results: list[dict[str, Any]] = []
+    for node in walk_a11y(tree):
+        if not _matches(node, _TEXT_FIELDS, text, text_contains):
+            continue
+        if not _matches(node, _DESC_FIELDS, desc, desc_contains):
+            continue
+        if not _matches(node, _RID_FIELDS, resource_id, None):
+            continue
+        if not _matches(node, _CLASS_FIELDS, class_name, None):
+            continue
+        if not _matches(node, _ANY_TEXT_FIELDS, None, any_contains):
+            continue
+        annotated = dict(node)
+        center = bounds_center(node_bounds(node))
+        if center is not None:
+            annotated["center"] = center
+        results.append(annotated)
+    return results
+
+
+def _node_field(node: dict[str, Any], *names: str) -> str | None:
+    for n in names:
+        v = node.get(n)
+        if isinstance(v, str):
+            return v
+    return None
+
+
+def _matches(
+    node: dict[str, Any],
+    fields: tuple[str, ...],
+    exact: str | None,
+    contains: str | None,
+) -> bool:
+    if exact is None and contains is None:
+        return True
+    value = _node_field(node, *fields)
+    if exact is not None and value != exact:
+        return False
+    if contains is not None and (
+        value is None or contains.lower() not in value.lower()
+    ):
+        return False
+    return True
+
+
+def node_bounds(node: dict[str, Any]) -> Any:
+    for name in _BOUNDS_FIELDS:
+        v = node.get(name)
+        if v:
+            return v
+    return None
+
+
+def bounds_center(bounds: Any) -> tuple[int, int] | None:
+    bounds = to_dict(bounds)
+    if not isinstance(bounds, dict):
+        return None
+    if "width" in bounds and "x" in bounds:
+        return (
+            int(bounds["x"]) + int(bounds["width"]) // 2,
+            int(bounds["y"]) + int(bounds["height"]) // 2,
+        )
+    if "right" in bounds and "left" in bounds:
+        return (
+            (int(bounds["left"]) + int(bounds["right"])) // 2,
+            (int(bounds["top"]) + int(bounds["bottom"])) // 2,
+        )
+    return None
+
+
+def _rect_dims(rect: Any) -> tuple[int, int] | None:
+    rect = to_dict(rect)
+    if not isinstance(rect, dict):
+        return None
+    if "width" in rect and "height" in rect:
+        w, h = int(rect["width"]), int(rect["height"])
+        return (w, h) if w > 0 and h > 0 else None
+    if all(k in rect for k in ("left", "right", "top", "bottom")):
+        w = int(rect["right"]) - int(rect["left"])
+        h = int(rect["bottom"]) - int(rect["top"])
+        return (w, h) if w > 0 and h > 0 else None
+    return None
+
+
+def probe_screen_dims(ui_response: Any) -> tuple[int, int] | None:
+    """Walk the UI response for usable (width, height). Tries
+    display_metrics first (canonical), then screen_bounds / screen_size,
+    and finally the a11y root's boundsInScreen as last resort."""
+    resp = to_dict(ui_response)
+    if not isinstance(resp, dict):
+        return None
+
+    ctx = resp.get("device_context") or {}
+    dm = ctx.get("display_metrics") or {}
+    w = _safe_int(dm.get("widthPixels") or dm.get("width_pixels"))
+    h = _safe_int(dm.get("heightPixels") or dm.get("height_pixels"))
+    if w and h:
+        return (w, h)
+
+    for key in ("screen_bounds", "screenBounds", "screen_size", "screenSize"):
+        dims = _rect_dims(ctx.get(key))
+        if dims:
+            return dims
+
+    a11y = resp.get("a11y_tree")
+    if isinstance(a11y, dict):
+        dims = _rect_dims(node_bounds(a11y))
+        if dims:
+            return dims
+    return None
+
+
+def _safe_int(v: Any) -> int | None:
+    try:
+        n = int(v)
+    except (TypeError, ValueError):
+        return None
+    return n if n > 0 else None

mobilerun_core/_utils.py

@@ -0,0 +1,12 @@
+"""Internal utilities shared across modules. Not part of the public API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def to_dict(obj: Any) -> Any:
+    """Coerce a Pydantic-ish model into a plain dict; pass dicts through."""
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()
+    return obj

mobilerun_core/connection/__init__.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from mobilerun_core.connection._unsupported import UnsupportedOperation, unsupported_on
+
+ConnectionKind = Literal["cloud", "framework"]
+
+DEFAULT_SWIPE_MS = 300
+
+# Android KeyEvent codes. Shared between Device (string→int mapping) and
+# the cloud connection (forwards the int to the SDK). Local connections
+# will pass the same int to ADB shell `input keyevent`.
+# https://developer.android.com/reference/android/view/KeyEvent
+KEY_CODES: dict[str, int] = {
+    "back": 4,
+    "home": 3,
+    "menu": 82,
+    "enter": 66,
+    "delete": 67,
+    "escape": 111,
+    "tab": 61,
+    "space": 62,
+    "search": 84,
+    "page_up": 92,
+    "page_down": 93,
+    "volume_up": 24,
+    "volume_down": 25,
+    "power": 26,
+    "media_play_pause": 85,
+    "media_next": 87,
+    "media_prev": 88,
+}
+
+
+@runtime_checkable
+class Connection(Protocol):
+    """Sync per-device contract.
+
+    One Connection instance == one device. The two implementations live
+    next to this Protocol: `MobilerunCloud` (wraps mobilerun-sdk) and
+    `MobilerunFramework` (wraps mobilerun-core-cli). Helpers on `Device`
+    consume this Protocol exclusively — they never touch SDK/CLI types.
+
+    Return-shape normalization is the Connection's job:
+    - `ui()` returns a plain dict (not a Pydantic model)
+    - `screenshot()` returns a base64-encoded PNG string
+    """
+
+    device_id: str
+
+    # -- state / observation ------------------------------------------------
+
+    def ui(self, *, filter: bool = True) -> dict[str, Any]: ...
+    def screenshot(self, *, hide_overlay: bool = False) -> str: ...
+    def time(self) -> str: ...
+
+    # -- input actions ------------------------------------------------------
+
+    def tap(self, x: int, y: int, *, stealth: bool = True) -> None: ...
+    def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        ms: int = DEFAULT_SWIPE_MS,
+    ) -> None: ...
+    def type(
+        self,
+        text: str,
+        *,
+        clear: bool = False,
+        wpm: int | None = None,
+        stealth: bool = True,
+    ) -> None: ...
+    def key(self, name_or_code: str | int) -> None: ...
+    def clear_input(self) -> None: ...
+
+    # -- app management -----------------------------------------------------
+
+    def app_start(self, package: str, *, activity: str | None = None) -> None: ...
+    def app_stop(self, package: str) -> None: ...
+    def app_install_apk(
+        self,
+        apk_path: str,
+        *,
+        replace: bool = False,
+        grant_permissions: bool = True,
+    ) -> None: ...
+    def app_uninstall(self, package: str) -> None: ...
+    def app_list(
+        self,
+        *,
+        include_system_apps: bool = False,
+        include_protected_apps: bool = False,
+    ) -> list[dict[str, Any]]: ...
+
+
+__all__ = [
+    "Connection",
+    "ConnectionKind",
+    "DEFAULT_SWIPE_MS",
+    "KEY_CODES",
+    "UnsupportedOperation",
+    "unsupported_on",
+]

mobilerun_core/connection/_unsupported.py

@@ -0,0 +1,141 @@
+"""Agent-friendly unsupported-operation signaling.
+
+The `Connection` Protocol is one surface, but each backend supports only
+a subset of verbs by design (cloud has store-installs but no APK paths;
+framework has APK paths but no store). Instead of raw
+`NotImplementedError("nope")`, unsupported verbs raise a typed
+`UnsupportedOperation` carrying structured fields an agent can inspect
+to recover automatically — verb, backend, alternative verb, and hint.
+
+Usage on a backend method:
+
+    class MobilerunCloud:
+        @unsupported_on(
+            backend="cloud",
+            alternative="app_install_store",
+            reason="Cloud devices can only install from the store.",
+            hint="Pass a package_name or bundle_id to app_install_store.",
+        )
+        def app_install_apk(self, apk_path, *, replace=False,
+                            grant_permissions=True):
+            ...
+
+The body is never executed — the decorator replaces it with a raise. The
+original signature, annotations, and docstring are preserved so
+introspection (help, IDEs, schema generators) still works.
+
+Inspect supported/unsupported verbs at runtime:
+
+    UnsupportedOperation.is_supported(MobilerunCloud, "app_install_apk")
+    UnsupportedOperation.describe(MobilerunCloud, "app_install_apk")
+"""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable
+
+
+class UnsupportedOperation(NotImplementedError):
+    """Raised when a backend doesn't support a verb defined on the
+    `Connection` Protocol. Subclasses `NotImplementedError` so existing
+    `except NotImplementedError:` callers keep working.
+
+    Fields:
+        verb         the Connection verb that was called
+        backend      "cloud" | "framework" (or other backend tag)
+        reason       short human-readable explanation
+        alternative  the verb to use instead, if any
+        hint         longer agent-targeted guidance, if any
+    """
+
+    def __init__(
+        self,
+        *,
+        verb: str,
+        backend: str,
+        reason: str,
+        alternative: str | None = None,
+        hint: str | None = None,
+    ) -> None:
+        self.verb = verb
+        self.backend = backend
+        self.reason = reason
+        self.alternative = alternative
+        self.hint = hint
+        super().__init__(self._format())
+
+    def _format(self) -> str:
+        parts = [f"{self.verb!r} is not supported on backend={self.backend!r}: {self.reason}"]
+        if self.alternative:
+            parts.append(f"Use {self.alternative!r} instead.")
+        if self.hint:
+            parts.append(self.hint)
+        return " ".join(parts)
+
+    def as_dict(self) -> dict[str, Any]:
+        """Structured payload an agent can parse to pick a recovery path."""
+        return {
+            "error": "unsupported_operation",
+            "verb": self.verb,
+            "backend": self.backend,
+            "reason": self.reason,
+            "alternative": self.alternative,
+            "hint": self.hint,
+        }
+
+    @staticmethod
+    def is_supported(cls_or_instance: Any, verb: str) -> bool:
+        """True iff `verb` exists on the target and is NOT marked unsupported."""
+        fn = getattr(cls_or_instance, verb, None)
+        if fn is None:
+            return False
+        return not getattr(fn, "__unsupported__", False)
+
+    @staticmethod
+    def describe(cls_or_instance: Any, verb: str) -> dict[str, Any] | None:
+        """Return the unsupported-annotation dict for `verb`, or None
+        if the verb is supported (or doesn't exist)."""
+        fn = getattr(cls_or_instance, verb, None)
+        if fn is None or not getattr(fn, "__unsupported__", False):
+            return None
+        return dict(fn.__unsupported_meta__)
+
+
+_DEFAULT_REASON = "this backend does not support this operation"
+
+
+def unsupported_on(
+    backend: str,
+    *,
+    reason: str | None = None,
+    alternative: str | None = None,
+    hint: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator marking a backend method as design-time unsupported.
+
+    The decorated function never runs — calls raise `UnsupportedOperation`
+    carrying the annotation. Only `backend` is required; everything else
+    falls back to sensible defaults. The original signature is preserved
+    via `functools.wraps`.
+    """
+    meta = {
+        "backend": backend,
+        "reason": reason or _DEFAULT_REASON,
+        "alternative": alternative,
+        "hint": hint,
+    }
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(fn)
+        def wrapper(*_args: Any, **_kwargs: Any) -> Any:
+            raise UnsupportedOperation(verb=fn.__name__, **meta)
+
+        wrapper.__unsupported__ = True  # type: ignore[attr-defined]
+        wrapper.__unsupported_meta__ = {"verb": fn.__name__, **meta}  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate
+
+
+__all__ = ["UnsupportedOperation", "unsupported_on"]

mobilerun_core/connection/cloud.py

@@ -0,0 +1,194 @@
+"""Cloud connection over `mobilerun-sdk`.
+
+Self-contained: bearer holder and SDK factory live in this module as
+private helpers. There is no separate `bearer.py` or `_sdk.py` — auth is
+a cloud-only concern and stays where it's used.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time as _time
+from functools import wraps
+from typing import Any
+
+from mobilerun_core._utils import to_dict
+from mobilerun_core.connection import DEFAULT_SWIPE_MS, KEY_CODES, unsupported_on
+
+_READ_RETRY_DELAYS = (0.5, 1.5)
+
+# Cloud-auth env vars. Public so detect.py can name them in error
+# messages and `cloud_creds_present()` checks.
+BEARER_ENV_VAR = "MOBILERUN_CLOUD_API_KEY"
+BASE_URL_ENV_VAR = "MOBILERUN_API_BASE_URL"
+
+
+class Bearer:
+    """Lock-protected holder for the upstream cloud bearer."""
+
+    def __init__(self, initial: str) -> None:
+        if not initial:
+            raise ValueError("Bearer requires a non-empty initial value")
+        self._value = initial
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_env(cls) -> "Bearer":
+        val = os.environ.get(BEARER_ENV_VAR)
+        if not val:
+            raise RuntimeError(f"no bearer in env (${BEARER_ENV_VAR})")
+        return cls(val)
+
+    def get(self) -> str:
+        with self._lock:
+            return self._value
+
+    def set(self, new_value: str) -> None:
+        if not new_value:
+            raise ValueError("refusing to set empty bearer")
+        with self._lock:
+            self._value = new_value
+
+
+def make_sdk_client(bearer: Bearer | str, base_url: str) -> Any:
+    """Build the upstream `mobilerun-sdk` client. SDK turns `api_key`
+    into `Authorization: Bearer <token>`."""
+    from mobilerun_sdk import Mobilerun as _SDK
+    token = bearer.get() if isinstance(bearer, Bearer) else bearer
+    if not token:
+        raise ValueError("make_sdk_client: bearer is empty")
+    return _SDK(api_key=token, base_url=base_url)
+
+
+def _transient_read_excs() -> tuple[type[BaseException], ...]:
+    from mobilerun_sdk import APIConnectionError, APITimeoutError, InternalServerError
+    return (InternalServerError, APIConnectionError, APITimeoutError)
+
+
+def _retry_transient_read(fn):
+    @wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        excs = _transient_read_excs()
+        for delay in (*_READ_RETRY_DELAYS, None):
+            try:
+                return fn(*args, **kwargs)
+            except excs:
+                if delay is None:
+                    raise
+                _time.sleep(delay)
+    return wrapper
+
+
+class MobilerunCloud:
+    """Cloud-backed `Connection`. One instance == one cloud device."""
+
+    def __init__(self, sdk_client: Any, device_id: str) -> None:
+        self.device_id = device_id
+        self._sdk = sdk_client
+
+    # -- state / observation ------------------------------------------------
+
+    @_retry_transient_read
+    def ui(self, *, filter: bool = True) -> dict[str, Any]:
+        resp = self._sdk.devices.state.ui(self.device_id, filter=filter)
+        out = to_dict(resp)
+        return out if isinstance(out, dict) else {}
+
+    @_retry_transient_read
+    def screenshot(self, *, hide_overlay: bool = False) -> str:
+        return self._sdk.devices.state.screenshot(
+            self.device_id, hide_overlay=hide_overlay
+        )
+
+    @_retry_transient_read
+    def time(self) -> str:
+        return self._sdk.devices.state.time(self.device_id)
+
+    # -- input actions ------------------------------------------------------
+
+    def tap(self, x: int, y: int, *, stealth: bool = True) -> None:
+        self._sdk.devices.actions.tap(self.device_id, x=x, y=y, stealth=stealth)
+
+    def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        ms: int = DEFAULT_SWIPE_MS,
+    ) -> None:
+        self._sdk.devices.actions.swipe(
+            self.device_id,
+            start_x=x1,
+            start_y=y1,
+            end_x=x2,
+            end_y=y2,
+            duration=ms,
+        )
+
+    def type(
+        self,
+        text: str,
+        *,
+        clear: bool = False,
+        wpm: int | None = None,
+        stealth: bool = True,
+    ) -> None:
+        kwargs: dict[str, Any] = {"text": text, "clear": clear, "stealth": stealth}
+        if wpm is not None:
+            kwargs["wpm"] = wpm
+        self._sdk.devices.keyboard.write(self.device_id, **kwargs)
+
+    def key(self, name_or_code: str | int) -> None:
+        if isinstance(name_or_code, int):
+            code = name_or_code
+        else:
+            code = KEY_CODES.get(name_or_code.lower())
+            if code is None:
+                raise ValueError(
+                    f"key: unknown name {name_or_code!r}; pass an int "
+                    f"KeyEvent code or one of {sorted(KEY_CODES)}"
+                )
+        self._sdk.devices.keyboard.key(self.device_id, key=code)
+
+    def clear_input(self) -> None:
+        self._sdk.devices.keyboard.clear(self.device_id)
+
+    # -- app management -----------------------------------------------------
+
+    def app_start(self, package: str, *, activity: str | None = None) -> None:
+        kwargs: dict[str, Any] = {"device_id": self.device_id}
+        if activity is not None:
+            kwargs["activity"] = activity
+        self._sdk.devices.apps.start(package, **kwargs)
+
+    def app_stop(self, package: str) -> None:
+        self._sdk.devices.apps.update(package, device_id=self.device_id)
+
+    @unsupported_on(
+        backend="cloud"
+    )
+    def app_install_apk(
+        self,
+        apk_path: str,
+        *,
+        replace: bool = False,
+        grant_permissions: bool = True,
+    ) -> None: ...
+
+    def app_uninstall(self, package: str) -> None:
+        self._sdk.devices.apps.delete(package, device_id=self.device_id)
+
+    def app_list(
+        self,
+        *,
+        include_system_apps: bool = False,
+        include_protected_apps: bool = False,
+    ) -> list[dict[str, Any]]:
+        resp = self._sdk.devices.apps.list(
+            self.device_id,
+            include_system_apps=include_system_apps,
+            include_protected_apps=include_protected_apps,
+        )
+        return [to_dict(item) for item in (resp or [])]