mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/settle/store.py

@@ -0,0 +1,93 @@
+"""What each app's transitions take to settle, learned from the settles themselves.
+
+A key is (app bundle id, transition shape). A sample is the time from the end of the action's dispatch to the
+first read of the screen that stayed (the arrival), in milliseconds. The store keeps the last WINDOW samples per
+key and answers with their 90th percentile once it has MIN_SAMPLES. It holds numbers only: no screen text, no
+labels. It is a file under the data folder (``settle/durations.json``), replaced atomically.
+"""
+
+import json
+import math
+import os
+import threading
+from pathlib import Path
+
+from ..paths import user_data_dir, write_text_atomic
+
+FLAG = "MOBSTER_EXPERIMENTAL_SETTLE"
+WINDOW = 40
+MIN_SAMPLES = 5
+MAX_KEYS = 256
+# A prediction past this is not worth a blind wait: the polling cap (WDA_SETTLE_CAP_SECONDS) is near.
+MAX_PREDICTION_MS = 1200.0
+# Polling accepts a screen about this long (WDA_SETTLE_QUIET_SECONDS) after it arrived. A blind wait pays only when
+# its p90 sits less than that above the typical (median) arrival; otherwise polling ends sooner on a typical settle.
+QUIET_MS = 500.0
+
+SHAPES = {"TAP": "tap", "DOUBLE_TAP": "tap", "LONG_PRESS": "tap", "SUBMIT": "submit", "TYPE": "type",
+          "SET_TEXT": "type", "LAUNCH_APP": "launch", "HOME": "home", "BACK": "back"}
+
+
+def enabled():
+    return os.environ.get(FLAG, "").strip().casefold() in {"1", "true", "on", "yes"}
+
+
+def shape_of(op):
+    """A transition shape for an operation name: swipes by axis, the rest by kind, anything else 'other'."""
+    op = str(op or "")
+    if op.startswith("SWIPE_"):
+        return "swipe_" + ("y" if op in {"SWIPE_UP", "SWIPE_DOWN"} else "x")
+    return SHAPES.get(op, "other")
+
+
+def percentile(samples, share):
+    """Nearest rank: the smallest sample that at least ``share`` of the samples do not exceed."""
+    ordered = sorted(samples)
+    return ordered[max(0, math.ceil(share * len(ordered)) - 1)]
+
+
+class SettleStore:
+    def __init__(self, path=None):
+        self.path = Path(path) if path else user_data_dir() / "settle" / "durations.json"
+        self._lock = threading.Lock()
+        self._data = self._load()
+
+    def _load(self):
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+            return {key: [float(v) for v in values][-WINDOW:] for key, values in raw["samples"].items()
+                    if isinstance(values, list)}
+        except (OSError, ValueError, KeyError, TypeError, AttributeError):
+            return {}
+
+    @staticmethod
+    def key(app, shape):
+        return f"{app}|{shape}"
+
+    def samples(self, app, shape):
+        with self._lock:
+            return list(self._data.get(self.key(app, shape), ()))
+
+    def p90(self, app, shape):
+        """The predicted settle in ms, or None: too few samples, or too slow or too uneven to be worth a blind wait."""
+        values = self.samples(app, shape)
+        if len(values) < MIN_SAMPLES:
+            return None
+        value = percentile(values, .9)
+        return value if value <= MAX_PREDICTION_MS and value - percentile(values, .5) < QUIET_MS else None
+
+    def add(self, app, shape, ms):
+        if not app or not math.isfinite(ms) or ms < 0:
+            return
+        key = self.key(app, shape)
+        with self._lock:
+            values = self._data.pop(key, [])
+            values.append(round(float(ms), 1))
+            self._data[key] = values[-WINDOW:]
+            while len(self._data) > MAX_KEYS:
+                self._data.pop(next(iter(self._data)))
+            payload = json.dumps({"version": 1, "samples": self._data}, sort_keys=True)
+        try:
+            write_text_atomic(self.path, payload)
+        except OSError:
+            pass  # A prediction is optional; a run never fails on it.

mobile_agent/settle/stream.py

