mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/packs/tools.py

@@ -0,0 +1,290 @@
+"""A pack as two agent tools: ``<PREFIX>_OPEN where`` and ``<PREFIX>_READ what [n]`` (IG_OPEN, IG_READ, TT_OPEN ...)."""
+
+import re
+import time
+from dataclasses import dataclass
+
+from .. import harness_api
+from ..agent_hooks import Prepared, SkillResult, safe_allows
+from . import context, core, heal, health, pins
+
+READ_SECONDS = 75.0
+OPEN_SECONDS = 30.0
+MAX_N = 40
+SCREENS_BACK = 40           # screens a call hands to the loop's checklist, newest
+FEEDBACK_ROWS = 40
+CELL_CHARS = 220
+_runs = {}                  # run id -> hints.Gate (both tools of a run share it)
+
+
+@dataclass(frozen=True)
+class PackResult(SkillResult):
+    screens: tuple = ()     # the screens the call read, for the loop's checklist (frontier._run_skill)
+
+
+def run_gate(run_id, data_dir=None):
+    """The run's hints.Gate: every source's one gate (two misses in a row, or a step stale at this app version, and the
+    general agent does it)."""
+    from .. import hints
+    if len(_runs) > 256:
+        _runs.clear()
+    return _runs.setdefault(run_id or "", hints.Gate(data_dir))
+
+
+def parse_open(pack, text):
+    """(route name, argument, act or None) from an OPEN's text, or ValueError with what it takes."""
+    words = core.plain(text)
+    head, _, rest = words.partition(" ")
+    head = head.casefold().rstrip(":")
+    alias = pack.open_aliases.get(head, head)
+    if alias in pack.controls:
+        spec = pack.controls[alias]
+        return spec.route, rest.strip() or None, alias
+    if alias in pack.routes:
+        arg = rest.strip() or None
+        if arg and alias in pack.route_with_arg:
+            alias = pack.route_with_arg[alias]
+        if pack.routes[alias].arg is None:
+            arg = None
+        return alias, arg, None
+    raise ValueError(f"{pack.prefix}_OPEN takes one of: {', '.join(pack.open_words)}")
+
+
+def parse_read(pack, text):
+    """(what, n, argument) from a READ's text: "dms 10", "thread Sam Lee", "reels 20", "profile @nasa"."""
+    words = core.plain(text)
+    head, _, rest = words.partition(" ")
+    what = pack.read_aliases.get(head.casefold(), head.casefold())
+    if what not in pack.readers:
+        raise ValueError(f"{pack.prefix}_READ takes one of: {', '.join(pack.read_words)}")
+    n, arg = pack.read_default.get(what, 10), rest.strip() or None
+    if arg:
+        found = re.match(r"^(\d{1,3})\b\s*(.*)$", arg)
+        if found:
+            n, arg = int(found.group(1)), found.group(2).strip() or None
+        else:
+            found = re.search(r"\s(\d{1,3})$", arg)
+            if found:
+                n, arg = int(found.group(1)), arg[:found.start()].strip() or None
+    return what, max(1, min(MAX_N, n)), arg
+
+
+def where(element):
+    """Where a control sits, as a person says it: "bottom right"."""
+    x, y = element.rect[0] + element.rect[2] / 2, element.rect[1] + element.rect[3] / 2
+    row = "top" if y < .33 else "middle" if y < .66 else "bottom"
+    column = "left" if x < .33 else "centre" if x < .66 else "right"
+    return f"{row} {column}"
+
+
+def row_line(index, row, columns, required=()):
+    """One row as a line."""
+    parts = []
+    for key, label, _kind in columns:
+        value = row.get(key)
+        if value is None or value == "" or value is False:
+            if key in required and value is not False:
+                parts.append(f"{label}: not on the screen")
+            continue
+        value = "yes" if value is True else core.plain(value)[:CELL_CHARS]
+        parts.append(f"{label}: {value}")
+    return f"{index}. " + "; ".join(parts)
+
+
+def block_for(pack, result):
+    """The result card for ``result``: a media list for Reels and posts, else a table. None for no rows."""
+    from .. import result_blocks as rb
+    if not result.rows:
+        return None
+    block_id = f"{pack.key}-{result.kind}"
+    if result.block == "media_list":
+        items = []
+        for index, row in enumerate(result.rows[:rb.MAX_ITEMS]):
+            noun = pack.noun(result.kind)
+            title = core.plain(row.get("caption") or "")[:120] or f"{noun[:1].upper()}{noun[1:]} by {row.get('author')}"
+            item = {"id": f"i{index + 1}", "title": title}
+            if row.get("author"):
+                item["creator"] = row["author"]
+            if row.get("audio") or row.get("sound"):
+                item["sounds"] = [row.get("audio") or row.get("sound")]
+            if str(row.get("link") or "").startswith("https://"):
+                item["link"] = row["link"]
+            items.append(item)
+        return rb.media_list(items, title=result.title, id=block_id)
+    columns = [{"key": key, "label": label, "type": kind} for key, label, kind in result.columns]
+    rows = [{"cells": {key: row.get(key) for key, _label, _kind in result.columns}}
+            for row in result.rows[:rb.MAX_ROWS]]
+    return rb.table(columns, rows, title=result.title, id=block_id)
+
+
+def _quiet(text):
+    """``text`` for the health log: quoted words (names, messages) left out."""
+    return re.sub(r"“[^”]*”", "“…”", str(text or ""))[:160]
+
+
+class PackTool:
+    """agent_hooks.Skill: one of a pack's two tools for one run."""
+
+    needs_target = False
+
+    def __init__(self, pack, kind, run_context=None, clock=time.monotonic, sleep=time.sleep):
+        self.pack, self.kind = pack, kind
+        self.op = f"{pack.prefix}_{kind}"
+        self.prompt = pack.prompts[kind]
+        self.run_context = run_context
+        self.clock, self.sleep = clock, sleep
+        self._version = ()
+        self._run_id = getattr(run_context, "run_id", None)
+
+    def available(self, ctx):
+        driver = getattr(ctx, "driver", None)
+        return callable(getattr(driver, "observe", None)) and callable(getattr(driver, "execute", None))
+
+    def prepare(self, ctx, act, snapshot):
+        try:
+            if self.kind == "OPEN":
+                route, arg, act_name = parse_open(self.pack, act.get("text"))
+                state = {"route": route, "arg": arg, "act": act_name}
+            else:
+                what, n, arg = parse_read(self.pack, act.get("text"))
+                state = {"what": what, "n": n, "arg": arg}
+        except ValueError as error:
+            return Prepared(None, {"error": str(error)})
+        guard = getattr(ctx, "guard", None)
+        if guard is not None and not safe_allows(guard, self.pack.bundle):
+            return Prepared(None, {"error": f"{self.pack.name} isn't allowed in this task."})
+        return Prepared(None, state)   # it moves around and reads: nothing to approve
+
+    def perform(self, ctx, prepared, act, snapshot):
+        state = prepared.state or {}
+        if state.get("error"):
+            return PackResult(feedback=state["error"])
+        run = getattr(ctx, "run", None) or self.run_context
+        self._run_id = getattr(run, "run_id", None)
+        gate = run_gate(self._run_id, getattr(run, "data_dir", None))
+        version = self._installed(run)
+        pinned = pins.aside(self.pack)
+        if pinned:
+            ctx.emit({"event": "tool_step", "op": self.op, "text": f"Left {self.pack.name} to the usual way"})
+            return PackResult(feedback=f"{self.op} steps aside for {self.pack.name}: {pinned} Do it the usual way.")
+        trusted, why = gate.trust("pack", self.pack.bundle, state.get("route") or state.get("what"), None, version)
+        if not trusted:
+            ctx.emit({"event": "tool_step", "op": self.op, "text": f"Left {self.pack.name} to the usual way"})
+            return PackResult(
+                feedback=f"{self.op} steps aside for {self.pack.name} here: it {why}. Do it the usual way.")
+        guard = getattr(ctx, "guard", None)
+        cancelled = getattr(run, "cancelled", None) or (lambda: False)
+        io = core.PackIO(ctx.driver, self.pack, cancelled=cancelled, clock=self.clock, sleep=self.sleep,
+                         allows_app=lambda bundle: guard is None or safe_allows(guard, bundle),
+                         deadline=OPEN_SECONDS if self.kind == "OPEN" else READ_SECONDS)
+        store = heal.attach([self.pack], getattr(run, "data_dir", None))
+        if version:
+            store.version_on_phone[self.pack.key] = version
+        started = self.clock()
+        ok, feedback, event, block, step = self._step(io, state)
+        missed = event.get("unsure_screen")
+        if missed and io.screens:
+            # The app changed under the pack (heal.py): a confirmed variant that passes the replay check on this very
+            # screen is trusted and the step runs once more; else this screen becomes a proposal, and the general
+            # agent takes the step now.
+            screen_now = io.screens[-1]
+            if store.check(self.pack, screen_now, missed, version):
+                ok, feedback, event, block, step = self._step(io, state)
+                event["healed"] = True
+            else:
+                # The miss is drift: hints.HintListener records it from this step's app_pack event, with the screen
+                # where the general agent takes over.
+                store.propose(self.pack, screen_now, missed, version, self._run_id)
+                event["fingerprint"] = heal.fingerprint(screen_now)
+                event["confidence"] = self.pack.recognize(screen_now).confidence
+        event.update(pack=self.pack.key, op=self.op, ok=ok, ms=round((self.clock() - started) * 1000),
+                     taps=io.taps, version=self._installed(run), verified=getattr(self.pack.verified, "version", None))
+        gate.note(ok, "pack", self.pack.bundle)
+        ctx.emit({"event": "app_pack", **event})
+        ctx.emit({"event": "tool_step", "op": self.op, "text": step})
+        if block is not None:
+            ctx.emit({"event": "result_blocks", "op": self.op, "blocks": [block]})
+        health.record(getattr(run, "data_dir", None), {key: (_quiet(value) if key == "why" else value)
+                                                        for key, value in event.items()})
+        return PackResult(feedback=feedback, changed=bool(io.taps) or len(io.screens) > 1,
+                          screens=tuple(io.screens[-SCREENS_BACK:]))
+
+    def _step(self, io, state):
+        return self._open(io, state) if self.kind == "OPEN" else self._read(io, state)
+
+    def _open(self, io, state):
+        pack, route, arg, act = self.pack, state["route"], state.get("arg"), state.get("act")
+        # For an act this only reaches its place and names the control: the model taps it, so that tap goes through the
+        # run's approvals, the journal and the duplicate guard.
+        landing = core.navigate(pack, io, route, arg)
+        event = {"step": act or route, "how": landing.how, "screen": landing.seen.screen,
+                 "confidence": landing.seen.confidence, "steps": landing.steps}
+        title = pack.routes[route].title
+        if not landing.ok:
+            event["why"] = landing.why
+            if not landing.seen.sure and landing.seen.app in ("", pack.bundle) and landing.snapshot is not None:
+                event["unsure_screen"] = pack.routes[route].lands[0]
+            return (False, f"{self.op} couldn't open {title}: {landing.why}. Go on the usual way from this screen.",
+                    event, None, f"Tried to open {title} in {pack.name}")
+        said = f"Now on {landing.seen.title} in {pack.name}" + (" (it was already there)" if landing.how == "already"
+                                                                  else f" ({landing.steps} steps, no model call)")
+        if act:
+            spec = pack.controls[act]
+            control = landing.control or core.control_for(pack, act, landing.snapshot)
+            if control is None:
+                return (True, f"{said}. Its {spec.title} control isn't on the screen: look for it.", event, None,
+                        f"Opened {title} in {pack.name}")
+            said += (f". The {spec.title} control is “{core.plain(control.label)[:60]}” ({control.role}, "
+                     f"{where(control)}). {self.op} doesn't tap it: tap it yourself only if the task asks for it, and "
+                     "Mobster asks the person first.")
+            return True, said, event, None, f"Went to {spec.title} in {pack.name}"
+        return True, said + ".", event, None, f"Opened {title} in {pack.name}"
+
+    def _read(self, io, state):
+        pack, what, n, arg = self.pack, state["what"], state["n"], state.get("arg")
+        event = {"step": what, "asked": n}
+        try:
+            result = pack.read(io, what, n, arg)
+        except core.Lost as lost:
+            event["why"] = str(lost)
+            screen_now = io.screens[-1] if io.screens else None
+            if screen_now is not None and str(getattr(screen_now, "bundle_id", "") or "") in ("", pack.bundle) \
+                    and not pack.recognize(screen_now).sure:
+                event["unsure_screen"] = pack.readers[what].screens[0]
+            return (False, f"{self.op} couldn't read {pack.read_titles.get(what, what)}: {lost}. Read it the usual "
+                           "way.", event, None, f"Tried to read {pack.read_titles.get(what, what)} in {pack.name}")
+        event.update(screen=result.screen, rows=len(result.rows), how="code")
+        if result.stopped:
+            event["stopped"] = result.stopped
+        if not result.rows:
+            return (True, f"{self.op} found no {pack.read_titles.get(what, what)} on {pack.screen_title(result.screen)}"
+                          + (f" ({result.stopped})" if result.stopped else "") + ".", event, None,
+                    f"Read {pack.read_titles.get(what, what)} in {pack.name}: none")
+        lines = "\n".join(row_line(i + 1, row, result.columns, pack.required.get(what, ()))
+                          for i, row in enumerate(result.rows[:FEEDBACK_ROWS]))
+        head = (f"{self.op} read {len(result.rows)} of {n} asked ({result.title}) by code"
+                + (f"; it stopped because {result.stopped}, so what it read is all there is for now" if result.stopped
+                   else "")
+                + ". These rows were on the screen: answer, and fill the checklist, with the values they hold (the "
+                  "names, words and numbers themselves). The person also sees them as a card in the result.")
+        block = block_for(pack, result)
+        context.keep(self._run_id, f"{pack.name} {result.title}", lines)
+        noun = pack.read_titles.get(what, what)
+        return (True, head + "\n" + harness_api.fence(f"{pack.name} {result.title}", lines), event, block,
+                f"Read {len(result.rows)} {noun if len(result.rows) != 1 else pack.noun(what)} in {pack.name}"
+                if what in pack.read_default
+                else f"Read the {noun} in {pack.name}")
+
+    def _installed(self, run):
+        if not self._version:
+            self._version = (core.app_version(getattr(run, "runtime", None), self.pack.bundle),)
+        return self._version[0]
+
+
+def factory(pack, kind):
+    """register_tool's factory for one of ``pack``'s tools: offered to a Smart run that starts in the pack's app or
+    whose task names it."""
+    def make(ctx):
+        return PackTool(pack, kind, ctx) if pack.offered_to(ctx) else None
+    make.__name__ = f"{pack.key}_{kind.lower()}_factory"
+    return make

