mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/permissions/gate.py

@@ -0,0 +1,316 @@
+"""The permission gate: one per run; applies the run's mode to an action and says allow or ask."""
+
+import re
+import threading
+import time
+from dataclasses import dataclass, replace
+
+from ..state import icon_glyph, pixel_read
+from ..task_policy import approval_title
+from . import consequence, project_policy
+from . import policy as P
+from .rules import RULE_OP, Action, changes, code_entry, norm, outside_act, rememberable, rule_words, screen_context
+
+TITLES = {"code": "Enter this code?", "setting": "Change this setting?", "save": "Save this?",
+          "submit": "Submit this?", "change": "Make this change?", "react": "Add this reaction?",
+          "follow": "Follow this account?", "unfollow": "Unfollow this account?", "post": "Repost this?",
+          "block": "Block this?", "report": "Report this?"}
+# The card's line for an act ``rules.outside_act`` found (at most 12 words).
+OUTSIDE_REASONS = {"react": "Others see this reaction", "follow": "Others see this follow",
+                   "unfollow": "Others see this unfollow", "post": "Others see this repost",
+                   "block": "Changes who can reach you", "report": "Sends a report about someone"}
+
+
+@dataclass(frozen=True)
+class Decision:
+    decision: str            # allow | ask
+    kind: str                # navigate | input | change | commit | floor
+    act: str | None          # the card's verb
+    reason: str              # for the card, at most 12 words
+    ms: float                # time this decision added
+    title: str | None = None
+    # The approval card may offer "Don't ask again" (an allow rule for ``rule`` in this app).
+    rememberable: bool = False
+    rule: str | None = None
+    # The ask is the project policy's (project_policy.py): the mode and the guards would have let it go ahead.
+    by_policy: bool = False
+
+    @property
+    def asks(self):
+        return self.decision == "ask"
+
+
+def decision_for(kind, mode, existing=False):
+    """allow | ask for an action of ``kind`` under ``mode``. ``existing``: the agent's own rules ask."""
+    if kind == "floor":
+        return "ask"
+    if mode == P.DONT_ASK:
+        return "allow"
+    if existing or kind == "commit":
+        return "ask"
+    if kind == "change" and mode == P.ASK_ALL:
+        return "ask"
+    return "allow"
+
+
+_COMPOSE = re.compile(r"\b(message|imessage|text message|reply|comment|write|chat|say something|add a caption)\b")
+
+
+def composer_text(elements):
+    """The text waiting in the screen's composer, "" for an empty one, None when the screen has no composer."""
+    found = None
+    for element in elements or ():
+        label, placeholder = getattr(element, "label", "") or "", getattr(element, "placeholder", "") or ""
+        if (getattr(element, "role", None) not in ("TextView", "TextField")
+                or not _COMPOSE.search(norm(label or placeholder))):
+            continue
+        value = getattr(element, "value", "") or ""
+        if placeholder and value == placeholder or value == label:
+            value = ""
+        if value.strip():
+            return value
+        found = ""
+    return found
+
+
+def action_from(op, element, snapshot, *, text=None, typed=None, app_name="", goal="", title=None, origins=None):
+    """The gate's Action for ``op`` on ``element`` (a state.Element, or None) in ``snapshot``."""
+    elements = getattr(snapshot, "elements", ()) or ()
+    if title is None:
+        try:
+            from ..contract_screen import screen_title
+            title = screen_title(snapshot) or ""
+        except Exception:
+            title = ""
+    return Action(op=op, label=getattr(element, "label", "") or "", role=getattr(element, "role", None),
+                  value=getattr(element, "value", None) or None,
+                  app=getattr(snapshot, "bundle_id", "") or "", app_name=app_name or "", text=text,
+                  typed=typed if typed is not None else composer_text(elements), screen=title or "",
+                  context=screen_context(elements), goal=goal or "",
+                  hint=" ".join(str(getattr(element, key, "") or "") for key in ("placeholder", "identifier")),
+                  origins=tuple(origins) if origins is not None else None,
+                  rect=tuple(getattr(element, "rect", ()) or ()), around=tuple(elements),
+                  pixels=pixel_read(snapshot), glyph=icon_glyph(getattr(element, "locator", "")))
+
+
+class PermissionGate:
+    def __init__(self, mode=P.DEFAULT_MODE, *, apps=None, emit=None, goal="", origin=None, exceptions=None,
+                 policy=None, profile=None):
+        self.mode = mode if mode in P.MODES else P.DEFAULT_MODE
+        self.apps = apps if apps is not None else P.AppPolicy()
+        self.emit = emit
+        self.goal = goal
+        self.origin = origin
+        self.exceptions = exceptions
+        # The project's policy and the profile (accounts' ``{id, handle...}``) the task acts as: they only add asks.
+        self.policy = policy
+        self.profile = profile
+
+    @property
+    def narrowed(self):
+        """Whether the project policy can ask here, so a run asks (or refuses, with nobody to answer) in Full access."""
+        return self.policy is not None and self.policy.narrows
+
+    def reading(self, action, existing_act=None):
+        """(kind, act, reason) for ``action`` by today's rules."""
+        if code_entry(action):
+            return "floor", "code", "Types a one-time code"
+        if existing_act:
+            return "commit", existing_act, ""
+        found = consequence.read(action if action.goal or not self.goal else replace(action, goal=self.goal),
+                                 action.around)
+        if found is not None:
+            return "commit", found.act, found.reason
+        act = outside_act(action)
+        if act is not None:
+            return "commit", act, OUTSIDE_REASONS[act]
+        act = changes(action)
+        if act is not None:
+            return "change", act, ""
+        op = (action.op or "").upper()
+        return ("input" if op in ("TYPE", "SET_TEXT") else "navigate"), None, ""
+
+    def decide(self, action, existing_act=None, forced=False):
+        """The answer for ``action``; ``forced`` asks whatever the mode says and offers or uses no allow rule. The
+        project policy, when there is one, can turn an allow into an ask and nothing else."""
+        decision = self._decide(action, existing_act, forced)
+        if self.policy is not None and decision.kind in ("commit", "change"):
+            decision = self._narrow(decision, action)
+        return self._record(decision)
+
+    def _narrow(self, decision, action):
+        """``decision`` or, when the project policy asks where the mode and the guards would not, an ask. An ask the
+        mode already made stays as it is, without an offer of "Don't ask again" if the policy asks too."""
+        kinds = project_policy.kinds_of(decision.kind, decision.act)
+        why = self.policy.asks(kinds, action.app, self.profile)
+        if decision.asks:
+            return replace(decision, rememberable=False, rule=None) if why and decision.rememberable else decision
+        why = why or self.policy.take(kinds, action.app, self.profile)
+        if why is None:
+            return decision
+        act = decision.act
+        title = consequence.TITLES.get(act or "") or TITLES.get(act or "") or approval_title(act)
+        return Decision("ask", decision.kind, act, why, decision.ms, title, by_policy=True)
+
+    def _decide(self, action, existing_act, forced):
+        started = time.perf_counter()
+        kind, act, reason = self.reading(action, existing_act)
+        verdict = decision_for(kind, self.mode, existing=bool(existing_act))
+        if forced and verdict == "allow":
+            verdict = "ask"
+        outside = self.origin in P.OUTSIDE_ORIGINS
+        rule = (rememberable(action, act) if verdict == "ask" and kind in ("commit", "change") and not forced
+                else None)
+        if rule is not None and not outside and self.exceptions is not None:
+            try:
+                remembered = self.exceptions.contains(action.app, rule, RULE_OP)
+            except Exception:  # noqa: BLE001 -- an unreadable store asks
+                remembered = False
+            if remembered:
+                return Decision("allow", kind, act, "You said not to ask again for this",
+                                (time.perf_counter() - started) * 1000, rule=rule)
+        title = None
+        if verdict == "ask":
+            title = (consequence.REASON_TITLES.get(reason) or TITLES.get(act or "")
+                     or consequence.TITLES.get(act or "")) if kind in ("floor", "change") or (
+                kind == "commit" and not existing_act) else None
+        return Decision(verdict, kind, act, reason if verdict != "allow" else "",
+                        (time.perf_counter() - started) * 1000, title,
+                        rememberable=rule is not None and not outside, rule=rule)
+
+    @staticmethod
+    def remember(decision, app, app_name=""):
+        """The approval request's ``remember`` for ``decision`` (run.Run keeps it until the answer)."""
+        if decision is None or not decision.rememberable or not decision.rule or not app:
+            return None
+        return {"app": app, "label": decision.rule, "op": RULE_OP, "app_name": app_name or "",
+                "words": rule_words(decision.rule, app_name)}
+
+    def _record(self, decision):
+        if self.emit is not None and decision.decision != "allow":
+            try:
+                # No label, no text: what the gate said, and why.
+                self.emit({"event": "permission_decision", "decision": decision.decision, "kind": decision.kind,
+                           "act": decision.act, "ms": round(decision.ms, 2), "mode": self.mode,
+                           **({"policy": True} if decision.by_policy else {})})
+            except Exception:
+                pass
+        return decision
+
+
+class PermissionGuard:
+    """A phone guard for the person's app choices; the rest is the inner guard's. Fails closed: no answer, no app."""
+
+    def __init__(self, inner, apps, names=None, outside=False, ask=None, grants=None, conversation=None):
+        self.inner, self.names, self.outside = inner, dict(names or {}), outside
+        self._apps = apps
+        self.ask, self.grants = ask, grants
+        self.declined = set()  # apps the person said Not now to in this run: not asked again in it
+        # Allow covers this run, or its conversation's runs; never an app that is refused or switched off.
+        self._conversation = conversation is not None
+        self._granted = conversation if conversation is not None else set()
+        self.instruction = None
+        self._lock = threading.Lock()
+
+    @property
+    def apps(self):
+        apps = self._apps
+        try:
+            return apps() if callable(apps) else apps
+        except Exception:  # noqa: BLE001 -- unreadable settings: nothing counts as approved, the never-open list holds
+            return P.AppPolicy(access="ask")
+
+    @apps.setter
+    def apps(self, value):
+        self._apps = value
+
+    def _approved(self, apps, bundle):
+        return bundle in self._granted or apps.approved(bundle, self.grants)
+
+    def take_instruction(self):
+        """What the person said to do instead on the app card, once; None when they didn't."""
+        with self._lock:
+            instruction, self.instruction = self.instruction, None
+        return instruction
+
+    def __getattr__(self, name):
+        if self.inner is None:
+            raise AttributeError(name)
+        return getattr(self.inner, name)
+
+    def check(self, driver, *, cause):
+        if self.inner is None:
+            from ..agent_hooks import READY
+            return READY
+        return self.inner.check(driver, cause=cause)
+
+    def attached(self):
+        return self.inner.attached() if self.inner is not None else None
+
+    def finish(self, driver):
+        if self.inner is not None:
+            self.inner.finish(driver)
+
+    def _name(self, bundle):
+        return self.names.get(bundle) or bundle
+
+    def request(self, bundles):
+        """Whether every app in ``bundles`` may be used now: False if one is refused, declined, or nobody answers."""
+        apps = self.apps
+        wanted = [b for b in dict.fromkeys(bundles) if b and b != P.SPRINGBOARD]
+        if any(not apps.allows(b, outside=self.outside) for b in wanted):
+            return False
+        with self._lock:
+            missing = [b for b in wanted if not self._approved(apps, b)]
+            if not missing:
+                return True
+            if any(b in self.declined for b in missing) or self.ask is None:
+                return False
+            names = [self._name(b) for b in missing]
+            listed = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " and " + names[-1]
+            card = {"kind": "commit", "operation": "OPEN_APP", "label": listed[:200], "role": "App", "text": None,
+                    "title": f"Allow Mobster to use {listed}?", "act": "use app", "app_name": names[0], "apps": names,
+                    "bundles": missing, "reason": P.task_card_reason(len(names), self._conversation)}
+            if self.grants is not None:
+                card["remember"] = {"app": missing[0], "label": P.APP_LABEL, "op": P.APP_OP, "app_name": names[0],
+                                    "words": P.ALWAYS_ALLOW,
+                                    "apps": [{"app": b, "app_name": n} for b, n in zip(missing, names)]}
+            try:
+                answer = self.ask(card)
+            except Exception:  # noqa: BLE001 -- no answer: the app stays shut
+                answer = None
+            if answer != "approved":
+                self.declined.update(missing)
+                if isinstance(answer, str) and answer.startswith("redirected:"):
+                    self.instruction = " ".join(answer.split(":", 1)[1].split())[:500] or None
+                return False
+            # Allow: this run only; Always allow is read from the store at each check, so it can be off mid-run.
+            self._granted.update(b for b in missing if not apps.approved(b, self.grants))
+            return True
+
+    def allows_app(self, bundle_id):
+        try:
+            if bundle_id and bundle_id != P.SPRINGBOARD and not self.request([bundle_id]):
+                return False
+            inner = getattr(self.inner, "allows_app", None)
+            return bool(inner(bundle_id)) if callable(inner) else True
+        except Exception:  # noqa: BLE001 -- fails closed
+            return False
+
+    def refusal(self, bundles):
+        """Why ``request(bundles)`` said no, without asking again."""
+        apps = self.apps
+        wanted = [b for b in dict.fromkeys(bundles) if b and b != P.SPRINGBOARD]
+        refused = [b for b in wanted if not apps.allows(b, outside=self.outside)]
+        waiting = [b for b in wanted if not self._approved(apps, b)]
+        return next((self.blocked_message(b) for b in refused + waiting), None)
+
+    def blocked_message(self, bundle_id, name=None):
+        name = name or self._name(bundle_id)
+        apps = self.apps
+        if not apps.allows(bundle_id, outside=self.outside):
+            return apps.blocked_message(name, outside=self.outside)
+        if not self._approved(apps, bundle_id):
+            return apps.unapproved_message(name)
+        inner = getattr(self.inner, "blocked_message", None)
+        return inner(bundle_id, name) if callable(inner) else None

