mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/intents/harvest.py

@@ -0,0 +1,91 @@
+"""Fill the atlas for a simulator: its apps' bundles through simctl, then each applinks domain's AASA over the network.
+
+The bundle read is local and quick; the AASA fetch is the only network use, runs in the background when the runner
+calls ``on_device_ready``, and is cached with the atlas under the app data folder. A failure is logged and never
+stops a run.
+"""
+
+import threading
+import time
+import urllib.request
+
+from . import atlas as atlas_module
+from . import enabled
+
+MAX_AGE_SECONDS = 24 * 3600
+AASA_BYTES = 1_000_000
+AASA_PATH = "/.well-known/apple-app-site-association"
+
+
+def fetch_aasa(domain, timeout=5):
+    """The AASA text of ``domain`` (https only, no redirects followed beyond urllib's default), or None."""
+    if not atlas_module.DOMAIN.match(domain or ""):
+        return None
+    with urllib.request.urlopen(f"https://{domain}{AASA_PATH}", timeout=timeout) as reply:   # noqa: S310 (https)
+        return reply.read(AASA_BYTES).decode("utf-8", "replace")
+
+
+def fill_aasa(atlas, fetch, log):
+    """Fetch each domain with no rules yet, once per domain. ``fetch(domain)`` raises or returns text or None."""
+    seen = {}
+    for entry in atlas.entries.values():
+        for domain in entry.domains:
+            if entry.paths.get(domain):
+                continue
+            if domain not in seen:
+                try:
+                    seen[domain] = fetch(domain)
+                except Exception as error:
+                    seen[domain] = None
+                    log(f"intents: no AASA for {domain} ({type(error).__name__})")
+            if seen[domain]:
+                atlas.add_aasa(entry.bundle, domain, seen[domain])
+    return atlas
+
+
+def harvest(udid, run, *, fetch=None, log=print, force=False, now=time.time):
+    """The simulator's atlas, saved under the app data folder. A cache younger than a day is reused unless
+    ``force``. Cached AASA rules carry over a bundle re-read. ``fetch=None`` never touches the network."""
+    path = atlas_module.path_for(udid)
+    if not force:
+        try:
+            if now() - path.stat().st_mtime < MAX_AGE_SECONDS:
+                return atlas_module.load(udid)
+        except OSError:
+            pass
+    fresh = atlas_module.harvest_simulator(udid, run)
+    old = atlas_module.load(udid)
+    for entry in fresh.entries.values():
+        before = old.entries.get(entry.bundle)
+        if before is not None:
+            entry.paths = {d: r for d, r in before.paths.items() if d in entry.domains}
+    if fetch is not None:
+        fill_aasa(fresh, fetch, log)
+    atlas_module.save(udid, fresh)
+    return fresh
+
+
+def on_device_ready(udid, log=print, *, run=None, fetch=fetch_aasa, background=True):
+    """The runner's device-ready step: refresh the atlas when the flag is on. Reads bundles now (quick) and fetches
+    AASA in a daemon thread. Never raises."""
+    if not enabled() or not udid:
+        return None
+    try:
+        if run is None:
+            from ..sim.simctl import run as simctl_run
+            run = simctl_run
+        atlas = harvest(udid, run, log=log)          # bundles only; cached for a day
+        if fetch is not None and any(not e.paths.get(d) for e in atlas.entries.values() for d in e.domains):
+            def finish():
+                try:
+                    atlas_module.save(udid, fill_aasa(atlas_module.load(udid), fetch, log))
+                except Exception as error:
+                    log(f"intents: AASA fetch stopped ({type(error).__name__})")
+            if background:
+                threading.Thread(target=finish, name="mobster-intents-aasa", daemon=True).start()
+            else:
+                finish()
+        return atlas
+    except Exception as error:
+        log(f"intents: atlas not refreshed ({type(error).__name__})")
+        return None

mobile_agent/intents/plan.py