@@ -0,0 +1,43 @@
+"""A stream of the screen, used only to say "nothing moved", never to read it.
+
+The accessibility read stays the observation. An observer answers one question: did the pixels stay still over a
+window? Predictive settle (``predict.py``) asks it before it accepts a read it took after a learned wait.
+
+* ``WdaMjpegObserver``: the FrameClock's view of WDA's MJPEG stream (``wda.video.WdaVideo``). WDA serves that
+  stream for iOS Simulators and for a phone over its own port; the FrameClock already decodes it at ~25 fps.
+* ``PhoneScreenStream``: the phone's screen over the cable (pymobiledevice3's screen-capture service or CoreDevice).
+  A stub. Nothing in this repository has run it on a phone.
+"""
+
+from typing import Protocol
+
+
+class StreamObserver(Protocol):
+    def still_between(self, start: float, end: float) -> bool | None:
+        """True when no tile moved from ``start`` to ``end`` (time.monotonic seconds), False when one did, None
+        when the stream cannot say (stale, too few frames, a busy screen)."""
+
+
+class WdaMjpegObserver:
+    """The FrameClock watch of one action, as a StreamObserver."""
+
+    def __init__(self, clock, watch):
+        self.clock, self.watch = clock, watch
+
+    def still_between(self, start, end):
+        if not getattr(self.watch, "usable", False):
+            return None
+        try:
+            return bool(self.clock.quiet_between(self.watch, start, end))
+        except Exception:
+            return None
+
+
+class PhoneScreenStream:
+    """Unverified, 26 Oct 2026: written from pymobiledevice3's API surface, never run against a phone (no test
+    phone exists). It reports itself unavailable, so a caller falls back to the WDA stream or to AX polling."""
+
+    UNVERIFIED = "unverified 26 Oct 2026: no phone has run this path"
+
+    def still_between(self, start, end):
+        return None

mobile_agent/setup_cli.py

