mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/mcp_server/device_tools.py

@@ -0,0 +1,306 @@
+"""Finding the devices the tools may drive, who holds them, and the direct session on one."""
+
+import time
+
+from ..android.records import is_phone
+from .protocol import ToolResult
+from .session import Session
+from .support import SHUTTING_DOWN, ToolError, cap_text, jsonable, sentence
+
+DEVICE_LIST_TTL = 30.0
+
+
+class DeviceTools:
+    def _device_records(self, fresh=False, probe=None):
+        at, records = self._devices_cache
+        if records is None or fresh or time.monotonic() - at > DEVICE_LIST_TTL:
+            if self._devices_source is not None:
+                records = self._devices_source()
+            else:
+                from ..android.records import records as android_records
+                from ..devices import discover
+                records = discover(probe=fresh if probe is None else probe) + android_records()
+            self._devices_cache = (time.monotonic(), records)
+        return records
+
+    def _app_ownership(self):
+        if self._ownership_source is not None:
+            return self._ownership_source()
+        if self._devices_source is not None:
+            return {}
+        at, found = self._ownership_cache
+        if time.monotonic() - at < 3.0:
+            return found
+        found = {}
+        try:
+            from ..threads.client import Client
+            listing = Client.connect(origin="mcp").call("GET", "/api/devices", timeout=2.0)
+            for item in listing.get("devices") or ():
+                if isinstance(item, dict) and isinstance(item.get("id"), str):
+                    found[item["id"]] = {"holder": item.get("holder"), "queue": item.get("queue") or []}
+        except Exception:  # noqa: BLE001 -- no app, an older app, a refused token
+            found = {}
+        self._ownership_cache = (time.monotonic(), found)
+        return found
+
+    def _holder_of(self, record):
+        from .. import ownership
+        for session in self._all_sessions() + self._direct_sessions():
+            run = session.run
+            if session.open and getattr(run, "device_id", None) in (record.get("id"), record.get("udid")):
+                since = time.time() - max(0.0, self.clock() - session.started)
+                label = ownership.clean_client(self.client_name()) or "this MCP client"
+                return {"kind": "mcp", "label": label, "runId": session.run_id, "since": int(since * 1000),
+                        "stopping": False}, []
+        if record.get("kind") == "simulator":
+            other = self._simulator_holder(record)
+            if other is not None:
+                return other, []
+        known = self._app_ownership().get(record.get("id")) or {}
+        return known.get("holder"), known.get("queue") or []
+
+    def _simulator_holder(self, record):
+        """The holder of a Mobster simulator in another process (an agent's session, a test run), from its record."""
+        from ..sim import holders
+        data_dir = getattr(self._manager_instance, "data_dir", None)
+        if data_dir is None:
+            from ..devices import simulator_folder
+            data_dir = simulator_folder()
+        found = holders.read(data_dir, record.get("udid") or record.get("id"))
+        if found is None:
+            return None
+        return {"kind": "mcp", "label": f"{found['client']} ({found['session']})", "runId": None,
+                "since": int(found["since"] * 1000), "stopping": False}
+
+    @staticmethod
+    def _holder_words(holder, queue):
+        from .. import ownership
+        if not holder:
+            return ""
+        minutes = max(0, int((time.time() * 1000 - holder["since"]) // 60000))
+        words = f"{ownership.holding_sentence(holder)}, {minutes} min" + (", stopping after this step"
+                                                                           if holder.get("stopping") else "")
+        return words + (f"; {len(queue)} waiting" if queue else "")
+
+    def _named_device(self, name, required=False):
+        from ..devices import AmbiguousDevice, DeviceNotFound, resolve
+        if not name:
+            return None
+        for attempt in range(2):
+            try:
+                return resolve(self._device_records(fresh=attempt > 0, probe=False), name)
+            except AmbiguousDevice as error:
+                raise ToolError(str(error)) from None
+            except DeviceNotFound as error:
+                if attempt == 0 and time.monotonic() - self._devices_cache[0] > 1.0:
+                    continue
+                if required:
+                    raise ToolError(f"{error} Call list_devices to see them.") from None
+                return None
+        return None
+
+    def _open_direct(self, name):
+        folded = str(name or "").strip().casefold()
+        if not folded:
+            return None
+        sessions = self._direct_sessions()
+        for session in sessions:
+            record = getattr(session.run, "record", None) or {}
+            if folded in {str(record.get("id") or "").casefold(), str(record.get("udid") or "").casefold()}:
+                return session
+        named = [session for session in sessions
+                 if str((getattr(session.run, "record", None) or {}).get("name") or "").casefold() == folded]
+        return named[0] if len(named) == 1 else None
+
+    def _direct_sessions(self, open_only=True):
+        with self._lock:
+            return [s for s in self.device_sessions.values() if s.open or not open_only]
+
+    def _allowed(self, record):
+        if not is_phone(record) or self.allow_devices is None:
+            return True
+        names = {str(record.get(key) or "").strip().casefold() for key in ("id", "udid", "name")}
+        return bool(names & self.allow_devices)
+
+    def _refuse_unless_allowed(self, record):
+        if not self._allowed(record):
+            raise ToolError(f"“{record['name']}” is a real device, and this server may drive only the ones "
+                            "`mobster mcp --allow-device` names. Ask the user to add it to the server's command.")
+
+    def _device_busy_with_check(self, record):
+        for session in self._all_sessions():
+            run = session.run
+            if (session.open
+                    and getattr(getattr(run, "target", None), "udid", None) in (record.get("udid"), record["id"])):
+                return session
+            if session.open and getattr(run, "device_id", None) == record["id"]:
+                return session
+        return None
+
+    def _device_session(self, name):
+        session = self._open_direct(name)
+        if session is not None and session.open:
+            session.touch()
+            return session
+        record = self._named_device(name, required=True)
+        with self._lock:
+            session = self.device_sessions.get(record["id"])
+            if session is not None and session.open:
+                session.touch()
+                return session
+            if self._closing.is_set():
+                raise ToolError(SHUTTING_DOWN)
+            check = self._device_busy_with_check(record)
+            if check is not None:
+                raise ToolError(f"Run {check.run_id} is checking an app on {record['name']}. Pass run_id "
+                                f"{check.run_id}, or stop that run first.")
+            self._refuse_unless_allowed(record)
+            if record.get("platform") == "android":
+                raise ToolError(f"“{record['name']}” is an Android device: use verify_start with device, or run_tests. "
+                                "Driving it directly with tap and screen isn't available yet.")
+            if record.get("state") in ("needs_setup", "disconnected") or not record.get("wdaUrl"):
+                raise ToolError(f"“{record['name']}” isn't ready: {record.get('reason') or record['state']}")
+            from .direct import DeviceRun
+            factory = self._device_run or DeviceRun
+            folder = self.runs_dir if record.get("kind") == "simulator" else self.device_runs_dir
+            run = factory(record, runs_dir=folder)
+            session = self._open_direct_run(run, record)
+        self.log(f"Run {session.run_id}: driving {record['name']} ({record['kind']}) directly.")
+        return session
+
+    def _open_direct_run(self, run, record, *, own=False):
+        """Prepare ``run`` and file it as the direct session on ``record``'s device. Call it under self._lock."""
+        try:
+            run.prepare()
+        except Exception as error:
+            run.close("It couldn't be opened.")
+            fix = getattr(error, "fix", "")
+            raise ToolError(sentence(error) + (" " + sentence(fix) if fix else "")) from None
+        if own:
+            # the simulator is known only once its lease is taken
+            udid, name = run.target.udid, run.target.name
+            record.update(id=udid, udid=udid, name=name)
+            run.device_id, run.device_name = udid, name
+            self._own_sim = udid
+        session = Session(run, "direct", clock=self.clock, image=True)
+        self.codes.seed(session, record["id"])
+        session.message = f"Driving {record['name']} directly."
+        session.set_state("ready")
+        self.device_sessions[record["id"]] = session
+        return session
+
+    def _yield_session_simulator(self, args):
+        """A check that names no device takes a free simulator itself: hand back the one this session leased, so
+        one session never holds two."""
+        session = self.device_sessions.get(self._own_sim) if self._own_sim else None
+        if args.get("device") or self.device or session is None or not session.open or session.busy:
+            return
+        self._close_direct(session, "A check is starting, so Mobster handed this session's simulator to it.",
+                           timeout=0)
+
+    def _session_simulator(self):
+        """This session's own simulator: leased on the first call that names no device, kept until the session
+        ends or sits idle for 30 minutes, and never given to another session while held."""
+        with self._lock:
+            session = self.device_sessions.get(self._own_sim) if self._own_sim else None
+            if session is not None and session.open:
+                session.touch()
+                return session
+            self._own_sim = None
+            if self._closing.is_set():
+                raise ToolError(SHUTTING_DOWN)
+            from .direct import DeviceRun
+            record = {"id": "", "udid": "", "kind": "simulator", "name": "a Mobster simulator"}
+            # no queueing: when every simulator is held, the answer names the holders at once
+            run = (self._device_run or DeviceRun)(record, runs_dir=self.runs_dir, manager=self._manager(),
+                                                  acquire_timeout=0)
+            session = self._open_direct_run(run, record, own=True)
+        self.log(f"Run {session.run_id}: leased {record['name']} for this session.")
+        return session
+
+    def _close_direct(self, session, reason, timeout=None):
+        if not session.open:
+            return True
+        locked = session.run.lock.acquire(timeout=self.lock_wait if timeout is None else max(0.0, timeout))
+        if not locked:
+            return False
+        try:
+            if session.open:
+                if self._own_sim and session.run.device_id == self._own_sim:
+                    self._own_sim = None
+                session.set_state("finished", jsonable(session.run.close(reason)))
+                self.log(f"Run {session.run_id}: {reason}")
+        finally:
+            session.run.lock.release()
+        return True
+
+    def _target_session(self, args):
+        run_id, device = args.get("run_id"), args.get("device")
+        if run_id:
+            session = self._ready_session(run_id)
+            if device:
+                record = self._named_device(device, required=True)
+                run = session.run
+                on = getattr(run, "device_id", None) or getattr(getattr(run, "target", None), "udid", None)
+                if on not in (record["id"], record.get("udid")):
+                    raise ToolError(f"Run {run_id} isn't on {record['name']}. Leave out device, or pass the run_id "
+                                    "of a run on it.")
+            return session
+        if device:
+            name = device
+        elif self.device and self._open_direct(self.device) is not None:
+            name = self.device
+        else:
+            name = self.device if self._named_device(self.device) is not None else None
+        if not name:
+            return self._session_simulator()
+        return self._device_session(name)
+
+    def tool_list_devices(self, args, call):
+        from ..devices import describe
+        records = self._device_records(fresh=True)
+        open_runs = {s.run.device_id: s.run_id for s in self._all_sessions() + self._direct_sessions()
+                     if s.open and getattr(s.run, "device_id", None)}
+        rows = []
+        for item in records:
+            row = {key: item.get(key) for key in ("id", "kind", "name", "model", "modelName", "ios", "state", "reason")}
+            row["platform"] = item.get("platform") or "ios"
+            row["run_id"] = open_runs.get(item["id"])
+            row["holder"], row["queue"] = self._holder_of(item)
+            row["yours"] = bool(self._own_sim) and item["id"] == self._own_sim
+            if not self._allowed(item):
+                row["state"] = "not_allowed"
+                row["reason"] = "this server may drive only the devices `mobster mcp --allow-device` names"
+            rows.append(row)
+        if not rows:
+            return ToolResult("No devices. Plug in an iPhone set up in the Mobster app, or prepare a simulator "
+                              "(`mobster sim prepare`).", {"devices": []})
+        lines = [describe(item) + f"  (id {item['id']})" + (f", open in run {row['run_id']}" if row["run_id"] else "")
+                 + (", not allowed: not named by --allow-device" if row["state"] == "not_allowed" else "")
+                 + (", yours" if row["yours"] else "")
+                 + (f". {self._holder_words(row['holder'], row['queue'])}" if row["holder"] and not row["yours"]
+                    else "")
+                 for item, row in zip(records, rows)]
+        return ToolResult(cap_text("\n".join(lines)), {"devices": rows})
+
+    def _phone_record(self, session):
+        record = getattr(session.run, "record", None)
+        if isinstance(record, dict):
+            return record
+        device_id = getattr(session.run, "device_id", None)
+        try:
+            return self._named_device(device_id) if device_id else None
+        except ToolError:
+            return None
+
+    def _on_phone(self, session):
+        record = self._phone_record(session)
+        return bool(record) and is_phone(record)
+
+    def _record_for(self, args):
+        name = args.get("device") or self.device
+        if not name:
+            raise ToolError("Pass device (from list_devices).")
+        record = self._named_device(name, required=True)
+        self._refuse_unless_allowed(record)
+        return record

mobile_agent/mcp_server/direct.py

@@ -0,0 +1,272 @@
+"""A device the phone tools drive directly, outside a check (SPEC §3: MCP drives real USB iPhones too)."""
+
+import re
+import threading
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+FRAME_QUALITY = 75
+EVALUATE_PAUSE = .5
+
+
+def url_app(url):
+    # An ordinary web link stays in Safari, so the person is asked about Safari before the page opens.
+    from ..deeplinks import app_for
+    return app_for(url) or ("com.apple.mobilesafari" if urlsplit(url).scheme.casefold() in ("http", "https") else "")
+
+
+class PhoneStop(Exception):
+    def __init__(self, verdict):
+        super().__init__(getattr(verdict, "message", "") or "Your iPhone isn't ready. No action was taken.")
+        self.code = getattr(verdict, "code", "") or "phone_locked"
+        self.verdict = verdict
+
+
+CHECK_FAILED = "Mobster couldn't check whether your iPhone is unlocked, so it stopped."
+VERDICTS = ("ready", "unlocked", "stop")
+
+
+def strict_check(guard, driver, cause):
+    from ..agent_hooks import GuardVerdict
+    try:
+        verdict = guard.check(driver, cause=cause)
+    except Exception:
+        verdict = None
+    if getattr(verdict, "state", None) not in VERDICTS:
+        return GuardVerdict("stop", "phone_locked", CHECK_FAILED)
+    return verdict
+
+
+def _decline(*_args, **_kwargs):
+    # MCP has nobody to ask: an approval the guard would want is declined.
+    return "denied"
+
+
+def default_guard(record, emit=None):
+    if record.get("kind") == "simulator":
+        return None
+    from ..lockscreen import guard_for
+    return guard_for(device_id=record["id"], wda_url=record.get("wdaUrl"), mode="scripts", approve=_decline,
+                     emit=emit or (lambda event: None))
+
+
+def lockscreen_available():
+    try:
+        from ..lockscreen import CAN_UNLOCK
+    except ImportError:
+        return False
+    return CAN_UNLOCK is True
+
+
+def unlock_settings(record):
+    keys = {"enabled": False, "askBeforeUnlocking": True, "scripts": False, "relockAfter": True, "needsCheck": False}
+    settings = None
+    try:
+        from .. import lockscreen
+        reader = getattr(lockscreen, "unlock_settings", None)
+        if callable(reader):
+            settings = reader(record["id"])
+    except ImportError:
+        pass
+    except Exception:
+        settings = None
+    if not isinstance(settings, dict):
+        try:
+            from ..devices import DeviceStore
+            from ..paths import user_data_dir
+            entry = next((item for item in DeviceStore(user_data_dir()).phones()
+                          if item.get("udid") in (record.get("udid"), record.get("id"))), None)
+            settings = (entry or {}).get("unlock")
+        except Exception:
+            settings = None
+    settings = settings if isinstance(settings, dict) else {}
+    return {key: settings.get(key) is True if not default else settings.get(key) is not False
+            for key, default in keys.items()}
+
+
+def passcode_saved(record):
+    try:
+        from .. import passcode_vault
+    except ImportError:
+        return False
+    try:
+        return bool(passcode_vault.exists(record.get("udid") or record["id"]))
+    except Exception:
+        return False
+
+
+class DeviceRun:
+    mode = "direct"
+
+    def __init__(self, record, *, runs_dir, manager=None, driver_factory=None, guard_factory=None, emit=None,
+                 acquire_timeout=None):
+        from ..device_targets import WdaDevice
+        from ..verify.runs import make_run_dir
+        self.record = record
+        self.device_id = record["id"]
+        self.device_name = record.get("name") or record["id"]
+        self.manager = manager or WdaDevice(record)
+        self._driver_factory = driver_factory
+        self._acquire_timeout = acquire_timeout  # None: the manager's own wait
+        self.runs_dir = Path(runs_dir).expanduser().resolve()
+        # Ignored in git and readable by this user only: the frames show the phone's screen.
+        self.run_id, self.run_dir = make_run_dir(self.runs_dir)
+        self.lock = threading.RLock()
+        self.steps, self.frames = [], []
+        self.state = "new"
+        self.driver = self.target = self.lease = self.app = None
+        self.result = None
+        self._guard_factory = guard_factory or default_guard
+        self._emit = emit or (lambda event: None)
+        self.guard = self.preflight = None
+        self._frame_n = 0
+        self._frame_width = None
+        self._t0 = time.monotonic()
+        self._release_lock = threading.Lock()
+        self.log(f"device {self.device_name} ({self.device_id}), driven directly")
+
+    def log(self, line):
+        try:
+            with open(self.run_dir / "run.log", "a", encoding="utf-8") as handle:
+                handle.write(f"{time.strftime('%H:%M:%S')} {line}\n")
+        except OSError:
+            pass
+
+    def prepare(self):
+        self.lease = (self.manager.acquire() if self._acquire_timeout is None
+                      else self.manager.acquire(timeout=self._acquire_timeout))
+        self.target = self.lease.target
+        try:
+            if self._driver_factory is not None:
+                self.driver = self._driver_factory(self.target)
+            else:
+                from ..verify.runner import build_driver
+                self.driver = build_driver(self.target, self.manager, self.run_dir, "keyless")
+            self._check_phone("preflight")
+        except BaseException:
+            self._release()
+            raise
+        self.state = "ready"
+
+    def _check_phone(self, cause):
+        if self.guard is None and self.preflight is None:
+            self.guard = self._guard_factory(self.record, self._emit)
+        if self.guard is None:
+            return None
+        verdict = strict_check(self.guard, self.driver, cause)
+        if cause == "preflight":
+            self.preflight = verdict
+        self.log(f"phone check ({cause}): {getattr(verdict, 'state', '?')} {getattr(verdict, 'code', '')}".rstrip())
+        if getattr(verdict, "state", "") == "stop":
+            raise PhoneStop(verdict)
+        return verdict
+
+    def check_phone(self, cause="resume"):
+        with self.lock:
+            return self._check_phone(cause)
+
+    def read_tree(self):
+        from ..verify.tree import read_tree, tree_from_pixels
+        pixels = getattr(self.driver, "pixel_snapshot", None)
+        if not callable(pixels):
+            return read_tree(self.driver, pause=time.sleep)
+        snapshot = pixels()
+        if snapshot is not None:
+            return tree_from_pixels(snapshot)
+        from ..wda.observe import WDA_TREE_BUDGET_SECONDS
+        started = time.monotonic()
+        try:
+            return read_tree(self.driver, timeout=WDA_TREE_BUDGET_SECONDS, pause=time.sleep, retry_slow=False)
+        except Exception:
+            if time.monotonic() - started < WDA_TREE_BUDGET_SECONDS - .1:
+                raise
+            snapshot = pixels(mark=True)
+            if snapshot is None:
+                raise
+            return tree_from_pixels(snapshot)
+
+    def frame(self, label):
+        self._frame_n += 1
+        label = re.sub(r"[^a-z0-9-]+", "-", str(label).lower()).strip("-") or "frame"
+        path = self.run_dir / "frames" / f"{self._frame_n:02d}-{label}.jpg"
+        try:
+            self.manager.screenshot(self.target, path, max_width=self._frame_width, quality=FRAME_QUALITY)
+            if self._frame_width is None:
+                from PIL import Image
+                with Image.open(path) as image:
+                    self._frame_width = max(1, image.width // 2)
+        except Exception as error:
+            self.log(f"no {label} frame: {type(error).__name__}")
+            return None
+        self.frames.append(path.relative_to(self.run_dir).as_posix())
+        return path
+
+    def record_step(self, *, op, text, target=None, typed=None, changed=None, frame=None):
+        from ..journal import append_jsonl
+        step = {"index": len(self.steps) + 1, "op": op, "text": text,
+                "target": ({"id": target.get("id"), "label": target.get("label"), "role": target.get("role")}
+                           if target else None),
+                "typed": typed, "changed": changed,
+                "frame": Path(frame).relative_to(self.run_dir).as_posix() if frame else None,
+                "at_ms": round((time.monotonic() - self._t0) * 1000)}
+        append_jsonl(self.run_dir / "events.jsonl", {"event": "step", **step})
+        self.steps.append(step)
+        return step
+
+    def open_url(self, url):
+        from ..deeplinks import open_link
+        from ..verify.checks import URL_SCHEME, CheckError
+        if not isinstance(url, str) or not URL_SCHEME.match(url) or len(url) > 2000:
+            raise CheckError("the link needs a scheme, such as https://example.com or myapp://home")
+        with self.lock:
+            return open_link(self.driver, url, bundle=url_app(url) or None)
+
+    def launch_app(self, bundle_id):
+        with self.lock:
+            self.driver.call("POST", "/wda/apps/activate", {"bundleId": bundle_id}, timeout=30)
+
+    def home(self):
+        with self.lock:
+            self.driver.call("POST", "/wda/pressButton", {"name": "home"}, timeout=10)
+
+    def evaluate(self, assertions, *, timeout=5):
+        from ..verify.assertions import evaluate_on
+        deadline = time.monotonic() + max(0.0, timeout)
+        with self.lock:
+            while True:
+                results = evaluate_on(assertions, self.read_tree())
+                if all(result.ok for result in results) or time.monotonic() >= deadline:
+                    return results
+                time.sleep(EVALUATE_PAUSE)
+
+    def _release(self):
+        with self._release_lock:
+            driver, self.driver = self.driver, None
+            lease, self.lease = self.lease, None
+            guard, self.guard = self.guard, None
+        if guard is not None and driver is not None:
+            try:
+                guard.finish(driver)  # locks the phone again if this guard unlocked it and relock is on
+            except Exception as error:
+                self.log(f"the phone guard's finish failed ({type(error).__name__})")
+        if driver is not None:
+            try:
+                driver.close()
+            except Exception:
+                pass
+        if lease is not None:
+            try:
+                lease.release()
+            except Exception:
+                pass
+
+    def close(self, reason):
+        if self.result is None:
+            self._release()
+            self.state = "finished"
+            self.result = {"schema": "mobster.device/1", "run_id": self.run_id, "device": self.device_id,
+                           "device_name": self.device_name, "status": "closed", "summary": reason,
+                           "steps": list(self.steps), "frames": list(self.frames), "run_dir": str(self.run_dir)}
+            self.log(f"closed: {reason}")
+        return self.result

mobile_agent/mcp_server/expo_tools.py

@@ -0,0 +1,105 @@
+"""The Expo dev loop as MCP tools: ``expo_preview`` opens the app from Metro, ``expo_reload`` reloads it."""
+
+import time
+from pathlib import Path
+
+from .. import harness_api
+from ..devkit import DevError, expo, expo_dev
+from .protocol import ToolResult
+from .support import ToolError, cap_text
+
+LOG_TAIL = 600
+START_WAIT = 30
+RELOAD_SETTLE = 2.0
+MAX_EXPECT_WAIT = 30
+BUNDLE_WAIT = 20
+
+
+def quoted(text, limit=LOG_TAIL):
+    # What Metro or a dev server said is data from the user's project, never instructions.
+    flat = " ".join(str(text or "").split())
+    return "“" + (flat if len(flat) <= limit else "…" + flat[-(limit - 1):]) + "”"
+
+
+def metro_tail(app, limit=LOG_TAIL):
+    try:
+        text = (Path(app.root) / expo.STATE_DIR / "metro.log").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    text = text[-4000:].strip()
+    return harness_api.fence("Metro's log (the end of it)", text[-limit:]) if text else ""
+
+
+def ensure_metro(toolset, app, port, wait=START_WAIT):
+    toolset.log(f"Checking Metro on port {port} for {app.name}")
+    try:
+        server, started = expo_dev.ensure(app, port, wait=wait)
+        return server["pid"] if started else None
+    except DevError as error:
+        tail = metro_tail(app)
+        raise DevError(error.message, (error.fix + (" " + tail if tail else "")).strip()) from None
+
+
+def _fail(error):
+    return ToolError(cap_text(error.line()))
+
+
+def preview(toolset, args, call, sleep=time.sleep):
+    try:
+        app = expo.resolve_project(args.get("project"))
+        if not app.expo:
+            raise DevError("expo_preview opens Expo apps, and this React Native app has no Expo.",
+                           "Run it from Xcode, or install a build with install_app.")
+        record = toolset._record_for(args)
+        port = int(args.get("port") or expo.DEFAULT_PORT)
+        path = args.get("path")
+        link = expo.app_link(app, path) if path and app.client == "dev-client" else None
+        if path and app.client == "dev-client" and link is None:
+            raise DevError("path needs the app's own URL scheme, and its Expo config has no scheme.",
+                           "Add \"scheme\" to app.json, rebuild the dev client, then try again.")
+        started = ensure_metro(toolset, app, port)
+        broken = expo_dev.bundle_error(app, port, wait=BUNDLE_WAIT)
+        if broken:
+            where = f" in {broken['file']}:{broken['line']}" if broken.get("file") and broken.get("line") else ""
+            raise DevError(f"Metro can't bundle {app.name}{where}: {quoted(broken['message'])}",
+                           "Fix the error, then call expo_preview again.")
+        url = expo.preview_url(app, expo.host_for(record), port, path)
+    except DevError as error:
+        raise _fail(error) from None
+    target = {"device": record["id"]}
+    opened = toolset.tool_open_url({**target, "url": url}, call)
+    lines = [f"Opened {app.name} from Metro on port {port} in "
+             f"{'its dev client' if app.client == 'dev-client' else 'Expo Go'} on {record['name']}."]
+    structured = {**(opened.structured or {}), "app": app.name, "client": app.client, "url": url, "port": port,
+                  "metro_started": started is not None}
+    if link:
+        sleep(3)  # the dev client loads the bundle first; its own link needs the app up
+        opened = toolset.tool_open_url({**target, "url": link}, call)
+        lines.append(f"Then opened its screen {quoted(link, 120)}.")
+        structured["link"] = link
+    if started is not None:
+        lines.append(f"Metro started in the background (log {expo.STATE_DIR}/metro.log). Call expo_reload after an "
+                     "edit.")
+    expect = args.get("expect") or []
+    if expect:
+        waited = toolset.tool_wait_for({**target, "timeout_s": min(float(args.get("wait_s") or 20), MAX_EXPECT_WAIT),
+                                        "expect": [{"text": text} for text in expect]}, call)
+        structured["held"] = (waited.structured or {}).get("held")
+        return ToolResult(cap_text("\n".join(lines) + "\n" + waited.text), {**structured, **(waited.structured or {})})
+    return ToolResult(cap_text("\n".join(lines) + "\n" + opened.text), structured)
+
+
+def reload(toolset, args, call, sleep=time.sleep):
+    port = int(args.get("port") or expo.DEFAULT_PORT)
+    try:
+        app = expo.resolve_project(args.get("project"))
+        record = toolset._record_for(args)
+        expo.reload(port)
+    except DevError as error:
+        raise _fail(error) from None
+    sleep(RELOAD_SETTLE)
+    screen = toolset.tool_screen({"device": record["id"], "image": bool(args.get("image", False))}, call)
+    head = f"Reloaded the JavaScript in every app connected to Metro on port {port}."
+    return ToolResult(cap_text(head + "\n" + screen.text),
+                      {"app": app.name, "port": port, "reloaded": True,
+                       "screen": (screen.structured or {}).get("screen")}, screen.images)