@@ -0,0 +1,93 @@
+"""The plan phase's question: does this goal have a deterministic path? Answers with links, never with taps.
+
+Layers, in order: ``deeplinks.LINKS`` (hand-curated; "verified" only with a real-iPhone date), then the atlas
+(discovered, never verified). A proposal is a suggestion: ``deeplinks.decide`` still governs whether it opens, and
+only links that open a screen are proposed (nothing that acts, writes or needs an unknown placeholder).
+"""
+
+from .. import deeplinks
+
+
+def propose(goal, atlas, installed=None):
+    """Up to 5 {"layer", "app", "url", "state"} for ``goal``, best first. ``installed``: bundle ids on the phone."""
+    out = []
+    seen = set()
+    said = str(goal or "").casefold()
+    for link in deeplinks.LINKS:
+        if (link.app.casefold() in said and link.risk == "opens" and not link.params
+                and (installed is None or not link.bundle or link.bundle in installed)):
+            out.append({"layer": "links", "app": link.app, "url": link.template, "bundle": link.bundle,
+                        "state": "verified" if link.verified else "known", "bestEffort": link.best_effort})
+            seen.add(link.template)
+    for entry in atlas.named_in(goal):
+        if installed is not None and entry.bundle not in installed:
+            continue
+        for scheme in entry.schemes:
+            url = f"{scheme}://"
+            try:
+                safe = deeplinks.risk_of(url) == "opens"
+            except deeplinks.LinkError:
+                safe = False
+            if safe and url not in seen:
+                out.append({"layer": "atlas", "app": entry.name, "url": url, "bundle": entry.bundle,
+                            "state": "discovered", "bestEffort": False})
+    return out[:5]
+
+
+class Tally:
+    """Link-first outcomes for the run report: ``taken`` links that opened the screen, ``missed`` that did not."""
+
+    def __init__(self):
+        self.taken = self.missed = 0
+
+    def record(self, landed):
+        if landed:
+            self.taken += 1
+        else:
+            self.missed += 1
+
+    def public(self):
+        return {"linkFirst": {"taken": self.taken, "missed": self.missed}}
+
+
+class LinkFirst:
+    """The agent's first turn, when the goal names one app and a link opens it: that turn opens the link (the
+    OPEN_URL skill, so ``deeplinks.decide`` and the app guard still govern) instead of asking the model for it.
+    ``turn`` answers the first call, ``settle`` is told the screen the next turn sees. Counts feed the run report."""
+
+    def __init__(self, atlas):
+        self.atlas = atlas
+        self.tried = False
+        self.pending = None      # the bundle the link should have opened
+        self.tally = Tally()
+
+    @classmethod
+    def for_device(cls, key):
+        from . import atlas
+        return cls(atlas.load(key))
+
+    def settle(self, snapshot):
+        if self.pending is not None:
+            self.tally.record(getattr(snapshot, "bundle_id", None) == self.pending)
+            self.pending = None
+
+    def turn(self, goal, apps):
+        """The model-shaped reply for the link-first turn, or None (the model decides). Once per run."""
+        if self.tried:
+            return None
+        self.tried = True
+        found = [p for p in propose(goal, self.atlas, installed=set(apps)) if not p["bestEffort"] and p["bundle"]]
+        if len({p["bundle"] for p in found}) != 1:
+            return None          # no app, or two: the model chooses
+        link = found[0]
+        self.pending = link["bundle"]
+        return {"thought": f"link first: {link['url']} ({link['state']})", "plan": None, "notes_add": [],
+                "checklist_updates": [], "answer": None,
+                "actions": [{"operation": "OPEN_URL", "target": None, "target_label": None, "text": link["url"],
+                             "app": None}]}
+
+    def counts(self):
+        if not (self.tally.taken or self.tally.missed):
+            return {}
+        return {"link_first": self.tally.taken + self.tally.missed, "link_first_landed": self.tally.taken,
+                "model_calls_saved": self.tally.taken + self.tally.missed}

mobile_agent/ios/__init__.py

@@ -0,0 +1 @@
+"""iOS itself, as an expert knows it."""

mobile_agent/ios/guide.py

@@ -0,0 +1,16 @@
+"""A turn's section of Mobster's iOS guide (kb.py): on iOS's own screens (the Home Screen, the App Library,
+Spotlight, Control Center, Settings, a keyboard), the few entries about that screen and the request, for the phone's
+iOS version. The engine gets it through harness_api's "ios_slice" hook (engine_hooks.py); elsewhere it is "".
+
+Measured 14 Oct 2026 (paired A/B, 12 Settings tasks on an iOS 26.4 simulator, Sonnet 5.5 low, one run per arm): with
+the section, 12/12 passed in 71 model calls, 43 actions and $0.328; without it, 12/12 in 79 calls, 55 actions and
+$0.338. An IOS_DOCS lookup tool offered instead was never called (0 of 12 runs) and was removed. The ``ios_docs`` MCP
+tool (mcp.py) answers the same guide for other agents."""
+
+from . import kb, system
+
+
+def turn_slice(snapshot, request, driver):
+    """The section for this turn's screen, or ""."""
+    return kb.slice_text(getattr(snapshot, "bundle_id", ""), [e.label for e in snapshot.elements],
+                         system.ios_version(driver), getattr(snapshot, "keyboard", ""), request)

