mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/run_delivery.py

@@ -0,0 +1,123 @@
+"""A finished result leaving Mobster by a person's click: "Send to" a saved destination, and "File as issue" in a
+connected tracker. Both ride the code that already sends (outlets' deliveries, ConnectorService.call), and both are
+the person's: the routes need the Mac app's session."""
+
+import time
+import uuid
+
+from .api_errors import APIError
+from .connectors import client as mcp
+from .connectors import issue as tracker
+from .connectors import service as connector_service
+from .connectors import store as connector_store
+from .connectors.skill import result_text
+from .journal import JournalError
+from .outlets import service as outlet_service
+from .outlets import webhook
+from .secret_filter import redact
+
+ISSUE_KEEP = 50
+TITLE_MAX = 120
+
+
+def _refuse(code, message, status=409):
+    return APIError(message, status, code)
+
+
+def send(runtime, run, destination):
+    """Queue ``run``'s result for the saved destination ``destination`` names:
+    the delivery, as the run view shows it."""
+    service = outlet_service.service_for(runtime)
+    if service is None:
+        raise _refuse("unavailable", "Sending results isn't available right now. Restart Mobster, then try again.",
+                      503)
+    if not service.store.destinations():
+        raise _refuse("no_destination", "No destination is saved yet. Add Slack, email or a webhook in Settings › "
+                                        "Connectors, then send the result.")
+    try:
+        row = service.find(destination)
+    except ValueError as error:
+        raise APIError(str(error), 404, "destination_not_found") from None
+    return {"delivery": service.public_delivery(service.enqueue(run.id, row["id"]))}
+
+
+def _text(run):
+    """The issue's title and text from the run's masked result (the same body a webhook gets)."""
+    body = webhook.payload(run)
+    title = " ".join(f"{run.goal or 'Mobster task'}".split())[:TITLE_MAX]
+    lines = [body["text"], "", f"Task: {redact(run.goal or '')}".strip(), f"Status: {body['status']}"]
+    if body.get("reason"):
+        lines.append(f"Why: {body['reason']}")
+    if run.device_name:
+        lines.append(f"Device: {run.device_name}")
+    lines += ["", f"Mobster run {run.id}"]
+    return title, "\n".join(lines)
+
+
+def _note(runtime, run, change):
+    with run.condition:
+        updated = change([dict(item) for item in run.issues])
+        if run.journal:
+            run.journal.annotate(run.id, {"issues": updated})  # JournalError: nothing is sent without this note
+        run.issues = updated
+    runtime.publish("runs", {"event": "run_issue", "runId": run.id})
+
+
+def file_issue(runtime, run, body):
+    """File ``run``'s result as one issue: the entry the run keeps ({"id", "tracker", "status", "url", ...}).
+    The attempt is noted on the run before the tool is called, and an answer that never came is never asked again."""
+    if (not isinstance(body, dict) or set(body) - {"tracker", "target", "again"}
+            or type(body.get("again", False)) is not bool):
+        raise ValueError('Send {"tracker": "GitHub", "target": {"owner": "...", "repo": "..."}} '
+                         '(tracker, target optional)')
+    target = tracker.clean_target(body.get("target"))
+    service = connector_service.service_for(runtime)
+    if service is None:
+        raise _refuse("unavailable", "Connectors aren't available right now. Restart Mobster, then try again.", 503)
+    row, refusal = tracker.pick(service.store.all(), body.get("tracker"))
+    if refusal:
+        raise _refuse(*refusal)
+    name = row["name"]
+    mine = [item for item in run.issues if item.get("connector") == row["id"]]
+    for item in mine:
+        if item["status"] in ("filing", "unknown"):
+            raise _refuse("outcome_unknown", f"Mobster doesn't know whether {name} got this issue. Check {name} "
+                                             "before filing it again; Mobster won't send it twice on its own.")
+    if mine and not body.get("again"):
+        raise _refuse("already_filed", f"This result is already filed in {name}. Send again with \"again\": true "
+                                       "to file another.")
+    title, text = _text(run)
+    chosen = tracker.tool_for(row, target, title, text)
+    if chosen is None:
+        raise _refuse("tool_missing", f"{name} has no tool Mobster can file an issue with. Test it in Settings › "
+                                      "Connectors, then try again.")
+    tool, arguments = chosen
+    if connector_store.mode_of(row, tool) == "off":
+        raise _refuse("tool_blocked", f"{name}: {tool} is blocked in Settings › Connectors, so nothing was filed.")
+    entry = {"id": uuid.uuid4().hex[:12], "connector": row["id"], "tracker": name, "tool": tool, "status": "filing",
+             "url": None, "error": None, "at": int(time.time() * 1000)}
+    try:
+        _note(runtime, run, lambda items: [entry, *items][:ISSUE_KEEP])
+    except JournalError:
+        raise _refuse("journal_unavailable", "Mobster couldn't save that. Try again.", 503) from None
+    status, url, error = "filed", None, None
+    try:
+        result = service.call(row, tool, arguments)
+        text_back = result_text(result)
+        if result.get("isError"):
+            status, error = "failed", redact(text_back)[:200]
+        else:
+            url = tracker.link_of(text_back)
+    except mcp.OutcomeUnknown:
+        status, error = "unknown", f"{name} didn't answer. The issue may exist, so Mobster won't send it again."
+    except mcp.ConnectorError as problem:
+        status, error = "failed", redact(problem.message)[:200]
+
+    def settle(items):
+        return [{**item, "status": status, "url": url, "error": error} if item["id"] == entry["id"] else item
+                for item in items]
+    try:
+        _note(runtime, run, settle)
+    except JournalError:
+        run.issues = settle(run.issues)  # the answer stays in memory; the note on disk keeps "filing"
+    return {"issue": next(item for item in run.issues if item["id"] == entry["id"])}

