mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/testkit/xctest.py

@@ -0,0 +1,378 @@
+"""`mobster test --xctest`: the project's own XCTest and Swift Testing targets, run beside the checks and read from the
+.xcresult into the suite's one results model (doc["xctest"]).
+
+This is not a general XCTest runner: one simulator, no retries of a test, no device runs, and the project's schemes
+and test plans are read, never changed."""
+
+import json
+import plistlib
+import re
+from pathlib import Path
+
+from ..sim.models import SimError
+from .prbuild import BuildError, find_project, pick_scheme, project_arg, run_command
+from .prbuild import build as build_app
+
+BUNDLE_DIR = "xctest"
+BUNDLE_NAME = "tests.xcresult"
+ATTACHMENTS = "attachments"
+RUN_LOG = "xctest.log"
+RUN_TIMEOUT = 30 * 60
+READ_TIMEOUT = 120
+FAILURE_EXIT = 65                 # xcodebuild's code for "the tests ran and some failed"
+MAX_FAILURES = 5                  # failure messages kept per test
+MAX_MESSAGE = 600
+ONLY_TESTING = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_ .+()-]*(/[A-Za-z0-9_ .+()-]+){0,2}$")
+LOCATION = re.compile(r"^(?P<file>[^\n:]+\.(?:swift|m|mm|h|c|cpp)):(?P<line>\d+):?\s*(?P<text>.*)$", re.S)
+EXPORT_SUFFIX = re.compile(r"_\d+_[0-9A-Fa-f-]{36}(?=\.[^.]*$|$)")    # xcresulttool appends _<n>_<UUID> to a name
+RESULTS = {"passed": "passed", "failed": "failed", "skipped": "skipped", "expected failure": "passed"}
+
+
+class XctestError(Exception):
+    """The XCTest half of the run couldn't be done: what happened, and what to do (the checks still ran)."""
+
+    def __init__(self, message, fix=""):
+        super().__init__(message)
+        self.message, self.fix = message, fix
+
+
+def only_testing_ok(items):
+    """``--only-testing`` values: Target, Target/Class or Target/Class/test. XCTestError otherwise."""
+    for item in items:
+        if not ONLY_TESTING.match(item):
+            raise XctestError(f"--only-testing {item!r} isn't a test identifier.",
+                              "Write Target, Target/Class or Target/Class/testName.")
+    return tuple(items)
+
+
+def find_xctestrun(derived):
+    """The .xctestrun file build-for-testing wrote under ``derived``, or None."""
+    found = sorted((Path(derived) / "Build" / "Products").glob("*.xctestrun"))
+    return found[-1] if found else None
+
+
+def targets_of(xctestrun):
+    """The test targets an .xctestrun names, in the order it lists them."""
+    try:
+        with open(xctestrun, "rb") as handle:
+            data = plistlib.load(handle)
+    except (OSError, plistlib.InvalidFileException, ValueError):
+        return []
+    blocks = []
+    for config in data.get("TestConfigurations") or ():
+        blocks += [block for block in config.get("TestTargets") or () if isinstance(block, dict)]
+    blocks += [block for key, block in data.items() if key != "__xctestrun_metadata__" and isinstance(block, dict)
+               and "TestBundlePath" in block]
+    names = [str(block.get("BlueprintName") or block.get("ProductModuleName") or "") for block in blocks]
+    return list(dict.fromkeys(name for name in names if name))
+
+
+def select_targets(targets, changed, only=()):
+    """(targets to run, {target: why}). ``only`` (--only-testing) wins; else the targets whose folder holds a changed
+    file; else every target, because a change that touches no test file can still break one."""
+    if only:
+        named = {item.split("/", 1)[0] for item in only}
+        return [name for name in targets if name in named], {name: "named with --only-testing" for name in named
+                                                              if name in targets}
+    if changed is None:
+        return list(targets), {}
+    hit = {}
+    for target in targets:
+        files = [path for path in changed if target in Path(path).parts]
+        if files:
+            hit[target] = f"{files[0]} changed" + (f" and {len(files) - 1} more" if len(files) > 1 else "")
+    if hit:
+        return [name for name in targets if name in hit], hit
+    return list(targets), {name: "no test file changed, so every target runs" for name in targets}
+
+
+def build(root, *, scheme, project, test_plan=None, runner=None, progress=None, bundle=None, configuration="Debug"):
+    """build-for-testing into .mobster/build: the app the checks drive, the test bundles and the .xctestrun. The
+    result is prbuild.build's, plus "xctestrun" and "targets". BuildError."""
+    built = build_app(root, scheme=scheme, project=project, platform="sim", configuration=configuration,
+                      runner=runner, progress=progress, bundle=bundle, for_testing=True, test_plan=test_plan)
+    derived = Path(root) / ".mobster" / "build"
+    run_file = find_xctestrun(derived)
+    if run_file is None:
+        raise BuildError(f"{scheme} built, but it has no test target to run.",
+                         "Add a unit test target to the scheme's Test action, or leave --xctest out.")
+    return {**built, "scheme": scheme, "xctestrun": str(run_file), "targets": targets_of(run_file)}
+
+
+def prepare(planned, progress, *, runner=None):
+    """The build for a run that didn't build for testing first (`mobster test --xctest`): the project's own scheme.
+    BuildError."""
+    options, root = planned.options, planned.root
+    found = project_arg(Path(root) / options.xctest_project) if options.xctest_project else find_project(root)
+    if found is None:
+        raise BuildError(f"{root} has no Xcode project to build the tests from.",
+                         "Pass --project YourApp.xcodeproj, or leave --xctest out.")
+    scheme = options.xctest_scheme or pick_scheme(found, runner=runner, cwd=root)
+    return build(root, scheme=scheme, project=found, test_plan=options.xctest_plan, runner=runner, progress=progress)
+
+
+def run_argv(xctestrun, udid, bundle_path, only):
+    argv = ["xcodebuild", "test-without-building", "-xctestrun", str(xctestrun), "-destination", f"id={udid}",
+            "-resultBundlePath", str(bundle_path)]
+    for item in only:
+        argv.append(f"-only-testing:{item}")
+    return argv
+
+
+def run_tests(xctestrun, udid, folder, only, *, runner=None, progress=None):
+    """Run the built tests on simulator ``udid``; the result bundle goes under ``folder``/xctest/. The bundle's path,
+    or XctestError when xcodebuild stopped before running tests."""
+    progress = progress or (lambda line: None)
+    bundle = Path(folder) / BUNDLE_DIR / BUNDLE_NAME
+    bundle.parent.mkdir(parents=True, exist_ok=True)
+    progress("Running your XCTest targets")
+    code, output = (runner or run_command)(run_argv(xctestrun, udid, bundle, only), Path(folder),
+                                           bundle.parent / RUN_LOG, RUN_TIMEOUT)
+    if code not in (0, FAILURE_EXIT) or not (bundle / "Info.plist").is_file():
+        errors = [line.strip() for line in output.splitlines() if "error:" in line or "Testing failed" in line][:3]
+        detail = "; ".join(errors)[:500] if errors else f"xcodebuild exited {code}"
+        raise XctestError(f"The tests didn't run: {detail}.", f"Read {bundle.parent / RUN_LOG}, then run it again.")
+    return bundle
+
+
+def _json(argv, runner):
+    code, output = (runner or run_command)(argv, Path.cwd(), None, READ_TIMEOUT)
+    start = output.find("{")
+    try:
+        data = json.JSONDecoder().raw_decode(output[start:])[0] if code == 0 and start >= 0 else None
+    except ValueError:
+        data = None
+    if not isinstance(data, dict):
+        raise XctestError("Mobster couldn't read the test results.", "Run `xcrun xcresulttool get test-results "
+                          "summary --path <the .xcresult>` to see why; it needs Xcode 16 or later.")
+    return data
+
+
+def read_bundle(bundle, *, runner=None):
+    """(tests, summary): xcresulttool's JSON for ``bundle``. XctestError when it can't be read."""
+    base = ["xcrun", "xcresulttool", "get", "test-results"]
+    tail = ["--path", str(bundle), "--format", "json"]
+    return _json(base + ["tests"] + tail, runner), _json(base + ["summary"] + tail, runner)
+
+
+def _seconds(node):
+    value = node.get("durationInSeconds")
+    if isinstance(value, (int, float)):
+        return value
+    match = re.match(r"^\s*([0-9.]+)\s*(ms|s|m)\b", str(node.get("duration") or ""))
+    if not match:
+        return 0
+    return float(match.group(1)) * {"ms": 0.001, "s": 1, "m": 60}[match.group(2)]
+
+
+def _failures(node):
+    """The case's failure messages, each as {"message", "file", "line"}."""
+    out = []
+    for child in node.get("children") or ():
+        if child.get("nodeType") == "Failure Message":
+            text = str(child.get("name") or "").strip()
+            found = LOCATION.match(text)
+            entry = {"message": (found.group("text") if found else text)[:MAX_MESSAGE], "file": None, "line": None}
+            if found:
+                entry["file"], entry["line"] = Path(found.group("file")).name, int(found.group("line"))
+            out.append(entry)
+        elif isinstance(child.get("children"), list):
+            out += _failures(child)
+    return out[:MAX_FAILURES]
+
+
+def _cases(nodes, bundle=None, suites=()):
+    """Every Test Case under ``nodes`` as (bundle, suite names, node)."""
+    for node in nodes:
+        kind = str(node.get("nodeType") or "")
+        if kind == "Test Case":
+            yield bundle, suites, node
+        elif isinstance(node.get("children"), list):
+            name = str(node.get("name") or "")
+            yield from _cases(node["children"], name if "test bundle" in kind.lower() else bundle,
+                              suites + (name,) if kind == "Test Suite" else suites)
+
+
+def parse(tests, summary=None, device=None):
+    """The targets of an xcresulttool ``tests`` document as the suite's results model:
+    [{"name", "status", "tests", "passed", "failed", "skipped", "durationMs", "cases": [...]}]. A case has name,
+    classname, status (passed, failed or skipped), durationMs, failures [{message, file, line}] and attachments []."""
+    targets = {}
+    where = {} if device is None else {"device": device["name"], "deviceKey": device["key"]}
+    for bundle, suites, node in _cases(tests.get("testNodes") or ()):
+        target = targets.setdefault(bundle or "Tests", {"name": bundle or "Tests", "cases": []})
+        status = RESULTS.get(str(node.get("result") or "").lower(), "failed")
+        name = re.sub(r"\(\)$", "", str(node.get("name") or ""))
+        failures = _failures(node)
+        if status == "failed" and not failures:
+            failures = [{"message": "The test failed without a message.", "file": None, "line": None}]
+        target["cases"].append({
+            "id": str(node.get("nodeIdentifier") or "/".join(filter(None, [suites[-1] if suites else None, name]))),
+            "name": name, "classname": suites[-1] if suites else target["name"], "status": status,
+            "durationMs": round(_seconds(node) * 1000), "failures": failures, "attachments": [], **where})
+    out = []
+    for target in targets.values():
+        cases = sorted(target["cases"], key=lambda case: (case["status"] != "failed", case["classname"], case["name"]))
+        counts = {key: sum(case["status"] == key for case in cases) for key in ("passed", "failed", "skipped")}
+        out.append({"name": target["name"], "status": "failed" if counts["failed"] else "passed", "tests": len(cases),
+                    **counts, "durationMs": sum(case["durationMs"] for case in cases), "cases": cases})
+    return out
+
+
+def export_attachments(bundle, folder, targets, *, runner=None):
+    """Export the screenshots and files the tests attached into ``folder``/xctest/attachments/ and name them on their
+    cases (paths relative to ``folder``). Best effort: a test's verdict never depends on it."""
+    folder = Path(folder)
+    out_dir = folder / BUNDLE_DIR / ATTACHMENTS
+    (runner or run_command)(["xcrun", "xcresulttool", "export", "attachments", "--path", str(bundle),
+                                       "--output-path", str(out_dir)], folder, None, READ_TIMEOUT)
+    try:
+        manifest = json.loads((out_dir / "manifest.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return 0
+    wanted = {case["id"]: case for target in targets for case in target["cases"]}
+    count = 0
+    for entry in manifest if isinstance(manifest, list) else ():
+        case = wanted.get(str(entry.get("testIdentifier") or ""))
+        for item in entry.get("attachments") or ():
+            name = str(item.get("exportedFileName") or "")
+            if case is None or not name or not (out_dir / name).is_file() or Path(name).name != name:
+                continue
+            label = EXPORT_SUFFIX.sub("", str(item.get("suggestedHumanReadableName") or name))[:120]
+            case["attachments"].append({"name": label, "path": f"{BUNDLE_DIR}/{ATTACHMENTS}/{name}"})
+            count += 1
+    return count
+
+
+def section(targets, *, scheme, test_plan, device, bundle=None, why=None):
+    """doc["xctest"]: the targets plus their totals, the device they ran on and why each target ran."""
+    totals = {key: sum(target[key] for target in targets) for key in ("tests", "passed", "failed", "skipped")}
+    status = "failed" if totals["failed"] else "passed"
+    return {"status": status, "scheme": scheme, "testPlan": test_plan, "device": device["name"],
+            "deviceKey": device["key"], "resultBundle": bundle, "why": dict(why or {}), "summary": totals,
+            "durationMs": sum(target["durationMs"] for target in targets), "targets": targets}
+
+
+def milliseconds(ms):
+    """"38 ms", "1.2 s": a test's time."""
+    return f"{ms} ms" if ms < 1000 else f"{ms / 1000:.1f} s"
+
+
+def couldnt_run(error, *, scheme=None, test_plan=None, why=None):
+    return {"status": "couldnt_run", "scheme": scheme, "testPlan": test_plan, "reason": {
+        "message": error.message, "fix": error.fix}, "why": dict(why or {}), "summary": {
+            "tests": 0, "passed": 0, "failed": 0, "skipped": 0}, "durationMs": 0, "targets": []}
+
+
+def words(found):
+    """"XCTest 3 of 4 passed", "XCTest 1 failed of 4", "XCTest couldn't run"."""
+    totals = found.get("summary") or {}
+    if found.get("status") == "couldnt_run":
+        return "XCTest couldn't run"
+    if totals.get("failed"):
+        return f"XCTest {totals['failed']} failed of {totals['tests']}"
+    return f"XCTest {totals.get('passed', 0)} of {totals.get('tests', 0)} passed"
+
+
+def failed_cases(doc):
+    """(target name, case) for every failed XCTest case in a suite's results document."""
+    return [(target["name"], case) for target in (doc.get("xctest") or {}).get("targets") or ()
+            for case in target.get("cases") or () if case.get("status") == "failed"]
+
+
+def failure_line(case):
+    """"PlanTests.swift:14: XCTAssertEqual failed ..." for a failed case."""
+    first = (case.get("failures") or [{}])[0]
+    where = f"{first['file']}:{first['line']}: " if first.get("file") else ""
+    return (where + str(first.get("message") or "failed")).strip()
+
+
+# The worst outcome decides the exit code: failed, couldn't run, review, passed.
+EXIT_RANK = {1: 0, 3: 1, 2: 2, 0: 3}
+
+
+def merge_summary(doc):
+    """Fold the XCTest result into the suite's summary and exit code (130, a stopped run, stays)."""
+    found = doc.get("xctest")
+    if not found:
+        return doc
+    summary = doc.setdefault("summary", {})
+    summary["xctest"] = dict(found["summary"], status=found["status"])
+    own = {"failed": 1, "couldnt_run": 3}.get(found["status"], 0)
+    current = doc.get("exitCode")
+    if current in EXIT_RANK and EXIT_RANK[own] < EXIT_RANK[current]:
+        doc["exitCode"] = own
+    elif current is None:
+        doc["exitCode"] = own
+    return doc
+
+
+def run_suite(planned, attempts, folder, progress, *, runner=None):
+    """Build for testing (unless `test pr` did), run the targets on a simulator leased from ``attempts`` and return
+    doc["xctest"].
+
+    The simulator is the first simulator target of the run (the lease the checks just used is free again, so a booted
+    one is reused); a run of iPhones only has none, and says so."""
+    options = planned.options
+    labels = {"scheme": options.xctest_scheme, "test_plan": options.xctest_plan, "why": {}}
+    built = planned.xctest_build
+    if built is None:
+        try:
+            built = prepare(planned, progress, runner=runner)
+        except BuildError as error:
+            return couldnt_run(XctestError(error.message, error.fix), **labels)
+    chosen, why = select_targets(built.get("targets") or [], planned.changed, tuple(options.xctest_only))
+    labels = {"scheme": built.get("scheme"), "test_plan": options.xctest_plan, "why": why}
+    target = next((t for t in planned.targets if t.kind in ("default", "simulator") and t.record is None), None)
+    if target is None:
+        return couldnt_run(XctestError("--xctest runs on a simulator, and this run names only iPhones.",
+                                       "Add --sim, or run the XCTest targets in another run."), **labels)
+    if not chosen:
+        return couldnt_run(XctestError("None of the scheme's test targets matches --only-testing.",
+                                       f"The scheme's targets are {', '.join(built.get('targets') or []) or 'none'}."),
+                           **labels)
+    only = [item for item in options.xctest_only if item.split("/", 1)[0] in chosen]
+    if not only and set(chosen) != set(built.get("targets") or []):
+        only = list(chosen)   # the targets a changed file picked
+    try:
+        lease = attempts.simulators().acquire(target.device_type, target.runtime)
+    except SimError as error:
+        return couldnt_run(XctestError(f"No simulator was free for the tests: {error}",
+                                       error.fix or "Run `mobster sim doctor`."), **labels)
+    try:
+        sim = lease.target
+        device = {"name": sim.name, "key": f"sim:{sim.device_type}@{sim.runtime}"}
+        try:
+            bundle = run_tests(built["xctestrun"], sim.udid, folder, only, runner=runner, progress=progress)
+            tests, summary = read_bundle(bundle, runner=runner)
+        except XctestError as error:
+            return couldnt_run(error, **labels)
+        targets = parse(tests, summary, device)
+        if not targets:
+            return couldnt_run(XctestError("The scheme ran no tests.", "Check --only-testing and the scheme's Test "
+                                                                       "action."), **labels)
+        export_attachments(bundle, folder, targets, runner=runner)
+        return section(targets, scheme=built.get("scheme"), test_plan=options.xctest_plan, device=device,
+                       bundle=Path(bundle).relative_to(folder).as_posix(), why=why)
+    finally:
+        lease.release()
+
+
+def text_lines(doc, paint):
+    """One line per failed XCTest case, with its file and line, and the XCTest totals."""
+    found = doc.get("xctest")
+    if not found:
+        return []
+    lines = [f"{paint('✗ failed', 'failed')}  {target}: {case['classname']}.{case['name']}\n    "
+             f"{failure_line(case)}" for target, case in failed_cases(doc)]
+    totals = found["summary"]
+    if found["status"] == "couldnt_run":
+        reason = found.get("reason") or {}
+        lines.append(f"{paint('✗ couldn\'t run', 'couldnt_run')}  your XCTest targets\n    "
+                     f"{reason.get('message')} {reason.get('fix')}".rstrip())
+    else:
+        lines.append(f"XCTest: {totals['passed']} of {totals['tests']} passed"
+                     + (f", {totals['failed']} failed" if totals["failed"] else "")
+                     + (f", {totals['skipped']} skipped" if totals["skipped"] else "")
+                     + f" in {len(found['targets'])} target{'' if len(found['targets']) == 1 else 's'}")
+    return lines

mobile_agent/threads/__init__.py

@@ -0,0 +1 @@
+"""Track `conversations`."""

mobile_agent/threads/chat_once.py

@@ -0,0 +1,264 @@
+"""`mobster chat "message"` and `mobster chat --workflow`: the scripted path."""
+
+import json
+import shlex
+import time
+
+from ..narrate import approval_title, completion_message, status_label
+from .client import NoService, ServiceError
+from .recent import remember_thread
+
+EXIT_DONE, EXIT_NOT_DONE, EXIT_NEEDS_YOU, EXIT_COULDNT, EXIT_RUNNING = 0, 1, 2, 3, 4
+DONE = frozenset({"completed", "completed_unverified", "user_condition_met"})
+
+
+def outcome(run, thread_id):
+    summary = run.get("summary") or {}
+    data = summary.get("data")
+    out = {"threadId": thread_id, "runId": run.get("id"), "status": run.get("status"),
+           "outcome": summary.get("outcome"), "answer": summary.get("answer"),
+           "costUsd": run.get("costUsd"), "elapsedMs": summary.get("elapsed_ms")}
+    if data is not None:
+        out["data"] = data
+    if run.get("status") not in DONE and summary.get("reason"):
+        out["reason"] = summary["reason"]
+    return out
+
+
+def waiting(run, thread_id):
+    approval = run.get("approval") or {}
+    if approval.get("kind") == "clarify":
+        return {"threadId": thread_id, "runId": run.get("id"), "status": "waiting_for_answer",
+                "question": approval.get("question") or approval.get("label"),
+                "choices": [c.get("label") for c in approval.get("choices") or ()]}
+    out = {"threadId": thread_id, "runId": run.get("id"), "status": "waiting_for_approval",
+           "approval": {"title": approval_title(approval), "text": approval.get("text"), "app": approval.get("app")}}
+    return out
+
+
+def once(client, chat, text, *, as_json, wait, out, keep=False):
+    """`mobster chat "message"`."""
+    tty = chat.interactive
+    if tty:
+        response = chat.send(text)          # prints the task's first line and follows it
+        if response is None:
+            return EXIT_COULDNT
+    else:
+        body = {"text": text, **({"device": chat.device} if chat.device else {})}
+        try:
+            chat.thread_id, response = client.send(chat.thread_id, body)
+        except ServiceError as error:
+            if as_json:
+                print(json.dumps({"status": "refused", "error": str(error), "code": error.code}), file=out,
+                      flush=True)
+            else:
+                chat.say(str(error))
+            return EXIT_COULDNT
+        remember_thread(client.url, chat.thread_id)
+    routed = routed_as(response)
+    if routed == "remember":
+        return offered(chat, response, tty=tty, as_json=as_json, wait=wait, out=out)
+    run_id = (response.get("run") or {}).get("id") or (response.get("item") or {}).get("runId")
+    if routed in ("steer", "answer"):
+        if as_json:
+            print(json.dumps({"threadId": chat.thread_id, "runId": run_id, "routed": routed}), file=out, flush=True)
+        else:
+            chat.say("  Mobster has your message; the task goes on. Follow it with: mobster chat --thread "
+                     f"{chat.thread_id}", "faint")
+        return EXIT_DONE
+    if not tty:
+        # --json, or no terminal: never answers an approval; waits until the task ends or needs someone (with
+        # --keep-waiting, until it ends: someone answers in Mobster).
+        return finish(client.wait_run(run_id, wait, through=keep), chat.thread_id, as_json, out, chat)
+    return follow_here(chat, run_id, wait, out)
+
+
+def follow_here(chat, run_id, wait, out):
+    """On a terminal: the steps as they happen; an approval waits for a typed y, n or x. Returns the exit code."""
+    deadline = time.monotonic() + wait
+    term = chat.term
+    try:
+        while time.monotonic() < deadline:
+            chat.pump(0.1)
+            if bool(chat.pending) != term.prompting:
+                term.clear()
+                term.prompting = bool(chat.pending)
+                term.show()
+            done = chat.finished.get(run_id)
+            if done is not None:
+                return finish(done, chat.thread_id, False, out, chat, printed=True)
+            if chat.pending and chat.pending.get("kind") == "clarify":
+                chat.say(f"  Answer with: mobster chat --thread {chat.thread_id} \"your answer\"", "faint")
+                return EXIT_NEEDS_YOU
+            if chat.pending:
+                chat.feed(chat.term.keys(0.1) or "")
+    except KeyboardInterrupt:
+        chat.stop()
+        return 130
+    chat.say(f"  Still working. Follow it with: mobster chat --thread {chat.thread_id}", "faint")
+    return EXIT_RUNNING
+
+
+def routed_as(response):
+    """How Mobster took a message: new_run, steer, answer or remember."""
+    return response.get("routed") or (response.get("item") or {}).get("routed") or "new_run"
+
+
+def proposals_of(client, thread_id, response):
+    """The suggestions to remember a message made, [{id, text, pin}]. Where the answer leaves them out (that older
+    Mobster), the conversation's pending ones."""
+    if "proposals" in response:
+        return response.get("proposals") or []
+    from urllib.parse import quote
+    try:
+        listed = client.call("GET", f"/api/memory/proposals?thread={quote(str(thread_id), safe='')}")["proposals"]
+    except (ServiceError, NoService, KeyError, TypeError):
+        return []
+    return [{"id": p.get("id"), "text": p.get("text"), "scope": p.get("scope") or "global",
+             "pin": bool(p.get("pin"))} for p in listed
+            if isinstance(p, dict)]
+
+
+def where_to_remember(proposal):
+    scope = proposal.get("scope") or "global"
+    command = ["mobster", "memory", "add", str(proposal.get("text") or "")]
+    if scope != "global":
+        command.extend(("--scope", scope))
+    return "Answer it in Mobster for Mac, or save it with: " + shlex.join(command)
+
+
+def offered(chat, response, *, tty, as_json, wait, out):
+    """A message that only asked Mobster to remember something: no task started, so there's no run to follow."""
+    if not tty:
+        proposals = proposals_of(chat.client, chat.thread_id, response)
+        if as_json:
+            print(json.dumps({"threadId": chat.thread_id, "status": "remember", "proposals": proposals},
+                             ensure_ascii=False), file=out, flush=True)
+        else:
+            chat.offer(proposals)
+        return EXIT_DONE
+    # chat.send showed the first suggestion already.
+    term, deadline = chat.term, time.monotonic() + wait
+    try:
+        while chat.offers and not chat.quit and time.monotonic() < deadline:
+            if not term.prompting:
+                term.prompting = True
+                term.show()
+            data = term.keys(0.1)
+            if data is None:
+                break
+            chat.feed(data)
+    except KeyboardInterrupt:
+        return 130
+    for proposal in chat.offers:
+        chat.say("  " + where_to_remember(proposal), "faint")
+    chat.offers = []
+    return EXIT_DONE
+
+
+def finish(run, thread_id, as_json, out, chat, printed=False):
+    if run.get("finishedAt") is None:
+        if run.get("approval"):
+            state = waiting(run, thread_id)
+            if as_json:
+                print(json.dumps(state, ensure_ascii=False), file=out, flush=True)
+            else:
+                if state["status"] == "waiting_for_answer":
+                    chat.note(chat.paint(str(state["question"]), "bold"), glyph="?", role="accent", indent="")
+                    chat.say(f"  Answer with: mobster chat --thread {thread_id} \"your answer\"", "faint")
+                else:
+                    chat.show_approval(run["approval"])
+                    chat.note("Waiting for your approval in Mobster (or in `mobster chat` on a terminal).")
+            return EXIT_NEEDS_YOU
+        if as_json:
+            print(json.dumps({"threadId": thread_id, "runId": run.get("id"), "status": "running"}), file=out,
+                  flush=True)
+        else:
+            chat.say(f"Still working. Follow it with: mobster chat --thread {thread_id}", "faint")
+        return EXIT_RUNNING
+    result = outcome(run, thread_id)
+    if as_json:
+        print(json.dumps(result, ensure_ascii=False, allow_nan=False), file=out, flush=True)
+    elif not printed:
+        chat.say(status_label(result["status"]), "bold")
+        message = result.get("data") if isinstance(result.get("data"), str) else result.get("answer")
+        if message:
+            chat.say(str(message))
+        elif result.get("reason"):
+            chat.say(completion_message(result["status"], result["reason"], summary=result))
+    return EXIT_DONE if result["status"] in DONE else EXIT_NOT_DONE
+
+
+def blank_values(pairs):
+    """{"topic": "basketball"} from ["topic=basketball", ...]. ValueError for a pair without "="."""
+    values = {}
+    for pair in pairs or ():
+        name, sep, value = pair.partition("=")
+        if not sep or not name.strip():
+            raise ValueError(f"Give each blank as NAME=VALUE, like --set topic=basketball (not {pair!r})")
+        values[name.strip()] = value.strip()
+    return values
+
+
+def follow_graph(client, workflow, batch, thread_id, *, as_json, wait, out):
+    """A workflow run as a graph: each step's state as it changes, then how the run ended (with --json, one object
+    with every step). 0 when it completed, 1 when it didn't, 4 while it still runs."""
+    def changed(node):
+        if as_json or str(node.get("type", "")).startswith("trigger."):
+            return
+        line = f"{node.get('instance')}: {node.get('state')}"
+        if node.get("reason") and node.get("state") in ("failed", "blocked", "skipped", "unknown", "cancelled"):
+            line += f" ({node['reason']})"
+        out.write(line + "\n")
+    ended = client.wait_batch(workflow["id"], batch["id"], wait, on_node=changed) or batch
+    status = ended.get("status")
+    if as_json:
+        nodes = {key: {k: node[k] for k in ("state", "reason", "output", "runId") if k in node}
+                 for key, node in (ended.get("nodes") or {}).items()}
+        out.write(json.dumps({"workflow": workflow["id"], "threadId": thread_id, "batch": ended.get("id"),
+                              "status": status, "reason": ended.get("reason"), "result": ended.get("result"),
+                              "nodes": nodes}) + "\n")
+    else:
+        out.write(f"“{workflow['name']}” {str(status).replace('_', ' ')}." +
+                  (f" {ended['reason']}" if ended.get("reason") else "") + "\n")
+    return 0 if status == "completed" else 4 if status == "running" else 1
+
+
+def workflow_once(client, chat, args, *, as_json, wait, out, fail):
+    """`mobster chat --workflow NAME [--set BLANK=VALUE]...`: start it, then follow it as one message."""
+    try:
+        values = blank_values(args.set)
+        workflow = client.find_workflow(args.workflow)
+    except ValueError as error:
+        return fail(str(error), "usage")
+    except LookupError as error:
+        return fail(str(error), "not_found")
+    try:
+        thread_id, answer = client.run_workflow(workflow["id"], values=values, thread_id=chat.thread_id,
+                                                new_conversation=bool(args.new))
+    except ServiceError as error:
+        return fail(str(error), error.code or "refused")
+    run = answer.get("run") or {}
+    chat.thread_id = thread_id
+    if thread_id:
+        remember_thread(client.url, thread_id)
+    batch = answer.get("batch") or {}
+    if batch.get("graph") == 2 and not chat.interactive:
+        return follow_graph(client, workflow, batch, thread_id, as_json=as_json, wait=wait, out=out)
+    if not run.get("id"):
+        # A workflow of steps that waits before its first task: nothing to follow yet. Its conversation has each step.
+        batch = answer.get("batch") or {}
+        if as_json:
+            out.write(json.dumps({"workflow": workflow["id"], "threadId": thread_id, "batch": batch.get("id"),
+                                  "status": batch.get("status")}) + "\n")
+        else:
+            out.write(f"Started “{workflow['name']}”. It waits before its first task; its conversation shows each "
+                      "step.\n")
+        return 0
+    if not chat.interactive:
+        keep = bool(getattr(args, "keep_waiting", False))
+        return finish(client.wait_run(run["id"], wait, through=keep), thread_id, as_json, out, chat)
+    where = run.get("deviceName")
+    chat.renderer(run["id"]).start(run.get("goal") or workflow["name"], f"on {where}" if where else "")
+    chat.follow(run["id"])
+    return follow_here(chat, run["id"], wait, out)