mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/hints.py

@@ -0,0 +1,248 @@
+"""Hints: what Mobster knows about an app before it looks, used only while it keeps proving true."""
+
+import hashlib
+import json
+import os
+import threading
+import time
+from pathlib import Path
+
+FILE = "hints.jsonl"
+HEALS = "hints-heals.jsonl"
+MAX_BYTES = 1_000_000
+SURE = .6                    # the confidence a source needs to act on a hint (packs' recognizers set it, 12 Oct)
+MISSES_TO_STEP_ASIDE = 2     # misses in a row, in one run, that turn a source off for that app for the run
+STALE_AFTER = 2              # a key's last uses at one app version that all missed: stale at that version
+RECENT = 400
+SOURCES = ("pack", "replay", "ios")
+# Heals are navigation: a step that commits is never learned from a fallback.
+HEAL_OPS = frozenset({"TAP", "LONG_PRESS", "SWIPE_LEFT", "SWIPE_RIGHT", "SCROLL_TO"})
+# A saved program's handovers that are drift, not by design.
+PROGRAM_DRIFT = ("didn't fit this screen", "found no control it can act on")
+_lock = threading.Lock()
+_cache = {}                  # path -> (mtime, size, entries)
+
+
+def _append(path, entry):
+    line = json.dumps({"at": round(time.time(), 3), **entry}, separators=(",", ":"), sort_keys=True) + "\n"
+    with _lock:
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            if path.exists() and path.stat().st_size > MAX_BYTES:
+                kept = path.read_bytes()[-MAX_BYTES // 2:]
+                path.write_bytes(kept[kept.find(b"\n") + 1:])
+            with open(path, "a", encoding="utf-8") as out:
+                out.write(line)
+            os.chmod(path, 0o600)
+        except OSError:
+            pass  # the ledger is a log: a full disk never stops a step
+
+
+def _read(path):
+    try:
+        stat = path.stat()
+    except OSError:
+        return []
+    with _lock:
+        cached = _cache.get(path)
+        if cached and cached[:2] == (stat.st_mtime_ns, stat.st_size):
+            return cached[2]
+    out = []
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            try:
+                out.append(json.loads(line))
+            except ValueError:
+                continue
+    except OSError:
+        return []
+    with _lock:
+        _cache[path] = (stat.st_mtime_ns, stat.st_size, out)
+    return out
+
+
+def record(data_dir, entry):
+    """One use or drift (``entry``: source, app, key, ok, and what's known of version, variant, confidence, why)."""
+    if data_dir:
+        _append(Path(data_dir) / FILE, entry)
+
+
+def recent(data_dir, *, source=None, app=None, limit=RECENT):
+    """The newest ``limit`` ledger lines (of one source, one app), oldest first."""
+    if not data_dir:
+        return []
+    lines = [e for e in _read(Path(data_dir) / FILE)
+             if (source is None or e.get("source") == source) and (app is None or e.get("app") == app)]
+    return lines[-limit:]
+
+
+def stale(entries, source, app, key, version):
+    """Whether ``key``'s last STALE_AFTER uses at ``version`` (among ``entries``) all missed."""
+    uses = [e for e in entries if e.get("kind", "use") == "use" and e.get("source") == source
+            and e.get("app") == app and e.get("key") == key and e.get("version") == version]
+    last = uses[-STALE_AFTER:]
+    return len(last) == STALE_AFTER and not any(e.get("ok") for e in last)
+
+
+class Gate:
+    """One run's gate for every source. ``trust`` before acting on a hint; ``note`` after each use."""
+
+    def __init__(self, data_dir=None):
+        self.data_dir = data_dir
+        self.misses = {}     # (source, app) -> misses in a row this run
+
+    def trust(self, source, app, key, confidence=None, version=None):
+        """(True, None), or (False, why) when the general agent should do this step."""
+        if confidence is not None and confidence < SURE:
+            return False, f"not sure enough where it is ({confidence:.2f} < {SURE})"
+        if self.misses.get((source, app), 0) >= MISSES_TO_STEP_ASIDE:
+            return False, f"missed {MISSES_TO_STEP_ASIDE} times in a row in this task"
+        if version and stale(recent(self.data_dir, source=source, app=app), source, app, key, version):
+            return False, f"missed its last {STALE_AFTER} uses on this version of the app"
+        return True, None
+
+    def note(self, ok, source="pack", app=None):
+        """A use landed or not; returns whether ``source`` is now off for ``app`` in this run."""
+        misses = 0 if ok else self.misses.get((source, app), 0) + 1
+        self.misses[(source, app)] = misses
+        return misses >= MISSES_TO_STEP_ASIDE
+
+
+def status(entries):
+    """One app's state for one source, from its ledger lines."""
+    uses = [e for e in entries if e.get("kind", "use") == "use"]
+    drifts = [e for e in entries if e.get("kind") == "drift"] or [e for e in uses if not e.get("ok")]
+    landed = sum(1 for e in uses if e.get("ok"))
+    state = "unknown"
+    if uses:
+        last = uses[-STALE_AFTER:]
+        state = ("stale" if len(last) == STALE_AFTER and not any(e.get("ok") for e in last)
+                 else "healthy" if landed / len(uses) >= .8 else "degraded")
+    last = drifts[-1] if drifts else None
+    return {"uses": len(uses), "landed": landed, "missed": len(uses) - landed, "state": state,
+            "versions": sorted({str(e["version"]) for e in uses if e.get("version")}),
+            "lastDrift": ({k: last.get(k) for k in ("key", "version", "variant", "why", "at")} if last else None)}
+
+
+def health(data_dir):
+    """Every app's hints by source: [{app, sources: {source: status}, heals: {checked, rejected}}], by app."""
+    by_app = {}
+    for entry in recent(data_dir, limit=10 ** 6):
+        by_app.setdefault(entry.get("app") or "", {}).setdefault(entry.get("source") or "", []).append(entry)
+    heals = _read(Path(data_dir) / HEALS) if data_dir else []
+    out = []
+    for app in sorted(by_app):
+        mine = [h for h in heals if h.get("app") == app]
+        out.append({"app": app, "sources": {source: status(lines) for source, lines in sorted(by_app[app].items())},
+                    "heals": {"checked": sum(1 for h in mine if h.get("checked")),
+                              "rejected": sum(1 for h in mine if not h.get("checked"))}})
+    return out
+
+
+def pair_hash(role, label):
+    """The screen-shape hash of one (role, label) pair: state.screen_shape's rule."""
+    return hashlib.sha1(json.dumps([role, label], ensure_ascii=False).encode()).hexdigest()[:8]
+
+
+def check(proposal, shape):
+    """The replay check before a heal is kept."""
+    action = proposal.get("action") or {}
+    return (action.get("op") in HEAL_OPS and bool(action.get("label")) and action.get("commit") is None
+            and pair_hash(action.get("role"), action.get("label")) in set(shape or ()))
+
+
+def use_of(event, app=None, version=None):
+    """A source's event as a ledger line, or None. ``app_pack`` lines are written by packs themselves (``own``)."""
+    kind = event.get("event")
+    if kind == "app_pack":
+        from .packs.health import bundle_of
+        return {"kind": "use", "source": "pack", "app": bundle_of(event.get("pack")), "key": event.get("step"),
+                "ok": bool(event.get("ok")), "version": event.get("version"), "confidence": event.get("confidence"),
+                "why": event.get("why"), "own": True}
+    if kind == "frontier_program" and isinstance(event.get("at"), int):
+        return {"kind": "use", "source": "replay", "app": app, "key": f"step {event['at'] + 1}", "ok": True,
+                "version": version}
+    if kind == "frontier_program_handover" and isinstance(event.get("at"), int) and any(
+            phrase in str(event.get("why") or "") for phrase in PROGRAM_DRIFT):
+        return {"kind": "use", "source": "replay", "app": app, "key": f"step {event['at'] + 1}", "ok": False,
+                "version": version, "why": str(event.get("why") or "")[:160]}
+    if kind == "replay_drift":
+        return {"kind": "use", "source": "replay", "app": app, "key": f"step {event.get('step')}",
+                "ok": False, "version": version, "why": str(event.get("why") or "")[:160]}
+    if kind == "hint" and event.get("source") in SOURCES:
+        return {"kind": "use", "source": event["source"], "app": event.get("app") or app, "key": event.get("key"),
+                "ok": bool(event.get("ok")), "version": event.get("version") or version,
+                "confidence": event.get("confidence"), "why": str(event.get("why") or "")[:160] or None}
+    return None
+
+
+class HintListener:
+    """harness_api.RunListener: writes each hint use to the ledger."""
+
+    def __init__(self):
+        self.runs = {}
+        self._lock = threading.Lock()
+
+    def on_created(self, run, runtime):
+        state_db = getattr(getattr(runtime, "config", None), "state_db", None)
+        data_dir = getattr(run, "data_dir", None) or (Path(state_db).parent if state_db else None)
+        if data_dir is None:
+            return
+        app = (getattr(run, "app", None) or {}).get("bundleId")
+        version = None
+        if app:
+            try:
+                from .packs.core import app_version
+                version = app_version(runtime, app)
+            except Exception:  # noqa: BLE001
+                version = None
+        with self._lock:
+            self.runs[run.id] = {"data_dir": Path(data_dir), "app": app, "version": version, "pending": [],
+                                 "proposals": []}
+
+    def _state(self, run):
+        with self._lock:
+            return self.runs.get(getattr(run, "id", None))
+
+    def on_event(self, run, event):
+        state = self._state(run)
+        if state is None or not isinstance(event, dict):
+            return
+        use = use_of(event, state["app"], state["version"])
+        if use is None:
+            return
+        own = use.pop("own", False)
+        if not own:
+            record(state["data_dir"], use)
+        if not use["ok"]:
+            state["pending"].append(use)
+
+    def on_step(self, run, record_):
+        state = self._state(run)
+        if state is None or not state["pending"]:
+            return
+        variant = getattr(record_, "screen", None)
+        target = getattr(record_, "target", None) or {}
+        for use in state["pending"]:
+            record(state["data_dir"], {**{k: use.get(k) for k in ("source", "app", "key", "version", "why")},
+                                       "kind": "drift", "variant": variant})
+            proposal = {"source": use["source"], "app": use["app"], "key": use["key"], "version": use.get("version"),
+                        "variant": variant, "run": getattr(run, "id", None),
+                        "action": {"op": getattr(record_, "op", None), "role": target.get("role"),
+                                   "label": target.get("label"), "commit": getattr(record_, "commit", None)}}
+            proposal["checked"] = check(proposal, getattr(record_, "shape", ()))
+            state["proposals"].append(proposal)
+        state["pending"] = []
+
+    def on_finished(self, run, summary, private):
+        with self._lock:
+            state = self.runs.pop(getattr(run, "id", None), None)
+        if state is None:
+            return
+        for use in state["pending"]:  # a miss with no step after it: the drift, with no variant
+            record(state["data_dir"], {**{k: use.get(k) for k in ("source", "app", "key", "version", "why")},
+                                       "kind": "drift", "variant": None})
+        done = (summary or {}).get("status") == "completed" and (summary or {}).get("outcome") == "done"
+        if done:
+            for proposal in state["proposals"]:
+                _append(state["data_dir"] / HEALS, proposal)

mobile_agent/history.py

@@ -0,0 +1,69 @@
+"""`mobster history`: past tasks over a read-only connection, while the journal stays open (SQLite WAL)."""
+
+import json
+import sqlite3
+import sys
+import time
+
+from .paths import default_history_db
+
+
+def read_history(path, limit=20):
+    from pathlib import Path
+    path = Path(path)
+    if not path.is_file():
+        return []
+    connection = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=2)
+    try:
+        rows = connection.execute("SELECT data FROM runs ORDER BY rowid DESC LIMIT ?", (max(0, limit),)).fetchall()
+    except sqlite3.Error:
+        return []
+    finally:
+        connection.close()
+    records = []
+    for (data,) in rows:
+        try:
+            record = json.loads(data)
+        except ValueError:
+            continue
+        if isinstance(record, dict):
+            records.append(record)
+    return records
+
+
+def summary_of(record):
+    return record.get("summary") if isinstance(record.get("summary"), dict) else {}
+
+
+def print_history(limit=20, as_json=False, path=None, stream=None):
+    from .narrate import status_label, status_tone
+    stream = stream or sys.stdout
+    records = read_history(path or default_history_db(), limit)
+    if as_json:
+        for record in records:
+            summary = summary_of(record)
+            stream.write(json.dumps({"id": record.get("id"), "app": record.get("appName"), "goal": record.get("goal"),
+                                     "status": record.get("status"), "createdAt": record.get("createdAt"),
+                                     "finishedAt": record.get("finishedAt"), "reason": summary.get("reason"),
+                                     **({"failure": summary["failure"]} if summary.get("failure") else {})},
+                                    allow_nan=False) + "\n")
+        return 0
+    if not records:
+        stream.write("No tasks yet. Run `mobster` (or `mobster --demo`) and give it one.\n")
+        return 0
+    from .style import Palette, color_enabled
+    paint = Palette(color_enabled(stream))
+    roles = {"success": "green", "error": "red", "warning": "amber", "review": "accent", "neutral": "muted"}
+    for record in records:
+        status = record.get("status") or ""
+        created = (record.get("createdAt") or 0) / 1000
+        when = time.strftime("%b %d %H:%M", time.localtime(created)) if created else ""
+        goal = (record.get("goal") or "")[:56]
+        stream.write(f"{paint(record.get('id', ''), 'faint')}  {when:<12}  "
+                     f"{paint(f'{status_label(status):<22}', roles.get(status_tone(status), 'muted'))}"
+                     f"{(record.get('appName') or '')[:12]:<13} {goal}\n")
+        failure = (summary_of(record).get("failure") or {}).get("line")
+        if failure:
+            stream.write(paint(f"{'':<36}{failure}\n", "faint"))
+    stream.write(paint("\nOpen one with: mobster --resume ID\nSave one as a GIF: mobster export ID --gif\n", "faint"))
+    return 0

