mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/accounts/context.py

@@ -0,0 +1,80 @@
+"""A profile's notes for the agent, and its values in a task's placeholders (the feature is Profiles; see screen.py)."""
+
+import re
+
+from .. import harness_api
+from .store import display
+
+ORDER = 15
+MAX_CHARS = 4000
+PLACEHOLDER = re.compile(r"(?<!\{)\{\s*([A-Za-z][A-Za-z0-9_ -]{0,39}?)\s*\}(?!\})")
+
+
+def values(account):
+    """{lowercase name: value} a placeholder may name."""
+    out = {"handle": "@" + account["handle"]}
+    if account.get("signature"):
+        out["signature"] = account["signature"]
+    links = account.get("links") or []
+    if links:
+        out["link"] = links[0]["url"]
+        for link in links:
+            out.setdefault(re.sub(r"\s+", "_", link["label"].strip().casefold()), link["url"])
+            out.setdefault(link["label"].strip().casefold(), link["url"])
+    for name, value in (account.get("variables") or {}).items():
+        if value:
+            out.setdefault(name, value)
+    return out
+
+
+def fill(goal, account):
+    """``goal`` with the profile's values in its placeholders: {handle}, {signature}, {link}, link labels, variables."""
+    known = values(account)
+
+    def put(match):
+        name = " ".join(match.group(1).split()).casefold()
+        value = known.get(name, known.get(name.replace(" ", "_")))
+        return value if value is not None else match.group(0)
+
+    return PLACEHOLDER.sub(put, goal or "")
+
+
+def text(account):
+    lines = [f"You act as {display(account)} in this task. Everything you post, reply, comment or send there goes out "
+             f"as @{account['handle']}.",
+             f"Before the first post, reply, comment or message in {account['app']['name']}, open its own profile "
+             "screen (the one with Edit profile) and use CHECK_PROFILE. If another profile is signed in, stop: "
+             "Mobster never switches profiles."]
+    if account.get("notes"):
+        lines.append("How this profile sounds (the person's notes): " + account["notes"])
+    if account.get("signature"):
+        lines.append("Signature: " + account["signature"])
+    for link in account.get("links") or ():
+        lines.append(f"Link, {link['label']}: {link['url']}")
+    for name, value in (account.get("variables") or {}).items():
+        if value:
+            lines.append(f"{name}: {value}")
+    return "\n".join(lines)[:MAX_CHARS]
+
+
+class AccountProvider:
+    key = "account"
+    max_chars = MAX_CHARS
+
+    def __init__(self, account):
+        self.account = account
+
+    def blocks(self, ctx):
+        return (harness_api.ContextBlock(key=self.key, title="The profile", text=text(self.account), stable=True),)
+
+    def turn_blocks(self, ctx, turn):
+        return ()
+
+
+def provider(ctx):
+    """The profile context captured when this run was admitted."""
+    account = (ctx.extras or {}).get("account")
+    if not isinstance(account, dict) or not account.get("id"):
+        return None
+    snapshot = getattr(ctx, "account_context", None)
+    return AccountProvider(snapshot) if snapshot is not None else None

mobile_agent/accounts/mcp.py

