mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/transport.py

@@ -0,0 +1,271 @@
+"""Bounded HTTP with one deadline per operation and no automatic retry: an interrupted request's outcome is unknown."""
+
+import http.client
+import json
+import math
+import select
+import socket
+import threading
+import time
+from urllib.parse import urlsplit
+
+from . import __version__
+from .errors import MobsterError
+
+
+def user_agent():
+    """The shared client identity used when calling Mobster services."""
+    import platform
+    return f"Mobster/{__version__} (macOS {platform.mac_ver()[0] or 'unknown'})"
+
+
+class TransportError(MobsterError):
+    """``status`` and ``wda_error``: a failed answer's HTTP status and WDA's error name, when there was an answer.
+    Not its message, which can hold app text."""
+
+    def __init__(self, *args, status=None, wda_error=None):
+        super().__init__(*args)
+        self.status, self.wda_error = status, wda_error
+
+
+# The request never left, so its outcome is known: nothing happened.
+class NotSent(TransportError):
+    pass
+
+
+# WDA checks the session before it runs anything, so nothing ran.
+class StaleSession(NotSent):
+    pass
+
+
+# Every error name WebDriverAgent v16.12.10 answers with, and the one HTTP status it pairs with each
+# (WebDriverAgentLib/Routing/FBCommandStatus.m). Anything else isn't WDA's name and is never kept: it could be app text.
+WDA_ERRORS = {
+    "unknown error": 500, "unable to capture screen": 500, "no such element": 404, "invalid element state": 400,
+    "invalid argument": 400, "stale element reference": 404, "invalid selector": 400, "no such alert": 404,
+    "unexpected alert open": 500, "unknown method": 405, "session not created": 500, "invalid coordinates": 400,
+    "unsupported operation": 500, "unknown command": 404, "timeout": 408, "element not visible": 400,
+    "invalid session id": 404,
+}
+
+
+def error_name(value):
+    """WDA's error name from an answer's ``value``, or None: only one of WDA_ERRORS' names, exactly."""
+    name = value.get("error") if isinstance(value, dict) else None
+    return name if isinstance(name, str) and name in WDA_ERRORS else None
+
+
+def answer_error(raw):
+    """Strictly decoded: a body with two ``error`` fields, say, names nothing."""
+    try:
+        return error_name(decode_json(raw).get("value"))
+    except (ValueError, AttributeError, UnicodeDecodeError, RecursionError):
+        return None
+
+
+class Deadline:
+    def __init__(self, timeout):
+        if type(timeout) not in (int, float) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("Timeout must be a finite positive number")
+        self.end = time.monotonic() + timeout
+
+    def remaining(self):
+        left = self.end - time.monotonic()
+        if left <= 0:
+            raise TimeoutError("Operation deadline exceeded")
+        return left
+
+
+def _unique_object(pairs):
+    # dict(pairs) then a length check: 4-6% faster than a Python loop on a 66 KB WDA tree (~400 us), 2026-09-24.
+    result = dict(pairs)
+    if len(result) != len(pairs):
+        raise ValueError("Duplicate JSON field")
+    return result
+
+
+def _invalid_constant(value):
+    raise ValueError("Nonfinite JSON value")
+
+
+def _finite_float(value):
+    result = float(value)
+    if not math.isfinite(result):
+        raise ValueError("Nonfinite JSON value")
+    return result
+
+
+def decode_json(raw):
+    return json.loads(raw, parse_constant=_invalid_constant, parse_float=_finite_float,
+                      object_pairs_hook=_unique_object)
+
+
+class HTTP:
+    def __init__(self, base_url, key="", timeout=20):
+        url = urlsplit(base_url)
+        if (url.scheme not in {"http", "https"} or not url.hostname or url.username or url.password
+                or url.query or url.fragment):
+            raise ValueError("Expected HTTP(S) base URL without embedded credentials")
+        if key and url.scheme != "https" and url.hostname not in {"localhost", "127.0.0.1", "::1"}:
+            raise ValueError("Remote credentials require HTTPS")
+        cls = http.client.HTTPSConnection if url.scheme == "https" else http.client.HTTPConnection
+        self.connection = cls(url.hostname, url.port, timeout=timeout)
+        self.prefix, self.key = url.path.rstrip("/"), key
+        self._inflight = threading.Lock()
+
+    def request(self, method, path, body=None, timeout=20):
+        deadline = Deadline(timeout)
+        if not isinstance(path, str) or not path.startswith("/") or any(c in path for c in "\r\n"):
+            raise ValueError("Expected an absolute HTTP request path")
+        # Encoding/validation precedes dispatch; invalid input cannot poison a live connection.
+        payload = None if body is None else json.dumps(body, allow_nan=False).encode()
+        if not self._inflight.acquire(blocking=False):
+            raise TransportError("HTTP client already has a request in flight; not retried")
+        headers = {"Content-Type": "application/json"}
+        if self.key:
+            headers["Authorization"] = "Bearer " + self.key
+        guard, finished = threading.Lock(), threading.Event()
+        active_socket = {"value": None}
+        answered_in_full = False
+
+        def expire():
+            # Socket timeouts restart on each chunk: cut a slow drip at the absolute deadline.
+            with guard:
+                if finished.is_set():
+                    return
+                sock = active_socket["value"] or self.connection.sock
+                if sock:
+                    try:
+                        sock.shutdown(socket.SHUT_RDWR)
+                    except OSError:
+                        pass
+                self.connection.close()
+
+        timer = threading.Timer(max(0, deadline.end - time.monotonic()), expire)
+        timer.daemon = True
+        timer.start()
+        try:
+            if self.connection.sock is not None and peer_closed(self.connection.sock):
+                # A kept connection the server has closed since, as WDA's failClient does after a header-level 400
+                # with no Connection header. Nothing of this request is sent yet, so a new connection resends nothing.
+                self.connection.close()
+            self.connection.timeout = deadline.remaining()
+            if self.connection.sock:
+                self.connection.sock.settimeout(deadline.remaining())
+            self.connection.request(method, self.prefix + path, payload, headers)
+            active_socket["value"] = self.connection.sock
+            deadline.remaining()
+            response = self.connection.getresponse()
+            raw = response.read(16_000_001)
+            deadline.remaining()
+            if len(raw) > 16_000_000:
+                raise TransportError("HTTP response exceeds limit; outcome unknown; not retried")
+            if isinstance(getattr(response, "length", None), int) and response.length != 0:
+                raise TransportError("Incomplete HTTP response; outcome unknown; not retried")
+            if response.status >= 300:
+                # Read to its end, so the connection is ready for the next request. WebDriverAgent keeps a descriptor
+                # per connection until it restarts: routine 404s would each cost one.
+                answered_in_full = response.isclosed()
+                name = answer_error(raw)
+                if response.status == 404 and name == "invalid session id":
+                    raise StaleSession("HTTP 404 StaleSession: invalid session id; nothing sent; not retried")
+                raise TransportError(f"HTTP {response.status}; request not retried",
+                                     status=response.status, wda_error=name)
+            result = decode_json(raw)
+            deadline.remaining()
+            if not isinstance(result, dict):
+                raise TransportError("HTTP response must be an object; outcome unknown; not retried")
+            return result
+        except TransportError:
+            if not answered_in_full:
+                self.connection.close()
+            raise
+        except (OSError, http.client.HTTPException, ValueError, RecursionError) as exc:
+            self.connection.close()
+            if isinstance(exc, ConnectionRefusedError):
+                raise NotSent(f"HTTP {type(exc).__name__}; nothing sent; not retried") from None
+            raise TransportError(f"HTTP {type(exc).__name__}; request outcome unknown; not retried") from None
+        finally:
+            with guard:
+                finished.set()
+                timer.cancel()
+            self._inflight.release()
+
+    def close(self):
+        self.connection.close()
+
+
+def peer_closed(sock):
+    """Whether an idle kept socket has anything to read, which on an idle HTTP connection means the server closed it
+    (or sent something unasked). Either way it can't carry the next request. A socket that can't be asked is closed."""
+    try:
+        if getattr(sock, "pending", lambda: 0)():
+            return True
+        # poll, not select: select refuses a descriptor numbered 1024 or more, which would read every socket as closed
+        # and bring back the per-request connections #2058 removed.
+        probe = select.poll()
+        probe.register(sock, select.POLLIN)
+        return bool(probe.poll(0))
+    except (OSError, ValueError):
+        return True
+
+
+def request_once(base_url, method, path, body=None, timeout=20):
+    client = HTTP(base_url)
+    try:
+        return client.request(method, path, body, timeout=timeout)
+    finally:
+        client.close()
+
+
+# A new connection per repeated read ran WebDriverAgent out of file descriptors in about 14 minutes (17 Oct).
+KEPT_MAX = 16
+CLOSED_WHILE_KEPT = ("RemoteDisconnected", "BrokenPipeError", "ConnectionResetError", "ConnectionAbortedError",
+                     "BadStatusLine")
+_kept = {}  # base url -> (HTTP, lock), oldest first
+_kept_lock = threading.Lock()
+
+
+def read_kept(base_url, path, timeout=2.0):
+    # Reads only: a kept connection the helper closed while idle is asked once more, which is safe for a GET.
+    base = base_url.rstrip("/")
+    deadline = Deadline(timeout)
+    with _kept_lock:
+        entry = _kept.get(base)
+        while entry is None and len(_kept) >= KEPT_MAX:
+            for address, (old_client, old_lock) in _kept.items():
+                if old_lock.acquire(blocking=False):
+                    del _kept[address]
+                    old_client.close()
+                    old_lock.release()
+                    break
+            else:
+                break
+        if entry is None and len(_kept) < KEPT_MAX:
+            entry = (HTTP(base), threading.Lock())
+            _kept[base] = entry
+        acquired = entry is not None and entry[1].acquire(blocking=False)
+        if acquired:
+            _kept.pop(base)
+            _kept[base] = entry
+    if not acquired:
+        return request_once(base, "GET", path, timeout=deadline.remaining())
+    client, lock = entry
+    try:
+        reused = client.connection.sock is not None
+        try:
+            return client.request("GET", path, timeout=deadline.remaining())
+        except TransportError as error:
+            if not reused or not any(name in str(error) for name in CLOSED_WHILE_KEPT):
+                raise
+            return client.request("GET", path, timeout=deadline.remaining())
+    finally:
+        lock.release()
+
+
+def wda_screenshot(wda_url, timeout=2):
+    try:
+        value = request_once(wda_url, "GET", "/screenshot", timeout=timeout).get("value")
+        return "data:image/png;base64," + value if isinstance(value, str) and value else None
+    except Exception:
+        return None

