mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/states.py

@@ -0,0 +1,217 @@
+"""The one table of states that stop Mobster, each with its words and its fix.
+
+A row is one state and one cause: what happened in a sentence, what to do in a sentence, and the fix. Every surface that
+names a state reads its words here: the Mac app, ``mobster mcp``'s ``status`` and ``mobster serve`` (through
+``engine_health``), and ``mobster doctor`` and ``mobster sim doctor`` (through ``doctor``). Nothing else holds a copy.
+``tests/test_states.py`` fails when a surface says a state in other words, or claims a row it can't produce.
+
+The fix is one of six kinds, so a state never shows a dead end:
+
+- ``Auto``: Mobster does it, because it touches only Mobster's own state and nothing another program is running.
+- ``Ask``: Mobster does it after it names the process or command and the person says yes. Never without a terminal.
+- ``Guided``: a guided flow (``mobster login``, ``mobster setup``) that asks its own questions.
+- ``Yours``: the person does it, on the iPhone or with the cable; ``picture`` names the picture of the iPhone's screen
+  that shows the taps. Mobster notices and goes on.
+- ``Run``: a command Mobster prints and never runs for the person (a download, opening the app).
+- ``Wait``: Mobster is already on it, or it clears by itself.
+
+``{phone}`` is the phone's name, or "your iPhone"; ``{Phone}`` is the same at the start of a sentence. A model's own
+sentence (``engine_health.classify_model``) replaces a row's ``message``, never its step.
+
+Nothing here acts on the phone. It only says what to do.
+"""
+
+from dataclasses import dataclass
+from typing import NoReturn, assert_never
+
+READY = "ready"
+WAITING_FOR_PHONE = "waiting_for_phone"
+HELPER_DOWN = "helper_down"
+NO_PHONE = "no_phone"
+MODEL_UNAVAILABLE = "model_unavailable"
+LIVE_OFF = "live_off"
+STOPPING = "stopping"
+# Named by whoever asks, when the process doesn't answer (engine_health.from_silence).
+SLOW = "slow"
+FROZEN = "frozen"
+DOWN = "down"
+RESTARTING = "restarting"
+
+STATES = (READY, WAITING_FOR_PHONE, HELPER_DOWN, NO_PHONE, MODEL_UNAVAILABLE, LIVE_OFF, STOPPING,
+          SLOW, FROZEN, DOWN, RESTARTING)
+
+
+# -- the fix ----------------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Auto:
+    action: str
+
+
+@dataclass(frozen=True)
+class Ask:
+    action: str
+
+
+@dataclass(frozen=True)
+class Guided:
+    command: str
+
+
+@dataclass(frozen=True)
+class Yours:
+    picture: str | None = None
+
+
+@dataclass(frozen=True)
+class Run:
+    command: str
+
+
+@dataclass(frozen=True)
+class Wait:
+    why: str
+
+
+Fix = Auto | Ask | Guided | Yours | Run | Wait
+
+
+def unreachable(fix) -> NoReturn:
+    assert_never(fix)
+
+
+def fix_public(fix):
+    """The fix as a client reads it: {"kind", ...}. ``action`` names what ``Auto`` and ``Ask`` run
+    (doctor_fix.ACTIONS)."""
+    match fix:
+        case Auto(action) | Ask(action):
+            return {"kind": type(fix).__name__.lower(), "action": action}
+        case Guided(command) | Run(command):
+            return {"kind": type(fix).__name__.lower(), "command": command}
+        case Yours(picture):
+            return {"kind": "yours", **({"picture": picture} if picture else {})}
+        case Wait(why):
+            return {"kind": "wait", "why": why}
+    unreachable(fix)
+
+
+def how(fix):
+    """One sentence on what Mobster does about the row, for the docs and the reports."""
+    match fix:
+        case Auto():
+            return "`mobster doctor --fix` does this for you."
+        case Ask():
+            return "`mobster doctor --fix` names what it would stop and asks you first."
+        case Guided(command):
+            return f"`{command}` walks you through it."
+        case Yours():
+            return "You do this one. Mobster notices and goes on."
+        case Run(command):
+            return f"Run `{command}`. Mobster doesn't run it for you."
+        case Wait(why):
+            return why
+    unreachable(fix)
+
+
+# -- the rows ---------------------------------------------------------------------------------------------------------
+
+# Where a row shows today. A surface listed here is tested to produce it (tests/test_states.py).
+ENGINE = ("app", "mcp")   # engine_health: the Mac app, `mobster mcp` status, `mobster serve`
+DOCTOR = ("cli",)         # `mobster doctor` and `mobster sim doctor`
+
+
+@dataclass(frozen=True)
+class Row:
+    state: str
+    cause: str
+    message: str
+    step: str
+    need: str | None
+    fix: Fix
+    surfaces: tuple[str, ...] = ENGINE
+
+
+# The next step of the three a task waits on is the sentence the task's caller (MCP, Mobster Remote) passes on.
+ROWS = (
+    Row(WAITING_FOR_PHONE, "locked", "{Phone} is locked.",
+        "Unlock {phone}: the task goes on as soon as it's unlocked.", "unlock", Yours(), ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "unplugged", "{Phone} is unplugged.",
+        "Plug {phone} back into the Mac: the task goes on when it's back.", "plug_in", Yours(), ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "wifi_lost", "{Phone} is out of reach over Wi-Fi.",
+        "Bring {phone} back near the Mac, or plug it in: the task goes on when it's back.", "bring_back", Yours(),
+        ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "helper_restarting", "Mobster's helper on {phone} is restarting.",
+        "Keep {phone} unlocked. This takes a few seconds.", None, Wait("Mobster starts the helper again by itself.")),
+    Row(WAITING_FOR_PHONE, "developer_mode_off", "Developer Mode is off on {phone}.",
+        "Turn it on in Settings › Privacy & Security › Developer Mode, then restart {phone}.", "developer_mode",
+        Yours("developer-mode"), ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "trust_needed", "{Phone} doesn't trust Mobster's helper yet.",
+        "On {phone}, open Settings › General › VPN & Device Management and trust your developer app.", "trust",
+        Yours("trust-developer-app"), ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "ui_automation_off", "UI Automation is off on {phone}.",
+        "On {phone}, turn on Settings › Developer › Enable UI Automation, and keep it unlocked while the helper "
+        "starts.", "ui_automation", Yours("ui-automation"), ENGINE + DOCTOR),
+    Row(WAITING_FOR_PHONE, "not_responding", "{Phone} isn't responding.",
+        "Unlock {phone} and close Control Center or Siri if they're open.", "clear_screen", Yours()),
+    Row(WAITING_FOR_PHONE, "computer_untrusted", "{Phone} doesn't trust this Mac yet.",
+        "On {phone}, tap Trust, then enter your passcode. Mobster never enters it.", "trust_computer",
+        Yours("trust-this-computer"), DOCTOR),
+    Row(HELPER_DOWN, "exposed",
+        "Mobster stopped its helper on {phone} because it answered on the phone's network address.",
+        "Build the helper again in Devices, then start it.", None, Guided("mobster setup")),
+    Row(HELPER_DOWN, "signature_expired", "Mobster's helper on {phone} has expired.",
+        "Refresh it in Devices.", None, Auto("rebuild_helper"), ENGINE + DOCTOR),
+    Row(HELPER_DOWN, "not_built", "Mobster's helper isn't on {phone} yet.",
+        "Set it up in Devices.", None, Guided("mobster setup"), ENGINE + DOCTOR),
+    Row(HELPER_DOWN, "failing", "Mobster's helper on {phone} keeps stopping.",
+        "Unlock {phone} and check Developer Mode, then start the helper in Devices.", None, Auto("start_helper")),
+    Row(HELPER_DOWN, "stopped", "Mobster's helper on {phone} isn't running.",
+        "Start it in Devices.", None, Auto("start_helper"), ENGINE + DOCTOR),
+    Row(HELPER_DOWN, "not_answering", "Mobster's helper on {phone} isn't answering.",
+        "Check that {phone} is on and reachable, then try again.", None, Yours()),
+    Row(HELPER_DOWN, "port_taken", "Another program is using the port Mobster's helper needs on this Mac.",
+        "Quit that program, or let Mobster name it and stop it with your OK.", None, Ask("free_port"), DOCTOR),
+    Row(NO_PHONE, "none_chosen", "No iPhone is set up.", "Add one in Devices.", None, Guided("mobster setup"),
+        ENGINE + DOCTOR),
+    Row(NO_PHONE, "none_attached", "No iPhone is attached.", "Start Mobster with a device, or add one in Devices.",
+        None, Guided("mobster setup")),
+    Row(NO_PHONE, "no_runtime", "No iOS Simulator runtime is installed.",
+        "Download one with xcodebuild -downloadPlatform iOS.", None, Run("xcodebuild -downloadPlatform iOS"), DOCTOR),
+    Row(MODEL_UNAVAILABLE, "no_key", "No AI account is connected.", "Connect your AI account in Settings › Models.",
+        None, Guided("mobster login"), ENGINE + DOCTOR),
+    Row(MODEL_UNAVAILABLE, "no_credit", "Your AI account is out of credit.",
+        "Add credit at your AI account, then try again.", None, Yours()),
+    Row(MODEL_UNAVAILABLE, "key_rejected", "Your AI account didn't accept your key.",
+        "Check your key in Settings › Models.", None, Guided("mobster login")),
+    Row(MODEL_UNAVAILABLE, "network_gone", "This Mac has no network.", "Join a network, then try again.", None,
+        Yours(), DOCTOR),
+    Row(LIVE_OFF, "disabled", "Live runs are off.", "Turn them on in Settings to act on the phone.", None, Yours()),
+    Row(STOPPING, "closing", "Mobster is closing.", "Open it again when you need it.", None,
+        Wait("Mobster is closing. Open it again when you need it.")),
+    Row(SLOW, "slow_answer", "Mobster is slow to answer.", "Wait a few seconds. Nothing is lost.", None,
+        Wait("Mobster answers again by itself.")),
+    Row(FROZEN, "no_answer", "Mobster stopped responding.",
+        "Restart Mobster. A task in flight is kept in History and is not resent.", None, Ask("restart_service"),
+        ENGINE + DOCTOR),
+    Row(DOWN, "not_running", "Mobster isn't running.", "Open the Mobster app.", None, Run("open -a Mobster"),
+        ENGINE + DOCTOR),
+    Row(RESTARTING, "restarted", "Mobster restarted.", "Wait a moment while it reconnects.", None,
+        Wait("Mobster reconnects by itself.")),
+)
+BY_CAUSE = {row.cause: row for row in ROWS}
+
+
+def row(cause):
+    """The row for a cause (KeyError for one the table doesn't have). Every cause belongs to one state."""
+    return BY_CAUSE[cause]
+
+
+def words(state, cause, phone=None, message=None):
+    """(message, next_step, need) for a state and cause, with the phone's name in. ``message`` replaces the table's
+    (a model's own sentence). KeyError for a pair the table doesn't have."""
+    found = BY_CAUSE[cause]
+    if found.state != state:
+        raise KeyError((state, cause))
+    name = (phone or "").strip() or "your iPhone"
+    fields = {"phone": name, "Phone": name[:1].upper() + name[1:]}
+    return (message or found.message.format(**fields)), found.step.format(**fields), found.need

