mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/cli_run.py

@@ -0,0 +1,115 @@
+"""What a command's run needs besides parsing; run-time modules import it, never `__main__`,
+which `python -m` loads twice."""
+
+import os
+import sys
+
+from .cli_constants import DEFAULT_WDA_URL
+
+NO_KEY = "no model key yet. Run `mobster login`, then run this again."
+
+
+def output(value):
+    import json
+    try:
+        print(json.dumps(value, allow_nan=False), flush=True)
+    except BrokenPipeError:
+        # The reader went away (`demo | head -1`): stop quietly, not with a traceback on exit.
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        sys.exit(0)
+
+
+class stop_at_safe_point:
+    """While a task runs: the first ctrl+c, SIGTERM or SIGHUP sets ``stop``; a second raises KeyboardInterrupt."""
+
+    def __init__(self, stop, on_stop=None):
+        self.stop, self.on_stop, self.caught, self.previous = stop, on_stop, [], {}
+
+    def handler(self, signum, frame):
+        self.caught.append(signum)
+        if self.stop.is_set():
+            raise KeyboardInterrupt
+        self.stop.set()
+        if self.on_stop is not None:
+            self.on_stop()
+        try:
+            print("mobster: stopping at the next safe point (ctrl+c again to force)", file=sys.stderr, flush=True)
+        except (OSError, ValueError, RuntimeError):
+            # A signal can interrupt stderr's buffered write; the diagnostic must not turn Stop into an error.
+            pass
+
+    def __enter__(self):
+        import signal
+        import threading
+        if threading.current_thread() is threading.main_thread():
+            for name in ("SIGINT", "SIGTERM", "SIGHUP"):
+                number = getattr(signal, name, None)
+                if number is not None:
+                    self.previous[number] = signal.signal(number, self.handler)
+        return self.caught
+
+    def __exit__(self, *exc):
+        import signal
+        for number, old in self.previous.items():
+            signal.signal(number, old)
+        return False
+
+
+def event_printer(args, preview=False):
+    """``output`` (JSON lines) for scripts and --json; the step renderer on a terminal."""
+    if getattr(args, "json", False) or not sys.stdout.isatty():
+        return output
+    from .console import ConsoleRenderer
+    return ConsoleRenderer(preview=preview)
+
+
+def wda_url_for(args):
+    return (getattr(args, "wda_url", None) or os.environ.get("MOBSTER_WDA_URL") or DEFAULT_WDA_URL).rstrip("/")
+
+
+def device_target(name):
+    """The device `--device NAME` names (devices.discover), with a WDA address to drive."""
+    from . import devices
+    try:
+        item = devices.resolve(devices.discover(probe=False), name)
+    except LookupError as error:
+        raise NoDevice(str(error)) from None
+    if not item.get("wdaUrl"):
+        raise NoDevice(f"“{item['name']}” isn't set up yet. {item.get('reason') or ''} Set it up with "
+                       "`mobster setup`, or in Mobster for Mac.".replace("  ", " "))
+    return item
+
+
+class NoDevice(ConnectionError):
+    """Nothing answered at the WDA address (exit code 3)."""
+
+
+class DeviceBusy(RuntimeError):
+    """Another Mobster process holds the phone's device lease."""
+
+
+class MissingKey(ValueError):
+    """The model key a command needs is not set (exit code 3)."""
+
+
+def no_device_reason(exc):
+    """A few words on how reaching WDA failed, from the transport's message (which never holds a body)."""
+    text = f"{type(exc).__name__} {exc}".lower()
+    for needle, words in (("refused", "connection refused"), ("reset", "connection reset"),
+                          ("disconnected", "connection closed"), ("gaierror", "unknown host"),
+                          ("timeout", "timed out"), ("deadline", "timed out"), ("http 4", "not WebDriverAgent"),
+                          ("json", "not WebDriverAgent")):
+        if needle in text:
+            return words
+    return "no usable answer"
+
+
+def error_result(exc, exit_code):
+    """`run`'s (and `demo`'s) JSON line for an error before or around the run."""
+    return {"event": "result", "status": "error", "ok": False, "error_type": type(exc).__name__,
+            "error": str(exc), "reason": str(exc), "exit_code": exit_code}
+
+
+def error_line(exc):
+    """A human line for a terminal: what happened, then what to do."""
+    return f"mobster: {exc}"

