mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/workflows/cron.py

@@ -0,0 +1,110 @@
+"""Bounded five-field cron validation and timezone-aware occurrence calculation."""
+
+import re
+from datetime import datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+MIN_INTERVAL_MS = 300_000
+DAILY_LIMIT = 60
+
+
+def timezone(value):
+    if not isinstance(value, str) or not 1 <= len(value) <= 128:
+        raise ValueError("Choose an IANA timezone")
+    try:
+        return ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError):
+        raise ValueError("Choose a recognized IANA timezone, such as America/Los_Angeles") from None
+
+
+def local_timezone(environ=None, localtime="/etc/localtime"):
+    """The Mac's IANA zone ("America/Los_Angeles"), so a new schedule reads in the user's own time."""
+    import os
+    environ = os.environ if environ is None else environ
+    candidates = [environ.get("TZ", "").lstrip(":")]
+    for resolve in (os.readlink, os.path.realpath):
+        try:
+            target = resolve(localtime)
+        except OSError:
+            continue
+        if "/zoneinfo/" in target:
+            candidates.append(target.split("/zoneinfo/", 1)[1])
+    for candidate in candidates:
+        if candidate and ("/" in candidate or candidate == "UTC"):
+            try:
+                timezone(candidate)
+                return candidate
+            except ValueError:
+                continue
+    return "UTC"
+
+
+def validate_cron(expression, zone, daily_limit=DAILY_LIMIT):
+    timezone(zone)
+    if not isinstance(expression, str) or len(expression) > 128 or len(expression.split()) != 5:
+        raise ValueError("Use a standard five-field cron expression")
+    expression = " ".join(expression.lower().split())
+    # Support numeric fields and standard month/weekday names, not seconds, years,
+    # random/hash expressions, nearest weekdays, or nth/last-day extensions.
+    for index, field in enumerate(expression.split()):
+        permitted = ("jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec" if index == 3 else
+                     "sun|mon|tue|wed|thu|fri|sat" if index == 4 else "")
+        stripped = re.sub(permitted, "0", field) if permitted else field
+        if not re.fullmatch(r"[0-9*,/\-]+", stripped):
+            raise ValueError("Use standard cron fields without seconds, aliases, or special extensions")
+    from croniter import CroniterBadCronError, croniter  # On first use: ~17 ms the agent's start does not need.
+    try:
+        expanded, _ = croniter.expand(expression, strict=True)
+    except (CroniterBadCronError, ValueError, KeyError):
+        raise ValueError("The cron expression is invalid or cannot match a calendar date") from None
+    minutes = range(60) if expanded[0] == ["*"] else expanded[0]
+    hours = range(24) if expanded[1] == ["*"] else expanded[1]
+    daily = sorted(hour * 60 + minute for hour in hours for minute in minutes)
+    if len(daily) > daily_limit:
+        raise ValueError(f"Schedules may contain at most {daily_limit} occurrences per day")
+    if any(b - a < 5 for a, b in zip(daily, daily[1:] + [daily[0] + 1440])):
+        raise ValueError("Scheduled occurrences must be at least five minutes apart")
+    return expression
+
+
+# Bounds the skipping below: clocks going back repeat an hour or two, at most 12 five-minute slots an hour.
+MAX_REPEATS_SKIPPED = 288
+
+
+def runs_through_repeated_hours(expression):
+    """Whether a schedule runs again when a wall-clock time repeats as clocks go back."""
+    hour = expression.split()[1]
+    return hour.startswith("*") or "/" in hour
+
+
+def next_occurrences(expression, zone, after_ms, count=1):
+    if not 1 <= count <= 3:
+        raise ValueError("Preview supports one to three occurrences")
+    from croniter import CroniterBadCronError, CroniterBadDateError, croniter
+    try:
+        zone_info = timezone(zone)
+        iterator = croniter(expression, datetime.fromtimestamp(after_ms / 1000, zone_info),
+                            max_years_between_matches=8)
+        repeats = runs_through_repeated_hours(expression)
+        values, skipped = [], 0
+        while len(values) < count:
+            moment = iterator.get_next(datetime).timestamp()
+            # fold=1 is the second of two identical wall-clock times; the first one matched the same fields.
+            if not repeats and datetime.fromtimestamp(moment, zone_info).fold:
+                skipped += 1
+                if skipped > MAX_REPEATS_SKIPPED:
+                    raise ValueError("too many repeated wall-clock times")
+                continue
+            values.append(round(moment * 1000))
+    except (CroniterBadCronError, CroniterBadDateError, ValueError, OverflowError):
+        raise ValueError("The schedule has no valid occurrence within eight years") from None
+    if any(b <= a for a, b in zip([after_ms] + values, values)):
+        raise ValueError("The schedule did not advance in time")
+    return values
+
+
+def preview(body, now_ms):
+    if not isinstance(body, dict) or set(body) != {"cron", "timezone"}:
+        raise ValueError("Supply cron and timezone")
+    expression = validate_cron(body["cron"], body["timezone"])
+    return {"next": next_occurrences(expression, body["timezone"], now_ms, 3)}

