mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/tui/demo_phone.py

@@ -0,0 +1,369 @@
+"""A scripted phone for `mobster --demo`: the real agent loop, no iPhone and no model calls."""
+
+import base64
+import io
+import re
+import threading
+import time
+from functools import lru_cache
+
+from ..drivers import Driver
+from ..state import Element, Snapshot
+
+SOURCE = "synthetic_fixture"
+MODEL = "scripted-demo"
+DEFAULT_MESSAGE = "Running 10 minutes late, save me a seat"
+
+MESSAGES, SETTINGS, WALLET = "com.apple.MobileSMS", "com.apple.Preferences", "com.apple.Passbook"
+
+
+def _element(index, label, role, rect, **extra):
+    return Element(str(index), label, role, rect, **extra)
+
+
+def _message(goal):
+    """The text to send: a quoted part of the request, else a stock line."""
+    match = re.search(r"[\"“']([^\"”']{2,120})[\"”']", goal or "")
+    return match.group(1) if match else DEFAULT_MESSAGE
+
+
+def _query(goal):
+    match = re.search(r"(?:search(?: for)?|find|look up)\s+(.+?)(?:\s+(?:in|on)\s+\w+)?$", goal or "", re.I)
+    return (match.group(1).strip(" .\"“”'") if match else "coffee")[:60] or "coffee"
+
+
+class Screens:
+    """The screens of one scenario, keyed by stage name: (elements, text)."""
+
+    ROWS = ["Apple Account", "Airplane Mode", "Wi-Fi", "Bluetooth", "Cellular", "Battery", "General",
+            "Accessibility"]
+    MORE_ROWS = ["General", "Accessibility", "Camera", "Control Center", "Display & Brightness",
+                 "Home Screen & App Library", "Search", "Siri", "StandBy", "Wallpaper"]
+    THREADS = [("Alex Rivera", "See you at 7? I'll grab a table"), ("Mom", "Call me when you land"),
+               ("Jordan Lee", "Sent the deck, take a look"), ("Priya Shah", "Haha yes"),
+               ("Dentist", "Reminder: cleaning Tue 9:30")]
+
+    def __init__(self, bundle, goal):
+        self.bundle, self.goal = bundle, goal
+        self.message = _message(goal)
+        self.query = _query(goal)
+
+    def build(self, stage, typed=""):
+        if self.bundle == MESSAGES:
+            return self.messages(stage, typed)
+        if self.bundle == SETTINGS:
+            return self.settings(stage)
+        if self.bundle == WALLET:
+            elements = [_element(0, "Add", "Button", (.84, .065, .12, .035)),
+                        _element(1, "Apple Card", "Button", (.05, .14, .9, .26)),
+                        _element(2, "Transit", "Button", (.05, .43, .9, .26))]
+            return elements, "Wallet\nApple Card\nTransit\nAdd"
+        return self.search(stage, typed)
+
+    def messages(self, stage, typed):
+        if stage == "inbox":
+            elements = [_element(90, "Messages", "NavigationBar", (0, .05, 1, .08)),
+                        _element(0, "Edit", "Button", (.04, .065, .12, .035)),
+                        _element(1, "Compose", "Button", (.86, .065, .1, .035)),
+                        _element(2, "Search", "SearchField", (.04, .15, .92, .045), editable=True,
+                                 actions=("TAP", "TYPE"))]
+            for row, (name, preview) in enumerate(self.THREADS):
+                elements.append(_element(3 + row, name, "Cell", (0, .22 + row * .1, 1, .095)))
+            text = "Messages\n" + "\n".join(f"{name}\n{preview}" for name, preview in self.THREADS)
+            return elements, text
+        sent = stage == "sent"
+        value = typed if stage == "typed" else ""
+        elements = [_element(90, "Alex Rivera", "NavigationBar", (0, .05, 1, .08)),
+                    _element(0, "Messages", "Button", (.02, .065, .24, .035)),
+                    _element(1, "Alex Rivera", "StaticText", (.3, .06, .4, .04)),
+                    _element(2, "See you at 7? I'll grab a table", "StaticText", (.05, .2, .7, .06)),
+                    _element(3, "Message", "TextField", (.12, .9, .7, .045), editable=True, value=value,
+                             actions=("TAP", "TYPE"))]
+        if stage == "typed":
+            elements.append(_element(4, "Send", "Button", (.85, .9, .1, .045)))
+        if sent:
+            elements.append(_element(5, self.message, "StaticText", (.3, .3, .65, .06)))
+            elements.append(_element(6, "Delivered", "StaticText", (.72, .37, .23, .025)))
+        text = "Alex Rivera\nSee you at 7? I'll grab a table" + (f"\n{self.message}\nDelivered" if sent else "")
+        return elements, text
+
+    def settings(self, stage):
+        if stage in {"top", "scrolled"}:
+            rows = self.ROWS if stage == "top" else self.MORE_ROWS
+            elements = [_element(90, "Settings", "NavigationBar", (0, .05, 1, .07)),
+                        _element(0, "Search", "SearchField", (.04, .13, .92, .045), editable=True,
+                                 actions=("TAP", "TYPE"))]
+            for row, name in enumerate(rows):
+                elements.append(_element(1 + row, name, "Cell", (0, .2 + row * .075, 1, .07)))
+            return elements, "Settings\n" + "\n".join(rows)
+        dark = stage == "dark"
+        elements = [_element(90, "Display & Brightness", "NavigationBar", (0, .05, 1, .07)),
+                    _element(0, "Settings", "Button", (.02, .065, .22, .035)),
+                    _element(1, "Display & Brightness", "StaticText", (.25, .06, .5, .04)),
+                    # The two appearances read as a pair of toggles, so the finished task can show its proof:
+                    # "Dark: On", the switch the request named at the value it asked for.
+                    _element(2, "Light", "Toggle", (.1, .15, .3, .22), value="0" if dark else "1"),
+                    _element(3, "Dark", "Toggle", (.6, .15, .3, .22), value="1" if dark else "0"),
+                    _element(4, "Automatic", "Switch", (0, .41, 1, .06), value="0"),
+                    _element(5, "Text Size", "Cell", (0, .53, 1, .06)),
+                    _element(6, "Bold Text", "Switch", (0, .6, 1, .06), value="0")]
+        text = ("Display & Brightness\nAPPEARANCE\nLight\nDark\nAutomatic\nText Size\nBold Text"
+                + ("\nDark, selected" if dark else "\nLight, selected"))
+        return elements, text
+
+    def search(self, stage, typed):
+        if stage == "home":
+            elements = [_element(0, "Search", "Button", (.82, .06, .12, .045)),
+                        _element(1, "Profile", "Button", (.8, .92, .15, .05))]
+            return elements, "For You\nSearch\nProfile"
+        if stage == "search":
+            elements = [_element(0, "Search", "SearchField", (.1, .06, .7, .05), editable=True,
+                                 actions=("TAP", "TYPE_SUBMIT", "TYPE"), value=typed),
+                        _element(1, "Cancel", "Button", (.82, .06, .15, .05))]
+            return elements, "Search"
+        title = f"{self.query.capitalize()} guide"
+        elements = [_element(0, title, "Button", (.05, .2, .9, .3)),
+                    _element(1, "@getmobster", "Button", (.1, .55, .5, .05))]
+        return elements, f"Top results\n{title}\n@getmobster"
+
+
+class DemoPhone(Driver):
+    """A scripted iPhone showing one app. ``pace`` scales the simulated latency (0 in tests)."""
+
+    capabilities = frozenset({"capture_preview"})
+    can_type = True
+
+    def __init__(self, bundle, goal, pace=1.0):
+        self.bundle, self.pace = bundle, pace
+        self.screens = Screens(bundle, goal)
+        self.stage = {MESSAGES: "inbox", SETTINGS: "top"}.get(bundle, "home")
+        self.typed = ""
+        self.lock = threading.Lock()
+        self.revision = 0
+
+    def _wait(self, seconds):
+        if self.pace > 0:
+            time.sleep(seconds * self.pace)
+
+    def snapshot(self):
+        elements, text = self.screens.build(self.stage, self.typed)
+        return Snapshot(elements, text, 390, 844, SOURCE, bundle_id=self.bundle,
+                        revision=f"{self.stage}-{self.revision}")
+
+    def observe(self, timeout=10):
+        self._wait(.18)
+        with self.lock:
+            return self.snapshot()
+
+    def execute(self, operation, target, snapshot, text=None, timeout=10):
+        self._wait(.22)
+        label = target.label if target is not None else ""
+        with self.lock:
+            self.revision += 1
+            stage = self.stage
+            if self.bundle == MESSAGES:
+                if stage == "inbox" and operation == "TAP" and label == "Alex Rivera":
+                    self.stage = "thread"
+                elif stage == "thread" and operation in {"TYPE", "TYPE_SUBMIT"}:
+                    self.stage, self.typed = "typed", text or ""
+                elif stage == "typed" and operation == "TAP" and label == "Send":
+                    self.stage = "sent"
+            elif self.bundle == SETTINGS:
+                if stage == "top" and operation == "SWIPE_UP":
+                    self.stage = "scrolled"
+                elif stage == "scrolled" and operation == "TAP" and label == "Display & Brightness":
+                    self.stage = "display"
+                elif stage == "display" and operation == "TAP" and label == "Dark":
+                    self.stage = "dark"
+            elif self.bundle != WALLET:
+                if stage == "home" and operation == "TAP":
+                    self.stage = "search"
+                elif stage == "search" and operation in {"TYPE", "TYPE_SUBMIT"}:
+                    self.stage, self.typed = "results", text or ""
+
+    def capture_preview(self, timeout=3):
+        with self.lock:
+            stage, typed = self.stage, self.typed
+        png = render_screen(self.bundle, stage, typed, self.screens.message, self.screens.query)
+        return "data:image/png;base64," + base64.b64encode(png).decode()
+
+    def close(self):
+        pass
+
+
+class DemoChat:
+    """The model's stand-in for Mobster's agent."""
+
+    model = MODEL
+    provider = "anthropic"  # the usage ledger's name for Mobster's agent's calls; a scripted one costs nothing
+
+    def __init__(self, pace=1.0):
+        self.pace = pace
+        self.usage = {"prompt_tokens": 0, "completion_tokens": 0, "cached_tokens": 0, "calls": 0}
+
+    def _wait(self, seconds):
+        if self.pace > 0:
+            time.sleep(seconds * self.pace)
+
+    def complete(self, messages, schema, timeout=60, **_):
+        text = "\n".join(part.get("text", "") for message in messages for part in (
+            message["content"] if isinstance(message["content"], list) else [{"text": message["content"]}]))
+        request = (re.search(r"Request: (.*)", text) or [None, ""])[1]
+        if "items" in (schema.get("properties") or {}):
+            # The task contract: a message to send is the one commit, so Mobster asks before it taps Send; anything
+            # else is a look at the screen.
+            items = [{"kind": "COMMIT", "app": "Messages", "what": "message to Alex Rivera",
+                      "payload": _message(request),
+                      "act": "send_message", "count": "1", "condition": "", "quote": request}] \
+                if re.search(r"\b(?:text|message|send)\b", request, re.I) else \
+                [{"kind": "READ", "app": "", "what": "the screen the task asks for", "payload": "", "act": "none",
+                  "count": "", "condition": "", "quote": request}]
+            return {"items": items}, {"prompt_tokens": 0, "completion_tokens": 0}
+        self._wait(.55)
+        self.usage["calls"] += 1
+        rows = text.split("Screen elements:\n", 1)[-1].splitlines()
+
+        def row(label):
+            return next((line for line in rows if f'"{label}"' in line), None)
+
+        def act(operation, label=None, words=None):
+            line = row(label) if label else None
+            return {"operation": operation, "target": line.split()[0] if line else None, "target_label": None,
+                    "text": words, "app": None}
+        answer = None
+        if row("Delivered"):
+            actions, answer = [act("DONE")], f"Sent “{_message(request)}” to Alex Rivera."
+        elif row("Send"):
+            actions = [act("TAP", "Send")]
+        elif row("Message"):
+            actions = [act("TYPE", "Message", _message(request))]
+        elif row("Alex Rivera"):
+            actions = [act("TAP", "Alex Rivera")]
+        elif row("Dark") and re.search(r'"Dark".*\bon\b', row("Dark")):
+            actions, answer = [act("DONE")], "Dark Mode is on."
+        elif row("Dark"):
+            actions = [act("TAP", "Dark")]
+        elif row("Display & Brightness"):
+            actions = [act("TAP", "Display & Brightness")]
+        elif row("Wi-Fi"):
+            actions = [act("SWIPE_UP")]
+        elif row("Apple Card"):
+            actions, answer = [act("DONE")], "Your Wallet has an Apple Card and a Transit card."
+        elif any("results" in line.casefold() for line in rows) or row(f"{_query(request).capitalize()} guide"):
+            actions, answer = [act("DONE")], f"The top result is the {_query(request).capitalize()} guide."
+        elif row("Cancel"):
+            actions = [act("TYPE_SUBMIT", "Search", _query(request))]
+        else:
+            actions = [act("TAP", "Search")]
+        return {"thought": "", "plan": "", "notes_add": [], "answer": answer, "checklist_updates": [],
+                "actions": actions}, {"prompt_tokens": 0, "completion_tokens": 0}
+
+    def close(self):
+        pass
+
+
+LIGHT = {"bg": (255, 255, 255), "text": (0, 0, 0), "muted": (138, 138, 142), "rule": (216, 216, 220),
+         "field": (238, 238, 240), "blue": (10, 132, 255), "bubble": (233, 233, 235)}
+DARK = {"bg": (0, 0, 0), "text": (255, 255, 255), "muted": (142, 142, 147), "rule": (56, 56, 58),
+        "field": (28, 28, 30), "blue": (10, 132, 255), "bubble": (38, 38, 40)}
+ICON_COLORS = [(52, 120, 246), (255, 149, 0), (0, 122, 255), (0, 122, 255), (52, 199, 89), (52, 199, 89),
+               (142, 142, 147), (0, 122, 255), (142, 142, 147), (0, 122, 255)]
+AVATARS = [(255, 159, 10), (191, 90, 242), (48, 209, 88), (100, 210, 255), (255, 69, 58)]
+
+
+@lru_cache(maxsize=32)
+def render_screen(bundle, stage, typed="", message=DEFAULT_MESSAGE, query="coffee"):
+    """A PNG of one scripted screen, 390 x 844 like an iPhone's points."""
+    from PIL import Image, ImageDraw, ImageFont
+
+    dark = bundle == SETTINGS and stage == "dark"
+    c = DARK if dark else LIGHT
+    image = Image.new("RGB", (390, 844), c["bg"])
+    draw = ImageDraw.Draw(image)
+
+    def font(size):
+        try:
+            return ImageFont.load_default(size=size)
+        except TypeError:  # Pillow without FreeType
+            return ImageFont.load_default()
+
+    small, body, title = font(15), font(17), font(30)
+    draw.text((28, 14), "9:41", fill=c["text"], font=small)
+    draw.rounded_rectangle((330, 16, 360, 28), radius=3, outline=c["text"], width=2)
+    draw.rectangle((333, 19, 352, 25), fill=c["text"])
+
+    if bundle == MESSAGES and stage == "inbox":
+        draw.text((16, 50), "Edit", fill=c["blue"], font=body)
+        draw.text((20, 88), "Messages", fill=c["text"], font=title)
+        draw.rounded_rectangle((16, 130, 374, 164), radius=10, fill=c["field"])
+        draw.text((40, 138), "Search", fill=c["muted"], font=body)
+        for row, (name, preview) in enumerate(Screens.THREADS):
+            y = 186 + row * 84
+            draw.ellipse((16, y, 70, y + 54), fill=AVATARS[row % len(AVATARS)])
+            draw.text((84, y + 4), name, fill=c["text"], font=body)
+            draw.text((84, y + 28), preview[:30], fill=c["muted"], font=small)
+            draw.line((84, y + 72, 390, y + 72), fill=c["rule"])
+    elif bundle == MESSAGES:
+        draw.text((12, 50), "‹", fill=c["blue"], font=title)
+        draw.ellipse((170, 44, 220, 94), fill=AVATARS[0])
+        draw.text((158, 100), "Alex Rivera", fill=c["text"], font=small)
+        draw.line((0, 126, 390, 126), fill=c["rule"])
+        draw.rounded_rectangle((16, 170, 270, 222), radius=20, fill=c["bubble"])
+        draw.text((32, 186), "See you at 7? I'll grab a table", fill=c["text"], font=small)
+        if stage == "sent":
+            draw.rounded_rectangle((110, 246, 374, 298), radius=20, fill=c["blue"])
+            draw.text((124, 262), message[:30], fill=(255, 255, 255), font=small)
+            draw.text((306, 306), "Delivered", fill=c["muted"], font=small)
+        draw.rounded_rectangle((52, 756, 374, 792), radius=18, outline=c["rule"], width=2)
+        field = typed if stage == "typed" else ""
+        draw.text((68, 764), field[:28] or "iMessage", fill=c["text"] if field else c["muted"], font=body)
+        if stage == "typed":
+            draw.ellipse((340, 760, 368, 788), fill=c["blue"])
+        draw.text((18, 758), "+", fill=c["muted"], font=title)
+    elif bundle == SETTINGS and stage in {"top", "scrolled"}:
+        draw.text((20, 60), "Settings", fill=c["text"], font=title)
+        draw.rounded_rectangle((16, 106, 374, 140), radius=10, fill=c["field"])
+        draw.text((40, 114), "Search", fill=c["muted"], font=body)
+        rows = Screens.ROWS if stage == "top" else Screens.MORE_ROWS
+        for row, name in enumerate(rows):
+            y = 166 + row * 62
+            draw.rounded_rectangle((20, y + 12, 50, y + 42), radius=7,
+                                   fill=ICON_COLORS[(row + (0 if stage == "top" else 5)) % len(ICON_COLORS)])
+            draw.text((64, y + 16), name, fill=c["text"], font=body)
+            draw.text((360, y + 14), "›", fill=c["muted"], font=body)
+            draw.line((64, y + 58, 390, y + 58), fill=c["rule"])
+    elif bundle == SETTINGS:
+        draw.text((12, 50), "‹ Settings", fill=c["blue"], font=body)
+        draw.text((100, 86), "Display & Brightness", fill=c["text"], font=body)
+        draw.text((24, 128), "APPEARANCE", fill=c["muted"], font=small)
+        for column, (name, shade) in enumerate((("Light", (242, 242, 247)), ("Dark", (28, 28, 30)))):
+            x = 60 + column * 160
+            draw.rounded_rectangle((x, 156, x + 110, 330), radius=14, fill=shade, outline=c["rule"], width=2)
+            draw.text((x + 34, 344), name, fill=c["text"], font=body)
+            selected = (name == "Dark") == dark
+            draw.ellipse((x + 45, 376, x + 65, 396), fill=c["blue"] if selected else c["bg"],
+                         outline=c["muted"], width=2)
+        for row, name in enumerate(("Automatic", "Text Size", "Bold Text")):
+            y = 440 + row * 58
+            draw.text((24, y), name, fill=c["text"], font=body)
+            draw.line((24, y + 40, 390, y + 40), fill=c["rule"])
+        draw.rounded_rectangle((300, 434, 350, 464), radius=15, fill=c["field"])
+    elif bundle == WALLET:
+        draw.text((20, 60), "Wallet", fill=c["text"], font=title)
+        draw.rounded_rectangle((20, 118, 370, 336), radius=18, fill=(40, 40, 40))
+        draw.rounded_rectangle((20, 362, 370, 580), radius=18, fill=(10, 132, 255))
+    else:
+        if stage == "home":
+            draw.rectangle((0, 0, 390, 844), fill=(18, 18, 18))
+            draw.text((150, 56), "For You", fill=(255, 255, 255), font=body)
+            draw.ellipse((150, 330, 240, 420), outline=(255, 255, 255), width=3)
+        else:
+            draw.rounded_rectangle((16, 50, 310, 90), radius=10, fill=c["field"])
+            draw.text((32, 60), (typed or query)[:22] if stage == "results" else "Search", fill=c["text"], font=body)
+            if stage == "results":
+                draw.rounded_rectangle((20, 160, 370, 420), radius=12, fill=(214, 170, 120))
+                draw.text((30, 430), f"{query.capitalize()} guide"[:30], fill=c["text"], font=body)
+    draw.rounded_rectangle((128, 826, 262, 831), radius=2, fill=c["text"])
+    out = io.BytesIO()
+    image.save(out, "PNG")
+    return out.getvalue()

