mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/ownership.py

@@ -0,0 +1,219 @@
+"""Who holds a phone, and who waits for it."""
+
+import os
+import re
+import threading
+import time
+from dataclasses import dataclass
+
+KINDS = ("task", "agent", "mcp", "schedule", "remote", "manual")
+
+# How many requests wait for one phone, and how long a request waits before it ends without starting.
+QUEUE_LIMIT = 10
+QUEUE_TTL_SECONDS = 30 * 60
+QUEUE_TTL_ENV = "MOBSTER_QUEUE_MINUTES"
+# After "Take it back" the queue holds this long so the person can use the phone; "Resume queue" ends the hold.
+TAKE_BACK_GRACE_SECONDS = 120
+
+ORIGIN_KINDS = {"app": "task", "tui": "task", "cli": "task", "mcp": "mcp", "remote": "remote",
+                "workflow": "schedule", "schedule": "schedule", "api": "agent", "hook": "schedule",
+                "trigger": "schedule", "console": "remote"}
+ORIGIN_LABELS = {"app": "a task in Mobster", "tui": "a task in the terminal", "cli": "a task from the command line",
+                 "mcp": "an MCP client", "remote": "Mobster Remote", "workflow": "a workflow",
+                 "schedule": "a scheduled workflow", "api": "an app using the local API",
+                 "hook": "a workflow started by a webhook", "trigger": "a task started by a notification",
+                 "console": "your team's console"}
+
+QUEUE_FULL = ("{count} requests already wait for {phone}. Try again when one of them has started.")
+QUEUE_EXPIRED = ("This task waited {minutes} minutes for {phone} and never started. Nothing was done on the phone. "
+                 "Send it again when the phone is free.")
+QUEUE_CANCELLED = "You cancelled this task while it waited for {phone}. Nothing was done on the phone."
+QUEUE_RESTART = (
+    "Mobster restarted while this task waited for the phone. It never started and did nothing. Send it again.")
+ANOTHER_PROCESS = "another Mobster process"
+
+
+_request = threading.local()
+
+
+def set_client(name):
+    _request.client = name
+
+
+def current_client():
+    return getattr(_request, "client", None)
+
+
+class QueueFull(Exception):
+    """The phone's queue is at its limit."""
+
+
+def ttl_seconds(environ=None):
+    """How long a request waits, from MOBSTER_QUEUE_MINUTES (1 to 1440), else 30 minutes."""
+    raw = (os.environ if environ is None else environ).get(QUEUE_TTL_ENV)
+    try:
+        minutes = float(raw)
+    except (TypeError, ValueError):
+        return QUEUE_TTL_SECONDS
+    return minutes * 60 if 1 <= minutes <= 1440 else QUEUE_TTL_SECONDS
+
+
+KNOWN_CLIENTS = {"claude-code": "Claude Code", "claude code": "Claude Code", "claude-ai": "Claude",
+                 "claude": "Claude", "codex": "Codex", "codex-mcp-client": "Codex", "cursor": "Cursor",
+                 "cursor-vscode": "Cursor", "windsurf": "Windsurf", "gemini-cli": "Gemini CLI",
+                 "vscode": "VS Code", "visual studio code": "VS Code", "zed": "Zed", "cline": "Cline"}
+
+
+def clean_client(name):
+    # a label for people to read: it grants nothing
+    if not isinstance(name, str):
+        return None
+    name = re.sub(r"[^A-Za-z0-9 .@+/()_-]", "", name, flags=re.ASCII).strip()[:40].strip()
+    return KNOWN_CLIENTS.get((name or "").casefold(), name) or None
+
+
+def sentence_case(text):
+    """``text`` with its first letter capitalized (a label starts a sentence)."""
+    return text[:1].upper() + text[1:] if text else text
+
+
+def holder_for(run, *, client=None, stopping=None, workflow=None):
+    origin = getattr(run, "origin", None) or "api"
+    kind = ORIGIN_KINDS.get(origin, "agent")
+    label = ORIGIN_LABELS.get(origin, "an app using the local API")
+    if origin == "mcp":
+        name = clean_client(client)
+        label = name or label
+    elif origin in ("workflow", "schedule"):
+        name = clean_client(workflow)
+        if name:
+            label = f"the {'scheduled ' if origin == 'schedule' else ''}workflow {name}"
+    started = getattr(run, "started_at", None) or getattr(run, "created_at", None) or time.time()
+    if stopping is None:
+        stop = getattr(run, "stop", None)
+        stopping = bool(stop is not None and stop.is_set()) or bool(getattr(run, "taking_back", False))
+    return {"kind": kind, "label": label, "runId": getattr(run, "id", None), "since": int(started * 1000),
+            "stopping": bool(stopping)}
+
+
+def manual_holder(label, since):
+    return {"kind": "manual", "label": label, "runId": None, "since": int(since * 1000), "stopping": False}
+
+
+def elsewhere_holder(since=None):
+    return {"kind": "agent", "label": ANOTHER_PROCESS, "runId": None,
+            "since": int((since or time.time()) * 1000), "stopping": False}
+
+
+def waiting_message(holder, phone, position):
+    """What a queued request is told: who it waits for, on which phone, and its number."""
+    who = holder["label"] if holder else "the phone's current task"
+    return f"Waiting for {who} on {phone}, you are number {position}."
+
+
+def holding_sentence(holder):
+    """"Claude Code is using this phone", for a holder record ("You are using this phone" for your own hands)."""
+    label = holder["label"]
+    return f"{sentence_case(label)} {'are' if label.casefold() == 'you' else 'is'} using this phone"
+
+
+@dataclass
+class Entry:
+    id: str            # the queued run's id
+    kind: str
+    label: str
+    since: float       # epoch seconds
+    expires_at: float  # epoch seconds
+
+
+# fail closed: an entry is a promise to try, never to act; the runtime checks phone, lease and limits again at the front
+class PhoneQueue:
+    """The requests that wait for one phone, first come first served. Not thread-safe: the runtime's lock guards it."""
+
+    def __init__(self, clock=time.time, limit=QUEUE_LIMIT, ttl=QUEUE_TTL_SECONDS):
+        self.clock, self.limit, self.ttl = clock, limit, ttl
+        self.entries = []
+        self.held_until = None   # Take it back: no request starts before this (epoch seconds)
+
+    def __len__(self):
+        return len(self.entries)
+
+    def add(self, run_id, kind, label):
+        """Put a request at the back; QueueFull at the limit. Returns its Entry."""
+        if len(self.entries) >= self.limit:
+            raise QueueFull(self.limit)
+        now = self.clock()
+        entry = Entry(run_id, kind, label, now, now + self.ttl)
+        self.entries.append(entry)
+        return entry
+
+    def remove(self, run_id):
+        """Take a request out (cancelled, expired, started). True when it was waiting."""
+        before = len(self.entries)
+        self.entries = [entry for entry in self.entries if entry.id != run_id]
+        return len(self.entries) != before
+
+    def position(self, run_id):
+        for index, entry in enumerate(self.entries, 1):
+            if entry.id == run_id:
+                return index
+        return None
+
+    def head(self):
+        return self.entries[0] if self.entries else None
+
+    def expired(self):
+        """Remove and return the requests that waited out their time."""
+        now = self.clock()
+        gone = [entry for entry in self.entries if entry.expires_at <= now]
+        if gone:
+            self.entries = [entry for entry in self.entries if entry.expires_at > now]
+        return gone
+
+    def hold(self, seconds=TAKE_BACK_GRACE_SECONDS):
+        self.held_until = self.clock() + seconds
+
+    def release(self):
+        self.held_until = None
+
+    def held(self):
+        """Whether the queue is paused after Take it back."""
+        if self.held_until is None:
+            return False
+        if self.clock() >= self.held_until:
+            self.held_until = None
+            return False
+        return True
+
+    def view(self):
+        """[{id, kind, label, position, since}] with ``since`` in epoch milliseconds."""
+        return [{"id": entry.id, "kind": entry.kind, "label": entry.label, "position": index,
+                 "since": int(entry.since * 1000)} for index, entry in enumerate(self.entries, 1)]
+
+
+class Queues:
+    """One ``PhoneQueue`` per phone key, made on first use. The runtime's lock guards it."""
+
+    def __init__(self, clock=time.time, limit=QUEUE_LIMIT, ttl=None):
+        self.clock, self.limit = clock, limit
+        self.ttl = QUEUE_TTL_SECONDS if ttl is None else ttl
+        self.by_key = {}
+
+    def of(self, key):
+        queue = self.by_key.get(key)
+        if queue is None:
+            queue = self.by_key[key] = PhoneQueue(self.clock, self.limit, self.ttl)
+        return queue
+
+    def find(self, key):
+        return self.by_key.get(key)
+
+    def locate(self, run_id):
+        """(key, queue) of the queue a request waits in, or (None, None)."""
+        for key, queue in self.by_key.items():
+            if queue.position(run_id) is not None:
+                return key, queue
+        return None, None
+
+    def total(self):
+        return sum(len(queue) for queue in self.by_key.values())