mobile_agent/run_executor.py

@@ -0,0 +1,200 @@
+"""One owner for the threads a run starts: a cancel token and a bounded pool of named workers."""
+
+import logging
+import threading
+import time
+from collections import deque
+from concurrent.futures import Future
+from dataclasses import dataclass
+from enum import StrEnum
+
+log = logging.getLogger("mobster.run_executor")
+
+KEPT = 32  # finished workers ``workers()`` still names, newest last
+
+
+class CancelToken:
+    """Set once, never cleared. ``CancelToken(parent)`` is set when its parent is, and can be set alone. ``set``,
+    ``is_set`` and ``wait`` are threading.Event's, so a run's Stop (``Run.stop``) is one: every ``run.stop.set()``
+    reaches the tokens and executors made from it."""
+
+    def __init__(self, parent=None):
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._callbacks = []
+        if parent is not None:
+            parent.on_cancel(self.set)
+
+    def set(self):
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._event.set()
+            callbacks, self._callbacks = self._callbacks, []
+        for fn in callbacks:
+            _call(fn)
+
+    def is_set(self):
+        return self._event.is_set()
+
+    def wait(self, timeout=None):
+        return self._event.wait(timeout)
+
+    def on_cancel(self, fn):
+        """Call ``fn()`` once when the token is set, or now when it already is. It runs on the thread that sets the
+        token, inside whatever locks that thread holds (Runtime.stop_run holds the runtime's and the run's), so it
+        must be short and never wait."""
+        with self._lock:
+            if not self._event.is_set():
+                self._callbacks.append(fn)
+                return
+        _call(fn)
+
+
+def _call(fn):
+    try:
+        fn()
+    except Exception:  # noqa: BLE001 -- a hook never reaches whoever pressed Stop
+        log.exception("a cancel hook failed")
+
+
+class Cancelled(RuntimeError):
+    """``RunExecutor.submit`` after its token was set: the run is stopping, so nothing new starts."""
+
+
+class State(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    DONE = "done"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True)
+class Worker:
+    name: str
+    state: State
+    error: str = ""  # a failed worker's exception type
+
+
+class _Job:
+    __slots__ = ("name", "fn", "args", "future", "state", "thread")
+
+    def __init__(self, name, fn, args):
+        self.name, self.fn, self.args = name, fn, args
+        self.future, self.state, self.thread = Future(), State.QUEUED, None
+
+
+class RunExecutor:
+    """The threads one run starts. At most ``max_workers`` named daemon workers run at once and the rest wait their
+    turn. They all read one ``token``, a child of ``parent`` (the run's Stop): ``cancel()`` sets it, drops the work
+    still waiting and refuses more, and ``join()`` waits for the work already running."""
+
+    def __init__(self, parent=None, *, max_workers=4):
+        if max_workers < 1:
+            raise ValueError("A run executor needs at least one worker")
+        self.token = CancelToken(parent)
+        self._max = max_workers
+        self._condition = threading.Condition()
+        self._live = []  # queued and running jobs, oldest first
+        self._finished = deque(maxlen=KEPT)
+        self.token.on_cancel(self._drop_queued)
+
+    def submit(self, name, fn, *args):
+        """Run ``fn(*args)`` on a daemon thread named ``name`` and return its Future. What ``fn`` raises never
+        reaches the caller: the Future holds it and ``workers()`` names the worker failed. Raises Cancelled once the
+        token is set, and the thread's own error when no thread can be started."""
+        job = _Job(name, fn, args)
+        with self._condition:
+            if self.token.is_set():
+                raise Cancelled(f"{name} was not started: this run is stopping")
+            self._live.append(job)
+            if self._running() < self._max:
+                try:
+                    self._start(job)
+                except BaseException:
+                    self._live.remove(job)
+                    raise
+        return job.future
+
+    def cancel(self):
+        self.token.set()
+
+    def join(self, timeout=None):
+        """Wait until every worker has finished. False when one still runs after ``timeout`` (``workers()`` names
+        it), and at once on one of this executor's own workers, which can't wait for itself."""
+        deadline = None if timeout is None else time.monotonic() + max(0.0, timeout)
+        with self._condition:
+            while self._live:
+                left = None if deadline is None else deadline - time.monotonic()
+                if (left is not None and left <= 0) or self._owns(threading.current_thread()):
+                    return False
+                self._condition.wait(left)
+            return True
+
+    def in_worker(self):
+        """True on one of this executor's worker threads."""
+        with self._condition:
+            return self._owns(threading.current_thread())
+
+    def workers(self):
+        """The last KEPT finished workers, then every queued and running one, oldest first."""
+        with self._condition:
+            return (*self._finished, *(Worker(job.name, job.state) for job in self._live))
+
+    def _running(self):
+        return sum(job.state is State.RUNNING for job in self._live)
+
+    def _owns(self, thread):
+        return any(job.thread is thread for job in self._live)
+
+    def _start(self, job):
+        job.state = State.RUNNING
+        job.thread = threading.Thread(target=self._work, args=(job,), name=job.name, daemon=True)
+        try:
+            job.thread.start()
+        except BaseException:
+            job.state, job.thread = State.QUEUED, None
+            raise
+
+    def _work(self, job):
+        state, error = State.CANCELLED, ""
+        if job.future.set_running_or_notify_cancel():
+            try:
+                value = job.fn(*job.args)
+            except BaseException as failure:  # noqa: BLE001 -- kept on its Future, never raised into the submitter
+                log.warning("run worker %s failed", job.name, exc_info=True)
+                job.future.set_exception(failure)
+                state, error = State.FAILED, type(failure).__name__
+            else:
+                job.future.set_result(value)
+                state = State.DONE
+        with self._condition:
+            self._retire(job, state, error)
+            self._start_queued()
+            self._condition.notify_all()
+
+    def _start_queued(self):
+        for job in [job for job in self._live if job.state is State.QUEUED]:
+            if self.token.is_set() or self._running() >= self._max:
+                return
+            try:
+                self._start(job)
+            except Exception as failure:  # noqa: BLE001 -- no thread to be had: this job fails, the next still waits
+                log.warning("run worker %s could not start", job.name, exc_info=True)
+                if job.future.set_running_or_notify_cancel():
+                    job.future.set_exception(failure)
+                self._retire(job, State.FAILED, type(failure).__name__)
+
+    def _drop_queued(self):
+        with self._condition:
+            for job in [job for job in self._live if job.state is State.QUEUED]:
+                job.future.cancel()
+                self._retire(job, State.CANCELLED)
+            self._condition.notify_all()
+
+    def _retire(self, job, state, error=""):
+        """Move ``job`` to the finished list, dropping what it held: a parked worker must not keep a run alive."""
+        self._live.remove(job)
+        job.fn = job.args = job.thread = None
+        self._finished.append(Worker(job.name, state, error))

