mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/alerts.py

@@ -0,0 +1,337 @@
+"""Alerts: a webhook post when a scheduled task fails, stops or waits on an approval for a minute, and when a phone
+needs you (fleet_health.py: unplugged, locked, signed out, a security check, a region that doesn't match).
+
+Opt-in: nothing is sent until MOBSTER_ALERT_WEBHOOK_URL holds an https address (Settings in the Mac app, or
+the env file). The post is shaped for the service the address belongs to: Slack ({"text"}), Discord
+({"content"}), ntfy (plain text with a Title header), or anything else as JSON {workflow, status, reason, runId,
+at, text}. It never carries the task's answer, a screenshot, typed text or any secret: the reason is one of
+Mobster's own fixed sentences, chosen by the run's status. A phone alert names the phone and, for a profile, its
+handle: the sentences are fixed, the names are the ones you gave.
+
+Delivery never blocks or fails a run: it happens on its own thread, tries twice with a 5-second limit each, and
+gives up quietly. Addresses on this Mac's network (localhost, private, link-local and reserved addresses, .local
+names) are refused, the name is resolved once and that address is the one connected to, and redirects are not
+followed, so an alert can't be turned against something on the local network.
+
+`mobster alerts test` sends a test post (``add_arguments`` and ``run``, registered by devtools.py).
+"""
+
+import datetime
+import http.client
+import ipaddress
+import json
+import os
+import socket
+import ssl
+import sys
+import threading
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+ENV = "MOBSTER_ALERT_WEBHOOK_URL"
+TIMEOUT = 5.0
+ATTEMPTS = 2
+RETRY_PAUSE = 1.0
+APPROVAL_WAIT_S = 60
+# Statuses that need no alert: it worked, or the user ended it themselves.
+QUIET = frozenset({"completed", "stopped", "approval_denied", "demo_complete", "queued", "running"})
+REASONS = {
+    "blocked": "It couldn't finish the task.",
+    "max_steps": "It ran out of steps.",
+    "timeout": "It ran out of time.",
+    "spend_cap": "It reached its spending limit.",
+    "approval_timeout": "Nobody answered its approval in time.",
+    "approval_waiting": "It is waiting for your approval.",
+    "interrupted": "Mobster stopped while it ran.",
+    "run_expired": "Its task was deleted or left the history after the run finished, before Mobster read how it ended.",
+    "error": "It hit an error.",
+    "failed": "It failed.",
+    "test": "This is a test alert from Mobster.",
+}
+# Why a run stopped before it began, when the phone guard says (agent_hooks.GuardVerdict.code).
+CODES = {
+    "phone_locked": "Your iPhone was locked.",
+    "passcode_failed": "The saved passcode didn't unlock your iPhone.",
+    "face_id": "An app asked for Face ID.",
+    "app_locked": "The app is locked on your iPhone.",
+    "apple_confirmation": "The App Store wanted you to confirm on your iPhone.",
+    "unplugged": "Your iPhone was unplugged.",
+    "keychain_locked": "Your Mac's Keychain was locked.",
+    "unlock_declined": "Unlocking the iPhone was declined.",
+    "blocked_app": "The task needed an app you told Mobster never to open.",
+    "system_dialog": "Your iPhone asked a question only you can answer.",
+}
+LOCAL_SUFFIXES = (".local", ".localhost", ".internal", ".lan", ".home.arpa", ".intranet", ".corp")
+
+
+class AlertError(ValueError):
+    """Why an address can't take alerts, in one plain sentence."""
+
+
+def validate_url(url):
+    """``url`` trimmed when it can take alerts (https, a name or a public address); names are checked at each send."""
+    text = str(url or "").strip()
+    if not text:
+        raise AlertError("Give the webhook's address.")
+    if len(text) > 2000 or any(ord(c) < 33 for c in text):
+        raise AlertError("That webhook address isn't valid.")
+    parts = urlsplit(text)
+    if parts.scheme.lower() != "https":
+        raise AlertError("Alerts go only to https addresses.")
+    if parts.username or parts.password:
+        raise AlertError("Put the webhook's secret in its path, not as user:password@.")
+    host = (parts.hostname or "").rstrip(".").lower()
+    if not host:
+        raise AlertError("That webhook address has no host.")
+    if host == "localhost" or host.endswith(LOCAL_SUFFIXES) or "." not in host and not _literal(host):
+        raise AlertError("Alerts never go to this Mac or its local network.")
+    address = _literal(host)
+    if address is not None and not _public(address):
+        raise AlertError("Alerts never go to this Mac or its local network.")
+    try:
+        parts.port
+    except ValueError:
+        raise AlertError("That webhook address has a bad port.") from None
+    return text
+
+
+def _literal(host):
+    try:
+        return ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return None
+
+
+def _public(address):
+    """Reachable on the internet; ``is_global`` also rules out shared 100.64.0.0/10 (Tailscale, carrier NAT)."""
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        address = address.ipv4_mapped
+    return address.is_global and not (address.is_private or address.is_loopback or address.is_link_local
+                                      or address.is_multicast or address.is_reserved or address.is_unspecified
+                                      or getattr(address, "is_site_local", False))
+
+
+def resolve_public(host, port, resolve=socket.getaddrinfo):
+    """The address to connect to: every address ``host`` resolves to must be public; the first is used."""
+    try:
+        infos = resolve(host, port, type=socket.SOCK_STREAM)
+    except (OSError, UnicodeError):
+        raise AlertError(f"{host} couldn't be found.") from None
+    addresses = [info[4][0] for info in infos]
+    if not addresses or not all(_public(ipaddress.ip_address(a.split("%")[0])) for a in addresses):
+        raise AlertError("Alerts never go to this Mac or its local network.")
+    return addresses[0]
+
+
+def configured_url(env=None, data_dir=None, read_file=False):
+    """The alert address: $MOBSTER_ALERT_WEBHOOK_URL, else (``read_file``) the Mac app's agent.env, else None."""
+    env = os.environ if env is None else env
+    value = (env.get(ENV) or "").strip()
+    if value:
+        return value
+    if not read_file:
+        return None
+    try:
+        from . import env_secrets
+        from .config import read_env_values
+        from .paths import user_data_dir
+        file = (Path(data_dir) if data_dir else user_data_dir()) / "agent.env"
+        # Mobster for Mac keeps the address in the Keychain: it's a credential for Slack and Discord (env_secrets.py).
+        # The file's own value comes first, so `mobster alerts test` only reads the Keychain when it must.
+        return read_env_values(file).get(ENV) or env_secrets.load(file).get(ENV) or None
+    except (OSError, UnicodeDecodeError, ImportError):
+        return None
+
+
+def reason_for(status, code=None):
+    if code in CODES:
+        return CODES[code]
+    return REASONS.get(status, "It didn't finish.")
+
+
+def payload(workflow, status, run_id=None, code=None, at=None):
+    """The alert: never the answer, a screenshot or anything the task typed."""
+    at = time.time() if at is None else at
+    name = " ".join(str(workflow or "Saved task").split())[:120]
+    return {"workflow": name, "status": str(status)[:40], "reason": reason_for(status, code),
+            "runId": str(run_id)[:40] if run_id else None,
+            "at": datetime.datetime.fromtimestamp(at, datetime.timezone.utc).isoformat(timespec="seconds")}
+
+
+def phone_payload(phone, code, message, action, at=None):
+    """The alert for a phone's condition (fleet_health.py): the phone's name, a code, and two fixed sentences."""
+    at = time.time() if at is None else at
+    name = " ".join(str(phone or "iPhone").split())[:120]
+    return {"workflow": name, "status": f"phone_{code}"[:40], "reason": f"{message} {action}"[:400], "runId": None,
+            "at": datetime.datetime.fromtimestamp(at, datetime.timezone.utc).isoformat(timespec="seconds")}
+
+
+def headline(data):
+    if data["status"].startswith("phone_"):
+        return f"Mobster: {data['reason']}"
+    if data["status"] == "approval_waiting":
+        return f"Mobster: “{data['workflow']}” is waiting for your approval. Open the Mobster app to answer it."
+    if data["status"] == "challenge":
+        return (f"Mobster: {data['workflow']}. {data['reason']} Nothing runs as it until you resume it in the Mac "
+                "app's Queue.")
+    if data["status"] == "test":
+        return "Mobster: alerts work. You'll hear here when a scheduled task fails or waits for you."
+    if data["status"] == "run_expired":
+        # Mobster can't say it failed (workflows/health.py UNKNOWN_ENDS), so the alert never says it didn't finish.
+        return (f"Mobster: We can't tell how “{data['workflow']}” ended. {data['reason']} "
+                "Open the Mobster app to run it again.")
+    return (f"Mobster: “{data['workflow']}” didn't finish ({data['status']}). {data['reason']} "
+            "Open the Mobster app to see it.")
+
+
+def shape(url, data):
+    """(body bytes, headers) for the service ``url`` belongs to."""
+    host = (urlsplit(url).hostname or "").lower()
+    line = headline(data)
+    if host == "hooks.slack.com" or host.endswith(".slack.com"):
+        body = {"text": line}
+    elif host in ("discord.com", "discordapp.com", "ptb.discord.com", "canary.discord.com"):
+        body = {"content": line}
+    elif host == "ntfy.sh" or host.startswith("ntfy."):
+        title = f"Mobster: {data['workflow']}"[:120].encode("ascii", "replace").decode()
+        return line.encode("utf-8"), {"Content-Type": "text/plain; charset=utf-8", "Title": title,
+                                      "Tags": "iphone,warning"}
+    else:
+        body = {**data, "text": line}
+    return json.dumps(body, ensure_ascii=False).encode("utf-8"), {"Content-Type": "application/json"}
+
+
+class _Pinned(http.client.HTTPSConnection):
+    """HTTPS to an address checked beforehand, with the name kept for TLS (SNI and the certificate check)."""
+
+    def __init__(self, host, address, port, timeout, context):
+        super().__init__(host, port=port, timeout=timeout, context=context)
+        self._address = address
+
+    def connect(self):
+        sock = socket.create_connection((self._address, self.port), self.timeout)
+        self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
+
+
+def _post(host, address, port, path, body, headers, timeout):
+    connection = _Pinned(host, address, port, timeout, ssl.create_default_context())
+    try:
+        connection.request("POST", path, body=body, headers={**headers, "User-Agent": "Mobster-alerts"})
+        response = connection.getresponse()
+        response.read(2048)
+        return response.status
+    finally:
+        connection.close()
+
+
+def deliver(url, data, *, post=None, resolve=socket.getaddrinfo, sleep=time.sleep, attempts=ATTEMPTS):
+    """Send ``data`` to ``url``; True when the service answered 2xx. Never raises."""
+    try:
+        url = validate_url(url)
+        parts = urlsplit(url)
+        host, port = parts.hostname.rstrip("."), parts.port or 443
+        path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+        body, headers = shape(url, data)
+    except Exception:
+        return False
+    post = post or _post
+    for attempt in range(attempts):
+        try:
+            address = resolve_public(host, port, resolve)
+            status = post(host, address, port, path, body, headers, TIMEOUT)
+            if 200 <= int(status) < 300:
+                return True
+            if 400 <= int(status) < 500 and status != 429:
+                return False  # the address refuses it: trying again won't help
+        except AlertError:
+            return False
+        except Exception:
+            pass
+        if attempt + 1 < attempts:
+            sleep(RETRY_PAUSE)
+    return False
+
+
+class Alerts:
+    """What workflows/service.py calls: reads the address at each alert and sends on a daemon thread, so no run waits
+    on it."""
+
+    def __init__(self, env=None, *, post=None, resolve=socket.getaddrinfo, background=True, clock=time.time):
+        self.env, self.post, self.resolve, self.background, self.clock = env, post, resolve, background, clock
+        self.sent = []  # (status, run id) of every alert started, for the log and tests
+
+    def url(self):
+        value = configured_url(self.env)
+        if not value:
+            return None
+        try:
+            return validate_url(value)
+        except AlertError:
+            return None
+
+    def run_finished(self, workflow, status, run_id, code=None):
+        """Alert when a scheduled run ended without finishing. True when an alert was started."""
+        if status in QUIET:
+            return False
+        return self._send(payload(workflow, status, run_id, code, self.clock()))
+
+    def approval_waiting(self, workflow, run_id):
+        return self._send(payload(workflow, "approval_waiting", run_id, None, self.clock()))
+
+    def challenge(self, title, reason, run_id):
+        """Alert that a profile was paused after the app challenged it (accounts/register.py)."""
+        return self._send({**payload(title, "challenge", run_id, None, self.clock()), "reason": reason})
+
+    def phone_alert(self, phone, code, message, action):
+        """Alert that a phone needs you (unplugged, locked, signed out, a check); True when an alert was started."""
+        return self._send(phone_payload(phone, code, message, action, self.clock()))
+
+    def _send(self, data):
+        url = self.url()
+        if not url:
+            return False
+        self.sent.append((data["status"], data["runId"]))
+
+        def work():
+            deliver(url, data, post=self.post, resolve=self.resolve)
+        if self.background:
+            threading.Thread(target=work, daemon=True, name="mobster-alert").start()
+        else:
+            work()
+        return True
+
+
+def add_arguments(parser, helpers):
+    subs = parser.add_subparsers(dest="alerts_command", metavar="<subcommand>")
+    subs.required = True
+    test = subs.add_parser("test", help="send a test alert to your webhook",
+                           description="Send a test alert to MOBSTER_ALERT_WEBHOOK_URL (or --url) and say whether "
+                                       "the service took it.",
+                           epilog="exit codes: 0 sent, 1 the service didn't take it, 2 no usable address")
+    test.add_argument("--url", metavar="URL", help="send to this https address instead of the saved one")
+    test.add_argument("--json", action="store_true", help="print one JSON object")
+
+
+def run(args, *, post=None, resolve=socket.getaddrinfo):
+    as_json = bool(getattr(args, "json", False))
+    url = getattr(args, "url", None) or configured_url(read_file=True)
+
+    def say(ok, message, code):
+        try:
+            if as_json:
+                print(json.dumps({"ok": ok, "message": message}), flush=True)
+            else:
+                print(("" if ok else "mobster alerts: ") + message, file=sys.stdout if ok else sys.stderr, flush=True)
+        except BrokenPipeError:
+            pass
+        return code
+    if not url:
+        return say(False, f"No alert address. Set {ENV} (Settings in the Mobster app), or pass --url.", 2)
+    try:
+        url = validate_url(url)
+    except AlertError as error:
+        return say(False, str(error), 2)
+    if deliver(url, payload("Test", "test"), post=post, resolve=resolve):
+        return say(True, f"Sent a test alert to {urlsplit(url).hostname}.", 0)
+    return say(False, f"{urlsplit(url).hostname} didn't take the test alert. Check the address, then try again.", 1)