mobile_agent/steering.py

@@ -0,0 +1,70 @@
+"""Messages the user sends a run while it works: ``Run.steer`` queues them and the frontier drains them each turn."""
+
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+
+SOURCES = ("app", "tui", "cli", "mcp", "voice", "remote")
+
+
+@dataclass(frozen=True)
+class SteerMessage:
+    id: str
+    text: str
+    at: float
+    source: str
+
+
+class SteeringFull(ValueError):
+    pass
+
+
+class SteeringQueue:
+    MAX_PENDING = 10
+    MAX_CHARS = 2000
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._pending = []
+        self._closed = False
+        self.paused = threading.Event()
+
+    def put(self, text, *, source="app"):
+        if not isinstance(text, str):
+            raise ValueError("A message is text")
+        text = text.strip()
+        if not text:
+            raise ValueError("Write a message first")
+        if len(text) > self.MAX_CHARS:
+            raise ValueError(f"A message can be at most {self.MAX_CHARS:,} characters")
+        if source not in SOURCES:
+            raise ValueError("Unknown message source")
+        with self._lock:
+            if self._closed:
+                raise ValueError("This task has finished")
+            if len(self._pending) >= self.MAX_PENDING:
+                raise SteeringFull("Mobster's agent has 10 messages it hasn't read yet. Wait for it to catch up.")
+            message = SteerMessage(uuid.uuid4().hex[:12], text, time.time(), source)
+            self._pending.append(message)
+        return message
+
+    def drain(self):
+        with self._lock:
+            out, self._pending = self._pending, []
+        return out
+
+    def pending(self):
+        with self._lock:
+            return len(self._pending)
+
+    @property
+    def closed(self):
+        with self._lock:
+            return self._closed
+
+    def close(self):
+        with self._lock:
+            self._closed = True
+            out, self._pending = self._pending, []
+        return out