mobile_agent/compiled_read/__init__.py

@@ -0,0 +1,21 @@
+"""Compiled reading, dark behind ``MOBSTER_EXPERIMENTAL_COMPILED_READ`` (default off).
+
+A screen is a typed interface, so reading it can be compiled the way acting is (learned/programs.py):
+
+- ``extractors``: a screen the model read into rows once is read again by code when it has the same shape;
+- ``delta``: a chained step sends the model the tree changes against a reference screen, not the whole tree;
+- ``routes``: a program learned for one app version is only offered for that version.
+
+Nothing here calls a model or imports a UI. The flag off, every hook returns what it was given.
+"""
+
+import os
+
+ENV_FLAG = "MOBSTER_EXPERIMENTAL_COMPILED_READ"
+
+
+def enabled(env=None):
+    """Whether compiled reading is switched on (``MOBSTER_EXPERIMENTAL_COMPILED_READ=1``)."""
+    env = os.environ if env is None else env
+    return (env.get(ENV_FLAG) or "").strip().casefold() in ("1", "true", "yes", "on")
+

mobile_agent/compiled_read/delta.py

@@ -0,0 +1,89 @@
+"""Token delta: a chained step sends the model what changed on the screen, not the whole tree.
+
+The prompt's screen section is one line per element (``e4 Cell "General" @0,20,100,7``), its alias counting down
+the screen. The agent's prompt keeps no earlier screen, so a diff alone would leave the model blind. The first
+full screen of a run (and any later one a diff can't describe) becomes the *reference*: it goes once in the
+prompt's cached part, and each next turn sends only
+
+- the lines that changed or are new, whole, under their own alias;
+- ``eN = reference eM`` for an element that is unchanged but moved from M to N (no arithmetic for the model);
+- ``e1-e5 as in the reference`` for a run of unchanged elements that kept their alias.
+
+A new app, a screen that shares under half of its lines with the reference (a scroll moves every row's frame) or a
+diff longer than ``MAX_RATIO`` of the full screen is sent whole and becomes the new reference. Actions still
+resolve through the current screen's aliases, so the diff changes what the model reads, never what an alias means.
+"""
+
+import difflib
+import re
+
+MAX_RATIO = .6
+MIN_SHARED = .5
+ALIAS = re.compile(r"^e(\d+) ")
+HEAD = "Changes since the reference screen (turn {turn}); `eN = reference eM` is the same element, once eM:"
+
+
+def _split(line):
+    found = ALIAS.match(line)
+    return (int(found.group(1)), line[found.end():]) if found else (None, line)
+
+
+def tokens(text):
+    """An estimate of tokens: four characters each. The model's own tokenizer isn't called."""
+    return -(-len(text) // 4)
+
+
+class Delta:
+    def __init__(self):
+        self.reference, self.app, self.turn, self.shipped = None, None, 0, False
+        self.stats = {"full": 0, "delta": 0, "tokens_full": 0, "tokens_new": 0, "tokens_cached_read": 0}
+
+    def screen(self, app, lines, turn=0):
+        """(reference lines to put in the cached part or None, the lines for this turn's screen section)."""
+        full = tokens("\n".join(lines))
+        body = self._diff(app, lines) if self.reference is not None and app == self.app else None
+        if body is None:
+            self.reference, self.app, self.turn, self.shipped = list(lines), app, turn, False
+            self.stats["full"] += 1
+            self.stats["tokens_full"] += full
+            self.stats["tokens_new"] += full
+            return None, lines
+        # The reference rides in the prompt's cached part: new input on its first turn, a cache read after.
+        held = tokens("\n".join(self.reference))
+        self.stats["delta"] += 1
+        self.stats["tokens_full"] += full
+        self.stats["tokens_new"] += tokens("\n".join(body)) + (0 if self.shipped else held)
+        self.stats["tokens_cached_read"] += held if self.shipped else 0
+        self.shipped = True
+        return list(self.reference), body
+
+    def _diff(self, app, lines):
+        old = [_split(line)[1] for line in self.reference]
+        new = [_split(line)[1] for line in lines]
+        matcher = difflib.SequenceMatcher(None, old, new, autojunk=False)
+        if matcher.ratio() < MIN_SHARED:
+            return None
+        body = []
+        for tag, a1, a2, b1, b2 in matcher.get_opcodes():
+            if tag == "equal":
+                if a1 == b1:
+                    body.append(f"e{b1 + 1}-e{b2} as in the reference" if b2 - b1 > 1
+                                else f"e{b1 + 1} as in the reference")
+                else:
+                    body.extend(f"e{b1 + k + 1} = reference e{a1 + k + 1}" for k in range(b2 - b1))
+            else:
+                body.extend(lines[b1:b2])
+        text = [HEAD.format(turn=self.turn), *body]
+        if tokens("\n".join(text)) > MAX_RATIO * tokens("\n".join(lines)):
+            return None
+        return text
+
+
+def for_agent(agent):
+    """The agent's Delta, made on first use; None with the flag off."""
+    from . import enabled
+    if not enabled():
+        return None
+    if getattr(agent, "_compiled_delta", None) is None:
+        agent._compiled_delta = Delta()
+    return agent._compiled_delta

mobile_agent/compiled_read/extractors.py

@@ -0,0 +1,202 @@
+"""Learned extractors: a screen the model read into rows is read again by code.
+
+After the model reads a screen (``read_screen``) every value it returned is found, word for word, on one line of the
+screen or in one of the ", " parts iOS joins a row's texts with. The extractor keeps which line (and part) fed which
+field of which row, and the screen's *skeleton*: each line's role, and for a line no value came from, a hash of its
+words (digit runs folded, so a clock or a count doesn't change it). A later screen with the same skeleton is read by
+taking those lines. Anything else is a miss and the model reads it.
+
+The confidence check is the skeleton itself: the same number of lines, the same roles, the same hashed labels
+where no value was, and every number field still a number. A value the model reworded (not a line's words) is not
+learned. The store keeps no screen text: roles, hashes and line numbers only, in a replay_core path of kind
+"extractor" (replay_core/store.py's Cache: 0600 files, written atomically).
+"""
+
+import hashlib
+import re
+
+from ..replay_core.path import signature_hash
+from ..replay_core.store import Cache, env_of
+
+MAX_PER_KEY = 8
+MAX_LINES = 400
+NUMBER = re.compile(r"([+-]?(?:\d+\.?\d*|\.\d+))(?:\s+[^\W\d_]+)?")   # "4.8", "4.8 stars"
+
+
+def _hash(words):
+    return hashlib.sha1(re.sub(r"\d+", "#", words).encode()).hexdigest()[:10]
+
+
+def _number(words):
+    found = NUMBER.fullmatch(words)
+    return float(found.group(1)) if found else None
+
+
+def _kind(value):
+    return "n" if isinstance(value, (int, float)) and not isinstance(value, bool) else "s"
+
+
+def _parts(words):
+    """A composite label's parts: iOS joins a row's texts with ", " ("Rye loaf, $6.50, 4.8 stars")."""
+    return words.split(", ")
+
+
+def _matches(value, words):
+    if isinstance(value, str):
+        return words == value
+    number = _number(words)
+    return number is not None and number == value
+
+
+def _where(value, lines, taken, after):
+    """(line, part) holding ``value`` exactly, the whole line (part None) before a part of it; the first after the
+    previous pick, else the first unused. None when no line has it."""
+    found = []
+    for index, (_, words) in enumerate(lines):
+        if (index, None) not in taken and _matches(value, words):
+            found.append((index, None))
+        parts = _parts(words)
+        if len(parts) > 1:
+            found.extend((index, k) for k, part in enumerate(parts)
+                         if (index, k) not in taken and _matches(value, part))
+    later = [spot for spot in found if (spot[0], -1 if spot[1] is None else spot[1]) > after]
+    return (later or found or [None])[0]
+
+
+def learn(lines, rows, fields):
+    """An extractor for ``rows`` read off ``lines`` ([(role, words)]), or None when a value isn't a line's words
+    (or one of its ", " parts)."""
+    if not rows or len(lines) > MAX_LINES:
+        return None
+    taken, picks, kinds, after = set(), [], {}, (-1, -1)
+    for row in rows:
+        if not isinstance(row, dict) or set(row) != set(fields):
+            return None
+        pick = []
+        for name in fields:
+            value = row[name]
+            if value is None:
+                pick.append(None)
+                continue
+            if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+                return None
+            kind = _kind(value)
+            if kinds.setdefault(name, kind) != kind or (kind == "s" and not value):
+                return None
+            spot = _where(value, lines, taken, after)
+            if spot is None:
+                return None
+            taken.add(spot)
+            after = (spot[0], -1 if spot[1] is None else spot[1])
+            pick.append(list(spot))
+        picks.append(pick)
+    whole = {name: kind == "n" and all(float(row[name]).is_integer() for row in rows if row[name] is not None)
+             for name, kind in kinds.items()}
+    used = {line for line, _ in taken}
+    skeleton = [[role, None if index in used else _hash(words)] for index, (role, words) in enumerate(lines)]
+    return {"skeleton": skeleton, "rows": picks, "kinds": [kinds.get(name, "s") for name in fields],
+            "whole": [bool(whole.get(name)) for name in fields]}
+
+
+def _text(lines, spot):
+    line, part = spot
+    words = lines[line][1]
+    return words if part is None else _parts(words)[part]
+
+
+def extract(extractor, lines, fields):
+    """The rows ``extractor`` reads from ``lines``, or None when the screen isn't the one it was learned on."""
+    skeleton = extractor.get("skeleton")
+    if not isinstance(skeleton, list) or len(skeleton) != len(lines):
+        return None
+    for (role, words), (want_role, want_hash) in zip(lines, skeleton):
+        if role != want_role or (want_hash is not None and _hash(words) != want_hash):
+            return None
+    kinds, whole = extractor["kinds"], extractor["whole"]
+    rows = []
+    for pick in extractor["rows"]:
+        row = {}
+        for position, name in enumerate(fields):
+            if pick[position] is None:
+                row[name] = None
+                continue
+            try:
+                text = _text(lines, pick[position])
+            except IndexError:      # a composite label with fewer parts than it had
+                return None
+            if kinds[position] == "n":
+                number = _number(text)
+                if number is None:
+                    return None
+                row[name] = int(number) if whole[position] else number
+            else:
+                row[name] = text
+        rows.append(row)
+    return rows
+
+
+class Extractors:
+    """The extractors in ``directory``, one replay_core path per (app, fields); counts of hits and misses kept in it."""
+
+    def __init__(self, directory):
+        self.cache = Cache(directory)
+
+    @staticmethod
+    def identity(app, fields):
+        return {"kind": "extractor", "app": app or None, "fields": list(fields)}
+
+    @staticmethod
+    def env(version=None, runtime=None, device=None):
+        return env_of(version, runtime, device)
+
+    def _load(self, identity, env):
+        return self.cache.load(identity, env)
+
+    def read(self, app, fields, lines, env=None):
+        """The rows read by code, or None (no extractor fits: the model reads, then ``remember``)."""
+        env = env or self.env()
+        identity = self.identity(app, fields)
+        path = self._load(identity, env)
+        if path is None:
+            return None
+        rows = None
+        for extractor in path.get("extractors") or ():
+            try:
+                rows = extract(extractor, lines, fields)
+            except (KeyError, IndexError, TypeError, ValueError):
+                rows = None
+            if rows is not None:
+                break
+        path["hits" if rows is not None else "misses"] = int(path.get("hits" if rows is not None else "misses")
+                                                              or 0) + 1
+        self._save(path)
+        return rows
+
+    def remember(self, app, fields, lines, rows, env=None):
+        """Keep the extractor for ``rows`` the model read off ``lines``; True when one was learned."""
+        extractor = learn(lines, rows, fields)
+        if extractor is None:
+            return False
+        env = env or self.env()
+        identity = self.identity(app, fields)
+        path = self._load(identity, env)
+        if path is None:
+            from ..replay_core.path import new_path
+            step = {"op": "READ_LIST", "app": app or None, "live": True,
+                    "screen": {"hash": signature_hash(extractor["skeleton"])}}
+            path = new_path([step], kind="extractor", identity=identity, env=env)
+            path["extractors"], path["hits"], path["misses"] = [], 0, 0
+        known = [e for e in path["extractors"] if e.get("skeleton") != extractor["skeleton"]]
+        path["extractors"] = [extractor, *known][:MAX_PER_KEY]
+        self._save(path)
+        return True
+
+    def counts(self, app, fields, env=None):
+        path = self._load(self.identity(app, fields), env or self.env())
+        return {"hits": int((path or {}).get("hits") or 0), "misses": int((path or {}).get("misses") or 0)}
+
+    def _save(self, path):
+        try:
+            self.cache.save(path)
+        except (OSError, ValueError):
+            pass

mobile_agent/compiled_read/routes.py

@@ -0,0 +1,56 @@
+"""The local route corpus: saved programs keyed by the app version they were learned on.
+
+A route is a saved program (learned/programs.py): a goal template and the steps that did it, as hashed screens plus
+the controls' roles and names. The program store already finds a route first (``pre_run`` consults it before the model
+plans); what it lacked is the version: a program learned on one build of an app replayed on the next and relied on
+the step check to notice. With the flag on, a program is stored under the app's version (replay_core/store.py's env
+key, so two builds keep two routes) and a later run is offered only the routes of its own version, or those learned
+before versions were kept.
+
+``shareable`` is the record a later opt-in sharing lane can send: the app, its version, a hash of the goal template
+and each step's op, role and hashed label and screen. No screen text, no typed text, no template.
+"""
+
+import hashlib
+
+from ..learned.programs import BLANK, folded
+
+
+def goal_fingerprint(template):
+    """16 hex digits for a goal template: blanks, case, spacing and end punctuation don't change it."""
+    return hashlib.sha256(BLANK.sub("{}", folded(template)).encode()).hexdigest()[:16]
+
+
+def version_of(runtime, bundle):
+    """The version of ``bundle`` on the phone, or None (unknown: routes are then not told apart)."""
+    from ..packs.core import app_version
+    try:
+        return app_version(runtime, bundle)
+    except Exception:
+        return None
+
+
+def fits_version(path, version):
+    """True when ``path`` may be offered on an app at ``version`` (None: any; a path without a version: always)."""
+    known = (path.get("env") or {}).get("app_version")
+    return version is None or known is None or known == version
+
+
+def _digest(text):
+    return hashlib.sha1(str(text or "").encode()).hexdigest()[:10]
+
+
+def shareable(path):
+    """The hashes-only record of a route, or None when it has no version or a step it can't describe."""
+    identity, env = path.get("identity") or {}, path.get("env") or {}
+    if identity.get("kind") != "program" or not env.get("app_version") or not identity.get("app"):
+        return None
+    steps = []
+    for step in path.get("steps") or ():
+        target = step.get("target") if isinstance(step.get("target"), dict) else {}
+        screen = step.get("screen") if isinstance(step.get("screen"), dict) else {}
+        steps.append({"op": step.get("op"), "role": target.get("role") or None,
+                      "label": _digest(target.get("label")) if target.get("label") else None,
+                      "screen": str(screen.get("hash") or "")[:16] or None})
+    return {"app": identity["app"], "version": env["app_version"], "ios": env.get("ios"),
+            "goal": goal_fingerprint(identity.get("template") or ""), "steps": steps}