mobile_agent/workflows/health.py

@@ -0,0 +1,257 @@
+"""What a workflow's row says about it (GET /api/workflows, each workflow's ``health``)."""
+
+from __future__ import annotations
+
+from . import starters
+
+OUTCOMES = frozenset({"done", "check", "couldnt_finish", "stopped", "declined"})
+# Every status as an outcome (None while the run goes). A status that means "it finished" is check here: only proof
+# makes it done. An unknown status is check, never done.
+STATUS_OUTCOMES = {
+    "queued": None, "running": None,
+    "completed": "check", "completed_unverified": "check", "expected_text_visible": "check", "demo_complete": "check",
+    "inconsistent_completion": "check", "completion_not_confirmed": "check",
+    "stopped": "stopped", "user_condition_met": "stopped", "approval_denied": "declined",
+    "interrupted": "couldnt_finish", "needs_clarification": "couldnt_finish", "error": "couldnt_finish",
+    "blocked": "couldnt_finish", "needs_text_helper": "couldnt_finish", "no_progress": "couldnt_finish",
+    "max_steps": "couldnt_finish", "timeout": "couldnt_finish", "approval_timeout": "couldnt_finish",
+    "spend_cap": "couldnt_finish", "duplicate_effect_blocked": "couldnt_finish",
+    "duplicate_text_blocked": "couldnt_finish",
+    "invalid_action": "couldnt_finish", "invalid_target": "couldnt_finish", "expected_text_missing": "couldnt_finish",
+    "preview": "stopped",
+}
+FINISHED = frozenset({"completed", "completed_unverified", "expected_text_visible"})
+# Stops by design (nobody answered, the spending limit, a repeat refused): never a failure to repair.
+SAFE_STOPS = frozenset({"approval_timeout", "spend_cap", "duplicate_effect_blocked"})
+# A run that ended because the iPhone wasn't there to use (agent_hooks.STOP_CODES that a person fixes at the phone).
+PHONE_CODES = frozenset({"phone_locked", "unlock_declined", "passcode_failed", "face_id", "unplugged",
+                         "keychain_locked"})
+
+# Dispatch outcomes that are not run statuses (service.py, records.py): how each reads on the row.
+PHONE_SKIPS = {
+    "skipped_busy": "Skipped: your iPhone was busy with another task",
+    "busy": "Skipped: your iPhone was busy with another task",
+    "skipped_offline": "Skipped: your iPhone wasn’t connected",
+    "offline": "Skipped: your iPhone wasn’t connected",
+}
+LIMIT_SKIPS = {
+    "skipped_monthly_limit": "Skipped: this month’s spending limit is reached",
+    "monthly_limit": "Skipped: this month’s spending limit is reached",
+    "skipped_daily_limit": "Skipped: the daily limit for scheduled runs is reached",
+    "skipped_interval_limit": "Skipped: too soon after the last scheduled run",
+}
+FAILURES = {
+    "dispatch_failed": "Last run couldn’t start",
+    "interrupted": "Last run was interrupted",
+    "time_limit": "Last run reached its time limit",
+    "loop_limit": "Last run reached its repeat limit",
+    "condition_unknown": "Last run couldn’t check its condition",
+    "delivery_failed": "Last run couldn’t send its result",
+    "error": "Last run couldn’t finish",
+}
+# A run that ended, then left before Mobster read how (its task deleted, on its own or with its conversation, or out of
+# the history it keeps): Mobster can't say how it ended, so it is never a failure. The row says so in grey and Needs you
+# doesn't list it (the lead, 5 Nov 2026: expired isn't failed); a failure before it still leads (workflow_health).
+UNKNOWN_ENDS = {"run_expired": "Last run is no longer kept"}
+GOING = frozenset({"claimed", "started"})
+# Outcomes that say nothing about the workflow itself: they never raise attention and never hide an older one.
+QUIET = frozenset({"skipped_missed"})
+LINE_MAX = 140
+
+
+def _record(value):
+    return isinstance(value, dict)
+
+
+def _text(value):
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def result_fields(run):
+    """The result's fields: the run's summary over its last ``result`` event."""
+    events = getattr(run, "events", None) or ()
+    result = next((event for event in reversed(events) if _record(event) and event.get("event") == "result"), None)
+    summary = getattr(run, "summary", None)
+    source = {**(result or {}), **summary} if _record(summary) else dict(result or {})
+    proof = [item for item in source.get("proof") or () if _record(item) and _text(item.get("quote"))] \
+        if isinstance(source.get("proof"), list) else []
+    outcome = source.get("outcome") if source.get("outcome") in OUTCOMES else None
+    return {"outcome": outcome, "proof": proof, "answer": _text(source.get("answer")),
+            "reason": _text(source.get("reason")), "stopCode": _text(source.get("stop_code"))}
+
+
+def run_outcome(run):
+    """done | check | couldnt_finish | stopped | declined, or None while the run goes (result-status.ts runOutcome)."""
+    status = getattr(run, "status", None)
+    if status in ("queued", "running") or getattr(run, "finished_at", None) is None:
+        return None
+    fields = result_fields(run)
+    outcome = fields["outcome"] or STATUS_OUTCOMES.get(status, "check")
+    if not fields["outcome"] and outcome == "check" and status in FINISHED and fields["proof"]:
+        outcome = "done"
+    if outcome == "done" and not fields["proof"]:
+        outcome = "check"
+    if outcome == "check" and getattr(run, "reviewed_ok", False):
+        outcome = "done"
+    return outcome
+
+
+def verified(run):
+    """The run finished and it is proven (or a person marked it OK)."""
+    return run is not None and run_outcome(run) == "done"
+
+
+def first_line(text, limit=LINE_MAX):
+    """The first line of an answer, cut at a word to ``limit`` characters."""
+    line = next((part.strip() for part in (text or "").splitlines() if part.strip()), None)
+    if line is None or len(line) <= limit:
+        return line
+    return line[:limit - 1].rsplit(" ", 1)[0].rstrip(" ,;:") + "…"
+
+
+def success_of(run):
+    """{"at", "runId", "line"} for a verified run: when it finished (ms) and its answer's first line."""
+    finished = getattr(run, "finished_at", None)
+    return {"at": round(finished * 1000) if finished is not None else None, "runId": run.id,
+            "line": first_line(result_fields(run)["answer"])}
+
+
+def _attention(kind, words, detail=None, run_id=None, at=None):
+    return {"kind": kind, "words": words, "detail": detail, "runId": run_id, "at": at}
+
+
+def attention_for(outcome, run, at=None, plain=True):
+    """What the newest ended attempt asks of you, or None."""
+    run_id = getattr(run, "id", None)
+    if outcome is None or outcome in GOING or outcome in QUIET:
+        return None
+    if outcome in PHONE_SKIPS:
+        return _attention("phone", PHONE_SKIPS[outcome], "Keep it plugged into this Mac and unlocked.", run_id, at)
+    if outcome in LIMIT_SKIPS:
+        return _attention("limit", LIMIT_SKIPS[outcome], None, run_id, at)
+    if outcome == "missing_values":
+        return _attention("input", "A value it needs is missing", "Edit the workflow and give each blank a value.",
+                          run_id, at)
+    if outcome in UNKNOWN_ENDS:
+        return _attention("unknown", UNKNOWN_ENDS[outcome], None, None, at)
+    fields = result_fields(run) if run is not None and getattr(run, "finished_at", None) is not None else None
+    if fields and fields["stopCode"] in PHONE_CODES:
+        return _attention("phone", "Last run stopped: your iPhone wasn’t available", fields["reason"], run_id, at)
+    if not plain:
+        # A batch ends completed only when every step ended done; stopped is your own Stop.
+        if outcome in FAILURES or STATUS_OUTCOMES.get(outcome) == "couldnt_finish" and outcome not in SAFE_STOPS:
+            return _attention("failed", FAILURES.get(outcome, "Last run couldn’t finish"),
+                              fields["reason"] if fields else None, run_id, at)
+        return None
+    if fields is not None:
+        if run_outcome(run) == "couldnt_finish" and getattr(run, "status", None) not in SAFE_STOPS:
+            return _attention("failed", "Last run couldn’t finish", fields["reason"], run_id, at)
+        return None
+    if outcome in FAILURES or STATUS_OUTCOMES.get(outcome) == "couldnt_finish" and outcome not in SAFE_STOPS:
+        return _attention("failed", FAILURES.get(outcome, "Last run couldn’t finish"), None, run_id, at)
+    return None
+
+
+def missing_input(workflow, filled=None):
+    """Attention for a scheduled workflow that can't fill what it needs"""
+    if not workflow.get("enabled"):
+        return None
+    repeat = workflow.get("repeat") or {}
+    if repeat.get("kind") == "each" and not repeat.get("rows"):
+        return _attention("input", "Its rows are missing", "Edit the workflow and save the rows it repeats over.")
+    keys = set(filled or ())
+    if repeat.get("rows"):
+        keys |= set.intersection(*[set(starters.clean_values(row)) for row in repeat["rows"]])
+    missing = [name for name in starters.unfilled(workflow.get("goal")) if starters._key(name) not in keys]
+    if missing:
+        return _attention("input", f"It needs a value for {missing[0]}",
+                          "Edit the workflow and give each blank a default.")
+    return None
+
+
+def is_plain(workflow):
+    """One task and no repeat: it runs as one task, whose own result is the workflow's."""
+    from ..graph.chain import record_is_plain
+    return record_is_plain(workflow)
+
+
+def latest_success(workflow, attempts, runs):
+    """The newest verified success among ``attempts``, else the one the record keeps (``lastSuccess``)."""
+    plain = is_plain(workflow)
+    success = None
+    for outcome, run_id, claimed_at in attempts:
+        run = runs.get(run_id) if isinstance(run_id, str) else None
+        if plain and verified(run):
+            success = success_of(run)
+            break
+        if not plain and outcome == "completed":
+            success = success_of(run) if run is not None else {"at": claimed_at, "runId": None, "line": None}
+            break
+    stored = workflow.get("lastSuccess")
+    if (_record(stored) and isinstance(stored.get("at"), (int, float))
+            and (success is None or (success["at"] or 0) < stored["at"])):
+        success = {"at": stored["at"], "runId": stored.get("runId"), "line": stored.get("line")}
+    return success
+
+
+RECENT = 10
+RUN_WORDS = {"done": "done", "check": "check", "couldnt_finish": "failed", "stopped": "stopped", "declined": "stopped"}
+
+
+def outcome_word(outcome, run, plain=True):
+    """One attempt as the row's history reads it: done, check, failed, stopped, skipped or running."""
+    if outcome in GOING:
+        return "running"
+    if outcome in PHONE_SKIPS or outcome in LIMIT_SKIPS or outcome == "missing_values":
+        return "skipped"
+    if outcome in UNKNOWN_ENDS:
+        return "unknown"
+    if plain and run is not None:
+        found = run_outcome(run)
+        return RUN_WORDS.get(found, "check") if found else "running"
+    if not plain and outcome == "completed":
+        return "done"
+    if outcome in SAFE_STOPS or STATUS_OUTCOMES.get(outcome) in ("stopped", "declined") or outcome == "cancelled":
+        return "stopped"
+    if outcome in FAILURES or STATUS_OUTCOMES.get(outcome) == "couldnt_finish":
+        return "failed"
+    return "check"
+
+
+def recent_of(workflow, attempts, runs):
+    """Its last ``RECENT`` attempts, newest first, as {"outcome", "at", "runId"}."""
+    plain = is_plain(workflow)
+    recent = []
+    for outcome, run_id, claimed_at in attempts:
+        if outcome in QUIET:
+            continue
+        run = runs.get(run_id) if isinstance(run_id, str) else None
+        recent.append({"outcome": outcome_word(outcome, run, plain), "at": claimed_at,
+                       "runId": run_id if isinstance(run_id, str) else None})
+        if len(recent) == RECENT:
+            break
+    return recent
+
+
+def workflow_health(workflow, attempts, runs, filled=None):
+    """A workflow's ``health``."""
+    plain = is_plain(workflow)
+    attention = missing_input(workflow, filled)
+    if attention is None:
+        unknown = None
+        for outcome, run_id, claimed_at in attempts:
+            if outcome in QUIET:
+                continue
+            if outcome in UNKNOWN_ENDS:
+                # An end Mobster can't read never hides an older one: a failure under it still leads, a success
+                # or nothing leaves the quiet line (review of #2089: fail closed).
+                unknown = unknown or attention_for(outcome, None, claimed_at, plain)
+                continue
+            run = runs.get(run_id) if isinstance(run_id, str) else None
+            found = attention_for(outcome, run, claimed_at, plain)
+            attention = found if unknown is None or (found and found["kind"] == "failed") else unknown
+            break
+        else:
+            attention = unknown
+    return {"lastSuccess": latest_success(workflow, attempts, runs), "attention": attention,
+            "recent": recent_of(workflow, attempts, runs)}

