mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/waiting/drafts.py

@@ -0,0 +1,136 @@
+"""Drafted replies from Apple's on-device model, through the ``draft-reply`` helper (helper_draft_reply.swift)."""
+
+import json
+import re
+import subprocess
+import time
+
+from .. import native_helpers
+
+HELPER = "draft_reply"
+PER_DRAFT_S = 15.0
+TOTAL_S = 75.0
+MAX_DRAFT = 280
+REASONS = {
+    "apple_intelligence_off": "Apple Intelligence is off on this Mac, so you'll write your own replies. Turn it on in "
+    "System Settings to get drafts.",
+    "device_not_eligible": "This Mac can't run Apple's on-device model, so you'll write your own replies.",
+    "model_not_ready": "Apple's on-device model is still downloading, so you'll write your own replies this time.",
+    "needs_macos_26": "Drafts need macOS 26 or later, so you'll write your own replies.",
+}
+UNAVAILABLE = "Drafts aren't available on this Mac right now, so you'll write your own replies."
+
+# A draft that commits the person: a date, a time, money, a day or month, a yes or no to a request.
+_COMMITS = re.compile(
+    r"[$€£¥]|\b\d{1,2}[:.]\d{2}\b|\b\d{1,2}\s?(am|pm)\b|\b\d{1,2}/\d{1,2}\b|\b\d+\s?(dollars|bucks|usd|eur|euros)\b"
+    r"|\b(monday|tuesday|wednesday|thursday|friday|saturday|sunday|tomorrow|tonight|today|january|february|march|april"
+    r"|may \d|june|july|august|september|october|november|december)\b"
+    r"|^(yes|yeah|yep|sure|no|nope|absolutely|definitely)\b|\bi('ll| will) (be there|come|pay|send|do it|take it)\b"
+    r"|\bcount me in\b|\bi('m| am) in\b", re.I)
+
+
+def reason_text(reason):
+    return REASONS.get(reason, UNAVAILABLE)
+
+
+def _run_helper():
+    """The helper's path, or None when this Mac has none and can't build one."""
+    path = native_helpers.find(HELPER)
+    if path is not None:
+        return str(path)
+    try:
+        return str(native_helpers.build(HELPER))
+    except (LookupError, FileNotFoundError, OSError, subprocess.SubprocessError):
+        return None
+
+
+def status(runner=None):
+    """{"available": bool, "reason": str}: whether the on-device model can draft. ``runner`` is for tests."""
+    if runner is not None:
+        return runner.status()
+    helper = _run_helper()
+    if helper is None:
+        return {"available": False, "reason": "no_helper"}
+    try:
+        done = subprocess.run([helper, "status"], capture_output=True, text=True, timeout=20)
+        data = json.loads((done.stdout or "").strip().splitlines()[-1])
+    except (OSError, subprocess.SubprocessError, ValueError, IndexError):
+        return {"available": False, "reason": "unavailable"}
+    return {"available": bool(data.get("available")), "reason": str(data.get("reason") or "")}
+
+
+def clean(text):
+    """One tidy line of at most 280 characters, or '' when there isn't one."""
+    text = " ".join(str(text or "").replace("“", '"').replace("”", '"').split()).strip(' "')
+    if len(text) > MAX_DRAFT:
+        text = text[:MAX_DRAFT].rsplit(" ", 1)[0].rstrip(" ,;:")
+    return text
+
+
+def acceptable(text):
+    """A draft that commits the person to nothing (no date, time, money, yes or no on their behalf)."""
+    return bool(text) and not _COMMITS.search(text)
+
+
+def payload(items):
+    """The helper's request for ``items`` (rank.Item): each item's id, situation and last 8 messages."""
+    return {"items": [{"id": str(item.chat), "kind": item.bucket,
+                       "messages": [{"from": "you" if m.mine else "them", "text": m.text} for m in item.context[-8:]]}
+                      for item in items]}
+
+
+def draft_all(items, runner=None, per_draft=PER_DRAFT_S, total=TOTAL_S, clock=time.monotonic):
+    """{str(chat id): draft} for the items that got one. Never raises; whatever fails is simply missing."""
+    if not items:
+        return {}
+    request = payload(items)
+    if runner is not None:
+        lines = runner.run(request, per_draft, total)
+    else:
+        lines = _stream(request, per_draft, total, clock)
+    out = {}
+    for line in lines:
+        if isinstance(line, dict) and line.get("ok") and isinstance(line.get("id"), str):
+            text = clean(line.get("draft"))
+            if acceptable(text):
+                out[line["id"]] = text
+    return out
+
+
+def _stream(request, per_draft, total, clock):
+    helper = _run_helper()
+    if helper is None:
+        return
+    deadline = clock() + total
+    try:
+        process = subprocess.Popen([helper, "run", "--timeout", str(per_draft)], stdin=subprocess.PIPE,
+                                   stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True)
+    except OSError:
+        return
+    try:
+        process.stdin.write(json.dumps(request))  # message text goes on stdin, never on a command line or in a log
+        process.stdin.close()
+        import selectors
+        selector = selectors.DefaultSelector()
+        selector.register(process.stdout, selectors.EVENT_READ)
+        while clock() < deadline:
+            if not selector.select(timeout=1.0):
+                if process.poll() is not None:
+                    break
+                continue
+            line = process.stdout.readline()
+            if not line:
+                break
+            try:
+                yield json.loads(line)
+            except ValueError:
+                continue
+    except (OSError, ValueError):
+        return
+    finally:
+        if process.poll() is None:
+            process.kill()
+        try:
+            process.wait(timeout=5)
+        except subprocess.SubprocessError:
+            pass