mobile_agent/home.py

@@ -0,0 +1,214 @@
+"""Home (GET /api/home): your jobs, what finished since you last looked, and this week's totals."""
+
+from __future__ import annotations
+
+import copy
+import re
+import time
+
+from . import usage
+from .workflows.health import first_line, run_outcome
+
+JOBS = 6
+FINISHED_OUTCOMES = frozenset({"done", "check"})
+ITEM_KINDS = {"review_queue": "items", "media_list": "items", "table": "rows", "checklist": "items"}
+NOUNS = {"review_queue": "conversations", "media_list": "videos", "table": "rows", "checklist": "checks"}
+# A workflow run's step: its dispatch's key, then :g<run>: (a graph run) or :b<run>: (a batch of step cards).
+BATCH_KEY = re.compile(r"^(workflow:([0-9a-f]{1,32}):[^:]+:[^:]+):[bg]([0-9a-f]{12}):")
+WORKFLOW_KEY = re.compile(r"^workflow:([0-9a-f]{1,32}):")
+PREVIEW = {"review_queue": ("items", 3), "media_list": ("items", 3), "table": ("rows", 4), "checklist": ("items", 3)}
+HISTORY = 100
+
+
+def _ms(seconds):
+    return round(seconds * 1000) if isinstance(seconds, (int, float)) else None
+
+
+def _summary(run):
+    return run.summary if isinstance(getattr(run, "summary", None), dict) else {}
+
+
+def _blocks(run):
+    envelope = _summary(run).get("blocks")
+    return [block for block in (envelope or {}).get("blocks") or () if isinstance(block, dict)] \
+        if isinstance(envelope, dict) else []
+
+
+def is_brief(run):
+    return isinstance(_summary(run).get("brief"), dict)
+
+
+def job_key(run):
+    found = BATCH_KEY.match(getattr(run, "idempotency_key", None) or "")
+    return f"batch:{found[3]}" if found else run.id
+
+
+def workflow_of(run):
+    found = WORKFLOW_KEY.match(getattr(run, "idempotency_key", None) or "")
+    return found[1] if found else None
+
+
+def items_of(run):
+    if is_brief(run):
+        return {}
+    out = {}
+    for block in _blocks(run):
+        field = ITEM_KINDS.get(block.get("type"))
+        if field:
+            out[block["type"]] = out.get(block["type"], 0) + len(block.get(field) or ())
+    return out
+
+
+def waiting_drafts(run):
+    if is_brief(run):
+        return 0
+    state = getattr(run, "block_state", None) or {}
+    return sum(1 for block in _blocks(run) if block.get("type") == "review_queue"
+               for item in block.get("items") or () if item.get("draft") and f"{block['id']}/{item['id']}" not in state)
+
+
+def counts(runs, since_ms, until_ms=None):
+    groups = {}
+    for run in runs:
+        groups.setdefault(job_key(run), []).append(run)
+    jobs, kinds, need = 0, {}, 0
+    for members in groups.values():
+        if any(getattr(run, "finished_at", None) is None for run in members):
+            continue
+        last = max(_ms(run.finished_at) for run in members)
+        if last < since_ms or (until_ms is not None and last >= until_ms):
+            continue
+        if all(run_outcome(run) in FINISHED_OUTCOMES for run in members):
+            jobs += 1
+        for run in members:
+            for kind, n in items_of(run).items():
+                kinds[kind] = kinds.get(kind, 0) + n
+            need += waiting_drafts(run)
+    return {"jobs": jobs, "items": sum(kinds.values()), "kinds": kinds, "needYou": need}
+
+
+def preview(block):
+    if not isinstance(block, dict):
+        return None
+    out = copy.deepcopy(block)
+    field, keep = PREVIEW.get(block.get("type"), (None, None))
+    if field:
+        out[field] = list(block.get(field) or ())[:keep]
+        out["total"] = len(block.get(field) or ())
+        if block.get("type") == "review_queue":
+            out["drafts"] = sum(1 for item in block.get("items") or () if item.get("draft"))
+        if block.get("type") == "checklist":
+            out["failed"] = sum(1 for item in block.get("items") or () if item.get("status") == "fail")
+        if block.get("type") == "table":
+            out["columns"] = list(block.get("columns") or ())[:3]
+    if block.get("type") == "markdown":
+        out["text"] = str(block.get("text") or "")[:600]
+    return out
+
+
+def learned_of(run):
+    summary = _summary(run)
+    replay, program = summary.get("replay"), summary.get("program")
+    if (isinstance(replay, dict) and replay.get("mode") in ("replayed", "healed")
+            and isinstance(replay.get("seconds"), (int, float))):
+        return {"seconds": replay["seconds"], "costUsd": replay.get("costUsd") or 0.0, "first": replay.get("first")}
+    if isinstance(program, dict) and program.get("replayed"):
+        elapsed = summary.get("elapsed_ms")
+        return {"seconds": elapsed / 1000 if isinstance(elapsed, (int, float)) else None,
+                "costUsd": getattr(run, "cost_usd", None), "first": program.get("first")}
+    return None
+
+
+def last_result(run):
+    if run is None or getattr(run, "finished_at", None) is None:
+        return None
+    summary = _summary(run)
+    brief = summary.get("brief") if isinstance(summary.get("brief"), dict) else None
+    elapsed = summary.get("elapsed_ms")
+    seconds = (brief.get("seconds") if brief else elapsed / 1000 if isinstance(elapsed, (int, float))
+               else run.finished_at - run.created_at)
+    cost = brief.get("spentUsd") if brief else getattr(run, "cost_usd", None)
+    blocks = _blocks(run)
+    # A brief's waiting drafts are its tasks': count them through the task that holds each card.
+    return {"runId": run.id, "status": run.status, "outcome": run_outcome(run), "at": _ms(run.finished_at),
+            "seconds": round(seconds, 1) if isinstance(seconds, (int, float)) else None,
+            "costUsd": round(cost, 6) if isinstance(cost, (int, float)) else None,
+            "answer": first_line(summary.get("answer") or summary.get("full_answer") or summary.get("reason")),
+            "preview": preview(blocks[0]) if blocks else None, "cards": len(blocks),
+            "items": sum(items_of(run).values()) if not brief else None,
+            "brief": bool(brief), "learned": learned_of(run)}
+
+
+def _brief_drafts(run, runs):
+    brief = _summary(run).get("brief")
+    if not isinstance(brief, dict):
+        return waiting_drafts(run)
+    sources = {source for source in brief.get("runs") or () if isinstance(source, str)}
+    return sum(waiting_drafts(runs[source]) for source in sources if source in runs)
+
+
+def jobs(workflows, runs, inbox_items, running=None):
+    running = running or {}
+    by_workflow = {}
+    for run in runs.values():
+        owner = workflow_of(run)
+        if owner:
+            by_workflow.setdefault(owner, []).append(run)
+    cards = []
+    for workflow in workflows:
+        last = runs.get(workflow.get("lastRunId") or "")
+        mine = {run.id for run in by_workflow.get(workflow["id"], ())}
+        waiting = sum(1 for item in inbox_items if (item.get("workflow") or {}).get("id") == workflow["id"]
+                      or item.get("runId") in mine)
+        drafts = _brief_drafts(last, runs) if last is not None and getattr(last, "finished_at", None) else 0
+        health = workflow.get("health") or {}
+        attention = health.get("attention") if isinstance(health.get("attention"), dict) else None
+        cards.append({"id": workflow["id"], "name": workflow.get("name"), "appId": workflow.get("appId"),
+                      "appName": workflow.get("appName"), "cron": workflow.get("cron"),
+                      "timezone": workflow.get("timezone"), "enabled": bool(workflow.get("enabled")),
+                      "nextAt": workflow.get("nextAt"), "produces": workflow.get("produces"),
+                      "running": workflow["id"] in running, "threadId": workflow.get("lastThreadId"),
+                      "last": last_result(last), "needsYou": waiting + drafts, "drafts": drafts,
+                      "attention": ({"kind": attention.get("kind"), "words": attention.get("words")} if attention
+                                    else None)})
+
+    def order(card):
+        scheduled = card["enabled"] and card["nextAt"] is not None
+        last_at = (card["last"] or {}).get("at") or 0
+        return (0 if scheduled else 1, card["nextAt"] if scheduled else -last_at)
+    cards.sort(key=order)
+    return cards[:JOBS]
+
+
+def summary(runtime, since_ms=None, now=None):
+    now = time.time() if now is None else now
+    with runtime.lock:
+        runs = dict(runtime.runs)
+    try:
+        workflows = runtime.workflows.list_with_health() if getattr(runtime, "workflows", None) is not None else []
+        running = runtime.workflows.running() if workflows else {}
+    except Exception:  # noqa: BLE001 -- a journal that can't list workflows leaves Home its counts
+        workflows, running = [], {}
+    try:
+        inbox_items = runtime.inbox().get("items") or []
+    except Exception:  # noqa: BLE001
+        inbox_items = []
+    week_from = usage.week_start(now)
+    oldest = min((_ms(run.created_at) for run in runs.values()), default=None)
+    partial = len(runs) >= HISTORY and oldest is not None and oldest > week_from
+    try:
+        spent = round(runtime.journal.spend_since(week_from), 6)
+    except Exception:  # noqa: BLE001 -- an unreadable ledger is no spend line, never a made-up one
+        spent = None
+    try:
+        plan = runtime.journal.plan_since(week_from)
+        plan_tokens, equivalent = plan["tokens"], plan["apiEquivalentUsd"]
+    except Exception:  # noqa: BLE001 -- as with spend: no line rather than a made-up one
+        plan_tokens = equivalent = None
+    week = {"from": round(week_from), **counts(runs.values(), week_from), "spentUsd": spent, "partial": partial,
+            "planTokens": plan_tokens, "apiEquivalentUsd": round(equivalent, 6) if equivalent is not None else None}
+    out = {"jobs": jobs(workflows, runs, inbox_items, running), "jobCount": len(workflows), "week": week,
+           "needsYou": len(inbox_items), "now": _ms(now)}
+    if isinstance(since_ms, (int, float)) and not isinstance(since_ms, bool) and 0 < since_ms <= _ms(now):
+        out["since"] = {"at": round(since_ms), **counts(runs.values(), since_ms)}
+    return out