mobile_agent/android/__init__.py

@@ -0,0 +1,18 @@
+"""Android: emulators and USB phones through adb, behind MOBSTER_EXPERIMENTAL_ANDROID=1 until the owner turns it on."""
+
+import os
+
+FLAG = "MOBSTER_EXPERIMENTAL_ANDROID"
+
+
+def enabled(environ=None):
+    environ = os.environ if environ is None else environ
+    return (environ.get(FLAG) or "").strip().casefold() in {"1", "true", "yes", "on"}
+
+
+def add_test_flag(where):
+    """`mobster test --android`, shown only while the flag is on."""
+    if enabled():
+        where.add_argument("--android", nargs="?", const="", metavar="AVD_OR_SERIAL",
+                           help="run on an Android emulator: an AVD name or its adb serial, or none for any idle "
+                                "emulator (experimental)")

mobile_agent/android/adb.py

@@ -0,0 +1,268 @@
+"""adb: find the SDK tools, list devices, and run the few commands the driver needs. One argv per call, never a shell
+string built on this side; the runner is injectable so the tests use a fake adb."""
+
+import base64
+import os
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+SERIAL = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:\-]{0,63}")
+PACKAGE = re.compile(r"[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+")
+DEFAULT_ROOTS = ("~/Library/Android/sdk", "~/Android/Sdk")
+OUTPUT_LIMIT = 64_000_000
+quote = shlex.quote
+
+
+class AdbError(RuntimeError):
+    """An adb call failed or its answer was not understood. ``fix`` is one plain sentence (may be "")."""
+
+    def __init__(self, message, fix=""):
+        super().__init__(message)
+        self.fix = fix
+
+
+@dataclass(frozen=True)
+class Result:
+    code: int
+    out: bytes = b""
+    err: bytes = b""
+
+    @property
+    def text(self):
+        return self.out.decode("utf-8", "replace")
+
+    @property
+    def message(self):
+        lines = (self.err or self.out).decode("utf-8", "replace").strip().splitlines()
+        return lines[-1] if lines else ""
+
+
+def run_process(argv, timeout=30, stdin=None):
+    """The default runner. A timeout kills the child (subprocess.run does) and is reported as code 124."""
+    try:
+        done = subprocess.run(argv, input=stdin, capture_output=True, timeout=timeout, check=False)
+    except subprocess.TimeoutExpired:
+        return Result(124, b"", b"timed out")
+    except OSError as error:
+        return Result(127, b"", str(error).encode())
+    return Result(done.returncode, done.stdout[:OUTPUT_LIMIT], done.stderr[:4096])
+
+
+def sdk_root(environ=None):
+    """The Android SDK folder: ANDROID_HOME, ANDROID_SDK_ROOT, else the Android Studio default; None when absent."""
+    environ = os.environ if environ is None else environ
+    for name in ("ANDROID_HOME", "ANDROID_SDK_ROOT"):
+        if environ.get(name):
+            path = Path(environ[name]).expanduser()
+            if path.is_dir():
+                return path
+    for default in DEFAULT_ROOTS:
+        path = Path(default).expanduser()
+        if path.is_dir():
+            return path
+    return None
+
+
+def tool(name, root=None):
+    """The path of an SDK tool (adb, emulator, avdmanager, ...), or None."""
+    root = root if root is not None else sdk_root()
+    if root is None:
+        return None
+    for relative in {"adb": ("platform-tools/adb",), "emulator": ("emulator/emulator",),
+                     "avdmanager": ("cmdline-tools/latest/bin/avdmanager", "cmdline-tools/bin/avdmanager")
+                     }.get(name, (name,)):
+        path = Path(root) / relative
+        if path.is_file() and os.access(path, os.X_OK):
+            return str(path)
+    return None
+
+
+def tool_in_build_tools(name, root=None):
+    """A tool from the newest build-tools folder (aapt2), or None."""
+    root = root if root is not None else sdk_root()
+    if root is None:
+        return None
+    for folder in sorted((Path(root) / "build-tools").glob("*"), reverse=True):
+        path = folder / name
+        if path.is_file() and os.access(path, os.X_OK):
+            return str(path)
+    return None
+
+
+def valid_serial(serial):
+    if not isinstance(serial, str) or not SERIAL.fullmatch(serial):
+        raise AdbError(f"{serial!r} is not an adb serial.")
+    return serial
+
+
+def valid_package(package):
+    if not isinstance(package, str) or len(package) > 255 or not PACKAGE.fullmatch(package):
+        raise AdbError(f"{package!r} is not an Android package name.")
+    return package
+
+
+@dataclass(frozen=True)
+class AndroidDevice:
+    serial: str
+    state: str        # device, offline, unauthorized
+    kind: str         # emulator or usb
+    model: str = ""
+    product: str = ""
+
+    @property
+    def ready(self):
+        return self.state == "device"
+
+
+def parse_devices(text):
+    """`adb devices -l` as AndroidDevice rows. Lines that are not a serial and a state are ignored."""
+    devices = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 2 or not SERIAL.fullmatch(parts[0]) or parts[0] == "List":
+            continue
+        extra = dict(item.split(":", 1) for item in parts[2:] if ":" in item)
+        devices.append(AndroidDevice(parts[0], parts[1], "emulator" if parts[0].startswith("emulator-") else "usb",
+                                     extra.get("model", ""), extra.get("product", "")))
+    return devices
+
+
+class Adb:
+    """adb for one device (``serial``) or, with none, for listing. ``run`` is (argv, timeout, stdin) -> Result."""
+
+    def __init__(self, serial=None, run=run_process, binary=None):
+        self.serial = valid_serial(serial) if serial else None
+        self._run = run
+        self.binary = binary or tool("adb") or "adb"
+
+    def adb(self, *args, timeout=30, stdin=None, check=True):
+        argv = [self.binary, *(["-s", self.serial] if self.serial else []), *map(str, args)]
+        result = self._run(argv, timeout, stdin)
+        if check and result.code != 0:
+            raise AdbError(f"adb {args[0]} failed: {result.message or 'exit ' + str(result.code)}",
+                           "Check that the device is online (`adb devices -l`) and unlocked.")
+        return result
+
+    def shell(self, *args, timeout=30, check=True):
+        return self.adb("shell", *args, timeout=timeout, check=check)
+
+    # -- devices
+
+    def devices(self):
+        return parse_devices(self.adb("devices", "-l", timeout=10).text)
+
+    def prop(self, name):
+        return self.shell("getprop", name, timeout=10).text.strip()
+
+    def booted(self):
+        return self.shell("getprop", "sys.boot_completed", timeout=10, check=False).text.strip() == "1"
+
+    # -- screen
+
+    def screen_px(self):
+        """(width, height, density dpi) of the display in pixels, from `wm size` and `wm density`."""
+        size = re.findall(r"(\d+)x(\d+)", self.shell("wm", "size", timeout=10).text)
+        density = re.findall(r"(\d+)", self.shell("wm", "density", timeout=10).text)
+        if not size or not density:
+            raise AdbError("The device did not report its screen size.")
+        width, height = map(int, size[-1])
+        return width, height, int(density[-1])
+
+    def dump_ui(self, timeout=15):
+        """The accessibility tree as uiautomator's XML, with the trailer line removed."""
+        text = self.adb("exec-out", "uiautomator", "dump", "/dev/tty", timeout=timeout).text
+        start, end = text.find("<?xml"), text.rfind("</hierarchy>")
+        if start < 0 or end < 0:
+            raise AdbError("uiautomator returned no accessibility tree.",
+                           "Wait for the screen to settle, or restart the device's UI automation.")
+        return text[start:end + len("</hierarchy>")]
+
+    def screenshot_png(self, timeout=15):
+        data = self.adb("exec-out", "screencap", "-p", timeout=timeout).out
+        if not data.startswith(b"\x89PNG"):
+            raise AdbError("The device returned no screenshot.")
+        return data
+
+    def screenshot_data_uri(self, timeout=15):
+        return "data:image/png;base64," + base64.b64encode(self.screenshot_png(timeout)).decode()
+
+    def front_package(self):
+        """The package in front, from the focused window; "" when the device does not say."""
+        text = self.shell("dumpsys", "window", timeout=10, check=False).text
+        match = re.search(r"mCurrentFocus=Window\{\S+ \S+ ([A-Za-z0-9_.]+)/", text)
+        return match.group(1) if match else ""
+
+    # -- input
+
+    def tap(self, x, y):
+        self.shell("input", "tap", int(round(x)), int(round(y)), timeout=10)
+
+    def swipe(self, x1, y1, x2, y2, millis=300):
+        self.shell("input", "swipe", *(int(round(n)) for n in (x1, y1, x2, y2)), int(millis), timeout=10)
+
+    def long_press(self, x, y, millis=900):
+        self.swipe(x, y, x, y, millis)
+
+    def key(self, code):
+        self.shell("input", "keyevent", int(code), timeout=10)
+
+    def text(self, value):
+        """Type ASCII text at the focus. adb joins its arguments into one device shell line, so the text is single
+        quoted. `input text` cannot send other characters, and reads "%s" as a space, so those are refused."""
+        if not value.isascii() or "%" in value or any(ord(c) < 32 for c in value):
+            raise AdbError("Android can type plain ASCII text without % only.",
+                           "Use text without accents, emoji or % until the keyboard helper ships.")
+        self.shell("input", "text", quote(value.replace(" ", "%s")), timeout=15)
+
+    # -- apps
+
+    def install(self, apk, timeout=180):
+        path = Path(apk)
+        if path.suffix != ".apk" or not path.is_file():
+            raise AdbError(f"{apk} is not an .apk file.")
+        result = self.adb("install", "-r", str(path), timeout=timeout, check=False)
+        if result.code != 0 or b"Success" not in result.out:
+            raise AdbError(f"adb install failed: {result.message or result.text.strip()[-200:]}")
+
+    def launch(self, package):
+        valid_package(package)
+        result = self.shell("monkey", "-p", package, "-c", "android.intent.category.LAUNCHER", "1", timeout=20)
+        if b"No activities found" in result.out + result.err:
+            raise AdbError(f"{package} has no launchable activity or is not installed.")
+
+    def stop(self, package):
+        self.shell("am", "force-stop", valid_package(package), timeout=10)
+
+    def installed_version(self, package):
+        """versionName of an installed package, or None when it is not installed."""
+        valid_package(package)
+        if "package:" not in self.shell("pm", "path", package, timeout=10, check=False).text:
+            return None
+        match = re.search(r"versionName=(\S+)", self.shell("dumpsys", "package", package, timeout=15).text)
+        return match.group(1) if match else ""
+
+    def clear_data(self, package):
+        result = self.shell("pm", "clear", valid_package(package), timeout=20, check=False)
+        if b"Success" not in result.out:
+            raise AdbError(f"Clearing {package}'s data failed: {result.message or result.text.strip()[-120:]}")
+
+    def uninstall(self, package):
+        self.adb("uninstall", valid_package(package), timeout=60, check=False)
+
+    def permission(self, package, permission, grant):
+        if not re.fullmatch(r"[A-Za-z0-9_.]+", permission):
+            raise AdbError(f"{permission!r} is not a permission name.")
+        result = self.shell("pm", "grant" if grant else "revoke", valid_package(package), permission, timeout=15,
+                            check=False)
+        if result.code != 0 or b"Exception" in result.out + result.err or b"Error" in result.err:
+            raise AdbError(f"{'Granting' if grant else 'Revoking'} {permission} failed: "
+                           f"{result.message or result.text.strip()[-120:]}")
+
+    def open_url(self, url, package=None):
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9+.\-]*:[^\s'\"`\\]+", url):
+            raise AdbError(f"{url!r} is not a link adb can open.")
+        self.shell("am", "start", "-a", "android.intent.action.VIEW", "-d", quote(url),
+                   *(["-p", valid_package(package)] if package else []), timeout=15)