mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/harness/prewarm.py

@@ -0,0 +1,213 @@
+"""Prewarm (SPEC §3.1 F8): ready the phone while the person types; it never acts or touches a phone running a task."""
+
+import dataclasses
+import logging
+import threading
+import time
+from concurrent import futures
+from urllib.parse import quote
+
+from ..compose import build_target_driver
+from ..journal import JournalError, Lease
+from ..run_executor import RunExecutor
+from ..wda.frame_clock import attach_frame_clock
+
+log = logging.getLogger("mobster.harness")
+
+SCREEN_TTL = 3.0         # seconds a prewarmed screen read may be reused for
+MIN_INTERVAL = 2.0       # a second prewarm of one phone within this answers from the first
+WAIT = 1.5               # how long the route waits for the warm-up before answering 202
+OBSERVE_TIMEOUT = 5.0
+SPRINGBOARD = "com.apple.springboard"
+
+
+@dataclasses.dataclass
+class Warm:
+    url: str
+    session: str
+    snapshot: object
+    clock: object
+    read_started: float
+
+
+_lock = threading.Lock()
+_screens = {}      # WDA url -> Warm
+_jobs = {}         # WDA url -> (Future, started monotonic, result dict)
+_workers = RunExecutor()
+
+
+def _close_clock(clock):
+    try:
+        if clock is not None:
+            clock.close()
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _drop(url, warm=None):
+    """Forget ``url``'s screen (only ``warm`` when given) and release its clock."""
+    with _lock:
+        current = _screens.get(url)
+        if current is None or (warm is not None and current is not warm):
+            return
+        del _screens[url]
+    _close_clock(current.clock)
+
+
+def _lease_free(url):
+    """True when no Mobster process holds this phone's lease now (taken and let go at once)."""
+    try:
+        lease = Lease.device(url.rstrip("/"), wait=0)
+    except JournalError:
+        return False
+    except Exception:  # noqa: BLE001 -- can't tell: treat it as busy, never as free
+        return False
+    lease.close()
+    return True
+
+
+def release(url):
+    """Let go of ``url``'s kept screen and its frame clock: the phone has been idle."""
+    _drop(url)
+
+
+def _owner_active(url):
+    from .. import owner_presence
+    return owner_presence.is_owner_active(url)
+
+
+def _busy(runtime, phone):
+    try:
+        if runtime.run_on(phone) is not None:
+            return True
+    except Exception:  # noqa: BLE001
+        return True
+    return not _lease_free(phone.wda_url)
+
+
+def _warm(runtime, phone, result):
+    """Warm ``phone`` up; fills ``result["warmed"]``. Never raises."""
+    url = phone.wda_url
+    driver = None
+    try:
+        if _owner_active(url):
+            # The owner is using the phone: a session or screen read now would reach into their hands.
+            result["reason"] = "owner_active"
+            return
+        if _busy(runtime, phone):
+            result["reason"] = "busy"
+            return
+        session = phone.wda_session()
+        if not session:
+            result["reason"] = "no_session"
+            return
+        driver = build_target_driver(wda_url=url, session=session)
+        tune = getattr(driver, "tune", None)
+        if callable(tune):
+            tune(rich=True, glide=True)
+        result["warmed"].append("wda")
+        video = getattr(phone, "video", None)
+        clock = attach_frame_clock(driver, video) if video is not None else None
+        if clock is None or _busy(runtime, phone):
+            return
+        started = time.monotonic()
+        observe = getattr(driver, "observe_ready", None) or driver.observe
+        snapshot = observe(timeout=OBSERVE_TIMEOUT)
+        read_started = float(getattr(snapshot, "read_started", 0.0) or started)
+        driver.frame_clock = None   # the clock outlives this driver, for SCREEN_TTL
+        warm = Warm(url, session, snapshot, clock, read_started)
+        with _lock:
+            old, _screens[url] = _screens.get(url), warm
+        if old is not None:
+            _close_clock(old.clock)
+        timer = threading.Timer(SCREEN_TTL + 0.5, _drop, args=(url, warm))
+        timer.daemon = True
+        timer.start()
+        result["warmed"].append("screen")
+    except Exception as error:  # noqa: BLE001 -- a cold or busy phone is never an error here
+        result.setdefault("reason", type(error).__name__)
+        log.info("prewarm stopped: %s", type(error).__name__)
+    finally:
+        if driver is not None:
+            clock = getattr(driver, "frame_clock", None)
+            if clock is not None:
+                driver.frame_clock = None
+                _close_clock(clock)
+            try:
+                driver.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def prewarm(runtime, device=None, *, wait=WAIT):
+    """Warm the phone ``device`` names (None: the one a new task runs on)."""
+    phone = runtime.resolve_device(device)
+    url = getattr(phone, "wda_url", None)
+    if not url:
+        return {"warmed": [], "pending": False, "reason": "no_phone"}
+    if _owner_active(url):
+        return {"warmed": [], "pending": False, "reason": "owner_active"}
+    now = time.monotonic()
+    with _lock:
+        job = _jobs.get(url)
+        if job is None or (job[0].done() and now - job[1] >= MIN_INTERVAL):
+            result = {"warmed": []}
+            job = _jobs[url] = (_workers.submit("mobster-prewarm", _warm, runtime, phone, result), now, result)
+    warming, _, result = job
+    futures.wait((warming,), max(0.0, wait))
+    out = {"warmed": list(result["warmed"]), "pending": not warming.done()}
+    if result.get("reason"):
+        out["reason"] = result["reason"]
+    return out
+
+
+def take(driver, run_context=None, *, now=None):
+    """The prewarmed read of ``driver``'s phone as its first screen, or None. (snapshot, age in seconds)."""
+    url = getattr(driver, "url", None)
+    if not url:
+        return None
+    with _lock:
+        warm = _screens.pop(url, None)
+    if warm is None:
+        return None
+    try:
+        now = time.monotonic() if now is None else now
+        age = now - warm.read_started
+        if age > SCREEN_TTL or age < 0:
+            return None
+        if not str(getattr(driver, "prefix", "")).endswith("/" + quote(warm.session, safe="")):
+            return None
+        expected = getattr(run_context, "app_bundle", None) or SPRINGBOARD
+        if getattr(warm.snapshot, "bundle_id", None) != expected:
+            return None
+        from ..wda.guards import STILL_MARGIN
+        still = warm.clock.still_for()
+        if still is None or now - still > warm.read_started - STILL_MARGIN:
+            return None   # something on screen changed since the read began (or the stream can't say)
+        # Unchanged since the read: the latest the run's own clock can vouch for, so its first action reuses it.
+        own = getattr(getattr(driver, "frame_clock", None), "still_for", None)
+        try:
+            run_still = own() if callable(own) else None
+        except Exception:  # noqa: BLE001
+            run_still = None
+        started = max(warm.read_started, now - run_still if run_still is not None else now)
+        return dataclasses.replace(warm.snapshot, captured_at=now, read_started=started), age
+    except Exception:  # noqa: BLE001
+        return None
+    finally:
+        _close_clock(warm.clock)
+
+
+def close_all(runtime=None):
+    """Release every kept read and its clock (Runtime.close)."""
+    with _lock:
+        warms = list(_screens.values())
+        _screens.clear()
+    for warm in warms:
+        _close_clock(warm.clock)
+
+
+def reset_for_tests():
+    close_all()
+    with _lock:
+        _jobs.clear()