mobile_agent/triggers/__init__.py

@@ -0,0 +1 @@
+"""Notification triggers: a notification sends its text to a destination, runs a workflow or starts a task."""

mobile_agent/triggers/actions.py

@@ -0,0 +1,204 @@
+"""What one firing does: send to a destination, run a workflow or start a task, once and never retried."""
+
+import hashlib
+import logging
+import time
+import uuid
+
+from .. import harness_api, secret_filter
+from ..api_errors import APIError
+from ..notify_triggers.sources import iso
+from . import model
+
+log = logging.getLogger("mobster.triggers")
+
+TOPIC = "triggers"
+NOTIFICATION_MAX = 1200
+TEXT_MAX = 3000
+DESTINATION_GONE = ("The destination was removed, so nothing was sent. Choose another destination for this trigger "
+                    "in Connectors.")
+WORKFLOW_GONE = "The workflow was deleted, so it didn't run. Choose another workflow for this trigger."
+TRIGGER_GONE = "The trigger was removed before it could run."
+BUSY = "Another task was running, so this one didn't start. Mobster doesn't queue a notification's run."
+DUPLICATE = "Mobster already started a run for this notification."
+NO_OUTLETS = "Sending isn't available right now. Restart Mobster, then the next match sends."
+NO_WORKFLOWS = "Workflows aren't available right now. Restart Mobster, then the next match runs."
+WORKFLOW_SKIPS = {"skipped_busy": "The workflow was running and one run already waits, so this one didn't start.",
+                  "skipped_rate_limit": "The workflow already started 6 times in the last hour, "
+                  "so this one didn't start."}
+SKIP_CODES = {"run_active", "device_busy"}
+OFFLINE_CODES = {"device_unavailable", "shutting_down", "device_not_found"}
+LABELS = {"destination": "Send to a destination", "workflow": "Run a workflow", "task": "Start a task"}
+
+
+def request_key(trigger_id, notification):
+    """The Idempotency-Key for this trigger and notification: [A-Za-z0-9_.:-], at most 128 characters."""
+    digest = hashlib.sha256(f"{trigger_id}\n{notification.key}".encode()).hexdigest()[:32]
+    return f"trigger:{trigger_id}:{digest}"
+
+
+def event_body(trigger, notification, masked):
+    """What a destination receives."""
+    head = notification.title or notification.app
+    said = " ".join((notification.body or notification.subtitle or "").split())
+    text = f"{trigger['name']}: {head}" + (f": {said}" if said else "")
+    when = iso(notification.date)
+    fields = {"trigger": trigger["name"], "app": notification.app, "title": notification.title,
+              "body": notification.body or notification.subtitle, "date": when}
+    body = {"type": "notification.matched", **fields, "masked": bool(masked),
+            "runId": None, "status": "completed", "answer": text[:TEXT_MAX], "data": dict(fields), "reason": None,
+            "startedAt": when, "finishedAt": when,
+            "workflow": {"id": trigger["id"], "name": trigger["name"], "blanks": {}}, "text": text[:TEXT_MAX]}
+    from ..outlets import webhook
+    return webhook.masked(body)
+
+
+def fenced(notification):
+    """The notification as data, for the end of a workflow's steps or a task's words. Never longer than a run takes."""
+    lines = [f"App: {notification.app}", f"From: {'your iPhone' if notification.source == 'iphone' else 'this Mac'}"]
+    for label, value in (("Title", notification.title), ("Subtitle", notification.subtitle),
+                         ("Body", notification.body)):
+        if value:
+            lines.append(f"{label}: {value}")
+    text = secret_filter.redact("\n".join(lines))[:NOTIFICATION_MAX]
+    return harness_api.fence("The notification that started this", text)
+
+
+def who(trigger):
+    """The run field ``trigger``: who started it. The run view says "Started by trigger: <name>"."""
+    return {"id": trigger["id"], "name": trigger["name"]}
+
+
+class Firer:
+    def __init__(self, runtime, store, lookup, *, clock=time.time, publish=None):
+        self.runtime = runtime
+        self.store = store
+        self.lookup = lookup          # trigger id -> the saved trigger (dict) or None
+        self.clock = clock
+        self.publish = publish or getattr(runtime, "publish", None)
+
+    def act(self, rule, notification, masked=False):
+        trigger = self.lookup(rule.name)
+        if trigger is None:
+            return {"ok": False, "outcome": "skipped", "message": TRIGGER_GONE}
+        kind = trigger["action"]["kind"]
+        firing = {"id": uuid.uuid4().hex[:12], "trigger_id": trigger["id"], "trigger_name": trigger["name"],
+                  "app": trigger["app"], "at": self.clock(), "kind": kind, "outcome": "sending", "message": None,
+                  "run_id": None}
+        self.store.add_firing(firing)       # before anything is sent
+        try:
+            outcome, message, run_id = self._do(trigger, notification, masked)
+        except Exception as error:  # noqa: BLE001 -- one firing's failure never stops the watcher
+            log.exception("triggers: a firing failed unexpectedly")
+            outcome, message, run_id = "failed", f"The action failed unexpectedly ({type(error).__name__}).", None
+        self.store.update_firing(firing["id"], outcome=outcome, message=message, run_id=run_id)
+        self.announce(firing["id"], trigger, outcome, message, run_id)
+        return {"ok": outcome == "done", "outcome": outcome, "message": message, "runId": run_id}
+
+    def announce(self, firing_id, trigger, outcome, message, run_id=None, reason=None):
+        event = {"event": "trigger_fired" if outcome in ("done", "failed") else "trigger_skipped",
+                 "firingId": firing_id, "triggerId": trigger["id"], "trigger": trigger["name"], "app": trigger["app"],
+                 "action": trigger["action"]["kind"], "outcome": outcome, "message": message, "runId": run_id}
+        if reason:
+            event["reason"] = reason
+        if callable(self.publish):
+            self.publish(TOPIC, event)
+
+    def skip(self, rule_name, name, app, reason, message):
+        """A refusal before any action (rate limit, loop guard, duplicate, access lost): journaled and announced."""
+        trigger = self.lookup(rule_name) or {"id": rule_name, "name": name or "A removed trigger", "app": app or "",
+                                             "action": {"kind": "destination"}}
+        firing = {"id": uuid.uuid4().hex[:12], "trigger_id": trigger["id"], "trigger_name": trigger["name"],
+                  "app": trigger["app"], "at": self.clock(), "kind": trigger["action"]["kind"], "outcome": "skipped",
+                  "message": message, "run_id": None}
+        try:
+            self.store.add_firing(firing)
+        except Exception:  # noqa: BLE001 -- the event still goes out
+            log.warning("triggers: couldn't journal a skipped firing")
+        self.announce(firing["id"], trigger, "skipped", message, reason=reason)
+
+    def _do(self, trigger, notification, masked):
+        action = trigger["action"]
+        if action["kind"] == "destination":
+            return self._destination(trigger, notification, masked)
+        if action["kind"] == "workflow":
+            return self._workflow(trigger, notification)
+        return self._task(trigger, notification)
+
+    def _destination(self, trigger, notification, masked):
+        from ..outlets import service as outlet_service
+        service = outlet_service.service_for(self.runtime)
+        if service is None:
+            return "skipped", NO_OUTLETS, None
+        try:
+            row = service.store.destination(trigger["action"]["outletId"])
+            if row is None:
+                return "skipped", DESTINATION_GONE, None
+            outcome = service.send_event(row["id"], event_body(trigger, notification, masked))
+        except APIError as error:
+            if error.code == "not_found":
+                return "skipped", DESTINATION_GONE, None
+            return "failed", str(error), None
+        if outcome.ok:
+            return "done", f"Sent to {row['name']}.", None
+        return "failed", (outcome.message or "It didn't arrive.") + " Mobster doesn't send it again.", None
+
+    def _workflow(self, trigger, notification):
+        workflows = getattr(self.runtime, "workflows", None)
+        if workflows is None:
+            return "skipped", NO_WORKFLOWS, None
+        workflow_id = trigger["action"]["workflowId"]
+        try:
+            workflows.get(workflow_id)
+        except APIError as error:
+            if error.status == 404:
+                return "skipped", WORKFLOW_GONE, None
+            return "failed", str(error), None
+        data = {"app": notification.app, "title": notification.title,
+                "body": notification.body or notification.subtitle,
+                "receivedAt": round((notification.date or self.clock()) * 1000)}
+        try:
+            # The engine masks, cuts and fences the fields; each task it starts says "Started by trigger: <name>".
+            outcome = workflows.triggers.fire(workflow_id, data, started_by=who(trigger))
+        except APIError as error:
+            if error.code == "not_published":
+                return "skipped", str(error), None
+            return self._refused(error)
+        except ValueError as error:
+            return "skipped", str(error), None
+        if outcome is None:
+            return "skipped", DUPLICATE, None
+        if outcome == "started":
+            return "done", "Started the workflow.", None
+        if outcome == "queued":
+            return "done", "The workflow was running, so it starts when that run ends.", None
+        if outcome in WORKFLOW_SKIPS:
+            return "skipped", WORKFLOW_SKIPS[outcome], None
+        return self._refused(APIError("The workflow didn't start.", 409, outcome))
+
+    def _task(self, trigger, notification):
+        action = trigger["action"]
+        if not action.get("allowed"):
+            return "skipped", model.TASK_OFF, None
+        goal = action["text"] + "\n\n" + fenced(notification)
+        kwargs = {"extras": {"trigger": who(trigger)}, "origin": "trigger"}
+        if getattr(self.runtime, "fleet", None) is not None:
+            kwargs["default_device"] = "primary"
+        try:
+            created = self.runtime.create(None, goal, "live", request_key(trigger["id"], notification), **kwargs)
+        except APIError as error:
+            return self._refused(error)
+        except ValueError as error:
+            return "skipped", str(error), None
+        run, replayed = created
+        if replayed:
+            return "skipped", DUPLICATE, getattr(run, "id", None)
+        return "done", "Started a task. It asks before it acts.", getattr(run, "id", None)
+
+    @staticmethod
+    def _refused(error):
+        if error.code in SKIP_CODES:
+            return "skipped", BUSY, None
+        if error.code in OFFLINE_CODES:
+            return "skipped", f"{error} Nothing was started.", None
+        return "failed", str(error), None