mobile_agent/run_export.py

@@ -0,0 +1,284 @@
+"""`mobster export ID --gif [--mp4] [--redact] [-o PATH]`: save a finished task as a captioned GIF or MP4, or
+`mobster export ID --trace [--screens]`: as a trace bundle (traces.py)."""
+
+import json
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+from .paths import PACKAGE, source_checkout, user_data_dir
+
+FRAME_ID = re.compile(r"f[0-9a-f]{10}")
+RUN_ID = re.compile(r"[0-9a-f]{4,12}")
+ACTIVE = ("queued", "running")
+REDACT_HINT = "It shows every screen of the task. Check it before you post it, or save it again with --redact."
+
+
+class ExportError(Exception):
+    pass
+
+
+def journals():
+    folders = []
+    if source_checkout():
+        folders.append(PACKAGE / ".state")
+    folders.append(user_data_dir() / "state")
+    paths = [folder / name for folder in folders for name in ("terminal.sqlite3", "mobster.sqlite3")]
+    found = [path for path in dict.fromkeys(paths) if path.is_file()]
+    return sorted(found, key=lambda path: path.stat().st_mtime, reverse=True)
+
+
+def _connect(path):
+    return sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=2)
+
+
+def _events(connection, run_id):
+    events = []
+    for (data,) in connection.execute("SELECT data FROM events WHERE run_id=? ORDER BY seq", (run_id,)):
+        try:
+            event = json.loads(data)
+        except ValueError:
+            continue
+        if isinstance(event, dict):
+            events.append(event)
+    return events
+
+
+def find_run(identifier, paths=None):
+    paths = journals() if paths is None else paths
+    identifier = (identifier or "").strip().lower()
+    latest = identifier == "latest"
+    if not latest and not RUN_ID.fullmatch(identifier):
+        raise ExportError(f"“{identifier}” isn’t a task ID. List your tasks with `mobster history`.")
+    matches = []
+    for path in paths:
+        try:
+            connection = _connect(path)
+        except sqlite3.Error:
+            continue
+        try:
+            if latest:
+                rows = connection.execute("SELECT id, data FROM runs ORDER BY rowid DESC LIMIT 50").fetchall()
+            else:
+                rows = connection.execute("SELECT id, data FROM runs WHERE substr(id, 1, ?) = ?",
+                                          (len(identifier), identifier)).fetchall()
+            for run_id, data in rows:
+                try:
+                    record = json.loads(data)
+                except ValueError:
+                    continue
+                if not isinstance(record, dict) or (latest and record.get("status") in ACTIVE):
+                    continue
+                matches.append((record, path, run_id))
+        except sqlite3.Error:
+            continue
+        finally:
+            connection.close()
+    if latest:
+        matches.sort(key=lambda item: item[0].get("createdAt") or 0, reverse=True)
+        matches = matches[:1]
+    if not matches:
+        what = "No finished task" if latest else f"No task {identifier}"
+        raise ExportError(f"{what} in your history. List your tasks with `mobster history`.")
+    if len({run_id for _, _, run_id in matches}) > 1:
+        raise ExportError(f"Several tasks start with {identifier}. Give more of the ID.")
+    record, path, run_id = matches[0]
+    connection = _connect(path)
+    try:
+        record = {**record, "events": _events(connection, run_id)}
+    finally:
+        connection.close()
+    return record, path
+
+
+def run_folder(journal, run_id):
+    """Where the run's frames and tape are, beside its journal."""
+    return Path(journal).parent / "frames" / run_id
+
+
+def frame_reader(journal, run_id):
+    folder = run_folder(journal, run_id)
+
+    def read(frame_id):
+        if not FRAME_ID.fullmatch(frame_id or ""):
+            return None
+        try:
+            return (folder / f"{frame_id}.jpg").read_bytes()
+        except OSError:
+            return None
+    return read
+
+
+def targets(output, stem, want_gif, want_mp4):
+    if output is None or output.is_dir() or str(output).endswith("/"):
+        folder = output if output is not None else Path.home() / "Downloads"
+        return {ext: (folder, stem, False) for ext, wanted in (("gif", want_gif), ("mp4", want_mp4)) if wanted}
+    base = output.with_suffix("") if output.suffix.lower() in (".gif", ".mp4") else output
+    return {ext: (base.parent, base.name, True) for ext, wanted in (("gif", want_gif), ("mp4", want_mp4)) if wanted}
+
+
+def _write(folder, stem, extension, data, overwrite):
+    from .api_errors import APIError
+    from .downloads import save_export_bytes
+    if overwrite:
+        target = Path(folder) / f"{stem}.{extension}"
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+        except OSError as error:
+            raise ExportError(f"Couldn’t write {target}: {error.strerror or error}.") from None
+        return {"name": target.name, "path": str(target)}
+    try:
+        return save_export_bytes(stem, extension, data, folder)
+    except APIError as error:
+        raise ExportError(str(error)) from None
+    except OSError as error:
+        raise ExportError(f"Couldn’t write to {folder}: {error.strerror or error}.") from None
+
+
+def _size(count):
+    return f"{count / 1_000_000:.1f} MB" if count >= 100_000 else f"{max(1, round(count / 1000))} KB"
+
+
+def _home(path):
+    home = str(Path.home())
+    return "~" + path[len(home):] if path.startswith(home + "/") else path
+
+
+def to_eval(args, stream=None, errors=None):
+    """`mobster history --to-eval ID`: a finished task into the local eval set, beside its journal
+    (traces.add_to_evals).
+    Exit 0 added (or already there), 1 couldn't."""
+    from . import traces
+    stream, errors = stream or sys.stdout, errors or sys.stderr
+    try:
+        record, journal = find_run(args.to_eval)
+        try:
+            result = traces.add_to_evals(record, run_folder(journal, record.get("id") or ""),
+                                         Path(journal).parent / "evals")
+        except traces.EvalError as error:
+            raise ExportError(str(error)) from None
+        except OSError as error:
+            raise ExportError(f"Couldn’t write the eval: {error.strerror or error}.") from None
+    except ExportError as error:
+        errors.write(f"mobster history: {error}\n")
+        return 1
+    if args.json:
+        stream.write(json.dumps({"ok": True, **result}, ensure_ascii=False) + "\n")
+        return 0
+    expected = result["expected"]
+    stream.write(f"{'Added' if result['added'] else 'Already in your evals:'} {result['id']}\n")
+    stream.write("It failed, so a fix is a change in how it acts: `python -m mobile_agent.bench evals` replays it "
+                 "offline.\n" if expected["replay"] == "changes" else
+                 "It finished, so a change must keep it acting the same: `python -m mobile_agent.bench evals` "
+                 "replays it offline.\n")
+    stream.write(f"The eval set is {_home(str(Path(result['path']).parent))}\n")
+    return 0
+
+
+def export_trace(args, stream, errors):
+    """``--trace``: the run's bundle as a zip in -o (a folder, or a file name) or ~/Downloads, never over a file
+    that is there. Exit 0 saved, 1 couldn't."""
+    from . import traces
+    try:
+        record, journal = find_run(args.run_id)
+        if record.get("status") in ACTIVE:
+            raise ExportError("This task is still running. Save it once it ends.")
+        run_id = record.get("id") or ""
+        data, manifest = traces.bundle(record, run_folder(journal, run_id),
+                                       read_frame=frame_reader(journal, run_id) if args.screens else None)
+        output = args.output
+        try:
+            if output is not None and not output.is_dir() and not str(output).endswith("/"):
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_bytes(data)
+                saved = output
+            else:
+                saved = traces.save(data, output if output is not None else Path.home() / "Downloads",
+                                    f"mobster-trace-{run_id}")
+        except OSError as error:
+            raise ExportError(f"Couldn’t write the bundle: {error.strerror or error}.") from None
+    except ExportError as error:
+        if args.json:
+            stream.write(json.dumps({"ok": False, "error": str(error)}) + "\n")
+        else:
+            errors.write(f"mobster export: {error}\n")
+        return 1
+    result = {"ok": True, "id": run_id, "trace": {"path": str(saved), "bytes": len(data), "tape": manifest["tape"],
+                                                   "screens": manifest["screens"]}}
+    if args.json:
+        stream.write(json.dumps(result, ensure_ascii=False) + "\n")
+        return 0
+    tape = "with its tape" if manifest["tape"]["included"] else "without a tape"
+    stream.write(f"Saved {saved.name} ({_size(len(data))}, {tape}) to {_home(str(saved.parent))}\n")
+    if not manifest["tape"]["included"]:
+        stream.write(manifest["tape"]["why"][0].upper() + manifest["tape"]["why"][1:] + ".\n")
+    stream.write(("It holds the task's text and the text on its screens, and the screenshots, which can't be masked. "
+                  if args.screens else "It holds the task's text and the text on its screens. ")
+                 + "Keys, codes and passwords are masked. Read it before you share it.\n")
+    return 0
+
+
+def export(args, stream=None, errors=None):
+    from . import run_gif
+    stream, errors = stream or sys.stdout, errors or sys.stderr
+    if args.trace:
+        if args.gif or args.mp4:
+            errors.write("mobster export: --trace saves a bundle; save a GIF or an MP4 in another command.\n")
+            return 2
+        return export_trace(args, stream, errors)
+    if args.screens:
+        errors.write("mobster export: --screens goes with --trace.\n")
+        return 2
+    if not args.gif and not args.mp4:
+        errors.write("mobster export: say what to save: --gif, --mp4, --trace, or a GIF and an MP4. Example: "
+                     "mobster export latest --gif\n")
+        return 2
+    try:
+        record, journal = find_run(args.run_id)
+        if record.get("status") in ACTIVE:
+            raise ExportError("This task is still running. Save it once it ends.")
+        read = frame_reader(journal, record.get("id") or "")
+        ffmpeg = run_gif.ffmpeg_path() if args.mp4 else None
+        if args.mp4 and ffmpeg is None:
+            raise ExportError("--mp4 needs ffmpeg. Install it with `brew install ffmpeg`, or save a GIF with --gif.")
+        stem = run_gif.file_stem(record.get("goal"))
+        places = targets(args.output, stem, args.gif, args.mp4)
+        result = {"ok": True, "id": record.get("id"), "gif": None, "mp4": None}
+        if args.gif:
+            try:
+                clip = run_gif.build_clip(record, read, theme=args.theme, redact=args.redact)
+            except ValueError as error:
+                raise ExportError(str(error)) from None
+            folder, name, overwrite = places["gif"]
+            saved = _write(folder, name, "gif", clip.gif, overwrite)
+            result["gif"] = {**saved, "bytes": len(clip.gif), "frames": clip.frames, "seconds": round(clip.seconds, 1)}
+            stem = Path(saved["name"]).stem
+        if args.mp4:
+            try:
+                data = run_gif.build_mp4(record, read, theme=args.theme, redact=args.redact, ffmpeg=ffmpeg)
+            except ValueError as error:
+                raise ExportError(str(error)) from None
+            except (RuntimeError, OSError) as error:
+                raise ExportError(str(error)) from None
+            folder, name, overwrite = places["mp4"]
+            saved = _write(folder, stem if args.gif and not overwrite else name, "mp4", data, overwrite)
+            result["mp4"] = {**saved, "bytes": len(data)}
+    except ExportError as error:
+        if args.json:
+            stream.write(json.dumps({"ok": False, "error": str(error)}) + "\n")
+        else:
+            errors.write(f"mobster export: {error}\n")
+        return 1
+    if args.json:
+        stream.write(json.dumps(result, ensure_ascii=False) + "\n")
+        return 0
+    for kind in ("gif", "mp4"):
+        saved = result[kind]
+        if saved:
+            facts = _size(saved["bytes"]) + (f", {saved['seconds']:g} s" if kind == "gif" else "")
+            stream.write(f"Saved {saved['name']} ({facts}) to {_home(str(Path(saved['path']).parent))}\n")
+    if not args.redact:
+        stream.write(REDACT_HINT + "\n")
+    return 0