mobile_agent/harness/register.py

@@ -0,0 +1,43 @@
+"""Track `harness`'s registrations, staged so a register that raises leaves nothing registered."""
+
+
+def _bool(value, runtime):
+    if type(value) is not bool:
+        raise ValueError("askUser must be true or false")
+    return value
+
+
+def hints_route(request):
+    """GET /api/harness/hints: {apps: hints.health}: every app's hints by source (packs, replays,
+    the iOS knowledge base)."""
+    from pathlib import Path
+
+    from .. import hints
+    from ..api_routes import Response
+    state_db = getattr(getattr(request.runtime, "config", None), "state_db", None)
+    return Response.json({"apps": hints.health(Path(state_db).parent if state_db else None)})
+
+
+def register(api):
+    """``api`` is mobile_agent.harness_api."""
+    from .. import api_routes, journal, project_env
+    from . import checkpoints, prewarm, routes
+    from .tools import ask_user, watch
+
+    journal.register_schema(checkpoints.SCHEMA, checkpoints.VERSION, checkpoints.migrate)
+    api.register_run_field("resumeFrom", checkpoints.validate_resume_from)
+    api.register_run_field("askUser", _bool)
+    # A saved task's ${NAME}s come from this project's secrets (project_env.py); the goal keeps the placeholder.
+    api.register_run_field("projectEnv", project_env.validate_root)
+    api.register_pre_run(checkpoints.pre_run, order=0)
+    api.register_frontier_options(checkpoints.frontier_options)
+    api.register_tool(ask_user.factory, order=0)
+    api.register_tool(watch.factory, order=1)
+    api.register_service(lambda runtime: None, lambda runtime: (checkpoints.close(runtime), prewarm.close_all(runtime)))
+    for route in routes.ROUTES:
+        api_routes.register(route)
+    from .. import hints
+    api.register_run_listener(hints.HintListener())
+    api_routes.register(api_routes.Route("harness", "GET", "/api/harness/hints", hints_route, body="none"))
+    from ..integrations import routes as client_routes
+    client_routes.register_routes()

