mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/packs/front_door.py

@@ -0,0 +1,316 @@
+"""The deterministic front door: a request that asks only for what a pack reader shows, or for a Settings page, is
+answered by code before any model call. It never acts: a request that holds an act word is never routed."""
+
+import os
+import re
+import time
+from dataclasses import dataclass, replace
+
+from .. import harness_api
+from . import core, health, pins, settings, tools
+
+ORDER = 2                       # after harness and long-form pick-up (0, 1), before the packs' own run fields (3)
+MAX_GOAL = 200
+MAX_N = 40
+# Run fields a routed run may carry: a conversation's id, who asked, the permission mode. Anything else (a workflow's
+# input, a destination, an account, a trigger, attachments, a replay mode) is a run the table wasn't written for.
+SAFE_EXTRAS = frozenset({"threadId", "via", "permissionMode"})
+# An app's name that is also what a request asks for ("messages"): the app is named by an alias, or started in.
+NOUNS = frozenset({"messages"})
+ALIASES = {"ig": "instagram", "insta": "instagram", "twitter": "x", "imessage": "messages",
+           "imessages": "messages"}
+
+# Words a request may hold besides an ask's own: politeness, question frames, determiners, "latest".
+STOP = frozenset("""a an the my of on in for to at up me please show tell give get read list check what whats what's
+is are do does i have how much many now currently right latest last newest recent recently most top first this that
+app""".split())
+# Any of these in a request, and nothing is routed. Wider than the table needs: a word here only costs a model call.
+ACTS = frozenset("""send sending sent post posting repost share buy purchase pay order book delete remove erase reset
+like unlike follow unfollow block report mute restrict reply respond comment subscribe accept decline approve confirm
+turn toggle enable disable change set update install uninstall clear add create write type call dial save unsend
+submit cancel forward archive move rename edit join leave sign log unlock restart shut allow deny schedule invite
+tag pin hide unhide""".split())
+OPEN_VERBS = frozenset({"open", "go", "launch", "navigate", "take"})
+OPEN_FILLER = frozenset({"to", "the", "my", "me", "app", "please", "up", "in", "and"})
+SEPARATORS = re.compile(r"\s*(?:›|»|→|->|=>|>|/)\s*")
+POLITE = re.compile(r"^(?:(?:hey|hi|ok|okay)[ ,]+)?(?:please[ ,]+)?"
+                    r"(?:(?:can|could|would|will) you[ ,]+(?:please[ ,]+)?)?"
+                    r"|[ ,.]*please[ .!?]*$", re.I)
+
+
+def phrases(*sets):
+    return tuple(frozenset(s.split()) for s in sets)
+
+
+def with_phone(*sets):
+    """Each set as is, and with the phone named ("what iOS version is this iPhone on")."""
+    out = []
+    for base in sets:
+        out.append(base)
+        out += [f"{base} {referent}" for referent in ("phone", "iphone", "device")]
+    return phrases(*out)
+
+
+@dataclass(frozen=True)
+class Ask:
+    pack: str                       # the pack's key
+    reader: str                     # one of the pack's readers
+    words: tuple                    # the content words the request may hold, as frozensets: one of these exactly
+    pick: tuple = ()                # (column, regex): answer only with the rows whose column matches
+    counted: bool = False           # "my last 10 DMs": a count is part of the ask
+    needs_app: bool = True          # the app must be named, started in, or in front (False: Settings' own words)
+
+
+ASKS = (
+    Ask("settings", "about", with_phone("ios version", "software version", "version ios"),
+        pick=("setting", r"^iOS Version$"), needs_app=False),
+    Ask("settings", "about", with_phone("model", "model name"), pick=("setting", r"^Model Name$"), needs_app=False),
+    Ask("settings", "storage", with_phone("storage", "free storage", "storage left", "storage space", "space left",
+                                          "free space", "available storage", "storage available",
+                                          "storage remaining", "free storage space"),
+        pick=("item", r"^(Used|Capacity|Free)$"), needs_app=False),
+    Ask("settings", "battery", with_phone("battery", "battery level", "battery percentage", "battery percent"),
+        pick=("setting", r"^Level$"), needs_app=False),
+    Ask("settings", "battery", with_phone("battery health"), pick=("setting", r"^Battery Health$"), needs_app=False),
+    Ask("instagram", "dms", phrases("dms", "dm", "direct messages", "messages"), counted=True),
+    Ask("tiktok", "dms", phrases("dms", "dm", "inbox", "messages"), counted=True),
+    Ask("x", "messages", phrases("dms", "dm", "messages"), counted=True),
+    Ask("messages", "inbox", phrases("conversations", "messages", "texts", "chats"), counted=True),
+    Ask("messages", "unread", phrases("unread messages", "unread texts", "unread conversations", "unread"),
+        counted=True),
+    Ask("calendar", "events", phrases("events", "upcoming events", "upcoming"), counted=True),
+)
+
+# Settings pages a request may open, as Settings names them, and the one parent a nested path must name. A page
+# nobody listed here (and a path nobody checked) goes to the model.
+SETTINGS_PAGES = {name.casefold(): name for name in settings.PAGES}
+PARENTS = {"about": "General", "iphone storage": "General", "software update": "General"}
+OWN_ROUTES = {"About": "about", "iPhone Storage": "storage", "Battery": "battery"}
+
+
+@dataclass(frozen=True)
+class Plan:
+    pack: core.Pack
+    kind: str                       # "read" or "open"
+    what: str                       # the reader or the route
+    n: int = 10
+    arg: str = None
+    ask: Ask = None
+    page: str = None                # an open's page, as Settings names it
+
+
+def tokens(text):
+    return re.findall(r"[a-z0-9&']+", str(text or "").casefold().replace("’", "'"))
+
+
+def packs_by_word():
+    """{word: pack} for every pack's name and key and the aliases people use."""
+    out = {}
+    for pack in registered():
+        for word in {pack.key, pack.name.casefold()} - NOUNS:
+            out[word] = pack
+    for alias, key in ALIASES.items():
+        pack = next((p for p in registered() if p.key == key), None)
+        if pack is not None:
+            out[alias] = pack
+    return out
+
+
+def registered():
+    from . import register
+    return register.all_packs()
+
+
+def reads_an_act(goal, words):
+    """Whether the request holds an act: an act word, or what the safety gate reads as one."""
+    from .. import harness_api as api
+    return (any(word in ACTS for word in words) or bool(core.NEVER.search(goal))
+            or api.commit_act("", goal, None, None) is not None)
+
+
+def parse(goal, *, app_bundle=None, front_bundle=None):
+    """The ``Plan`` for a request that is exactly an ask in the table or an open of a Settings page, else None."""
+    text = POLITE.sub("", str(goal or "").strip())
+    if not text or len(text) > MAX_GOAL or "\n" in text:
+        return None
+    words = tokens(text)
+    if not words or reads_an_act(text, words):
+        return None
+    if words[0] in OPEN_VERBS:
+        return parse_open(text)
+    return parse_read(words, app_bundle, front_bundle)
+
+
+def parse_read(words, app_bundle, front_bundle):
+    by_word = packs_by_word()
+    named = {by_word[w].key: by_word[w] for w in words if w in by_word}
+    if len(named) > 1:
+        return None                                    # two apps in one request: the model decides what is meant
+    numbers = [w for w in words if w.isdigit()]
+    if len(numbers) > 1 or (numbers and not 1 <= int(numbers[0]) <= MAX_N):
+        return None
+    content = frozenset(w for w in words if w not in STOP and not w.isdigit() and w not in by_word)
+    matches = []
+    for ask in ASKS:
+        pack = next((p for p in registered() if p.key == ask.pack), None)
+        if pack is None or ask.reader not in pack.readers or (named and ask.pack not in named):
+            continue
+        if content not in ask.words or (numbers and not ask.counted):
+            continue
+        if ask.needs_app and not (ask.pack in named or pack.bundle in (app_bundle, front_bundle)):
+            continue
+        matches.append((pack, ask))
+    if len(matches) != 1:
+        return None
+    pack, ask = matches[0]
+    n = int(numbers[0]) if numbers else pack.read_default.get(ask.reader, 10)
+    return Plan(pack, "read", ask.reader, n, None, ask)
+
+
+def parse_open(text):
+    """"open Settings", "go to Settings › General › About", "open settings > battery": Settings' own pages."""
+    parts = [p for p in SEPARATORS.split(text) if p.strip()]
+    first = [w for w in tokens(parts[0]) if w not in OPEN_VERBS and w not in OPEN_FILLER]
+    rest = [" ".join(tokens(p)) for p in parts[1:]]
+    if len(parts) == 1 and first and first[0] == "settings":
+        rest, first = [" ".join(first[1:])] if len(first) > 1 else [], ["settings"]
+    if first != ["settings"] or len(rest) > 2:
+        return None
+    pack = next((p for p in registered() if p.key == "settings"), None)
+    if pack is None:
+        return None
+    if not rest:
+        return Plan(pack, "open", "root")
+    pages = [SETTINGS_PAGES.get(name) for name in rest]
+    if None in pages:
+        return None
+    page = pages[-1]
+    if len(pages) == 2 and PARENTS.get(page.casefold()) != pages[0]:
+        return None                                    # a path nobody checked: not claimed
+    route = OWN_ROUTES.get(page, "find")
+    return Plan(pack, "open", route, arg=page if route == "find" else None, page=page)
+
+
+def enabled():
+    return os.environ.get("MOBSTER_FRONT_DOOR", "").strip().lower() not in ("off", "0", "false", "no")
+
+
+def eligible(ctx):
+    if not enabled() or getattr(ctx, "engine", None) != "smart" or not getattr(ctx, "goal", None):
+        return False
+    if set(ctx.extras or {}) - SAFE_EXTRAS:
+        return False
+    run = (getattr(getattr(ctx, "runtime", None), "runs", None) or {}).get(ctx.run_id)
+    if run is not None and (getattr(run, "output_schema", None) is not None
+                            or getattr(run, "output_format", None) in _structured()
+                            or getattr(run, "longform", None) or getattr(run, "pinned_apps", None)):
+        return False                                   # these need the model's structuring or its plan
+    return True
+
+
+def _structured():
+    from .. import smart_result
+    return smart_result.AUTOMATIC_FORMATS
+
+
+def front_app(driver):
+    """The bundle id in front on the phone when the connection can say, else None."""
+    reader = getattr(driver, "active_app", None)
+    if callable(reader) and getattr(driver, "reads_front_app", True):
+        try:
+            bundle = reader()
+        except Exception:  # noqa: BLE001 -- can't tell: not named
+            return None
+        return bundle if isinstance(bundle, str) else None
+    return None
+
+
+def hook(ctx, driver, approve):
+    """harness_api pre-run hook: answer the request by code, or None and the run goes on as it would."""
+    if driver is None or not eligible(ctx):
+        return None
+    words = tokens(ctx.goal)
+    # The phone is asked which app is in front only for a request that could use it (a bare "my DMs").
+    plan = parse(ctx.goal, app_bundle=ctx.app_bundle) or (
+        parse(ctx.goal, app_bundle=ctx.app_bundle, front_bundle=front_app(driver)) if words else None)
+    if plan is None:
+        return None
+    pinned = pins.aside(plan.pack)
+    if pinned:
+        ctx.emit({"event": "front_door", "routed": False, "pack": plan.pack.key, "why": pinned})
+        return None                                    # the general agent does it
+    gate = tools.run_gate(ctx.run_id, ctx.data_dir)
+    version = core.app_version(ctx.runtime, plan.pack.bundle)
+    trusted, why = gate.trust("pack", plan.pack.bundle, plan.what, None, version)
+    if not trusted:
+        ctx.emit({"event": "front_door", "routed": False, "pack": plan.pack.key, "why": why})
+        return None
+    from .register import _io
+    pack, started = plan.pack, time.monotonic()
+    ctx.emit({"event": "skill_started", "op": f"{pack.prefix}_{'READ' if plan.kind == 'read' else 'OPEN'}"})
+    io = _io(ctx, driver, pack)
+    try:
+        answer = _read(pack, io, plan) if plan.kind == "read" else _open(pack, io, plan)
+    except core.Lost as lost:
+        answer, why = None, str(lost).rstrip(".")
+    ok = answer is not None
+    gate.note(ok, "pack", pack.bundle)
+    event = {"pack": pack.key, "op": f"{pack.prefix}_{plan.kind.upper()}", "step": plan.what, "ok": ok, "door": True,
+             "ms": round((time.monotonic() - started) * 1000), "taps": io.taps, "version": version,
+             "how": "code", **({} if ok else {"why": why})}
+    ctx.emit({"event": "app_pack", **event})
+    health.record(ctx.data_dir,
+                  {k: v for k, v in event.items() if k != "why"} | ({} if ok else {"why": tools._quiet(why)}))
+    if not ok:
+        ctx.emit({"event": "front_door", "routed": False, "pack": pack.key, "why": why})
+        return None                                    # the model takes the phone where the code left it
+    return harness_api.PreRun(result=_result(ctx, answer, started))
+
+
+def _read(pack, io, plan):
+    result = pack.read(io, plan.what, plan.n, plan.arg)
+    rows = list(result.rows)
+    if plan.ask.pick:
+        column, pattern = plan.ask.pick
+        rows = [row for row in rows if re.search(pattern, str(row.get(column) or ""), re.I)]
+    if not rows:
+        raise core.Lost(f"{pack.read_titles.get(plan.what, plan.what)} showed nothing it could name")
+    columns = result.columns
+    keep = rows[:tools.FEEDBACK_ROWS]
+    lines = "\n".join(_pair(row, columns) if plan.ask.pick else
+                      tools.row_line(i + 1, row, columns, pack.required.get(plan.what, ()))
+                      for i, row in enumerate(keep))
+    note = f" It read {len(rows)} of the {plan.n} you asked for: {result.stopped}." if (
+        plan.ask.counted and len(rows) < plan.n and result.stopped) else ""
+    block = None if plan.ask.pick else tools.block_for(pack, replace(result, rows=rows))
+    return {"text": f"{pack.name}, {result.title}, as the screen shows it:\n{lines}{note}", "rows": rows,
+            "columns": columns, "title": result.title, "stopped": result.stopped, "block": block}
+
+
+def _pair(row, columns):
+    """One picked row as "iOS Version: 26.0.1" (its first two columns)."""
+    keys = [key for key, _label, _kind in columns][:2]
+    return ": ".join(core.plain(row.get(key)) for key in keys if row.get(key) not in (None, ""))
+
+
+def _open(pack, io, plan):
+    landing = core.navigate(pack, io, plan.what, plan.arg)
+    if not landing.ok:
+        raise core.Lost(landing.why)
+    page = plan.page or "Settings"
+    return {"text": f"Opened {page} in {pack.name}. The screen is {landing.seen.title}.", "rows": [], "columns": [],
+            "title": page, "stopped": None, "block": None}
+
+
+def _result(ctx, answer, started):
+    from .. import result_blocks as rb
+    scalars = (str, int, float, bool, type(None))
+    rows = [{k: v for k, v in row.items() if isinstance(v, scalars)} for row in answer["rows"]]
+    columns = [{"key": k, "label": label, "type": kind} for k, label, kind in answer["columns"]]
+    data = {"rows": rows, "columns": columns, "title": answer["title"], "stopped": answer["stopped"] or None} \
+        if rows else None
+    blocks = [answer["block"]] if answer["block"] else []
+    return {"event": "result", "status": "completed", "engine": "smart", "outcome": "done", "answer": answer["text"],
+            "reason": None, "data": data, "actions": 1, "decisions": 0, "costUsd": 0.0, "model": None,
+            "elapsed_ms": round((time.monotonic() - started) * 1000), "blocks": rb.envelope(blocks),
+            "independently_verified": True, "proof": []}

