@capagents/forgeqe 1.3.1 → 2.0.0

package/py/forgeqe_mobile/maestro.py

@@ -0,0 +1,321 @@
+"""
+Maestro (maestro.mobile.dev): replay ForgeQE mobile workflows as Maestro flows, and run the team's own flows.
+
+- ``to_flow`` writes a workflow as a Maestro flow. Variables are filled in first; ``{{secret:NAME}}`` becomes
+  ``${MAESTRO_NAME}``, which Maestro reads from the environment ForgeQE gives it, so a secret's value never lands in
+  the flow file or on a command line.
+- ``check_flow`` checks a flow someone else wrote before it runs. Maestro evaluates ``${…}`` as JavaScript and has
+  commands that run scripts, call AI services or write files, so only an allowlist of UI commands passes, ``${…}`` may
+  only name a variable, and ``runFlow`` files must stay inside the project.
+- ``run_maestro`` starts ``maestro test`` with an argument list (no shell) and reads its JUnit report and its debug
+  output for the result of each command.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+import yaml
+
+from forgeqe_desktop.workflow import WorkflowError, fill, fill_targets, secret_names, validate
+
+_JS_EXPR = re.compile(r"\$\{([^}]*)\}")
+_JS_VAR = re.compile(r"^\s*[A-Za-z_][A-Za-z0-9_]*\s*$")
+_REGEX_SPECIAL = re.compile(r"([\\.^$|?*+()\[\]{}])")
+MAESTRO_KEYS = {"enter": "Enter", "back": "Back", "tab": "Tab", "delete": "Backspace"}
+MAX_FLOW_DEPTH = 5
+
+# Maestro commands that only act on the app's UI. Everything else (runScript, evalScript, assertTrue, the AI commands,
+# takeScreenshot and recordings that write files, addMedia) is refused in flows ForgeQE did not write.
+ALLOWED_COMMANDS = frozenset(
+    {
+        "launchApp", "stopApp", "killApp", "clearState", "clearKeychain", "tapOn", "doubleTapOn", "longPressOn",
+        "inputText", "inputRandomText", "inputRandomNumber", "inputRandomEmail", "inputRandomPersonName", "eraseText",
+        "pressKey", "back", "hideKeyboard", "scroll", "scrollUntilVisible", "swipe", "assertVisible", "assertNotVisible",
+        "waitForAnimationToEnd", "extendedWaitUntil", "copyTextFrom", "pasteText", "openLink", "setLocation", "travel",
+        "setAirplaneMode", "toggleAirplaneMode", "runFlow", "repeat", "retry",
+    }
+)
+_REFUSED_LINK = re.compile(r"^\s*(javascript|file|data|content|intent|vbscript):", re.I)
+
+
+def regex_literal(text: str) -> str:
+    """``text`` as a Maestro (Java) regex that matches it literally."""
+    return _REGEX_SPECIAL.sub(r"\\\1", text)
+
+
+def _selector(target: Mapping[str, Any], text: Optional[str] = None) -> Dict[str, Any]:
+    sel: Dict[str, Any] = {}
+    if target.get("automation_id"):
+        sel["id"] = regex_literal(str(target["automation_id"]))
+    if text is not None:
+        sel["text"] = f".*{regex_literal(text)}.*"
+    elif target.get("name"):
+        sel["text"] = regex_literal(str(target["name"]))
+    if "index" in target:
+        sel["index"] = int(target["index"])
+    if not sel:
+        raise WorkflowError("a Maestro step needs an automation_id or a name")
+    return sel
+
+
+def _ms(seconds: Any) -> int:
+    return int(float(seconds) * 1000)
+
+
+def to_flow(workflow: Mapping[str, Any], app_id: str, variables: Optional[Mapping[str, Any]] = None, allowed_secrets: Iterable[str] = ()) -> Tuple[str, List[str]]:
+    """``(flow text, secret names)`` for a mobile workflow; the secrets are read from MAESTRO_<NAME> when it runs."""
+    wf = validate(dict(workflow))
+    if wf["format"] != "forgeqe-mobile-v1":
+        raise WorkflowError("only mobile workflows (forgeqe-mobile-v1) run on Maestro")
+    allowed = {str(n) for n in allowed_secrets}
+    values: Dict[str, Any] = {**wf["variables"], **dict(variables or {})}
+    wf = fill_targets(wf, values)
+    used: List[str] = []
+
+    def secret(name: str) -> Optional[str]:
+        if name not in allowed:
+            raise WorkflowError(f"secret {name} is not listed in forgeqe.yaml mobile.secrets")
+        if name not in used:
+            used.append(name)
+        return "${MAESTRO_%s}" % name
+
+    def text(raw: str) -> str:
+        for name in secret_names(raw):
+            secret(name)
+        # A value with ${…} would be run by Maestro as JavaScript.
+        filled_values = fill(raw, values, lambda n: "")
+        if "${" in filled_values:
+            raise WorkflowError("text for Maestro may not contain ${…}: Maestro would run it as JavaScript")
+        return fill(raw, values, secret)
+
+    timeout = wf.get("timeout")
+    cmds: List[Any] = []
+    for i, step in enumerate(wf["steps"], 1):
+        op = step["op"]
+        t = step.get("timeout", timeout)
+        try:
+            if op == "launch":
+                cmds.append("launchApp")
+                # dismiss: Maestro has no handler for a dialog that may show, so each is tapped if it is there after a
+                # launch, where system prompts (permissions) show.
+                for d in wf.get("dismiss") or []:
+                    cmds.append({"tapOn": {**_selector(d), "optional": True}})
+            elif op == "close":
+                cmds.append("stopApp")
+            elif op in ("tap", "double_tap", "long_press"):
+                cmds.append({{"tap": "tapOn", "double_tap": "doubleTapOn", "long_press": "longPressOn"}[op]: _selector(step["target"])})
+            elif op == "type":
+                cmds += [{"tapOn": _selector(step["target"])}, "eraseText", {"inputText": text(step["text"])}]
+            elif op == "expect":
+                cmds.append({"assertVisible": _selector(step["target"], text(step["text"]) if "text" in step else None)})
+            elif op == "wait_for":
+                sel = _selector(step["target"], text(step["text"]) if "text" in step else None)
+                cmds.append({"extendedWaitUntil": {("notVisible" if step.get("gone") else "visible"): sel, "timeout": _ms(t or 10)}})
+            elif op == "wait":
+                # Maestro has no sleep: wait for something that never appears, and carry on.
+                cmds.append({"extendedWaitUntil": {"visible": {"id": "forgeqe-wait-never-present"}, "timeout": _ms(step["seconds"]), "optional": True}})
+            elif op == "swipe":
+                swipe: Dict[str, Any] = {"direction": step["direction"].upper()}
+                if "target" in step:
+                    swipe["from"] = _selector(step["target"])
+                cmds.append({"swipe": swipe})
+            elif op == "scroll_to":
+                cmds.append({"scrollUntilVisible": {"element": _selector(step["target"]), "direction": step.get("direction", "down").upper(), **({"timeout": _ms(t)} if t else {})}})
+            elif op == "back":
+                cmds.append("back")
+            elif op == "hide_keyboard":
+                cmds.append("hideKeyboard")
+            elif op == "keys":
+                if step["keys"] not in MAESTRO_KEYS:
+                    raise WorkflowError(f"the {step['keys']} key has no Maestro equivalent; replay with the Appium driver")
+                cmds.append({"pressKey": MAESTRO_KEYS[step["keys"]]})
+            elif op == "expect_image":
+                raise WorkflowError("expect_image needs the Appium driver (Maestro does not compare images)")
+            else:
+                raise WorkflowError(f"op {op} has no Maestro equivalent")
+        except WorkflowError as e:
+            raise WorkflowError(f"step {i} ({op}): {e}")
+    header = {"appId": app_id, **({"name": wf["name"]} if wf["name"] else {})}
+    body = yaml.safe_dump(header, sort_keys=False, allow_unicode=True) + "---\n" + yaml.safe_dump(cmds, sort_keys=False, allow_unicode=True)
+    return body, used
+
+
+# -- flows the team wrote ------------------------------------------------------------------------------------------
+
+
+def _check_strings(value: Any, where: str) -> None:
+    if isinstance(value, str):
+        for m in _JS_EXPR.finditer(value):
+            if not _JS_VAR.match(m.group(1)):
+                raise WorkflowError(f"{where}: ${{{m.group(1)}}} is JavaScript; flows may only use ${{NAME}} variables")
+    elif isinstance(value, Mapping):
+        for k, v in value.items():
+            _check_strings(k, where)
+            _check_strings(v, where)
+    elif isinstance(value, list):
+        for v in value:
+            _check_strings(v, where)
+
+
+def _inside(path: Path, root: Path) -> bool:
+    try:
+        Path(os.path.realpath(path)).relative_to(Path(os.path.realpath(root)))
+        return True
+    except ValueError:
+        return False
+
+
+def _check_commands(cmds: Any, where: str, base: Path, root: Path, depth: int, seen: List[Path]) -> None:
+    if cmds is None:
+        return
+    if not isinstance(cmds, list):
+        raise WorkflowError(f"{where}: commands must be a list")
+    for i, cmd in enumerate(cmds, 1):
+        at = f"{where} command {i}"
+        if isinstance(cmd, str):
+            name, args = cmd, None
+        elif isinstance(cmd, Mapping) and len([k for k in cmd if k not in ("optional", "label")]) == 1:
+            name = next(k for k in cmd if k not in ("optional", "label"))
+            args = cmd[name]
+        else:
+            raise WorkflowError(f"{at}: one command per list item")
+        if name not in ALLOWED_COMMANDS:
+            raise WorkflowError(f"{at}: {name} is not allowed (only UI commands run; scripts, AI commands and file writes are refused)")
+        _check_strings(args, at)
+        if isinstance(args, Mapping) and isinstance(args.get("when"), Mapping) and "true" in args["when"]:
+            raise WorkflowError(f"{at}: when.true is JavaScript")
+        if name == "openLink":
+            link = args.get("link") if isinstance(args, Mapping) else args
+            if not isinstance(link, str) or _REFUSED_LINK.match(link):
+                raise WorkflowError(f"{at}: openLink must be an http(s) link or the app's own deep link")
+        if name in ("repeat", "retry") and isinstance(args, Mapping):
+            _check_commands(args.get("commands"), at, base, root, depth, seen)
+            if name == "retry" and args.get("file"):
+                _check_flow_file(base / str(args["file"]), root, depth + 1, seen)
+        if name == "runFlow":
+            if isinstance(args, str):
+                _check_flow_file(base / args, root, depth + 1, seen)
+            elif isinstance(args, Mapping):
+                if isinstance(args.get("when"), Mapping) and "true" in args["when"]:
+                    raise WorkflowError(f"{at}: when.true is JavaScript")
+                if args.get("file"):
+                    _check_flow_file(base / str(args["file"]), root, depth + 1, seen)
+                _check_commands(args.get("commands"), at, base, root, depth, seen)
+            else:
+                raise WorkflowError(f"{at}: runFlow needs a file or commands")
+
+
+def _check_flow_file(path: Path, root: Path, depth: int, seen: List[Path]) -> None:
+    if depth > MAX_FLOW_DEPTH:
+        raise WorkflowError(f"{path.name}: runFlow is nested more than {MAX_FLOW_DEPTH} deep")
+    if path.suffix.lower() not in (".yaml", ".yml"):
+        raise WorkflowError(f"{path.name} is not a Maestro flow (.yaml)")
+    if not path.is_file():
+        raise WorkflowError(f"no flow at {path}")
+    if not _inside(path, root):
+        raise WorkflowError(f"{path} is outside the project folder; flows are read from it only")
+    real = Path(os.path.realpath(path))
+    if real in seen:
+        return
+    seen.append(real)
+    docs = [d for d in yaml.safe_load_all(real.read_text(encoding="utf-8"))]
+    if not docs:
+        raise WorkflowError(f"{path.name} is empty")
+    config, commands = (docs[0], docs[1] if len(docs) > 1 else None) if isinstance(docs[0], Mapping) else ({}, docs[0])
+    if len(docs) > 2:
+        raise WorkflowError(f"{path.name}: a flow is a config and one list of commands")
+    if not isinstance(config, Mapping):
+        raise WorkflowError(f"{path.name}: the first part must be the flow's config (appId: …)")
+    for key in config:
+        if key not in ("appId", "url", "name", "tags", "env", "onFlowStart", "onFlowComplete", "properties"):
+            raise WorkflowError(f"{path.name}: config key {key} is not allowed")
+    _check_strings({k: v for k, v in config.items() if k not in ("onFlowStart", "onFlowComplete")}, path.name)
+    for hook in ("onFlowStart", "onFlowComplete"):
+        _check_commands(config.get(hook), f"{path.name} {hook}", real.parent, root, depth, seen)
+    _check_commands(commands, path.name, real.parent, root, depth, seen)
+
+
+def check_flow(path: str | os.PathLike, root: str | os.PathLike) -> List[str]:
+    """Check a flow (and every flow it runs) before Maestro gets it; returns the flow files checked."""
+    seen: List[Path] = []
+    _check_flow_file(Path(path), Path(root), 0, seen)
+    return [str(p) for p in seen]
+
+
+# -- running ---------------------------------------------------------------------------------------------------------
+
+
+def _junit(path: Path) -> List[Dict[str, Any]]:
+    if not path.is_file():
+        return []
+    try:
+        root = ET.parse(path).getroot()
+    except ET.ParseError:
+        return []
+    out: List[Dict[str, Any]] = []
+    for case in root.iter("testcase"):
+        failure = case.find("failure")
+        error = case.find("error")
+        bad = failure if failure is not None else error
+        out.append({"name": case.get("name") or "", "ok": bad is None, **({"error": ((bad.get("message") or "") + " " + (bad.text or "")).strip()[:2000]} if bad is not None else {})})
+    return out
+
+
+_INTERNAL_COMMANDS = frozenset({"applyConfigurationCommand", "defineVariablesCommand"})
+
+
+def command_results(debug_dir: Path) -> List[Dict[str, Any]]:
+    """The status of each command Maestro ran (its debug output's commands-*.json), in order; [] when not written."""
+    results: List[Dict[str, Any]] = []
+    for f in sorted(debug_dir.rglob("commands-*.json")):
+        try:
+            doc = json.loads(f.read_text(encoding="utf-8", errors="replace"))
+        except ValueError:
+            continue
+        for entry in doc if isinstance(doc, list) else []:
+            command = entry.get("command") if isinstance(entry, Mapping) else None
+            # Maestro's own bookkeeping (the flow's config, its env), not a command of the flow.
+            if isinstance(command, Mapping) and set(command) & _INTERNAL_COMMANDS:
+                continue
+            meta = entry.get("metadata") if isinstance(entry, Mapping) else None
+            status = str((meta or {}).get("status") or "").upper()
+            err = (meta or {}).get("error")
+            results.append({"status": status, **({"error": str(err.get("message") if isinstance(err, Mapping) else err)[:1000]} if err else {})})
+    return results
+
+
+def run_maestro(
+    command: Sequence[str],
+    flows: Sequence[str],
+    out_dir: Path,
+    env: Mapping[str, str],
+    device: Optional[str] = None,
+    timeout: float = 3600,
+    run: Callable[..., Any] = subprocess.run,
+) -> Dict[str, Any]:
+    """Run ``maestro test`` on ``flows``; ``{ok, flows: [{name, ok, error}], commands: [...], log}``."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    junit = out_dir / "maestro-junit.xml"
+    debug = out_dir / "maestro-debug"
+    args = [*command, *(["--device", device] if device else []), "test", "--format", "junit", "--output", str(junit), "--debug-output", str(debug), *flows]
+    try:
+        proc = run(args, env=dict(env), capture_output=True, text=True, timeout=timeout, shell=False)
+    except FileNotFoundError:
+        raise WorkflowError(f"Maestro is not installed or not on PATH ({command[0]}); see https://maestro.mobile.dev")
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "flows": [], "commands": [], "error": f"Maestro did not finish within {int(timeout)} s", "log": ""}
+    log = ((proc.stdout or "") + (proc.stderr or ""))[-8000:]
+    (out_dir / "maestro.log").write_text(log, encoding="utf-8")
+    cases = _junit(junit)
+    ok = proc.returncode == 0 and all(c["ok"] for c in cases)
+    result: Dict[str, Any] = {"ok": ok, "flows": cases, "commands": command_results(debug), "log": log[-2000:]}
+    if not ok:
+        failed = [c for c in cases if not c["ok"]]
+        result["error"] = (failed[0].get("error") if failed else "") or f"maestro exited with {proc.returncode}: {log.strip().splitlines()[-1] if log.strip() else ''}"
+    return result

package/py/forgeqe_mobile/service.py

@@ -0,0 +1,332 @@
+"""
+``python -m forgeqe_mobile serve``: one request as a JSON line on stdin, events as JSON lines on stdout, like the
+desktop engine. A later ``stop`` line on stdin stops a replay between steps, or an explore between actions.
+
+Request: ``mode`` (``replay``, ``explore`` or ``maestro``), ``out_dir``, ``mobile`` (``apps``, ``secrets``,
+``appium`` {``url``, ``capabilities``, ``username_env``, ``access_key_env``}, ``maestro`` {``command``, ``device``},
+``driver``), ``llm`` and ``profile_name`` (healing and explore), and per mode: ``workflow``, ``variables``, ``heal``,
+``update_baselines``, ``driver`` (replay); ``goal``, ``app``, ``name`` (explore); ``flows``, ``root`` (maestro: the
+team's own flows, checked first).
+
+Events: ``log``, ``step`` (one per replayed or explored step), ``call`` (one model call's time and tokens), ``done``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import IO, Any, Callable, Dict, List, Mapping, Optional
+
+import yaml
+
+from forgeqe_desktop.replay import replay
+from forgeqe_desktop.service import Events, _out_dir, _secret_names, _step_fields
+from forgeqe_desktop.workflow import MOBILE_FORMAT, WorkflowError, load, save
+from forgeqe_desktop.visual import image_checker
+
+from .apps import load_mobile_apps
+from .hyperexecute import run_hyperexecute, testmu_settings
+from .maestro import check_flow, run_maestro, to_flow
+
+
+def _mobile(req: Mapping[str, Any]) -> Dict[str, Any]:
+    m = req.get("mobile")
+    return dict(m) if isinstance(m, Mapping) else {}
+
+
+def _model(req: Mapping[str, Any], events: Events, model_factory: Optional[Callable[..., Any]]) -> Any:
+    from forgeqe_desktop.models import DesktopModel
+
+    profile = req.get("llm")
+    if not isinstance(profile, dict):
+        raise WorkflowError("this mode needs an llms.json profile")
+    return (model_factory or DesktopModel)(profile, on_call=lambda c: events.emit({"type": "call", **c}))
+
+
+def appium_driver(mobile: Mapping[str, Any]) -> Any:
+    from .appium_driver import AppiumDriver
+
+    a = mobile.get("appium") if isinstance(mobile.get("appium"), Mapping) else {}
+    user_env, key_env = a.get("username_env"), a.get("access_key_env")
+    return AppiumDriver(
+        url=str(a.get("url") or "http://127.0.0.1:4723"),
+        capabilities=a.get("capabilities") if isinstance(a.get("capabilities"), Mapping) else {},
+        username=os.environ.get(str(user_env)) if user_env else None,
+        access_key=os.environ.get(str(key_env)) if key_env else None,
+    )
+
+
+def _maestro_command(mobile: Mapping[str, Any]) -> List[str]:
+    m = mobile.get("maestro") if isinstance(mobile.get("maestro"), Mapping) else {}
+    cmd = m.get("command") or ["maestro"]
+    if isinstance(cmd, str):
+        cmd = [cmd]
+    if not isinstance(cmd, list) or not cmd or not all(isinstance(c, str) and c for c in cmd):
+        raise WorkflowError("mobile.maestro.command must be the maestro program (and its arguments) as a list")
+    return list(cmd)
+
+
+def _maestro_env(names: List[str], secrets: Mapping[str, str]) -> Dict[str, str]:
+    """The environment for maestro: this process's (already only system settings and listed secrets), with each secret
+    as MAESTRO_<NAME>, the only form a flow can read it in."""
+    env = dict(os.environ)
+    for n in names:
+        if secrets.get(n) is not None:
+            env[f"MAESTRO_{n}"] = secrets[n]
+    return env
+
+
+def run_replay(req: Mapping[str, Any], events: Events, stop: threading.Event, driver_factory: Optional[Callable[[], Any]] = None, model_factory: Optional[Callable[..., Any]] = None, maestro_run: Optional[Callable[..., Any]] = None, cloud_run: Optional[Callable[..., Any]] = None) -> Dict[str, Any]:
+    out = _out_dir(req)
+    mobile = _mobile(req)
+    workflow_file = str(req.get("workflow") or "")
+    wf = load(workflow_file)
+    if wf["format"] != MOBILE_FORMAT:
+        raise WorkflowError(f"{workflow_file} is a desktop workflow; run it with forgeqe desktop replay")
+    apps = load_mobile_apps(mobile)
+    if wf["app"] not in apps:
+        raise WorkflowError(f"app {wf['app']!r} is not in mobile.apps or the environment's mobile apps (configured: {', '.join(sorted(apps)) or 'none'})")
+    names = _secret_names(mobile)
+    driver_name = str(req.get("driver") or mobile.get("driver") or "appium")
+    base = {"mode": "replay", "driver": driver_name, "name": wf["name"], "app": wf["app"], "workflow": workflow_file, "total": len(wf["steps"])}
+
+    if driver_name == "maestro":
+        spec = apps[wf["app"]]
+        flow, used = to_flow(wf, spec.app_id, req.get("variables") or {}, names)
+        flow_file = out / "flow.yaml"
+        flow_file.write_text(flow, encoding="utf-8")
+        secrets = {n: os.environ[n] for n in used if os.environ.get(n) is not None}
+        missing = [n for n in used if n not in secrets]
+        if missing:
+            raise WorkflowError(f"secret {missing[0]} is not set")
+        m = mobile.get("maestro") if isinstance(mobile.get("maestro"), Mapping) else {}
+        testmu = testmu_settings(mobile)
+        if testmu:
+            if used:
+                raise WorkflowError("this workflow types secrets, which Maestro on TestMu cannot be given safely yet; replay it on TestMu with --driver appium")
+            events.log(f"Running {wf['name'] or 'the workflow'} on Maestro on TestMu ({', '.join(testmu['devices'])}).")
+            res = (cloud_run or run_hyperexecute)([(flow_file, "flow.yaml")], ["flow.yaml"], spec.app, spec.platform, testmu, out, wf["name"] or wf["app"], dict(os.environ))
+        else:
+            events.log(f"Running {wf['name'] or 'the workflow'} on Maestro ({flow_file}).")
+            res = (maestro_run or run_maestro)(_maestro_command(mobile), [str(flow_file)], out, _maestro_env(used, secrets), device=m.get("device"))
+        steps = _maestro_steps(wf, res.get("commands") or [], res["ok"])
+        for s in steps:
+            events.emit({"type": "step", **s})
+        return {**base, "ok": res["ok"], "steps": steps, "heals": [], "flow": str(flow_file), **({"job": res["job"]} if res.get("job") else {}), **({"error": res["error"]} if res.get("error") else {})}
+
+    from forgeqe_desktop.heal import make_heal
+    from forgeqe_desktop.models import takes_images
+
+    driver = (driver_factory or (lambda: appium_driver(mobile)))()
+    heal = make_heal(_model(req, events, model_factory), driver, log=events.log, images=takes_images(req.get("llm") or {})) if req.get("heal") else None
+    shots = bool(mobile.get("screenshots", True))
+    (out / "steps").mkdir(exist_ok=True)
+
+    def on_step(res: Any) -> None:
+        shot = None
+        if shots and res.op != "close":
+            png = driver.screenshot_png()
+            if png:
+                shot = f"steps/{res.index:03d}.png"
+                (out / shot).write_bytes(png)
+        events.emit({"type": "step", **_step_fields(res), "screenshot": shot})
+
+    result = replay(
+        wf,
+        driver,
+        apps,
+        variables=req.get("variables") or {},
+        allowed_secrets=names,
+        heal=heal,
+        must_exist=False,
+        on_step=on_step,
+        should_stop=stop.is_set,
+        compare_image=image_checker(workflow_file, out, update=bool(req.get("update_baselines"))),
+    )
+    steps = []
+    for s in result.steps:
+        shot = f"steps/{s.index:03d}.png"
+        steps.append({**_step_fields(s), "screenshot": shot if (out / shot).is_file() else None, "target": wf["steps"][s.index - 1].get("target")})
+    return {
+        **base,
+        "ok": result.ok,
+        "stopped": result.stopped,
+        "steps": steps,
+        "heals": [{"index": s.index, "old": wf["steps"][s.index - 1].get("target"), "new": s.healed_target} for s in result.healed],
+    }
+
+
+def _maestro_steps(wf: Mapping[str, Any], commands: List[Mapping[str, Any]], ok: bool) -> List[Dict[str, Any]]:
+    """Each workflow step's result from Maestro's command results (a type step is three Maestro commands)."""
+    per_step = [3 if s["op"] == "type" else 1 for s in wf["steps"]]
+    if not commands and not ok:
+        # No step's result is known (Maestro wrote none, or the job's results did not come back): the run's error says
+        # what failed, rather than a step that may have passed.
+        return []
+    out: List[Dict[str, Any]] = []
+    pos = 0
+    for i, (step, n) in enumerate(zip(wf["steps"], per_step), 1):
+        chunk = commands[pos : pos + n]
+        pos += n
+        if not commands:
+            status_ok, error = ok, ""
+        elif not chunk:
+            break  # Maestro stopped before this step
+        else:
+            failed = [c for c in chunk if c.get("status") == "FAILED"]
+            status_ok = not failed and all(c.get("status") in ("COMPLETED", "SKIPPED", "WARNED") for c in chunk)
+            error = failed[0].get("error", "failed") if failed else ""
+        out.append({"index": i, "op": step["op"], "ok": status_ok, "ms": 0, "error": error, "healed_target": None, "target": step.get("target")})
+        if not status_ok:
+            break
+    return out
+
+
+def run_explore(req: Mapping[str, Any], events: Events, stop: threading.Event, driver_factory: Optional[Callable[[], Any]] = None, model_factory: Optional[Callable[..., Any]] = None) -> Dict[str, Any]:
+    from forgeqe_desktop.models import require_vision, takes_images
+
+    from .explore import explore
+
+    out = _out_dir(req)
+    mobile = _mobile(req)
+    goal = str(req.get("goal") or "").strip()
+    if not goal:
+        raise WorkflowError("explore needs a goal")
+    app = str(req.get("app") or "")
+    apps = load_mobile_apps(mobile)
+    if app not in apps:
+        raise WorkflowError(f"app {app!r} is not in mobile.apps or the environment's mobile apps (configured: {', '.join(sorted(apps)) or 'none'})")
+    profile = req.get("llm") or {}
+    require_vision(str(req.get("profile_name") or "profile"), profile)
+    names = _secret_names(mobile)
+    secrets = {n: os.environ[n] for n in names if os.environ.get(n) is not None}
+    driver = (driver_factory or (lambda: appium_driver(mobile)))()
+    name = str(req.get("name") or goal)[:120]
+    started = time.time()
+    error = ""
+    workflow: Optional[Dict[str, Any]] = None
+    outcome: Dict[str, Any] = {}
+    events.log(f"Starting {app} and exploring: {goal}")
+    try:
+        workflow, outcome = explore(
+            _model(req, events, model_factory), driver, apps[app], goal, name, secrets, images=takes_images(profile), log=events.log,
+            on_step=lambda s: events.emit({"type": "step", "ok": True, "ms": 0, **s}), should_stop=stop.is_set,
+        )
+    except Exception as e:
+        error = f"Explore stopped with an error: {type(e).__name__}: {e}"[:2000]
+        events.log(error, "error")
+    finally:
+        try:
+            driver.close()
+        except Exception:
+            pass
+    recorded = len(workflow["steps"]) - 1 - int(outcome.get("checks", 0)) if workflow else 0
+    workflow_file = out / "workflow.yaml"
+    if workflow and recorded:
+        save(workflow, workflow_file)
+    done = bool(outcome.get("done"))
+    return {
+        "mode": "explore",
+        "ok": recorded > 0 and done and not error,
+        "goal": goal,
+        "app": app,
+        "name": name,
+        "seconds": int(time.time() - started),
+        "recorded": recorded,
+        "checks": int(outcome.get("checks", 0)),
+        "values": outcome.get("values") or {},
+        "ufo_complete": done,
+        "workflow": str(workflow_file) if workflow and recorded else None,
+        "steps": [{"index": i, "op": s["op"], "ok": True, "ms": 0, "target": s.get("target")} for i, s in enumerate(workflow["steps"], 1)] if workflow else [],
+        "error": error or ("" if done else f"The model did not finish the goal: {outcome.get('reason') or 'no reason given'}"),
+    }
+
+
+def run_flows(req: Mapping[str, Any], events: Events, maestro_run: Optional[Callable[..., Any]] = None, cloud_run: Optional[Callable[..., Any]] = None) -> Dict[str, Any]:
+    """The team's own Maestro flows: each checked against the allowlist, then run together."""
+    out = _out_dir(req)
+    mobile = _mobile(req)
+    root = str(req.get("root") or "")
+    flows = req.get("flows")
+    if not root or not isinstance(flows, list) or not flows or not all(isinstance(f, str) for f in flows):
+        raise WorkflowError("maestro mode needs flows (a list of files) and root (the project folder)")
+    checked: List[str] = []
+    for f in flows:
+        checked += check_flow(f, root)
+    names = _secret_names(mobile)
+    secrets = {n: os.environ[n] for n in names if os.environ.get(n) is not None}
+    m = mobile.get("maestro") if isinstance(mobile.get("maestro"), Mapping) else {}
+    testmu = testmu_settings(mobile)
+    name = f"{len(flows)} Maestro flow{'' if len(flows) == 1 else 's'}"
+    if testmu:
+        spec = _app_of_flows(flows, load_mobile_apps(mobile))
+        events.log(f"Checked {len(checked)} flow file{'' if len(checked) == 1 else 's'}; running {len(flows)} on Maestro on TestMu.")
+        # A flow that runs another (runFlow) needs it in the project too: every checked file goes, in its layout.
+        real_root = Path(os.path.realpath(root))
+        rel = lambda f: Path(os.path.realpath(f)).relative_to(real_root).as_posix()  # noqa: E731
+        res = (cloud_run or run_hyperexecute)([(Path(f), rel(f)) for f in checked], [rel(f) for f in flows], spec.app, spec.platform, testmu, out, name, dict(os.environ))
+    else:
+        events.log(f"Checked {len(checked)} flow file{'' if len(checked) == 1 else 's'}; running {len(flows)} on Maestro.")
+        res = (maestro_run or run_maestro)(_maestro_command(mobile), [str(Path(f).resolve()) for f in flows], out, _maestro_env(names, secrets), device=m.get("device"))
+    return {"mode": "maestro", "ok": res["ok"], "flows": res.get("flows") or [], "checked": checked, "name": name, **({"job": res["job"]} if res.get("job") else {}), **({"error": res["error"]} if res.get("error") else {})}
+
+
+def _app_of_flows(flows: List[str], apps: Mapping[str, Any]) -> Any:
+    """The configured mobile app the flows are for, by their appId: TestMu installs it from its `app`."""
+    ids = set()
+    for f in flows:
+        docs = list(yaml.safe_load_all(Path(f).read_text(encoding="utf-8")))
+        if docs and isinstance(docs[0], Mapping) and isinstance(docs[0].get("appId"), str):
+            ids.add(docs[0]["appId"])
+    if len(ids) != 1:
+        raise WorkflowError("to run on TestMu, the flows must all be for one app (one appId)")
+    app_id = ids.pop()
+    for spec in apps.values():
+        if spec.app_id == app_id:
+            return spec
+    raise WorkflowError(f"no mobile app with app_id {app_id} is configured; add it (with its app build or lt:// id) to env.yaml or mobile.apps")
+
+
+def _watch_stop(stream: IO[str], stop: threading.Event) -> None:
+    for line in stream:
+        if line.strip() == "stop":
+            stop.set()
+            return
+
+
+def serve(
+    stdin: IO[str] = sys.stdin,
+    stdout: IO[str] = sys.stdout,
+    driver_factory: Optional[Callable[[], Any]] = None,
+    model_factory: Optional[Callable[..., Any]] = None,
+    maestro_run: Optional[Callable[..., Any]] = None,
+    cloud_run: Optional[Callable[..., Any]] = None,
+) -> int:
+    events = Events(stdout)
+    stop = threading.Event()
+    out: Optional[Path] = None
+    try:
+        req = json.loads(stdin.readline() or "{}")
+        if not isinstance(req, dict):
+            raise WorkflowError("the request must be a JSON object")
+        threading.Thread(target=_watch_stop, args=(stdin, stop), daemon=True).start()
+        out = _out_dir(req)
+        mode = req.get("mode")
+        if mode == "replay":
+            result = run_replay(req, events, stop, driver_factory, model_factory, maestro_run, cloud_run)
+        elif mode == "explore":
+            result = run_explore(req, events, stop, driver_factory, model_factory)
+        elif mode == "maestro":
+            result = run_flows(req, events, maestro_run, cloud_run)
+        else:
+            raise WorkflowError(f"mode must be replay, explore or maestro, not {mode!r}")
+    except Exception as e:
+        result = {"ok": False, "error": f"{type(e).__name__}: {e}" if not isinstance(e, (WorkflowError, ValueError)) else str(e)}
+    result.setdefault("format", MOBILE_FORMAT)
+    if out is not None:
+        (out / "run.json").write_text(json.dumps(result, ensure_ascii=False, indent=2, default=str), encoding="utf-8")
+    events.emit({"type": "done", "result": result})
+    return 0 if result.get("ok") else 1