mobile_agent/harness/routes.py

@@ -0,0 +1,114 @@
+"""The harness track's HTTP API (seam S3, mobile_agent/docs/harness.md); none of its routes approves anything."""
+
+from ..api_errors import APIError
+from ..api_routes import HEADER_ORIGINS, Response, Route
+from ..steering import SteeringFull
+from . import checkpoints, control, prewarm, settings
+from .control import PAUSE_LIMIT_SECONDS
+
+NO_MESSAGES = "This task can't take messages while it works. Stop it, or wait for it to finish."
+NO_PAUSE = "This task can't pause. Stop it instead."
+FULL = "Mobster's agent has 10 messages it hasn't read yet. Wait for it to catch up."
+
+
+def _run(request):
+    runtime = request.runtime
+    with runtime.lock:
+        run = runtime.runs.get(request.params["id"])
+    if run is None:
+        raise APIError("Task not found", 404, "not_found")
+    return run
+
+
+def _steerable_now(run, unsupported, code):
+    if run.finished_at is not None:
+        raise APIError("This task has finished.", 409, "run_not_active")
+    if not run.steerable:
+        raise APIError(unsupported, 409, code)
+
+
+def source_of(request, given):
+    """The message's source: the request's origin label, or "voice" from the Mac app."""
+    origin = request.origin if request.origin in HEADER_ORIGINS else "cli"
+    if given is None or given == origin:
+        return origin
+    if given == "voice" and origin == "app":
+        return "voice"
+    raise ValueError("source can only be \"voice\", from the Mac app")
+
+
+def messages(request):
+    run = _run(request)
+    body = request.body or {}
+    if "control" in body:
+        if set(body) != {"control"} or body["control"] != "stop_after_step":
+            raise ValueError("The only control is \"stop_after_step\", on its own")
+        _steerable_now(run, NO_MESSAGES, "steer_unsupported")
+        control.request_stop_after(run.steering)
+        run.emit({"event": "stop_after_step_requested"})
+        return Response.json({"control": "stop_after_step"}, 202)
+    if set(body) - {"text", "source"} or not isinstance(body.get("text"), str) \
+            or body.get("source") is not None and not isinstance(body["source"], str):
+        raise ValueError("Send the message as text, 1 to 2,000 characters")
+    source = source_of(request, body.get("source"))
+    _steerable_now(run, NO_MESSAGES, "steer_unsupported")
+    try:
+        message = run.steer(body["text"], source)
+    except SteeringFull:
+        raise APIError(FULL, 429, "steering_full") from None
+    return Response.json({"message": message}, 202)
+
+
+def pause(request):
+    run = _run(request)
+    body = request.body or {}
+    if set(body) != {"paused"} or type(body["paused"]) is not bool:
+        raise ValueError("Send {\"paused\": true} to pause or {\"paused\": false} to continue")
+    _steerable_now(run, NO_PAUSE, "pause_unsupported")
+    control.set_paused(run.steering, body["paused"])
+    return Response.json({"run": run.public(include_events=False), "paused": body["paused"]})
+
+
+def pickup(request):
+    if request.body:
+        raise ValueError("Send an empty JSON object")
+    keys = request.headers.get_all("Idempotency-Key", []) if hasattr(request.headers, "get_all") else []
+    key = keys[0] if keys else None
+    run, replayed = checkpoints.pick_up(request.runtime, request.params["id"], idempotency_key=key,
+                                        origin=request.origin)
+    return Response.json({"run": run.public(), "replayed": replayed}, 200 if replayed else 201)
+
+
+def prewarm_route(request):
+    body = request.body or {}
+    if set(body) - {"device"} or body.get("device") is not None and not isinstance(body["device"], str):
+        raise ValueError("Send {} or {\"device\": \"<a device's id, UDID or name>\"}")
+    return Response.json(prewarm.prewarm(request.runtime, body.get("device")), 202)
+
+
+def state(runtime):
+    return {"askUser": settings.ask_user(runtime),
+            "askUserLimit": settings.ASK_USER_LIMIT, "pauseLimitSeconds": PAUSE_LIMIT_SECONDS,
+            "ledger": False, "earlyLaunch": False, "longRun": None}
+
+
+def harness_get(request):
+    return Response.json(state(request.runtime))
+
+
+def harness_post(request):
+    body = request.body or {}
+    if set(body) != {"askUser"} or type(body["askUser"]) is not bool:
+        raise ValueError("Send {\"askUser\": true} or {\"askUser\": false}")
+    settings.save(request.runtime, {"askUser": body["askUser"]})
+    return Response.json(state(request.runtime))
+
+
+ROUTES = (
+    Route("harness", "POST", r"/api/runs/{id}/messages", messages, max_bytes=8_000),
+    Route("harness", "POST", r"/api/runs/{id}/pause", pause, max_bytes=1_000),
+    Route("harness", "POST", r"/api/runs/{id}/pickup", pickup, max_bytes=1_000, idempotency=True),
+    Route("harness", "POST", r"/api/prewarm", prewarm_route, max_bytes=1_000),
+    Route("harness", "GET", r"/api/harness", harness_get, body="none"),
+    Route("harness", "POST", r"/api/harness", harness_post, max_bytes=1_000),
+)

