mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/usage.py

@@ -0,0 +1,184 @@
+"""Durable workspace usage independent of the bounded task history."""
+
+import json
+import time
+from datetime import datetime
+
+from .costs import NANODOLLARS
+
+# Who priced a call: Jev, Gemini on Vertex, an OpenAI-compatible helper, OpenAI or Anthropic (the Smart engine), or
+# a plan or provider from Settings › Models (harness_api.EngineHooks.model_routes; a plan call costs 0).
+# The coding agents a task can run on (ai_plans.AGENT_ENGINES) record their runs under their own names.
+PROVIDERS = frozenset({"typesafe", "google", "helper", "openai", "anthropic", "claude_code", "codex", "gemini"})
+BILLINGS = frozenset({"plan", "api_key"})
+# Columns added after the first ledger: added in place to a ledger that predates them (NULL in old rows: unknown).
+ADDED_COLUMNS = (("cache_read_tokens", "INTEGER"), ("cache_write_tokens", "INTEGER"), ("billing", "TEXT"),
+                 ("api_equivalent_nanodollars", "INTEGER"))
+MAX_COUNT = 9_007_199_254_740_991
+
+
+def known_provider(provider):
+    from .harness_api import hooks
+    return provider in PROVIDERS or hooks().model_routes().get(provider) is not None
+
+
+def initialize(connection):
+    connection.executescript("""
+        CREATE TABLE IF NOT EXISTS usage_tracking (
+            id INTEGER PRIMARY KEY CHECK(id=1), since REAL NOT NULL);
+        CREATE TABLE IF NOT EXISTS usage_calls (
+            run_id TEXT NOT NULL, call_id TEXT NOT NULL,
+            provider TEXT NOT NULL, model TEXT NOT NULL,
+            started_at REAL NOT NULL, finished_at REAL,
+            input_tokens INTEGER, output_tokens INTEGER, total_tokens INTEGER,
+            cost_nanodollars INTEGER, PRIMARY KEY(run_id,call_id));
+        CREATE TABLE IF NOT EXISTS usage_limits (
+            provider TEXT PRIMARY KEY, data TEXT NOT NULL, at REAL NOT NULL);
+    """)
+    present = {row[1] for row in connection.execute("PRAGMA table_info(usage_calls)")}
+    for name, kind in ADDED_COLUMNS:
+        if name not in present:
+            connection.execute(f"ALTER TABLE usage_calls ADD COLUMN {name} {kind}")
+    connection.execute("INSERT OR IGNORE INTO usage_tracking VALUES (1,?)", (time.time() * 1000,))
+
+
+def _count(value):
+    return value is None or (type(value) is int and 0 <= value <= MAX_COUNT)
+
+
+def record_call(connection, run_id, event):
+    """Called in the same transaction as the run event it records."""
+    kind = event.get("event")
+    if kind == "agent_limits":
+        record_limits(connection, event)
+        return
+    if kind not in {"inference_started", "inference_finished"}:
+        return
+    call_id, provider, model = (event.get(key) for key in ("call_id", "provider", "model"))
+    if (not isinstance(call_id, str) or not 1 <= len(call_id) <= 128
+            or not known_provider(provider)
+            or not isinstance(model, str) or not 1 <= len(model) <= 200):
+        raise ValueError("Invalid inference usage identity")
+    if kind == "inference_started":
+        connection.execute("""INSERT INTO usage_calls
+            (run_id,call_id,provider,model,started_at) VALUES (?,?,?,?,?)""",
+            (run_id, call_id, provider, model, event["timestamp"]))
+        return
+    usage = event.get("usage", {})
+    counts = [usage.get(key) for key in ("input_tokens", "output_tokens", "total_tokens")]
+    # Smart's calls say cached_input_tokens; the coding agents' say cache_read_tokens.
+    cache = [usage.get("cache_read_tokens", usage.get("cached_input_tokens")), usage.get("cache_write_tokens")]
+    cost, equivalent = event.get("cost_nanodollars"), event.get("api_equivalent_nanodollars")
+    if not all(_count(n) for n in [*counts, *cache, cost, equivalent]):
+        raise ValueError("Invalid inference usage counts")
+    billing = event.get("billing")
+    if billing is None and event.get("cost_basis") == "plan":
+        billing = "plan"
+    if billing is not None and billing not in BILLINGS:
+        raise ValueError("Invalid inference billing")
+    changed = connection.execute("""UPDATE usage_calls SET model=?,finished_at=?,
+        input_tokens=?,output_tokens=?,total_tokens=?,cost_nanodollars=?,
+        cache_read_tokens=?,cache_write_tokens=?,billing=?,api_equivalent_nanodollars=?
+        WHERE run_id=? AND call_id=? AND provider=? AND finished_at IS NULL""",
+        (model, event["timestamp"], *counts, cost, *cache, billing, equivalent, run_id, call_id, provider)).rowcount
+    if changed != 1:
+        raise ValueError("Inference completion must match one pending call")
+
+
+# What a coding agent says of its plan's usage limits (Claude Code's rate_limit_event): kept per agent, newest only.
+LIMIT_STATUSES = frozenset({"allowed", "allowed_warning", "rejected"})
+
+
+def record_limits(connection, event):
+    """Keep the newest limit signal an agent's run reported (ai_plans.cli.limit_signal's shape). Anything malformed is
+    dropped: a limit reading is a hint, never a reason to stop a run."""
+    provider, limits = event.get("agent"), event.get("limits")
+    if provider not in PROVIDERS or not isinstance(limits, dict) or limits.get("status") not in LIMIT_STATUSES:
+        return
+    data = json.dumps(limits, sort_keys=True)
+    if len(data) > 2000:
+        return
+    connection.execute("INSERT INTO usage_limits VALUES (?,?,?) ON CONFLICT(provider) DO UPDATE SET data=excluded.data,"
+                       "at=excluded.at", (provider, data, event["timestamp"]))
+
+
+def limits(connection):
+    """{agent: {...the limit signal, "at": ms}} for every agent that reported one."""
+    out = {}
+    for provider, data, at in connection.execute("SELECT provider,data,at FROM usage_limits ORDER BY provider"):
+        try:
+            out[provider] = {**json.loads(data), "at": at}
+        except ValueError:
+            continue
+    return out
+
+
+def summary(connection, run_id=None):
+    where, params = ("WHERE run_id=?", (run_id,)) if run_id else ("", ())
+    rows = connection.execute(f"""SELECT provider,model,billing,count(*),
+        count(total_tokens),sum(input_tokens),sum(output_tokens),sum(total_tokens),
+        sum(cost_nanodollars),count(cost_nanodollars),
+        sum(CASE WHEN finished_at IS NULL THEN 1 ELSE 0 END),
+        sum(cache_read_tokens),sum(cache_write_tokens),sum(api_equivalent_nanodollars)
+        FROM usage_calls {where} GROUP BY provider,model,billing ORDER BY provider,model,billing""", params).fetchall()
+    providers = []
+    for (provider, model, billing, calls, reported, incoming, outgoing, total, cost, priced, pending, cache_read,
+         cache_write, equivalent) in rows:
+        providers.append({"provider": provider, "model": model, "billing": billing, "calls": calls,
+            "reported_calls": reported, "input_tokens": incoming, "output_tokens": outgoing,
+            "total_tokens": total, "estimated_usd": cost / NANODOLLARS if cost is not None else None,
+            "priced_calls": priced, "unreported_calls": calls - reported,
+            "unpriced_calls": calls - priced, "in_flight_calls": pending,
+            "cache_read_tokens": cache_read, "cache_write_tokens": cache_write,
+            "api_equivalent_usd": equivalent / NANODOLLARS if equivalent is not None else None})
+    totals = {key: sum(p[key] for p in providers) for key in (
+        "calls", "reported_calls", "priced_calls", "unreported_calls", "unpriced_calls", "in_flight_calls")}
+    for key in ("input_tokens", "output_tokens", "total_tokens", "estimated_usd", "cache_read_tokens",
+                "cache_write_tokens", "api_equivalent_usd"):
+        known = [p[key] for p in providers if p[key] is not None]
+        totals[key] = sum(known) if known else None
+    plan = [p for p in providers if p["billing"] == "plan" and p["total_tokens"] is not None]
+    totals["plan_tokens"] = sum(p["total_tokens"] for p in plan) if plan else None
+    return {"tracked_since": connection.execute("SELECT since FROM usage_tracking WHERE id=1").fetchone()[0],
+            "updated_at": time.time() * 1000, "scope": "mobster_workspace",
+            "cost_basis": "published_rate", "totals": totals, "providers": providers,
+            "limits": limits(connection) if not run_id else {}}
+
+
+def close_pending(connection, run_id, timestamp):
+    # Terminal/recovered runs cannot leave a perpetual 'in flight' counter.
+    # Unknown usage remains NULL, including interrupted requests that may bill.
+    connection.execute("UPDATE usage_calls SET finished_at=? WHERE run_id=? AND finished_at IS NULL",
+                       (timestamp, run_id))
+
+
+def month_start(now=None):
+    """Milliseconds at the start of this calendar month in the Mac's local time zone."""
+    # Keep this local and naive so timestamp() uses the offset at the month's start,
+    # which can differ from today's offset across a daylight-saving transition.
+    now = datetime.fromtimestamp(time.time() if now is None else now)
+    return now.replace(day=1, hour=0, minute=0, second=0, microsecond=0).timestamp() * 1000
+
+
+def week_start(now=None):
+    """Milliseconds at the start of this week (Monday, 00:00) in the Mac's local time zone."""
+    from datetime import timedelta
+    local = datetime.fromtimestamp(time.time() if now is None else now)  # naive local time: DST-safe below
+    monday = (local - timedelta(days=local.weekday())).replace(hour=0, minute=0, second=0, microsecond=0)
+    return monday.timestamp() * 1000
+
+
+def spend_since(connection, since_ms):
+    """Published-rate spend of the calls started at or after ``since_ms`` (unpriced calls add nothing)."""
+    cost = connection.execute("SELECT sum(cost_nanodollars) FROM usage_calls WHERE started_at>=?",
+                              (since_ms,)).fetchone()[0]
+    return (cost or 0) / NANODOLLARS
+
+
+def plan_since(connection, since_ms):
+    """Tokens on the person's plans since ``since_ms`` and what they'd cost at list price: {"tokens",
+    "apiEquivalentUsd"}
+    (None where nothing was reported)."""
+    tokens, equivalent = connection.execute("""SELECT sum(total_tokens),sum(api_equivalent_nanodollars)
+        FROM usage_calls WHERE started_at>=? AND billing='plan'""", (since_ms,)).fetchone()
+    return {"tokens": tokens, "apiEquivalentUsd": equivalent / NANODOLLARS if equivalent is not None else None}