@@ -0,0 +1,225 @@
+"""`mobster setup`: get your iPhone ready for Mobster, in the terminal, one step at a time."""
+
+import json
+import sys
+import time
+
+STEPS = ("tools", "api_key", "phone", "wda_build", "wda_running", "live")
+POLL = 2.0
+
+
+def render(state, paint, frame=0, width=100):
+    """The checklist for ``state`` (SetupService.state()), as lines."""
+    from .style import SPINNER, wrap
+    steps = [step for step in state.get("steps") or () if step.get("id") in STEPS]
+    done = sum(1 for step in steps if step.get("state") == "done")
+    lines = [paint("Set up your iPhone", "bold") + paint(f"{done} of {len(steps)} done".rjust(
+        max(10, min(width, 72) - 18)), "tertiary"), ""]
+    for number, step in enumerate(steps, 1):
+        status = step.get("state")
+        glyph = {"done": paint("✓", "green"), "working": paint(SPINNER[frame % len(SPINNER)], "accent"),
+                 "blocked": paint("○", "tertiary")}.get(status, paint("○", "accent"))
+        title = step.get("title") or step.get("id")
+        lines.append(f"  {glyph} {number}. " + (paint(title, "tertiary") if status == "done" else
+                                                  paint(title, "bold")))
+        detail = step.get("detail") or ""
+        if step.get("id") == "api_key" and status != "done":
+            detail = "Run `mobster login` in another terminal to add your Claude or OpenAI key."
+        if status == "blocked":
+            detail = ""
+        if detail and status != "done":
+            lines.append(paint(wrap(detail, min(width, 100) - 2, indent=7), "secondary"))
+        for command in step.get("commands") or () if status != "done" else ():
+            text = command.get("command") if isinstance(command, dict) else str(command)
+            if text:
+                lines.append(" " * 7 + paint(text, "accent"))
+    return lines
+
+
+def run(args):
+    """Returns 0 when the phone is ready, 1 when a step failed, 3 when setup can't run here, 130 on ctrl+c."""
+    from .style import palette
+    paint = palette(sys.stdout)
+    as_json = bool(getattr(args, "json", False)) or not sys.stdout.isatty()
+    try:
+        runtime = open_runtime()
+    except Exception as error:  # noqa: BLE001 -- the runtime's own sentence
+        print(f"mobster setup: {error}", file=sys.stderr)
+        return 3
+    setup = runtime.setup
+    shown = 0
+    frame = 0
+    last = None
+    try:
+        if getattr(args, "device", None):
+            choose(runtime, args.device)
+        while True:
+            state = setup.state()
+            frame += 1
+            if as_json:
+                public = {"complete": _ready(state), "steps": [{k: s.get(k) for k in ("id", "title", "state",
+                                                                                         "detail")}
+                                                                for s in state["steps"] if s["id"] in STEPS]}
+                if public != last:
+                    print(json.dumps(public), flush=True)
+                    last = public
+            else:
+                lines = render(state, paint, frame, _width())
+                if shown:
+                    sys.stdout.write(f"\033[{shown}F\033[J")
+                sys.stdout.write("\n".join(lines) + "\n")
+                sys.stdout.flush()
+                shown = len(lines)
+            if _ready(state) and (state.get("wifi") or {}).get("state") != "pairing":   # a Wi-Fi yes ends first
+                if not as_json:
+                    name = (state.get("device") or {}).get("name") or "Your iPhone"
+                    print("\n" + paint("✓ ", "green", "bold") + paint(f"{name} is ready.", "bold")
+                          + " Give it a first task: " + paint("mobster", "accent"))
+                return 0
+            failed = _failed(state)
+            if failed:
+                if not as_json:
+                    print("\n" + paint("✗ ", "coral", "bold") + failed +
+                          "\n  Fix it, then run " + paint("mobster setup", "accent") + " again.")
+                return 1
+            action = _next_action(state)
+            if action is not None and not as_json:
+                shown = 0
+                if not _act(runtime, state, action, args, paint):
+                    return 1
+            elif action is not None and as_json:
+                print(json.dumps({"waiting": action, "hint": _hint(state, action)}), flush=True)
+                return 1
+            time.sleep(POLL)
+    except KeyboardInterrupt:
+        print()
+        return 130
+    finally:
+        runtime.close(timeout=5)
+
+
+def _ready(state):
+    steps = {step["id"]: step["state"] for step in state.get("steps") or ()}
+    return all(steps.get(name) == "done" for name in ("phone", "wda_build", "wda_running", "live"))
+
+
+def _failed(state):
+    build = state.get("build") or {}
+    if build.get("state") == "failed" and build.get("error"):
+        return build["error"]
+    return None
+
+
+def _next_action(state):
+    steps = {step["id"]: step for step in state.get("steps") or ()}
+    build, running, live = steps.get("wda_build"), steps.get("wda_running"), steps.get("live")
+    if build and build["state"] == "todo":
+        return "build"
+    if running and running["state"] == "todo" and build and build["state"] == "done":
+        return "start"
+    if live and live["state"] == "todo":
+        return "live"
+    if (state.get("wifi") or {}).get("state") == "asking":
+        return "wifi"
+    return None
+
+
+def _hint(state, action):
+    """What a run with no terminal to ask on says instead of the question: it never takes a yes for granted."""
+    if action != "wifi":
+        return "run mobster setup on a terminal to answer"
+    name = json.dumps((state.get("device") or {}).get("name") or "your iPhone", ensure_ascii=False)
+    return (f"Wi-Fi stays off for this iPhone until you say yes: run mobster setup on a terminal to answer, or run "
+            f"mobster wifi on --device {name} with it plugged in")
+
+
+def _yes(question, paint, default=True):
+    while True:
+        try:
+            answer = input(paint("? ", "accent", "bold") + question + (" [Y/n] " if default else " [y/N] ")
+                           ).strip().lower()
+        except EOFError:
+            return False
+        if answer == "":
+            return default
+        if answer in ("y", "yes"):
+            return True
+        if answer in ("n", "no"):
+            return False
+
+
+def _act(runtime, state, action, args, paint):
+    setup = runtime.setup
+    name = (state.get("device") or {}).get("name") or "your iPhone"
+    if action == "build":
+        teams = state.get("teams") or []
+        team = getattr(args, "team", None) or (teams[0].get("id") if len(teams) == 1 else None)
+        if team is None and len(teams) > 1:
+            print("Which Apple Account signs Mobster's helper?")
+            for index, item in enumerate(teams, 1):
+                print(f"  {paint(str(index), 'accent')}  {item.get('label') or item.get('id')}")
+            choice = input("Choose a number: ").strip()
+            if not choice.isdigit() or not 1 <= int(choice) <= len(teams):
+                return False
+            team = teams[int(choice) - 1].get("id")
+        if team is None:
+            print("Sign in to Xcode first: open Xcode, then Xcode › Settings › Accounts, choose +, and sign in "
+                  "with your Apple Account. Then run " + paint("mobster setup", "accent") + " again.")
+            return False
+        first = not (state.get("build") or {}).get("expires_at")
+        took = "The first install takes about 2 minutes." if first else "It's quicker than the first time."
+        if not _yes(f"Install Mobster's helper on {name}? Xcode signs it with your Apple Account. {took}", paint):
+            return False
+        setup.manager.start_build(team)
+        return True
+    if action == "start":
+        setup.manager.start_runner()
+        return True
+    if action == "live":
+        if not _yes("Let Mobster tap and type on your iPhone while a task runs? It asks before it sends, buys, "
+                    "posts or deletes.", paint):
+            return False
+        setup.set_live(True)
+        return True
+    if action == "wifi":
+        yes = _yes(f"Use {name} over Wi-Fi when it's unplugged? Mobster turns on its Connect via network switch "
+                   "over this cable, the same switch as in Xcode.", paint, default=False)
+        try:
+            setup.answer_wifi(state.get("device"), yes)
+        except LookupError:
+            pass   # the question ended meanwhile: unplugged, or answered in the Mac app
+        if not yes:
+            print(f"Wi-Fi stays off for {name}. To turn it on later, plug it in and run "
+                  + paint("mobster wifi on", "accent") + ".")
+        return True
+    return True
+
+
+def choose(runtime, name):
+    state = runtime.setup.state()
+    wanted = name.casefold()
+    for device in state.get("devices") or ():
+        if wanted in {str(device.get("udid", "")).casefold(), str(device.get("name", "")).casefold()}:
+            runtime.manager.choose(device["udid"])
+            return
+    raise LookupError(f"No iPhone called {name} is plugged in.")
+
+
+def open_runtime():
+    """The runtime `mobster serve --manage-device` runs, with no task history and the helper kept running on exit."""
+    import os
+
+    from . import server
+    from .cli_constants import DEFAULT_WDA_URL
+    from .config import app_env_file
+    from .paths import user_data_dir
+    from .tui.session import serve_config
+    config = serve_config(manage_device=True, wda_url=DEFAULT_WDA_URL, state_db=None,
+                          enable_live=os.environ.get("MOBSTER_ENABLE_LIVE") == "1", data_dir=user_data_dir(),
+                          env_file=app_env_file(), keep_runner=True)
+    return server.Runtime(config)
+
+
+def _width():
+    from .style import columns
+    return columns()