mobile_agent/harness/settings.py

@@ -0,0 +1,66 @@
+"""Harness settings, kept in the run journal's ``harness_settings`` table (schema ``harness``)."""
+
+import json
+import os
+import threading
+import weakref
+
+DEFAULTS = {"askUser": True}
+ASK_USER_LIMIT = 2          # questions a task may ask
+_cache = weakref.WeakKeyDictionary()   # journal -> {key: value}
+_lock = threading.Lock()
+
+
+def ask_user_switch():
+    """The process-wide switch: on unless MOBSTER_ASK_USER says off."""
+    return os.environ.get("MOBSTER_ASK_USER", "on").strip().casefold() not in ("off", "0", "false", "no")
+
+
+def _journal(runtime):
+    return getattr(runtime, "journal", None)
+
+
+def load(runtime):
+    """Every setting, the saved value over the default."""
+    journal = _journal(runtime)
+    values = dict(DEFAULTS)
+    if journal is None or getattr(journal, "connection", None) is None:
+        return values
+    with _lock:
+        cached = _cache.get(journal)
+    if cached is not None:
+        return {**values, **cached}
+    saved = {}
+    try:
+        with journal.transaction() as connection:
+            rows = connection.execute("SELECT key, value FROM harness_settings").fetchall()
+        for key, raw in rows:
+            if key in DEFAULTS:
+                try:
+                    saved[key] = json.loads(raw)
+                except ValueError:
+                    pass
+    except Exception:  # noqa: BLE001 -- no table (the track is off) or no journal: the defaults
+        saved = {}
+    with _lock:
+        _cache[journal] = saved
+    return {**values, **saved}
+
+
+def save(runtime, changes):
+    """Save ``changes`` (validated by the caller). Returns every setting."""
+    journal = _journal(runtime)
+    if journal is None or getattr(journal, "connection", None) is None:
+        raise ValueError("Settings can't be saved without Mobster's task history")
+    with journal.transaction() as connection:
+        for key, value in changes.items():
+            connection.execute("INSERT INTO harness_settings(key, value) VALUES (?, ?) "
+                               "ON CONFLICT(key) DO UPDATE SET value=excluded.value", (key, json.dumps(value)))
+    with _lock:
+        _cache.pop(journal, None)
+    return load(runtime)
+
+
+def ask_user(runtime):
+    """Whether Mobster's agent may ask clarifying questions in tasks a person watches."""
+    return ask_user_switch() and load(runtime).get("askUser") is not False