mobile_agent/packs/heal.py

@@ -0,0 +1,214 @@
+"""Packs that survive an app's redesigns and A/B tests: drift is logged, the general agent takes over at once, and a
+screen the pack missed can become a learned variant, used only after it passes a replay check."""
+
+import json
+import re
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import core
+
+KIND = "variant"            # the heal file's lines this module owns
+MIN_SIGNALS = 3
+MAX_SIGNALS = 6
+MAX_VARIANTS = 12          # per pack, version and screen
+MAX_LABEL = 28
+CHROME_TOP, CHROME_BOTTOM = .3, .85
+# A name, a handle, a number, a time or a link: never kept as a signal.
+PERSONAL = re.compile(r"(@|https?://|\d{2,}|\b\d+\s?[smhdw]\b|\bago\b|[\w.]+\.(com|net|org)\b|"
+                      r"^[A-Za-z0-9]+[._][A-Za-z0-9._]+$|^[A-Z][a-z]+ [A-Z][a-z]+$)", re.I)
+_stores = {}
+_lock = threading.Lock()
+
+
+def fingerprint(snapshot):
+    """The screen's structural hash (replay_core): which roles and label shapes, no text. None when unknown."""
+    try:
+        from ..replay_core.path import screen_hashes
+        hashed = screen_hashes(snapshot)
+        return hashed["hash"] if hashed else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def chrome(snapshot):
+    """The app's own words on ``snapshot``: short labels in its top part (titles, filters, the search field), the
+    current tab, and named buttons in between, with no name, handle, number, time or link in them."""
+    picked, seen = [], set()
+    for element in getattr(snapshot, "elements", ()) or ():
+        label = core.plain(element.label)
+        if not label or len(label) > MAX_LABEL or PERSONAL.search(label) or label.casefold() in seen:
+            continue
+        y = core.centre_y(element)
+        if y > CHROME_BOTTOM:
+            if not core.is_selected(element):
+                continue
+        elif y >= CHROME_TOP and element.role != "Button":
+            continue
+        seen.add(label.casefold())
+        picked.append((label, element.role, round(y, 2)))
+    picked.sort(key=lambda item: item[2])
+    return picked
+
+
+@dataclass(frozen=True)
+class Variant:
+    id: str
+    pack: str
+    version: str
+    screen: str
+    fingerprint: str
+    signals: tuple                                   # ({"pattern", "role", "region"}, ...)
+    pictured: bool
+    status: str = "proposed"                         # proposed | confirmed | trusted
+    runs: tuple = ()
+    at: float = 0.0
+    checked_at: float = 0.0
+
+    def spec(self, pack):
+        signals = tuple(core.Signal(re.compile(s["pattern"], re.I), s.get("role"), tuple(s["region"])
+                                    if s.get("region") else None) for s in self.signals)
+        title = pack.screen_title(self.screen)
+        if self.pictured:
+            return core.ScreenSpec(self.screen, title, (), "learned", ocr=signals)
+        return core.ScreenSpec(self.screen, title, signals, "learned")
+
+
+class Learned:
+    """The variants this Mac learned, by pack, app version and screen (a JSON file beside the journal)."""
+
+    def __init__(self, path, clock=time.time):
+        self.path = Path(path) if path else None
+        self.clock = clock
+        self.lock = threading.Lock()
+        self.version_on_phone = {}                   # pack key -> the app version the phone has, when known
+        newest = {}
+        if self.path is not None and self.path.exists():
+            try:
+                for line in self.path.read_text(encoding="utf-8").splitlines():
+                    try:
+                        item = json.loads(line)
+                    except ValueError:
+                        continue
+                    if item.get("kind") != KIND:
+                        continue
+                    item = {k: v for k, v in item.items() if k in Variant.__dataclass_fields__}
+                    newest[item["id"]] = Variant(**{**item, "signals": tuple(item.get("signals") or ()),
+                                                    "runs": tuple(item.get("runs") or ())})
+            except (OSError, TypeError, KeyError):
+                newest = {}
+        self.variants = list(newest.values())
+
+    def _write(self, variant):
+        """One line for ``variant``'s new state in the heal file (its newest line is its state)."""
+        if self.path is None:
+            return
+        from .. import hints
+        hints._append(self.path, {"kind": KIND, "source": "pack", **variant.__dict__, "signals": list(variant.signals),
+                                  "runs": list(variant.runs)})
+
+    def _replace(self, old, new):
+        self.variants = [new if v is old else v for v in self.variants]
+        self._write(new)
+
+    def propose(self, pack, snapshot, screen, version, run_id):
+        """A candidate variant of ``screen`` from ``snapshot`` (the pack missed it): its id, or None when the screen
+        shows too few of the app's own words to learn from."""
+        words = chrome(snapshot)[:MAX_SIGNALS]
+        if len(words) < MIN_SIGNALS:
+            return None
+        pictured = core.image_only(snapshot)
+        signals = tuple({"pattern": "^" + re.escape(label) + "$", "role": None if pictured else role,
+                         "region": [max(0.0, round(y - .06, 2)), min(1.0, round(y + .06, 2))]}
+                        for label, role, y in words)
+        mark = fingerprint(snapshot) or ""
+        with self.lock:
+            same = next((v for v in self.variants if (v.pack, v.version, v.screen) == (pack.key, version or "", screen)
+                         and (v.fingerprint == mark and mark or v.signals == signals)), None)
+            if same is not None:
+                if run_id and run_id not in same.runs:
+                    self._replace(same, Variant(**{**same.__dict__, "runs": (*same.runs, run_id)[-8:]}))
+                return same.id
+            kept = [v for v in self.variants if (v.pack, v.version, v.screen) == (pack.key, version or "", screen)]
+            if len(kept) >= MAX_VARIANTS:
+                return None
+            variant = Variant(f"{pack.key}-{screen}-{int(self.clock() * 1000) % 10**10}", pack.key, version or "",
+                              screen, mark, signals, pictured, "proposed", (run_id,) if run_id else (), self.clock())
+            self.variants.append(variant)
+            self._write(variant)
+            return variant.id
+
+    def confirm_run(self, run_id):
+        """The run finished completed: the general agent finished from the screens the pack missed in it."""
+        changed = 0
+        with self.lock:
+            for variant in list(self.variants):
+                if variant.status == "proposed" and run_id in variant.runs:
+                    self._replace(variant, Variant(**{**variant.__dict__, "status": "confirmed"}))
+                    changed += 1
+        return changed
+
+    def check(self, pack, snapshot, screen, version):
+        """The replay check, on a fresh screen the pack missed again: a confirmed variant of ``screen`` that names it,
+        while no built-in screen of another name does, becomes trusted."""
+        trusted = []
+        with self.lock:
+            others = [spec for spec in pack.screens if spec.name != screen]
+            rival = max((core.score(spec, snapshot)[0] for spec in others), default=0.0)
+            for variant in list(self.variants):
+                if (variant.pack, variant.version, variant.screen, variant.status) != (pack.key, version or "", screen,
+                                                                                      "confirmed"):
+                    continue
+                if core.image_only(snapshot) != variant.pictured:
+                    continue
+                value = core.score(variant.spec(pack), snapshot)[0]
+                if value >= core.SURE and rival < core.SURE:
+                    new = Variant(**{**variant.__dict__, "status": "trusted", "checked_at": self.clock()})
+                    self._replace(variant, new)
+                    trusted.append(new.id)
+        return trusted
+
+    def specs(self, pack):
+        """The trusted variants of ``pack`` as ScreenSpecs, for the app version on the phone (all, when unknown). An
+        act's control is never found through one: core.control_for reads the pack's own patterns."""
+        version = self.version_on_phone.get(pack.key)
+        return tuple(v.spec(pack) for v in self.variants if v.pack == pack.key and v.status == "trusted"
+                     and (not version or v.version in (version, "")))
+
+    def summary(self, pack_key):
+        counts = {}
+        for variant in self.variants:
+            if variant.pack == pack_key:
+                counts[variant.status] = counts.get(variant.status, 0) + 1
+        return counts
+
+
+def store_for(data_dir):
+    """The one Learned store of a data folder. Without one (a benchmark, a test), a fresh store that keeps nothing."""
+    if not data_dir:
+        return Learned(None)
+    from .. import hints
+    key = str(Path(data_dir) / hints.HEALS)
+    with _lock:
+        if key not in _stores:
+            _stores[key] = Learned(key)
+        return _stores[key]
+
+
+def confirm_run(run_id):
+    """A run that finished completed: confirm, in every store, the variants proposed from screens it missed."""
+    with _lock:
+        stores = list(_stores.values())
+    for store in stores:
+        store.confirm_run(run_id)
+
+
+def attach(packs, data_dir):
+    """Give ``packs`` the store of ``data_dir``: core.recognize then uses its trusted variants."""
+    store = store_for(data_dir)
+    if data_dir:
+        for pack in packs:
+            pack.learned = store
+    return store