mobile_agent/style.py

@@ -0,0 +1,178 @@
+"""Colour and layout for plain terminal output: help, doctor, tables, `run`'s steps."""
+
+import os
+import sys
+import time
+
+from . import brand
+
+
+def _roles(palette):
+    """The roles terminal text takes: violet text, the second and third ink, and the three status tones."""
+    return {"accent": palette["violet-text"], "secondary": palette["ink-2"], "tertiary": palette["ink-3"],
+            "green": palette["green"], "amber": palette["amber"], "coral": palette["coral"]}
+
+
+SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"  # braille frames for a step in progress; the terminal UI, `run` and `setup` share them
+
+DARK, LIGHT = _roles(brand.DARK), _roles(brand.LIGHT)
+# Older role names, kept so every caller reads the same.
+ALIASES = {"muted": "secondary", "faint": "tertiary", "red": "coral", "dim": "tertiary"}
+
+
+def xterm256(value):
+    """The xterm-256 colour nearest ``value`` (#rrggbb): from the 6x6x6 cube or the grey ramp."""
+    r, g, b = brand.rgb(value)
+    steps = (0, 95, 135, 175, 215, 255)
+
+    def nearest(channel):
+        return min(range(6), key=lambda i: abs(steps[i] - channel))
+    cube = (nearest(r), nearest(g), nearest(b))
+    cube_rgb = tuple(steps[i] for i in cube)
+    grey = max(0, min(23, round(((r + g + b) / 3 - 8) / 10)))
+    grey_rgb = (8 + grey * 10,) * 3
+
+    def distance(other):
+        return sum((a - b) ** 2 for a, b in zip((r, g, b), other))
+    if distance(grey_rgb) < distance(cube_rgb):
+        return 232 + grey
+    return 16 + 36 * cube[0] + 6 * cube[1] + cube[2]
+
+
+def truecolor():
+    return os.environ.get("COLORTERM", "").lower() in {"truecolor", "24bit"}
+
+
+_theme = None
+
+
+def theme():
+    """The theme, light or dark: $MOBSTER_THEME, else $COLORFGBG, else the terminal's answer."""
+    global _theme
+    chosen = os.environ.get("MOBSTER_THEME", "").strip().lower()
+    if chosen in {"light", "dark"}:
+        return chosen
+    if _theme is None:
+        _theme = _detect_theme()
+    return _theme
+
+
+def _detect_theme():
+    colorfgbg = os.environ.get("COLORFGBG", "")
+    if colorfgbg:
+        background = colorfgbg.split(";")[-1]
+        if background.isdigit():
+            return "light" if int(background) in {7, 9, 10, 11, 12, 13, 14, 15} else "dark"
+    rgb = _query_background()
+    if rgb is None:
+        return "dark"
+    luminance = sum(weight * channel for weight, channel in zip((.2126, .7152, .0722), rgb))
+    return "light" if luminance > .5 else "dark"
+
+
+def _query_background(timeout=.2):
+    """The terminal's background as (r, g, b) in 0..1, from OSC 11, or None."""
+    # tmux and screen answer for themselves, not for the terminal behind them.
+    if os.environ.get("TMUX") or os.environ.get("STY") or os.environ.get("TERM", "").startswith("screen") \
+            or os.environ.get("CI"):
+        return None
+    try:
+        import select
+        import termios
+        if not (sys.stdin.isatty() and sys.stdout.isatty()):
+            return None
+        fd = os.open("/dev/tty", os.O_RDWR | os.O_NOCTTY)
+    except (OSError, ImportError, ValueError, AttributeError):
+        return None
+    answer = b""
+    try:
+        old = termios.tcgetattr(fd)
+        raw = termios.tcgetattr(fd)
+        raw[3] &= ~(termios.ECHO | termios.ICANON)
+        raw[6][termios.VMIN], raw[6][termios.VTIME] = 0, 0
+        termios.tcsetattr(fd, termios.TCSANOW, raw)
+        try:
+            # Device attributes (ESC [c) follow: every terminal answers them, so one that ignores OSC 11 ends the
+            # wait at once and leaves no late reply in the shell's input.
+            os.write(fd, b"\033]11;?\033\\\033[c")
+            deadline = time.monotonic() + timeout
+            while time.monotonic() < deadline:
+                ready, _, _ = select.select([fd], [], [], max(0.0, deadline - time.monotonic()))
+                if not ready:
+                    break
+                chunk = os.read(fd, 256)
+                if not chunk:
+                    break
+                answer += chunk
+                if b"\033[?" in answer and answer.endswith(b"c"):
+                    break  # the device attributes came: any OSC 11 answer came before them
+        finally:
+            termios.tcsetattr(fd, termios.TCSAFLUSH, old)
+    except Exception:  # noqa: BLE001 -- a terminal that can't be asked is a dark one
+        return None
+    finally:
+        os.close(fd)
+    import re
+    found = re.search(rb"\]11;rgba?:([0-9a-fA-F]+)/([0-9a-fA-F]+)/([0-9a-fA-F]+)", answer)
+    if not found:
+        return None
+    return tuple(int(part, 16) / (16 ** len(part) - 1) for part in found.groups())
+
+
+class Palette:
+    """``paint(text, *roles)``: roles accent, secondary, tertiary, green, amber, coral, bold, underline."""
+
+    def __init__(self, enabled, light=None):
+        self.codes = {}
+        if not enabled:
+            return
+        values = LIGHT if (theme() == "light" if light is None else light) else DARK
+        full = truecolor()
+        for role, value in values.items():
+            r, g, b = brand.rgb(value)
+            self.codes[role] = f"38;2;{r};{g};{b}" if full else f"38;5;{xterm256(value)}"
+        self.codes.update(bold="1", text="39", underline="4")
+        for old, new in ALIASES.items():
+            self.codes[old] = self.codes[new]
+
+    @property
+    def enabled(self):
+        return bool(self.codes)
+
+    def __call__(self, text, *roles):
+        if not self.codes or not text:
+            return text
+        return "".join(f"\033[{self.codes[role]}m" for role in roles) + text + "\033[0m"
+
+
+def color_enabled(stream):
+    try:
+        tty = stream.isatty()
+    except (AttributeError, ValueError):
+        return False
+    return bool(tty) and "NO_COLOR" not in os.environ and os.environ.get("TERM") != "dumb" \
+        and os.environ.get("MOBSTER_PLAIN", "") not in {"1", "true", "yes"}
+
+
+def palette(stream=None):
+    """The palette for ``stream`` (stdout by default): colour on an interactive terminal that allows it."""
+    return Palette(color_enabled(sys.stdout if stream is None else stream))
+
+
+def columns(default=100):
+    try:
+        return int(os.environ.get("COLUMNS") or os.get_terminal_size().columns)
+    except (OSError, ValueError):
+        return default
+
+
+def wrap(text, width, indent=0, first=None):
+    """``text`` wrapped at ``width``, with a hanging ``indent``."""
+    import re
+    import textwrap
+    first = indent if first is None else first
+    # textwrap breaks only at ASCII whitespace, so a no-break space holds a command together.
+    held = re.sub(r"\bmobster(?: -{0,2}[a-z][\w-]*){1,2}|--[a-z][\w-]* [A-Z]+\b",
+                  lambda match: match[0].replace(" ", "\u00a0"), text)
+    return textwrap.fill(held, width=max(24, width), initial_indent=" " * first, subsequent_indent=" " * indent,
+                         break_long_words=False, break_on_hyphens=False).replace("\u00a0", " ")