@@ -0,0 +1,55 @@
+"""The ``list_profiles`` MCP tool, and ``list_accounts``, its deprecated alias (provider ``accounts``, seam S10)."""
+
+from ..threads.client import Client, NoService, ServiceError
+
+NO_SERVICE = "Open Mobster or run `mobster serve` so your agent can read your profiles."
+EMPTY = "The user hasn't mapped any profiles yet. They add them in Mobster, Settings › Profiles."
+SCHEMA = {"type": "object", "properties": {}, "required": [], "additionalProperties": False}
+TOOL = "list_profiles"
+ALIAS = "list_accounts"
+
+
+class AccountsProvider:
+    name = "accounts"
+
+    def __init__(self, connect=None):
+        self._connect = connect or (lambda: Client.connect(origin="mcp"))
+
+    def definitions(self, toolset):
+        return [{"name": TOOL, "title": "List profiles",
+                 "description": "The user's social media profiles mapped in Mobster (handle, app and the iPhone each "
+                                "is signed in on). Pass one to phone_task as profile, such as "
+                                "\"@getmobster on Instagram\".",
+                 "inputSchema": dict(SCHEMA)},
+                {"name": ALIAS, "title": "List profiles (old name)",
+                 "description": "Deprecated: use list_profiles, which answers the same list. Kept so clients that "
+                                "learned this name keep working.",
+                 "inputSchema": dict(SCHEMA)}]
+
+    def annotations(self):
+        from ..mcp_server.tools import READ_ONLY
+        return {TOOL: READ_ONLY, ALIAS: READ_ONLY}
+
+    def instructions(self):
+        return ("phone_task takes profile (from list_profiles): the task runs on that profile's iPhone, and Mobster "
+                "confirms the profile on screen before it posts or sends.")
+
+    def call(self, name, arguments, call, toolset):
+        from ..mcp_server.protocol import ToolResult
+        from ..mcp_server.tools import ToolError
+        try:
+            client = self._connect()
+            answer = client.call("GET", "/api/accounts")
+        except (NoService, ServiceError) as error:
+            raise ToolError(NO_SERVICE if isinstance(error, NoService) else str(error)) from None
+        key, field = ("accounts", "account") if name == ALIAS else ("profiles", "profile")
+        rows = [{"id": a.get("id"), field: a.get("display"), "handle": "@" + str(a.get("handle")),
+                 "app": (a.get("app") or {}).get("name"), "phone": a.get("deviceName") or "the default phone"}
+                for a in (answer or {}).get("accounts") or () if isinstance(a, dict)]
+        allow = getattr(toolset, "allow_devices", None)
+        if allow is not None:
+            rows = [row for row in rows if str(row["phone"]).strip().casefold() in allow]
+        if not rows:
+            return ToolResult(EMPTY, structured={key: []})
+        lines = "\n".join(f"- {row[field]}, on {row['phone']}" for row in rows)
+        return ToolResult("The user's profiles:\n" + lines, structured={key: rows})

mobile_agent/accounts/pacing.py