mobile_agent/packs/__init__.py

@@ -0,0 +1 @@
+"""App packs: first-party knowledge of the apps people hand Mobster most (Instagram, TikTok), for Mobster for Mac."""

mobile_agent/packs/calendar.py

@@ -0,0 +1,243 @@
+"""The Calendar pack: what's coming up and one event's details, by code (read-only)."""
+
+import re
+
+from . import core, rows
+from .core import PickRow, ReadResult, Route, ScreenSpec, Tap, Verified, sig
+
+BUNDLE = "com.apple.mobilecal"
+TOP = (0.0, .14)
+BOTTOM = (.86, 1.0)
+DAY = re.compile(r"^((mon|tues|wednes|thurs|fri|satur|sun)day)\s*[-–]\s*([a-z]{3,9}\.? \d{1,2})(, \d{4})?$", re.I)
+TIME = r"\d{1,2}(:\d{2})?\s?[AP]M"
+SPAN = re.compile(rf"^(?:from )?({TIME})\s*(?:to|–|-)\s*({TIME})$", re.I)
+EVENT_DATE = re.compile(r"^(mon|tues|wednes|thurs|fri|satur|sun)day, [a-z]{3,9}\.? \d{1,2}, \d{4}", re.I)
+
+
+class Calendar(core.Pack):
+    name, key, prefix, bundle = "Calendar", "calendar", "CA", BUNDLE
+    verified = Verified("iOS 26.0.1", "2026-10-12", "iPhone 15 Pro over USB (test device)")
+    tabs = sig(r"^Today$", region=BOTTOM)
+    never = re.compile(r"^(sign in|log in|add|edit|delete.*|accept|decline|maybe|tentative|new event|new calendar|"
+                       r"add calendar|share|invite.*|subscribe.*|done)\b", re.I)
+    mentions = re.compile(r"\b(calendar|schedule|agenda|events?|appointments?|meetings?|"
+                          r"what('s| is) (on|coming up)|when (and where )?is my|busy)\b", re.I)
+
+    screens = (
+        ScreenSpec("year", "the year", (
+            sig(r"^YearViewContainerView$", weight=2),
+            sig(r"^Current month, "),
+            sig(r"^20\d\d$", region=(.1, .22), weight=2),
+            sig(r"^Today$", region=BOTTOM),
+        ), "recorded",
+            ocr=(
+                sig(r"^20\d\d$", region=(.1, .22), weight=2),
+                sig(r"^(Jan|Feb|Mar)$"),
+                sig(r"^Today$", region=BOTTOM),
+            )),
+        ScreenSpec("month", "the month", (
+            sig(r"^MonthViewContainerView$", weight=2),
+            sig(r"^(January|February|March|April|May|June|July|August|September|October|November|December)$",
+                region=(.1, .22), weight=2),
+            sig(r"^(<\s*)?20\d\d$", region=TOP),
+            sig(r"^List$", region=TOP),
+            sig(r"^Today$", region=BOTTOM),
+            sig(r"^(Compact|Stacked)$", never=True),
+        ), "recorded",
+            ocr=(
+                sig(r"^(January|February|March|April|May|June|July|August|September|October|November|December)$",
+                    region=(.1, .22), weight=2),
+                sig(r"^(<\s*)?20\d\d$", region=TOP),
+                sig(r"^Today$", region=BOTTOM),
+                sig(r"^(Compact|Stacked)$", never=True),
+            )),
+        ScreenSpec("list", "your upcoming events", (
+            sig(r"^ListViewContainerView$", weight=3),
+            sig(DAY.pattern, field="text", weight=2),
+            sig(r"^all-day$", field="text"),
+            sig(r", from .+ to .+", "Cell"),
+            sig(r"^Today$", region=BOTTOM),
+            sig(r"^(Compact|Stacked)$", never=True),
+            sig(r"^EKEventView$", never=True),
+        ), "recorded",
+            ocr=(
+                sig(DAY.pattern, field="text", weight=2),
+                sig(r"^all-day$", field="text"),
+                sig(rf"^{TIME}$", field="text"),
+                sig(r"^Today$", region=BOTTOM),
+                sig(r"^(Compact|Stacked)$", never=True),
+                sig(r"^EKEventView$", never=True),
+            )),
+        ScreenSpec("event", "an event", (
+            sig(r"^EKEventView$", weight=2),
+            sig(EVENT_DATE.pattern, field="text", weight=2),
+            sig(r"^Delete Event$", weight=2),
+            sig(r"^Edit$", region=TOP),
+            sig(r"^(Calendar|Alert|Second Alert|Travel Time|Invitees)$"),
+        ), "recorded",
+            ocr=(
+                sig(EVENT_DATE.pattern, field="text", weight=2),
+                sig(r"^Delete Event$", weight=2),
+                sig(r"^Edit$", region=TOP),
+                sig(r"^(Calendar|Alert|Second Alert|Travel Time|Invitees)$"),
+            )),
+        ScreenSpec("views", "the view menu", (
+            sig(r"^Compact$", must=True, weight=2),
+            sig(r"^Stacked$", weight=2),
+            sig(r"^Details$"),
+            sig(r"^List$"),
+        ), "recorded",
+            ocr=(
+                sig(r"^Compact$", must=True, weight=2),
+                sig(r"^Stacked$", weight=2),
+                sig(r"^Details$"),
+                sig(r"^List$"),
+            )),
+    )
+
+    routes = {
+        "today": Route("today", "today", ("month", "list"), (Tap(r"^Today$", "Today", region=BOTTOM),)),
+        "list": Route("list", "your upcoming events", ("list",), (
+            Tap(r"^Today$", "Today", region=BOTTOM, wait=.3),
+            Tap(r"^List$", "the List button", region=TOP, opens=True),
+            Tap(r"^List$", "List in the view menu", region=(.15, .4), opens=True, optional=True, wait=.3))),
+        "event": Route("event", "an event", ("event",), (
+            Tap(r"^Today$", "Today", region=BOTTOM, wait=.3),
+            Tap(r"^List$", "the List button", region=TOP, opens=True),
+            Tap(r"^List$", "List in the view menu", region=(.15, .4), opens=True, optional=True, wait=.3),
+            PickRow("event", roles=("Cell", "StaticText"), region=(.12, .9), template=(r"^{arg}(,|$)", r"^{arg}\b"),
+                    scrolls=6)), arg="name"),
+    }
+    open_aliases = {"upcoming": "list", "events": "list", "agenda": "list", "schedule": "list", "day": "today"}
+    read_aliases = {"upcoming": "events", "agenda": "events", "schedule": "events", "list": "events",
+                    "next": "events", "details": "event"}
+    read_default = {"events": 10}
+    read_titles = {"events": "upcoming events", "event": "event"}
+    nouns = {"events": "event", "event": "event"}
+    prompts = {
+        "OPEN": ("- CA_OPEN where: go to a Calendar screen by code, no taps from you: today | list (your upcoming "
+                 "events) | event <title>. It only reads: it never adds, edits or deletes. If it can't, go on the "
+                 "usual way."),
+        "READ": ("- CA_READ what [n]: read Calendar by code: events n (your next n events from today: title, date, "
+                 "time or all-day, place) | event <title> (opens it: its date, time, place, calendar, alert). Opens "
+                 "the screen it needs."),
+    }
+    mcp_open_hint = "today, the list of upcoming events, or one event by its title"
+    mcp_read_hint = "your next events with their dates, times and places, or one event's details"
+    read_columns = {
+        "events": (("title", "Event", "text"), ("date", "Date", "text"), ("time", "Time", "text"),
+                   ("place", "Where", "text"), ("calendar", "Calendar", "text")),
+        "event": (("title", "Event", "text"), ("date", "Date", "text"), ("time", "Time", "text"),
+                  ("place", "Where", "text"), ("calendar", "Calendar", "text"), ("alert", "Alert", "text")),
+    }
+
+    @property
+    def readers(self):
+        return {"events": core.Reader(read_events, ("list",), "list"),
+                "event": core.Reader(read_event, ("event",), "event")}
+
+    back_control = rows.back_unless_act
+
+    def confirm(self, route, arg, snapshot):
+        if route != "event" or not arg:
+            return None
+        title = event_title(snapshot)
+        if title and core.plain(arg).casefold() in title.casefold():
+            return None
+        return f"the event on screen is “{(title or '')[:40]}”, not “{core.plain(arg)[:40]}”"
+
+
+def _time(text):
+    span = SPAN.match(core.plain(text).replace(" ", " "))
+    return f"{span.group(1)} – {span.group(3)}" if span else None
+
+
+def parse_cell(label):
+    """A timed event's cell ("MobsterBench Review, from 2:00PM to 3:00PM, Room 42, Sam") as a row."""
+    tokens = [t.strip() for t in core.plain(label).replace(" ", " ").split(", ")]
+    span = next((i for i, t in enumerate(tokens) if SPAN.match(t)), None)
+    if span is None or span == 0:
+        return None
+    rest = tokens[span + 1:]
+    return {"title": ", ".join(tokens[:span]), "date": None, "time": _time(tokens[span]),
+            "place": ", ".join(rest[:-1]) or None if len(rest) > 1 else None,
+            "calendar": rest[-1] if rest else None}
+
+
+def parse_list(snapshot):
+    """The events the list shows, top to bottom, each dated by the day header above it when one shows."""
+    out, day = [], None
+    texts = rows.lines(snapshot, (.12, .9))
+    if core.image_only(snapshot):
+        for index, line in enumerate(texts):
+            text = core.plain(line.label).replace(" ", " ")
+            header = DAY.match(text)
+            if header:
+                day = f"{header.group(1)}, {header.group(3)}"
+                continue
+            if line.rect[0] > .6 or re.match(r"^[*•]\s", text):
+                continue      # a time, "all-day", or a place under the title
+            right = [e for e in texts if e.rect[0] > .6 and abs(core.centre_y(e) - core.centre_y(line)) < .015]
+            if not right:
+                continue
+            under = [e for e in texts if e.rect[0] > .6 and .012 < core.centre_y(e) - core.centre_y(line) < .045]
+            place = next((re.sub(r"^[*•]\s*", "", core.plain(e.label)) for e in texts
+                          if e.rect[0] < .6 and .012 < core.centre_y(e) - core.centre_y(line) < .045), None)
+            first = core.plain(right[0].label).replace(" ", " ")
+            when = "all-day" if first.casefold() == "all-day" else (
+                f"{first} – {core.plain(under[0].label)}" if under else first)
+            out.append({"title": text, "date": day, "time": when,
+                        "place": place if when != "all-day" else None, "calendar": None})
+        return out
+    for element in texts:
+        text = core.plain(element.label)
+        header = DAY.match(text.replace(" ", " "))
+        if header:
+            day = f"{header.group(1)}, {header.group(3)}"
+            continue
+        if element.role == "Cell":
+            row = parse_cell(text)
+            if row:
+                out.append({**row, "date": day})
+            continue
+        if element.role == "StaticText" and text.casefold() != "all-day" and element.rect[0] < .6:
+            beside = [e for e in texts if e.rect[0] > .6 and abs(core.centre_y(e) - core.centre_y(element)) < .015
+                      and core.plain(e.label).casefold() == "all-day"]
+            if beside:
+                out.append({"title": text, "date": day, "time": "all-day", "place": None, "calendar": None})
+    return out
+
+
+def read_events(pack, io, snapshot, n, arg):
+    found, stopped, _ = core.collect(io, snapshot, parse_list, lambda r: (r["title"], r["date"], r["time"]), n,
+                                     max_swipes=min(n // 4 + 2, 8))
+    return ReadResult("events", f"Your next {len(found)} events", pack.read_columns["events"], found, stopped)
+
+
+def event_title(snapshot):
+    cell = core.find(snapshot, r"\w", role="Cell", region=(.1, .3))
+    if cell is not None:
+        return core.plain(cell.label)
+    first = [e for e in rows.lines(snapshot, (.1, .3)) if not EVENT_DATE.match(core.plain(e.label))]
+    return core.plain(first[0].label) if first else None
+
+
+def read_event(pack, io, snapshot, n, arg):
+    texts = [core.plain(e.label).replace(" ", " ") for e in rows.lines(snapshot, (.1, .9))]
+    date = next((t for t in texts if EVENT_DATE.match(t)), None)
+    time = next((t for t in texts if re.match(rf"^({TIME})\s*[–-]\s*({TIME})$", t, re.I) or t.casefold() == "all-day"),
+                None)
+    place = next((e.value for e in snapshot.elements if e.role == "TextView" and e.value
+                  and core.centre_y(e) < .3), None)
+    if place is None and core.image_only(snapshot):
+        title = event_title(snapshot)
+        after = texts[texts.index(title) + 1:] if title in texts else []
+        place = next((t for t in after if t != date and t != time and not EVENT_DATE.match(t)), None)
+    found = rows.pairs(snapshot, region=(.4, .9))
+    row = {"title": event_title(snapshot), "date": date, "time": time, "place": place,
+           "calendar": found.get("Calendar"), "alert": found.get("Alert")}
+    return ReadResult("event", row["title"] or "This event", pack.read_columns["event"], [row],
+                      "" if date else "the event's date isn't on the screen")
+
+
+PACK = Calendar()

mobile_agent/packs/context.py

@@ -0,0 +1,68 @@
+"""What a pack read in this run, kept in front of the model on every later turn (a harness_api context provider)."""
+
+import threading
+from collections import OrderedDict, deque
+
+from .. import harness_api
+
+KEY = "packs"
+MAX_CHARS = 4000
+READS = 3                   # the newest reads kept per run
+RUNS = 64
+_reads = OrderedDict()      # run id -> deque of (title, lines)
+_lock = threading.Lock()
+
+
+def keep(run_id, title, lines):
+    """A tool's feedback reaches the model for one turn only, so the run's reads are kept here for every later turn."""
+    if not run_id or not lines:
+        return
+    with _lock:
+        kept = _reads.pop(run_id, None) or deque(maxlen=READS)
+        kept = deque((entry for entry in kept if entry[0] != title), maxlen=READS)
+        kept.append((title, lines))
+        _reads[run_id] = kept
+        while len(_reads) > RUNS:
+            _reads.popitem(last=False)
+
+
+def reads(run_id):
+    with _lock:
+        return list(_reads.get(run_id) or ())
+
+
+def forget(run_id):
+    with _lock:
+        _reads.pop(run_id, None)
+
+
+class Provider:
+    key = KEY
+    max_chars = MAX_CHARS
+
+    def blocks(self, ctx):
+        forget(ctx.run_id)   # a run id is used once; nothing of an earlier run with the same id is shown
+        return ()
+
+    def turn_blocks(self, ctx, turn):
+        kept = reads(ctx.run_id)
+        if not kept:
+            return ()
+        text, left = [], MAX_CHARS
+        for title, lines in reversed(kept):          # newest first, so the newest survives the cap
+            part = f"{title}:\n{lines}"
+            if len(part) > left:
+                part = part[:max(0, left - 1)] + "…"
+            text.insert(0, part)
+            left -= len(part)
+            if left <= 0:
+                break
+        return (harness_api.ContextBlock(KEY, "What Mobster read in the app earlier in this task", "\n\n".join(text),
+                                         stable=False, untrusted=True),)
+
+
+def factory(packs):
+    """register_context_provider's factory: a Provider for a Smart run any pack's tools are offered to."""
+    def make(ctx):
+        return Provider() if any(pack.offered_to(ctx) for pack in packs) else None
+    return make