mobile_agent/tui/images.py

@@ -0,0 +1,29 @@
+"""Whether this terminal can show the phone's real screenshot inside the UI."""
+
+import os
+
+
+def likely(env):
+    """True when the environment names a terminal that shows images."""
+    from ..terminal_image import protocol
+    term = env.get("TERM", "")
+    return (protocol(env) != "blocks" or term.startswith("foot") or "KONSOLE_VERSION" in env
+            or env.get("TERM_PROGRAM", "").lower() in {"rio", "contour"})
+
+
+def image_widget(env=None):
+    """textual-image's widget class for this terminal (kitty protocol or sixel), or None for the text view."""
+    env = os.environ if env is None else env
+    choice = env.get("MOBSTER_PHONE_VIEW", "auto").lower()
+    if choice == "text" or (choice != "image" and not likely(env)):
+        return None
+    try:
+        import textual_image.renderable as renderable  # asks the terminal once, on import
+        from textual_image.widget import SixelImage, TGPImage
+    except Exception:
+        return None
+    if renderable.Image is renderable.TGPImage:
+        return TGPImage
+    if renderable.Image is renderable.SixelImage:
+        return SixelImage
+    return None

mobile_agent/tui/keys.py

@@ -0,0 +1,64 @@
+"""The terminal UI's commands and keys, without the UI library."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    args: str
+    help: str
+    section: str = "Task"
+    key: str = ""
+
+
+COMMANDS = [
+    Command("new", "", "Start a new conversation", "Conversation", "ctrl+n"),
+    Command("threads", "", "Open a recent conversation", "Conversation", "ctrl+t"),
+    Command("attach", "<path>", "Send a file with the next task", "Conversation", "@./"),
+    Command("memory", "", "See what Mobster remembers", "Conversation"),
+    Command("remember", "<text>", "Tell Mobster something to remember", "Conversation"),
+    Command("app", "[name]", "Choose the app the next task starts in", "Task", "@app"),
+    Command("ask", "", "Turn “Ask before acting” on or off", "Task", "shift+tab"),
+    Command("cap", "<usd>|off", "Set a spend cap per task, in US dollars", "Task"),
+    Command("format", "<auto|text|json|yaml|csv|markdown>", "Choose the answer format", "Task"),
+    Command("history", "", "Browse past tasks", "View", "ctrl+r"),
+    Command("resume", "[id]", "Open a past task and put it back in the box", "View"),
+    Command("devices", "", "Your iPhone, and how to set it up", "View"),
+    Command("login", "", "Save your Claude or OpenAI key", "View"),
+    Command("screen", "", "Show or hide your iPhone's screen", "View", "ctrl+s"),
+    Command("details", "", "Show every phase of each step", "View", "ctrl+o"),
+    Command("clear", "", "Clear the transcript", "View", "ctrl+l"),
+    Command("help", "", "Keys and commands", "View", "?"),
+    Command("quit", "", "Leave Mobster", "View", "ctrl+d"),
+]
+SECTIONS = ("Conversation", "Task", "View")
+
+KEY_GROUPS = (
+    ("Task", (
+        ("enter", "Run the task; while one runs, tell Mobster something"),
+        ("esc", "Stop the task, or answer Don't to an approval"),
+        ("y / n", "Answer an approval: its verb (Send, Pay…) or Don't"),
+        ("a", "Always allow the apps on a task's approval card"),
+        ("page up / page down", "Read a long approval card"),
+        ("ctrl+c", "Stop the task; press twice to quit"),
+        ("shift+tab", "Ask before acting on or off"),
+        ("@", "Pick the app: @messages text Kate Bell…"),
+        ("↑ ↓", "Previous tasks (the Try rows, before your first)"),
+    )),
+    ("Conversation", (
+        ("ctrl+n", "New conversation"),
+        ("ctrl+t", "Recent conversations"),
+        ("@./ @~/", "Attach a file by its path"),
+    )),
+    ("View", (
+        ("/", "Commands"),
+        ("?", "This sheet"),
+        ("ctrl+o", "Step details"),
+        ("ctrl+s", "Your iPhone's screen"),
+        ("ctrl+r", "History"),
+        ("ctrl+l", "Clear"),
+        ("ctrl+d", "Quit"),
+    )),
+)
+KEYS = [pair for _, pairs in KEY_GROUPS for pair in pairs]

mobile_agent/tui/prompt.py

@@ -0,0 +1,195 @@
+"""The terminal UI's prompt: @mentions, the suggestion popup and history recall."""
+
+import os
+import re
+
+from rich.text import Text
+from textual.widgets import Input, OptionList, Static
+from textual.widgets.option_list import Option
+
+from ..app_choice import MENTION, find_app, infer_app, mention_rank
+from .chrome import EXAMPLES
+from .keys import COMMANDS, SECTIONS
+from .render import ACCENT, FAINT, GREEN, TEXT
+
+PATH_MENTION = re.compile(r"(?:^|\s)@((?:\./|~/|/)[^\s]*)$")
+
+
+class PromptMixin:
+    """The prompt box: which app a task names, the popup of commands, apps and paths, and recalling past tasks."""
+
+    def target_app(self, value):
+        """The app the next task starts in: the one chosen, the one it names, else None (Mobster picks)."""
+        if self.app_choice:
+            return self.app_choice
+        goal, mentioned = self.split_mentions(value)
+        return mentioned or (infer_app(goal, self.apps) if goal.strip() else None)
+
+    def split_mentions(self, value):
+        """(the task without the @words that name an app, the first app they name)."""
+        named = []
+
+        def drop(match):
+            app = find_app(match.group(1), self.apps)
+            if app is None:
+                return match.group(0)
+            named.append(app)
+            return ""
+        return MENTION.sub(drop, value).strip(), (named[0] if named else None)
+
+    def suggest(self, value):
+        box = self.query_one("#suggest", OptionList)
+        hint = self.query_one("#suggest-hint", Static)
+        options = []
+        footer = ""
+        if value.startswith("/") and " " not in value:
+            query = value[1:].casefold()
+            matches = [c for c in COMMANDS if c.name.startswith(query) or (query and query in c.name)]
+            name_width = max((len(c.name) + 1 for c in matches), default=0) + 2
+            help_width = max((len(c.help) for c in matches), default=0) + 2
+            for section in SECTIONS:
+                rows = [c for c in matches if c.section == section]
+                if not rows:
+                    continue
+                if not query:
+                    options.append(Option(Text(section, style=f"bold {FAINT}"), id=f"section:{section}",
+                                          disabled=True))
+                for command in rows:
+                    prompt = Text()
+                    prompt.append(f"/{command.name}".ljust(name_width), style=f"bold {ACCENT}")
+                    prompt.append(command.help.ljust(help_width), style=TEXT)
+                    prompt.append(command.key or (command.args if command.args.startswith("<") else ""),
+                                  style=FAINT)
+                    options.append(Option(prompt, id=f"cmd:{command.name}"))
+            footer = "↑↓ move   enter choose   esc close"
+        else:
+            path = PATH_MENTION.search(value)
+            match = re.search(r"(?:^|\s)@([\w.-]*)$", value)
+            if path:
+                for entry in self.path_matches(path.group(1))[:10]:
+                    prompt = Text()
+                    prompt.append(entry["shown"], style=f"bold {TEXT}")
+                    prompt.append("  folder" if entry["dir"] else "  attach", style=FAINT)
+                    options.append(Option(prompt, id=f"path:{entry['path']}"))
+                footer = "enter attach   tab open a folder   esc close"
+            elif match:
+                query = match.group(1).casefold()
+                # Best match first (tab and enter take the first row): "@fa" is FaceTime, not safari.
+                ranked = sorted(((rank, index, app) for index, app in enumerate(self.apps)
+                                 if (rank := mention_rank(app, query)) is not None), key=lambda item: item[:2])
+                for _, _, app in ranked[:10]:
+                    prompt = Text()
+                    prompt.append(app["name"], style=f"bold {TEXT}")
+                    prompt.append(f"  {app['bundleId']}", style=FAINT)
+                    if app.get("installed"):
+                        prompt.append("  installed", style=GREEN)
+                    options.append(Option(prompt, id=f"app:{app['id']}"))
+                footer = "enter choose   esc close"
+        box.clear_options()
+        if options:
+            box.add_options(options)
+            first = next((i for i, option in enumerate(options) if not option.disabled), 0)
+            box.highlighted = first
+        box.set_class(bool(options), "open")
+        hint.update(Text(footer, style=FAINT))
+        hint.set_class(bool(options), "open")
+
+    def path_matches(self, typed):
+        """Files and folders for an @./, @~/ or @/ path: [{path, shown, dir}]."""
+        from pathlib import Path
+        expanded = os.path.expanduser(typed)
+        folder, _, stem = expanded.rpartition("/")
+        folder = folder + "/" if folder or typed.startswith("/") else "./"
+        try:
+            entries = sorted(Path(folder or "/").iterdir(), key=lambda p: (not p.is_dir(), p.name.casefold()))
+        except OSError:
+            return []
+        out = []
+        for entry in entries:
+            if entry.name.startswith(".") and not stem.startswith("."):
+                continue
+            if not entry.name.casefold().startswith(stem.casefold()):
+                continue
+            shown = typed[:len(typed) - len(stem)] + entry.name + ("/" if entry.is_dir() else "")
+            out.append({"path": str(entry), "shown": shown, "dir": entry.is_dir()})
+        return out
+
+    def suggestions_open(self):
+        return self.query_one("#suggest", OptionList).has_class("open")
+
+    def close_suggestions(self):
+        self.query_one("#suggest", OptionList).set_class(False, "open")
+        self.query_one("#suggest-hint", Static).set_class(False, "open")
+
+    def accept_suggestion(self, key_name="enter"):
+        box = self.query_one("#suggest", OptionList)
+        if box.highlighted is None:
+            return False
+        option = box.get_option_at_index(box.highlighted)
+        if option.disabled:
+            return False
+        prompt = self.query_one("#prompt", Input)
+        kind, _, key = option.id.partition(":")
+        if kind == "cmd":
+            command = next(c for c in COMMANDS if c.name == key)
+            if command.args and not command.args.startswith("["):
+                prompt.value = f"/{key} "
+            else:
+                prompt.value = ""
+                self.run_command(key, "")
+        elif kind == "app":
+            self.app_choice = next((a for a in self.apps if a["id"] == key), None)
+            prompt.value = re.sub(r"(?:^|\s)@[\w.-]*$", "", prompt.value).lstrip()
+        elif kind == "path":
+            if os.path.isdir(key) and key_name == "tab":
+                typed = PATH_MENTION.search(prompt.value).group(1)
+                stem = typed.rpartition("/")[2]
+                prompt.value = prompt.value[:len(prompt.value) - len(stem)] + os.path.basename(key) + "/"
+                prompt.cursor_position = len(prompt.value)
+                self.suggest(prompt.value)
+                return True
+            prompt.value = PATH_MENTION.sub("", prompt.value).rstrip()
+            if not os.path.isdir(key):
+                self.attach(key)
+        prompt.cursor_position = len(prompt.value)
+        self.close_suggestions()
+        self.refresh_chip()
+        return True
+
+    def prompt_key(self, key, character):
+        """Keys the prompt hands over before editing: the popup's, history recall and ``?``. True if used."""
+        if self.suggestions_open():
+            box = self.query_one("#suggest", OptionList)
+            if key in {"down", "up"}:
+                box.action_cursor_down() if key == "down" else box.action_cursor_up()
+                option = box.get_option_at_index(box.highlighted) if box.highlighted is not None else None
+                if option is not None and option.disabled:
+                    box.action_cursor_down() if key == "down" else box.action_cursor_up()
+                return True
+            if key in {"tab", "enter"}:
+                return self.accept_suggestion(key)
+            if key == "escape":
+                self.close_suggestions()
+                return True
+            return False
+        if key in {"up", "down"}:
+            self.action_recall(-1 if key == "up" else 1)
+            return True
+        if character == "?" and not self.query_one("#prompt", Input).value:
+            self.run_command("help", "")
+            return True
+        return False
+
+    def action_recall(self, delta):
+        prompt = self.query_one("#prompt", Input)
+        # With no past tasks yet, ↑ steps through the Try rows on the welcome screen, the first one first.
+        recalls = self.recalls or [goal for _, goal in reversed(EXAMPLES)]
+        if self.focused is not prompt or self.suggestions_open() or self.running is not None:
+            return
+        if self.recall_index is None:
+            if delta > 0:
+                return
+            self.recall_index = len(recalls)
+        self.recall_index = max(0, min(len(recalls), self.recall_index + delta))
+        prompt.value = recalls[self.recall_index] if self.recall_index < len(recalls) else ""
+        prompt.cursor_position = len(prompt.value)