@@ -0,0 +1,318 @@
+"""Pacing per profile: how often and when a profile may act, and a stop when the app challenges it."""
+
+import contextlib
+import datetime
+import fcntl
+import json
+import math
+import os
+import tempfile
+import threading
+import time
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+SETTINGS = "pacing.json"
+LEDGER = "pacing.jsonl"
+WAIT_MAX_S = 15 * 60
+KEEP_DAYS = 3
+COMPACT_BYTES = 128 * 1024   # a ledger bigger than this drops the entries older than KEEP_DAYS on the next record
+KINDS = ("post", "message", "comment", "follow", "react")
+ACT_KIND = {"post": "post", "publish": "post", "share": "post", "tweet": "post",
+            "send_message": "message", "reply": "message", "send": "message",
+            "comment": "comment",
+            "follow": "follow", "unfollow": "follow", "subscribe": "follow",
+            "react": "react", "like": "react"}
+DEFAULTS = {"post": {"daily": 4, "gapMinutes": 60}, "message": {"daily": 20, "gapMinutes": 4},
+            "comment": {"daily": 30, "gapMinutes": 2}, "follow": {"daily": 30, "gapMinutes": 2},
+            "react": {"daily": 100, "gapMinutes": 0.5}}
+CAPS = {"daily": (0, 1000), "gapMinutes": (0, 24 * 60)}
+CHALLENGE_WORDS = ("captcha", "suspect", "automated", "unusual activity", "confirm it's you", "confirm it’s you",
+                   "verify your account", "verify it's you", "verify it’s you", "selfie", "upload an id",
+                   "temporarily blocked", "try again later", "action blocked", "we restrict", "challenge")
+
+
+class PacingError(ValueError):
+    pass
+
+
+def kind_of(act):
+    return ACT_KIND.get(act or "")
+
+
+def _zone(name):
+    if not name:
+        return None
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError):
+        return None
+
+
+def _local(settings, at):
+    """``at`` (epoch seconds) in the profile's time zone, or the Mac's when it names none."""
+    zone = _zone(settings.get("timeZone"))
+    return datetime.datetime.fromtimestamp(at, zone) if zone else datetime.datetime.fromtimestamp(at).astimezone()
+
+
+def _minutes(text):
+    hours, minutes = text.split(":")
+    value = int(hours) * 60 + int(minutes)
+    if not 0 <= value <= 24 * 60:
+        raise ValueError
+    return value
+
+
+def clean(body):
+    """A profile's pacing settings from ``body``: {timeZone, window: {start, end} | None, limits: {kind: {daily,
+    gapMinutes}}}."""
+    if not isinstance(body, dict) or set(body) - {"timeZone", "window", "limits"}:
+        raise PacingError("Pacing takes timeZone, window and limits.")
+    out = {"timeZone": None, "window": None, "limits": {}}
+    zone = body.get("timeZone")
+    if zone not in (None, ""):
+        if not isinstance(zone, str) or _zone(zone) is None:
+            raise PacingError("timeZone is a time zone such as America/New_York.")
+        out["timeZone"] = zone
+    window = body.get("window")
+    if window is not None:
+        try:
+            start, end = _minutes(window["start"]), _minutes(window["end"])
+        except (KeyError, TypeError, ValueError, AttributeError):
+            raise PacingError("window is {start, end} as 24-hour times, such as 09:00 and 21:00.") from None
+        if start == end:
+            raise PacingError("A posting window needs a start and an end that differ.")
+        out["window"] = {"start": window["start"], "end": window["end"]}
+    limits = body.get("limits", {})
+    if not isinstance(limits, dict):
+        raise PacingError("limits is an object with daily and gapMinutes values per kind.")
+    for kind, limit in limits.items():
+        if kind not in KINDS or not isinstance(limit, dict) or set(limit) - set(CAPS):
+            raise PacingError(f"limits are per kind: {', '.join(KINDS)}, each with daily and gapMinutes.")
+        cleaned = {}
+        for key, value in limit.items():
+            low, high = CAPS[key]
+            if isinstance(value, bool) or not isinstance(value, (int, float)) or not low <= value <= high:
+                raise PacingError(f"{kind} {key} is a number from {low} to {high}.")
+            cleaned[key] = value
+        out["limits"][kind] = cleaned
+    return out
+
+
+class Pacing:
+    """Settings and ledger in ``data_dir``. ``clock`` replaces time.time in tests."""
+
+    def __init__(self, data_dir, clock=time.time):
+        self.data_dir = Path(data_dir)
+        self.settings_path = self.data_dir / SETTINGS
+        self.ledger_path = self.data_dir / LEDGER
+        self.clock = clock
+        self._lock = threading.RLock()
+
+    def _read(self):
+        try:
+            data = json.loads(self.settings_path.read_text())
+        except FileNotFoundError:
+            return {"version": 1, "profiles": {}}
+        if not isinstance(data, dict) or not isinstance(data.get("profiles"), dict):
+            raise PacingError("The saved profile pacing settings aren't readable.")
+        for stored in data["profiles"].values():
+            if not isinstance(stored, dict):
+                raise PacingError("The saved profile pacing settings aren't readable.")
+            clean({key: value for key, value in stored.items() if key != "paused"})
+            paused = stored.get("paused")
+            if paused is not None and (not isinstance(paused, dict) or not isinstance(paused.get("reason"), str)):
+                raise PacingError("The saved profile pause isn't readable.")
+        return data
+
+    @contextlib.contextmanager
+    def _exclusive(self):
+        """This process's lock and the folder's file lock: the Mac app and the CLI share the folder."""
+        with self._lock:
+            self.data_dir.mkdir(parents=True, exist_ok=True)
+            fd = os.open(self.data_dir / "pacing.lock", os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX)
+                yield
+            finally:
+                os.close(fd)
+
+    def _replace(self, path, text, prefix):
+        handle, temporary = tempfile.mkstemp(prefix=prefix, suffix=path.suffix, dir=self.data_dir)
+        try:
+            with os.fdopen(handle, "w") as stream:
+                os.fchmod(stream.fileno(), 0o600)
+                stream.write(text)
+            os.replace(temporary, path)
+        except BaseException:
+            Path(temporary).unlink(missing_ok=True)
+            raise
+
+    @contextlib.contextmanager
+    def _edit(self):
+        with self._exclusive():
+            data = self._read()
+            yield data
+            self._replace(self.settings_path, json.dumps(data, indent=1) + "\n", ".pacing.")
+
+    def settings(self, profile):
+        """The profile's settings with every kind's limit filled in, and whether it is paused."""
+        stored = self._read()["profiles"].get(profile) or {}
+        limits = {kind: {**DEFAULTS[kind], **((stored.get("limits") or {}).get(kind) or {})} for kind in KINDS}
+        return {"timeZone": stored.get("timeZone"), "window": stored.get("window"), "limits": limits,
+                "paused": stored.get("paused")}
+
+    def save(self, profile, body):
+        cleaned = clean(body)
+        with self._edit() as data:
+            current = data["profiles"].get(profile) or {}
+            data["profiles"][profile] = {**cleaned, "paused": current.get("paused")}
+        return self.settings(profile)
+
+    def pause(self, profile, reason):
+        with self._edit() as data:
+            current = data["profiles"].setdefault(profile, {})
+            current["paused"] = {"at": round(self.clock() * 1000), "reason": str(reason)[:300]}
+
+    def resume(self, profile):
+        with self._edit() as data:
+            if profile in data["profiles"]:
+                data["profiles"][profile]["paused"] = None
+        return self.settings(profile)
+
+    def record(self, profile, act, run_id=None):
+        kind = kind_of(act)
+        if kind is None:
+            return
+        line = json.dumps({"at": self.clock(), "profile": profile, "kind": kind, "run": run_id}) + "\n"
+        with self._exclusive():
+            fd = os.open(self.ledger_path, os.O_CREAT | os.O_WRONLY | os.O_APPEND | os.O_NOFOLLOW, 0o600)
+            try:
+                os.write(fd, line.encode())
+            finally:
+                os.close(fd)
+            # Preserve the ledger when maintenance cannot read or replace it.
+            with contextlib.suppress(OSError, ValueError):
+                self._compact()
+
+    def _compact(self):
+        """Drop the entries older than KEEP_DAYS once the ledger is big (called under ``_exclusive``)."""
+        if self.ledger_path.stat().st_size <= COMPACT_BYTES:
+            return
+        cutoff = self.clock() - KEEP_DAYS * 86400
+        kept = [json.dumps(entry) + "\n" for entry in self._ledger() if entry["at"] >= cutoff]
+        self._replace(self.ledger_path, "".join(kept), ".pacing.")
+
+    def _ledger(self):
+        try:
+            lines = self.ledger_path.read_text().splitlines()
+        except FileNotFoundError:
+            return []
+        entries = []
+        for line in lines:
+            entry = json.loads(line)
+            if (not isinstance(entry, dict) or not isinstance(entry.get("profile"), str)
+                    or entry.get("kind") not in KINDS
+                    or type(entry.get("at")) not in (int, float)):
+                raise PacingError("The saved profile pacing history isn't readable.")
+            try:
+                entry["at"] = float(entry["at"])
+            except OverflowError:
+                raise PacingError("The saved profile pacing history isn't readable.") from None
+            if not math.isfinite(entry["at"]):
+                raise PacingError("The saved profile pacing history isn't readable.")
+            entries.append(entry)
+        return entries
+
+    def _entries(self, profile, kind):
+        cutoff = self.clock() - KEEP_DAYS * 86400
+        return sorted(entry["at"] for entry in self._ledger()
+                      if entry["profile"] == profile and entry["kind"] == kind and entry["at"] >= cutoff)
+
+    def _day_start(self, settings, now):
+        return _local(settings, now).replace(hour=0, minute=0, second=0, microsecond=0)
+
+    def today(self, profile):
+        """{kind: how many ran today} in the profile's time zone."""
+        settings = self.settings(profile)
+        start = self._day_start(settings, self.clock()).timestamp()
+        return {kind: sum(1 for at in self._entries(profile, kind) if at >= start) for kind in KINDS}
+
+    def check(self, profile, act):
+        """None when the profile may do ``act`` now; else {"wait": seconds, "reason"} or {"stop": reason}."""
+        kind = kind_of(act)
+        settings = self.settings(profile)
+        if settings.get("paused"):
+            return {"stop": "This profile is paused: " + settings["paused"]["reason"] + " Resume it in the Queue "
+                    "after you've dealt with it in the app.", "code": "profile_paused"}
+        if kind is None:
+            return None
+        limit = settings["limits"][kind]
+        now = self.clock()
+        done = self._entries(profile, kind)
+        start = self._day_start(settings, now)
+        today = [at for at in done if at >= start.timestamp()]
+        if len(today) >= limit["daily"]:
+            tomorrow = (start + datetime.timedelta(days=1)).timestamp()
+            return {"stop": f"This profile has reached today's limit for {kind}s ({limit['daily']}). The next can go "
+                    "after midnight in its time zone.", "code": "pacing_daily", "until": tomorrow}
+        if done and limit["gapMinutes"] > 0:
+            ready = done[-1] + limit["gapMinutes"] * 60
+            if ready > now:
+                return {"wait": ready - now, "reason": f"keeps at least {limit['gapMinutes']:g} minutes between "
+                        f"{kind}s", "until": ready}
+        return None
+
+    def next_post_time(self, profile, wanted=None):
+        """The earliest time (epoch seconds) at or after ``wanted`` (default now) the profile may post."""
+        settings = self.settings(profile)
+        if settings.get("paused"):
+            return None
+        at = max(wanted or self.clock(), self.clock())
+        verdict = self.check(profile, "post")
+        if verdict and verdict.get("until"):
+            at = max(at, verdict["until"])
+        return self._in_window(settings, at)
+
+    def same_day(self, profile, first, second):
+        """Whether two times (epoch seconds) fall on one calendar day in the profile's time zone (the Mac's when it
+        names none). Settings it can't read raise, so it never guesses a day."""
+        settings = self.settings(profile)
+        return _local(settings, first).date() == _local(settings, second).date()
+
+    def _in_window(self, settings, at):
+        window = settings.get("window")
+        if not window:
+            return at
+        local = _local(settings, at)
+        start, end = _minutes(window["start"]), _minutes(window["end"])
+        minute = local.hour * 60 + local.minute
+        inside = start <= minute < end if start < end else (minute >= start or minute < end)
+        if inside:
+            return at
+        day = local.replace(hour=0, minute=0, second=0, microsecond=0)
+        opens = day + datetime.timedelta(minutes=start)
+        if opens.timestamp() <= at:
+            opens += datetime.timedelta(days=1)
+        return opens.timestamp()
+
+
+def looks_challenged(*texts):
+    """Whether a task's words say an app challenged the profile (fail closed: any of the words)."""
+    joined = " ".join(str(t or "") for t in texts).casefold()
+    return any(word in joined for word in CHALLENGE_WORDS)
+
+
+_instances = {}
+_instances_lock = threading.Lock()
+
+
+def pacing_for(runtime):
+    """The Pacing beside ``runtime``'s profiles (accounts.json's folder)."""
+    from .store import store_for
+    folder = store_for(runtime).data_dir
+    with _instances_lock:
+        found = _instances.get(folder)
+        if found is None:
+            found = _instances[folder] = Pacing(folder)
+        return found