mobile_agent/harness/tools/__init__.py

@@ -0,0 +1,67 @@
+"""The tool policy (SPEC §3.1 F7): which registered tools a Smart run offers its model."""
+
+import logging
+import re
+
+from ...agent_hooks import SkillContext
+
+log = logging.getLogger("mobster.harness")
+
+MAX_TOOLS = 8
+OP = re.compile(r"[A-Z][A-Z_]{1,30}")
+PROMPT_CHARS = 400
+
+
+def _default_ops():
+    from ...frontier import default_skills
+    return {getattr(skill, "op", None) for skill in default_skills()}
+
+
+def _why_not(skill, taken, run_context, context):
+    """None when ``skill`` may be offered, else a short reason for the log."""
+    op = getattr(skill, "op", None)
+    if not isinstance(op, str) or not OP.fullmatch(op) or op in taken:
+        return "its op is invalid or taken"
+    if not callable(getattr(skill, "prepare", None)) or not callable(getattr(skill, "perform", None)):
+        return "it has no prepare or perform"
+    raw = str(getattr(skill, "prompt", "") or "")
+    prompt = raw.strip()
+    prompt = prompt[2:] if prompt.startswith("- ") else prompt
+    if not prompt.startswith(op) or len(prompt) > PROMPT_CHARS or "\n" in raw.strip():
+        return "its prompt is not one line that starts with its op"
+    if getattr(skill, "interactive_only", False) and not getattr(run_context, "interactive", False):
+        return "nobody is watching this run"
+    available = getattr(skill, "available", None)
+    if callable(available):
+        try:
+            if not available(context):
+                return "it isn't available here"
+        except Exception:  # noqa: BLE001 -- a tool that can't say is not offered
+            return "its availability check failed"
+    return None
+
+
+def offered(skills, *, run_context=None, driver=None, guard=None, emit=None):
+    """``skills`` as the policy offers them (a tuple), the default skills first as given."""
+    from ...frontier import OPERATIONS
+    defaults = _default_ops()
+    context = SkillContext(driver=driver, request="", app_bundle=getattr(run_context, "app_bundle", None),
+                           emit=emit or (lambda event: None), guard=guard, run=run_context,
+                           clarify=getattr(run_context, "clarify", None))
+    out, taken, extra = [], set(OPERATIONS), 0
+    for skill in skills or ():
+        op = getattr(skill, "op", None)
+        if op in defaults and op not in taken:
+            taken.add(op)
+            out.append(skill)
+            continue
+        why = _why_not(skill, taken, run_context, context)
+        if why is None and extra >= MAX_TOOLS:
+            why = f"only {MAX_TOOLS} tools are offered at once"
+        if why is not None:
+            log.info("tool %r not offered: %s", op, why)
+            continue
+        taken.add(op)
+        extra += 1
+        out.append(skill)
+    return tuple(out)

mobile_agent/harness/tools/ask_user.py