mobile_agent/packs/x.py

@@ -0,0 +1,127 @@
+"""The X pack (formerly Twitter): the timeline, a post and its replies, profiles, search, notifications and messages."""
+
+import re
+
+from . import core, rows, social
+from .core import Control, PickRow, Reader, Route, ScreenSpec, TypeIn, Verified, sig
+
+BUNDLE = "com.atebits.Tweetie2"
+TAB = (.86, 1.0)
+TOP = (0.0, .2)
+TAB_LABEL = r"^(Home|Search( and Explore)?|Explore|Grok|Communities|Notifications|Messages|Direct Messages)\b"
+COLUMNS = (("author", "Author", "text"), ("handle", "Handle", "text"), ("text", "Post", "text"),
+           ("when", "When", "text"), ("replies", "Replies", "number"), ("reposts", "Reposts", "number"),
+           ("likes", "Likes", "number"), ("views", "Views", "number"), ("ad", "Ad", "text"))
+NOT_A_POST = re.compile(r"^(show more|show this thread|who to follow|trending|what's happening|subscribe to premium|"
+                        r"relevant people|discover more)\b", re.I)
+
+
+tab = rows.tab_tap(TAB)
+
+
+class X(core.Pack):
+    name, key, prefix, bundle = "X", "x", "X", BUNDLE
+    verified = Verified("12.21", "2026-10-14", "inferred from X's usual labels; no recorded tree yet")
+    tabs = sig(TAB_LABEL, "Button", region=TAB)
+    never = re.compile(r"^(repost|undo repost|quote|bookmark|remove bookmark|post|reply|send|unfollow|mute|block|"
+                       r"report|not interested)\b", re.I)
+    mentions = re.compile(r"\b(twitter|tweets?|x\.com|on x|my x|x timeline|x feed|x profile|x dms?)\b", re.I)
+    sites = ("x.com", "twitter.com", "www.x.com", "mobile.twitter.com")
+
+    screens = (
+        ScreenSpec("home", "your timeline", (
+            sig(r"^Home$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r"^(For you|Following)$", region=TOP), sig(r"\b\d[\d,.]*[KMB]? (likes?|replies|reposts?)\b", "Cell")),
+            ocr=(sig(r"^For you$", region=TOP, weight=2), sig(r"^Following$", region=TOP),
+                 sig(r"@\w{2,}\s*[·•,]\s*\d+[smhd]\b", weight=2), sig(r"^(Post|Tweet)$", region=TOP, never=True))),
+        ScreenSpec("post", "a post", (
+            sig(r"^(Post|Tweet)$", "StaticText", region=TOP, must=True, weight=2), sig(r"^Back$", "Button", region=TOP),
+            sig(r"^(Post your reply|Tweet your reply)", weight=2)),
+            ocr=(sig(r"^(Post|Tweet)$", region=TOP, must=True, weight=2), sig(r"^(Post your reply|Tweet your reply)"),
+                 sig(r"\bViews?\b"))),
+        ScreenSpec("profile", "a profile", (
+            sig(r"\bFollowers\b", weight=2), sig(r"\bFollowing\b"), sig(r"^(Posts|Replies|Highlights|Media|Likes)$"),
+            sig(r"^(Follow|Following|Edit profile)$", "Button"),
+            sig(r"^Home$", "Button", region=TAB, selected=True, never=True)),
+            ocr=(sig(r"\bFollowers$", weight=2), sig(r"\bFollowing$"), sig(r"^(Posts|Replies|Highlights|Media|Likes)$"),
+                 sig(r"^(Follow|Following|Edit profile)$"))),
+        ScreenSpec("search", "search", (
+            sig(r"^(Search and Explore|Search)$", "Button", region=TAB, selected=True, weight=2),
+            sig(r"^Search", "SearchField", must=True), sig(r"^(Top|Latest|People|Media|Lists)$", region=(0, .3))),
+            ocr=(sig(r"^Search", "SearchField", must=True),
+                 sig(r"^(Top|Latest|People|Media|Lists|Trending|For you)$", region=(0, .3), weight=2))),
+        ScreenSpec("notifications", "your notifications", (
+            sig(r"^Notifications$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r"^(All|Verified|Mentions)$", region=TOP)),
+            ocr=(sig(r"^Notifications$", region=TOP, must=True, weight=2),
+                 sig(r"^(All|Verified|Mentions)$", region=TOP))),
+        ScreenSpec("messages", "your messages", (
+            sig(r"^(Messages|Direct Messages)$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r"^(Message requests|New message|Search Direct Messages)", weight=1)),
+            ocr=(sig(r"^Messages$", region=TOP, must=True, weight=2),
+                 sig(r"^(Message requests|Search Direct Messages)"))),
+        ScreenSpec("thread", "a conversation", (
+            sig(r"^(Start a message|Start a new message|Message)\W*$", must=True, weight=2),
+            sig(r"^Back$", "Button", region=TOP), sig(TAB_LABEL, "Button", region=TAB, never=True)),
+            ocr=(sig(r"^(Start a message|Start a new message)", must=True, weight=2),
+                 sig(r"^Back$", "Button", region=TOP))),
+    )
+    routes = {
+        "home": Route("home", "your timeline", ("home",), (tab(r"^Home$", "the Home tab"),)),
+        "search": Route("search", "search", ("search",), (tab(r"^(Search( and Explore)?|Explore)$", "the Search tab"),
+                                                          TypeIn(r"^Search", "the search field", submit=True)),
+                        arg="query"),
+        "notifications": Route("notifications", "your notifications", ("notifications",),
+                               (tab(r"^Notifications$", "the Notifications tab"),)),
+        "messages": Route("messages", "your messages", ("messages",),
+                          (tab(r"^(Messages|Direct Messages)$", "the Messages tab"),)),
+        "thread": Route("thread", "a conversation", ("thread",),
+                        (tab(r"^(Messages|Direct Messages)$", "the Messages tab"),
+                         PickRow("conversation", roles=("Cell", "Button")),), arg="name"),
+        "user": Route("user", "a profile", ("profile",),
+                      (tab(r"^(Search( and Explore)?|Explore)$", "the Search tab"),
+                       TypeIn(r"^Search", "the search field"),
+                       PickRow("account", roles=("Cell", "Button", "StaticText"), template=(r"@{arg}\b",))),
+                      link="https://x.com/{arg}", arg="user"),
+        "post": Route("post", "the post", ("post",), (), link="{arg}", arg="url", from_tabs=False),
+        "here": Route("here", "a post", ("home", "post", "profile"), (tab(r"^Home$", "the Home tab"),)),
+    }
+    hidden_routes = ("user", "here")
+    controls = {
+        "like": Control(route="here", control=r"^Like\b", role="Button", title="Like"),
+        "follow": Control(route="user", control=r"^Follow\b", role="Button", region=(0, .6), title="Follow"),
+        "reply": Control(route="post", control=r"^(Post your reply|Tweet your reply|Reply)\b", title="reply field"),
+    }
+    open_aliases = {"timeline": "home", "feed": "home", "profile": "user", "dms": "messages", "dm": "messages",
+                    "inbox": "messages", "chat": "thread", "conversation": "thread", "link": "post"}
+    read_aliases = {"timeline": "home", "feed": "home", "posts": "home", "tweets": "home", "dms": "messages",
+                    "dm": "messages", "user": "profile", "stats": "profile", "replies": "post"}
+    read_default = {"home": 10, "messages": 15, "post": 10, "search": 10}
+    read_titles = {"home": "posts", "messages": "messages", "post": "replies", "search": "results",
+                   "profile": "profile"}
+    nouns = {"home": "post", "post": "reply", "search": "result", "messages": "message"}
+    prompts = {
+        "OPEN": ("- X_OPEN where: go to an X screen by code, no taps from you: home | search <words> | "
+                 "notifications | messages | thread <name> | user @handle | post <link>; or to an act's control: "
+                 "like | follow @handle | reply <link> (it names the control and never taps it; you tap it, the "
+                 "person approves). If it can't, go on the usual way."),
+        "READ": ("- X_READ what [n]: read X by code from the screen's tree: home n (your timeline) | post (a post "
+                 "and its replies) | search n | messages n | profile @handle (followers, following). Gives author, "
+                 "handle, words, time, replies, reposts, likes, views and Promoted flags. Opens the screen it needs."),
+    }
+    mcp_open_hint = "your timeline, search, notifications, messages, a profile, a post's link"
+    mcp_read_hint = "your timeline, a post and its replies, search results, messages or a profile's numbers"
+
+    @property
+    def readers(self):
+        posts = social.feed_reader("home", "posts", COLUMNS, skip=NOT_A_POST)
+        return {"home": Reader(posts, ("home",), "home"),
+                "post": Reader(social.feed_reader("post", "posts and replies", COLUMNS, skip=NOT_A_POST), ("post",),
+                               None),
+                "search": Reader(social.feed_reader("search", "results", COLUMNS, skip=NOT_A_POST), ("search",), None),
+                "messages": Reader(social.dm_reader(re.compile(r"^(message requests|new message|search)\b", re.I)),
+                             ("messages",), "messages"),
+                "profile": Reader(social.profile_reader(("followers", "following")), ("profile",), "user")}
+
+
+PACK = X()

mobile_agent/packs/youtube.py

@@ -0,0 +1,199 @@
+"""The YouTube pack: Home, Shorts, Subscriptions, a video and its comments, channels, search and your history."""
+
+import re
+
+from . import core, rows
+from .core import Control, Reader, ReadResult, Route, ScreenSpec, Tap, TypeIn, Verified, sig
+from .social import WORDED_COUNT
+
+BUNDLE = "com.google.ios.youtube"
+TAB = (.86, 1.0)
+TOP = (0.0, .2)
+TAB_LABEL = r"^(Home|Shorts|Create|Subscriptions|You|Library)\b"
+VIDEO = re.compile(r"^(?P<title>.+?) - (?P<channel>[^-]{2,60}?) - (?P<views>[\d.,]+\s?[KMB]? views?)"
+                   r"(?: - (?P<when>[^-]+? ago|Streamed [^-]+|Premiered [^-]+))?(?: - (?P<length>[^-]+))?"
+                   r"(?: - .*)?$", re.I)
+VIDEO_COLUMNS = (("title", "Title", "text"), ("channel", "Channel", "text"), ("views", "Views", "number"),
+                 ("when", "When", "text"), ("length", "Length", "text"), ("ad", "Ad", "text"))
+SHORT_COLUMNS = (("channel", "Channel", "text"), ("title", "Title", "text"), ("sound", "Sound", "text"),
+                 ("likes", "Likes", "number"), ("comments", "Comments", "number"), ("ad", "Ad", "text"))
+
+
+tab = rows.tab_tap(TAB)
+
+
+def parse_video(label):
+    found = VIDEO.match(core.plain(label))
+    if not found:
+        # A picture's row: "Title, Channel, 2.1M views, 3 days ago" (core.rows joins the lines).
+        parts = [p.strip() for p in core.plain(label).split(", ")]
+        views = next((i for i, p in enumerate(parts) if re.match(r"^[\d.,]+\s?[KMB]? views?$", p, re.I)), None)
+        if views is None or views < 2:
+            return None
+        number = re.match(r"([\d.,]+\s?[KMB]?)", parts[views]).group(1).replace(" ", "")
+        when = next((p for p in parts[views + 1:] if re.search(r"\bago$|^(Streamed|Premiered)\b", p)), None)
+        return {"title": ", ".join(parts[:views - 1]), "channel": parts[views - 1], "views": core.number(number),
+                "when": when, "length": None,
+                "ad": "Sponsored" if re.search(r"\b(sponsored|ad)\b", label, re.I) else None}
+    views = re.match(r"([\d.,]+\s?[KMB]?)", found.group("views"))
+    return {"title": found.group("title").strip(), "channel": found.group("channel").strip(),
+            "views": core.number(views.group(1).replace(" ", "")) if views else None,
+            "when": (found.group("when") or "").strip() or None,
+            "length": (found.group("length") or "").strip() or None,
+            "ad": "Sponsored" if re.search(r"\b(sponsored|ad)\b", label, re.I) else None}
+
+
+def video_rows(snapshot):
+    rows = []
+    for e in core.rows(snapshot):
+        if not .1 < core.centre_y(e) < .9 or e.role not in ("Cell", "Button", "Other", "Link"):
+            continue
+        row = parse_video(e.label)
+        if row and row not in rows:
+            rows.append(row)
+    return rows
+
+
+def read_videos(kind, noun):
+    def read(pack, io, snapshot, n, arg):
+        rows, stopped, _ = core.collect(io, snapshot, video_rows, lambda r: (r["channel"], r["title"]), n,
+                                        max_swipes=min(n, 20))
+        return ReadResult(kind, f"{len(rows)} {noun}", VIDEO_COLUMNS, rows, stopped)
+    return read
+
+
+def read_short(snapshot):
+    channel = next((m.group(1) for e in snapshot.elements if .55 < core.centre_y(e) < .92
+                    for m in [re.fullmatch(r"(@[\w.-]{2,30})", core.plain(e.label))] if m), None)
+    title = next((core.plain(e.label) for e in snapshot.elements if e.role in ("StaticText", "Button")
+                  and .6 < core.centre_y(e) < .92 and e.rect[0] < .75 and len(core.plain(e.label)) > 8
+                  and not re.match(r"^(@|subscribe|like|dislike|comments?|share|remix)", core.plain(e.label), re.I)),
+                 None)
+    like = core.find(snapshot, r"^Like this video along with ([\d,.]+\s?[KMB]?)")
+    likes = core.number(re.search(r"([\d,.]+\s?[KMB]?)", like.label).group(1).replace(" ", "")) if like else None
+    comments = core.find(snapshot, r"^(View )?([\d,.]+[KMB]?) comments?$|^Comments,? [\d,.]+")
+    sound = next((core.plain(e.label) for e in snapshot.elements if re.search(r"(original sound|♪|♫|\bmusic\b)",
+                                                                            core.plain(e.label), re.I)), None)
+    return {"channel": channel, "title": title, "sound": sound, "likes": likes,
+            "comments": core.number(re.search(r"(\d[\d,.]*[KMB]?)", comments.label).group(1)) if comments else None,
+            "ad": "Sponsored" if core.find(snapshot, r"^(Sponsored|Ad)$") else None}
+
+
+def read_shorts(pack, io, snapshot, n, arg):
+    rows, keys, shown, stuck, stopped = [], set(), 0, 0, ""
+    while shown < n:
+        row = read_short(snapshot)
+        key = (row["channel"], row["title"])
+        if row["channel"] or row["title"]:
+            if key in keys:
+                stuck += 1
+                if stuck >= 2:
+                    stopped = "the Shorts stopped moving"
+                    break
+            else:
+                stuck, shown = 0, shown + (0 if row["ad"] else 1)
+                keys.add(key)
+                rows.append(row)
+        if shown >= n:
+            break
+        try:
+            snapshot = io.swipe(snapshot, "up")
+        except core.Lost as lost:
+            stopped = str(lost)
+            break
+        if pack.recognize(snapshot).screen != "shorts":
+            stopped = "it left Shorts"
+            break
+    return ReadResult("shorts", f"{shown} Shorts", SHORT_COLUMNS, rows, stopped, block="media_list")
+
+
+class YouTube(core.Pack):
+    name, key, prefix, bundle = "YouTube", "youtube", "YT", BUNDLE
+    verified = Verified("21.28.3", "2026-10-14", "inferred from YouTube's usual labels; no recorded tree yet")
+    tabs = sig(TAB_LABEL, "Button", region=TAB)
+    never = re.compile(r"^(subscribe|unsubscribe|dislike|remix|save to playlist|save|download|add to queue|"
+                       r"not interested|don't recommend|report|join|thanks)\b", re.I)
+    mentions = re.compile(r"\b(youtube|yt|shorts|subscriptions|watch later)\b", re.I)
+    sites = ("www.youtube.com", "youtube.com", "m.youtube.com", "youtu.be")
+
+    screens = (
+        ScreenSpec("home", "YouTube's Home", (
+            sig(r"^Home$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r" - [\d.,]+\s?[KMB]? views", weight=2), sig(r"^(All|Music|Gaming|News|Live)$", region=TOP)),
+            ocr=(sig(r"^(Music|Gaming|News|Mixes|Podcasts|Recently uploaded|New to you)$", region=(0, .22), weight=2),
+                 sig(r"\bviews?\b"), sig(r"^Home$", region=TAB),
+                 sig(r"^(Today|Continue watching)$", region=(0, .22), never=True))),
+        ScreenSpec("shorts", "Shorts", (
+            sig(r"^Shorts$", "Button", region=TAB, selected=True, weight=2),
+            sig(r"^Like this video along with", weight=2), sig(r"^(Remix|Dislike this video)\b"),
+            sig(r" - [\d.,]+\s?[KMB]? views", never=True)),
+            ocr=(sig(rf"^{WORDED_COUNT}$", region=(.35, .88), column=(.84, 1.0), weight=2),
+                 sig(r"^Subscribe$", region=(.6, .92), weight=2), sig(r"^(Remix|Dislike|Share)$"),
+                 sig(r"\bviews?\b", never=True))),
+        ScreenSpec("subscriptions", "your subscriptions", (
+            sig(r"^Subscriptions$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r" - [\d.,]+\s?[KMB]? views")),
+            ocr=(sig(r"^(Today|Continue watching|Unwatched|Posts)$", region=(0, .22), weight=2), sig(r"\bviews?\b"),
+                 sig(r"^Subscriptions$", region=TAB))),
+        ScreenSpec("you", "You", (
+            sig(r"^(You|Library)$", "Button", region=TAB, selected=True, must=True, weight=2),
+            sig(r"^(History|Playlists|Watch later|Your videos|Liked videos)$", weight=2)),
+            ocr=(sig(r"^(History|Playlists|Watch later|Your videos|Liked videos)$", weight=2),
+                 sig(r"^(View all|Switch account)$"))),
+        ScreenSpec("video", "a video", (
+            sig(r"^(Like this video|Dislike this video|Share|Save|Download|Clip)\b", weight=2),
+            sig(r"^(Comments|Comments\.?\s+[\d,.]+)", weight=1), sig(r"\bsubscribers?\b"),
+            sig(r"^Like this video along with", "Button", region=(.3, .9), never=True)),
+            ocr=(sig(r"\bsubscribers?\b", weight=2), sig(r"^(Subscribe|Subscribed)$"), sig(r"^Comments\b"),
+                 sig(r"\bviews?\b"))),
+        ScreenSpec("search", "search results", (
+            sig(r"^Search YouTube$|^Search$", "SearchField", must=True, weight=2), sig(r" - [\d.,]+\s?[KMB]? views")),
+            ocr=(sig(r"^Search YouTube$|^Search$", "SearchField", must=True, weight=2), sig(r"\bviews?\b"))),
+    )
+    routes = {
+        "home": Route("home", "YouTube's Home", ("home",), (tab(r"^Home$", "the Home tab"),)),
+        "shorts": Route("shorts", "Shorts", ("shorts",), (tab(r"^Shorts$", "the Shorts tab"),)),
+        "subscriptions": Route("subscriptions", "your subscriptions", ("subscriptions",),
+                               (tab(r"^Subscriptions$", "the Subscriptions tab"),)),
+        "you": Route("you", "You (history, playlists, Watch later)", ("you",),
+                     (tab(r"^(You|Library)$", "the You tab"),)),
+        "search": Route("search", "search results", ("search",),
+                        (Tap(r"^Search$", "Search", role="Button", region=TOP),
+                         TypeIn(r"^Search", "the search field", submit=True)), arg="query"),
+        "channel": Route("channel", "a channel", ("video", "home"), (), link="https://www.youtube.com/{arg}",
+                         arg="user", from_tabs=False),
+        "video": Route("video", "the video", ("video", "shorts"), (), link="{arg}", arg="url", from_tabs=False),
+        "here": Route("here", "a video", ("video", "shorts"), ()),
+    }
+    hidden_routes = ("here",)
+    controls = {"like": Control(route="here", control=r"^Like this video", role="Button", title="Like"),
+                "subscribe": Control(route="here", control=r"^Subscribe\b", role="Button", title="Subscribe")}
+    open_aliases = {"library": "you", "history": "you", "watch": "video", "link": "video", "subs": "subscriptions"}
+    read_aliases = {"videos": "home", "feed": "home", "short": "shorts", "subs": "subscriptions",
+                    "results": "search", "history": "you"}
+    read_default = {"home": 10, "shorts": 10, "subscriptions": 10, "search": 10, "you": 10}
+    read_titles = {"home": "videos", "shorts": "Shorts", "subscriptions": "videos", "search": "results",
+                   "you": "videos", "video": "video"}
+    nouns = {"shorts": "Short", "home": "video", "subscriptions": "video", "search": "video", "you": "video"}
+    prompts = {
+        "OPEN": ("- YT_OPEN where: go to a YouTube screen by code, no taps from you: home | shorts | subscriptions | "
+                 "you (history, playlists) | search <words> | channel @name | video <link>; or to an act's control: "
+                 "like | subscribe (it names the control and never taps it; you tap it, the person approves). If it "
+                 "can't, go on the usual way."),
+        "READ": ("- YT_READ what [n]: read YouTube by code from the screen's tree: home n | subscriptions n | "
+                 "shorts n (swipes through n Shorts) | search n | you n. Gives each video's title, channel, views, "
+                 "when and length, or each Short's channel, title, likes and comments. Opens the screen it needs."),
+    }
+    mcp_open_hint = "Home, Shorts, Subscriptions, You, search, a channel, a video's link"
+    mcp_read_hint = "Home, Subscriptions, Shorts, search results or your history, as rows"
+
+    @property
+    def readers(self):
+        return {"home": Reader(read_videos("home", "videos"), ("home",), "home"),
+                "subscriptions": Reader(read_videos("subscriptions", "videos"), ("subscriptions",), "subscriptions"),
+                "shorts": Reader(read_shorts, ("shorts",), "shorts"),
+                "search": Reader(read_videos("search", "results"), ("search",), None),
+                "you": Reader(read_videos("you", "videos"), ("you",), "you")}
+
+
+PACK = YouTube()