mobile_agent/accounts/register.py

@@ -0,0 +1,78 @@
+"""Track `accounts`'s registrations (tracks.load calls ``register(api)`` once per process, staged)."""
+
+from .. import alerts
+from . import context, routing, screen
+
+TOOL_ORDER = 5
+
+
+def tool(ctx):
+    check = screen.check_for(ctx)
+    return screen.CheckAccount(check) if check is not None else None
+
+
+class Listener:
+    """Forgets a finished run's profile check; counts each commit a run as a profile carried out (pacing's ledger);
+    and pauses a profile whose run ended on an app's challenge (a captcha, "we suspect automated behavior", an ID
+    check), with an alert, so nothing else runs as it until the person resumes it."""
+
+    def on_step(self, run, record):
+        account = (getattr(run, "extras", None) or {}).get("account")
+        if not isinstance(account, dict) or not getattr(record, "commit", None):
+            return
+        pacing = _pacing(run)
+        if pacing is not None:
+            pacing.record(account["id"], record.commit, getattr(run, "id", None))
+
+    def on_finished(self, run, summary, private):
+        screen.forget(run.id)
+        account = (getattr(run, "extras", None) or {}).get("account")
+        if not isinstance(account, dict) or not isinstance(summary, dict):
+            return
+        from .pacing import looks_challenged
+        data = summary.get("data") if isinstance(summary.get("data"), dict) else {}
+        if (data.get("challenge") is True or summary.get("code") == "challenge" or (
+                summary.get("status") != "completed"
+                and looks_challenged(summary.get("reason"), summary.get("answer")))):
+            reason = (f"{account.get('app', {}).get('name', 'The app')} showed @{account.get('handle')} a check "
+                      "(a captcha, a verification or a warning about automated behavior).")
+            pacing = _pacing(run)
+            if pacing is not None:
+                pacing.pause(account["id"], reason)
+            alerts.Alerts().challenge(f"@{account.get('handle')} paused", reason, getattr(run, "id", None))
+
+
+def _pacing(run):
+    from .pacing import pacing_for
+    runtime = _RUNTIME[0]
+    if runtime is None:
+        return None
+    try:
+        return pacing_for(runtime)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+_RUNTIME = [None]
+
+
+def started(runtime):
+    _RUNTIME[0] = runtime
+
+
+def stopped(runtime):
+    if _RUNTIME[0] is runtime:
+        _RUNTIME[0] = None
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from ..mcp_server import registry as mcp_registry
+    from . import mcp, routes
+    api.register_run_field("account", routing.validate, public=True)
+    api.register_context_provider(context.provider, order=context.ORDER)
+    api.register_tool(tool, order=TOOL_ORDER)
+    api.register_run_listener(Listener())
+    api.register_service(started, stopped)
+    routes.register_routes()
+    mcp_registry.register_provider(mcp.AccountsProvider())