@@ -0,0 +1,102 @@
+"""ASK_USER: Mobster's agent asks the person a clarifying question (SPEC §3.1 F2); an answer approves nothing."""
+
+import time
+
+from ...agent_hooks import Prepared, SkillResult
+from ...secret_filter import redact
+from ..settings import ASK_USER_LIMIT
+
+PROMPT = ("- ASK_USER text: only when the request can be read two ways the screen can't settle and a wrong guess would "
+          "change what is sent, bought, posted, deleted or answered. Never to confirm a send (that asks by itself). "
+          "Put up to 4 short answers after the question, each after \" | \", a person's with what tells them apart "
+          "after \" \u2014 \" (\"Which Sam? | Sam Lee \u2014 texted Tuesday | Sam Ortiz \u2014 ends 0142\").")
+QUESTION_CHARS, LABEL_CHARS, CHOICE_CHARS, MAX_CHOICES = 300, 80, 120, 6
+
+NO_QUESTION = "ASK_USER needs the question in text."
+CANT_ASK = ("Refused: this task can't ask the user. Decide from the request and the screen, or finish with BLOCKED "
+            "and say what you need to know.")
+ASKED_ENOUGH = ("You already asked the user twice in this task. Decide from the request and the screen, or finish "
+                "with BLOCKED and say what you need to know.")
+DECLINED = ("The user chose not to answer. Decide from the request and the screen, or finish with BLOCKED and say "
+            "what you need to know. Don't ask again.")
+NO_ANSWER = "Nobody answered Mobster's question in 10 minutes, so it stopped without doing anything more."
+STOPPED = "Stopped while Mobster waited for an answer to its question."
+
+
+def split(text):
+    """(question, choices) from "Question? | A | B": at most MAX_CHOICES distinct choices, none unless two or more."""
+    parts = [" ".join(part.split()) for part in str(text or "").split("|")]
+    question = parts[0][:QUESTION_CHARS]
+    choices, seen = [], set()
+    for part in parts[1:]:
+        label = part[:CHOICE_CHARS]
+        if label and label.casefold() not in seen:
+            seen.add(label.casefold())
+            choices.append({"id": f"c{len(choices) + 1}", "label": label})
+        if len(choices) == MAX_CHOICES:
+            break
+    return question, (choices if len(choices) >= 2 else [])
+
+
+def feedback_for(answer, choices):
+    """(feedback for the model, run-ending status or None) for the asker's answer."""
+    answer = answer if isinstance(answer, str) else "denied"
+    if answer.startswith("answer:") or answer.startswith("redirected:"):
+        text = " ".join(answer.split(":", 1)[1].split())[:500]
+        return f"The user answered your question: {text!r}. Go on with that.", None
+    if answer.startswith("choice:"):
+        chosen = answer.split(":", 1)[1]
+        label = next((c["label"] for c in choices if c["id"] == chosen), chosen)
+        return f"The user answered your question: {label!r}. Go on with that.", None
+    if answer == "timeout":
+        return NO_ANSWER, "approval_timeout"
+    if answer == "stopped":
+        return STOPPED, "stopped"
+    return DECLINED, None
+
+
+class AskUser:
+    """agent_hooks.Skill: ASK_USER (one instance per run: it counts its questions)."""
+
+    op = "ASK_USER"
+    prompt = PROMPT
+    needs_target = False
+    interactive_only = True
+
+    def __init__(self, limit=ASK_USER_LIMIT, clock=time.monotonic):
+        self.limit, self.clock, self.asked = limit, clock, 0
+
+    def available(self, ctx):
+        return callable(getattr(ctx, "clarify", None))
+
+    def prepare(self, ctx, act, snapshot):
+        return Prepared(None)   # a question is not a commit: nothing to approve
+
+    def perform(self, ctx, prepared, act, snapshot):
+        question, choices = split(redact(str(act.get("text") or "")))
+        if not question:
+            return SkillResult(NO_QUESTION)
+        clarify = getattr(ctx, "clarify", None)
+        if not callable(clarify):
+            return SkillResult(CANT_ASK)
+        if self.asked >= self.limit:
+            return SkillResult(ASKED_ENOUGH)
+        self.asked += 1
+        started = self.clock()
+        answer = clarify({"kind": "clarify", "operation": self.op, "label": question[:LABEL_CHARS],
+                          "question": question, "choices": choices, "allow_text": True})
+        waited = max(0.0, self.clock() - started)
+        feedback, status = feedback_for(answer, choices)
+        return SkillResult(feedback, changed=False, waited=waited, status=status)
+
+
+def factory(ctx):
+    """register_tool's factory: an AskUser for a run a person watches, else None."""
+    from ..settings import ask_user
+    if not getattr(ctx, "interactive", False) or getattr(ctx, "engine", None) != "smart":
+        return None
+    if (ctx.extras or {}).get("askUser") is not True:
+        return None
+    if not ask_user(ctx.runtime):
+        return None
+    return AskUser()