mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/outlets/webhook.py

@@ -0,0 +1,316 @@
+"""A webhook destination's address, the JSON a run sends it, the signature, and one POST."""
+
+import base64
+import datetime
+import hashlib
+import hmac
+import io
+import ipaddress
+import json
+import time
+from urllib.parse import urlsplit
+
+from .. import secret_filter
+from . import net
+
+TIMEOUT = 10.0
+URL_MAX = 2000
+SECRET_MAX = 200
+NAME_MAX = 60
+ANSWER_MAX = 20_000
+TEXT_MAX = 3000
+SCREENSHOT_SIDE = 1280
+USER_AGENT = "Mobster-Webhooks/1"
+# The run statuses that finished the task: no reason goes with them.
+DONE = frozenset({"completed", "completed_unverified", "user_condition_met"})
+LOCAL_SUFFIXES = (".local", ".localhost", ".lan", ".home.arpa", ".internal")
+
+
+class AddressError(ValueError):
+    """Why an address can't take results, in one sentence that never repeats the address."""
+
+
+def _literal(host):
+    try:
+        return ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return None
+
+
+def _private(host):
+    """This Mac or a private network: localhost, a name with no dot or a .local one, or a loopback, private or
+    link-local address."""
+    if host == "localhost" or host.endswith(LOCAL_SUFFIXES) or ("." not in host and ":" not in host):
+        return True
+    address = _literal(host)
+    if address is None:
+        return False
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        address = address.ipv4_mapped
+    return address.is_loopback or address.is_private or address.is_link_local
+
+
+def validate_url(value):
+    """``value`` trimmed, when results may go there; AddressError otherwise."""
+    text = value.strip() if isinstance(value, str) else ""
+    if not text:
+        raise AddressError("Paste the webhook's address.")
+    if len(text) > URL_MAX or any(ord(c) < 33 or ord(c) == 127 for c in text):
+        raise AddressError("That address isn't a web address.")
+    parts = urlsplit(text)
+    scheme = parts.scheme.lower()
+    if scheme not in ("https", "http"):
+        raise AddressError("Use an address that starts with https://.")
+    if parts.username or parts.password:
+        raise AddressError("Put the secret in Secret, not in the address.")
+    host = (parts.hostname or "").rstrip(".").lower()
+    if not host:
+        raise AddressError("That address has no host.")
+    try:
+        parts.port
+    except ValueError:
+        raise AddressError("That address has a port Mobster can't use.") from None
+    if scheme == "http" and not _private(host):
+        raise AddressError("Use https:// for an address on the internet. http:// works for this Mac and your own "
+                           "network.")
+    return text
+
+
+def hint(url):
+    """What the app shows of an address: its scheme, host and first path segment ("https://hooks.zapier.com/hooks/…").
+    The rest often carries the address's own key."""
+    parts = urlsplit(url)
+    host = parts.hostname or ""
+    if ":" in host:
+        host = f"[{host}]"
+    if parts.port:
+        host += f":{parts.port}"
+    segments = [s for s in parts.path.split("/") if s]
+    shown = f"{parts.scheme.lower()}://{host}"
+    if segments:
+        first = segments[0] if len(segments[0]) <= 24 else segments[0][:24] + "…"
+        shown += "/" + first + ("/…" if len(segments) > 1 or parts.query else "")
+    elif parts.query:
+        shown += "/…"
+    return shown
+
+
+host_of = net.host_of
+
+
+def validate_secret(value):
+    if value is None or value == "":
+        return None
+    if (not isinstance(value, str) or not 8 <= len(value) <= SECRET_MAX
+            or any(ord(c) < 33 or ord(c) == 127 for c in value)):
+        raise ValueError("A secret is 8 to 200 characters with no spaces.")
+    return value
+
+
+def validate_name(value, example="My server"):
+    """The destination's name, spaces folded. ``example``: a name for its kind, for the error (kinds.Kind.example)."""
+    text = " ".join(value.split()) if isinstance(value, str) else ""
+    if not 1 <= len(text) <= NAME_MAX:
+        raise ValueError(f"Name the destination in 1 to {NAME_MAX} characters, like {example}.")
+    return text
+
+
+def iso(seconds):
+    if not isinstance(seconds, (int, float)):
+        return None
+    return datetime.datetime.fromtimestamp(seconds, datetime.timezone.utc).isoformat(timespec="seconds").replace(
+        "+00:00", "Z")
+
+
+def masked(value, depth=0):
+    """``value`` with secret_filter.redact over every string inside it (keys too). Depth past 20 becomes None."""
+    if depth > 20:
+        return None
+    if isinstance(value, str):
+        return secret_filter.redact(value)
+    if isinstance(value, dict):
+        return {secret_filter.redact(str(k)): masked(v, depth + 1) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [masked(v, depth + 1) for v in value]
+    if isinstance(value, bool) or value is None or isinstance(value, (int, float)):
+        return value
+    return secret_filter.redact(str(value))
+
+
+def answer_of(summary):
+    """The run's whole answer as text: the answer it wrote in full, else its text data, else its headline."""
+    for key in ("full_answer", "data", "answer"):
+        value = summary.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()[:ANSWER_MAX]
+    return None
+
+
+def data_of(summary):
+    """The structured data: an output schema's (or a format's) data once it was validated; None for a text answer."""
+    data = summary.get("data")
+    if summary.get("data_status") == "validated" and data is not None and not isinstance(data, str):
+        return data
+    return None
+
+
+def line_of(title, status, answer, reason):
+    """``text``: the answer; without one, Done or why it couldn't finish."""
+    if answer:
+        said = answer
+    elif status in DONE:
+        said = "Done."
+    else:
+        said = f"Couldn't finish. {reason}" if reason else "Couldn't finish."
+    text = f"{title}: {' '.join(said.split())}"
+    return text if len(text) <= TEXT_MAX else text[:TEXT_MAX - 1] + "…"
+
+
+def payload(run, workflow=None, screenshot=None):
+    """The body for ``run``: an object as the module docstring shows."""
+    summary = run.summary if isinstance(getattr(run, "summary", None), dict) else {}
+    status = getattr(run, "status", None) or summary.get("status") or "error"
+    answer = masked(answer_of(summary))
+    reason = summary.get("reason") if status not in DONE else None
+    reason = masked(" ".join(reason.split())) if isinstance(reason, str) and reason.strip() else None
+    flow = None
+    if isinstance(workflow, dict) and workflow.get("name"):
+        blanks = workflow.get("blanks") if isinstance(workflow.get("blanks"), dict) else {}
+        flow = {"id": workflow.get("id"), "name": masked(workflow["name"]), "blanks": masked(blanks)}
+    body = {"type": "run.finished", "runId": run.id, "status": status, "answer": answer,
+            "data": masked(data_of(summary)), "reason": reason, "startedAt": iso(getattr(run, "created_at", None)),
+            "finishedAt": iso(getattr(run, "finished_at", None)), "workflow": flow,
+            "text": line_of(f"Mobster › {flow['name']}" if flow else "Mobster", status, answer, reason)}
+    if screenshot:
+        body["screenshot"] = {"contentType": "image/jpeg", "base64": base64.b64encode(screenshot).decode()}
+    return body
+
+
+def started_payload(run, workflow=None):
+    """run.started: which run, when, and its workflow when it came from one. No task words."""
+    flow = _flow(workflow)
+    title = f"Mobster › {flow['name']}" if flow else "Mobster"
+    return {"type": "run.started", "runId": run.id, "startedAt": iso(getattr(run, "created_at", None)),
+            "workflow": flow, "text": f"{title}: a task started."}
+
+
+# approval_requested kinds (server.request_approval) and what a needs_you event calls them.
+NEED_KINDS = {"action": "approval", "commit": "approval", "proposals": "approval", "clarify": "question",
+              "loop": "question", "question": "question", "plan": "plan"}
+QUESTION_MAX = 300
+
+
+def needs_payload(run, event, workflow=None, now=None):
+    """needs_you: the run is waiting for an answer in the app. ``event`` is its approval_requested event."""
+    now = time.time() if now is None else now
+    flow = _flow(workflow)
+    # What the card asks, masked: never the message, a typed answer or anything the card doesn't say.
+    asked = " ".join(str(event.get("title") or event.get("label") or "").split())[:QUESTION_MAX]
+    question = secret_filter.redact(asked) or "Mobster needs your answer in the app."
+    title = f"Mobster › {flow['name']}" if flow else "Mobster"
+    return {"type": "needs_you", "runId": run.id, "kind": NEED_KINDS.get(event.get("kind") or "action", "approval"),
+            "question": question, "askedAt": iso(now), "workflow": flow,
+            "text": f"{title} needs you: {question}"[:TEXT_MAX]}
+
+
+def _flow(workflow):
+    if isinstance(workflow, dict) and workflow.get("name"):
+        blanks = workflow.get("blanks") if isinstance(workflow.get("blanks"), dict) else {}
+        return {"id": workflow.get("id"), "name": masked(workflow["name"]), "blanks": masked(blanks)}
+    return None
+
+
+def test_payload(now=None):
+    now = time.time() if now is None else now
+    return {"type": "test", "runId": None, "status": "completed",
+            "answer": "This is a test from Mobster. A finished task's answer goes here.", "data": None, "reason": None,
+            "startedAt": iso(now), "finishedAt": iso(now), "workflow": None,
+            "text": "Mobster: this is a test. Results from your tasks will arrive here."}
+
+
+def slack_text(text):
+    """Slack's escaping for its text field: &, < and > only."""
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def encode_body(url, body):
+    """The bytes to send. Slack's incoming webhooks read ``text`` as their own markup, so it's escaped for them."""
+    host = host_of(url)
+    if host == "hooks.slack.com" or host.endswith(".slack.com"):
+        body = {**body, "text": slack_text(body.get("text") or "")}
+    return json.dumps(body, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")
+
+
+def signature(secret, timestamp, data):
+    """v1: HMAC-SHA256 with ``secret`` over ``<timestamp>.<body>``, in hex."""
+    message = str(int(timestamp)).encode() + b"." + data
+    return hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
+
+
+def headers(event, delivery_id, data, secret=None, timestamp=None):
+    timestamp = int(time.time() if timestamp is None else timestamp)
+    out = {"Content-Type": "application/json", "User-Agent": USER_AGENT, "Mobster-Event": event,
+           "Mobster-Delivery": delivery_id, "Mobster-Timestamp": str(timestamp)}
+    if secret:
+        out["Mobster-Signature"] = f"t={timestamp},v1={signature(secret, timestamp, data)}"
+    return out
+
+
+def screenshot_of(run, frames=None):
+    """The run's last screen as JPEG bytes (at most SCREENSHOT_SIDE px), or None: the final full screenshot while the
+    app still has it, else the last step's saved frame."""
+    image = getattr(run, "image", None)
+    if isinstance(image, str) and image.startswith("data:image/") and "," in image:
+        try:
+            raw = base64.b64decode(image.split(",", 1)[1])
+            from PIL import Image
+            picture = Image.open(io.BytesIO(raw)).convert("RGB")
+            picture.thumbnail((SCREENSHOT_SIDE, SCREENSHOT_SIDE))
+            out = io.BytesIO()
+            picture.save(out, "JPEG", quality=80)
+            return out.getvalue()
+        except Exception:  # noqa: BLE001 -- the step frame below, or none
+            pass
+    if frames is None:
+        return None
+    for event in reversed(list(getattr(run, "events", None) or ())):
+        frame = event.get("frameId") if isinstance(event, dict) else None
+        if isinstance(frame, str):
+            try:
+                data = frames.get(run.id, frame)
+            except Exception:  # noqa: BLE001
+                data = None
+            if data:
+                return data
+    return None
+
+
+class Outcome:
+    """What one try came to: ``ok``, ``retry`` (worth another try), the HTTP ``status`` and a ``message``. ``unsent``:
+    the try surely never reached the destination, so another can't make a duplicate."""
+
+    def __init__(self, ok, retry, status=None, message=None, unsent=False):
+        self.ok, self.retry, self.status, self.message, self.unsent = ok, retry, status, message, unsent
+
+    def __repr__(self):
+        return f"Outcome(ok={self.ok}, retry={self.retry}, status={self.status}, message={self.message!r})"
+
+
+def post(url, data, request_headers, timeout=TIMEOUT, connect=net.connection):
+    """POST ``data`` to ``url`` once. Never raises; never names the address beyond its host."""
+    try:
+        reply = net.call("POST", url, data, request_headers, timeout, connect, read_limit=4096)
+    except net.NetError as error:
+        return Outcome(False, error.retry, None, error.message, unsent=error.unsent)
+    return judge(reply.status)
+
+
+def judge(status):
+    if 200 <= status < 300:
+        return Outcome(True, False, status, None)
+    if 300 <= status < 400:
+        return Outcome(False, False, status, f"The address answered {status}, a redirect. Use the address it points "
+                                             "to.")
+    if status in (408, 425, 429) or status >= 500:
+        return Outcome(False, True, status, f"The address answered {status}.")
+    return Outcome(False, False, status, f"The address answered {status}. Check it in Settings › Connectors.")

mobile_agent/output_contract.py

@@ -0,0 +1,141 @@
+"""Result presentation contracts, and the bounded JSON Schema subset a task's output may declare.
+
+The schema subset is safe on purpose: it never fetches references, executes regular expressions or infers missing
+values.
+"""
+
+import json
+
+from .transport import decode_json
+
+KEYWORDS = frozenset({"$schema", "type", "properties", "required", "additionalProperties",
+    "items", "minItems", "maxItems", "uniqueItems", "minLength", "maxLength", "minimum",
+    "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "enum", "const",
+    "title", "description"})
+TYPES = frozenset({"object", "array", "string", "number", "integer", "boolean", "null"})
+
+
+def bounded_json(value, *, max_bytes=32000, max_nodes=2000, max_depth=12):
+    pending, count = [(value, 0)], 0
+    while pending:
+        node, depth = pending.pop()
+        count += 1
+        if count > max_nodes or depth > max_depth:
+            raise ValueError("JSON exceeds structural limits")
+        if type(node) is dict:
+            if any(not isinstance(key, str) for key in node):
+                raise ValueError("JSON object keys must be strings")
+            pending.extend((child, depth + 1) for child in node.values())
+        elif type(node) is list:
+            pending.extend((child, depth + 1) for child in node)
+        elif node is not None and type(node) not in (str, int, float, bool):
+            raise ValueError("Result contains a non-JSON value")
+    try:
+        wire = json.dumps(value, allow_nan=False, sort_keys=True, separators=(",", ":"))
+        if len(wire.encode()) > max_bytes:
+            raise ValueError("JSON exceeds byte limit")
+        return decode_json(wire)
+    except (TypeError, OverflowError, UnicodeError):
+        raise ValueError("Invalid JSON value") from None
+
+
+def validate_schema(schema):
+    schema = bounded_json(schema, max_bytes=16000, max_nodes=500, max_depth=12)
+    if not isinstance(schema, dict):
+        raise ValueError("Output schema must be a JSON Schema object")
+    try:
+        from jsonschema import Draft202012Validator
+    except ImportError:
+        raise ValueError("Structured output requires mobile_agent/requirements.txt") from None
+
+    def inspect(node, depth=0):
+        if not isinstance(node, dict) or depth > 6 or set(node) - KEYWORDS:
+            raise ValueError("Unsupported output schema keyword or nesting depth")
+        declared = node.get("type")
+        kinds = declared if isinstance(declared, list) else [declared]
+        if not kinds or any(not isinstance(kind, str) or kind not in TYPES for kind in kinds):
+            raise ValueError("Every output schema node requires an explicit supported type")
+        if "$schema" in node and node["$schema"] != "https://json-schema.org/draft/2020-12/schema":
+            raise ValueError("Only JSON Schema Draft 2020-12 is supported")
+        if "object" in kinds:
+            properties = node.get("properties", {})
+            if (not isinstance(properties, dict) or len(properties) > 40
+                    or node.get("additionalProperties") is not False):
+                raise ValueError("Objects require bounded properties and additionalProperties:false")
+            required = node.get("required", [])
+            if (not isinstance(required, list)
+                    or any(not isinstance(key, str) or key not in properties for key in required)):
+                raise ValueError("Required properties must have a defined schema")
+            for child in properties.values():
+                inspect(child, depth + 1)
+        elif "properties" in node or "required" in node or "additionalProperties" in node:
+            raise ValueError("Object keywords require object type")
+        if "array" in kinds:
+            if "items" not in node:
+                raise ValueError("Arrays require a bounded item schema")
+            inspect(node["items"], depth + 1)
+            if type(node.get("maxItems")) is not int or not 0 <= node["maxItems"] <= 100:
+                raise ValueError("Arrays require maxItems between 0 and 100")
+        elif "items" in node:
+            raise ValueError("Array items require array type")
+        if "enum" in node and (not isinstance(node["enum"], list) or not 1 <= len(node["enum"]) <= 100):
+            raise ValueError("Enum exceeds supported bounds")
+
+    inspect(schema)
+    try:
+        Draft202012Validator.check_schema(schema)
+    except Exception:
+        raise ValueError("Invalid JSON Schema") from None
+    return schema
+
+
+
+FORMATS = frozenset({"text", "json", "yaml", "csv", "markdown"})
+SCALAR_TYPES = frozenset({"string", "number", "integer", "boolean", "null"})
+
+
+def validate_format(output_format):
+    """An actual result format; Auto is a request policy, never a serializer."""
+    if not isinstance(output_format, str) or output_format not in FORMATS:
+        raise ValueError("Choose Text, JSON, YAML, CSV, or Markdown output")
+
+
+def validate_output(output_format, schema):
+    if output_format == "auto":
+        if schema is not None:
+            raise ValueError("Choose a structured format to supply a custom schema")
+        return None
+    validate_format(output_format)
+    if output_format == "text" and schema is not None:
+        raise ValueError("Choose a structured format to supply a custom schema")
+    schema = validate_schema(schema) if schema is not None else None
+    if output_format != "csv" or schema is None:
+        return schema
+    return _validate_csv_shape(schema)
+
+
+def validate_automatic_schema(output_format, schema):
+    """A model-selected schema is mandatory and bounded, including plain-text answers."""
+    validate_format(output_format)
+    schema = validate_schema(schema)
+    if output_format == "csv":
+        return _validate_csv_shape(schema)
+    if output_format == "text" and schema["type"] != "string":
+        # Automatic text is one string or one flat object; a table is CSV-only.
+        if schema["type"] == "array":
+            raise ValueError("Text requires a string or a flat object with named columns")
+        return _validate_csv_shape(schema)
+    return schema
+
+
+def _validate_csv_shape(schema):
+    row = schema.get("items") if schema.get("type") == "array" else schema
+    if (not isinstance(row, dict) or row.get("type") != "object"
+            or row.get("additionalProperties") is not False or not row.get("properties")):
+        raise ValueError("CSV requires a flat object or an array of flat objects with named columns")
+    for column in row["properties"].values():
+        declared = column["type"]
+        kinds = declared if isinstance(declared, list) else [declared]
+        if any(kind not in SCALAR_TYPES for kind in kinds):
+            raise ValueError("CSV columns must be scalar values, not nested objects or arrays")
+    return schema

mobile_agent/owner_presence.py

@@ -0,0 +1,211 @@
+"""Whether the person who owns an iPhone is using it, so Mobster never grabs it from them."""
+
+import threading
+import time
+
+POLL_INTERVAL_S = 15.0     # between read-only polls of one phone
+READ_TIMEOUT_S = 3.0
+ACTION_QUIET_S = 30.0      # a change this soon after a Mobster action is Mobster's own
+OWNER_QUIET_S = 120.0      # owner_active ends after this long with no change
+IDLE_AFTER_S = 300.0       # a phone first seen, or unchanged, is idle after this long
+IDLE_RELEASE_S = 120.0     # idle for this long: stop live view, prewarm and the awake hold
+
+OWNER_ACTIVE_REFUSAL = ("You're using your iPhone right now, so Mobster didn't start this task. "
+                        "No action was taken. It can start once you put the phone down.")
+
+
+class OwnerPresence:
+    """One phone's presence. ``observe`` is the only input besides ``note_mobster_action``/``run_started``."""
+
+    def __init__(self, clock=time.time):
+        self.clock = clock
+        self.lock = threading.Lock()
+        self.state, self.since = "unknown", self._ms(clock())
+        self.baseline = None          # (locked, front) at the last read
+        self.first_seen = None
+        self.last_change = None
+        self.last_action = None
+        self.holding = False
+        self.idle_since = None
+        self.released = False         # idle release already done for this idle stretch
+
+    @staticmethod
+    def _ms(seconds):
+        return int(seconds * 1000)
+
+    def _set(self, state, now):
+        if state != self.state:
+            self.state, self.since = state, self._ms(now)
+            self.released = False
+            self.idle_since = now if state == "idle" else None
+
+    # -- inputs -----------------------------------------------------------------------------------
+
+    def note_mobster_action(self, now=None):
+        """Mobster acted on the phone (a run's step, an MCP tap, manual control): a change soon after is its own."""
+        with self.lock:
+            self.last_action = self.clock() if now is None else now
+
+    def run_started(self, now=None):
+        with self.lock:
+            now = self.clock() if now is None else now
+            self.holding, self.last_action = True, now
+            self._set("mobster", now)
+
+    def run_finished(self, locked=None, front=None, now=None):
+        """The run ended. What the phone shows now is Mobster's doing, not the owner's: it becomes the baseline."""
+        with self.lock:
+            now = self.clock() if now is None else now
+            self.holding, self.last_action = False, now
+            if locked is not None or front is not None:
+                self.baseline = (locked, front)
+            self.last_change = now
+            self._set("idle", now)
+
+    def observe(self, *, held=False, ok=True, locked=None, front=None, now=None):
+        with self.lock:
+            now = self.clock() if now is None else now
+            if held:
+                self.holding, self.last_action = True, now
+                self._set("mobster", now)
+                return self.state
+            if self.holding:
+                # A hold just ended without run_finished (another process's lease): treat it as a finished run.
+                self.holding, self.last_action = False, now
+                if ok:
+                    self.baseline, self.last_change = (locked, front), now
+                self._set("idle", now)
+                return self.state
+            if not ok or not isinstance(locked, bool):
+                self._set("unknown", now)
+                return self.state
+            reading = (locked, front)
+            if self.first_seen is None:
+                self.first_seen = now
+            if self.baseline is None:
+                self.baseline, self.last_change = reading, now
+            elif reading != self.baseline:
+                self.baseline = reading
+                # Only a person unlocks a phone or switches its app. The phone locking itself (auto-lock) is not use.
+                if locked is False:
+                    self.last_change = now
+                    own = self.last_action is not None and now - self.last_action <= ACTION_QUIET_S
+                    if not own:
+                        self._set("owner_active", now)
+                        return self.state
+            quiet = now - (self.last_change if self.last_change is not None else self.first_seen)
+            if self.state == "owner_active":
+                if quiet >= OWNER_QUIET_S:
+                    self._set("idle", now)
+            elif quiet >= IDLE_AFTER_S or self.state == "idle":
+                self._set("idle", now)
+            else:
+                self._set("unknown", now)
+            return self.state
+
+    # -- outputs ----------------------------------------------------------------------------------
+
+    def is_owner_active(self):
+        with self.lock:
+            return self.state == "owner_active"
+
+    def should_release(self, now=None):
+        with self.lock:
+            now = self.clock() if now is None else now
+            if self.state != "idle" or self.released or self.idle_since is None:
+                return False
+            if now - self.idle_since < IDLE_RELEASE_S:
+                return False
+            self.released = True
+            return True
+
+    def snapshot(self):
+        with self.lock:
+            return {"state": self.state, "since": self.since}
+
+
+# -- the reads ---------------------------------------------------------------------------------------
+
+
+def read_phone(wda_url, timeout=READ_TIMEOUT_S):
+    """(ok, locked, front): the two read-only sessionless reads. Never raises."""
+    from .transport import read_kept  # the helper's kept connection: a connection a poll ran WDA out of descriptors
+    try:
+        locked = read_kept(wda_url, "/wda/locked", timeout=timeout).get("value")
+        front = None
+        if locked is False:
+            value = read_kept(wda_url, "/wda/activeAppInfo", timeout=timeout).get("value")
+            bundle = value.get("bundleId") if isinstance(value, dict) else None
+            front = bundle if isinstance(bundle, str) and bundle else None
+        return isinstance(locked, bool), locked, front
+    except Exception:  # noqa: BLE001 -- an unanswered phone is "unknown", never an error
+        return False, None, None
+
+
+def lease_held(wda_url):
+    """Whether a Mobster process holds this phone's lease now (taken and let go at once). Fails to True."""
+    from .journal import Lease
+    try:
+        lease = Lease.device(wda_url.rstrip("/"), wait=0)
+    except Exception:  # noqa: BLE001 -- can't tell: treat it as held, never as free
+        return True
+    lease.close()
+    return False
+
+
+class Poller:
+    """Polls one phone's presence lazily: at most every POLL_INTERVAL_S, and never reads while a run holds it."""
+
+    def __init__(self, presence, wda_url, busy=lambda: False, reader=read_phone, lease=lease_held,
+                 monotonic=time.monotonic):
+        self.presence, self.wda_url, self.busy = presence, wda_url, busy
+        self.reader, self.lease, self.monotonic = reader, lease, monotonic
+        self.polled_at = None
+
+    def poll(self, force=False):
+        now = self.monotonic()
+        if not force and self.polled_at is not None and now - self.polled_at < POLL_INTERVAL_S:
+            return self.presence.snapshot()
+        self.polled_at = now
+        try:
+            held = bool(self.busy()) or self.lease(self.wda_url)
+        except Exception:  # noqa: BLE001
+            held = True
+        from .wda.watchdog import tracker
+        # an MCP tap or a manual-control gesture is Mobster's, not the owner's
+        mine = tracker.last_action_at(self.wda_url)
+        if mine is not None:
+            self.presence.note_mobster_action(mine)
+        if held:
+            self.presence.observe(held=True)
+        else:
+            ok, locked, front = self.reader(self.wda_url)
+            self.presence.observe(ok=ok, locked=locked, front=front)
+        return self.presence.snapshot()
+
+
+# -- a registry, so a guard or an MCP tool finds a phone's presence from its WDA address --------------
+
+_registry = {}
+_registry_lock = threading.Lock()
+
+
+def register(wda_url, presence):
+    with _registry_lock:
+        _registry[(wda_url or "").rstrip("/")] = presence
+
+
+def presence_for(wda_url):
+    with _registry_lock:
+        return _registry.get((wda_url or "").rstrip("/"))
+
+
+def is_owner_active(wda_url):
+    """Whether the owner is using the phone at ``wda_url``. False when nothing tracks it."""
+    presence = presence_for(wda_url)
+    return bool(presence is not None and presence.is_owner_active())
+
+
+def forget(wda_url):
+    with _registry_lock:
+        _registry.pop((wda_url or "").rstrip("/"), None)