mobile_agent/waiting/job.py

@@ -0,0 +1,145 @@
+"""The "Who's waiting on me" job: Messages read, ranked and drafted on this Mac, never by a cloud model."""
+
+import os
+import sqlite3
+import threading
+import time
+import uuid
+
+from .. import result_blocks
+from ..api_errors import APIError
+from . import contacts as contact_book
+from . import drafts, messages, rank
+
+BUNDLE = "com.apple.MobileSMS"
+APP = {"id": "messages", "name": "Messages", "bundleId": BUNDLE}
+GOAL = "Who's waiting on me?"
+MAX_LAST = 200
+MISSING = ("Mobster can't find your Messages history on this Mac. Turn on Messages in iCloud in Messages settings, "
+           "then try again.")
+DENIED = (
+    "Mobster needs Full Disk Access to read your Messages on this Mac. Turn it on in System Settings, then try again.")
+UNREADABLE = (
+    "Mobster couldn't read the Messages database on this Mac, so nothing was changed. Update Mobster, then try again.")
+BUSY = "Mobster is already looking through your Messages. Wait for it to finish."
+_lock = threading.Lock()
+
+
+def ago(seconds):
+    """'3 hours ago', '1 day ago', '2 weeks ago'."""
+    minutes = max(int(seconds // 60), 0)
+    for unit, size in (("week", 7 * 24 * 60), ("day", 24 * 60), ("hour", 60)):
+        if minutes >= size:
+            count = minutes // size
+            return f"{count} {unit}{'' if count == 1 else 's'} ago"
+    return "just now"
+
+
+def _short(text, limit=MAX_LAST):
+    text = " ".join((text or "").split())
+    return text if len(text) <= limit else text[:limit - 1].rsplit(" ", 1)[0].rstrip(" ,;:") + "…"
+
+
+def block_for(items, names, written, *, title=None):
+    """The review_queue block for ranked ``items``: ``names`` is {chat id: name}, ``written`` {str(chat id): draft}."""
+    out = []
+    for item in items:
+        name = names.get(item.chat)
+        when = ago(item.age_s)
+        quote = _short(item.last.text)
+        if item.bucket == "promised":
+            context = f"You said this {when}. They haven't written since."
+            quote = f"You wrote: {quote}"
+        elif item.bucket == "asked":
+            context = f"Asked you {when}"
+        else:
+            context = f"Wrote {when}"
+        row = {"id": f"c{item.chat}", "bucket": item.bucket, "to": name or item.handle,
+               "app": APP["name"], "bundleId": BUNDLE, "context": context, "lastMessage": quote,
+               "draft": written.get(str(item.chat)) or ""}
+        if name:
+            row["handle"] = item.handle
+        if not row["draft"]:
+            # No draft because the on-device model is off or its draft was dropped: the person writes the reply, and
+            # Approve takes their typed words (result_blocks.approval_item).
+            row["yourWords"] = result_blocks.YOUR_WORDS
+        out.append(row)
+    buckets = [{"id": bucket, "label": rank.LABELS[bucket]} for bucket in rank.BUCKETS
+               if any(item.bucket == bucket for item in items)]
+    return result_blocks.review_queue(out, title=title, buckets=buckets, action="send_message", id="waiting")
+
+
+def _plural(count, one, many):
+    return f"{count} {one if count == 1 else many}"
+
+
+def answer_for(items, drafted, availability):
+    """The one line the result says: counts only, no names and no message text."""
+    if not items:
+        return (
+            "Nobody is waiting on you in your Messages. Group chats, short codes and conversations older than 30 days "
+            "aren't counted.")
+    counts = rank.counts(items)
+    parts = []
+    if counts["asked"]:
+        parts.append(f"{_plural(counts['asked'], 'person asked', 'people asked')} you something")
+    if counts["waiting"]:
+        parts.append(f"{_plural(counts['waiting'], 'person is', 'people are')} waiting on a reply")
+    if counts["promised"]:
+        parts.append(f"{_plural(counts['promised'], 'promise', 'promises')} to keep")
+    line = ", ".join(parts).capitalize() + "."
+    if availability.get("available"):
+        line += f" {_plural(drafted, 'draft', 'drafts')} to approve. Nothing was sent."
+    else:
+        line += " " + drafts.reason_text(availability.get("reason")) + " Nothing was sent."
+    return line
+
+
+def read(now, path=None):
+    """Ranked items from chat.db with the errors the app shows in plain words."""
+    target = path or messages.DEFAULT_PATH
+    if not os.path.exists(target):
+        raise APIError(MISSING, 404, "messages_missing")
+    if not messages.columns_ok(target):
+        # A file we can see but can't open is Full Disk Access; one we open but that lacks the columns is a newer macOS.
+        try:
+            messages.connect(target).close()
+        except sqlite3.Error:
+            raise APIError(DENIED, 403, "full_disk_access") from None
+        raise APIError(UNREADABLE, 422, "messages_unreadable")
+    try:
+        chats = messages.read_chats(target, now)
+    except sqlite3.Error:
+        raise APIError(DENIED, 403, "full_disk_access") from None
+    return rank.rank(chats, now)
+
+
+def run(runtime, *, now=None, path=None, book=None, runner=None, key=None):
+    """Make the finished task. Returns the Run. ``runner`` and ``book`` are for tests."""
+    if key:
+        # A retried start (a lost answer) returns the task the first one made, without reading or drafting again.
+        prior = runtime.journal.lookup(key[:128])
+        if prior and prior[0] in runtime.runs:
+            return runtime.runs[prior[0]]
+    if not _lock.acquire(blocking=False):
+        raise APIError(BUSY, 409, "waiting_busy")
+    try:
+        now = time.time() if now is None else now
+        items = read(now, path)
+        availability = drafts.status(runner)
+        written = drafts.draft_all(items, runner=runner) if availability.get("available") else {}
+        book = book if book is not None else contact_book.ContactBook.load()
+        names = {item.chat: book.name(item.handle) for item in items}
+        total = len(items)
+        title = f"Who's waiting on you: {_plural(total, 'person', 'people')}"
+        blocks = [block_for(items, names, written, title=title)] if items else []
+        answer = answer_for(items, len(written), availability)
+        summary = {"event": "result", "status": "completed", "outcome": "done", "answer": answer, "reason": None,
+                   "independently_verified": True, "actions": 0, "decisions": 0, "elapsed_ms": 0, "model": None,
+                   "proof": [{"quote": "Read your Messages on this Mac. Nothing was sent.", "app": APP["name"]}],
+                   **({"blocks": {"v": 1, "blocks": blocks}} if blocks else {})}
+        app = next((dict(one) for one in runtime.apps_for(None) if one.get("bundleId") == BUNDLE), dict(APP))
+        return runtime.compose_result(app=app, goal=GOAL, summary=summary,
+                                      idempotency_key=(key or f"waiting-{uuid.uuid4().hex}")[:128], origin="app")
+    finally:
+        _lock.release()

mobile_agent/waiting/messages.py

@@ -0,0 +1,174 @@
+"""A read-only reader of the Messages history on this Mac (``~/Library/Messages/chat.db``)."""
+
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import quote
+
+from ..notify_triggers.sources import MAC_EPOCH
+
+ONE_TO_ONE = 45                  # chat.style
+MAX_TEXT = 600                   # characters kept of one message
+DEFAULT_PATH = Path.home() / "Library" / "Messages" / "chat.db"
+ATTACHMENT_TEXT = "[attachment]"
+
+NEEDED = {
+    "message": {"ROWID", "text", "attributedBody", "handle_id", "is_from_me", "date", "item_type",
+                "associated_message_type", "cache_has_attachments"},
+    "chat": {"ROWID", "style"},
+    "chat_message_join": {"chat_id", "message_id"},
+    "chat_handle_join": {"chat_id", "handle_id"},
+    "handle": {"ROWID", "id"},
+}
+# SMS fallbacks of a tapback from before iOS 10 and from Android: the reaction as a text.
+_REACTION_TEXT = re.compile(r"^(Loved|Liked|Disliked|Laughed at|Emphasized|Questioned|Reacted \S+ to) [“\"]", re.I)
+_OBJECT_REPLACEMENT = ""
+
+
+@dataclass(frozen=True)
+class Message:
+    rowid: int
+    mine: bool
+    when: float                  # Unix seconds
+    text: str
+    attachment: bool = False
+
+
+@dataclass
+class Chat:
+    rowid: int
+    handle: str                  # the other person's phone number or email, as Messages has it
+    messages: list = field(default_factory=list)      # oldest first, real messages only
+
+
+def apple_to_unix(value):
+    """Messages' ``date`` as Unix seconds: nanoseconds (macOS 10.13 on) or seconds since 2001-01-01."""
+    value = float(value or 0)
+    if abs(value) > 1e11:
+        value /= 1e9
+    return value + MAC_EPOCH
+
+
+def unix_to_apple_ns(seconds):
+    return int((seconds - MAC_EPOCH) * 1_000_000_000)
+
+
+def decode_attributed_body(blob):
+    """The message's plain string from an ``attributedBody`` blob, or None when there isn't one to find."""
+    if not blob:
+        return None
+    # typedstream: NSString, class bytes, "+", the UTF-8 length (a byte, or 0x81/0x82/0x83 and 2/4/8 LE bytes), text.
+    data = bytes(blob)
+    start = 0
+    while True:
+        at = data.find(b"NSString", start)
+        if at < 0:
+            return None
+        start = at + 1
+        plus = data.find(b"+", at + 8, at + 8 + 12)
+        if plus < 0:
+            continue
+        cursor = plus + 1
+        if cursor >= len(data):
+            continue
+        first = data[cursor]
+        if first == 0x81:
+            width, cursor = 2, cursor + 1
+        elif first == 0x82:
+            width, cursor = 4, cursor + 1
+        elif first == 0x83:
+            width, cursor = 8, cursor + 1
+        elif first < 0x80:
+            width = 0
+        else:
+            continue
+        if width:
+            if cursor + width > len(data):
+                continue
+            length = int.from_bytes(data[cursor:cursor + width], "little")
+            cursor += width
+        else:
+            length, cursor = first, cursor + 1
+        if length <= 0 or cursor + length > len(data):
+            continue
+        try:
+            text = data[cursor:cursor + length].decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        return text
+    return None
+
+
+def message_text(text, attributed):
+    """What a message says: ``text``, else the string in ``attributedBody``; attachments' placeholders removed."""
+    words = text if isinstance(text, str) and text.strip() else decode_attributed_body(attributed)
+    return (words or "").replace(_OBJECT_REPLACEMENT, "").strip()
+
+
+def connect(path=None):
+    """The database, read-only. ``sqlite3.OperationalError`` when it can't be opened (no file, no access)."""
+    target = Path(path) if path else DEFAULT_PATH
+    connection = sqlite3.connect(f"file:{quote(str(target))}?mode=ro", uri=True, timeout=5)
+    connection.execute("PRAGMA query_only = ON")
+    return connection
+
+
+def columns_ok(path=None):
+    """Whether chat.db has the tables and columns this reader reads (``PRAGMA table_info`` only)."""
+    try:
+        connection = connect(path)
+    except sqlite3.Error:
+        return False
+    try:
+        for table, needed in NEEDED.items():
+            have = {row[1] for row in connection.execute(f"PRAGMA table_info({table})")}
+            if not needed <= have:
+                return False
+        return True
+    except sqlite3.Error:
+        return False
+    finally:
+        connection.close()
+
+
+def read_chats(path, now, days=30, per_chat=40, limit_chats=400):
+    """Every one-to-one chat with a real message in the last ``days`` days"""
+    since = unix_to_apple_ns(now - days * 86400)
+    connection = connect(path)
+    try:
+        # Newest activity first; a chat with one handle only (a one-to-one chat has exactly one).
+        chats = connection.execute(
+            "SELECT c.ROWID, MIN(h.id), COUNT(h.ROWID) "
+            "FROM chat c JOIN chat_handle_join j ON j.chat_id = c.ROWID JOIN handle h ON h.ROWID = j.handle_id "
+            "WHERE c.style = ? AND EXISTS (SELECT 1 FROM chat_message_join m WHERE m.chat_id = c.ROWID) "
+            "GROUP BY c.ROWID HAVING COUNT(h.ROWID) = 1", (ONE_TO_ONE,)).fetchall()
+        recent = {row[0]: row[1] for row in connection.execute(
+            "SELECT j.chat_id, MAX(m.date) FROM chat_message_join j JOIN message m ON m.ROWID = j.message_id "
+            "WHERE m.date >= ? GROUP BY j.chat_id", (since,))}
+        wanted = sorted((row for row in chats if row[0] in recent), key=lambda row: -recent[row[0]])[:limit_chats]
+        out = []
+        for rowid, handle, _count in wanted:
+            rows = connection.execute(
+                "SELECT m.ROWID, m.text, m.attributedBody, m.is_from_me, m.date, m.cache_has_attachments "
+                "FROM chat_message_join j JOIN message m ON m.ROWID = j.message_id "
+                "WHERE j.chat_id = ? AND m.date >= ? AND COALESCE(m.item_type, 0) = 0 "
+                "AND COALESCE(m.associated_message_type, 0) = 0 "
+                "ORDER BY m.date DESC, m.ROWID DESC LIMIT ?", (rowid, since, per_chat * 2)).fetchall()
+            messages = []
+            for mid, text, body, mine, date, attached in rows:
+                words = message_text(text, body)
+                if words and _REACTION_TEXT.match(words):
+                    continue
+                if not words:
+                    if not attached:
+                        continue
+                    words = ATTACHMENT_TEXT
+                messages.append(Message(mid, bool(mine), apple_to_unix(date), words[:MAX_TEXT], bool(attached)))
+                if len(messages) >= per_chat:
+                    break
+            if messages:
+                out.append(Chat(rowid, handle, list(reversed(messages))))
+        return out
+    finally:
+        connection.close()

mobile_agent/waiting/rank.py

@@ -0,0 +1,115 @@
+"""Who is waiting on you: deterministic rules over the chats ``messages.read_chats`` returns."""
+
+import re
+from dataclasses import dataclass, field
+
+WINDOW_DAYS = 30
+MIN_AGE_S = 2 * 3600
+MAX_ITEMS = 25
+CONTEXT = 8
+BUCKETS = ("asked", "waiting", "promised")
+LABELS = {"asked": "Asked you something", "waiting": "Waiting on you", "promised": "You said you would"}
+
+_ASK = re.compile(
+    r"\?|\b(can|could|would|will) (you|u)\b|\b(did|do|are|have|were|was|is) (you|u)\b|\blet me know\b|\blmk\b"
+    r"|\bcall me\b|\btext me\b|\bget back to me\b|\bany update\b|\bwhen (can|are|will|do) (you|u)\b"
+    r"|\bplease (send|call|text|let|reply|confirm|check)\b|\bwhat do you think\b|\bwhat time\b", re.I)
+_PROMISE = re.compile(r"\b(i'll|i will|ill|let me|i can send|i'm going to|im gonna|i am going to)\b|\btomorrow\b", re.I)
+_NOT_A_PROMISE = re.compile(r"\blet me know\b", re.I)
+_CLOSER_WORDS = frozenset((
+    "ok okay k kk thanks thank you thx ty tysm np yw lol lmao haha hahaha hehe ha cool nice great awesome perfect "
+    "sounds "
+    "good got it yep yup yes yeah sure bet will do right same true word love u so much see ya later bye night "
+    "goodnight "
+    "gn lovely amazing wonderful appreciate appreciated all fine alright sweet noted").split())
+
+
+def clean(text):
+    return (text or "").replace("’", "'").replace("‘", "'").strip()
+
+
+def is_closer(text):
+    """Whether a message ends a conversation instead of asking for a reply: "ok", "thanks!", "lol", "👍", "😂😂"."""
+    text = clean(text)
+    if not text:
+        return True
+    if "?" in text:
+        return False
+    if not re.search(r"[^\W_]", text):       # no letter or digit: an emoji, "!!!", "..."
+        return True
+    words = re.findall(r"[^\W_]+(?:'[^\W_]+)?", text.lower())
+    return 0 < len(words) <= 5 and all(word in _CLOSER_WORDS for word in words)
+
+
+def asks(text):
+    return bool(_ASK.search(clean(text)))
+
+
+def promises(text):
+    """Whether the message promises something ("I'll send it tomorrow", "let me check"). "Let me know" doesn't."""
+    return bool(_PROMISE.search(_NOT_A_PROMISE.sub(" ", clean(text))))
+
+
+def is_person_handle(handle):
+    """A phone number (7 or more digits) or an email address that isn't a no-reply sender."""
+    handle = (handle or "").strip()
+    if not handle:
+        return False
+    lowered = handle.lower()
+    if re.search(r"no[-_.]?reply|do[-_.]?not[-_.]?reply|donotreply|mailer-daemon|notifications?@", lowered):
+        return False
+    if "@" in handle:
+        return bool(re.fullmatch(r"[^@\s]+@[^@\s]+\.[^@\s]+", handle))
+    if re.fullmatch(r"\+?[\d\s().-]+", handle):
+        return len(re.sub(r"\D", "", handle)) >= 7
+    return False
+
+
+@dataclass
+class Item:
+    chat: int
+    handle: str
+    bucket: str
+    last: object                         # the Message the item is about (theirs; yours for "promised")
+    age_s: float
+    context: list = field(default_factory=list)      # up to 8 newest messages, oldest first
+
+
+def classify(chat, now):
+    """The Item for one chat, or None."""
+    if not is_person_handle(chat.handle) or not chat.messages:
+        return None
+    messages = sorted(chat.messages, key=lambda m: (m.when, m.rowid))
+    horizon = now - WINDOW_DAYS * 86400
+    last = messages[-1]
+    if not last.mine:
+        age = now - last.when
+        if last.when < horizon or age < MIN_AGE_S or is_closer(last.text):
+            return None
+        bucket = "asked" if asks(last.text) else "waiting"
+        return Item(chat.rowid, chat.handle, bucket, last, age, messages[-CONTEXT:])
+    # The last message is yours: the newest promise of yours that they haven't answered, unless you sent a file after.
+    for index in range(len(messages) - 1, -1, -1):
+        message = messages[index]
+        if not message.mine:
+            return None
+        if message.when < horizon:
+            return None
+        if promises(message.text) and not message.attachment:
+            age = now - message.when
+            if age < MIN_AGE_S or any(later.attachment for later in messages[index + 1:]):
+                return None
+            return Item(chat.rowid, chat.handle, "promised", message, age,
+                        messages[max(0, index - CONTEXT + 1):index + 1])
+    return None
+
+
+def rank(chats, now, limit=MAX_ITEMS):
+    """The items for ``chats``: by bucket, then the longest wait first, at most ``limit``."""
+    items = [item for item in (classify(chat, now) for chat in chats) if item is not None]
+    items.sort(key=lambda item: (BUCKETS.index(item.bucket), -item.age_s, item.chat))
+    return items[:limit]
+
+
+def counts(items):
+    return {bucket: sum(1 for item in items if item.bucket == bucket) for bucket in BUCKETS}

mobile_agent/waiting/register.py

@@ -0,0 +1,26 @@
+"""Track ``waiting``'s registrations: no agent or MCP tool, since its result would carry message text to a model."""
+
+from ..api_errors import APIError
+from ..api_routes import Response, Route
+from ..api_routes import register as add_route
+from . import job
+
+APP_ONLY = "Only the Mobster app can read your Messages. Open Mobster and ask there."
+
+
+def start(request):
+    """POST /api/waiting: {"key"?} -> 201 {"runId"}. The Mac app only (its session), like Settings routes."""
+    # Fail closed: the result holds message text, so only the Mac app's own session starts it (not an API token alone).
+    if not request.app_session:
+        raise APIError(APP_ONLY, 403, "app_only")
+    body = request.body if isinstance(request.body, dict) else {}
+    key = body.get("key")
+    if key is not None and (not isinstance(key, str) or not 1 <= len(key) <= 100):
+        raise ValueError("key is 1 to 100 characters")
+    run = job.run(request.runtime, key=f"waiting-{key}" if key else None)
+    return Response.json({"runId": run.id}, 201)
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    add_route(Route("waiting", "POST", "/api/waiting", start))