mobile_agent/verify/__main__.py

@@ -0,0 +1,41 @@
+"""`python -m mobile_agent.verify …`: the same command as `mobster verify`, with the same flags and exit codes."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def build_parser():
+    from .. import cli_parser as mobster
+    from ..devtools import TEXT
+    from . import cli
+    description, epilog = TEXT["verify"]
+    parser = argparse.ArgumentParser(prog="mobster verify", description=description, epilog=epilog,
+                                     formatter_class=mobster.Formatter)
+    cli.add_arguments(parser, {"env_option": mobster._env_option, "path_type": mobster.path_type,
+                               "bounded": mobster._bounded})
+    mobster._tidy(parser)  # "show this help and exit", as under `mobster`
+    return parser
+
+
+def main(argv=None):
+    from .. import tls
+    from ..config import load_env_file
+    from . import cli
+    args = build_parser().parse_args(argv)
+    env_file = getattr(args, "env_file", None)
+    if env_file is None and os.environ.get("MOBSTER_ENV_FILE"):
+        env_file = Path(os.environ["MOBSTER_ENV_FILE"]).expanduser()
+    if env_file:
+        for warning in load_env_file(env_file).warnings:
+            print(f"mobster: {warning}", file=sys.stderr, flush=True)
+    tls.ensure_ca_bundle()
+    try:
+        return cli.run(args)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mobile_agent/verify/a11y.py

@@ -0,0 +1,189 @@
+"""The accessibility audit (docs/accessibility.mdx): rules on the trees a run reads, with no model or pixels."""
+
+import json
+import re
+
+from .conditions import CONTENT_SIZES
+from .tree import SCROLL_CONTAINERS, STRUCTURAL
+
+NAME = "a11y"
+MIN_TARGET = 44.0
+EDGE = 1.0   # points of slack for rounding in frames
+CONTROLS = frozenset({"Button", "Switch", "Toggle", "Link", "Slider", "Stepper", "TextField", "SecureTextField",
+                      "SearchField", "TextView"})
+# Controls whose own value is not a name ("0", "1", "50%"), so only a label names them.
+ENTRY = frozenset({"TextField", "SecureTextField", "SearchField", "TextView"})
+TARGETS = frozenset({"Button", "Link", "Switch", "Toggle"})
+TEXT = frozenset({"StaticText", "Button", "Link", "TextField", "SecureTextField", "SearchField", "TextView"})
+LARGE_SIZES = CONTENT_SIZES[CONTENT_SIZES.index("extra-large"):]
+GUIDELINES = {"control-no-label": "WCAG 4.1.2", "target-too-small": "HIG 44 pt", "image-no-label": "WCAG 1.1.1",
+              "text-clipped": "WCAG 1.4.4", "duplicate-label": "WCAG 2.4.6", "label-unhelpful": "WCAG 2.4.6",
+              "unreachable-element": "WCAG 2.1.1"}
+LEVELS = ("warn", "strict")
+GENERIC = frozenset({"button", "image", "icon", "img", "picture", "photo", "untitled", "label", "view", "item"})
+FILE_LABEL = re.compile(r".+\.(png|jpe?g|pdf|svg|gif|heic|webp)", re.I)
+CODE_LABEL = re.compile(r"[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+")
+
+
+def large_text(content_size):
+    return content_size in LARGE_SIZES
+
+
+def _describe(node):
+    name = f"{node.role} \"{node.label}\"" if node.label.strip() else (
+        f"{node.role} (id {node.identifier})" if node.identifier else node.role)
+    x, y, w, h = node.rect
+    return name, f"at {x:g}, {y:g}, {w:g} x {h:g} pt"
+
+
+def _finding(rule, node, message, frame):
+    name, where = _describe(node)
+    x, y, w, h = node.rect
+    return {"id": rule, "audit": NAME, "guideline": GUIDELINES[rule], "level": "fail", "frame": frame,
+            "message": f"{name} {where}: {message}", "evidence": f"{name} {where}",
+            "element": {"role": node.role, "label": node.label, "identifier": node.identifier, "path": node.path,
+                        "rect": [x, y, w, h]}}
+
+
+def _ancestors(path):
+    while "/" in path.strip("/"):
+        path = path.rsplit("/", 1)[0]
+        yield path
+
+
+def audit_tree(tree, *, content_size=None, frame=None):
+    """The findings of one screen's tree."""
+    shown = tree.shown()
+    by_path = {node.path: node for node in tree.nodes}
+    labelled_controls = {node.path for node in shown if node.role in CONTROLS and node.label.strip()}
+    width = tree.size[0]
+    out = []
+    for node in shown:
+        x, y, w, h = node.rect
+        if node.role in CONTROLS and not node.label.strip() and not (node.role in ENTRY and node.placeholder.strip()):
+            out.append(_finding("control-no-label", node,
+                                "it has no accessibility label, so VoiceOver can't say what it does. Give it one "
+                                "(SwiftUI: .accessibilityLabel; UIKit: accessibilityLabel).", frame))
+        if node.role in TARGETS and w > 0 and h > 0 and (w < MIN_TARGET or h < MIN_TARGET):
+            out.append(_finding("target-too-small", node,
+                                f"the tap target is {w:g} x {h:g} pt, under {MIN_TARGET:g} x {MIN_TARGET:g}. "
+                                "Make the control or its tappable area at least 44 pt each way (SwiftUI: "
+                                ".frame(minWidth: 44, minHeight: 44) or .contentShape).", frame))
+        if node.role == "Image" and not node.label.strip() and w > 1 and h > 1 \
+                and not any(path in labelled_controls for path in _ancestors(node.path)):
+            out.append(_finding("image-no-label", node,
+                                "the image has no label. Label it, or hide it from accessibility if it is "
+                                "decoration (SwiftUI: .accessibilityHidden(true)).", frame))
+        if (node.role in CONTROLS or node.role == "Image") and node.label.strip() and unhelpful(node.label) \
+                and not (node.role in ENTRY):
+            out.append(_finding("label-unhelpful", node,
+                                f"the label \"{node.label.strip()}\" doesn't say what it is for. Name the action or "
+                                "the picture (SwiftUI: .accessibilityLabel).", frame))
+        if large_text(content_size) and node.role in TEXT and node.label.strip() and w > 0 and h > 0:
+            clipped = _clipped(node, by_path, width)
+            if clipped:
+                out.append(_finding("text-clipped", node,
+                                    f"at the {content_size} text size it is {clipped}. Let the text wrap or the "
+                                    "container grow (SwiftUI: remove fixed frames and lineLimit).", frame))
+    out.extend(_duplicates(shown, frame))
+    out.extend(_unreachable(tree, by_path, frame))
+    return out
+
+
+def unhelpful(label):
+    text = label.strip()
+    return text.lower() in GENERIC or bool(FILE_LABEL.fullmatch(text)) or bool(CODE_LABEL.fullmatch(text))
+
+
+def _duplicates(shown, frame):
+    groups = {}
+    for node in shown:
+        if node.role in TARGETS and node.label.strip() and node.rect[2] > 0 and node.rect[3] > 0:
+            groups.setdefault((node.role, " ".join(node.label.split()).casefold()), []).append(node)
+    return [_finding("duplicate-label", nodes[0],
+                     f"{len(nodes)} {nodes[0].role.lower()}s on this screen are all labelled "
+                     f"\"{nodes[0].label.strip()}\", "
+                     "so VoiceOver reads them alike. Say what each one acts on (SwiftUI: .accessibilityLabel).", frame)
+            for nodes in groups.values() if len(nodes) > 1 and len({tuple(n.rect) for n in nodes}) > 1]
+
+
+def _unreachable(tree, by_path, frame):
+    width, height = tree.size
+    out = []
+    for node in tree.nodes:
+        x, y, w, h = node.rect
+        if node.role not in CONTROLS or not node.label.strip() or not node.enabled or w <= 0 or h <= 0:
+            continue
+        if not (x + w <= 0 or x >= width or y + h <= 0 or y >= height):
+            continue
+        if any(by_path[path].role in SCROLL_CONTAINERS for path in _ancestors(node.path) if path in by_path):
+            continue
+        out.append(_finding("unreachable-element", node,
+                            "its frame is wholly off the screen and it is in no scroll view, so nothing can reach it. "
+                            "Move it on screen, or remove it from the layout when it is meant to be hidden.", frame))
+    return out
+
+
+def _clipped(node, by_path, screen_width):
+    x, y, w, h = node.rect
+    ancestors = [by_path[path] for path in _ancestors(node.path) if path in by_path]
+    in_scroll = any(item.role in SCROLL_CONTAINERS for item in ancestors)
+    if x < -EDGE or x + w > screen_width + EDGE:
+        if not in_scroll:
+            return "wider than the screen"
+    parent = next((item for item in ancestors if item.role not in STRUCTURAL and item.rect[2] * item.rect[3] > 0), None)
+    if parent is not None and parent.role not in SCROLL_CONTAINERS:
+        px, py, pw, ph = parent.rect
+        if x < px - EDGE or x + w > px + pw + EDGE or y < py - EDGE or y + h > py + ph + EDGE:
+            return f"outside its {parent.role}"
+    return None
+
+
+def baseline_key(scope, finding):
+    """A finding's baseline key: the check's file, the rule, the role, label and identifier. Not the frame, so a layout
+    shift doesn't make an old finding new."""
+    element = finding["element"]
+    return json.dumps((scope, finding["id"], element["role"], element["label"], element["identifier"]),
+                      ensure_ascii=False, separators=(",", ":"))
+
+
+class Collector:
+    LIMIT = 60
+
+    def __init__(self, content_size=None, *, level="strict", baseline=frozenset(), scope=""):
+        self.content_size, self.level, self.baseline, self.scope = content_size, level, baseline, scope
+        self._seen, self._found = {}, []
+        self._keys = set()
+
+    def add(self, tree, frame=None):
+        fingerprint = tree.audit_fingerprint()
+        if fingerprint in self._seen:
+            if frame is not None:
+                start, end = self._seen[fingerprint]
+                for finding in self._found[start:end]:
+                    if finding["frame"] is None:
+                        finding["frame"] = frame
+            return True
+        if len(self._seen) >= self.LIMIT:
+            return False
+        start = len(self._found)
+        for finding in audit_tree(tree, content_size=self.content_size, frame=frame):
+            element = finding["element"]
+            key = (finding["id"], element["role"], element["label"], element["identifier"],
+                   tuple(round(n) for n in element["rect"]))
+            if key not in self._keys:
+                self._keys.add(key)
+                finding["key"] = baseline_key(self.scope, finding)
+                known = finding["key"] in self.baseline
+                finding["level"] = "known" if known else ("fail" if self.level == "strict" else "warn")
+                finding["baseline"] = known
+                self._found.append(finding)
+        self._seen[fingerprint] = (start, len(self._found))
+        return True
+
+    @property
+    def screens(self):
+        return len(self._seen)
+
+    def findings(self):
+        return list(self._found)