mobile_agent/setup_errors.py

@@ -0,0 +1,87 @@
+"""The setup failures people actually hit, as one line to act on and one button."""
+
+import re
+
+# The failures, most specific first: a destination error can mention Developer Mode, so
+# Developer Mode is tested before the generic "not available" wordings, and an expired
+# Xcode sign-in is told apart from a missing team before "Pick your Apple team".
+RULES = (
+    # iOS caps apps signed by a free Apple ID at 3 on the phone. Waiting never frees a slot; deleting one does.
+    ("free_app_limit", "Delete an app you installed with Xcode from your iPhone. A free Apple Account allows 3",
+     "retry",
+     (r"maximum number of apps for free development", r"maximum number of installed apps using a free developer",
+      r"installed apps using a free (developer|development) profile")),
+    ("app_id_limit",
+     "Your free Apple Account can make 10 app IDs a week. Wait a few days, or use a paid developer team",
+     "choose_team",
+     (r"maximum (number of )?app ?ids?", r"app id limit", r"may create up to \d+ app ids")),
+    ("bundle_conflict", "The helper's app ID is taken by another team. Install again to give it one of your own",
+     "retry",
+     (r"cannot be registered to your development team.*not available", r"failed registering bundle identifier")),
+    # The team is chosen, but Xcode's sign-in for it lapsed: the likeliest way a renewal fails days later.
+    ("xcode_signin", "Sign in again in Xcode › Settings › Accounts", "check_again",
+     (r"no account for team", r"no accounts? (with|for)\b", r"no accounts?: add a new account",
+      r"unable to log in with account", r"login details for account .* were rejected",
+      r"your session has expired")),
+    ("no_team", "Choose your Apple Account", "choose_team",
+     (r"requires a development team", r"no signing certificate", r"signing certificate .* not found",
+      r"no team (was )?selected")),
+    ("developer_mode", "Turn on Developer Mode: on your iPhone open Settings › Privacy & Security › Developer Mode",
+     "check_again",
+     (r"developer mode (is )?(disabled|off|not enabled)", r"enable developer mode",
+      r"developermodestatus.*false")),
+    ("untrusted_developer", "Trust Mobster's helper on your iPhone: open Settings › General › VPN & Device "
+                            "Management", "retry",
+     (r"not been explicitly trusted", r"developer app certificate is not trusted", r"untrusted developer",
+      r"invalid code signature", r"verify the developer app")),
+    # iOS asks for the passcode before UI automation starts unless the switch is on; unanswered, the start times out.
+    ("ui_automation", "On your iPhone, turn on Settings › Developer › Enable UI Automation, and keep it unlocked",
+     "retry",
+     (r"timed out while enabling automation mode", r"failed to initialize for ui testing",
+      r"ui automation (is )?(disabled|not enabled|off)", r"hasn't enabled automation mode")),
+    # Mobster tries a build that failed this way again by itself once the phone reads unlocked (retry_locked_build).
+    ("locked", "Unlock your iPhone and keep it unlocked. Mobster tries again by itself", "retry",
+     (r"device (is|was) locked", r"because the device is locked", r"could not,? be,? unlocked",
+      r"password protected \(-17\)", r"passcode (protected|is required)", r"unlock (your|the) (device|iphone)")),
+    ("not_trusted", "Unlock your iPhone and tap Trust, then enter your passcode", "check_again",
+     (r"pairing dialog response pending", r"user denied pairing", r"trust this computer",
+      r"has not trusted this (computer|mac)", r"not trusted by (the )?(device|iphone)")),
+    ("not_paired", "Unplug your iPhone, plug it back in and tap Trust", "check_again",
+     (r"invalid hostid", r"not paired", r"no pairing record", r"pairing (record )?(is )?(missing|invalid)",
+      r"could not (connect to lockdownd|pair)", r"lockdownd.*(-21|-3)\b")),
+    # Xcode installs what it lacks when it opens (Settings › Components for iOS): no Terminal command.
+    ("xcode_components", "Open Xcode and let it finish installing: Settings › Components › iOS, then try again",
+     "retry",
+     (r"-runfirstlaunch", r"is not installed\. to use with xcode", r"download and install the platform",
+      r"required plugin failed to load", r"coresimulator is out of date", r"requires a newer version of xcode",
+      r"no ios (platform|sdk)", r"platform .* (is )?not installed")),
+    ("disk_full", "Free up space on your Mac, then try again", "retry",
+     (r"no space left on device", r"disk (is )?full", r"not enough (free )?(disk )?space", r"errno 28",
+      r"out of disk space")),
+)
+PATTERNS = tuple((kind, fix, action, re.compile("|".join(patterns), re.I)) for kind, fix, action, patterns in RULES)
+RAW_LIMIT = 4000
+
+
+def translate(text):
+    """{"kind", "fix", "action", "raw"} for a failure people can act on, else None."""
+    if not isinstance(text, str) or not text.strip():
+        return None
+    for kind, fix, action, pattern in PATTERNS:
+        if pattern.search(text):
+            return {"kind": kind, "fix": fix, "action": action, "raw": raw_text(text)}
+    return None
+
+
+def raw_text(text):
+    """The tool's own words, trimmed to the lines that say what failed (for "Details")."""
+    lines = [line.rstrip() for line in str(text).splitlines() if line.strip()]
+    errors = [line for line in lines if re.search(r"\berror\b|failed|ERROR", line)]
+    kept = errors[-12:] if errors else lines[-12:]
+    return "\n".join(kept)[-RAW_LIMIT:]
+
+
+def problem(text, fallback=None):
+    """translate(text), or the raw text with no fix (``fix`` None) when nothing matches."""
+    return translate(text) or ({"kind": "unknown", "fix": None, "action": None, "raw": raw_text(text)}
+                               if isinstance(text, str) and text.strip() else fallback)