mobile_agent/ios/kb.py

@@ -0,0 +1,212 @@
+"""The iOS knowledge base."""
+
+import math
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+
+NEWEST = 26
+OLDEST = 18
+# BM25's usual constants; titles and keywords count twice (they name the task, the text explains it).
+K1, B = 1.2, .75
+TITLE_WEIGHT = 2
+MAX_K = 8
+SLICE_CHARS = 900
+# A request match joins a screen's slice at this share of the best match's score.
+RELATED = .6
+WORD = re.compile(r"[a-z0-9]+(?:'[a-z]+)?")
+STOP = frozenset("a an and are as at be by can do does for from how i if in into is it its me my of on or so that "
+                 "the then this to up what when where which with you your".split())
+SPRINGBOARD = "com.apple.springboard"
+SETTINGS = "com.apple.Preferences"
+SPOTLIGHT = "com.apple.Spotlight"
+
+
+@dataclass(frozen=True)
+class Entry:
+    id: str
+    topic: str
+    title: str
+    ios: tuple            # (min, max) iOS majors, inclusive
+    text: str
+    keywords: tuple = ()
+    screens: tuple = ()
+    source: tuple = ()
+
+    def holds_for(self, major):
+        return self.ios[0] <= major <= self.ios[1]
+
+    def line(self):
+        """The entry as one line for the model: its title, then its text."""
+        return f"{self.title}: {self.text}"
+
+    def public(self):
+        return {"id": self.id, "topic": self.topic, "title": self.title, "ios": list(self.ios), "text": self.text}
+
+
+def major(version):
+    """The iOS major of "26.0.1", "iOS 18.4", 26 or None; None when it can't be read."""
+    if isinstance(version, bool):
+        return None
+    if isinstance(version, int):
+        return version
+    found = re.search(r"(\d{1,2})(?:\.\d+)*", str(version or ""))
+    return int(found.group(1)) if found else None
+
+
+def known(version):
+    """The iOS major the base answers for."""
+    wanted = major(version)
+    if wanted is None or wanted > NEWEST:
+        return NEWEST
+    return max(OLDEST, wanted)
+
+
+def words(text):
+    return [w for w in WORD.findall(str(text or "").casefold().replace("’", "'")) if w not in STOP]
+
+
+@lru_cache(maxsize=1)
+def entries():
+    """Every entry, checked: unique ids, a valid version range, text present."""
+    from .kb_data import ENTRIES
+    out, seen = [], set()
+    for raw in ENTRIES:
+        low, high = raw["ios"]
+        entry = Entry(id=raw["id"], topic=raw["topic"], title=raw["title"], ios=(int(low), int(high)),
+                      text=" ".join(raw["text"].split()), keywords=tuple(raw.get("keywords") or ()),
+                      screens=tuple(raw.get("screens") or ()), source=tuple(raw.get("source") or ()))
+        if entry.id in seen or not entry.text or not OLDEST <= entry.ios[0] <= entry.ios[1] <= NEWEST:
+            raise ValueError(f"bad knowledge-base entry {entry.id}")
+        seen.add(entry.id)
+        out.append(entry)
+    return tuple(out)
+
+
+class Index:
+    """BM25 over a set of entries."""
+
+    def __init__(self, items):
+        self.items = tuple(items)
+        self.docs = []
+        for entry in self.items:
+            terms = words(entry.text) + TITLE_WEIGHT * (words(entry.title) + words(" ".join(entry.keywords)))
+            counts = {}
+            for term in terms:
+                counts[term] = counts.get(term, 0) + 1
+            self.docs.append((counts, len(terms)))
+        self.average = sum(length for _, length in self.docs) / max(1, len(self.docs))
+        frequency = {}
+        for counts, _ in self.docs:
+            for term in counts:
+                frequency[term] = frequency.get(term, 0) + 1
+        n = len(self.docs)
+        self.idf = {term: math.log(1 + (n - f + .5) / (f + .5)) for term, f in frequency.items()}
+
+    def scores(self, text):
+        terms = set(words(text))
+        out = []
+        for entry, (counts, length) in zip(self.items, self.docs):
+            score = 0.0
+            for term in terms:
+                tf = counts.get(term)
+                if tf:
+                    score += self.idf[term] * tf * (K1 + 1) / (tf + K1 * (1 - B + B * length / self.average))
+            if score > 0:
+                out.append((score, entry))
+        out.sort(key=lambda pair: -pair[0])
+        return out
+
+
+@lru_cache(maxsize=4)
+def index_for(ios_major):
+    return Index(entry for entry in entries() if entry.holds_for(ios_major))
+
+
+def query(text, ios=None, k=4):
+    """The ``k`` entries that best answer ``text`` on that iOS version (BM25), best first; () for no match."""
+    k = max(1, min(int(k or 4), MAX_K))
+    return tuple(entry for _, entry in index_for(known(ios)).scores(text)[:k])
+
+
+def answer(text, ios=None, k=4):
+    """``query`` as text for a person or a model: one line per entry, with the version it holds for."""
+    found = query(text, ios, k)
+    version = known(ios)
+    head = f"iOS {version}" + ("" if major(ios) == version else
+                               f" (the phone's version {'is unknown' if major(ios) is None else 'is ' + str(ios)})")
+    if not found:
+        return f"{head}: nothing in Mobster's iOS guide matches “{str(text)[:80]}”."
+    return head + ":\n" + "\n".join(f"- {entry.line()}" for entry in found)
+
+
+# Which screen of iOS's own is in front, from its labels: (name, the entries' topic or id prefixes, a test).
+def screen_of(bundle, labels, keyboard=""):
+    text = {" ".join(str(label or "").split()).casefold() for label in labels or ()}
+    # OCR reads a search field's magnifier as a "Q" before its placeholder ("Q App Library", "Q Search").
+    text |= {label[2:] for label in text if label.startswith("q ")}
+    if bundle == SPOTLIGHT or "spotlightsearchfield" in text or "top hit" in text and bundle in (SPRINGBOARD, ""):
+        return "spotlight"
+    if bundle == SPRINGBOARD or not bundle:
+        if "app library" in text or "dewey-search-field" in text:
+            return "app_library"
+        if "add controls" in text or {"focus", "screen mirroring"} <= text:
+            return "control_center"
+        if any(label.startswith("page ") and " of " in label for label in text) or "page control" in text \
+                or "q search" in text:
+            return "home"
+    if bundle == SETTINGS:
+        return "settings"
+    if keyboard == "visible":
+        return "keyboard"
+    return ""
+
+
+SLICES = {
+    "home": ("home.spotlight.hidden_app", "home.app_library.search"),
+    "app_library": ("home.app_library.search",),
+    "spotlight": ("home.spotlight.hidden_app", "home.app_library.search"),
+    "control_center": ("panels.control_center.controls", "panels.control_center.wifi_bluetooth"),
+    "settings": ("settings.search", "settings.search.no_results"),
+    "keyboard": ("keyboard.dismiss", "keyboard.return_key"),
+}
+# Where an entry about the request may join a screen's slice: entries written for that screen (or for any).
+SCREEN_BUNDLES = {"home": SPRINGBOARD, "app_library": SPRINGBOARD, "spotlight": SPRINGBOARD,
+                  "control_center": SPRINGBOARD, "settings": SETTINGS, "keyboard": "keyboard"}
+
+
+def slice_for(bundle, labels, ios=None, keyboard="", request="", k=3):
+    """The entries about the iOS screen in front, at most ``k``."""
+    screen = screen_of(bundle, labels, keyboard)
+    prefixes = SLICES.get(screen)
+    if not prefixes:
+        return ()
+    version = known(ios)
+    out = []
+    if request:
+        where = {SCREEN_BUNDLES.get(screen), "any"} | ({SPOTLIGHT} if screen == "spotlight" else set())
+        scored = index_for(version).scores(request)
+        best = scored[0][0] if scored else 0
+        for score, entry in scored[:8]:
+            if score >= RELATED * best and where & set(entry.screens) and len(out) < 2:
+                out.append(entry)
+    for prefix in prefixes:
+        for entry in entries():
+            if entry.holds_for(version) and (entry.id == prefix or entry.id.startswith(prefix + ".")) \
+                    and entry not in out:
+                out.append(entry)
+                break
+    return tuple(out[:k])
+
+
+def slice_text(bundle, labels, ios=None, keyboard="", request=""):
+    """``slice_for`` as a short prompt section of whole entries, at most SLICE_CHARS; "" off iOS's own screens."""
+    lines = []
+    for entry in slice_for(bundle, labels, ios, keyboard, request):
+        line = f"- {entry.line()}"
+        if sum(len(x) + 1 for x in lines) + len(line) > SLICE_CHARS:
+            break
+        lines.append(line)
+    if not lines:
+        return ""
+    return f"\n\nHow iOS {known(ios)} works here (Mobster's iOS guide):\n" + "\n".join(lines)