mobile_agent/triggers/model.py

@@ -0,0 +1,146 @@
+"""A trigger's fields, checked. Every refusal is a sentence that says what to change."""
+
+import re
+
+from ..notify_triggers.rules import own_app
+
+NAME_MAX = 60
+WORDS_MAX = 10
+WORD_MAX = 40
+TASK_MAX = 1000
+MAX_TRIGGERS = 50
+SOURCES = ("iphone", "mac", "any")
+ACTIONS = ("destination", "workflow", "task")
+BUNDLE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,158}[A-Za-z0-9_]")
+ID = re.compile(r"[0-9a-f]{12}")
+FIELDS = {"name", "enabled", "app", "appName", "words", "source", "action"}
+ACTION_FIELDS = {"destination": {"kind", "outletId"}, "workflow": {"kind", "workflowId"},
+                 "task": {"kind", "text", "allowed"}}
+TASK_OFF = ("Starting a task from a notification is off for this trigger. Turn it on in the trigger's settings, "
+            "then it runs and asks before acting.")
+
+
+def name_of(value):
+    text = " ".join(value.split()) if isinstance(value, str) else ""
+    if not 1 <= len(text) <= NAME_MAX:
+        raise ValueError(f"Give the trigger a name of 1 to {NAME_MAX} characters.")
+    return text
+
+
+def app_of(value):
+    app = value.strip() if isinstance(value, str) else ""
+    if not BUNDLE.fullmatch(app):
+        raise ValueError("Choose the iPhone app this trigger watches.")
+    if own_app(app) or app.lower().startswith("app.mobster"):
+        raise ValueError("A trigger can't watch Mobster's own notifications, because the notification it sends "
+                         "would start it again.")
+    return app
+
+
+def words_of(value):
+    """The words, as a list of 0 to 10 short phrases. Text with commas or new lines splits into words."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        value = re.split(r"[,\n]", value)
+    if not isinstance(value, list) or not all(isinstance(word, str) for word in value):
+        raise ValueError("Words is a list of words or phrases to look for in the notification.")
+    words = []
+    for word in value:
+        word = " ".join(word.split())
+        if not word:
+            continue
+        if len(word) > WORD_MAX:
+            raise ValueError(f"A word or phrase is at most {WORD_MAX} characters.")
+        if word.casefold() not in [w.casefold() for w in words]:
+            words.append(word)
+    if len(words) > WORDS_MAX:
+        raise ValueError(f"Use at most {WORDS_MAX} words or phrases.")
+    return words
+
+
+def source_of(value):
+    if value is None:
+        return "iphone"
+    if value not in SOURCES:
+        raise ValueError("Source is iphone, mac or any.")
+    return value
+
+
+def enabled_of(value):
+    if value is None:
+        return False
+    if type(value) is not bool:
+        raise ValueError("Enabled is true or false.")
+    return value
+
+
+def action_of(value):
+    """The action, cleaned. It names its destination or workflow by id;
+    whether that exists is the service's to check."""
+    if not isinstance(value, dict) or value.get("kind") not in ACTIONS:
+        raise ValueError("Choose what the trigger does: send to a destination, run a workflow or start a task.")
+    kind = value["kind"]
+    extra = set(value) - ACTION_FIELDS[kind]
+    if extra:
+        raise ValueError(f"A {kind} action doesn't take {', '.join(sorted(extra))}.")
+    if kind == "destination":
+        if not isinstance(value.get("outletId"), str) or not ID.fullmatch(value["outletId"]):
+            raise ValueError("Choose a destination you saved in Connectors.")
+        return {"kind": kind, "outletId": value["outletId"]}
+    if kind == "workflow":
+        if not isinstance(value.get("workflowId"), str) or not ID.fullmatch(value["workflowId"]):
+            raise ValueError("Choose a saved workflow.")
+        return {"kind": kind, "workflowId": value["workflowId"]}
+    text = value.get("text")
+    if not isinstance(text, str) or not 1 <= len(text.strip()) <= TASK_MAX:
+        raise ValueError(f"Write the task in 1 to {TASK_MAX} characters.")
+    allowed = value.get("allowed", False)
+    if type(allowed) is not bool:
+        raise ValueError("Allowed is true or false.")
+    return {"kind": kind, "text": text.strip(), "allowed": allowed}
+
+
+def clean(body, current=None):
+    """The fields to save from a create or update body."""
+    if not isinstance(body, dict):
+        raise ValueError("A trigger has a name, an app and an action.")
+    extra = set(body) - FIELDS
+    if extra:
+        raise ValueError(f"A trigger doesn't take {', '.join(sorted(extra))}.")
+    out = dict(current or {})
+    if current is None or "name" in body:
+        out["name"] = name_of(body.get("name"))
+    if current is None or "app" in body:
+        out["app"] = app_of(body.get("app"))
+    if "appName" in body or current is None:
+        name = body.get("appName")
+        if name is not None and (not isinstance(name, str) or len(name.strip()) > 80):
+            raise ValueError("The app's name is at most 80 characters.")
+        out["appName"] = " ".join(name.split()) if isinstance(name, str) and name.strip() else None
+    if current is None or "words" in body:
+        out["words"] = words_of(body.get("words"))
+    if current is None or "source" in body:
+        out["source"] = source_of(body.get("source"))
+    if current is None or "enabled" in body:
+        out["enabled"] = enabled_of(body.get("enabled"))
+    if current is None or "action" in body:
+        action = action_of(body.get("action"))
+        # "Start a task" is off until the person turns it on for this trigger. A change that leaves "allowed" out keeps
+        # what was saved, unless the task's words changed: new words are off until they are turned on again.
+        before = (current or {}).get("action") or {}
+        if action["kind"] == "task" and "allowed" not in body["action"]:
+            same = before.get("kind") == "task" and before.get("text") == action["text"]
+            action["allowed"] = bool(before.get("allowed")) if same else False
+        out["action"] = action
+    return out
+
+
+def word_pattern(words, regex=None):
+    """The compiled search for a trigger"""
+    if regex:
+        return re.compile(regex, re.IGNORECASE | re.MULTILINE)
+    if not words:
+        return None
+    alternatives = "|".join(re.escape(" ".join(word.split())).replace(r"\ ", r"\s+") for word in words)
+    return re.compile(r"(?<!\w)(?:" + alternatives + r")(?!\w)", re.IGNORECASE)

mobile_agent/triggers/register.py

@@ -0,0 +1,29 @@
+"""Track ``triggers``' registrations (tracks.load calls ``register(api)`` once per process, staged)."""
+
+import re
+
+from . import routes, service
+
+ID = re.compile(r"[0-9a-f]{12}")
+
+
+def validate_trigger(value, runtime):
+    """The run field: {"id": 12 hex characters, "name": 1 to 60 characters}."""
+    if not isinstance(value, dict) or set(value) != {"id", "name"}:
+        raise ValueError('trigger is {"id", "name"}')
+    if not isinstance(value["id"], str) or not ID.fullmatch(value["id"]):
+        raise ValueError("A trigger's id is 12 hex characters")
+    if not isinstance(value["name"], str) or not 1 <= len(value["name"].strip()) <= 60:
+        raise ValueError("A trigger's name is 1 to 60 characters")
+    return {"id": value["id"], "name": " ".join(value["name"].split())}
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from .. import full_disk_access, journal
+    from . import store
+    journal.register_schema(store.SCHEMA, store.VERSION, store.migrate)
+    api.register_run_field("trigger", validate_trigger, public=True)
+    api.register_service(service.start, service.close)
+    routes.register_routes()
+    full_disk_access.register_route()