mobile_agent/permissions/outside.py

@@ -0,0 +1,316 @@
+"""Approvals for outside agents over MCP: the same gate applies, and only the Mac app's session can answer one."""
+
+import hashlib
+import json
+import threading
+import time
+import uuid
+from dataclasses import asdict
+
+from . import consequence
+from . import policy as P
+from .gate import PermissionGate
+
+EXPIRES_S = 600
+WAIT_S = 38.0
+KEEP_S = 120          # a decided approval stays readable this long, for the agent that asked
+MAX_PENDING = 20
+POLL_S = 20.0
+
+
+class Refused(Exception):
+    """The action may not go ahead now; the message says why and what the agent can do."""
+
+    def __init__(self, message="", state=None, minutes=None):
+        super().__init__(message)
+        self.state, self.minutes = state, minutes
+
+
+def _clean(value, limit):
+    return " ".join(str(value or "").split())[:limit] or None
+
+
+class Registry:
+    def __init__(self, clock=time.time):
+        self.clock = clock
+        self._items = {}
+        self._version = 0
+        self._cond = threading.Condition()
+
+    def _expire(self, now):
+        for item in list(self._items.values()):
+            if item["state"] == "pending" and now * 1000 >= item["expiresAt"]:
+                item["state"], item["decidedAt"] = "timeout", now * 1000
+                self._version += 1
+            if item["state"] != "pending" and now * 1000 - (item.get("decidedAt") or 0) > KEEP_S * 1000:
+                del self._items[item["id"]]
+
+    def create(self, body):
+        if not isinstance(body, dict) or set(body) - {"key", "request", "device", "source"}:
+            raise ValueError("An approval takes key, request, device and source")
+        request = body.get("request")
+        if not isinstance(request, dict) or not isinstance(request.get("label"), str):
+            raise ValueError("request needs at least the control's label")
+        key = _clean(body.get("key"), 128)
+        source = body.get("source") if isinstance(body.get("source"), dict) else {}
+        fingerprint = hashlib.sha256(json.dumps((body.get("device"), source, request), sort_keys=True,
+                                               ensure_ascii=False, allow_nan=False).encode()).hexdigest()
+        now = self.clock()
+        with self._cond:
+            self._expire(now)
+            for item in self._items.values():
+                if key and item["key"] == key and item["state"] == "pending":
+                    if item["fingerprint"] != fingerprint:
+                        raise ValueError("This approval key already names a different waiting action")
+                    return dict(item)
+            if sum(item["state"] == "pending" for item in self._items.values()) >= MAX_PENDING:
+                raise ValueError("Too many approvals are waiting")
+            item = {"id": uuid.uuid4().hex[:12], "key": key, "fingerprint": fingerprint, "state": "pending",
+                    "kind": "commit", "outside": True,
+                    "source": {"kind": "mcp", "client": _clean(source.get("client"), 60)},
+                    "device": _clean(body.get("device"), 128),
+                    "operation": _clean(request.get("operation"), 20) or "TAP",
+                    "label": _clean(request.get("label"), 200) or "", "role": _clean(request.get("role"), 40) or "",
+                    "text": str(request["text"])[:4000] if isinstance(request.get("text"), str) else None,
+                    "title": _clean(request.get("title"), 160), "act": _clean(request.get("act"), 40),
+                    "reason": _clean(request.get("reason"), 120), "app": _clean(request.get("app_name"), 80) or "",
+                    "target": None, "requestedAt": now * 1000, "expiresAt": (now + EXPIRES_S) * 1000,
+                    "instruction": None}
+            if isinstance(request.get("apps"), list):
+                item["apps"] = [name for name in (_clean(n, 80) for n in request["apps"][:6]) if name]
+            self._items[item["id"]] = item
+            self._version += 1
+            self._cond.notify_all()
+            return dict(item)
+
+    def get(self, approval_id, wait=0.0):
+        """The approval, once decided or after ``wait`` seconds; None when unknown."""
+        deadline = time.monotonic() + max(0.0, min(wait, POLL_S))
+        with self._cond:
+            while True:
+                self._expire(self.clock())
+                item = self._items.get(approval_id)
+                if item is None or item["state"] != "pending":
+                    return dict(item) if item else None
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    return dict(item)
+                self._cond.wait(min(left, 1.0))
+
+    def pending(self, since=None, wait=0.0):
+        """(version, the approvals waiting): returns at once, or when the list changes after ``since``."""
+        deadline = time.monotonic() + max(0.0, min(wait, POLL_S))
+        with self._cond:
+            while True:
+                self._expire(self.clock())
+                if since is None or since != self._version or time.monotonic() >= deadline:
+                    items = [dict(i) for i in self._items.values() if i["state"] == "pending"]
+                    return self._version, sorted(items, key=lambda i: i["requestedAt"])
+                self._cond.wait(min(deadline - time.monotonic(), 1.0))
+
+    def answer(self, approval_id, approve, instruction=None):
+        if type(approve) is not bool:
+            raise ValueError("approve must be true or false")
+        if instruction is not None:
+            instruction = " ".join(str(instruction).split())
+            if approve or not 1 <= len(instruction) <= 500:
+                raise ValueError("A redirect declines the action and says in 1–500 characters what to do instead")
+        with self._cond:
+            self._expire(self.clock())
+            item = self._items.get(approval_id)
+            if item is None or item["state"] != "pending":
+                return False
+            item["state"] = "approved" if approve else "redirected" if instruction else "denied"
+            item["instruction"], item["decidedAt"] = instruction, self.clock() * 1000
+            self._version += 1
+            self._cond.notify_all()
+            return True
+
+    def cancel(self, approval_id):
+        with self._cond:
+            item = self._items.get(approval_id)
+            if item is None or item["state"] != "pending":
+                return False
+            item["state"], item["decidedAt"] = "cancelled", self.clock() * 1000
+            self._version += 1
+            self._cond.notify_all()
+            return True
+
+
+# In memory only: an approval can hold the exact text to be sent, which is never journaled.
+REGISTRY = Registry()
+
+
+def public(item):
+    """An approval as the Mac app reads it (the exact text included: it never leaves this Mac's memory)."""
+    return {k: v for k, v in item.items() if k not in {"key", "fingerprint"}}
+
+
+def key_for(device, action):
+    raw = json.dumps((device, asdict(action)), sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(raw.encode()).hexdigest()[:32]
+
+
+def app_name(bundle, device=None, folder=None):
+    """The name the person knows the app by ("Chrome")."""
+    try:
+        from ..catalog import app_name as catalog_name
+        from ..installed_apps import InventoryCache
+        from ..paths import user_data_dir
+        inventory = InventoryCache(folder or user_data_dir() / "installed-apps").load(device) if device else None
+        for app in (inventory.user if inventory is not None else ()):
+            if app.get("bundleId") == bundle and app.get("name") and app["name"] != bundle:
+                return app["name"]
+        return catalog_name(bundle) or bundle
+    except Exception:  # noqa: BLE001 -- a name is for reading: the bundle id stands in
+        return bundle
+
+
+def check_app(bundle, name=None, *, device, client_name=None, settings=None, grants=None, connect=None,
+              wait_s=WAIT_S):
+    """An outside agent opening or acting in ``bundle``: returns once approved, else Refused."""
+    settings = settings or P.from_file()
+    name = name or app_name(bundle, device)
+    if not settings.apps.allows(bundle, outside=True):
+        raise Refused(settings.apps.blocked_message(name, outside=settings.apps.allows(bundle)) +
+                      " Nothing was done.")
+    if grants is None:
+        from .exceptions import Exceptions, default_path
+        grants = Exceptions(default_path())
+    if settings.apps.approved(bundle, grants):
+        return
+    request = {"operation": "OPEN_APP", "label": name, "role": "App", "text": None,
+               "title": f"Allow Mobster to use {name}?", "act": "use app", "app_name": name, "apps": [name],
+               "reason": P.app_card_reason()}
+    answer = ask_app(request, key=hashlib.sha256(f"{device}␟app␟{bundle}".encode()).hexdigest()[:32],
+                     device=device, client_name=client_name, connect=connect, wait_s=wait_s)
+    if answer.get("state") == "approved":
+        try:
+            grants.add(bundle, P.APP_LABEL, P.APP_OP, name)
+        except Exception:  # noqa: BLE001 -- approved now even if the store can't keep it
+            pass
+        return
+    _refuse(answer, f"Allow Mobster to use {name}")
+
+
+def _refuse(answer, what):
+    """Refused with what the person's answer (not approved) means for the agent."""
+    state = answer.get("state")
+    if state == "redirected":
+        raise Refused(f"The user declined this in the Mobster app and said: {answer.get('instruction')!r}. Nothing "
+                      "was done.", state)
+    if state == "denied":
+        raise Refused("The user declined this in the Mobster app. Nothing was done.", state)
+    if state == "timeout":
+        raise Refused("Nobody answered the approval in the Mobster app in 10 minutes, so nothing was done.", state)
+    if state == "pending":
+        left = max(0, int((answer.get("expiresAt", 0) / 1000 - time.time()) // 60))
+        raise Refused(f"This needs the user's OK in the Mobster app ({what}). They haven't answered yet, so nothing "
+                      f"was done. Tell the user, then make the same call again to keep waiting (the request stays "
+                      f"open about {left} more minutes).", state, left)
+    raise Refused("The approval was withdrawn, so nothing was done.", "withdrawn")
+
+
+def _project_policy():
+    """The policy of the project this server runs in (its working folder), when MOBSTER_POLICY is on."""
+    from ..paths import default_history_db
+    from . import project_policy
+    folder = project_policy.project_folder() if project_policy.enabled() else None
+    return project_policy.load(folder, project_policy.counts_path(default_history_db())) if folder else None
+
+
+def check_action(action, *, device, client_name=None, settings=None, connect=None, wait_s=WAIT_S, forced=False):
+    """An outside agent's action: whether it asked (True), or Refused; never below ask_important."""
+    settings = settings or P.from_file()
+    if action.app:
+        check_app(action.app, action.app_name, device=device, client_name=client_name, settings=settings,
+                  connect=connect, wait_s=wait_s)
+    from ..harness_api import commit_act
+    gate = PermissionGate(P.effective_mode(settings.mode, None, "mcp"), apps=settings.apps, origin="mcp",
+                          policy=_project_policy())
+    op = (action.op or "").upper()
+    typing = op in ("TYPE", "SET_TEXT")
+    # A row's swipe is read by the gate's own signals (permissions.consequence): its words are the row's content.
+    existing = None if typing or op.startswith("SWIPE_") else commit_act(action.op, action.label, None,
+                                                                        action.app or None)
+    if existing == "other" and op in consequence.RETURN_OPS and consequence.query_return(action) and commit_act(
+            "TYPE", action.label, None, action.app or None) is None:
+        # commit_act calls every Return a commit; only a field told for certain to be a search or address bar drops it.
+        existing = None
+    decision = gate.decide(action, existing_act=existing, forced=forced)
+    if decision.decision == "allow":
+        return False
+    title = decision.title or approval_title(decision.act)
+    text = action.text
+    if text is None and decision.act in {"send_message", "reply", "comment", "post", "share"}:
+        text = action.typed
+    request = {"operation": action.op, "label": action.label, "role": action.role or "", "text": text,
+               "title": title, "act": decision.act, "reason": decision.reason or None,
+               "app_name": action.app_name or action.app}
+    answer = ask_app(request, key=key_for(device, action), device=device, client_name=client_name, connect=connect,
+                     wait_s=wait_s)
+    if answer.get("state") == "approved":
+        return True
+    _refuse(answer, title)
+
+
+def check_code(bundle, field_name, *, device, client_name=None, connect=None, wait_s=WAIT_S):
+    """An outside agent entering a one-time code (use_code): it asks in the Mac app in every mode, never remembered."""
+    request = {"operation": "USE_CODE", "label": str(field_name or "the code field")[:200], "role": "TextField",
+               "text": None, "title": "Enter this code?", "act": "code", "reason": "Types a one-time code",
+               "app_name": bundle or ""}
+    answer = ask_app(request, key=hashlib.sha256(f"{device}␟code␟{bundle}␟{field_name}".encode()).hexdigest()[:32],
+                     device=device, client_name=client_name, connect=connect, wait_s=wait_s)
+    if answer.get("state") == "approved":
+        return
+    _refuse(answer, "Enter this code?")
+
+
+def check_link(url, title, app, app_name, *, device, client_name=None, connect=None, wait_s=WAIT_S):
+    """An outside agent opening a link that asks (deeplinks.decide): the Mac app's card every time, never remembered."""
+    request = {"operation": "OPEN_URL", "label": f"Open {str(url)[:180]}", "role": "Link", "text": str(url)[:500],
+               "title": title or "Open this link?", "act": "open link", "reason": None,
+               "app_name": app_name or app or ""}
+    answer = ask_app(request, key=hashlib.sha256(f"{device}␟link␟{url}".encode()).hexdigest()[:32], device=device,
+                     client_name=client_name, connect=connect, wait_s=wait_s)
+    if answer.get("state") == "approved":
+        return
+    _refuse(answer, title or "Open this link?")
+
+
+_TITLES = {"send_message": "Send this message?", "reply": "Send this reply?", "comment": "Post this comment?",
+           "post": "Post this?", "react": "Send this reaction?", "pay": "Make this payment?",
+           "request_money": "Send this request?", "transfer": "Make this transfer?", "order": "Place this order?",
+           "book": "Make this booking?", "follow": "Follow this account?", "unfollow": "Unfollow this account?",
+           "share": "Share this?", "call": "Place this call?", "delete": "Delete this?", "cancel": "Cancel this?",
+           "install": "Get this app?"}
+
+
+def approval_title(act):
+    """The card's question for an act of today's commit test ("Send this message?")."""
+    return _TITLES.get(act or "", "Do this now?")
+
+
+def ask_app(request, *, key, device=None, client_name=None, connect=None, wait_s=WAIT_S):
+    """Raise the approval in the Mac app and wait up to ``wait_s`` for its answer: the approval as the app has it."""
+    from ..threads.client import Client, NoService, ServiceError
+    try:
+        client = (connect or (lambda: Client.connect(origin="mcp")))()
+        made = client.call("POST", "/api/approvals", {"key": key, "request": request, "device": device,
+                                                      "source": {"client": client_name}})
+    except (NoService, ServiceError, OSError):
+        raise Refused("This needs the user's OK, and the Mobster app isn't open to ask them. Ask the user to open "
+                      "Mobster, then try again. Nothing was done.") from None
+    approval = made.get("approval") or made
+    deadline = time.monotonic() + wait_s
+    while approval.get("state") == "pending":
+        left = deadline - time.monotonic()
+        if left <= 0:
+            break
+        try:
+            got = client.call("GET", f"/api/approvals/{approval['id']}?wait={min(POLL_S, max(1, int(left)))}",
+                              timeout=min(POLL_S, left) + 5)
+        except (ServiceError, OSError):
+            break
+        approval = got.get("approval") or got
+    return approval