mobile_agent/packs/health.py

@@ -0,0 +1,122 @@
+"""Pack health: which app version a pack was checked on, how its steps go on this Mac, and when it steps aside."""
+
+RECENT = 200
+
+
+def bundle_of(pack_key):
+    """The bundle id of the pack named ``pack_key`` (the ledger's ``app``), or the key when no pack has it."""
+    try:
+        from .register import all_packs
+        return next((pack.bundle for pack in all_packs() if pack.key == pack_key), pack_key)
+    except Exception:  # noqa: BLE001
+        return pack_key
+
+
+def record(data_dir, entry):
+    """Append one pack step (``entry``, no screen text) to the hint ledger."""
+    from .. import hints
+    hints.record(data_dir, {**entry, "kind": "use", "source": "pack", "app": bundle_of(entry.get("pack")),
+                            "key": entry.get("step"), "ok": bool(entry.get("ok"))})
+
+
+def recent(data_dir, pack_key=None, limit=RECENT):
+    """The newest ``limit`` pack steps (of one pack), oldest first."""
+    from .. import hints
+    lines = [e for e in hints.recent(data_dir, source="pack", limit=10 ** 6)
+             if e.get("kind", "use") == "use" and (pack_key is None or e.get("pack") == pack_key)]
+    return lines[-limit:]
+
+
+def status(pack, installed=None, entries=()):
+    """One pack's health: what it was checked on, what the phone has, and how its recent steps went."""
+    verified = pack.verified
+    steps = [e for e in entries if e.get("pack") == pack.key]
+    landed = sum(1 for e in steps if e.get("ok"))
+    aside = [e for e in steps if not e.get("ok")]
+    state = "unknown"
+    if steps:
+        state = "healthy" if not aside or landed / len(steps) >= .8 else "degraded"
+    changed = changed_screens(steps)
+    version = installed or (verified.version if verified else None)
+    if not steps:
+        line = f"{pack.name} pack: not used on this Mac yet"
+    elif changed:
+        line = (f"{pack.name} pack: working on {version}; {len(changed)} screen{'s' if len(changed) != 1 else ''} "
+                "changed")
+    else:
+        line = f"{pack.name} pack: working on {version}"
+    learned = (getattr(pack, "learned", None).summary(pack.key) if getattr(pack, "learned", None) is not None else {})
+    return {"pack": pack.key, "name": pack.name, "bundleId": pack.bundle, "summary": line,
+            "changedScreens": [{"screen": name, "title": pack.screen_title(name), "since": at, "version": v}
+                               for name, (at, v) in changed.items()],
+            "learned": learned,
+            "verified": ({"version": verified.version, "date": verified.date, "device": verified.device or None}
+                         if verified else None),
+            "pin": _pin(pack),
+            "installed": installed, "sameVersion": (installed == verified.version) if installed and verified else None,
+            "screens": [{"name": s.name, "title": s.title, "evidence": s.evidence} for s in pack.screens],
+            "steps": len(steps), "landed": landed, "steppedAside": len(aside), "state": state,
+            "lastProblem": ({"step": aside[-1].get("step"), "why": aside[-1].get("why"), "at": aside[-1].get("at"),
+                             "version": aside[-1].get("version")} if aside else None)}
+
+
+def _pin(pack):
+    """What the team pinned this pack to ("off" or an app version), and whether it steps aside; None with no pin."""
+    from . import pins
+    to = pins.current().get(pack.key)
+    return None if to is None else {"to": to, "aside": pins.aside(pack) is not None}
+
+
+def changed_screens(steps):
+    """{screen: (since, version)} for each screen a pack last failed to recognize (``unsure_screen``) with no
+    recognition of it since, in log order: the screens the app changed under the pack."""
+    missed = {}
+    for entry in steps:
+        if entry.get("unsure_screen"):
+            missed[entry["unsure_screen"]] = (entry.get("at") or 0, entry.get("version"))
+        elif entry.get("ok") and entry.get("screen"):
+            missed.pop(entry["screen"], None)
+    return missed
+
+
+def tab_routes(pack):
+    """The routes a health run visits: each reaches a screen from the tab bar by taps alone (no argument, no link
+    needed,
+    no act)."""
+    acts = {spec.route for spec in pack.controls.values()}
+    return [route for route in pack.routes.values()
+            if route.from_tabs and not route.arg and route.name not in acts and route.steps
+            and all(type(step).__name__ == "Tap" for step in route.steps)]
+
+
+def check(pack, io):
+    """Visit each tab route and say whether the pack named the screen it reached: [{route, screen, landed, confidence,
+    evidence, why}]."""
+    from . import core
+    rows = []
+    for route in tab_routes(pack):
+        landing = core.navigate(pack, io, route.name)
+        rows.append({"route": route.name, "title": route.title, "screen": landing.seen.screen, "landed": landing.ok,
+                     "confidence": landing.seen.confidence, "evidence": landing.seen.evidence or None,
+                     "why": landing.why or None})
+        if io.cancelled():
+            break
+    return rows
+
+
+def check_result(pack, rows, version, seconds):
+    """A health run's result, as a task's: the answer line and a checklist card."""
+    from .. import result_blocks as rb
+    landed = sum(1 for row in rows if row["landed"])
+    items = [{"id": f"s{i + 1}", "label": row["title"][:1].upper() + row["title"][1:],
+              "status": "pass" if row["landed"] else "fail",
+              "expected": f"{pack.name} shows {row['title']}",
+              "observed": (f"recognized ({row['confidence']:.2f})" if row["landed"] else (row["why"] or "not named"))}
+             for i, row in enumerate(rows)]
+    changed = len(rows) - landed
+    answer = (f"{pack.name} pack: working on {version or 'this version'}"
+              + (f"; {changed} screen{'s' if changed != 1 else ''} changed." if changed else "."))
+    return {"event": "result", "status": "completed", "engine": "smart", "outcome": "done" if not changed else "check",
+            "answer": answer, "actions": len(rows), "decisions": 0, "elapsed_ms": round(seconds * 1000),
+            "costUsd": 0.0, "model": None,
+            "blocks": rb.envelope([rb.checklist(items, title=f"{pack.name} pack health", id=f"{pack.key}-health")])}