mobile_agent/workflows/history.py

@@ -0,0 +1,126 @@
+"""A workflow's history (docs/workflows.mdx › Drafts, publishing and versions)"""
+
+import json
+
+from ..api_errors import APIError
+from ..graph import edit
+from ..journal import encode
+
+KEPT = 100
+# What a rollback brings back from an old version; whether the schedule is on, the home conversation and the webhook
+# stay as they are now.
+RESTORED = ("graph", "name", "appId", "appName", "engine", "device", "account", "sendTo", "sameConversation",
+            "outputSchema", "outputFormat", "produces")
+
+
+class WorkflowHistory:
+    def __init__(self, owner):
+        self.owner = owner
+        with owner.journal.transaction() as connection:
+            connection.execute("""CREATE TABLE IF NOT EXISTS workflow_versions (
+                workflow_id TEXT NOT NULL, revision INTEGER NOT NULL, saved_at INTEGER NOT NULL, data TEXT NOT NULL,
+                published_at INTEGER, PRIMARY KEY (workflow_id, revision))""")
+
+    def forget(self, connection, identifier):
+        connection.execute("DELETE FROM workflow_versions WHERE workflow_id=?", (identifier,))
+
+    def _version_row(self, identifier, revision):
+        """Read a saved version under the journal lock, after checking the workflow still exists."""
+        row = self.owner.journal.connection.execute(
+            "SELECT data, published_at FROM workflow_versions WHERE workflow_id=? AND revision=?",
+            (identifier, revision)).fetchone()
+        if row is None:
+            raise APIError("That version isn't kept any more.", 404, "version_not_found")
+        return row
+
+    def publish(self, identifier, body):
+        """POST /api/workflows/{id}/publish {revision}"""
+        if not isinstance(body, dict) or set(body) != {"revision"} or type(body["revision"]) is not int:
+            raise ValueError("Give the revision to publish")
+        with self.owner.lock, self.owner.journal.lock:
+            workflow = self.owner._get(identifier)
+            row = self._version_row(identifier, body["revision"])
+            try:
+                graph = self.owner.check_graph(json.loads(row[0]).get("graph"), identifier)
+            except ValueError as error:
+                raise APIError(f"That version can't run now: {error}", 409, "version_invalid") from None
+            updated = {**workflow, "published": {"revision": body["revision"], "graph": graph}}
+            self.owner.derive(updated)
+            next_at = self.owner._schedule(updated)
+            if any(updated.get(key) != workflow.get(key) for key in ("cron", "timezone")):
+                updated["nextAt"] = next_at if updated["enabled"] else None
+            with self.owner.journal.transaction() as connection:
+                self.owner._save(connection, updated)
+                connection.execute("UPDATE workflow_versions SET published_at=? WHERE workflow_id=? AND revision=?",
+                                   (self.owner.now(), identifier, body["revision"]))
+            self.owner.triggers.changed()
+            return self.owner.public(updated)
+
+    def keep(self, connection, workflow):
+        published = (workflow.get("published") or {}).get("revision") == workflow["revision"]
+        connection.execute("INSERT OR REPLACE INTO workflow_versions VALUES (?,?,?,?,?)",
+                           (workflow["id"], workflow["revision"], workflow["updatedAt"], encode(workflow),
+                            workflow["updatedAt"] if published else None))
+        connection.execute("""DELETE FROM workflow_versions WHERE workflow_id=? AND revision NOT IN (
+            SELECT revision FROM workflow_versions WHERE workflow_id=? ORDER BY revision DESC LIMIT ?)""",
+                           (workflow["id"], workflow["id"], KEPT))
+
+    def versions(self, identifier):
+        """GET /api/workflows/{id}/versions"""
+        with self.owner.journal.lock:
+            live = (self.owner._get(identifier).get("published") or {}).get("revision")
+            rows = self.owner.journal.connection.execute("""SELECT revision, saved_at, data, published_at FROM workflow_versions
+                WHERE workflow_id=? ORDER BY revision""", (identifier,)).fetchall()  # noqa: E501
+        out, before = [], None
+        for revision, saved_at, data, published_at in rows:
+            graph = (json.loads(data).get("graph") or {})
+            out.append({"revision": revision, "savedAt": saved_at, "nodes": len(graph.get("nodes") or []),
+                        "edges": len(graph.get("edges") or []), "change": edit.change_line(before, graph),
+                        "published": published_at is not None, "live": revision == live})
+            before = graph
+        return out[::-1]
+
+    def diff(self, identifier, a, b):
+        """GET /api/workflows/{id}/versions/{a}/diff/{b}: the nodes and edges added, removed and changed from a to b."""
+        return edit.diff(self.version(identifier, a)["graph"], self.version(identifier, b)["graph"])
+
+    def version(self, identifier, revision):
+        """GET /api/workflows/{id}/versions/{revision}: that version as the API shows a workflow."""
+        with self.owner.journal.lock:
+            self.owner._get(identifier)
+            row = self._version_row(identifier, revision)
+        return self.owner.public(json.loads(row[0]))
+
+    def call_graph(self, identifier, revision, *, allow_draft=False):
+        """The saved graph a child call may run, with publication provenance checked under the same lock."""
+        with self.owner.journal.lock:
+            self.owner._get(identifier)
+            row = self._version_row(identifier, revision)
+            if row[1] is None and not allow_draft:
+                raise APIError("Publish that saved version before another workflow runs it.", 409, "not_published")
+            return json.loads(row[0])["graph"]
+
+    def rollback(self, identifier, body):
+        """POST /api/workflows/{id}/rollback {revision, current}: save version ``revision`` as the newest."""
+        if not isinstance(body, dict) or set(body) != {"revision", "current"} or any(
+                type(body[key]) is not int for key in body):
+            raise ValueError("Give the revision to bring back and the current revision")
+        with self.owner.lock, self.owner.journal.lock:
+            workflow = self.owner._get(identifier)
+            if body["current"] != workflow["revision"]:
+                raise APIError("The workflow changed. Reload before rolling it back.", 409, "revision_conflict")
+            row = self._version_row(identifier, body["revision"])
+            old = json.loads(row[0])
+            updated = dict(workflow)
+            for key in RESTORED:
+                if key in old:
+                    updated[key] = old[key]
+                else:
+                    updated.pop(key, None)
+            try:
+                updated["graph"] = self.owner.check_graph(old.get("graph"), identifier)
+            except ValueError as error:
+                raise APIError(f"That version can't be saved now: {error}", 409, "version_invalid") from None
+            updated["published"] = {"revision": workflow["revision"] + 1, "graph": updated["graph"]}
+            self.owner.derive(updated)
+            return self.owner._commit(workflow, updated)